repo-harness 0.4.1 → 0.4.3

package/AGENTS.md

@@ -6,7 +6,7 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 
 - `tasks/current.md` for the tracked current-status snapshot derived from workflow artifacts
 - `tasks/todos.md` for deferred medium/long-term goals, not active execution checklists
-- `plans/prds/` for program-level sprint PRDs and ordered backlogs, operated by `scripts/sprint-backlog.sh` (Sprint = program layer; task contracts stay the execution slices)
+- `plans/prds/` for upper-layer PRDs; `plans/sprints/` for ordered sprint backlogs operated through `scripts/sprint-backlog.sh` (installed implementations live under `.ai/harness/scripts/`; task contracts stay the execution slices)
 - `.ai/context/capabilities.json` for the capability registry and longest-prefix context boundaries
 - `tasks/workstreams/` for capability long-running workstreams that project durable progress into local contracts
 - `tasks/lessons.md` for correction-derived rules

package/CLAUDE.md

@@ -6,7 +6,7 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 
 - `tasks/current.md` for the tracked current-status snapshot derived from workflow artifacts
 - `tasks/todos.md` for deferred medium/long-term goals, not active execution checklists
-- `plans/prds/` for program-level sprint PRDs and ordered backlogs, operated by `scripts/sprint-backlog.sh` (Sprint = program layer; task contracts stay the execution slices)
+- `plans/prds/` for upper-layer PRDs; `plans/sprints/` for ordered sprint backlogs operated through `scripts/sprint-backlog.sh` (installed implementations live under `.ai/harness/scripts/`; task contracts stay the execution slices)
 - `.ai/context/capabilities.json` for the capability registry and longest-prefix context boundaries
 - `tasks/workstreams/` for capability long-running workstreams that project durable progress into local contracts
 - `tasks/lessons.md` for correction-derived rules

package/README.es.md

@@ -345,8 +345,8 @@ Guards habituales:
 
 ## Release actual
 
-- npm package: `repo-harness@0.4.1`
-- Generated workflow stamp: `repo-harness@0.4.1+template@0.4.1`
+- npm package: `repo-harness@0.4.3`
+- Generated workflow stamp: `repo-harness@0.4.3+template@0.4.3`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.fr.md

@@ -350,8 +350,8 @@ Guards courants :
 
 ## Release actuelle
 
-- npm package : `repo-harness@0.4.1`
-- Generated workflow stamp : `repo-harness@0.4.1+template@0.4.1`
+- npm package : `repo-harness@0.4.3`
+- Generated workflow stamp : `repo-harness@0.4.3+template@0.4.3`
 - GitHub repository : `Ancienttwo/repo-harness`
 - Release history : [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.ja.md

@@ -312,8 +312,8 @@ hook がブロックしたときは、まず terminal の構造化された出
 
 ## 現在の Release
 
-- npm package：`repo-harness@0.4.1`
-- Generated workflow stamp：`repo-harness@0.4.1+template@0.4.1`
+- npm package：`repo-harness@0.4.3`
+- Generated workflow stamp：`repo-harness@0.4.3+template@0.4.3`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.md

@@ -34,21 +34,29 @@ This repository now dogfoods its own tasks-first contract. It is both:
   read a 1KB capability contract or query the index instead of spending thousands of
   tokens rediscovering structure.
 
-## What's New in 0.4.1
-
-- **Session-scoped CodeGraph nudges.** Hook stdin `session_id` now drives the
-  one-shot CodeGraph route hint, so stale local session files no longer suppress
-  or repeat guidance across independent Claude/Codex sessions.
-- **Central-first hook safety.** Generated and migrated repos stay on the
-  user-level hook runtime by default; repo-local top-level hook scripts are
-  pruned unless `.ai/harness/policy.json` explicitly pins `"hook_source": "repo"`.
-- **Workflow document migration.** Active workflow docs now use
-  `tasks/todos.md` for deferred goals and `docs/researches/*.md` for durable
-  research, with legacy `tasks/todo.md` and `tasks/research.md` treated as
-  migration inputs.
-- **Release-gate stability.** Runtime ignore rules cover transient
-  `tasks/.current.md.tmp.*` and `.claude/.plan-state/` state, and the default
-  Bun test timeout matches the release gate budget.
+In an adopted repo, the surface area is intentionally small:
+
+| Surface | Purpose |
+| --- | --- |
+| `docs/spec.md` and `docs/reference-configs/` | Shared standards and stable product intent that every agent session can read. |
+| `plans/`, `plans/prds/`, and `plans/sprints/` | Decision-complete work packages before implementation starts. |
+| `tasks/contracts/`, `tasks/reviews/`, and `.ai/harness/checks/` | Scope, verification, and review evidence for proving the work is done. |
+| `.ai/harness/handoff/` and `tasks/current.md` | Session journal and resumable status, derived from workflow artifacts instead of chat memory. |
+
+## What's New in 0.4.3
+
+- **Runtime docs lookup.** `repo-harness docs list|path|show` resolves bundled
+  runtime/reference docs from the installed package instead of requiring copied
+  repo prose.
+- **Init-hook bootstrap audit.** `repo-harness init-hook --json` reports concrete
+  Agent actions for missing working rules, adapter drift, stale CLI installs,
+  and tooling readiness.
+- **First-principles edit guard.** Managed hook routes now include
+  anti-overengineering guidance for implementation edits while keeping the guard
+  advisory.
+- **Slimmer generated reference docs.** Generated and migrated repos write
+  deterministic `docs/reference-configs/*.md` pointer stubs while `.ai/harness/*`
+  and `.ai/context/*` remain local runtime artifacts.
 
 ## What repo-harness Does
 
@@ -119,7 +127,8 @@ delegation without changing the file-backed authority model.
 ```mermaid
 flowchart TD
   Program["Program goal or release theme"] --> Sprint{"Sprint layer needed?"}
-  Sprint -->|yes| SprintDoc["Sprint PRD + backlog<br/>plans/prds/*.prd.md"]
+  Sprint -->|yes| PRD["Upper-layer PRD<br/>plans/prds/*.prd.md"]
+  PRD --> SprintDoc["Sprint backlog<br/>plans/sprints/*.sprint.md"]
   SprintDoc --> NextTask["Select next sprint task<br/>sprint-backlog.sh next"]
   Sprint -->|no| UserTask["User task or planning prompt"]
   Heartbeat["Heartbeat triage<br/>scripts/heartbeat-triage.sh<br/>.ai/harness/triage/"] --> UserTask
@@ -185,23 +194,26 @@ judgment in Claude-Fable before asking Codex to loop on execution:
    `plan-eng-review` for engineering plan review. The output should be the
    development documents that lock product intent, architecture, risks, and the
    evidence contract.
-2. Turn those documents into a PRD sprint under `plans/prds/`, with an
-   ordered backlog and detailed sub-plans for each execution slice.
+2. Turn those documents into an upper-layer PRD under `plans/prds/`, then into
+   an ordered sprint backlog under `plans/sprints/` with detailed sub-plans for
+   each execution slice.
 3. In Codex, create a Goal that points at that sprint file. The harness can then
    project each sprint item through the normal plan -> contract -> worktree ->
    verification flow.
 
 That handoff keeps long-running loops precise: Claude-Fable owns the broad
-front-loaded judgment, the PRD sprint is the durable source of truth, and Codex
-Goal mode resumes against a concrete sprint instead of reinterpreting the
-original chat.
+front-loaded judgment, the PRD remains the upper source of truth, the sprint
+backlog is the durable execution queue, and Codex Goal mode resumes against a
+concrete sprint instead of reinterpreting the original chat.
 
 ## First 5 Minutes
 
 This is the fastest path for an AI tooling owner evaluating whether the workflow is
-safe to adopt in a real repo.
+safe to adopt in a real repo. It separates the machine-level runtime bootstrap
+from the repo-local contract install, so a dry run can show exactly what will
+change before anything is applied.
 
-### Initial bootstrap
+### 1. Bootstrap the host runtime once
 
 ```bash
 npx -y repo-harness init
@@ -213,27 +225,36 @@ user-level hook adapters, configures Waza runtime skills, persists a brain root
 under `~/.repo-harness/config.json`, and configures CodeGraph MCP. It does not
 apply repo-local workflow files to the current directory.
 
-### Install or refresh a repo-local harness
+For an Agent-owned, read-only bootstrap audit, run `npx -y repo-harness
+init-hook --json` or add `--check-updates` for version advisories. `init-hook`
+is not a runtime hook: it does not write user-level files, install updates, or
+register adapters. It emits `agent_actions` with the reason, risk, target files,
+optional command, and verification surface for the Agent to execute deliberately.
+
+### 2. Preview the repo-local contract
 
 ```bash
 npx -y repo-harness update --dry-run
+```
+
+Run the dry run from the target repository root. It reports the specs, task
+state, helper runtime, hook adapter target, and verification files that would be
+created or refreshed. It should not create an application stack; existing repos
+use `repo-harness update`, while new projects or modules use
+`repo-harness-scaffold`.
+
+### 3. Apply, then prove the workflow
+
+```bash
 npx -y repo-harness update
+bash scripts/check-task-workflow.sh --strict
+bun test
 ```
 
-`update` is the existing-repo install and refresh path. Run it from a target
-repository to install or refresh workflow files, hook assets, host adapters,
-skill aliases, and repo-local verification surfaces from the current npm package.
-
-The npm package and generated workflow stamp now share the `0.4.x` release line.
-The `0.4.1` package keeps first-run
-global bootstrap (`repo-harness init`) separate from repo-local refresh
-(`repo-harness update`) while hardening session-scoped hook state, central-first
-hook execution, workflow-document migration, and release-gate stability on top
-of the `0.4.0` loop-engine surfaces.
-These sit on top of the renamed `repo-harness` CLI, user-level hook
-adapter bootstrap, AI-native scaffold overlays, the typed prompt-guard decision
-engine, plan-stem task artifact naming, `REPO_HARNESS_*` runtime aliases, Waza
-runtime skill sync, and the maintainer release gate.
+After apply, the repo should have a reviewable file-backed contract rather than
+tool-specific chat setup. Agents should be able to find the stable intent in
+`docs/spec.md`, execution state in `plans/` and `tasks/`, and resume state in
+`.ai/harness/handoff/`.
 
 Only maintainers editing the package need a source checkout:
 
@@ -289,16 +310,9 @@ The command should end with `=== Migration Report ===` and summarize:
 - `Host hook config target: user-level ~/.claude/settings.json and ~/.codex/hooks.json` to show the adapter layer
 - `Host hook adapters are user-level:` to remind the user to install global adapters and trust `~/.codex/hooks.json`
 - `Workflow migration:` to show the repo-local harness surfaces it will create or refresh
-- `Helper scripts:` to show the operational toolchain you get after apply
+- `Helper runtime:` to show `.ai/harness/scripts/*` implementations and `scripts/*` compatibility wrappers after apply
 - `--- External Tooling ---` to show default gstack/Waza/gbrain routing plus advisory install/update hints
 
-### Next two commands
-
-```bash
-bash scripts/check-task-workflow.sh --strict
-bun test
-```
-
 If the dry-run output looks wrong, stop there and inspect
 [`docs/reference-configs/hook-operations.md`](docs/reference-configs/hook-operations.md)
 before applying anything.
@@ -380,8 +394,8 @@ Most common guards:
 
 ## Current Release
 
-- npm package: `repo-harness@0.4.1`
-- Generated workflow stamp: `repo-harness@0.4.1+template@0.4.1`
+- npm package: `repo-harness@0.4.3`
+- Generated workflow stamp: `repo-harness@0.4.3+template@0.4.3`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -431,7 +445,8 @@ Most common guards:
 
 ## Acknowledgements and Workflow Influences
 
-`repo-harness` is built around a small set of external skills and repos that
+`repo-harness` is built around a small set of external skills, repos, and agent
+runtimes that
 proved useful while this project was being designed, debugged, and released.
 They are acknowledged here because they shaped the workflow contract, but they
 are not ordinary bundled product dependencies.
@@ -443,6 +458,20 @@ are not ordinary bundled product dependencies.
 | gstack skills and `gbrain` by [Garry Tan](https://x.com/garrytan) | Product discovery, plan review, design review, post-ship documentation hygiene, knowledge sync, handoff retrieval, and long-form repo memory | External operator workflow plus optional external CLI/index; advisory by default |
 | `mermaid` | Human-readable architecture and system-flow diagrams when Mermaid is not enough | Runtime-referenced skill, not vendored into generated repos |
 | CodeGraph (`@colbymchenry/codegraph`) | Symbol-aware navigation, impact tracing, and readiness checks for this self-host repo | Dev dependency in this repo; generated repos stay global-MCP-first unless policy opts in |
+| OpenAI Codex | Primary execution agent for repo-local implementation, verification, and GitHub contributor attribution when a commit materially includes Codex-authored work | External agent runtime; attribution is an explicit commit trailer, not hidden hook automation |
+
+### GitHub Contributor Attribution
+
+When Codex materially contributes to a commit, use GitHub's standard co-author
+trailer format at the end of the commit message:
+
+```text
+Co-authored-by: codex <codex@openai.com>
+```
+
+Keep this opt-in and visible per commit. Do not bake it into downstream
+repo-harness commit scripts or hooks unless that repo explicitly adopts the same
+policy.
 
 ## Action Command Skills
 
@@ -450,7 +479,8 @@ Source-owned command facades live in `assets/skill-commands/`. They keep host
 skill discovery compatible while the CLI and hooks own execution:
 
 - Planning and review: `repo-harness-plan`, `repo-harness-review`, `repo-harness-autoplan`
-- Sprint program layer: `repo-harness-sprint` (PRD + ordered backlog in `plans/prds/`, executed task-by-task through the contract flow)
+- Product planning layer: `repo-harness-prd` (upper-layer PRDs in `plans/prds/`, evidence-marked unknowns, sprint-consumable sections)
+- Sprint program layer: `repo-harness-sprint` (ordered sprint backlogs in `plans/sprints/`, each row expanded with `$think` before the contract flow)
 - Repo workflow actions: `repo-harness-ship`, `repo-harness-init`, `repo-harness-migrate`, `repo-harness-upgrade`, `repo-harness-capability`, `repo-harness-architecture`, `repo-harness-handoff`, `repo-harness-deploy`, `repo-harness-repair`, `repo-harness-check`
 - Branch project creation command: `repo-harness-scaffold`
 
@@ -510,6 +540,22 @@ bun scripts/inspect-project-state.ts --repo . --format text
 bash scripts/migrate-project-template.sh --repo . --dry-run
 ```
 
+### Runtime reference docs
+
+Generic repo-harness runtime/reference docs live in the installed package under
+`assets/reference-configs/` and are resolved through the CLI:
+
+```bash
+repo-harness docs list
+repo-harness docs path harness-overview
+repo-harness docs show harness-overview
+```
+
+Generated and migrated repos still keep `docs/reference-configs/*.md`, but
+those files are deterministic pointer stubs. Repo-local workflow state,
+policy, checks, runs, handoff packets, context maps, and helper snapshots stay
+under `.ai/`.
+
 ### Explicit template assembly
 
 ```bash
@@ -539,8 +585,9 @@ bun run benchmark:skills --eval repair-agents-task-sync
 - Plan mapping: `assets/plan-map.json`
 - Question-pack: `assets/initializer-question-pack.v4.json`
 - Shared hooks: `assets/hooks/`
+- Runtime reference docs: `assets/reference-configs/` via `repo-harness docs`
 - Workflow contract: `assets/workflow-contract.v1.json`
-- Hook operations reference: `docs/reference-configs/hook-operations.md`
+- Source repo reference docs: `docs/reference-configs/*.md`
 - Template assembler: `scripts/assemble-template.ts`
 - Question inference helper: `scripts/initializer-question-pack.ts`
 - State inspector: `scripts/inspect-project-state.ts`

package/README.zh-CN.md

@@ -23,20 +23,27 @@ repo-local workflow 的自托管样例。
   做渐进式上下文加载：一份小而稳定的 root context（约 12KB），加上只在改到对应文件时才加载的
   capability 块。agent 读一份 1KB 的 capability 合约或查索引，而不是花上千 token 重新摸清结构。
 
-## 0.4.1 新特性
-
-- **Session-scoped CodeGraph 提醒。** Hook stdin 里的 `session_id` 现在会驱动
-  一次性 CodeGraph route hint，避免 stale 本地 session 文件跨 Claude/Codex
-  会话误抑制或重复提醒。
-- **Central-first hook safety。** Generated 和 migrated repos 默认继续使用
-  user-level hook runtime；只有 `.ai/harness/policy.json` 明确设置
-  `"hook_source": "repo"` 时，才保留 repo-local top-level hook scripts。
-- **Workflow 文档迁移。** Active workflow docs 统一使用 `tasks/todos.md`
-  记录 deferred goals，使用 `docs/researches/*.md` 保存 durable research；
-  legacy `tasks/todo.md` 和 `tasks/research.md` 只作为 migration inputs。
-- **Release-gate 稳定性。** Runtime ignore rules 覆盖
-  `tasks/.current.md.tmp.*` 和 `.claude/.plan-state/` 这类 transient state，
-  默认 Bun test timeout 也和 release gate budget 对齐。
+接入后的仓库只需要理解几个 surface：
+
+| Surface | 作用 |
+| --- | --- |
+| `docs/spec.md` 和 `docs/reference-configs/` | 共享标准和稳定产品意图，每个 agent 会话都能读取。 |
+| `plans/`、`plans/prds/`、`plans/sprints/` | 实现前先沉淀 decision-complete work package。 |
+| `tasks/contracts/`、`tasks/reviews/`、`.ai/harness/checks/` | 证明完成所需的 scope、verification 和 review evidence。 |
+| `.ai/harness/handoff/` 和 `tasks/current.md` | session journal 与可恢复状态，从 workflow artifacts 派生，而不是依赖聊天记忆。 |
+
+## 0.4.3 新特性
+
+- **Runtime docs lookup。** `repo-harness docs list|path|show` 从已安装 package
+  解析 bundled runtime/reference docs，不再要求把完整 repo prose 复制到下游。
+- **Init-hook bootstrap audit。** `repo-harness init-hook --json` 会把缺失的
+  working rules、adapter drift、stale CLI install 和 tooling readiness 汇成
+  具体 Agent actions。
+- **First-principles edit guard。** Managed hook routes 增加实现编辑时的
+  anti-overengineering guidance，同时保持 advisory，不把风格判断变成硬拦截。
+- **更轻的 generated reference docs。** 生成和迁移的仓库写入确定性的
+  `docs/reference-configs/*.md` pointer stubs，`.ai/harness/*` 和 `.ai/context/*`
+  继续作为 repo-local runtime artifacts。
 
 ## 产品做什么
 
@@ -167,9 +174,11 @@ source of truth，Codex Goal mode 只围绕具体 sprint 恢复和推进，而
 
 ## 前 5 分钟
 
-这是评估一个真实仓库是否适合接入该 workflow 的最快路径。
+这是评估一个真实仓库是否适合接入该 workflow 的最快路径。它把机器级 runtime
+bootstrap 和 repo-local contract install 分开，所以 dry-run 能先展示会改什么，
+再决定是否应用。
 
-### 初次引导
+### 1. 先做一次 host runtime bootstrap
 
 ```bash
 npx -y repo-harness init
@@ -180,27 +189,34 @@ skill aliases，安装 user-level hook adapters，配置 Waza runtime skills，
 root 持久化到 `~/.repo-harness/config.json`，并配置 CodeGraph MCP。它不会把当前目录
 默认迁移成 repo-local workflow。
 
-### 安装或刷新 repo-local harness
+如果要让 Agent 做只读 bootstrap audit，运行 `npx -y repo-harness init-hook
+--json`；需要版本提示时加 `--check-updates`。`init-hook` 不是 runtime hook：
+它不会写 user-level files、安装更新或注册 adapters，只输出带 reason、risk、
+targets、可选 command 和 verification 的 `agent_actions`，由 Agent 再显式执行。
+
+### 2. 预览 repo-local contract
 
 ```bash
 npx -y repo-harness update --dry-run
-npx -y repo-harness update
 ```
 
-`update` 是已有目标仓库的安装和刷新入口。从目标仓库根目录运行它，用当前 npm 包
-安装或刷新 workflow files、hook assets、host adapters、skill aliases 和
-repo-local verification surfaces。
+在目标仓库根目录运行 dry-run。它会报告将要创建或刷新的 spec、task state、
+helper runtime、hook adapter target 和 verification files。它不会创建应用技术栈；
+已有仓库走 `repo-harness update`，新项目或新模块走 `repo-harness-scaffold`。
+
+### 3. 应用后验证 workflow
+
+```bash
+npx -y repo-harness update
+bash scripts/check-task-workflow.sh --strict
+bun test
+```
 
-npm package 和 generated workflow stamp 现在共用 `0.4.x` release line。
-`repo-harness@0.4.1` 继续把首次全局引导（`repo-harness init`）
-和 repo-local 刷新（`repo-harness update`）拆开，并在 `0.4.0` loop-engine
-surfaces 之上强化 session-scoped hook state、central-first hook execution、
-workflow-document migration 和 release-gate stability。
-这些能力叠加在改名后的 CLI、user-level hook adapter bootstrap、AI-native scaffold overlays、
-typed prompt-guard decision engine、plan-stem task artifact 命名、`REPO_HARNESS_*`
-runtime aliases、Waza runtime skill sync，以及 maintainer 发布 npm 前使用的 release gate 之上。
+应用后，目标仓库应该得到一套可审查的 file-backed contract，而不是 tool-specific
+聊天配置。agent 应该能在 `docs/spec.md` 找到稳定意图，在 `plans/` 和 `tasks/`
+找到执行状态，在 `.ai/harness/handoff/` 找到可恢复状态。
 
-只有维护者需要在编辑 package 源码时使用 source checkout：
+只有维护者编辑 package 源码时才需要 source checkout：
 
 ```bash
 git clone https://github.com/Ancienttwo/repo-harness.git ~/Projects/repo-harness
@@ -254,13 +270,6 @@ npx -y repo-harness update
 - `Helper scripts:`：应用后会得到的操作工具链
 - `--- External Tooling ---`：gstack/Waza/gbrain 路由以及 advisory 安装/更新提示
 
-### 接着跑的两个命令
-
-```bash
-bash scripts/check-task-workflow.sh --strict
-bun test
-```
-
 如果 dry-run 输出不对，先停在这里，阅读
 [`docs/reference-configs/hook-operations.md`](docs/reference-configs/hook-operations.md)。
 
@@ -334,8 +343,8 @@ hook block 工作时，先看 terminal 里的结构化输出。核心字段是
 
 ## 当前 Release
 
-- npm package：`repo-harness@0.4.1`
-- Generated workflow stamp：`repo-harness@0.4.1+template@0.4.1`
+- npm package：`repo-harness@0.4.3`
+- Generated workflow stamp：`repo-harness@0.4.3+template@0.4.3`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -373,6 +382,16 @@ decision rationale 的要求，来自他的贡献与启发。
 product discovery、plan/design review、release 文档、knowledge sync 和
 handoff retrieval 的工作流设计。
 
+感谢 OpenAI Codex 作为本仓库主要执行 agent 参与实现、验证和收口。Codex 对某个
+commit 有实质贡献时，GitHub contributor 署名使用显式 trailer：
+
+```text
+Co-authored-by: codex <codex@openai.com>
+```
+
+这条署名保持逐 commit 显式添加，不把它藏进下游 `repo-harness` commit 脚本或 hook
+里，除非目标仓库自己采用同样策略。
+
 ## Action Command Skills
 
 公共 command facades 在 `assets/skill-commands/`；它们保留 host skill discovery

package/SKILL.md

@@ -142,7 +142,8 @@ contract files:
 - `repo-harness-deploy`: check deploy and private operations configuration without publishing or deploying
 - `repo-harness-repair`: repair broken task sync, hook routing, handoff, context, policy, or helpers
 - `repo-harness-check`: run verification gates and report release or pre-merge readiness
-- `repo-harness-sprint`: plan a program-level sprint (PRD + ordered backlog) and drive backlog tasks through the task-contract flow
+- `repo-harness-prd`: generate an upper-layer PRD in `plans/prds/`
+- `repo-harness-sprint`: plan a sprint backlog in `plans/sprints/` from a PRD or source spec, then expand each row with `$think` before the task-contract flow
 
 Internal steps such as `hooks-init`, `docs-init`, and `create-project-dirs` are
 not public commands. They stay behind `init`, `scaffold`, `migrate`, and

package/assets/hooks/AGENTS.md

@@ -37,3 +37,39 @@ Owns the runtime-harness-hook-adapters capability boundary declared in .ai/conte
 - `bun test tests/hook-runtime.test.ts tests/hook-contracts.test.ts tests/workflow-contract.test.ts`
 - `bash scripts/check-task-workflow.sh --strict`
 <!-- END CAPABILITY CONTEXT -->
+
+<!-- BEGIN ARCHITECTURE CONTRACT -->
+## Architecture Contract
+
+- Functional block: `.ai/hooks`
+- Capability ID: `runtime-harness-hook-adapters`
+- Matched prefix: `.ai/hooks`
+- Architecture domain: `runtime-harness`
+- Architecture capability: `hook-adapters`
+- Architecture module: `docs/architecture/modules/runtime-harness/hook-adapters.md`
+- Last architecture event: 2026-06-13T00:04:13+0800
+- Last changed path: `.ai/hooks/post-tool-observer.sh`
+- Severity: high
+- Change type: workflow-surface
+- Module responsibility: Keep this block aligned with the local boundary described by surrounding human-owned context.
+- Entrypoints: `.ai/hooks`
+- Allowed dependencies: Follow root `AGENTS.md` / `CLAUDE.md` and this local contract.
+- Forbidden dependencies: Do not cross sibling app/service/package boundaries without an architecture snapshot or explicit plan.
+- Runtime path: `.ai/hooks`
+- LSP/tooling profile: `typescript-lsp`
+- Verification: Use root required checks plus local commands recorded in this capability contract.
+- Latest snapshot: `(none yet)`
+- Semantic diagram source: `docs/architecture/modules/runtime-harness/hook-adapters.md`
+- Latest human diagram: `(none yet)`
+- Pending architecture request: `(none)`
+
+## Active Workstreams
+
+- (none yet)
+
+## Current Session Projection
+
+- Durable progress lives under `tasks/workstreams/runtime-harness/hook-adapters`.
+- `tasks/current.md` is the tracked derived status snapshot; it is not a live lock or task source.
+- `tasks/todos.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
+<!-- END ARCHITECTURE CONTRACT -->

package/assets/hooks/CLAUDE.md

@@ -37,3 +37,39 @@ Owns the runtime-harness-hook-adapters capability boundary declared in .ai/conte
 - `bun test tests/hook-runtime.test.ts tests/hook-contracts.test.ts tests/workflow-contract.test.ts`
 - `bash scripts/check-task-workflow.sh --strict`
 <!-- END CAPABILITY CONTEXT -->
+
+<!-- BEGIN ARCHITECTURE CONTRACT -->
+## Architecture Contract
+
+- Functional block: `.ai/hooks`
+- Capability ID: `runtime-harness-hook-adapters`
+- Matched prefix: `.ai/hooks`
+- Architecture domain: `runtime-harness`
+- Architecture capability: `hook-adapters`
+- Architecture module: `docs/architecture/modules/runtime-harness/hook-adapters.md`
+- Last architecture event: 2026-06-13T00:04:13+0800
+- Last changed path: `.ai/hooks/post-tool-observer.sh`
+- Severity: high
+- Change type: workflow-surface
+- Module responsibility: Keep this block aligned with the local boundary described by surrounding human-owned context.
+- Entrypoints: `.ai/hooks`
+- Allowed dependencies: Follow root `AGENTS.md` / `CLAUDE.md` and this local contract.
+- Forbidden dependencies: Do not cross sibling app/service/package boundaries without an architecture snapshot or explicit plan.
+- Runtime path: `.ai/hooks`
+- LSP/tooling profile: `typescript-lsp`
+- Verification: Use root required checks plus local commands recorded in this capability contract.
+- Latest snapshot: `(none yet)`
+- Semantic diagram source: `docs/architecture/modules/runtime-harness/hook-adapters.md`
+- Latest human diagram: `(none yet)`
+- Pending architecture request: `(none)`
+
+## Active Workstreams
+
+- (none yet)
+
+## Current Session Projection
+
+- Durable progress lives under `tasks/workstreams/runtime-harness/hook-adapters`.
+- `tasks/current.md` is the tracked derived status snapshot; it is not a live lock or task source.
+- `tasks/todos.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
+<!-- END ARCHITECTURE CONTRACT -->

package/assets/hooks/anti-simplification.sh

@@ -1,30 +1,12 @@
 #!/bin/bash
-# Anti-Simplification Guard — PostToolUse on Edit|Write
-# Warns when changes suggest compatibility debt or unnecessary branch complexity.
+# Compatibility wrapper for the renamed First-Principles Guard.
 
 set -eo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-# shellcheck source=/dev/null
-. "$SCRIPT_DIR/hook-input.sh"
 
-FILE_PATH="$(hook_get_file_path "${1:-}")"
-[[ -z "$FILE_PATH" ]] && exit 0
-
-if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-  exit 0
+if [[ -f "$SCRIPT_DIR/first-principles-guard.sh" ]]; then
+  exec bash "$SCRIPT_DIR/first-principles-guard.sh" "$@"
 fi
 
-DIFF_CONTENT="$(git diff -- "$FILE_PATH" 2>/dev/null || true)"
-[[ -z "$DIFF_CONTENT" ]] && exit 0
-
-if echo "$DIFF_CONTENT" | grep -E '^\+.*(legacy|compat|backward|polyfill|shim)' >/dev/null; then
-  echo "[AntiSimplification] Compatibility-like additions detected in $FILE_PATH"
-  echo "  Prefer clean upgrades and rewrite-over-patch instead of legacy branches."
-fi
-
-branch_additions="$(echo "$DIFF_CONTENT" | grep -E '^\+.*\b(if|else if|switch)\b' | wc -l | tr -d ' ')"
-if [[ "$branch_additions" -ge 4 ]]; then
-  echo "[AntiSimplification] Branch-heavy additions detected in $FILE_PATH ($branch_additions new branch lines)"
-  echo "  Re-check data structures before adding more control-flow branches."
-fi
+exit 0

package/assets/hooks/codex.hooks.template.json

@@ -15,6 +15,12 @@
           { "type": "command", "command": "repo=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0; HOOK_HOST=codex HOOK_REPO_ROOT=\"$repo\" bash \"$repo/.ai/hooks/run-hook.sh\" worktree-guard.sh", "timeout": 30 },
           { "type": "command", "command": "repo=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0; HOOK_HOST=codex HOOK_REPO_ROOT=\"$repo\" bash \"$repo/.ai/hooks/run-hook.sh\" pre-edit-guard.sh", "timeout": 30 }
         ]
+      },
+      {
+        "matcher": "Task|Agent|SendUserMessage",
+        "hooks": [
+          { "type": "command", "command": "repo=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0; HOOK_HOST=codex HOOK_REPO_ROOT=\"$repo\" bash \"$repo/.ai/hooks/run-hook.sh\" subagent-return-channel-guard.sh", "timeout": 30 }
+        ]
       }
     ],
     "PostToolUse": [