repo-harness 0.2.3 → 0.3.0

package/AGENTS.md

@@ -1,11 +1,12 @@
 # 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
@@ -22,7 +23,7 @@ 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.

package/CLAUDE.md

@@ -1,11 +1,12 @@
 # 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
@@ -22,7 +23,7 @@ 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.

package/README.es.md

@@ -186,7 +186,7 @@ adoptar este workflow.
 npx -y repo-harness init
 ```
 
-La npm package release line es ahora `0.2.x`; el workflow compatibility model line
+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
 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
@@ -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,7 +325,7 @@ Guards habituales:
 
 ## Release actual
 
-- npm package: `repo-harness@0.2.1`
+- npm package: `repo-harness@0.3.0`
 - Generated workflow compatibility: `5.2.3`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)

package/README.fr.md

@@ -190,7 +190,7 @@ de ce workflow.
 npx -y repo-harness init
 ```
 
-La release line du package npm est désormais `0.2.x` ; la generated workflow
+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`
 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
@@ -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,7 +329,7 @@ Guards courants :
 
 ## Release actuelle
 
-- npm package : `repo-harness@0.2.1`
+- npm package : `repo-harness@0.3.0`
 - Generated workflow compatibility : `5.2.3`
 - GitHub repository : `Ancienttwo/repo-harness`
 - Release history : [`docs/CHANGELOG.md`](docs/CHANGELOG.md)

package/README.ja.md

@@ -159,7 +159,7 @@ flowchart TD
 npx -y repo-harness init
 ```
 
-npm package の release line は現在 `0.2.x` です。生成される workflow compatibility model line は
+npm package の release line は現在 `0.3.x` です。生成される workflow compatibility model line は
 別途 `5.x` として追跡されます。`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,7 +293,7 @@ hook がブロックしたときは、まず terminal の構造化された出
 
 ## 現在の Release
 
-- npm package：`repo-harness@0.2.1`
+- npm package：`repo-harness@0.3.0`
 - Generated workflow compatibility：`5.2.3`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)

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,40 +34,28 @@ 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.3
-
-- **Safer global init defaults.** `repo-harness init` no longer calls the legacy
-  Claude plugin setup script or any Superpowers marketplace installer path.
-- **Global init command (`repo-harness init`).** One command installs the
-  `repo-harness` CLI globally, refreshes repo-harness skill aliases, installs
-  user-level Codex/Claude hook adapters, configures Waza
-  (`think`, `hunt`, `check`, `health`) plus Mermaid, persists the brain root, and
-  configures CodeGraph MCP.
-  Run `npx -y repo-harness init`; no source checkout is required.
-- **Repo refresh command (`repo-harness update`).** Existing-repo install and
-  refresh now has its own command surface, preserving the previous repo-local
-  harness migration path while keeping `init` focused on global runtime setup.
-- **CodeGraph index self-heal.** When the prompt hook detects structural
-  code-navigation intent and the repo has no `.codegraph` index, it initializes
-  the index with the local or PATH-visible CodeGraph binary before emitting the
-  route hint. This remains advisory: no dependency install, no heavy readiness
-  probe, and no prompt block if CodeGraph is unavailable.
-- **Security sentinel (`repo-harness security scan` + `security-sentinel.sh`).** A
-  read-only check over high-value config injection surfaces (`~/.claude/settings.json`,
-  `~/.codex/hooks.json`, repo-local `.vscode/tasks.json`, and legacy project-level
-  `.claude`/`.codex` adapters). It flags suspicious command patterns — remote-shell
-  pipes, base64-decode-to-exec, `osascript`, `launchctl`/`crontab` persistence, netcat,
-  inline interpreter exec — plus unmanaged hooks and auto-run `folderOpen` tasks, and it
-  never mutates config. The `SessionStart` sentinel fingerprints the set and re-scans
-  only when a fingerprint changes, so there is no session-start noise. Audit on demand:
-  `repo-harness security scan --json`.
-- **Claude/Codex draft-plan lifecycle.** Plan mode is explicitly two-stage: Draft vs
-  Approved. Hooks detect plan-creation intent and track pending orchestration; a stop gate
-  (`stop-orchestrator.sh`) requires one self-review pass before a session ends mid-plan.
-  Capture a draft with `scripts/capture-plan.sh --slug <slug> --title <title> --status
-  Draft`, then promote to Approved and project into execution with `--execute` or
-  `scripts/plan-to-todo.sh --plan <plan>`. Plans become the file-backed source of truth in
-  `plans/`.
+## 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 repo-harness Does
 
@@ -97,19 +85,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
@@ -118,13 +115,20 @@ 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.
 
 ```mermaid
 flowchart TD
-  UserTask["User task or planning prompt"] --> Discovery["Due diligence<br/>P1 map, P2 trace, P3 decision"]
+  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"]
+  NextTask --> UserTask
+
+  UserTask --> Discovery["Due diligence<br/>P1 map, P2 trace, P3 decision"]
   Discovery --> PlanDraft["Draft plan<br/>plans/plan-*.md"]
   PlanDraft --> PlanReview{"Plan ready for execution?"}
   PlanReview -->|no| Refine["Refine plan, scope, evidence contract"]
@@ -133,6 +137,7 @@ 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"]
@@ -156,7 +161,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"]
@@ -193,14 +201,13 @@ 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.3` package splits first-run
-global bootstrap (`repo-harness init`) from repo-local refresh
-(`repo-harness update`), replaces the legacy global plugin installer path with
-typed CLI/hook/dependency bootstrap, keeps the read-only config security sentinel
-(`repo-harness security scan`), the explicit Claude/Codex draft-plan lifecycle,
-and adds non-blocking CodeGraph index initialization for structural prompt
-routing.
+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
+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.
 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
@@ -217,16 +224,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
@@ -284,16 +289,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
@@ -302,15 +320,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
 
@@ -323,7 +341,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
@@ -340,7 +358,7 @@ Most common guards:
 
 ## Current Release
 
-- npm package: `repo-harness@0.2.3`
+- npm package: `repo-harness@0.3.0`
 - Generated workflow compatibility: `5.2.3`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
@@ -412,6 +430,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`
 
@@ -428,6 +447,12 @@ UI runtime, Bun/Hono gateway, shared contracts, observability, and MCP/HTTP
 sidecar rules without installing model providers or making Python, Go, Rust, or
 A2UI mandatory defaults.
 
+Webapp rendering is a separate overlay. Client-only Vite remains Plan B, while
+React webapps that need public SEO/SSR plus an authenticated workspace should
+use Plan C: one TanStack Start + Vite app deployed as a Cloudflare Worker under
+`apps/web`, with `/` SSR/prerender-capable and `/app` client-only. The scaffold
+does not default to separate `apps/marketing` and `apps/web` frontend deploys.
+
 Use `repo-harness-capability` when the harness already exists and only selected
 capability boundaries should be added. It updates `.ai/context/capabilities.json`,
 syncs the requested local `AGENTS.md` / `CLAUDE.md` contract files, and validates
@@ -439,11 +464,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:
 
@@ -480,6 +503,9 @@ bun scripts/assemble-template.ts --target agents --plan C --name "MyProject"
 bun run benchmark:skills --dry-run
 ```
 
+Dry-run benchmark output is a wiring smoke only. Release or readiness evidence
+needs a non-dry-run eval with grader output.
+
 ### Run one eval across both Claude and Codex
 
 ```bash
@@ -534,5 +560,5 @@ bash scripts/check-task-workflow.sh --strict
 bun scripts/inspect-project-state.ts --repo . --format text
 bash scripts/migrate-project-template.sh --repo . --dry-run
 bash scripts/check-agent-tooling.sh --host both --check-updates
-bun run benchmark:skills --dry-run
+bun run benchmark:skills --eval route-workflow-check
 ```