repo-harness 0.4.0 → 0.4.1

package/AGENTS.md

@@ -5,8 +5,8 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 ## Canonical Workflow Files
 
 - `tasks/current.md` for the tracked current-status snapshot derived from workflow artifacts
-- `tasks/todo.md` for deferred medium/long-term goals, not active execution checklists
-- `tasks/sprints/` for program-level sprint PRDs and ordered backlogs, operated by `scripts/sprint-backlog.sh` (Sprint = program layer; task contracts stay the execution slices)
+- `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)
 - `.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
@@ -24,7 +24,7 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 - Sync `tasks/` whenever substantive repo changes are made.
 - Use `tasks/notes/<plan-stem>.notes.md` only for non-obvious slice decisions, deviations, tradeoffs, and open questions; `<plan-stem>` is the active plan filename without `plan-` and `.md` (for example `20260531-0045-governance-workflow`). Do not use notes as durable memory or a task log, and archive/promote them deliberately when the slice closes.
 - Treat hook execution as central-first: trusted repos run `~/.repo-harness/hooks/` (bash shim) or the packaged CLI copy; this self-host repo pins `"hook_source": "repo"` in `.ai/harness/policy.json` so `.ai/hooks/` stays the live development runtime, with `assets/hooks/` as the product source mirrored on install. User-level `~/.claude/settings.json` and `~/.codex/hooks.json` are the host adapters.
-- Keep the umbrella hierarchy explicit: architecture owns stable truth, capability contracts own local agent context, `tasks/workstreams/<domain>/<capability>/` owns durable progress, and `tasks/todo.md` owns only deferred medium/long-term goals with tradeoff and revisit trigger.
+- Keep the umbrella hierarchy explicit: architecture owns stable truth, capability contracts own local agent context, `tasks/workstreams/<domain>/<capability>/` owns durable progress, and `tasks/todos.md` owns only deferred medium/long-term goals with tradeoff and revisit trigger.
 - Treat `.ai/context/capabilities.json` as the source of truth for capability prefixes; `agent-context-blocks.txt` and nested agent files are compatibility inputs only.
 - Keep architecture drift handling split: `architecture-queue.sh` writes architecture requests/events, `workstream-sync.sh` maintains durable capability workstreams, and `context-contract-sync.sh` only updates controlled local `CLAUDE.md`/`AGENTS.md` architecture blocks.
 - Keep `assets/workflow-contract.v1.json` and `.ai/harness/workflow-contract.json` in sync.
@@ -90,5 +90,5 @@ bash scripts/migrate-project-template.sh --repo . --dry-run
 
 - 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/todo.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
+- `tasks/todos.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
 <!-- END ARCHITECTURE CONTRACT -->

package/CLAUDE.md

@@ -5,8 +5,8 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 ## Canonical Workflow Files
 
 - `tasks/current.md` for the tracked current-status snapshot derived from workflow artifacts
-- `tasks/todo.md` for deferred medium/long-term goals, not active execution checklists
-- `tasks/sprints/` for program-level sprint PRDs and ordered backlogs, operated by `scripts/sprint-backlog.sh` (Sprint = program layer; task contracts stay the execution slices)
+- `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)
 - `.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
@@ -24,7 +24,7 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 - Sync `tasks/` whenever substantive repo changes are made.
 - Use `tasks/notes/<plan-stem>.notes.md` only for non-obvious slice decisions, deviations, tradeoffs, and open questions; `<plan-stem>` is the active plan filename without `plan-` and `.md` (for example `20260531-0045-governance-workflow`). Do not use notes as durable memory or a task log, and archive/promote them deliberately when the slice closes.
 - Treat hook execution as central-first: trusted repos run `~/.repo-harness/hooks/` (bash shim) or the packaged CLI copy; this self-host repo pins `"hook_source": "repo"` in `.ai/harness/policy.json` so `.ai/hooks/` stays the live development runtime, with `assets/hooks/` as the product source mirrored on install. User-level `~/.claude/settings.json` and `~/.codex/hooks.json` are the host adapters.
-- Keep the umbrella hierarchy explicit: architecture owns stable truth, capability contracts own local agent context, `tasks/workstreams/<domain>/<capability>/` owns durable progress, and `tasks/todo.md` owns only deferred medium/long-term goals with tradeoff and revisit trigger.
+- Keep the umbrella hierarchy explicit: architecture owns stable truth, capability contracts own local agent context, `tasks/workstreams/<domain>/<capability>/` owns durable progress, and `tasks/todos.md` owns only deferred medium/long-term goals with tradeoff and revisit trigger.
 - Treat `.ai/context/capabilities.json` as the source of truth for capability prefixes; `agent-context-blocks.txt` and nested agent files are compatibility inputs only.
 - Keep architecture drift handling split: `architecture-queue.sh` writes architecture requests/events, `workstream-sync.sh` maintains durable capability workstreams, and `context-contract-sync.sh` only updates controlled local `CLAUDE.md`/`AGENTS.md` architecture blocks.
 - Keep `assets/workflow-contract.v1.json` and `.ai/harness/workflow-contract.json` in sync.
@@ -90,5 +90,5 @@ bash scripts/migrate-project-template.sh --repo . --dry-run
 
 - 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/todo.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
+- `tasks/todos.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
 <!-- END ARCHITECTURE CONTRACT -->

package/README.es.md

@@ -175,6 +175,26 @@ flowchart TD
   Cleanup --> Done["Tarea completada y auditable"]
 ```
 
+## Bucles largos de producto
+
+Para trabajo Greenfield y Brownfield, adelanta la discovery y el juicio de
+engineering plan en Claude-Fable antes de pedirle a Codex que haga loops de
+ejecución:
+
+1. En Claude-Fable, usa gstack `office-hours` para product discovery o
+   `plan-eng-review` para review del plan de ingeniería. La salida debe ser los
+   development documents que fijan la intención de producto, la arquitectura, los
+   riesgos y el evidence contract.
+2. Convierte esos documentos en un PRD Sprint bajo `plans/prds/`, con un
+   backlog ordenado y sub-plans detallados para cada execution slice.
+3. Crea un Codex Goal que apunte a ese archivo de sprint. repo-harness puede
+   entonces proyectar cada sprint item por el flow normal plan -> contract ->
+   worktree -> verification.
+
+Ese handoff mantiene precisos los loops largos: Claude-Fable se ocupa del juicio
+amplio al inicio, el PRD Sprint es la durable source of truth, y Codex Goal mode
+retoma contra un sprint concreto en vez de reinterpretar el chat original.
+
 ## Primeros 5 minutos
 
 Esta es la ruta más rápida para evaluar si un repositorio real es apto para
@@ -325,8 +345,8 @@ Guards habituales:
 
 ## Release actual
 
-- npm package: `repo-harness@0.4.0`
-- Generated workflow stamp: `repo-harness@0.4.0+template@0.4.0`
+- npm package: `repo-harness@0.4.1`
+- Generated workflow stamp: `repo-harness@0.4.1+template@0.4.1`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -349,6 +369,21 @@ Guards habituales:
   - `bash scripts/check-agent-tooling.sh --host both --check-updates`
   - no configura automáticamente gstack, gbrain, CodeGraph MCP, daemon ni provider
 
+## Agradecimientos
+
+Gracias a [Hylarucoder](https://x.com/hylarucoder) por su contribución
+metodológica. El método P1/P2/P3 due-diligence de `repo-harness`, y la práctica
+Geju que disciplina el planning, el trace y el decision rationale, vienen de su
+contribución e influencia.
+
+Gracias a [TW93](https://x.com/HiTw93), autor de Waza. Los skills centrales
+`think`, `hunt`, `check` y `health` dan forma al ritmo diario de planning, bug
+hunt y verification de `repo-harness`.
+
+Gracias a [Garry Tan](https://x.com/garrytan), autor de gstack y gbrain. Ambos
+influyeron en el workflow de product discovery, plan/design review, release
+documentation, knowledge sync y handoff retrieval.
+
 ## Action Command Skills
 
 Los command facades públicos están en `assets/skill-commands/`; preservan la

package/README.fr.md

@@ -179,6 +179,27 @@ flowchart TD
   Cleanup --> Done["Tâche terminée et auditable"]
 ```
 
+## Longues boucles produit
+
+Pour le travail Greenfield comme Brownfield, avancez la discovery et le jugement
+d'engineering plan dans Claude-Fable avant de demander à Codex de boucler sur
+l'exécution :
+
+1. Dans Claude-Fable, utilisez gstack `office-hours` pour la product discovery ou
+   `plan-eng-review` pour la review du plan d'ingénierie. La sortie doit être les
+   development documents qui verrouillent l'intention produit, l'architecture,
+   les risques et l'evidence contract.
+2. Transformez ces documents en PRD Sprint sous `plans/prds/`, avec un backlog
+   ordonné et des sub-plans détaillés pour chaque execution slice.
+3. Créez un Codex Goal qui pointe vers ce fichier de sprint. repo-harness peut
+   ensuite projeter chaque sprint item dans le flow normal plan -> contract ->
+   worktree -> verification.
+
+Ce handoff rend les longues boucles plus précises : Claude-Fable porte le
+jugement large en amont, le PRD Sprint devient la durable source of truth, et
+Codex Goal mode reprend sur un sprint concret au lieu de réinterpréter le chat
+initial.
+
 ## Les 5 premières minutes
 
 C'est le chemin le plus rapide pour évaluer si un dépôt réel se prête à l'adoption
@@ -329,8 +350,8 @@ Guards courants :
 
 ## Release actuelle
 
-- npm package : `repo-harness@0.4.0`
-- Generated workflow stamp : `repo-harness@0.4.0+template@0.4.0`
+- npm package : `repo-harness@0.4.1`
+- Generated workflow stamp : `repo-harness@0.4.1+template@0.4.1`
 - GitHub repository : `Ancienttwo/repo-harness`
 - Release history : [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -353,6 +374,21 @@ Guards courants :
   - `bash scripts/check-agent-tooling.sh --host both --check-updates`
   - pas de configuration automatique de gstack, gbrain, CodeGraph MCP, daemon ou provider
 
+## Remerciements
+
+Merci à [Hylarucoder](https://x.com/hylarucoder) pour sa contribution
+méthodologique. La méthode P1/P2/P3 due-diligence de `repo-harness`, ainsi que
+la pratique Geju qui structure le planning, le trace et le decision rationale,
+viennent de sa contribution et de son influence.
+
+Merci à [TW93](https://x.com/HiTw93), auteur de Waza. Les skills centraux
+`think`, `hunt`, `check` et `health` structurent le rythme quotidien de planning,
+bug hunt et verification de `repo-harness`.
+
+Merci à [Garry Tan](https://x.com/garrytan), auteur de gstack et gbrain. Ils ont
+influencé le workflow de product discovery, plan/design review, release
+documentation, knowledge sync et handoff retrieval.
+
 ## Action Command Skills
 
 Les command facades publics se trouvent dans `assets/skill-commands/` ; ils

package/README.ja.md

@@ -149,6 +149,25 @@ flowchart TD
   Cleanup --> Done["レビュー可能な完了タスク"]
 ```
 
+## 長期プロダクト Loop
+
+Greenfield と Brownfield の作業では、Codex に実行 loop を任せる前に、
+discovery と engineering-plan judgment を Claude-Fable 側で前倒しします。
+
+1. Claude-Fable で、product discovery には gstack `office-hours` を使い、
+   engineering plan review には `plan-eng-review` を使います。出力は、product
+   intent、architecture、risks、evidence contract を固定する development
+   documents にします。
+2. それらの documents を `plans/prds/` 配下の PRD Sprint に変換し、
+   各 execution slice に ordered backlog と detailed sub-plans を持たせます。
+3. Codex Goal を作成し、その sprint file を指します。repo-harness はその後、
+   各 sprint item を通常の plan -> contract -> worktree -> verification flow
+   へ投射できます。
+
+この handoff により、長期 loop は精密になります。Claude-Fable が広い前置判断を担い、
+PRD Sprint が durable source of truth となり、Codex Goal mode は元の chat を再解釈する
+のではなく、具体的な sprint に対して resume します。
+
 ## 最初の 5 分
 
 実際のリポジトリがこの workflow を導入するのに適しているかを評価する、最速の経路です。
@@ -293,8 +312,8 @@ hook がブロックしたときは、まず terminal の構造化された出
 
 ## 現在の Release
 
-- npm package：`repo-harness@0.4.0`
-- Generated workflow stamp：`repo-harness@0.4.0+template@0.4.0`
+- npm package：`repo-harness@0.4.1`
+- Generated workflow stamp：`repo-harness@0.4.1+template@0.4.1`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -317,6 +336,20 @@ hook がブロックしたときは、まず terminal の構造化された出
   - `bash scripts/check-agent-tooling.sh --host both --check-updates`
   - gstack、gbrain、CodeGraph MCP、daemon、provider を自動設定しない
 
+## 謝辞
+
+[Hylarucoder](https://x.com/hylarucoder) の方法論への貢献に感謝します。
+`repo-harness` の P1/P2/P3 due-diligence メソッドと、planning、trace、
+decision rationale を重視する Geju の実践は、彼の貢献と示唆に基づいています。
+
+[TW93](https://x.com/HiTw93) による Waza にも感謝します。`think`、`hunt`、
+`check`、`health` という中核 skill は、`repo-harness` の日々の planning、
+bug hunt、verification のリズムを形作っています。
+
+[Garry Tan](https://x.com/garrytan) による gstack と gbrain にも感謝します。
+これらは product discovery、plan/design review、release documentation、
+knowledge sync、handoff retrieval の workflow 設計に影響を与えています。
+
 ## Action Command Skills
 
 公開 command facades は `assets/skill-commands/` にあります。host skill discovery との互換性を残しつつ、実行は CLI と hooks が担います。

package/README.md

@@ -34,25 +34,21 @@ 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.0
-
-- **Loop-engine evidence surfaces.** `repo-harness-hook state-snapshot --json`,
-  the NL decision-table reference, route A/B evals, and the cutover gate make
-  prompt-routing experiments measurable while keeping the TypeScript classifier
-  authoritative until evidence says otherwise.
-- **Architecture queue gate.** `scripts/architecture-queue.sh`,
-  `scripts/check-architecture-sync.sh`, and the expanded architecture event
-  helper replace the retired append-only drift script with a derived request
-  index that can gate stale architecture state.
-- **Contract delegation pilot.** Contract templates now include
-  `budget`, `permission_scope`, and `roles`, and `scripts/contract-run.ts`
-  can run explicit worker/verifier child commands against contract exit
-  criteria.
-- **Heartbeat triage.** `scripts/heartbeat-triage.sh` records scheduled
-  workflow checks, sprint-next signals, and architecture request state into the
-  repo-local triage inbox.
-- **Workflow asset sync.** New helpers, docs, tests, and generated-repo assets
-  keep the self-host runtime and installed template copies aligned.
+## 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.
 
 ## What repo-harness Does
 
@@ -115,7 +111,7 @@ The diagram below assumes the harness is already installed in the repo. It shows
 the normal lifecycle from a program sprint backlog down to one contract task:
 draft or select the task, project it into execution files, check out the
 contract worktree when policy requires it, implement under hooks, verify, review,
-complete the sprint task when applicable, and close out. The 0.4.0 loop-system
+complete the sprint task when applicable, and close out. The 0.4.x loop-system
 surfaces add scheduled heartbeat discovery, state-snapshot/eval evidence for
 routing changes, architecture queue freshness, and optional contract-run
 delegation without changing the file-backed authority model.
@@ -123,7 +119,7 @@ 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/>tasks/sprints/*.sprint.md"]
+  Sprint -->|yes| SprintDoc["Sprint PRD + backlog<br/>plans/prds/*.prd.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
@@ -180,6 +176,26 @@ flowchart TD
   Cleanup --> Done["Reviewable completed task"]
 ```
 
+## Long-Running Product Loops
+
+For Greenfield and Brownfield work, front-load discovery and engineering-plan
+judgment in Claude-Fable before asking Codex to loop on execution:
+
+1. In Claude-Fable, use gstack `office-hours` for product discovery or
+   `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.
+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.
+
 ## First 5 Minutes
 
 This is the fastest path for an AI tooling owner evaluating whether the workflow is
@@ -209,11 +225,11 @@ 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.0` package keeps first-run
+The `0.4.1` package keeps first-run
 global bootstrap (`repo-harness init`) separate from repo-local refresh
-(`repo-harness update`) while adding the loop-engine state snapshot, architecture
-queue gate, contract delegation pilot, heartbeat triage helper, and generated
-asset sync for those workflow surfaces.
+(`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
@@ -364,8 +380,8 @@ Most common guards:
 
 ## Current Release
 
-- npm package: `repo-harness@0.4.0`
-- Generated workflow stamp: `repo-harness@0.4.0+template@0.4.0`
+- npm package: `repo-harness@0.4.1`
+- Generated workflow stamp: `repo-harness@0.4.1+template@0.4.1`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -408,27 +424,25 @@ Most common guards:
   - no automatic gstack, gbrain MCP, CodeGraph daemon, or provider setup
 - Manual distillation stays repo-local:
   - repeated corrections -> `tasks/lessons.md`
-  - deep findings and hidden contracts -> `tasks/research.md`
+  - deep findings and hidden contracts -> topic-scoped `docs/researches/*.md`
   - sprint verification evidence -> `tasks/reviews/*.review.md`
   - durable capability progress -> `tasks/workstreams/`
   - release history -> `docs/CHANGELOG.md`
 
-## Acknowledgements and Tooling Dependencies
+## Acknowledgements and Workflow Influences
 
 `repo-harness` is built around a small set of external skills and repos 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 all bundled product dependencies.
+are not ordinary bundled product dependencies.
 
 | Tool or repo | Used for | Dependency shape |
 | --- | --- | --- |
-| gstack skills, including `document-release`, `office-hours`, `plan-eng-review`, and `plan-design-review` | Product discovery, plan review, design review, and post-ship documentation hygiene | External operator workflow; advisory by default |
-| Waza core skills `think`, `hunt`, `check`, and `health` | Daily planning, bug hunts, verification, health checks, and Codex-first skill sync | Installed through the skills CLI into host skill roots |
+| [Hylarucoder](https://x.com/hylarucoder) / Geju | P1/P2/P3 due-diligence method and Geju practice that shaped the planning, tracing, and decision-rationale discipline in this workflow | Methodology contribution and acknowledgement; not a bundled dependency |
+| Waza by [TW93](https://x.com/HiTw93), including `think`, `hunt`, `check`, and `health` | Daily planning, bug hunts, verification, health checks, and Codex-first skill sync | Installed through the skills CLI into host skill roots |
+| 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 |
-| `gbrain` | Knowledge sync, handoff retrieval, and long-form repo memory | Optional external CLI and index |
 | 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 |
-| Bun | Source checkout execution, tests, template assembly, and release checks | Required local runtime for maintainers |
-| `commander` | `repo-harness` CLI command parsing | Runtime npm dependency |
 
 ## Action Command Skills
 
@@ -436,7 +450,7 @@ 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 `tasks/sprints/`, executed task-by-task through the contract flow)
+- Sprint program layer: `repo-harness-sprint` (PRD + ordered backlog in `plans/prds/`, executed task-by-task through 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`
 

package/README.zh-CN.md

@@ -23,21 +23,20 @@ repo-local workflow 的自托管样例。
   做渐进式上下文加载：一份小而稳定的 root context（约 12KB），加上只在改到对应文件时才加载的
   capability 块。agent 读一份 1KB 的 capability 合约或查索引，而不是花上千 token 重新摸清结构。
 
-## 0.4.0 新特性
-
-- **Loop-engine 证据面。** `repo-harness-hook state-snapshot --json`、NL
-  decision-table、route A/B eval 和 cutover gate 让 prompt-routing 实验可度量；
-  在证据达标前，TypeScript classifier 仍是权威路径。
-- **Architecture queue gate。** `scripts/architecture-queue.sh`、
-  `scripts/check-architecture-sync.sh` 和扩展后的 architecture event helper
-  取代已退休的 append-only drift 脚本，用派生 request index 检查 stale 架构状态。
-- **Contract delegation pilot。** Contract template 新增 `budget`、
-  `permission_scope`、`roles`，`scripts/contract-run.ts` 可用显式
-  worker/verifier child commands 按 contract exit criteria 执行试点。
-- **Heartbeat triage。** `scripts/heartbeat-triage.sh` 把定时 workflow checks、
-  sprint-next 信号和 architecture request 状态写入 repo-local triage inbox。
-- **Workflow asset sync。** 新 helpers、docs、tests 和 generated-repo assets
-  保持 self-host runtime 与安装模板副本同步。
+## 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 对齐。
 
 ## 产品做什么
 
@@ -86,14 +85,14 @@ classifier/state-machine 层不再散落在 shell 条件分支里。
 下面这张图假设目标仓库已经安装 harness。它展示的是从 program sprint backlog
 到单个 contract task 的正常闭环：先选择或形成任务，再投射到执行文件，需要时
 checkout 隔离 worktree，在 hooks 保护下实现，然后验证、review、external acceptance，
-必要时标记 sprint task 完成，最后 closeout。0.4.0 的 loop-system surface
+必要时标记 sprint task 完成，最后 closeout。0.4.x 的 loop-system surface
 新增 heartbeat 定时发现、state-snapshot/eval 证据、architecture queue freshness，
 以及可选的 contract-run 委派，但 source of truth 仍然是 repo 内文件合约。
 
 ```mermaid
 flowchart TD
   Program["Program goal 或 release theme"] --> Sprint{"需要 sprint layer?"}
-  Sprint -->|是| SprintDoc["Sprint PRD + backlog<br/>tasks/sprints/*.sprint.md"]
+  Sprint -->|是| SprintDoc["Sprint PRD + backlog<br/>plans/prds/*.prd.md"]
   SprintDoc --> NextTask["选择下一个 sprint task<br/>sprint-backlog.sh next"]
   Sprint -->|否| UserTask["用户任务或 planning prompt"]
   Heartbeat["Heartbeat triage<br/>scripts/heartbeat-triage.sh<br/>.ai/harness/triage/"] --> UserTask
@@ -150,6 +149,22 @@ flowchart TD
   Cleanup --> Done["可审查的已完成任务"]
 ```
 
+## 长周期产品 Loop
+
+Greenfield 和 Brownfield 工作先把 discovery 和工程计划前置在 Claude-Fable
+中完成，不要直接让 Codex 从原始聊天长期滚动：
+
+1. 在 Claude-Fable 里用 gstack `office-hours` 做产品 discovery，或用
+   `plan-eng-review` 做工程方案评审。输出应当是锁定产品意图、架构、风险和
+   evidence contract 的开发文档。
+2. 把这些文档转成 `plans/prds/` 下的 PRD Sprint，并为每个 execution
+   slice 写清有序 backlog 和详细 sub-plan。
+3. 创建 Codex Goal，目标指向该 sprint 文件。repo-harness 之后就可以按既有
+   plan -> contract -> worktree -> verification flow 逐项投射和执行。
+
+这个交接让长周期 loop 更精准：Claude-Fable 负责前置判断，PRD Sprint 是 durable
+source of truth，Codex Goal mode 只围绕具体 sprint 恢复和推进，而不是反复重新解释原始聊天。
+
 ## 前 5 分钟
 
 这是评估一个真实仓库是否适合接入该 workflow 的最快路径。
@@ -177,10 +192,10 @@ npx -y repo-harness update
 repo-local verification surfaces。
 
 npm package 和 generated workflow stamp 现在共用 `0.4.x` release line。
-`repo-harness@0.4.0` 继续把首次全局引导（`repo-harness init`）
-和 repo-local 刷新（`repo-harness update`）拆开，同时新增 loop-engine state
-snapshot、architecture queue gate、contract delegation pilot、heartbeat triage
-helper，以及这些 workflow surfaces 的 generated asset sync。
+`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 之上。
@@ -319,8 +334,8 @@ hook block 工作时，先看 terminal 里的结构化输出。核心字段是
 
 ## 当前 Release
 
-- npm package：`repo-harness@0.4.0`
-- Generated workflow stamp：`repo-harness@0.4.0+template@0.4.0`
+- npm package：`repo-harness@0.4.1`
+- Generated workflow stamp：`repo-harness@0.4.1+template@0.4.1`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -344,6 +359,20 @@ hook block 工作时，先看 terminal 里的结构化输出。核心字段是
   - `bash scripts/check-agent-tooling.sh --host both --check-updates`
   - 不自动设置 gstack、gbrain MCP、CodeGraph daemon 或 provider
 
+## 致谢
+
+感谢 [Hylarucoder](https://x.com/hylarucoder) 的方法论贡献。`repo-harness`
+里的 P1/P2/P3 due-diligence 方法，以及 Geju 实践对 planning、trace 和
+decision rationale 的要求，来自他的贡献与启发。
+
+感谢 [TW93](https://x.com/HiTw93) 创作 Waza；`think`、`hunt`、`check`
+和 `health` 这些核心 skill 构成了 `repo-harness` 的日常 planning、bug hunt
+和 verification 节奏。
+
+感谢 [Garry Tan](https://x.com/garrytan) 创作 gstack 和 gbrain；它们影响了
+product discovery、plan/design review、release 文档、knowledge sync 和
+handoff retrieval 的工作流设计。
+
 ## Action Command Skills
 
 公共 command facades 在 `assets/skill-commands/`；它们保留 host skill discovery

package/SKILL.md

@@ -287,8 +287,8 @@ Migration defaults:
 - archive uncertain legacy content instead of guessing
 - remove repo-local Skill Factory and auto-memory surfaces when present
 - archive legacy `docs/PROGRESS.md` content; do not regenerate it as a default workflow surface
-- keep `tasks/todo.md` limited to deferred medium/long-term goals, including the tradeoff and revisit trigger
-- move hidden contracts and deep findings into `tasks/research.md`
+- keep `tasks/todos.md` limited to deferred medium/long-term goals, including the tradeoff and revisit trigger
+- move hidden contracts and deep findings into topic-scoped `docs/researches/*.md`
 - distill repeated corrections into `tasks/lessons.md`
 - merge missing `external_tooling` defaults into `.ai/harness/policy.json` without overwriting explicit user values
 - keep gstack/gbrain/CodeGraph detection advisory-only; do not auto-install, auto-upgrade, auto-sync, or auto-enable MCP
@@ -304,15 +304,15 @@ Preserve these semantics:
 
 - `plans/` is the timestamped plan catalog; `.ai/harness/active-plan` selects the active plan, with `.claude/.active-plan` as a legacy fallback during transition
 - `plans/plan-*.md` must carry a workflow inventory before implementation: active plan, owning worktree, contract, review, notes, deferred ledger, checks, run snapshots, scope owner, switching rule, and worktree isolation path
-- `tasks/todo.md` is the deferred-goal ledger; active execution stays in the plan's `## Task Breakdown`
+- `tasks/todos.md` is the deferred-goal ledger; active execution stays in the plan's `## Task Breakdown`
 - `tasks/lessons.md` stores correction-derived rules
-- `tasks/research.md` stores deep repo findings and hidden contracts
+- `docs/researches/*.md` stores deep repo findings and hidden contracts by topic
 - `tasks/contracts/` and `tasks/reviews/` are completion gates
 - `tasks/contracts/*.contract.md` must repeat the workflow inventory and make `allowed_paths` the edit-scope authority
 - `tasks/workstreams/` stores durable capability progress
 - `docs/CHANGELOG.md` stores release history
-- `.ai/hooks/` is the shared hook source of truth
-- `.claude/settings.json` is the Claude adapter surface; `.codex/hooks.json` is the Codex adapter surface; repo-local `.claude/hooks/` is not generated by default
+- `assets/hooks/` is the installable hook product source; `.ai/hooks/` is a full live runtime only in repos that pin `"hook_source": "repo"`
+- user-level `~/.claude/settings.json` and `~/.codex/hooks.json` are the host adapter surfaces; repo-local `.claude/hooks/`, `.claude/settings.json`, and `.codex/hooks.json` are legacy cleanup targets
 
 ## Hook Workflow Protocol
 
@@ -322,28 +322,31 @@ automation, treat it as a runtime-harness slice, not a generic config edit.
 Map the route first:
 
 1. `assets/hooks/` is the installable source.
-2. `.ai/hooks/` is the repo-local implementation.
-3. `.claude/settings.json` and `.codex/hooks.json` are adapters that dispatch to
-   `.ai/hooks/run-hook.sh`.
-4. Codex also requires the repo hook to be trusted in Codex Settings before it
+2. The active runtime resolves central-first through `repo-harness-hook`; `.ai/hooks/`
+   is a full repo-local implementation only when `"hook_source": "repo"` is pinned.
+3. User-level `~/.claude/settings.json` and `~/.codex/hooks.json` are adapters
+   that dispatch to `repo-harness-hook` or the compatibility `repo-harness hook`
+   route.
+4. Codex also requires the user-level hook config to be trusted in Codex Settings before it
    executes.
-5. Generated `.claude/hooks/` shims are legacy cleanup targets; preserve only
-   user-authored `custom-*.sh` hooks.
+5. Generated `.claude/hooks/`, repo-local `.claude/settings.json`, and repo-local
+   `.codex/hooks.json` are legacy cleanup targets; preserve only user-authored
+   `custom-*.sh` hooks.
 
 Trace one real event before changing behavior, for example:
 
-`UserPromptSubmit -> adapter -> .ai/hooks/run-hook.sh -> prompt-guard.sh -> plan
+`UserPromptSubmit -> adapter -> repo-harness-hook -> prompt-guard.sh -> plan
 or advisory output`
 
 or:
 
-`PostToolUse(Edit|Write) -> adapter -> .ai/hooks/run-hook.sh ->
+`PostToolUse(Edit|Write) -> adapter -> repo-harness-hook ->
 post-edit-guard.sh -> architecture drift, brain sync, contract verification,
 task handoff`
 
-For Codex hook failures, debug in this order: `.codex/hooks.json`, Codex Settings
-trust, `.ai/hooks/run-hook.sh`, the target hook script, then `.ai/harness/events.jsonl`
-or `.claude/.trace.jsonl` evidence.
+For Codex hook failures, debug in this order: user-level `~/.codex/hooks.json`,
+Codex Settings trust, `repo-harness-hook` resolution, the active target hook
+script, then `.ai/harness/events.jsonl` or `.claude/.trace.jsonl` evidence.
 
 Hooks are accelerators and guards. They do not replace `plans/`, `tasks/`,
 contracts, reviews, policy, checks, or handoff artifacts. Heavy workflows such as
@@ -375,9 +378,9 @@ This skill may create or update:
 - `.claude/templates/*`
 - `docs/spec.md`
 - `docs/reference-configs/*.md`
-- `tasks/todo.md`
+- `tasks/todos.md`
 - `tasks/lessons.md`
-- `tasks/research.md`
+- `docs/researches/*`
 - `tasks/contracts/*`
 - `tasks/reviews/*`
 - `tasks/workstreams/*`

package/assets/AGENTS.md

@@ -64,5 +64,5 @@ Owns the workflow-engine-contract-assets capability boundary declared in .ai/con
 
 - Durable progress lives under `tasks/workstreams/workflow-engine/contract-assets`.
 - `tasks/current.md` is a tracked derived status snapshot, not a live lock or task source.
-- `tasks/todo.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
+- `tasks/todos.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
 <!-- END ARCHITECTURE CONTRACT -->

package/assets/CLAUDE.md

@@ -64,5 +64,5 @@ Owns the workflow-engine-contract-assets capability boundary declared in .ai/con
 
 - Durable progress lives under `tasks/workstreams/workflow-engine/contract-assets`.
 - `tasks/current.md` is a tracked derived status snapshot, not a live lock or task source.
-- `tasks/todo.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
+- `tasks/todos.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
 <!-- END ARCHITECTURE CONTRACT -->