repo-harness 0.2.4 → 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.4`
+- 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.4`
+- 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.4`
+- 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,30 +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.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.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
 
@@ -87,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
@@ -108,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"]
@@ -123,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"]
@@ -146,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"]
@@ -183,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.4` package keeps first-run
+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`), 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`), 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
@@ -207,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
@@ -274,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
@@ -292,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
 
@@ -313,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
@@ -330,7 +358,7 @@ Most common guards:
 
 ## Current Release
 
-- npm package: `repo-harness@0.2.4`
+- 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)
@@ -402,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`
 
@@ -435,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:
 

package/README.zh-CN.md

@@ -23,25 +23,25 @@ repo-local workflow 的自托管样例。
   做渐进式上下文加载：一份小而稳定的 root context（约 12KB），加上只在改到对应文件时才加载的
   capability 块。agent 读一份 1KB 的 capability 合约或查索引，而不是花上千 token 重新摸清结构。
 
-## 0.2.4 新特性
-
-- **计划咨询保持 advisory。** 提到 plans、workflow、hooks、`new plan` 或 `方案` 的问题和状态报告，
-  不再因为包含执行相关词就进入 `PlanStatusGuard` 或创建 plan 文件；只有明确开始执行时才触发执行门。
-- **Autoresearch 不再是后台 hook。** 自托管专用的 `autoresearch-advisory.sh` route 已从
-  `.ai/hooks`、生成的 hook installer 和 user-level adapters 里退休。需要 autoresearch 证据时，
-  由 agent 显式运行实验流程，而不是靠常驻 hook 提示。
-- **Hook parity 更严格。** 自托管 `.ai/hooks/` 和可安装的 `assets/hooks/` 现在必须完全一致，
-  不再保留 maintainer-only hook exception。
-- **复制版 hook fallback。** 已安装的 prompt hook 即使找不到 TypeScript decision
-  engine，也会保留 PlanCaptureGate guidance，而不是直接报 engine unavailable。
-- **Darwin readiness gates。** Workflow checks 现在会抓 stale handoff/resume plan
-  references；公共 action-command skills 也增加 failure modes、boundaries 和高风险
-  checkpoint 的静态质量门。
-- **权威 eval evidence。** Benchmark report 现在输出 `full_test_count`、
-  `dry_run_ratio`、`grader_pass_rate` 和 `effectiveness_authority`，避免把 dry-run
-  smoke 当成 release-grade skill effectiveness 证明。
-- **Tooling freshness。** self-host CodeGraph dev dependency 刷到 `0.9.9`，gbrain
-  readiness 会先尝试 `doctor --json --fast`，再 fallback 到完整 doctor。
+## 0.3.0 新特性
+
+- **Sprint program layer。** `repo-harness-sprint`、`tasks/sprints/`、sprint
+  template、active sprint marker 和 `scripts/sprint-backlog.sh` 现在承接 program
+  PRD 与有序 backlog，不再把 `tasks/todo.md` 当成活跃执行 checklist。
+- **Central-first hook runtime。** User-level Claude/Codex adapters 进入
+  `repo-harness-hook`；默认跑 central packaged hooks，本仓库自托管开发时仍可通过
+  `"hook_source": "repo"` 钉回 repo 内 `.ai/hooks`。
+- **Prompt decision 进入 TypeScript。** Prompt-text intent classifier 在
+  `src/cli/hook/prompt-intents.ts` 里处理 Unicode，shell hook 只接收一行 verdict
+  JSON，prompt 层的 plan/spec/contract gate 退为 advisory。
+- **Edit-layer enforcement。** 真正的实现写入由 `pre-edit-guard.sh` 拦截，依据路径、
+  active plan state 和仓库文件判断，不再靠自然语言猜测。
+- **Always-on hooks 更轻。** `trace-event.sh` 与 `context-pressure-hook.sh` 合并为
+  `post-tool-observer.sh`：一次 dispatch、一次 stdin parse、一份 trace 文件，并抽样跑
+  context-budget probes。
+- **Legacy surface 清理。** 已退休的 `repo-harness-skill`、`project-initializer`、
+  `PROJECT_INITIALIZER_*` fallbacks、重复 shell classifier table、孤立 version checker
+  和拆分 observer hooks 都已移除。
 
 ## 产品做什么
 
@@ -69,8 +69,9 @@ repo-local hooks，然后验证这些 workflow surfaces 仍然一致。
    `.ai/hooks/`。
 3. **Host adapter 层**：user-level `~/.claude/settings.json` 和 `~/.codex/hooks.json`
    把 Claude/Codex events 路由到 `repo-harness-hook`。hook entrypoint 会先检查当前
-   repo 是否存在 `.ai/harness/workflow-contract.json`；没有 opt in 就静默退出，有 opt in
-   才进入当前仓库的 `.ai/hooks/*`。
+   repo 是否存在 `.ai/harness/workflow-contract.json`；没有 opt in 就静默退出。有 opt in
+   时按 central-first 解析 packaged install 或 `~/.repo-harness/hooks/`，repo policy
+   也可以把自托管开发钉回 `.ai/hooks/*`。
 
 对 `UserPromptSubmit` 来说，公开 adapter contract 仍然是
 `repo-harness-hook UserPromptSubmit --route default`。CLI route registry 会把这个
@@ -86,13 +87,20 @@ classifier/state-machine 层不再散落在 shell 条件分支里。
 
 ## 任务 Workflow：从 Plan 到 Closeout
 
-下面这张图假设目标仓库已经安装 harness。它展示的是单个任务的正常闭环：
-先形成 plan，再投射到 sprint contract，需要时 checkout 隔离 worktree，在 hooks 保护下实现，
-然后验证、review、external acceptance，最后 closeout。
+下面这张图假设目标仓库已经安装 harness。它展示的是从 program sprint backlog
+到单个 contract task 的正常闭环：先选择或形成任务，再投射到执行文件，需要时
+checkout 隔离 worktree，在 hooks 保护下实现，然后验证、review、external acceptance，
+必要时标记 sprint task 完成，最后 closeout。
 
 ```mermaid
 flowchart TD
-  UserTask["用户任务或 planning prompt"] --> Discovery["前置调查<br/>P1 map, P2 trace, P3 decision"]
+  Program["Program goal 或 release theme"] --> Sprint{"需要 sprint layer?"}
+  Sprint -->|是| SprintDoc["Sprint PRD + backlog<br/>tasks/sprints/*.sprint.md"]
+  SprintDoc --> NextTask["选择下一个 sprint task<br/>sprint-backlog.sh next"]
+  Sprint -->|否| UserTask["用户任务或 planning prompt"]
+  NextTask --> UserTask
+
+  UserTask --> Discovery["前置调查<br/>P1 map, P2 trace, P3 decision"]
   Discovery --> PlanDraft["Draft plan<br/>plans/plan-*.md"]
   PlanDraft --> PlanReview{"Plan 是否可执行?"}
   PlanReview -->|否| Refine["收敛 scope 和 evidence contract"]
@@ -101,6 +109,7 @@ flowchart TD
 
   Approve --> Project["投射到执行面<br/>capture-plan.sh --execute<br/>或 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"]
@@ -124,7 +133,10 @@ flowchart TD
   External --> DoneGate{"Contract、checks、review、acceptance 是否通过?"}
   DoneGate -->|否| Repair["修复失败 evidence 或实现"]
   Repair --> Implement
-  DoneGate -->|是| Closeout["Closeout<br/>scripts/contract-worktree.sh finish"]
+  DoneGate -->|是| SprintComplete{"存在 active sprint task?"}
+  SprintComplete -->|是| MarkSprint["标记 backlog item 完成<br/>sprint-backlog.sh complete-task"]
+  SprintComplete -->|否| Closeout["Closeout<br/>scripts/contract-worktree.sh finish"]
+  MarkSprint --> Closeout
 
   Closeout --> Commit["提交 contract branch"]
   Commit --> Merge["Fast-forward target branch"]
@@ -159,12 +171,11 @@ npx -y repo-harness update
 安装或刷新 workflow files、hook assets、host adapters、skill aliases 和
 repo-local verification surfaces。
 
-npm package release line 现在是 `0.2.x`；生成的 workflow compatibility model line
-单独以 `5.x` 追踪。`repo-harness@0.2.4` 继续把首次全局引导（`repo-harness init`）
-和 repo-local 刷新（`repo-harness update`）拆开，保留 typed global bootstrap 与只读
-配置安全哨兵，同时收紧 hook parity，退休自托管 autoresearch advisory hook，避免
-计划/工作流咨询 prompt 被误判成执行请求，并增加复制版 hook fallback、readiness checks
-和 skill-eval authority reporting。
+npm package release line 现在是 `0.3.x`；生成的 workflow compatibility model line
+单独以 `5.x` 追踪。`repo-harness@0.3.0` 继续把首次全局引导（`repo-harness init`）
+和 repo-local 刷新（`repo-harness update`）拆开，新增 sprint program layer，把 hook
+执行切到 central-first runtime resolution，把 prompt decision 移进 TypeScript，在
+edit boundary 执行实现写入门，并把 always-on hook observers 合并为更轻的一条路径。
 这些能力叠加在改名后的 CLI、user-level hook adapter bootstrap、AI-native scaffold overlays、
 typed prompt-guard decision engine、plan-stem task artifact 命名、`REPO_HARNESS_*`
 runtime aliases、Waza runtime skill sync，以及 maintainer 发布 npm 前使用的 release gate 之上。
@@ -180,12 +191,12 @@ bun src/cli/index.ts update
 本地路径模型：
 
 - 源码仓库：`~/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-backed runtime entrypoints。退休的 `project-initializer` runtime 目录会被
+symlink-backed runtime entrypoints。退休的 `repo-harness-skill` 与
+`project-initializer` runtime 目录会被
 `scripts/sync-codex-installed-copies.sh` 清理。
 
 ### 最小前置条件
@@ -242,11 +253,17 @@ bun test
 - Codex 必须在 Settings 里信任 `~/.codex/hooks.json`，hooks 才会执行。
 - 调试顺序：user-level adapter config -> `repo-harness-hook` 或 fallback `repo-harness hook` -> route registry -> `.ai/hooks/*`。
 
-`SessionStart` 在开工前按顺序跑两个脚本：
+`SessionStart` 先按 central-first 解析 hook source，再按顺序跑两个脚本：
 
 ```mermaid
 flowchart LR
-  SessionStart["Claude/Codex SessionStart"] --> Ctx["session-start-context.sh<br/>恢复 + handoff 上下文"]
+  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/>或 ~/.repo-harness/hooks"]
+  Source -->|repo policy pin| Repo["repo .ai/hooks<br/>self-host development"]
+  Central --> Ctx["session-start-context.sh<br/>恢复 + sprint + handoff 上下文"]
+  Repo --> Ctx
   Ctx --> Sec["security-sentinel.sh<br/>只读配置扫描，按指纹门控"]
   Sec --> SSOut["SessionStart additionalContext<br/>上次会话状态 + SecurityConfig 发现项"]
 ```
@@ -297,7 +314,7 @@ hook block 工作时，先看 terminal 里的结构化输出。核心字段是
 
 ## 当前 Release
 
-- npm package：`repo-harness@0.2.4`
+- 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)