repo-harness 0.3.0 → 0.4.0

package/AGENTS.md

@@ -10,7 +10,7 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 - `.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
@@ -26,11 +26,11 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 - 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`.
@@ -50,6 +50,7 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 ```bash
 bun test
 bash scripts/check-deploy-sql-order.sh
+bash scripts/check-architecture-sync.sh
 bash scripts/check-task-sync.sh
 bash scripts/check-task-workflow.sh --strict
 bun scripts/inspect-project-state.ts --repo . --format text
@@ -79,7 +80,7 @@ bash scripts/migrate-project-template.sh --repo . --dry-run
 - Latest snapshot: `(none yet)`
 - Semantic diagram source: `docs/architecture/modules/runtime-harness/hook-adapters.md`
 - Latest human diagram: `(none yet)`
-- Pending architecture request: `docs/architecture/requests/20260529-094446-ai-hooks-ai-hooks-session-start-context-sh.md`
+- Pending architecture request: `(none)`
 
 ## Active Workstreams
 

package/CLAUDE.md

@@ -10,7 +10,7 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 - `.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
@@ -26,11 +26,11 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 - 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`.
@@ -50,6 +50,7 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 ```bash
 bun test
 bash scripts/check-deploy-sql-order.sh
+bash scripts/check-architecture-sync.sh
 bash scripts/check-task-sync.sh
 bash scripts/check-task-workflow.sh --strict
 bun scripts/inspect-project-state.ts --repo . --format text
@@ -79,7 +80,7 @@ bash scripts/migrate-project-template.sh --repo . --dry-run
 - Latest snapshot: `(none yet)`
 - Semantic diagram source: `docs/architecture/modules/runtime-harness/hook-adapters.md`
 - Latest human diagram: `(none yet)`
-- Pending architecture request: `docs/architecture/requests/20260529-094446-ai-hooks-ai-hooks-session-start-context-sh.md`
+- Pending architecture request: `(none)`
 
 ## Active Workstreams
 

package/README.es.md

@@ -186,8 +186,8 @@ adoptar este workflow.
 npx -y repo-harness init
 ```
 
-La npm package release line es ahora `0.3.x`; el workflow compatibility model line
-generado se rastrea por separado como `5.x`. `repo-harness init` es el bootstrap
+La npm package release line y el generated workflow stamp usan ahora la misma
+línea `0.4.x`. `repo-harness init` es el bootstrap
 global y `repo-harness update` es el refresco repo-local. `repo-harness init`
 configura el CLI, los hook adapters de nivel usuario, Waza, Mermaid, el brain
 root y CodeGraph MCP; el viejo camino Claude plugin `scripts/setup-plugins.sh`
@@ -325,12 +325,12 @@ Guards habituales:
 
 ## Release actual
 
-- npm package: `repo-harness@0.3.0`
-- 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.3.x` ; la generated workflow
-compatibility model line est suivie séparément en `5.x`. `repo-harness init`
+La release line du package npm et le generated workflow stamp utilisent
+désormais la même ligne `0.4.x`. `repo-harness init`
 sert au bootstrap global et `repo-harness update` sert au rafraîchissement
 repo-local. `repo-harness init` configure le CLI, les hook adapters de niveau
 utilisateur, Waza, Mermaid, le brain root et CodeGraph MCP ; l'ancien chemin
@@ -329,12 +329,12 @@ Guards courants :
 
 ## Release actuelle
 
-- npm package : `repo-harness@0.3.0`
-- 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.3.x` です。生成される workflow compatibility model line は
-別途 `5.x` として追跡されます。`repo-harness init` は global bootstrap、`repo-harness update` は
+npm package と generated workflow stamp は現在同じ `0.4.x` release line を使います。
+`repo-harness init` は global bootstrap、`repo-harness update` は
 repo-local refresh です。`repo-harness init` は CLI、user-level hook adapters、Waza、Mermaid、
 brain root、CodeGraph MCP を設定し、退役した `scripts/setup-plugins.sh` の Claude plugin path は使いません。
 
@@ -293,12 +293,12 @@ hook がブロックしたときは、まず terminal の構造化された出
 
 ## 現在の Release
 
-- npm package：`repo-harness@0.3.0`
-- 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

@@ -34,28 +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.3.0
-
-- **Sprint program layer.** `repo-harness-sprint`, `tasks/sprints/`, sprint
-  templates, active sprint markers, and `scripts/sprint-backlog.sh` now capture
-  program-level PRDs and ordered backlogs without turning `tasks/todo.md` into
-  an active execution checklist.
-- **Central-first hook runtime.** User-level Claude/Codex adapters dispatch into
-  `repo-harness-hook`; central packaged hooks are the default runtime, while
-  this self-host repo can still pin `"hook_source": "repo"` for live hook
-  development.
-- **Prompt decisions moved to TypeScript.** Prompt-text intent classification is
-  Unicode-aware in `src/cli/hook/prompt-intents.ts`, the shell hook receives one
-  verdict JSON line, and prompt-layer plan/spec/contract gates are advisory.
-- **Edit-layer enforcement.** Implementation writes are enforced at
-  `pre-edit-guard.sh`, where the guard can key off path, active plan state, and
-  repo files instead of natural-language guesses.
-- **Cheaper always-on hooks.** `trace-event.sh` and `context-pressure-hook.sh`
-  are merged into `post-tool-observer.sh`: one dispatch, one stdin parse, one
-  trace file, and sampled context-budget probes.
-- **Legacy surface cleanup.** The retired `repo-harness-skill`,
-  `project-initializer`, `PROJECT_INITIALIZER_*` fallbacks, duplicate shell
-  classifier table, orphan version checker, and split observer hooks are gone.
+## What's New in 0.4.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
 
@@ -118,7 +115,10 @@ The diagram below assumes the harness is already installed in the repo. It shows
 the normal lifecycle from a program sprint backlog down to one contract task:
 draft or select the task, project it into execution files, check out the
 contract worktree when policy requires it, implement under hooks, verify, review,
-complete the sprint task when applicable, and close out.
+complete the sprint task when applicable, and close out. The 0.4.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
@@ -126,10 +126,12 @@ flowchart TD
   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 --> PlanDraft["Draft plan<br/>plans/plan-*.md"]
+  Discovery --> LoopEvidence["Loop evidence when routing changes<br/>state-snapshot --json<br/>route-nl-vs-ts / cutover gate"]
+  LoopEvidence --> PlanDraft["Draft plan<br/>plans/plan-*.md"]
   PlanDraft --> PlanReview{"Plan ready for execution?"}
   PlanReview -->|no| Refine["Refine plan, scope, evidence contract"]
   Refine --> PlanDraft
@@ -142,18 +144,23 @@ flowchart TD
   Project --> ReviewFile["Review file<br/>tasks/reviews/YYYYMMDD-HHMM-task-slug.review.md"]
   Project --> Notes["Task notes<br/>tasks/notes/YYYYMMDD-HHMM-task-slug.notes.md"]
 
-  Contract --> WorktreePolicy{"Contract worktree required?"}
+  Contract --> Delegation["Delegation contract<br/>budget / permission_scope / roles"]
+  Delegation --> Delegate{"Use contract-run delegation?"}
+  Delegate -->|yes| ContractRun["Worker/verifier child run<br/>scripts/contract-run.ts"]
+  Delegate -->|no| WorktreePolicy{"Contract worktree required?"}
   WorktreePolicy -->|yes| Checkout["Checkout isolated worktree<br/>contract-worktree.sh start --plan<br/>branch codex/task-slug"]
   WorktreePolicy -->|no| CurrentTree["Use current worktree<br/>small or explicitly allowed slice"]
   Checkout --> Implement
   CurrentTree --> Implement
+  ContractRun --> Changes
 
   Implement["Edit and run commands"] --> PreHooks["Pre-edit guards<br/>PlanStatusGuard, ContractScopeGuard, WorktreeGuard"]
   PreHooks -->|blocked| ScopeFix["Fix plan, contract, worktree, or scope"]
   ScopeFix --> Implement
   PreHooks -->|allowed| Changes["Code, docs, tests, or config changes"]
   Changes --> PostHooks["Post-edit and post-bash hooks<br/>trace, drift request, handoff, check evidence"]
-  PostHooks --> Verify["Run verification<br/>tests plus repo workflow checks"]
+  PostHooks --> ArchQueue["Architecture queue<br/>architecture-queue.sh record/reindex<br/>check-architecture-sync.sh"]
+  ArchQueue --> Verify["Run verification<br/>tests plus repo workflow checks"]
 
   Verify --> Checks["Structured evidence<br/>.ai/harness/checks/latest.json<br/>.ai/harness/runs/*.json"]
   Checks --> CheckReview["Evaluator review<br/>Waza /check -> review file"]
@@ -201,13 +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.3.x`; generated workflow compatibility is
-tracked separately as the `5.x` model line. The `0.3.0` package keeps first-run
+The npm package and generated workflow stamp now share the `0.4.x` release line.
+The `0.4.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.
+(`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
@@ -358,12 +364,12 @@ Most common guards:
 
 ## Current Release
 
-- npm package: `repo-harness@0.3.0`
-- Generated workflow compatibility: `5.2.3`
+- npm package: `repo-harness@0.4.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:

package/README.zh-CN.md

@@ -23,25 +23,21 @@ repo-local workflow 的自托管样例。
   做渐进式上下文加载：一份小而稳定的 root context（约 12KB），加上只在改到对应文件时才加载的
   capability 块。agent 读一份 1KB 的 capability 合约或查索引，而不是花上千 token 重新摸清结构。
 
-## 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 都已移除。
+## 0.4.0 新特性
+
+- **Loop-engine 证据面。** `repo-harness-hook state-snapshot --json`、NL
+  decision-table、route A/B eval 和 cutover gate 让 prompt-routing 实验可度量；
+  在证据达标前，TypeScript classifier 仍是权威路径。
+- **Architecture queue gate。** `scripts/architecture-queue.sh`、
+  `scripts/check-architecture-sync.sh` 和扩展后的 architecture event helper
+  取代已退休的 append-only drift 脚本，用派生 request index 检查 stale 架构状态。
+- **Contract delegation pilot。** Contract template 新增 `budget`、
+  `permission_scope`、`roles`，`scripts/contract-run.ts` 可用显式
+  worker/verifier child commands 按 contract exit criteria 执行试点。
+- **Heartbeat triage。** `scripts/heartbeat-triage.sh` 把定时 workflow checks、
+  sprint-next 信号和 architecture request 状态写入 repo-local triage inbox。
+- **Workflow asset sync。** 新 helpers、docs、tests 和 generated-repo assets
+  保持 self-host runtime 与安装模板副本同步。
 
 ## 产品做什么
 
@@ -90,7 +86,9 @@ classifier/state-machine 层不再散落在 shell 条件分支里。
 下面这张图假设目标仓库已经安装 harness。它展示的是从 program sprint backlog
 到单个 contract task 的正常闭环：先选择或形成任务，再投射到执行文件，需要时
 checkout 隔离 worktree，在 hooks 保护下实现，然后验证、review、external acceptance，
-必要时标记 sprint task 完成，最后 closeout。
+必要时标记 sprint task 完成，最后 closeout。0.4.0 的 loop-system surface
+新增 heartbeat 定时发现、state-snapshot/eval 证据、architecture queue freshness，
+以及可选的 contract-run 委派，但 source of truth 仍然是 repo 内文件合约。
 
 ```mermaid
 flowchart TD
@@ -98,10 +96,12 @@ flowchart TD
   Sprint -->|是| SprintDoc["Sprint PRD + backlog<br/>tasks/sprints/*.sprint.md"]
   SprintDoc --> NextTask["选择下一个 sprint task<br/>sprint-backlog.sh next"]
   Sprint -->|否| UserTask["用户任务或 planning prompt"]
+  Heartbeat["Heartbeat triage<br/>scripts/heartbeat-triage.sh<br/>.ai/harness/triage/"] --> UserTask
   NextTask --> UserTask
 
   UserTask --> Discovery["前置调查<br/>P1 map, P2 trace, P3 decision"]
-  Discovery --> PlanDraft["Draft plan<br/>plans/plan-*.md"]
+  Discovery --> LoopEvidence["路由变更时的 loop evidence<br/>state-snapshot --json<br/>route-nl-vs-ts / cutover gate"]
+  LoopEvidence --> PlanDraft["Draft plan<br/>plans/plan-*.md"]
   PlanDraft --> PlanReview{"Plan 是否可执行?"}
   PlanReview -->|否| Refine["收敛 scope 和 evidence contract"]
   Refine --> PlanDraft
@@ -114,18 +114,23 @@ flowchart TD
   Project --> ReviewFile["Review file<br/>tasks/reviews/YYYYMMDD-HHMM-task-slug.review.md"]
   Project --> Notes["Task notes<br/>tasks/notes/YYYYMMDD-HHMM-task-slug.notes.md"]
 
-  Contract --> WorktreePolicy{"是否需要 contract worktree?"}
+  Contract --> Delegation["Delegation contract<br/>budget / permission_scope / roles"]
+  Delegation --> Delegate{"是否使用 contract-run 委派?"}
+  Delegate -->|是| ContractRun["Worker/verifier child run<br/>scripts/contract-run.ts"]
+  Delegate -->|否| WorktreePolicy{"是否需要 contract worktree?"}
   WorktreePolicy -->|是| Checkout["Checkout 隔离 worktree<br/>contract-worktree.sh start --plan<br/>branch codex/task-slug"]
   WorktreePolicy -->|否| CurrentTree["使用当前 worktree<br/>小任务或明确允许的 slice"]
   Checkout --> Implement
   CurrentTree --> Implement
+  ContractRun --> Changes
 
   Implement["编辑和运行命令"] --> PreHooks["Pre-edit guards<br/>PlanStatusGuard, ContractScopeGuard, WorktreeGuard"]
   PreHooks -->|blocked| ScopeFix["修正 plan、contract、worktree 或 scope"]
   ScopeFix --> Implement
   PreHooks -->|allowed| Changes["代码、文档、测试或配置改动"]
   Changes --> PostHooks["Post-edit / post-bash hooks<br/>trace, drift request, handoff, check evidence"]
-  PostHooks --> Verify["运行验证<br/>tests plus repo workflow checks"]
+  PostHooks --> ArchQueue["Architecture queue<br/>architecture-queue.sh record/reindex<br/>check-architecture-sync.sh"]
+  ArchQueue --> Verify["运行验证<br/>tests plus repo workflow checks"]
 
   Verify --> Checks["结构化 evidence<br/>.ai/harness/checks/latest.json<br/>.ai/harness/runs/*.json"]
   Checks --> CheckReview["Evaluator review<br/>Waza /check -> review file"]
@@ -171,11 +176,11 @@ npx -y repo-harness update
 安装或刷新 workflow files、hook assets、host adapters、skill aliases 和
 repo-local verification surfaces。
 
-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 合并为更轻的一条路径。
+npm package 和 generated workflow stamp 现在共用 `0.4.x` release line。
+`repo-harness@0.4.0` 继续把首次全局引导（`repo-harness init`）
+和 repo-local 刷新（`repo-harness update`）拆开，同时新增 loop-engine state
+snapshot、architecture queue gate、contract delegation pilot、heartbeat triage
+helper，以及这些 workflow surfaces 的 generated asset sync。
 这些能力叠加在改名后的 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 之上。
@@ -314,12 +319,12 @@ hook block 工作时，先看 terminal 里的结构化输出。核心字段是
 
 ## 当前 Release
 
-- npm package：`repo-harness@0.3.0`
-- 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/assets/hooks/lib/workflow-state.sh

@@ -889,18 +889,42 @@ workflow_pending_orchestration_summary() {
   printf '\n'
 }
 
+latest_research_report() {
+  local research_dir="${1:-docs/researches}"
+  local file mtime latest_file="" latest_mtime=0
+
+  [[ -d "$research_dir" ]] || return 1
+
+  while IFS= read -r -d '' file; do
+    case "$(basename "$file")" in
+      README.md)
+        continue
+        ;;
+    esac
+
+    mtime="$(workflow_read_file_mtime "$file" || true)"
+    if [[ -n "$mtime" && "$mtime" -gt "$latest_mtime" ]]; then
+      latest_mtime="$mtime"
+      latest_file="$file"
+    fi
+  done < <(find "$research_dir" -type f -name '*.md' -print0 2>/dev/null)
+
+  [[ -n "$latest_file" ]] || return 1
+  printf '%s' "$latest_file"
+}
+
 has_research_for_new_plan() {
-  local research_file="tasks/research.md"
-  local latest_plan research_mtime plan_mtime
+  local latest_plan latest_report research_mtime plan_mtime
 
-  [[ -f "$research_file" ]] || return 1
+  latest_report="$(latest_research_report || true)"
+  [[ -n "$latest_report" ]] || return 1
 
   latest_plan="$(get_latest_plan || true)"
   if [[ -z "$latest_plan" ]]; then
     return 0
   fi
 
-  research_mtime="$(workflow_read_file_mtime "$research_file" || true)"
+  research_mtime="$(workflow_read_file_mtime "$latest_report" || true)"
   plan_mtime="$(workflow_read_file_mtime "$latest_plan" || true)"
 
   [[ -n "$research_mtime" && -n "$plan_mtime" && "$research_mtime" -gt "$plan_mtime" ]]

package/assets/hooks/post-edit-guard.sh

@@ -29,22 +29,22 @@ run_continuous_contract_verification() {
   fi
 }
 
-run_architecture_drift_sync() {
-  local drift_output status
+run_architecture_queue_sync() {
+  local queue_output status
 
-  [[ -x "scripts/architecture-drift.sh" ]] || return 0
+  [[ -x "scripts/architecture-queue.sh" ]] || return 0
 
-  if drift_output="$(bash "scripts/architecture-drift.sh" record --file "$FILE_PATH" 2>&1)"; then
+  if queue_output="$(bash "scripts/architecture-queue.sh" record --file "$FILE_PATH" 2>&1)"; then
     :
   else
     status=$?
-    [[ -n "$drift_output" ]] && printf '%s\n' "$drift_output"
-    echo "[SyncChain] WARN: architecture-drift failed for $FILE_PATH (exit $status)"
+    [[ -n "$queue_output" ]] && printf '%s\n' "$queue_output"
+    echo "[SyncChain] WARN: architecture-queue failed for $FILE_PATH (exit $status)"
     return 0
   fi
-  [[ -n "$drift_output" ]] && printf '%s\n' "$drift_output"
+  [[ -n "$queue_output" ]] && printf '%s\n' "$queue_output"
 
-  if printf '%s\n' "$drift_output" | grep -q '^\[ArchitectureDrift\] Request:'; then
+  if printf '%s\n' "$queue_output" | grep -q '^\[ArchitectureDrift\] Request:'; then
     if [[ -x "scripts/context-contract-sync.sh" ]]; then
       if bash "scripts/context-contract-sync.sh" sync-latest; then
         :
@@ -154,7 +154,7 @@ if [[ -x "$SCRIPT_DIR/anti-simplification.sh" ]]; then
   bash "$SCRIPT_DIR/anti-simplification.sh" "$FILE_PATH" </dev/null || true
 fi
 
-run_architecture_drift_sync
+run_architecture_queue_sync
 
 run_brain_doc_sync
 

package/assets/hooks/prompt-guard.sh

@@ -847,8 +847,10 @@ emit_workflow_file_guards() {
     echo "[LessonGuard] tasks/lessons.md has updates. Review prevention rules before coding."
   fi
 
-  if [ -f "tasks/research.md" ] && has_changes "tasks/research.md"; then
-    echo "[ResearchGuard] tasks/research.md updated. Review research deeply before planning or implementation."
+  local changed_research
+  changed_research="$(has_changes_glob '^docs/researches/.*\.md$' || true)"
+  if [ -n "$changed_research" ]; then
+    echo "[ResearchGuard] ${changed_research} updated. Review research deeply before planning or implementation."
   fi
 
   local changed_plan
@@ -896,11 +898,11 @@ if [ "$plan_start_intent" -eq 1 ]; then
     latest_plan="$(get_latest_plan || true)"
     if [[ -n "$latest_plan" ]]; then
       plan_research_ready=0
-      echo "[ResearchGate] Advisory: tasks/research.md is missing or older than $latest_plan; skipping automatic Draft plan creation."
-      echo "[ResearchGate] Update tasks/research.md with fresh findings before creating the next plan."
+      echo "[ResearchGate] Advisory: docs/researches/*.md is missing or older than $latest_plan; skipping automatic Draft plan creation."
+      echo "[ResearchGate] Add or update a docs/researches/ report with fresh findings before creating the next plan."
     else
-      echo "[ResearchGate] WARNING: tasks/research.md does not exist yet. Consider creating it with current findings before drafting the plan."
-      echo "  首次创建计划：建议先写 tasks/research.md，但不阻塞。"
+      echo "[ResearchGate] WARNING: no docs/researches/*.md report exists yet. Consider creating one with current findings before drafting the plan."
+      echo "  首次创建计划：建议先写 docs/researches/<date-topic>.md，但不阻塞。"
     fi
   fi
 fi

package/assets/hooks/session-start-context.sh

@@ -158,6 +158,46 @@ ${pending_lines}
 EOF_CONTEXT
 }
 
+architecture_queue_pending() {
+  local requests_dir="docs/architecture/requests"
+  local pending_count="0"
+  local oldest_epoch="" oldest_days="unknown"
+  local now_epoch request detected detected_date detected_epoch
+
+  [[ -d "$requests_dir" ]] || return 1
+
+  now_epoch="$(date '+%s' 2>/dev/null || true)"
+  while IFS= read -r request; do
+    [[ -f "$request" ]] || continue
+    grep -Eq '^> \*\*Status\*\*:[[:space:]]*Pending[[:space:]]*$' "$request" || continue
+    pending_count=$((pending_count + 1))
+    detected="$(awk '/^> \*\*Detected\*\*:/ {sub(/^.*> \*\*Detected\*\*:[[:space:]]*/, ""); print; exit}' "$request" | xargs || true)"
+    detected_date="${detected%%T*}"
+    detected_epoch=""
+    if [[ "$detected_date" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ ]]; then
+      detected_epoch="$(date -j -f '%Y-%m-%d' "$detected_date" '+%s' 2>/dev/null || date -d "$detected_date" '+%s' 2>/dev/null || true)"
+    fi
+    if [[ -n "$detected_epoch" && ( -z "$oldest_epoch" || "$detected_epoch" -lt "$oldest_epoch" ) ]]; then
+      oldest_epoch="$detected_epoch"
+    fi
+  done < <(find "$requests_dir" -maxdepth 1 -type f -name '*.md' | sort)
+
+  [[ "$pending_count" -gt 0 ]] || return 1
+  if [[ -n "$now_epoch" && -n "$oldest_epoch" && "$now_epoch" -ge "$oldest_epoch" ]]; then
+    oldest_days="$(( (now_epoch - oldest_epoch) / 86400 ))d"
+  fi
+
+  cat <<EOF_CONTEXT
+# Architecture Queue
+
+${pending_count} capabilities have pending architecture drift (oldest ${oldest_days}). Run:
+
+\`\`\`bash
+bash scripts/architecture-queue.sh status
+\`\`\`
+EOF_CONTEXT
+}
+
 pending_plan_capture_context() {
   local active_plan summary draft_path prompt_slug kind source_ref capture_source source_arg
 
@@ -335,6 +375,15 @@ if [[ -n "$pending_context" ]]; then
   fi
 fi
 
+architecture_context="$(architecture_queue_pending || true)"
+if [[ -n "$architecture_context" ]]; then
+  if [[ -n "$context" ]]; then
+    context="${context}"$'\n'"${architecture_context}"
+  else
+    context="$architecture_context"
+  fi
+fi
+
 pending_capture_context="$(pending_plan_capture_context || true)"
 if [[ -n "$pending_capture_context" ]]; then
   if [[ -n "$context" ]]; then

package/assets/partials/04-project-structure.partial.md

@@ -41,7 +41,7 @@
 - Keep stable product truth in `docs/spec.md`.
 - Keep sprint done definitions in `tasks/contracts/`, `tasks/reviews/`, and task-local implementation notes in `tasks/notes/`.
 - Keep resumable state in `.ai/harness/handoff/current.md`.
-- Treat `_ref/` as an occasional ignored external reference checkout cache; read or refresh it for comparison, but keep it out of commits and cite repo+commit/tag+path in `tasks/notes/` or `tasks/research.md` when it influences a decision.
+- Treat `_ref/` as an occasional ignored external reference checkout cache; read or refresh it for comparison, but keep it out of commits and cite repo+commit/tag+path in `tasks/notes/` or `docs/researches/` when it influences a decision.
 - 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 execution as worktree-first: `scripts/plan-to-todo.sh --plan <approved-plan>` starts a linked `codex/<slug>` worktree when policy enables it, and `scripts/contract-worktree.sh finish` merges back only after Waza `/check` and sprint verification pass.