repo-harness 0.3.0 → 0.4.1

package/AGENTS.md

@@ -5,12 +5,12 @@ 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
-- `tasks/research.md` for deep repo knowledge
+- `docs/researches/` for deep repo knowledge
 - `tasks/notes/` for task-local implementation decisions, deviations, tradeoffs, and open questions
 - `plans/` for timestamped plans, with `plans/archive/` for history
 - `.ai/harness/workflow-contract.json` for the installed workflow contract manifest
@@ -24,13 +24,13 @@ 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-drift.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 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.
 - Keep `CLAUDE.md` and `AGENTS.md` short; put detailed guidance in `docs/reference-configs/`.
 - Treat Codex auto-compact as a fallback only; use `.ai/harness/handoff/current.md` and `.ai/harness/handoff/resume.md` for long-task rollover.
-- Treat `_ref/` as an occasional ignored external reference checkout cache, not a commit surface or daily workflow. Agents may read or refresh it for comparison; when it influences a decision, cite the source repo plus commit/tag and path in `tasks/notes/` or `tasks/research.md`.
+- Treat `_ref/` as an occasional ignored external reference checkout cache, not a commit surface or daily workflow. Agents may read or refresh it for comparison; when it influences a decision, cite the source repo plus commit/tag and path in `tasks/notes/` or `docs/researches/`.
 - Treat `deploy/` as the trackable deployment and operations surface for runbooks, submission materials, release checklists, helper scripts, ordered SQL files under `deploy/sql/`, and env examples.
 - Treat `_ops/` as ignored local operations state for secrets, real env files, provider state, artifacts, logs, and scratch files; do not commit or agent-edit `_ops/*`.
 - Treat contract-level task execution as worktree-first: `scripts/plan-to-todo.sh --plan <approved-plan>` starts `scripts/contract-worktree.sh start --plan <approved-plan>` when policy enables it, and completed blocks finish through Waza `/check` plus `scripts/contract-worktree.sh finish`.
@@ -50,6 +50,7 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 ```bash
 bun test
 bash scripts/check-deploy-sql-order.sh
+bash scripts/check-architecture-sync.sh
 bash scripts/check-task-sync.sh
 bash scripts/check-task-workflow.sh --strict
 bun scripts/inspect-project-state.ts --repo . --format text
@@ -79,7 +80,7 @@ bash scripts/migrate-project-template.sh --repo . --dry-run
 - Latest snapshot: `(none yet)`
 - Semantic diagram source: `docs/architecture/modules/runtime-harness/hook-adapters.md`
 - Latest human diagram: `(none yet)`
-- Pending architecture request: `docs/architecture/requests/20260529-094446-ai-hooks-ai-hooks-session-start-context-sh.md`
+- Pending architecture request: `(none)`
 
 ## Active Workstreams
 
@@ -89,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,12 +5,12 @@ 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
-- `tasks/research.md` for deep repo knowledge
+- `docs/researches/` for deep repo knowledge
 - `tasks/notes/` for task-local implementation decisions, deviations, tradeoffs, and open questions
 - `plans/` for timestamped plans, with `plans/archive/` for history
 - `.ai/harness/workflow-contract.json` for the installed workflow contract manifest
@@ -24,13 +24,13 @@ 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-drift.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 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.
 - Keep `CLAUDE.md` and `AGENTS.md` short; put detailed guidance in `docs/reference-configs/`.
 - Treat Codex auto-compact as a fallback only; use `.ai/harness/handoff/current.md` and `.ai/harness/handoff/resume.md` for long-task rollover.
-- Treat `_ref/` as an occasional ignored external reference checkout cache, not a commit surface or daily workflow. Agents may read or refresh it for comparison; when it influences a decision, cite the source repo plus commit/tag and path in `tasks/notes/` or `tasks/research.md`.
+- Treat `_ref/` as an occasional ignored external reference checkout cache, not a commit surface or daily workflow. Agents may read or refresh it for comparison; when it influences a decision, cite the source repo plus commit/tag and path in `tasks/notes/` or `docs/researches/`.
 - Treat `deploy/` as the trackable deployment and operations surface for runbooks, submission materials, release checklists, helper scripts, ordered SQL files under `deploy/sql/`, and env examples.
 - Treat `_ops/` as ignored local operations state for secrets, real env files, provider state, artifacts, logs, and scratch files; do not commit or agent-edit `_ops/*`.
 - Treat contract-level task execution as worktree-first: `scripts/plan-to-todo.sh --plan <approved-plan>` starts `scripts/contract-worktree.sh start --plan <approved-plan>` when policy enables it, and completed blocks finish through Waza `/check` plus `scripts/contract-worktree.sh finish`.
@@ -50,6 +50,7 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 ```bash
 bun test
 bash scripts/check-deploy-sql-order.sh
+bash scripts/check-architecture-sync.sh
 bash scripts/check-task-sync.sh
 bash scripts/check-task-workflow.sh --strict
 bun scripts/inspect-project-state.ts --repo . --format text
@@ -79,7 +80,7 @@ bash scripts/migrate-project-template.sh --repo . --dry-run
 - Latest snapshot: `(none yet)`
 - Semantic diagram source: `docs/architecture/modules/runtime-harness/hook-adapters.md`
 - Latest human diagram: `(none yet)`
-- Pending architecture request: `docs/architecture/requests/20260529-094446-ai-hooks-ai-hooks-session-start-context-sh.md`
+- Pending architecture request: `(none)`
 
 ## Active Workstreams
 
@@ -89,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
@@ -186,8 +206,8 @@ adoptar este workflow.
 npx -y repo-harness init
 ```
 
-La npm package release line es ahora `0.3.x`; el workflow compatibility model line
-generado se rastrea por separado como `5.x`. `repo-harness init` es el bootstrap
+La npm package release line y el generated workflow stamp usan ahora la misma
+línea `0.4.x`. `repo-harness init` es el bootstrap
 global y `repo-harness update` es el refresco repo-local. `repo-harness init`
 configura el CLI, los hook adapters de nivel usuario, Waza, Mermaid, el brain
 root y CodeGraph MCP; el viejo camino Claude plugin `scripts/setup-plugins.sh`
@@ -325,12 +345,12 @@ Guards habituales:
 
 ## Release actual
 
-- npm package: `repo-harness@0.3.0`
-- Generated workflow compatibility: `5.2.3`
+- 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)
 
-## Current Model (5.2.3)
+## Current Model
 
 - El question flow usa **12 grouped decision points**, infiriendo primero los harness defaults.
 - El plan menu está por capas: los **Core Plans (A-F)** primero, los **Custom Presets (G-K)** solo cuando hace falta.
@@ -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
@@ -190,8 +211,8 @@ de ce workflow.
 npx -y repo-harness init
 ```
 
-La release line du package npm est désormais `0.3.x` ; la generated workflow
-compatibility model line est suivie séparément en `5.x`. `repo-harness init`
+La release line du package npm et le generated workflow stamp utilisent
+désormais la même ligne `0.4.x`. `repo-harness init`
 sert au bootstrap global et `repo-harness update` sert au rafraîchissement
 repo-local. `repo-harness init` configure le CLI, les hook adapters de niveau
 utilisateur, Waza, Mermaid, le brain root et CodeGraph MCP ; l'ancien chemin
@@ -329,12 +350,12 @@ Guards courants :
 
 ## Release actuelle
 
-- npm package : `repo-harness@0.3.0`
-- Generated workflow compatibility : `5.2.3`
+- 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)
 
-## Current Model (5.2.3)
+## Current Model
 
 - Le question flow utilise **12 grouped decision points**, en inférant d'abord les harness defaults.
 - Le plan menu est hiérarchisé : **Core Plans (A-F)** en priorité, **Custom Presets (G-K)** uniquement quand c'est nécessaire.
@@ -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 を導入するのに適しているかを評価する、最速の経路です。
@@ -159,8 +178,8 @@ flowchart TD
 npx -y repo-harness init
 ```
 
-npm package の release line は現在 `0.3.x` です。生成される workflow compatibility model line は
-別途 `5.x` として追跡されます。`repo-harness init` は global bootstrap、`repo-harness update` は
+npm package と generated workflow stamp は現在同じ `0.4.x` release line を使います。
+`repo-harness init` は global bootstrap、`repo-harness update` は
 repo-local refresh です。`repo-harness init` は CLI、user-level hook adapters、Waza、Mermaid、
 brain root、CodeGraph MCP を設定し、退役した `scripts/setup-plugins.sh` の Claude plugin path は使いません。
 
@@ -293,12 +312,12 @@ hook がブロックしたときは、まず terminal の構造化された出
 
 ## 現在の Release
 
-- npm package：`repo-harness@0.3.0`
-- Generated workflow compatibility：`5.2.3`
+- 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)
 
-## Current Model (5.2.3)
+## Current Model
 
 - Question flow は **12 grouped decision points** を使い、まず harness defaults を推論します。
 - Plan menu は階層化されています。**Core Plans (A-F)** を優先し、**Custom Presets (G-K)** は必要なときだけ現れます。
@@ -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,28 +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.3.0
-
-- **Sprint program layer.** `repo-harness-sprint`, `tasks/sprints/`, sprint
-  templates, active sprint markers, and `scripts/sprint-backlog.sh` now capture
-  program-level PRDs and ordered backlogs without turning `tasks/todo.md` into
-  an active execution checklist.
-- **Central-first hook runtime.** User-level Claude/Codex adapters dispatch into
-  `repo-harness-hook`; central packaged hooks are the default runtime, while
-  this self-host repo can still pin `"hook_source": "repo"` for live hook
-  development.
-- **Prompt decisions moved to TypeScript.** Prompt-text intent classification is
-  Unicode-aware in `src/cli/hook/prompt-intents.ts`, the shell hook receives one
-  verdict JSON line, and prompt-layer plan/spec/contract gates are advisory.
-- **Edit-layer enforcement.** Implementation writes are enforced at
-  `pre-edit-guard.sh`, where the guard can key off path, active plan state, and
-  repo files instead of natural-language guesses.
-- **Cheaper always-on hooks.** `trace-event.sh` and `context-pressure-hook.sh`
-  are merged into `post-tool-observer.sh`: one dispatch, one stdin parse, one
-  trace file, and sampled context-budget probes.
-- **Legacy surface cleanup.** The retired `repo-harness-skill`,
-  `project-initializer`, `PROJECT_INITIALIZER_*` fallbacks, duplicate shell
-  classifier table, orphan version checker, and split observer hooks are gone.
+## 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
 
@@ -118,18 +111,23 @@ 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.
+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.
 
 ```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
   NextTask --> UserTask
 
   UserTask --> Discovery["Due diligence<br/>P1 map, P2 trace, P3 decision"]
-  Discovery --> PlanDraft["Draft plan<br/>plans/plan-*.md"]
+  Discovery --> LoopEvidence["Loop evidence when routing changes<br/>state-snapshot --json<br/>route-nl-vs-ts / cutover gate"]
+  LoopEvidence --> PlanDraft["Draft plan<br/>plans/plan-*.md"]
   PlanDraft --> PlanReview{"Plan ready for execution?"}
   PlanReview -->|no| Refine["Refine plan, scope, evidence contract"]
   Refine --> PlanDraft
@@ -142,18 +140,23 @@ flowchart TD
   Project --> ReviewFile["Review file<br/>tasks/reviews/YYYYMMDD-HHMM-task-slug.review.md"]
   Project --> Notes["Task notes<br/>tasks/notes/YYYYMMDD-HHMM-task-slug.notes.md"]
 
-  Contract --> WorktreePolicy{"Contract worktree required?"}
+  Contract --> Delegation["Delegation contract<br/>budget / permission_scope / roles"]
+  Delegation --> Delegate{"Use contract-run delegation?"}
+  Delegate -->|yes| ContractRun["Worker/verifier child run<br/>scripts/contract-run.ts"]
+  Delegate -->|no| WorktreePolicy{"Contract worktree required?"}
   WorktreePolicy -->|yes| Checkout["Checkout isolated worktree<br/>contract-worktree.sh start --plan<br/>branch codex/task-slug"]
   WorktreePolicy -->|no| CurrentTree["Use current worktree<br/>small or explicitly allowed slice"]
   Checkout --> Implement
   CurrentTree --> Implement
+  ContractRun --> Changes
 
   Implement["Edit and run commands"] --> PreHooks["Pre-edit guards<br/>PlanStatusGuard, ContractScopeGuard, WorktreeGuard"]
   PreHooks -->|blocked| ScopeFix["Fix plan, contract, worktree, or scope"]
   ScopeFix --> Implement
   PreHooks -->|allowed| Changes["Code, docs, tests, or config changes"]
   Changes --> PostHooks["Post-edit and post-bash hooks<br/>trace, drift request, handoff, check evidence"]
-  PostHooks --> Verify["Run verification<br/>tests plus repo workflow checks"]
+  PostHooks --> ArchQueue["Architecture queue<br/>architecture-queue.sh record/reindex<br/>check-architecture-sync.sh"]
+  ArchQueue --> Verify["Run verification<br/>tests plus repo workflow checks"]
 
   Verify --> Checks["Structured evidence<br/>.ai/harness/checks/latest.json<br/>.ai/harness/runs/*.json"]
   Checks --> CheckReview["Evaluator review<br/>Waza /check -> review file"]
@@ -173,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
@@ -201,13 +224,12 @@ npx -y repo-harness update
 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 release line is now `0.3.x`; generated workflow compatibility is
-tracked separately as the `5.x` model line. The `0.3.0` package keeps first-run
+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`), adds the sprint program layer, moves hook execution to
-central-first runtime resolution, moves prompt decisions into TypeScript,
-enforces implementation writes at the edit boundary, and merges always-on hook
-observers into one cheaper path.
+(`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
@@ -358,12 +380,12 @@ Most common guards:
 
 ## Current Release
 
-- npm package: `repo-harness@0.3.0`
-- Generated workflow compatibility: `5.2.3`
+- 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)
 
-## Current Model (5.2.3)
+## Current Model
 
 - Question flow uses **12 grouped decision points** with harness defaults inferred first.
 - Plan menu is tiered:
@@ -402,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
 
@@ -430,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`