repo-harness 0.2.4 → 0.4.0

package/AGENTS.md

@@ -1,15 +1,16 @@
 # repo-harness AGENTS.md
 
-This repository self-hosts the `repo-harness` contract, formerly `repo-harness-skill` and `project-initializer`. Claude and Codex should follow the same repo-local workflow surface.
+This repository self-hosts the `repo-harness` contract; the former `repo-harness-skill` and `project-initializer` names are retired and removed by installed-copy sync. Claude and Codex should follow the same repo-local workflow surface.
 
 ## 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)
 - `.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
@@ -22,14 +23,14 @@ This repository self-hosts the `repo-harness` contract, formerly `repo-harness-s
 
 - 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 `.ai/hooks/` as the shared repo-local hook implementation; user-level `~/.claude/settings.json` and `~/.codex/hooks.json` are the host adapters.
+- 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.
 - 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`.
@@ -49,6 +50,7 @@ This repository self-hosts the `repo-harness` contract, formerly `repo-harness-s
 ```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
@@ -78,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
 

package/CLAUDE.md

@@ -1,15 +1,16 @@
 # repo-harness AGENTS.md
 
-This repository self-hosts the `repo-harness` contract, formerly `repo-harness-skill` and `project-initializer`. Claude and Codex should follow the same repo-local workflow surface.
+This repository self-hosts the `repo-harness` contract; the former `repo-harness-skill` and `project-initializer` names are retired and removed by installed-copy sync. Claude and Codex should follow the same repo-local workflow surface.
 
 ## 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)
 - `.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
@@ -22,14 +23,14 @@ This repository self-hosts the `repo-harness` contract, formerly `repo-harness-s
 
 - 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 `.ai/hooks/` as the shared repo-local hook implementation; user-level `~/.claude/settings.json` and `~/.codex/hooks.json` are the host adapters.
+- 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.
 - 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`.
@@ -49,6 +50,7 @@ This repository self-hosts the `repo-harness` contract, formerly `repo-harness-s
 ```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
@@ -78,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
 

package/README.es.md

@@ -186,8 +186,8 @@ adoptar este workflow.
 npx -y repo-harness init
 ```
 
-La npm package release line es ahora `0.2.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`
@@ -204,14 +204,13 @@ bun src/cli/index.ts init
 Modelo de rutas locales:
 
 - Repositorio fuente: `~/Projects/repo-harness`
-- Claude skill aliases: `~/.claude/skills/repo-harness`, `~/.claude/skills/repo-harness-skill`
+- Claude skill alias: `~/.claude/skills/repo-harness`
 - Codex discoverable skill alias: `~/.codex/skills/repo-harness`
-- Codex compatibility fallback alias: `~/.codex/skills/repo-harness-skill`
 
 `~/Projects/repo-harness` es la única source of truth editable. Las rutas locales
 de Claude/Codex son runtime entrypoints respaldados por symlinks. Los directorios
-del runtime `project-initializer` ya retirado los limpia
-`scripts/sync-codex-installed-copies.sh`.
+de los runtimes ya retirados `repo-harness-skill` y `project-initializer` los
+elimina `scripts/sync-codex-installed-copies.sh`.
 
 ### Prerrequisitos mínimos
 
@@ -326,12 +325,12 @@ Guards habituales:
 
 ## Release actual
 
-- npm package: `repo-harness@0.2.4`
-- Generated workflow compatibility: `5.2.3`
+- npm package: `repo-harness@0.4.0`
+- Generated workflow stamp: `repo-harness@0.4.0+template@0.4.0`
 - 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.

package/README.fr.md

@@ -190,8 +190,8 @@ de ce workflow.
 npx -y repo-harness init
 ```
 
-La release line du package npm est désormais `0.2.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
@@ -208,14 +208,13 @@ bun src/cli/index.ts init
 Modèle de chemins locaux :
 
 - Dépôt source : `~/Projects/repo-harness`
-- Claude skill aliases : `~/.claude/skills/repo-harness`, `~/.claude/skills/repo-harness-skill`
+- Claude skill alias : `~/.claude/skills/repo-harness`
 - Codex discoverable skill alias : `~/.codex/skills/repo-harness`
-- Codex compatibility fallback alias : `~/.codex/skills/repo-harness-skill`
 
 `~/Projects/repo-harness` est l'unique source of truth éditable. Les chemins
 Claude/Codex locaux sont des runtime entrypoints adossés à des symlinks. Les
-répertoires du runtime `project-initializer` retiré sont nettoyés par
-`scripts/sync-codex-installed-copies.sh`.
+répertoires des runtimes retirés `repo-harness-skill` et `project-initializer`
+sont supprimés par `scripts/sync-codex-installed-copies.sh`.
 
 ### Prérequis minimaux
 
@@ -330,12 +329,12 @@ Guards courants :
 
 ## Release actuelle
 
-- npm package : `repo-harness@0.2.4`
-- Generated workflow compatibility : `5.2.3`
+- npm package : `repo-harness@0.4.0`
+- Generated workflow stamp : `repo-harness@0.4.0+template@0.4.0`
 - 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.

package/README.ja.md

@@ -159,8 +159,8 @@ flowchart TD
 npx -y repo-harness init
 ```
 
-npm package の release line は現在 `0.2.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 は使いません。
 
@@ -175,13 +175,13 @@ bun src/cli/index.ts init
 ローカルパスのモデル：
 
 - ソースリポジトリ：`~/Projects/repo-harness`
-- Claude skill aliases：`~/.claude/skills/repo-harness`、`~/.claude/skills/repo-harness-skill`
+- Claude skill alias：`~/.claude/skills/repo-harness`
 - Codex discoverable skill alias：`~/.codex/skills/repo-harness`
-- Codex compatibility fallback alias：`~/.codex/skills/repo-harness-skill`
 
 `~/Projects/repo-harness` が唯一の編集可能な source of truth です。ローカルの Claude/Codex パスは
-symlink に裏打ちされた runtime entrypoint です。退役した `project-initializer` runtime ディレクトリは
-`scripts/sync-codex-installed-copies.sh` によって整理されます。
+symlink に裏打ちされた runtime entrypoint です。退役した `repo-harness-skill` と
+`project-initializer` の runtime ディレクトリは
+`scripts/sync-codex-installed-copies.sh` によって削除されます。
 
 ### 最小の前提条件
 
@@ -293,12 +293,12 @@ hook がブロックしたときは、まず terminal の構造化された出
 
 ## 現在の Release
 
-- npm package：`repo-harness@0.2.4`
-- Generated workflow compatibility：`5.2.3`
+- npm package：`repo-harness@0.4.0`
+- Generated workflow stamp：`repo-harness@0.4.0+template@0.4.0`
 - 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)** は必要なときだけ現れます。

package/README.md

@@ -6,8 +6,8 @@
 
 Repo-local agentic development harness CLI and skill runtime for Claude/Codex
 workflows. The npm package and primary command are now `repo-harness`.
-`repo-harness-skill` remains a compatibility alias, while `project-initializer`
-install paths are retired and removed by installed-copy sync.
+The legacy `repo-harness-skill` and `project-initializer` install paths are
+retired and removed by installed-copy sync.
 Repository: `https://github.com/Ancienttwo/repo-harness`
 
 [English](README.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [Français](README.fr.md) | [Español](README.es.md)
@@ -34,30 +34,25 @@ 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.2.4
-
-- **Plan consultation stays advisory.** Questions and status reports that mention
-  plans, workflows, hooks, `new plan`, or `方案` no longer fall into
-  `PlanStatusGuard` or create plan files unless they explicitly start execution.
-- **Autoresearch is no longer a background hook.** The self-host-only
-  `autoresearch-advisory.sh` route is retired from `.ai/hooks`, generated hook
-  installers, and user-level adapters. Autoresearch evidence is now gathered by
-  an explicit agent-run workflow, not by an always-on hook.
-- **Hook parity is stricter.** Self-host `.ai/hooks/` and installable
-  `assets/hooks/` now match without maintainer-only hook exceptions.
-- **Copied hook fallback.** Installed prompt hooks now keep PlanCaptureGate
-  guidance working even when the copied runtime cannot reach the TypeScript
-  decision engine.
-- **Darwin readiness gates.** Workflow checks now catch stale handoff/resume
-  plan references, and public action-command skills have static quality gates
-  for failure modes, boundaries, and high-risk checkpoints.
-- **Authoritative eval evidence.** Benchmark reports now include
-  `full_test_count`, `dry_run_ratio`, `grader_pass_rate`, and
-  `effectiveness_authority`, so dry-run smoke output cannot be mistaken for
-  release-grade skill effectiveness proof.
-- **Tooling freshness.** The self-host CodeGraph dev dependency is refreshed to
-  `0.9.9`, and gbrain readiness probes try `doctor --json --fast` before the
-  full doctor path.
+## 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 repo-harness Does
 
@@ -87,19 +82,28 @@ The design has three layers:
    `.ai/harness/`, helper scripts, and `.ai/hooks/`.
 3. **Host adapters**: user-level `~/.claude/settings.json` and
    `~/.codex/hooks.json` route Claude/Codex events into `repo-harness-hook`.
-   The hook entrypoint exits silently for non-opt-in repos and dispatches into
-   the current repo's `.ai/hooks/*` scripts only when
-   `.ai/harness/workflow-contract.json` exists.
+   The hook entrypoint exits silently for non-opt-in repos. For opted-in repos,
+   it resolves hooks central-first through the packaged install or
+   `~/.repo-harness/hooks/`, with repo policy able to pin self-host development
+   back to `.ai/hooks/*`.
 
 For `UserPromptSubmit`, the public adapter contract stays
 `repo-harness-hook UserPromptSubmit --route default`. The CLI route registry
 dispatches that route to `.ai/hooks/prompt-guard.sh`. The shell hook remains the
 repo-local adapter for host JSON parsing, workflow file reads, capture side
-effects, quality gate rendering, and host-safe stdout/stderr. The prompt intent
-and workflow-state decision is handled by the TypeScript decision engine behind
-`repo-harness-hook prompt-guard-decide`, which returns one action enum from an
-explicit decision table. That split keeps host configuration stable while moving
-the brittle classifier/state-machine layer out of shell conditionals.
+effects, and host-safe stdout/stderr. It pipes the prompt text into
+`repo-harness-hook prompt-guard-decide`, where every prompt-text intent
+classifier (Unicode-aware, `src/cli/hook/prompt-intents.ts`) and the
+`intent x plan state` decision table live; the engine returns one verdict JSON
+line with the action, the classified intent facts, and derived strings. The
+shell keeps no duplicate classifier or fallback decision table — when the
+engine is unreachable the prompt layer degrades to a one-shot advisory.
+
+Prompt-layer plan/spec/contract gates are advisory routing. Hard enforcement
+lives at the edit boundary: `pre-edit-guard.sh` blocks implementation edits
+unless the active plan is Approved/Executing (policy
+`.guards.edit_plan_gate`: enforce | advice | off). Done-claim gates keep
+blocking because they verify file-backed completion evidence, not language.
 
 The core invariant is that durable truth lives in the repo, not in a chat
 thread. Hooks are accelerators and guardrails; the authority remains the
@@ -108,14 +112,26 @@ file-backed plan, contract, review, checks, and handoff artifacts.
 ## Task Workflow: Plan to Closeout
 
 The diagram below assumes the harness is already installed in the repo. It shows
-the normal task lifecycle: plan, project into a sprint contract, check out the
+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,
-and close out.
+complete the sprint task when applicable, and close out. The 0.4.0 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
-  UserTask["User task or planning prompt"] --> Discovery["Due diligence<br/>P1 map, P2 trace, P3 decision"]
-  Discovery --> PlanDraft["Draft plan<br/>plans/plan-*.md"]
+  Program["Program goal or release theme"] --> Sprint{"Sprint layer needed?"}
+  Sprint -->|yes| SprintDoc["Sprint PRD + backlog<br/>tasks/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
+  NextTask --> UserTask
+
+  UserTask --> Discovery["Due diligence<br/>P1 map, P2 trace, P3 decision"]
+  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
@@ -123,22 +139,28 @@ flowchart TD
 
   Approve --> Project["Project plan into execution<br/>capture-plan.sh --execute<br/>or plan-to-todo.sh --plan"]
   Project --> Active["Active markers<br/>.ai/harness/active-plan<br/>.ai/harness/active-worktree"]
+  Project --> SprintActive["Sprint projection<br/>active-sprint marker<br/>tasks/current.md"]
   Project --> Contract["Sprint contract<br/>tasks/contracts/YYYYMMDD-HHMM-task-slug.contract.md"]
   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"]
@@ -146,7 +168,10 @@ flowchart TD
   External --> DoneGate{"Contract, checks, review, and acceptance pass?"}
   DoneGate -->|no| Repair["Repair failing evidence or implementation"]
   Repair --> Implement
-  DoneGate -->|yes| Closeout["Closeout<br/>scripts/contract-worktree.sh finish"]
+  DoneGate -->|yes| SprintComplete{"Sprint task active?"}
+  SprintComplete -->|yes| MarkSprint["Mark backlog item complete<br/>sprint-backlog.sh complete-task"]
+  SprintComplete -->|no| Closeout["Closeout<br/>scripts/contract-worktree.sh finish"]
+  MarkSprint --> Closeout
 
   Closeout --> Commit["Commit contract branch"]
   Commit --> Merge["Fast-forward target branch"]
@@ -183,14 +208,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.2.x`; generated workflow compatibility is
-tracked separately as the `5.x` model line. The `0.2.4` package keeps first-run
+The npm package and generated workflow stamp now share the `0.4.x` release line.
+The `0.4.0` package keeps first-run
 global bootstrap (`repo-harness init`) separate from repo-local refresh
-(`repo-harness update`), preserves the typed global bootstrap and read-only
-config security sentinel, tightens hook parity, retires the self-host
-autoresearch advisory hook, prevents consultative plan/workflow prompts from
-being mistaken for execution, and adds copied-hook fallback, readiness checks,
-and skill-eval authority reporting.
+(`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.
 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
@@ -207,16 +230,14 @@ bun src/cli/index.ts update
 Local path model:
 
 - Source repo: `~/Projects/repo-harness`
-- Claude skill aliases: `~/.claude/skills/repo-harness`, `~/.claude/skills/repo-harness-skill`
+- Claude skill alias: `~/.claude/skills/repo-harness`
 - Codex discoverable skill alias: `~/.codex/skills/repo-harness`
-- Codex compatibility fallback alias: `~/.codex/skills/repo-harness-skill`
 
 The `~/Projects/repo-harness` repo is the only editable source of truth. Local
 Claude/Codex paths are symlink-backed runtime entrypoints. Only
 `~/.codex/skills/repo-harness` should expose `SKILL.md` and
-`assets/skill-commands/`; compatibility directories exist only so renamed
-repos can still resolve upstream assets without duplicate command discovery.
-The retired `project-initializer` directories under `~/.codex/skills` and
+`assets/skill-commands/`. The retired `repo-harness-skill` and
+`project-initializer` directories under `~/.codex/skills` and
 `~/.claude/skills` are deleted by `scripts/sync-codex-installed-copies.sh`.
 
 ### Minimum prerequisites
@@ -274,16 +295,29 @@ before applying anything.
 - Repo-local `.claude/settings.json` and `.codex/hooks.json` hook adapters are legacy project-level config and should be retired during migration.
 - Codex must mark `~/.codex/hooks.json` as trusted in Codex Settings before those hooks run.
 - Debug in this order: user-level adapter config -> `repo-harness-hook` (or fallback `repo-harness hook`) -> route registry -> `.ai/hooks/*`.
+- If `repo-harness-hook` reports `.ai/hooks` drift, refresh the repo-local copy with `repo-harness update --repo <root>`.
 
-`SessionStart` runs two ordered scripts before work begins:
+`SessionStart` resolves hooks central-first, then runs two ordered scripts before
+work begins:
 
 ```mermaid
 flowchart LR
-  SessionStart["Claude/Codex SessionStart"] --> Ctx["session-start-context.sh<br/>resume + handoff context"]
+  SessionStart["Claude/Codex SessionStart"] --> Adapter["user-level adapter"]
+  Adapter --> Entry["repo-harness-hook SessionStart --route default"]
+  Entry --> Source{"hook source"}
+  Source -->|central default| Central["packaged hooks<br/>or ~/.repo-harness/hooks"]
+  Source -->|repo policy pin| Repo["repo .ai/hooks<br/>self-host development"]
+  Central --> Ctx["session-start-context.sh<br/>resume + sprint + handoff context"]
+  Repo --> Ctx
   Ctx --> Sec["security-sentinel.sh<br/>read-only config scan, fingerprint-gated"]
   Sec --> SSOut["SessionStart additionalContext<br/>prior-session state + SecurityConfig findings"]
 ```
 
+`SessionStart` and `Stop` hooks are advisory for missing repo-local scripts: stale
+repos get a drift warning instead of a startup failure. Required guard routes,
+including edit and prompt gates, still fail closed when their scripts are
+missing.
+
 Prompt guard has one extra internal step:
 
 ```mermaid
@@ -292,15 +326,15 @@ flowchart LR
   Adapter --> CLI["repo-harness-hook UserPromptSubmit --route default"]
   CLI --> Route["route registry"]
   Route --> Shell[".ai/hooks/prompt-guard.sh"]
-  Shell --> Decision["repo-harness-hook prompt-guard-decide<br/>TypeScript decision table"]
-  Decision --> Action["single action enum"]
-  Action --> Shell
+  Shell -->|"stdin {prompt}"| Decision["repo-harness-hook prompt-guard-decide<br/>TypeScript classifiers + decision table"]
+  Decision -->|"verdict JSON<br/>action + intent facts + derived"| Shell
   Shell --> RouteHint["Waza route hint<br/>explicit think/planning matched first → /think"]
-  Shell --> HostOutput["host-safe allow, advice, block, or done gate output"]
+  Shell --> HostOutput["host-safe advice, done gate, or capture output"]
 ```
 
-The shell layer still owns filesystem authority and side effects. TypeScript owns
-only the classifier plus `intent x plan state` decision table.
+The shell layer owns filesystem authority and side effects. TypeScript owns all
+prompt-text classification plus the `intent x plan state` decision table.
+Plan-state blocks render at the PreToolUse edit layer, not here.
 
 ## Hook Failure Playbook
 
@@ -313,7 +347,7 @@ fields are `guard`, `reason`, `fix`, `failure_class`, and `run_id`.
 
 Most common guards:
 
-- `PlanStatusGuard`: no active plan, or the plan is not ready to execute
+- `PlanStatusGuard` (edit layer): an implementation edit was attempted with no active plan, or the plan is not ready to execute; the prompt layer emits the same guard name as advisory guidance
 - `ContractGuard`: approved execution has not yet produced the contract/review/notes scaffold
 - `ContractGuard`: completion was claimed before the task contract passed
 - `WorktreeGuard`: writes were attempted in the primary worktree while linked worktrees are enforced
@@ -330,12 +364,12 @@ Most common guards:
 
 ## Current Release
 
-- npm package: `repo-harness@0.2.4`
-- Generated workflow compatibility: `5.2.3`
+- npm package: `repo-harness@0.4.0`
+- Generated workflow stamp: `repo-harness@0.4.0+template@0.4.0`
 - 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,6 +436,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)
 - 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`
 
@@ -435,11 +470,9 @@ passes. These commands call existing repo-local helpers and keep their scope
 narrow instead of refreshing the full harness.
 
 Codex installed-copy rule: only `~/.codex/skills/repo-harness` exposes the root
-skill and `repo-harness-*` command facades. The compatibility directory
-`~/.codex/skills/repo-harness-skill` is a runtime fallback bundle only; it must
-not contain `SKILL.md` files or `assets/skill-commands/`. The retired
-`~/.codex/skills/project-initializer` and `~/.claude/skills/project-initializer`
-directories are removed during sync.
+skill and `repo-harness-*` command facades. The retired `repo-harness-skill`
+and `project-initializer` directories under `~/.codex/skills` and
+`~/.claude/skills` are removed during sync.
 
 After cloning or moving this source repo, rebuild the local runtime aliases with: