repo-harness 0.4.0 → 0.4.2

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 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
@@ -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 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
@@ -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.2`
+- Generated workflow stamp: `repo-harness@0.4.2+template@0.4.2`
 - 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.2`
+- Generated workflow stamp : `repo-harness@0.4.2+template@0.4.2`
 - 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.2`
+- Generated workflow stamp：`repo-harness@0.4.2+template@0.4.2`
 - 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,20 @@ 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.2
+
+- **PRD-to-Sprint planning hierarchy.** `repo-harness-prd` now owns
+  upper-layer product requirements under `plans/prds/`, while
+  `repo-harness-sprint` derives ordered execution backlogs under
+  `plans/sprints/*.sprint.md`.
+- **Generated helper runtime isolation.** Downstream installs place real helper
+  implementations under `.ai/harness/scripts/` and keep root `scripts/*` as
+  compatibility wrappers; this self-host repo remains the source runtime.
+- **Subagent return-channel guard.** Managed hook routes include a guard that
+  keeps delegated runs reporting back through the parent session instead of
+  bypassing the file-backed contract.
+- **Release path alignment.** PRD/Sprint eval fixtures, workflow checks, and
+  command guidance now point at the same installed helper runtime.
 
 ## What repo-harness Does
 
@@ -115,7 +110,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 +118,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/>tasks/sprints/*.sprint.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
@@ -180,6 +176,27 @@ 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 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 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
@@ -209,11 +226,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.2` 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 adding the PRD-to-Sprint planning hierarchy,
+isolated generated-project helper runtime, subagent return-channel guard, and
+release-path alignment 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
@@ -273,7 +290,7 @@ 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
@@ -364,8 +381,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.2`
+- Generated workflow stamp: `repo-harness@0.4.2+template@0.4.2`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -408,27 +425,40 @@ 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
+`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 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 |
+| 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
 
@@ -436,7 +466,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 `tasks/sprints/`, 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`
 

package/README.zh-CN.md

@@ -23,21 +23,19 @@ 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.2 新特性
+
+- **PRD-to-Sprint planning hierarchy。** `repo-harness-prd` 负责
+  `plans/prds/` 下的上层产品需求，`repo-harness-sprint` 负责把 PRD 或明确
+  slice 推成 `plans/sprints/*.sprint.md` 下的有序执行 backlog。
+- **Generated helper runtime isolation。** 下游安装把真实 helper 实现放到
+  `.ai/harness/scripts/`，root `scripts/*` 只保留 compatibility wrappers；
+  自托管源码仓库继续以 root `scripts/` 作为 source runtime。
+- **Subagent return-channel guard。** Managed hook routes 增加 return-channel
+  guard，要求 delegated runs 回到 parent session 汇报，避免绕过 file-backed
+  contract。
+- **Release path alignment。** PRD/Sprint eval fixtures、workflow checks 和
+  command guidance 现在都指向同一个 installed helper runtime。
 
 ## 产品做什么
 
@@ -86,14 +84,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 +148,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 +191,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.2` 继续把首次全局引导（`repo-harness init`）
+和 repo-local 刷新（`repo-harness update`）拆开，并在 `0.4.0` loop-engine
+surfaces 之上加入 PRD-to-Sprint planning hierarchy、isolated generated-project
+helper runtime、subagent return-channel guard 和 release-path alignment。
 这些能力叠加在改名后的 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 +333,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.2`
+- Generated workflow stamp：`repo-harness@0.4.2+template@0.4.2`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -344,6 +358,30 @@ 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 的工作流设计。
+
+感谢 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