zenforge-init

zenforge-init — 仓库脚手架引擎

运行不变量

• 变更前置关卡：仅通过 Changeset 暂存严格缺失的资源，然后暂停当前轮次，等待人工批准；绝不覆盖有效的现有配置。
• 隐私基线：始终在 .gitignore 中隔离 .agents/scratch/、.agents/dev-environment.md 和旧版 .agents/host-toolchain.md；禁止提交临时草稿文件、本机环境配置或机密信息。

领域规则

1. 任务跟踪矩阵（.agents/task-tracker.md）

• 远程 GitHub + gh auth status 有效 ──> 提议使用 GitHub Issues (gh)（模板 references/issue-tracker-github.md）或 本地 Markdown。
• 远程 GitLab + glab auth status 有效 ──> 提议使用 GitLab Issues (glab)（模板 references/issue-tracker-gitlab.md）或 本地 Markdown。
• CLI 未认证／其他远程仓库／离线 ──> 提议使用 本地 Markdown（.agents/tasks/，模板 references/issue-tracker-local.md）。向用户报告 CLI 认证状态，以便他们选择进行认证或继续使用本地方式。

2. Harness 锚点（.agents/harness-anchor.md）

使用模板 references/harness-anchor.md 提议 Harness 锚点。

• SSOT 发现：扫描现有测试指南（test/AGENTS.md、tests/AGENTS.md、docs/**/testing*.md、<subsystem>/test/AGENTS.md）。将发现的所有 SSOT 路径作为相对路径记录在 Governing Testing SSOTs 下，不抄录内容，以避免副本过时，并将 Agent 直接引导至权威来源。
• Hermetic 原语发现：扫描测试辅助目录（test/helpers/、test/fixtures/），在 Hermetic Primitives Registry 中登记现有基础辅助工具。

3. 开发环境与主机配置（.agents/dev-environment.md）

使用模板 references/dev-environment.md 提议 开发环境配置。通过 scripts/discover-toolchain.sh 填充或替换 ## 1. Toolchain & Environment 部分（--file 默认为 .agents/dev-environment.md；若该文件不存在，则回退到 .agents/host-toolchain.md，并确保目标文件位于 .gitignore 中），记录当前启用的运行时包装器、规范的测试／分析命令，以及已安装的主机 CLI。对于不适用的部分（服务、数据存储），可以省略。

4. Git 隐私配置（.gitignore）

• .agents/scratch/：私有草稿区（不可变）。
• .agents/dev-environment.md / .agents/host-toolchain.md：本机环境与工具链配置（不可变）。
• .agents/tasks/：本地 Markdown 的默认本地专用目录；若用户要求团队共享跟踪，则省略。

5. 文档放置矩阵（docs/README.md）

# Documentation Index & Placement Matrix

| Topic / Scope | Authoritative SSOT | Responsibility |
| :--- | :--- | :--- |
| **Tasks & Execution** | Defined in `.agents/task-tracker.md` | Decomposed task units and progress tracking |
| **Testing Governance** | Defined in `.agents/harness-anchor.md` | Test harness infrastructure and invariant testing |
| **Documentation Governance** | `docs/` | Governed via `/ssot` |

6. Agent 章程钩子（AGENTS.md 或 CLAUDE.md）

如果存在 CLAUDE.md，则以其为目标；否则以 AGENTS.md 为目标（若不存在则创建）。如果目标文件已存在，则追加此内容块；不要覆盖：

## Agent Workflow
- **Dev Environment**: Governed by `.agents/dev-environment.md` (local runners, zero-touch for `.env*` secrets).
- **Task Tracker**: Governed by `.agents/task-tracker.md`.
- **Harness Anchor**: Governed by `.agents/harness-anchor.md` (via `/harness-audit`).
- **Documentation**: Governed by `docs/README.md` (via `/ssot`).

路由

• 调用方在设置完成后请求设计讨论 →（通过 /clarify）。
• 调用方请求检查 harness 健康状况 →（通过 /harness-audit）。
• 调用方请求审查文档权威性 →（通过 /ssot）。

执行协议

阶段 1：只读探索

1. 远程仓库与拓扑结构：运行 git remote -v，确定主机和仓库路径（owner/repo）。

2. 工具链预检：运行 bash scripts/discover-toolchain.sh <path_to_repository> --dry-run，检查跟踪器 CLI 身份验证（gh / glab）、推断出的运行时包装器、测试／分析命令，以及已安装的主机工具，且不修改磁盘。

3. 工作区信号：

   • 检查 AGENTS.md 与 CLAUDE.md（保留现有文件，禁止重复创建）。
   • 检查 .gitignore、.agents/dev-environment.md（或 .agents/host-toolchain.md）、.agents/task-tracker.md、.agents/harness-anchor.md、.agents/tasks/。
   • 扫描现有文档（docs/README.md 或 README.md）。

4. 配置齐全时提前结束：如果所有脚手架资源（.agents/dev-environment.md / .agents/host-toolchain.md、.agents/task-tracker.md、.agents/harness-anchor.md、.gitignore 隐私规则、docs/README.md 和 constitution 钩子）都已配置且有效，则报告：

   Repository ecosystem is already initialized and up-to-date.
   
   

   立即结束当前轮次，不要暂存多余的变更。

阶段 2：暂存与授权关卡

1. 以 Changeset 格式暂存缺失或尚未配置的脚手架资源：

   # Changeset: Repository Initialization
   
   |-- .agents/
   |   |-- dev-environment.md
   |   |   `-- [CREATE] Record machine-local environment, toolchains, and service contracts.
   |   |-- task-tracker.md
   |   |   `-- [CREATE] Configure task tracking mode and execution protocols.
   |   `-- harness-anchor.md
   |       `-- [CREATE] Establish test SSOT routing and hermetic primitives registry.
   |-- docs/README.md
   |   `-- [<ACTION>] Establish documentation Placement Matrix.
   |-- .gitignore
   |   `-- [<ACTION>] Add .agents/scratch/, .agents/dev-environment.md, and .agents/tasks/ privacy rules.
   `-- <AGENTS.md | CLAUDE.md>
       `-- [<ACTION>] Add agent workflow, secret privacy rules, and documentation pointers.
   
   Summary: <N> files affected (<C> created, <U> updated).
   

2. 提供 Changeset 摘要、建议的跟踪器选择和工具链状态（如果 CLI 未通过身份验证，则报告身份验证状态）。禁止在聊天中输出原始文件内容。

3. 立即暂停，等待人工批准；未经明确授权，禁止修改磁盘上的工作区文件。

阶段 3：原子化应用与交接

1. 收到批准后，将暂存的文件写入磁盘，并运行 bash scripts/discover-toolchain.sh <path_to_repository> [--file <path.md>]，以创建或更新 .agents/dev-environment.md 并将其登记到 .gitignore 中。
2. 报告设置已完成，以及任何与调用方相关的后续事项缺口。