diff --git a/AGENTS.md b/AGENTS.md index cafd8cb7..27a2395f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,14 +10,21 @@ All AI agents and contributors must follow these rules when writing, reviewing, - Use `@.ai/environment/tools.raw.yaml` only when you need the full collected facts behind the AI-facing hints. - Prefer the project-relevant tools listed there instead of assuming every installed system tool is fair game. - If the real environment differs from the inventory, use the project-relevant installed tool and report the mismatch. -- When working in WSL against this repository's Windows-backed worktree, prefer Windows Git from WSL (for example - `git.exe`) instead of the Linux `git` binary. -- If a Git command in WSL fails with a worktree-style “not a git repository” path translation error, rerun it with the - Windows Git executable and treat that as the repository-default Git path for the rest of the task. -- If the shell does not currently resolve `git.exe` to the host Windows Git installation, prepend that installation's - command directory to `PATH` and reset shell command hashing for the current session before continuing. -- After resolving the host Windows Git path, prefer an explicit session-local binding for subsequent commands so the - shell does not fall back to Linux `/usr/bin/git` later in the same WSL session. +- When working in WSL against this repository's Windows-backed worktree, first prefer Linux `git` with an explicit + `--git-dir=/.git/worktrees/` and `--work-tree=` binding for every repository + command. Treat that explicit binding as higher priority than `git.exe`, because it avoids WSL worktree path + translation mistakes and still works in sessions where Windows `.exe` execution is unavailable. +- If a plain Linux `git` command in WSL fails with a worktree-style “not a git repository” path translation error, + rerun it with the explicit `--git-dir` / `--work-tree` binding before trying `git.exe`. +- Only prefer Windows Git from WSL (for example `git.exe`) when that executable is both resolvable and executable in the + current session, and when the explicit Linux `git` binding is unavailable or has already failed. +- If the shell resolves `git.exe` but the current WSL session cannot execute it cleanly (for example `Exec format + error`), keep using the explicit Linux `git` binding for the rest of the task instead of retrying Windows Git. +- If the shell does not currently resolve `git.exe` to the host Windows Git installation and you still need Windows Git + as a fallback, prepend that installation's command directory to `PATH` and reset shell command hashing for the + current session before continuing. +- After resolving either strategy, prefer a session-local binding or command wrapper for subsequent Git commands so the + shell does not silently fall back to the wrong repository context later in the same WSL session. ## Git Workflow Rules diff --git a/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md b/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md index 941b7f00..070a982e 100644 --- a/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md +++ b/ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md @@ -12,12 +12,12 @@ ## 当前恢复点 -- 恢复点编号:`DOCUMENTATION-FULL-COVERAGE-GOV-RP-005` -- 当前阶段:`Phase 4 - Game Docs Refresh` +- 恢复点编号:`DOCUMENTATION-FULL-COVERAGE-GOV-RP-006` +- 当前阶段:`Phase 5 - Governance Maintenance` - 当前焦点: - - 收口 `Game` / `Game.Abstractions` / `Game.SourceGenerators` 的 README / landing / abstractions / XML inventory - - 延续 `README / landing / API reference / XML inventory` 的同一治理模板 - - 把 `Game.Abstractions` 从失真的接口摘录页收敛为真实契约边界页面,并为下一轮巡检保留统一口径 + - 将当前 WSL 会话验证通过的 Git 回退策略写回 `AGENTS.md` + - 明确显式 `--git-dir` / `--work-tree` 绑定在本仓库中的优先级高于 `git.exe` + - 避免后续 `boot` / 恢复任务重复踩到 `git.exe` 无法执行与 plain `git` worktree 路径翻译错误 ## 当前状态摘要 @@ -51,6 +51,8 @@ - 为 `docs/zh-CN/game/index.md` 补齐 frontmatter,并增加 `Game` / `Game.Abstractions` / `Game.SourceGenerators` 的 XML 覆盖基线入口 - 将 `docs/zh-CN/abstractions/game-abstractions.md` 从失真的旧接口摘录页重写为契约边界 / 包关系 / 最小接入路径页面 - 基于顶层目录轻量盘点确认:`GFramework.Game` 为 `56/56`、`GFramework.Game.Abstractions` 为 `80/80`、`GFramework.Game.SourceGenerators` 为 `2/2`,当前公开 / 内部类型声明都已带 XML 注释 + - 更新 `AGENTS.md` 的 WSL Git 策略,将显式 `--git-dir` / `--work-tree` 绑定提升为高于 `git.exe` 的默认优先级 + - 记录当前环境偏差:本会话 `git.exe` 可解析但执行会触发 `Exec format error`,而 plain Linux `git` 会命中 worktree 路径翻译错误,需要显式仓库绑定 ## Inventory(第一版) @@ -88,6 +90,8 @@ - 缓解措施:站内页面用模块路径文本或站内 API 入口表达,仓库级 README 仍保留仓库文件链接 - `GFramework.Cqrs` 在当前 WSL / dotnet 环境下,本地 build 仍会读取失效的 fallback package folder 配置,导致无法完成该项目的标准编译验证 - 缓解措施:本轮先以 `GFramework.Cqrs.SourceGenerators` 编译通过和 docs site build 通过作为有效验证,并在后续环境治理或构建脚本清理时单独处理 `RestoreFallbackFolders` / 资产文件问题 +- 当前 WSL 会话中 `git.exe` 虽然可解析,但不能执行 + - 缓解措施:把显式 `--git-dir` / `--work-tree` 绑定上升为仓库默认回退策略,并仅把 `git.exe` 保留为可执行时的次级 fallback ## 验证说明 @@ -154,6 +158,9 @@ - `cd docs && bun run build` - 结果:通过 - 备注:`2026-04-23` 在 `Game` 波次文档刷新后重新构建通过;仅保留 VitePress 大 chunk warning,无构建失败 +- `cd docs && bun run build` +- 结果:通过 +- 备注:`2026-04-23` 在更新 `AGENTS.md` 的 WSL Git 优先级后重新构建通过;仅保留 VitePress 大 chunk warning,无构建失败 ## 下一步 diff --git a/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md b/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md index 4c938d80..2e33a6b0 100644 --- a/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md +++ b/ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md @@ -178,3 +178,30 @@ 1. 进入 `Game` family 巡检,优先检查 `config-system.md`、`scene.md`、`ui.md` 与 `source-generators/index.md` 的交叉引用是否回漂 2. 评估是否需要把 `Godot` family 的关键 XML inventory 摘要迁回 active topic,减少对 archive 的依赖 + +### 当前恢复点:RP-006 + +- 更新 `AGENTS.md` 的 WSL Git 规则: + - 将显式 `git --git-dir=<...> --work-tree=<...>` 绑定提升为高于 `git.exe` 的默认优先级 + - 明确 plain Linux `git` 命中 worktree 路径翻译错误时,应先切到显式绑定而不是直接改用 `git.exe` + - 明确 `git.exe` 只有在当前会话可执行时才作为次级 fallback +- 记录本次恢复任务的环境偏差: + - `git.exe` 在当前 WSL 会话中可解析,但执行会触发 `Exec format error` + - plain `git` 会把 worktree 元数据路径翻译错并报“not a git repository” + - 显式 `--git-dir` / `--work-tree` 绑定是本次已验证可用的 Git 操作方式 + +### 当前决策(RP-006) + +- 把 Git 回退顺序写进 `AGENTS.md`,而不是只留在一次性的聊天上下文里 +- 不额外扩张 `gframework-boot` skill,因为它本身不内嵌 Git 选择逻辑,继续由 `AGENTS.md` 作为唯一准则 +- 继续把 `git.exe` 保留为 fallback,而不是完全删除,避免在可执行的 WSL 会话里丢掉可用路径 + +### 当前验证(RP-006) + +- 构建校验: + - `cd docs && bun run build`:通过;仅保留 VitePress 大 chunk warning,无构建失败 + +### 下一步 + +1. 继续 `Game` family 巡检,优先检查 `config-system.md`、`scene.md`、`ui.md` 与 `source-generators/index.md` 的交叉引用是否回漂 +2. 评估是否需要把 `Godot` family 的关键 XML inventory 摘要迁回 active topic,减少对 archive 的依赖