From c82518aa0ddd0c10146fbfe7a51053701a51d646 Mon Sep 17 00:00:00 2001 From: gewuyou <95328647+GeWuYou@users.noreply.github.com> Date: Sun, 19 Apr 2026 10:46:27 +0800 Subject: [PATCH] =?UTF-8?q?docs(ai-plan):=20=E6=94=B6=E5=8F=A3=E5=85=AC?= =?UTF-8?q?=E5=85=B1=E8=AE=A1=E5=88=92=E4=B8=BB=E9=A2=98=E7=B4=A2=E5=BC=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 重构 ai-plan public 结构为按主题分组并引入归档层级 - 新增 public README worktree 映射并同步 boot 启动入口 - 更新治理 tracking trace 与仓库文档中的 ai-plan 路径约定 --- .codex/skills/gframework-boot/SKILL.md | 37 ++++++++---- .../references/startup-artifacts.md | 12 ++-- .gitignore | 7 +-- AGENTS.md | 28 ++++++--- README.md | 2 +- ai-plan/README.md | 47 +++++++++++---- ai-plan/public/README.md | 35 +++++++++++ .../todos/ai-plan-governance-tracking.md | 60 +++++++++++++++++++ .../traces/ai-plan-governance-trace.md | 58 ++++++++++++++++++ .../cqrs-cache-docs-hardening-tracking.md | 2 +- .../traces/cqrs-cache-docs-hardening-trace.md | 0 .../todos/cqrs-rewrite-migration-tracking.md | 10 ++-- .../traces/cqrs-rewrite-migration-trace.md | 4 +- .../todos/ai-plan-governance-tracking.md | 50 ---------------- .../public/traces/ai-plan-governance-trace.md | 31 ---------- 15 files changed, 253 insertions(+), 130 deletions(-) create mode 100644 ai-plan/public/README.md create mode 100644 ai-plan/public/ai-plan-governance/todos/ai-plan-governance-tracking.md create mode 100644 ai-plan/public/ai-plan-governance/traces/ai-plan-governance-trace.md rename ai-plan/public/{ => archive/cqrs-cache-docs-hardening}/todos/cqrs-cache-docs-hardening-tracking.md (98%) rename ai-plan/public/{ => archive/cqrs-cache-docs-hardening}/traces/cqrs-cache-docs-hardening-trace.md (100%) rename ai-plan/public/{ => cqrs-rewrite}/todos/cqrs-rewrite-migration-tracking.md (99%) rename ai-plan/public/{ => cqrs-rewrite}/traces/cqrs-rewrite-migration-trace.md (99%) delete mode 100644 ai-plan/public/todos/ai-plan-governance-tracking.md delete mode 100644 ai-plan/public/traces/ai-plan-governance-trace.md diff --git a/.codex/skills/gframework-boot/SKILL.md b/.codex/skills/gframework-boot/SKILL.md index 38841396..a1c5eea5 100644 --- a/.codex/skills/gframework-boot/SKILL.md +++ b/.codex/skills/gframework-boot/SKILL.md @@ -14,42 +14,55 @@ Treat `AGENTS.md` as the source of truth. Use this skill to enforce a startup se 1. Read `AGENTS.md` before choosing tools, planning edits, or delegating work. 2. Read `.ai/environment/tools.ai.yaml` to confirm the preferred local toolchain. -3. Inspect `ai-plan/public/todos/` and `ai-plan/public/traces/` before asking the user for missing context. -4. If `ai-plan/private//` exists and is relevant, treat it as private recovery context for the current worktree only and do not assume it should be committed. -5. Classify the task state: +3. Read `ai-plan/public/README.md` before asking the user for missing context. +4. If `ai-plan/public/README.md` maps the current branch or worktree to active topics, inspect those topics' + `todos/` and `traces/` directories in listed priority order. +5. If no mapping exists, scan `ai-plan/public//todos/` and `ai-plan/public//traces/` across active + topics, and ignore `ai-plan/public/archive/` unless the user explicitly asks for historical context. +6. If `ai-plan/private//` exists and is relevant, treat it as private recovery context for the + current worktree only and do not assume it should be committed. +7. Classify the task state: - `new`: no matching recovery document exists, or the user is clearly starting fresh work - `resume`: a matching todo or trace exists and the user is continuing that thread - `recovery`: prior work looks partial, interrupted, or ambiguous and the next safe recovery point must be reconstructed -6. Choose the best matching `ai-plan` artifacts: +8. Choose the best matching `ai-plan` artifacts: + - Prefer topics explicitly mapped from `ai-plan/public/README.md` - Prefer path names or headings that match the user's task wording - Break ties by most recently updated trace or todo - If ambiguity would materially change implementation, summarize the candidates and ask one concise question -7. Classify the task complexity before deciding on subagents: +9. Classify the task complexity before deciding on subagents: - `simple`: one concern, one file or module, no parallel discovery required - `medium`: a small number of modules, some read-only exploration helpful, critical path still easy to keep local - `complex`: cross-module design, migration, large refactor, or work likely to exceed one context window -8. Apply the delegation policy from `AGENTS.md`: +10. Apply the delegation policy from `AGENTS.md`: - Keep the critical path local - Use `explorer` with `gpt-5.1-codex-mini` for narrow read-only questions, tracing, inventory, and comparisons - Use `worker` with `gpt-5.4` only for bounded implementation tasks with explicit ownership - Do not delegate purely for ceremony; delegate only when it materially shortens the task or controls context growth -9. Before editing files, tell the user what you read, how you classified the task, whether subagents will be used, and the first implementation step. -10. Proceed with execution, validation, and documentation updates required by `AGENTS.md`. +11. Before editing files, tell the user what you read, how you classified the task, whether subagents will be used, + and the first implementation step. +12. Proceed with execution, validation, and documentation updates required by `AGENTS.md`. ## Task Tracking For multi-step, cross-module, or interruption-prone work, maintain the repository recovery artifacts instead of keeping state only in chat. -- Update the active public document under `ai-plan/public/todos/` with completed work, validation results, risks, and the next recovery point. -- Update the matching public trace under `ai-plan/public/traces/` with key decisions, delegated scope, and the immediate next step. +- Update `ai-plan/public/README.md` whenever the active topic set or worktree mapping changes. +- Update the active public document under `ai-plan/public//todos/` with completed work, validation results, + risks, and the next recovery point. +- Update the matching public trace under `ai-plan/public//traces/` with key decisions, delegated scope, and the + immediate next step. +- Move stage-complete artifacts into `ai-plan/public//archive/`, and move completed topics into + `ai-plan/public/archive//` so `boot` does not keep reloading stale context. - Keep worktree-private scratch recovery files under `ai-plan/private/` and do not treat them as commit targets. - Never write secrets, machine-specific paths, or other sensitive environment details into any `ai-plan/**` artifact. - If the task is clearly complex and no recovery artifact exists yet, create one before substantive edits. ## Recovery Heuristics -- If the user says `next step`, `continue`, `继续`, or similar resume language, search the relevant `ai-plan/` artifacts first, then classify the task as `resume` or `recovery` based on artifact clarity and continuity. -- If the current branch and the newest recovery documents describe the same feature area, prefer resuming that thread. +- If the user says `next step`, `continue`, `继续`, or similar resume language, read `ai-plan/public/README.md` + first, then search the mapped active topics before scanning the broader public area. +- If the current branch and the mapped active topics describe the same feature area, prefer resuming those topics first. - If the repository state suggests in-flight work but no recovery document matches, reconstruct the safest next step from code, tests, and Git state before asking the user for clarification. ## Example Triggers diff --git a/.codex/skills/gframework-boot/references/startup-artifacts.md b/.codex/skills/gframework-boot/references/startup-artifacts.md index 8e1ada8c..2ffb67d8 100644 --- a/.codex/skills/gframework-boot/references/startup-artifacts.md +++ b/.codex/skills/gframework-boot/references/startup-artifacts.md @@ -4,14 +4,18 @@ - `AGENTS.md` - `.ai/environment/tools.ai.yaml` -- `ai-plan/public/todos/` -- `ai-plan/public/traces/` +- `ai-plan/public/README.md` +- the selected `ai-plan/public//todos/` directories +- the selected `ai-plan/public//traces/` directories ## AI-Plan Selection Heuristics -- Match the user's wording against public todo and trace file names first. +- Match the current branch or worktree against `ai-plan/public/README.md` first. +- If the index maps the current worktree to topics, inspect those topics in listed order before scanning anything else. +- Match the user's wording against public todo and trace file names next. - Prefer the newest matching trace when several candidates describe the same feature area. - If one file records a clearer recovery point than a newer but vague file, prefer the clearer recovery point. +- Ignore `ai-plan/public/archive/**` unless the user explicitly requests historical recovery context. - If a matching `ai-plan/private//` directory exists, use it only as private context for the current worktree. ## Complexity Defaults @@ -29,4 +33,4 @@ Use a short update before execution: -`Read AGENTS.md, the environment inventory, and the relevant public ai-plan artifacts. This looks like a task. I will and start with .` +`Read AGENTS.md, the environment inventory, ai-plan/public/README.md, and the relevant public ai-plan artifacts. This looks like a task. I will and start with .` diff --git a/.gitignore b/.gitignore index 99da1101..5f35f8bd 100644 --- a/.gitignore +++ b/.gitignore @@ -18,10 +18,9 @@ ai-plan/* !ai-plan/README.md !ai-plan/public/ ai-plan/public/* -!ai-plan/public/todos/ -!ai-plan/public/traces/ -!ai-plan/public/todos/*.md -!ai-plan/public/traces/*.md +!ai-plan/public/README.md +!ai-plan/public/**/ +!ai-plan/public/**/*.md ai-plan/private/ ai-libs/ # tool diff --git a/AGENTS.md b/AGENTS.md index 44e79200..058e2d2a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -44,8 +44,8 @@ All AI agents and contributors must follow these rules when writing, reviewing, `按 boot 开始`、`先看 AGENTS`、`继续当前任务`. - The boot skill is a startup convenience layer, not a replacement for this document. If the skill and `AGENTS.md` diverge, follow `AGENTS.md` first and update the skill in the same change. -- The boot skill MUST read `AGENTS.md`、`.ai/environment/tools.ai.yaml` and the relevant `ai-plan/` artifacts before - substantive execution. +- The boot skill MUST read `AGENTS.md`、`.ai/environment/tools.ai.yaml`、`ai-plan/public/README.md` and the relevant + active-topic `ai-plan/` artifacts before substantive execution. ## Subagent Usage Rules @@ -330,8 +330,12 @@ bash scripts/validate-csharp-naming.sh ### Task Tracking - `ai-plan/` is split by intent: - - `ai-plan/public/todos/`: repository-safe recovery documents that may be committed and shared across worktrees - - `ai-plan/public/traces/`: repository-safe execution traces that may be committed and shared across worktrees + - `ai-plan/public/README.md`: the shared startup index that binds worktrees or branches to active topics and resume + entry points + - `ai-plan/public//todos/`: repository-safe recovery documents for an active topic + - `ai-plan/public//traces/`: repository-safe execution traces for an active topic + - `ai-plan/public//archive/`: archived stage-level artifacts that still belong to an active topic + - `ai-plan/public/archive//`: completed-topic archives that should not be treated as default boot context - `ai-plan/private/`: worktree-private recovery artifacts; keep these untracked and scoped to the current worktree - Contributors MUST keep committed `ai-plan/public/**` content safe to publish in Git history. - Never write secrets, tokens, credentials, private keys, machine usernames, home-directory paths, hostnames, IP @@ -340,17 +344,25 @@ bash scripts/validate-csharp-naming.sh stable document identifiers instead. - Use `ai-plan/public/**` only for durable, handoff-safe task state. Put temporary notes, local experiments, or worktree-specific scratch recovery data under `ai-plan/private/`. +- `ai-plan/public/README.md` MUST list only active topics. Do not add `ai-plan/public/archive/**` content to the + default boot index. +- When a worktree-to-topic mapping changes, or when a topic becomes active/inactive, contributors MUST update + `ai-plan/public/README.md` in the same change. - When working from a tracked implementation plan, contributors MUST update the corresponding tracking document under - `ai-plan/public/todos/` in the same change. + `ai-plan/public//todos/` in the same change. - Tracking updates MUST reflect completed work, newly discovered issues, validation results, and the next recommended recovery point. - Completing code changes without updating the active tracking document is considered incomplete work. - For any multi-step refactor, migration, or cross-module task, contributors MUST create or adopt a dedicated recovery - document under `ai-plan/public/todos/` before making substantive code changes. + document under `ai-plan/public//todos/` before making substantive code changes. - Recovery documents MUST record the current phase, the active recovery point identifier, known risks, and the next recommended resume step so another contributor or subagent can continue the work safely. -- Contributors MUST maintain a matching execution trace under `ai-plan/public/traces/` for complex work. The trace - should record the current date, key decisions, validation milestones, and the immediate next step. +- Contributors MUST maintain a matching execution trace under `ai-plan/public//traces/` for complex work. The + trace should record the current date, key decisions, validation milestones, and the immediate next step. +- When a stage inside an active topic is fully complete, move the finished artifacts into that topic's `archive/` + directory instead of leaving every completed step in the default boot path. +- When a topic is fully complete, move the entire topic directory under `ai-plan/public/archive//` and remove it + from `ai-plan/public/README.md` in the same change. - When a task spans multiple commits or is likely to exceed a single agent context window, update both the recovery document and the trace at each meaningful milestone before pausing or handing work off. - If subagents are used on a complex task, the main agent MUST capture the delegated scope and any accepted findings in diff --git a/README.md b/README.md index 71e00a03..2c4f8634 100644 --- a/README.md +++ b/README.md @@ -133,7 +133,7 @@ GFramework.sln 1. 先阅读对应模块目录下的 `README.md` 2. 如果改动影响采用路径、安装方式、公共 API 或目录结构，同时更新 `docs/zh-CN/` -3. 对跨模块或多阶段任务，维护 `ai-plan/public/todos/` 与 `ai-plan/public/traces/` +3. 对跨模块或多阶段任务，维护 `ai-plan/public/README.md` 与对应主题目录下的 tracking / trace ## 许可证 diff --git a/ai-plan/README.md b/ai-plan/README.md index 0731310c..5fcab16b 100644 --- a/ai-plan/README.md +++ b/ai-plan/README.md @@ -1,33 +1,56 @@ # AI Plan -`ai-plan/` stores AI task recovery artifacts for this repository, but not every file under it has the same sharing rules. +`ai-plan/` stores AI task recovery artifacts for this repository, but each subdirectory serves a different sharing and +bootstrapping purpose. ## Directory Semantics -- `public/todos/` - - Repository-safe recovery documents. +- `public/README.md` + - Shared startup index for `boot`. + - Maps worktrees or branches to active topics and points at the primary tracking/trace entry paths. + - Must list only active topics. +- `public//todos/` + - Repository-safe recovery documents for one active topic. - Use these for durable task state that another contributor or worktree may need to resume safely. - - These files may be committed. -- `public/traces/` - - Repository-safe execution traces that record decisions, validation milestones, and the immediate next step. - - These files may be committed. +- `public//traces/` + - Repository-safe execution traces for one active topic. + - Record decisions, validation milestones, and the immediate next step. +- `public//archive/` + - Stage-level archive for completed artifacts that still belong to an active topic. + - Use this when a topic remains active, but some prior phase no longer belongs in the default boot path. +- `public/archive//` + - Completed-topic archive. + - Move the entire topic directory here when that work direction is fully complete. - `private/` - Worktree-private recovery space. - Use this for temporary notes, local scratch recovery points, or state that only matters in the current worktree. - Keep this directory untracked. +## Workflow Rules + +- `boot` must read `public/README.md` first, then the mapped active topic directories, and only then fall back to + scanning active topics directly. +- If no mapping exists for the current worktree or branch, scan `public//` and ignore `public/archive/` unless + the user explicitly asks for historical context. +- When a worktree changes its active topic set, update `public/README.md` in the same change. +- When a stage is complete, move the finished artifacts into `public//archive/`. +- When a topic is complete, move the whole topic directory into `public/archive//` and remove it from the + shared startup index. + ## Content Rules -- Never write secrets, tokens, credentials, private keys, hostnames, IP addresses, proprietary URLs, or other sensitive data. +- Never write secrets, tokens, credentials, private keys, hostnames, IP addresses, proprietary URLs, or other + sensitive data. - Never write absolute file-system paths, home-directory paths, or machine usernames. -- Use repository-relative paths, branch names, PR numbers, recovery-point IDs, and stable document identifiers instead. +- Use repository-relative paths, branch names, PR numbers, recovery-point IDs, and stable document identifiers + instead. - Keep committed `public/**` content concise, handoff-safe, and understandable without machine-local context. ## Naming -- Shared recovery documents should describe the task, for example: - - `public/todos/cqrs-rewrite-migration-tracking.md` - - `public/traces/cqrs-rewrite-migration-trace.md` +- Topic directories should be named by capability or work direction, for example: + - `public/ai-plan-governance/` + - `public/cqrs-rewrite/` - Worktree-private files should live under a folder named for the current branch or worktree, for example: - `private/feat-cqrs-optimization/` - `private/gframework-cqrs/` diff --git a/ai-plan/public/README.md b/ai-plan/public/README.md new file mode 100644 index 00000000..a56d8aa9 --- /dev/null +++ b/ai-plan/public/README.md @@ -0,0 +1,35 @@ +# AI-Plan Public Index + +`ai-plan/public/README.md` is the shared startup index for `boot`. It should stay short, list only active topics, and +help the current worktree land on the right recovery documents without scanning every public artifact. + +## Boot Rules + +1. Read this file before scanning `ai-plan/public//`. +2. If the current branch or worktree appears in the map below, read the listed topics in priority order. +3. If there is no match, fall back to scanning active topic directories. +4. Ignore `ai-plan/public/archive/**` by default unless the user explicitly asks for historical context. + +## Active Topics + +- `ai-plan-governance` + - Purpose: govern the `ai-plan/` directory model, startup index, and archive policy. + - Tracking: `ai-plan/public/ai-plan-governance/todos/ai-plan-governance-tracking.md` + - Trace: `ai-plan/public/ai-plan-governance/traces/ai-plan-governance-trace.md` +- `cqrs-rewrite` + - Purpose: continue the CQRS migration, registry hardening, and related PR follow-up. + - Tracking: `ai-plan/public/cqrs-rewrite/todos/cqrs-rewrite-migration-tracking.md` + - Trace: `ai-plan/public/cqrs-rewrite/traces/cqrs-rewrite-migration-trace.md` + +## Worktree To Active Topic Map + +- Branch: `feat/cqrs-optimization` + - Worktree hint: `GFramework-cqrs` + - Priority 1: `ai-plan-governance` + - Priority 2: `cqrs-rewrite` + +## Archived Topics + +- `cqrs-cache-docs-hardening` + - Archive root: `ai-plan/public/archive/cqrs-cache-docs-hardening/` + - Note: archived topics stay outside the default `boot` context until a user explicitly requests historical review. diff --git a/ai-plan/public/ai-plan-governance/todos/ai-plan-governance-tracking.md b/ai-plan/public/ai-plan-governance/todos/ai-plan-governance-tracking.md new file mode 100644 index 00000000..c78865fd --- /dev/null +++ b/ai-plan/public/ai-plan-governance/todos/ai-plan-governance-tracking.md @@ -0,0 +1,60 @@ +# AI-Plan 治理跟踪 + +## 目标 + +继续收口 `ai-plan/` 的目录语义、启动入口与归档策略，避免多 worktree 并行时的公共恢复文档持续膨胀并拖慢 +`boot` 的上下文定位。 + +- 为 `ai-plan/` 建立明确的目录分层 +- 区分“可提交共享状态”与“工作树私有状态” +- 明确禁止写入敏感数据、绝对路径和机器本地信息 +- 让 `AGENTS.md`、`ai-plan/README.md` 与 boot skill 使用同一套目录语义 +- 让 `boot` 能通过公共索引快速定位当前 worktree 的活跃主题 +- 为阶段完成和主题完成两类归档建立稳定规则 + +## 当前恢复点 + +- 恢复点编号：`AI-PLAN-GOV-RP-003` +- 当前阶段：`Phase 2` +- 当前焦点： + - 已将共享恢复文档按主题迁移到 `ai-plan/public//todos/` 与 `ai-plan/public//traces/` + - 已为 `boot` 新增 `ai-plan/public/README.md` 公共索引，并绑定当前 worktree 的活跃主题顺序 + - 已将完成度更高的 `cqrs-cache-docs-hardening` 移入 `ai-plan/public/archive/` + - 已同步更新 `.gitignore`、`AGENTS.md`、`ai-plan/README.md`、根 `README.md` 与 `gframework-boot` + - 已明确主题内归档与主题级归档的双层规则，避免活动区无限增长 + +## 已完成 + +- `.gitignore` 现允许 `ai-plan/public/**/*.md` 以主题目录与归档目录形式进入版本控制 +- `AGENTS.md` 已补充： + - `public/README.md`、活动主题目录、主题内归档与主题级归档的职责划分 + - `boot` 默认忽略 `ai-plan/public/archive/**` + - worktree 与活跃主题映射变化时，必须同步更新公共索引 +- `.codex/skills/gframework-boot/SKILL.md` 与其 `references/startup-artifacts.md` 已切换到： + - 优先读取 `ai-plan/public/README.md` + - 命中映射后优先读取对应主题目录 + - 未命中映射时再扫描活动主题目录，并排除公共归档区 +- `ai-plan/README.md` 已补充主题命名、归档触发条件与 `boot` 读取顺序 +- 根 `README.md` 已改为要求维护公共索引与对应主题目录 +- 现有共享文档已迁移为： + - `ai-plan/public/ai-plan-governance/**` + - `ai-plan/public/cqrs-rewrite/**` + - `ai-plan/public/archive/cqrs-cache-docs-hardening/**` + +## 验证 + +- `find ai-plan/public -maxdepth 4 -type f | sort` + - 结果：通过 + - 备注：活动主题、公共索引与归档主题已按新目录语义落位 +- `rg -n "ai-plan/public/README.md|ai-plan/public/|ai-plan/public/archive|ai-plan/private/" AGENTS.md .codex/skills/gframework-boot/SKILL.md .codex/skills/gframework-boot/references/startup-artifacts.md ai-plan/README.md README.md .gitignore` + - 结果：通过 + - 备注：新目录语义、索引入口与归档规则已统一到仓库规则与 boot skill +- `dotnet build GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj -c Release --no-restore` + - 结果：通过 + - 备注：本轮规则与文档调整未引入构建问题 + +## 下一步 + +1. 后续新增活动主题时，先在 `ai-plan/public/README.md` 登记 worktree 到主题映射，再创建对应主题目录 +2. 阶段完成后优先收入主题内 `archive/`；主题整体完成后，再整目录移入 `ai-plan/public/archive/` +3. 若未来再新增 skill 或仓库规则引用 `ai-plan/`，统一按“公共索引 + 活动主题 + 归档主题 + 私有目录”扩展，不再恢复平铺结构 diff --git a/ai-plan/public/ai-plan-governance/traces/ai-plan-governance-trace.md b/ai-plan/public/ai-plan-governance/traces/ai-plan-governance-trace.md new file mode 100644 index 00000000..7f9be231 --- /dev/null +++ b/ai-plan/public/ai-plan-governance/traces/ai-plan-governance-trace.md @@ -0,0 +1,58 @@ +# AI-Plan 治理追踪 + +## 2026-04-19 + +### 阶段：目录语义收口（RP-002） + +- 建立 `AI-PLAN-GOV-RP-002` 恢复点 +- 用户指出当前 `ai-plan/` 存在三个治理问题： + - 缺少更细的目录分层，容易随着 worktree 增长持续膨胀 + - 缺少“不得写入敏感数据、真实路径、机器信息”的明确约束 + - 目录语义没有区分共享恢复信息与 worktree 私有状态 +- 已据此完成以下收口： + - 将既有共享 tracking / trace 文件迁移到扁平的 `ai-plan/public/` 共享目录 + - 新增 `ai-plan/private/` 作为工作树私有恢复空间，并通过 `.gitignore` 保持未跟踪 + - 新增 `ai-plan/README.md` 作为目录语义与内容规范的单点说明 + - 在 `AGENTS.md` 中补齐 public/private 职责边界，以及敏感信息与绝对路径禁写规则 + - 在 `gframework-boot` 中同步新的读取顺序：优先 public，按需读取当前 worktree 私有目录 + +### 验证 + +- `find ai-plan -maxdepth 3 -type f | sort` + - 结果：通过 +- `rg -n "ai-plan/public/|ai-plan/private/" AGENTS.md .codex/skills/gframework-boot/SKILL.md .codex/skills/gframework-boot/references/startup-artifacts.md ai-plan/README.md .gitignore` + - 结果：通过 +- `dotnet build GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj -c Release` + - 结果：通过 + +### 下一步 + +1. 后续若出现新的 worktree 私有恢复需求，直接在 `ai-plan/private//` 下创建，不再向共享目录追加本地临时状态 +2. 若将来需要进一步限制格式，可再为 `public/**` 与 `private/` 各自补一个模板文件，但本轮先把目录语义和安全边界固定下来 + +### 阶段：主题分组与启动索引（RP-003） + +- 建立 `AI-PLAN-GOV-RP-003` 恢复点 +- 用户进一步指出：即使 public/private 已分层，只要多 worktree 并行，扁平的活动主题集合仍会让 `boot` 随着 + `ai-plan/public` 增长而退化成大范围扫描 +- 已据此完成第二轮治理： + - 将活动共享文档迁移到 `ai-plan/public//todos/` 与 `ai-plan/public//traces/` + - 新增 `ai-plan/public/README.md` 作为公共启动索引，维护 worktree 到多个活跃主题的映射与优先顺序 + - 将已完成的 `cqrs-cache-docs-hardening` 整体移入 `ai-plan/public/archive/cqrs-cache-docs-hardening/` + - 在 `AGENTS.md`、`ai-plan/README.md`、根 `README.md` 与 `gframework-boot` 中统一“公共索引 + 活动主题 + + 主题内归档 + 主题级归档”的语义 + - 将 `.gitignore` 调整为允许 `ai-plan/public/**/*.md` 以新层级进入版本控制 + +### 验证 + +- `find ai-plan/public -maxdepth 4 -type f | sort` + - 结果：通过 +- `rg -n "ai-plan/public/README.md|ai-plan/public/|ai-plan/public/archive|ai-plan/private/" AGENTS.md .codex/skills/gframework-boot/SKILL.md .codex/skills/gframework-boot/references/startup-artifacts.md ai-plan/README.md README.md .gitignore` + - 结果：通过 +- `dotnet build GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj -c Release --no-restore` + - 结果：通过 + +### 下一步 + +1. 未来每次新增或关闭主题，都同步更新 `ai-plan/public/README.md`，不要让 `boot` 回到全量扫描模式 +2. 若某个活跃主题内部继续积累阶段性完成物，优先收入该主题目录下的 `archive/` diff --git a/ai-plan/public/todos/cqrs-cache-docs-hardening-tracking.md b/ai-plan/public/archive/cqrs-cache-docs-hardening/todos/cqrs-cache-docs-hardening-tracking.md similarity index 98% rename from ai-plan/public/todos/cqrs-cache-docs-hardening-tracking.md rename to ai-plan/public/archive/cqrs-cache-docs-hardening/todos/cqrs-cache-docs-hardening-tracking.md index 93b67225..85c9b8a9 100644 --- a/ai-plan/public/todos/cqrs-cache-docs-hardening-tracking.md +++ b/ai-plan/public/archive/cqrs-cache-docs-hardening/todos/cqrs-cache-docs-hardening-tracking.md @@ -16,7 +16,7 @@ collectible assemblies. ## Planned Work -- [x] Create the matching execution trace under `ai-plan/public/traces/`. +- [x] Create the matching execution trace under `ai-plan/public/archive/cqrs-cache-docs-hardening/traces/`. - [x] Update `README.md` quick-install guidance to include CQRS runtime packages. - [x] Update the related Chinese setup/integration docs with CQRS runtime + source-generator wiring and a minimal working CQRS generator example. diff --git a/ai-plan/public/traces/cqrs-cache-docs-hardening-trace.md b/ai-plan/public/archive/cqrs-cache-docs-hardening/traces/cqrs-cache-docs-hardening-trace.md similarity index 100% rename from ai-plan/public/traces/cqrs-cache-docs-hardening-trace.md rename to ai-plan/public/archive/cqrs-cache-docs-hardening/traces/cqrs-cache-docs-hardening-trace.md diff --git a/ai-plan/public/todos/cqrs-rewrite-migration-tracking.md b/ai-plan/public/cqrs-rewrite/todos/cqrs-rewrite-migration-tracking.md similarity index 99% rename from ai-plan/public/todos/cqrs-rewrite-migration-tracking.md rename to ai-plan/public/cqrs-rewrite/todos/cqrs-rewrite-migration-tracking.md index 6c52969a..c89803d3 100644 --- a/ai-plan/public/todos/cqrs-rewrite-migration-tracking.md +++ b/ai-plan/public/cqrs-rewrite/todos/cqrs-rewrite-migration-tracking.md @@ -58,8 +58,8 @@ ### Phase 0：工作流基础 -- [x] 在 `ai-plan/public/todos/` 建立本任务跟踪文档 -- [x] 在 `ai-plan/public/traces/` 建立本任务追踪文档 +- [x] 在 `ai-plan/public/cqrs-rewrite/todos/` 建立本任务跟踪文档 +- [x] 在 `ai-plan/public/cqrs-rewrite/traces/` 建立本任务追踪文档 - [x] 将恢复点 / trace / subagent 协作规范写入 `AGENTS.md` ### Phase 1：本地验证链路 @@ -468,7 +468,7 @@ 若本轮中断，优先从以下顺序恢复： -1. 查看 `ai-plan/public/traces/cqrs-rewrite-migration-trace.md` +1. 查看 `ai-plan/public/cqrs-rewrite/traces/cqrs-rewrite-migration-trace.md` 2. 确认当前恢复点 `CQRS-REWRITE-RP-042` 已对应到最新提交 3. 优先继续执行 `ai-plan/migration/CQRS_MODULE_SPLIT_PLAN.md` 中的 Phase 7： - 先决定是否正式支持旧 `GFramework.Core.Abstractions.Cqrs*` / `GFramework.Core.Cqrs.Extensions` public namespace 兼容，还是明确要求消费端迁到当前 `GFramework.Cqrs*` 路径 @@ -659,7 +659,7 @@ - `dotnet build GFramework.Cqrs/GFramework.Cqrs.csproj -c Release` - 结果：通过 - 备注：存在既有 `MA0051` 与 `MA0158` analyzer warnings，无新增构建错误 -- `rg -n "ai-libs/Mediator|只读|第三方项目源码副本" AGENTS.md ai-plan/public/todos/cqrs-rewrite-migration-tracking.md ai-plan/public/traces/cqrs-rewrite-migration-trace.md` +- `rg -n "ai-libs/Mediator|只读|第三方项目源码副本" AGENTS.md ai-plan/public/cqrs-rewrite/todos/cqrs-rewrite-migration-tracking.md ai-plan/public/cqrs-rewrite/traces/cqrs-rewrite-migration-trace.md` - 结果：通过 - 备注：`AGENTS.md`、tracking 与 trace 均已命中新规则和本地参考路径说明 @@ -717,7 +717,7 @@ - `--branch` 到 PR 编号的解析改为走 GitHub PR API - CodeRabbit summary / CTRF 测试报告改为走 issue comments API - 最新 review 依据改为 latest head commit review threads，而不是只看汇总块 - - `ai-plan/public/todos/cqrs-rewrite-migration-tracking.md` 已移除公开文档中的机器本地绝对路径，并统一 + - `ai-plan/public/cqrs-rewrite/todos/cqrs-rewrite-migration-tracking.md` 已移除公开文档中的机器本地绝对路径，并统一 下次恢复建议里的恢复点编号 ### 阶段：RP-042 验证 diff --git a/ai-plan/public/traces/cqrs-rewrite-migration-trace.md b/ai-plan/public/cqrs-rewrite/traces/cqrs-rewrite-migration-trace.md similarity index 99% rename from ai-plan/public/traces/cqrs-rewrite-migration-trace.md rename to ai-plan/public/cqrs-rewrite/traces/cqrs-rewrite-migration-trace.md index 3696ff6c..237379b7 100644 --- a/ai-plan/public/traces/cqrs-rewrite-migration-trace.md +++ b/ai-plan/public/cqrs-rewrite/traces/cqrs-rewrite-migration-trace.md @@ -1327,7 +1327,7 @@ - `dotnet build GFramework.Cqrs/GFramework.Cqrs.csproj -c Release` - 结果：通过 - 备注：存在既有 `MA0051` 与 `MA0158` analyzer warnings，无新增构建错误 -- `rg -n "ai-libs/|ai-libs/Mediator|只读|第三方源码参考区|第三方项目源码副本" AGENTS.md ai-plan/public/todos/cqrs-rewrite-migration-tracking.md ai-plan/public/traces/cqrs-rewrite-migration-trace.md` +- `rg -n "ai-libs/|ai-libs/Mediator|只读|第三方源码参考区|第三方项目源码副本" AGENTS.md ai-plan/public/cqrs-rewrite/todos/cqrs-rewrite-migration-tracking.md ai-plan/public/cqrs-rewrite/traces/cqrs-rewrite-migration-trace.md` - 结果：通过 - 备注：三处文档都已命中 `ai-libs` 只读规则与 `ai-libs/Mediator` 参考路径 @@ -1378,7 +1378,7 @@ - 不依赖 `gh` CLI，也不要求登录态；脚本会显式绕过当前 shell 中失效的代理变量 - 用新脚本验证了 PR `#253` 的当前状态： - latest head commit review threads 已可直接从 API 提取；在远端最新提交未更新前，当前仍显示 4 条 open - threads，其中 2 条落在 `fetch_current_pr_review.py`、2 条落在 `ai-plan/public/todos/cqrs-rewrite-migration-tracking.md` + threads，其中 2 条落在 `fetch_current_pr_review.py`、2 条落在 `ai-plan/public/cqrs-rewrite/todos/cqrs-rewrite-migration-tracking.md` - PR 页面当前无 `Failed Tests`，CTRF 测试报告显示 `2103 passed / 0 failed` - `Failed checks` 当前可稳定提取到 `Docstring Coverage` warning；该项属于 PR 级文档注释覆盖率问题，不是 FPR skill 解析链路故障 diff --git a/ai-plan/public/todos/ai-plan-governance-tracking.md b/ai-plan/public/todos/ai-plan-governance-tracking.md deleted file mode 100644 index 0bb51913..00000000 --- a/ai-plan/public/todos/ai-plan-governance-tracking.md +++ /dev/null @@ -1,50 +0,0 @@ -# AI-Plan 治理跟踪 - -## 目标 - -收口 `ai-plan/` 的目录语义与提交边界，避免不同 worktree 的恢复文件持续膨胀并污染仓库历史。 - -- 为 `ai-plan/` 建立明确的目录分层 -- 区分“可提交共享状态”与“工作树私有状态” -- 明确禁止写入敏感数据、绝对路径和机器本地信息 -- 让 `AGENTS.md` 与 boot skill 使用同一套目录语义 - -## 当前恢复点 - -- 恢复点编号：`AI-PLAN-GOV-RP-002` -- 当前阶段：`Phase 1` -- 当前焦点： - - 已将共享恢复文档迁移到 `ai-plan/public/todos/` 与 `ai-plan/public/traces/` - - 已保留 `ai-plan/private/` 作为工作树私有空间，并通过 `.gitignore` 保持未跟踪 - - 已新增 `ai-plan/README.md`，明确目录语义、命名方式和敏感信息限制 - - 已同步更新 `AGENTS.md` 与 `gframework-boot`，让启动流程和 tracking 规则使用新的目录语义 - - 已将目录根名从 `local-plan/` 正式收口到 `ai-plan/`，避免“本地计划”和“可共享 AI 恢复文档”语义混淆 - -## 已完成 - -- `.gitignore` 现只允许 `ai-plan/README.md` 与 `ai-plan/public/**/*.md` 被纳入版本控制 -- `AGENTS.md` 已补充： - - `public/**` 与 `private/` 的职责划分 - - 禁止写入敏感数据、绝对路径、主机与账号信息 - - 复杂任务应更新 `ai-plan/public/**`，而不是把 worktree 私有状态直接丢进 Git -- `.codex/skills/gframework-boot/SKILL.md` 与其 `references/startup-artifacts.md` 已切换到： - - 优先读取 `ai-plan/public/**` - - 按需读取 `ai-plan/private//` 作为私有上下文 -- 既有共享 tracking / trace 文件已迁移到 `ai-plan/public/` 下 - -## 验证 - -- `find ai-plan -maxdepth 3 -type f | sort` - - 结果：通过 - - 备注：当前只剩 `ai-plan/README.md` 与 `ai-plan/public/**` 进入仓库可见范围 -- `rg -n "ai-plan/public/|ai-plan/private/" AGENTS.md .codex/skills/gframework-boot/SKILL.md .codex/skills/gframework-boot/references/startup-artifacts.md ai-plan/README.md .gitignore` - - 结果：通过 - - 备注：新目录语义已统一到仓库规则与 boot skill -- `dotnet build GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj -c Release` - - 结果：通过 - - 备注：本轮规则与文档调整未引入构建问题 - -## 下一步 - -1. 若后续需要 worktree 级恢复文件，可在 `ai-plan/private//` 下建立私有目录，但仍遵守“不写敏感数据、不写绝对路径”的约束 -2. 若未来再新增 skill 或仓库规则引用 `ai-plan/`，统一按 `public/**` 与 `private/` 的语义扩展，不再恢复平铺结构 diff --git a/ai-plan/public/traces/ai-plan-governance-trace.md b/ai-plan/public/traces/ai-plan-governance-trace.md deleted file mode 100644 index 77ee6019..00000000 --- a/ai-plan/public/traces/ai-plan-governance-trace.md +++ /dev/null @@ -1,31 +0,0 @@ -# AI-Plan 治理追踪 - -## 2026-04-19 - -### 阶段：目录语义收口（RP-002） - -- 建立 `AI-PLAN-GOV-RP-002` 恢复点 -- 用户指出当前 `ai-plan/` 存在三个治理问题： - - 缺少更细的目录分层，容易随着 worktree 增长持续膨胀 - - 缺少“不得写入敏感数据、真实路径、机器信息”的明确约束 - - 目录语义没有区分共享恢复信息与 worktree 私有状态 -- 已据此完成以下收口： - - 将既有共享 tracking / trace 文件迁移到 `ai-plan/public/todos/` 与 `ai-plan/public/traces/` - - 新增 `ai-plan/private/` 作为工作树私有恢复空间，并通过 `.gitignore` 保持未跟踪 - - 新增 `ai-plan/README.md` 作为目录语义与内容规范的单点说明 - - 在 `AGENTS.md` 中补齐 public/private 职责边界，以及敏感信息与绝对路径禁写规则 - - 在 `gframework-boot` 中同步新的读取顺序：优先 public，按需读取当前 worktree 私有目录 - -### 验证 - -- `find ai-plan -maxdepth 3 -type f | sort` - - 结果：通过 -- `rg -n "ai-plan/public/|ai-plan/private/" AGENTS.md .codex/skills/gframework-boot/SKILL.md .codex/skills/gframework-boot/references/startup-artifacts.md ai-plan/README.md .gitignore` - - 结果：通过 -- `dotnet build GFramework.Core.Abstractions/GFramework.Core.Abstractions.csproj -c Release` - - 结果：通过 - -### 下一步 - -1. 后续若出现新的 worktree 私有恢复需求，直接在 `ai-plan/private//` 下创建，不再向共享目录追加本地临时状态 -2. 若将来需要进一步限制格式，可再为 `public/**` 与 `private/` 各自补一个模板文件，但本轮先把目录语义和安全边界固定下来