repo-harness 0.8.4 → 0.9.0

package/AGENTS.md

@@ -36,6 +36,7 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 - 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: `repo-harness run plan-to-todo --plan <approved-plan>` starts `repo-harness run contract-worktree start --plan <approved-plan>` when policy enables it, and completed blocks finish through Waza `/check` plus `repo-harness run contract-worktree finish`.
+- Treat the EXECUTION_BOUNDARY anti-extras clause as mandatory on every delegated runner surface (contract worker prompts, the Codex delegation advisor hook, subagent start context, and MCP `codex-goal` documents): absent requirements are forbidden design space, not permission to improve, and unrequested extras fail closed.
 - After Codex Plan mode, Waza `/think`, or `repo-harness-plan` produces a decision-complete work-package plan, capture it with `repo-harness run capture-plan --artifact-level work-package --slug <slug> --title <title>` so `plans/` becomes the file-backed source of truth; if the user has already approved implementation, capture with `--status Approved --execute --promotion-reason <merge_boundary|rollback_boundary|verification_boundary|risk_boundary|human_decision_boundary|worktree_boundary>` or run `repo-harness run plan-to-todo --plan <active-plan>`.
 - Promote work into a top-level `plans/plan-*.md` only when `Artifact Level: work-package` is justified by a merge/PR unit, rollback surface, independent verification boundary, review/acceptance boundary, high-risk surface, or otherwise cannot remain a checklist item in the current active plan or sprint backlog. Inline sprint rows and checklist rows stay in the sprint backlog or active plan `## Task Breakdown`; contract rows may expand into plan -> contract -> review -> notes only through the work-package gate.
 - If current repo state conflicts with the task, open an isolated `codex/<task-slug>` worktree, finish there, run Waza `/check`-style validation, then merge back to `main` without absorbing unrelated dirty changes.
@@ -63,35 +64,38 @@ bash scripts/migrate-project-template.sh --repo . --dry-run
 <!-- BEGIN ARCHITECTURE CONTRACT -->
 ## Architecture Contract
 
-- Functional block: `.ai/hooks`
-- Capability ID: `runtime-harness-hook-adapters`
-- Matched prefix: `.ai/hooks`
-- Architecture domain: `runtime-harness`
-- Architecture capability: `hook-adapters`
-- Architecture module: `docs/architecture/modules/runtime-harness/hook-adapters.md`
-- Last architecture event: 2026-05-29T09:44:46+0800
-- Last changed path: `.ai/hooks/session-start-context.sh`
+- Functional block: `scripts/inspect-project-state.ts`
+- Capability ID: `workflow-engine-inspection-migration`
+- Matched prefix: `scripts/inspect-project-state.ts`
+- Architecture domain: `workflow-engine`
+- Architecture capability: `inspection-migration`
+- Architecture module: `docs/architecture/modules/workflow-engine/inspection-migration.md`
+- Last architecture event: 2026-07-03T15:44:54+0800
+- Last changed path: `docs/architecture/requests/archive/2026/workflow-engine-inspection-migration.md`
 - Severity: high
-- Change type: workflow-surface
+- Change type: architecture-closeout
 - Module responsibility: Keep this block aligned with the local boundary described by surrounding human-owned context.
-- Entrypoints: `.ai/hooks`
+- Entrypoints: `scripts/inspect-project-state.ts`
 - Allowed dependencies: Follow root `AGENTS.md` / `CLAUDE.md` and this local contract.
 - Forbidden dependencies: Do not cross sibling app/service/package boundaries without an architecture snapshot or explicit plan.
-- Runtime path: `.ai/hooks`
+- Runtime path: `scripts/inspect-project-state.ts`
 - LSP/tooling profile: `typescript-lsp`
 - Verification: Use root required checks plus local commands recorded in this capability contract.
 - Latest snapshot: `(none yet)`
-- Semantic diagram source: `docs/architecture/modules/runtime-harness/hook-adapters.md`
+- Semantic diagram source: `docs/architecture/modules/workflow-engine/inspection-migration.md`
 - Latest human diagram: `(none yet)`
 - Pending architecture request: `(none)`
 
 ## Active Workstreams
 
-- (none yet)
+- `tasks/workstreams/workflow-engine/inspection-migration/20260703-inspection-migration.md`
+  - status: active
+  - current_slice: completed-20260703-architecture-closeout
+  - source_plan: (none)
 
 ## Current Session Projection
 
-- Durable progress lives under `tasks/workstreams/runtime-harness/hook-adapters`.
+- Durable progress lives under `tasks/workstreams/workflow-engine/inspection-migration`.
 - `tasks/current.md` is the tracked derived status snapshot; it is not a live lock or task source.
 - `tasks/todos.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
 <!-- END ARCHITECTURE CONTRACT -->

package/CLAUDE.md

@@ -36,6 +36,7 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 - 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: `repo-harness run plan-to-todo --plan <approved-plan>` starts `repo-harness run contract-worktree start --plan <approved-plan>` when policy enables it, and completed blocks finish through Waza `/check` plus `repo-harness run contract-worktree finish`.
+- Treat the EXECUTION_BOUNDARY anti-extras clause as mandatory on every delegated runner surface (contract worker prompts, the Codex delegation advisor hook, subagent start context, and MCP `codex-goal` documents): absent requirements are forbidden design space, not permission to improve, and unrequested extras fail closed.
 - After Codex Plan mode, Waza `/think`, or `repo-harness-plan` produces a decision-complete work-package plan, capture it with `repo-harness run capture-plan --artifact-level work-package --slug <slug> --title <title>` so `plans/` becomes the file-backed source of truth; if the user has already approved implementation, capture with `--status Approved --execute --promotion-reason <merge_boundary|rollback_boundary|verification_boundary|risk_boundary|human_decision_boundary|worktree_boundary>` or run `repo-harness run plan-to-todo --plan <active-plan>`.
 - Promote work into a top-level `plans/plan-*.md` only when `Artifact Level: work-package` is justified by a merge/PR unit, rollback surface, independent verification boundary, review/acceptance boundary, high-risk surface, or otherwise cannot remain a checklist item in the current active plan or sprint backlog. Inline sprint rows and checklist rows stay in the sprint backlog or active plan `## Task Breakdown`; contract rows may expand into plan -> contract -> review -> notes only through the work-package gate.
 - If current repo state conflicts with the task, open an isolated `codex/<task-slug>` worktree, finish there, run Waza `/check`-style validation, then merge back to `main` without absorbing unrelated dirty changes.
@@ -63,35 +64,38 @@ bash scripts/migrate-project-template.sh --repo . --dry-run
 <!-- BEGIN ARCHITECTURE CONTRACT -->
 ## Architecture Contract
 
-- Functional block: `.ai/hooks`
-- Capability ID: `runtime-harness-hook-adapters`
-- Matched prefix: `.ai/hooks`
-- Architecture domain: `runtime-harness`
-- Architecture capability: `hook-adapters`
-- Architecture module: `docs/architecture/modules/runtime-harness/hook-adapters.md`
-- Last architecture event: 2026-05-29T09:44:46+0800
-- Last changed path: `.ai/hooks/session-start-context.sh`
+- Functional block: `scripts/inspect-project-state.ts`
+- Capability ID: `workflow-engine-inspection-migration`
+- Matched prefix: `scripts/inspect-project-state.ts`
+- Architecture domain: `workflow-engine`
+- Architecture capability: `inspection-migration`
+- Architecture module: `docs/architecture/modules/workflow-engine/inspection-migration.md`
+- Last architecture event: 2026-07-03T15:44:54+0800
+- Last changed path: `docs/architecture/requests/archive/2026/workflow-engine-inspection-migration.md`
 - Severity: high
-- Change type: workflow-surface
+- Change type: architecture-closeout
 - Module responsibility: Keep this block aligned with the local boundary described by surrounding human-owned context.
-- Entrypoints: `.ai/hooks`
+- Entrypoints: `scripts/inspect-project-state.ts`
 - Allowed dependencies: Follow root `AGENTS.md` / `CLAUDE.md` and this local contract.
 - Forbidden dependencies: Do not cross sibling app/service/package boundaries without an architecture snapshot or explicit plan.
-- Runtime path: `.ai/hooks`
+- Runtime path: `scripts/inspect-project-state.ts`
 - LSP/tooling profile: `typescript-lsp`
 - Verification: Use root required checks plus local commands recorded in this capability contract.
 - Latest snapshot: `(none yet)`
-- Semantic diagram source: `docs/architecture/modules/runtime-harness/hook-adapters.md`
+- Semantic diagram source: `docs/architecture/modules/workflow-engine/inspection-migration.md`
 - Latest human diagram: `(none yet)`
 - Pending architecture request: `(none)`
 
 ## Active Workstreams
 
-- (none yet)
+- `tasks/workstreams/workflow-engine/inspection-migration/20260703-inspection-migration.md`
+  - status: active
+  - current_slice: completed-20260703-architecture-closeout
+  - source_plan: (none)
 
 ## Current Session Projection
 
-- Durable progress lives under `tasks/workstreams/runtime-harness/hook-adapters`.
+- Durable progress lives under `tasks/workstreams/workflow-engine/inspection-migration`.
 - `tasks/current.md` is the tracked derived status snapshot; it is not a live lock or task source.
 - `tasks/todos.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
 <!-- END ARCHITECTURE CONTRACT -->

package/README.es.md

@@ -85,7 +85,7 @@ artifacts.
 ## Novedades
 
 Las notas de versión viven en [`docs/CHANGELOG.md`](docs/CHANGELOG.md). La línea
-actual es `0.8.4`.
+actual es `0.9.0`.
 
 ## Cómo funciona
 
@@ -419,8 +419,8 @@ Guards habituales:
 
 ## Release actual
 
-- npm package: `repo-harness@0.8.4`
-- Generated workflow stamp: `repo-harness@0.8.4+template@0.8.4`
+- npm package: `repo-harness@0.9.0`
+- Generated workflow stamp: `repo-harness@0.9.0+template@0.9.0`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.fr.md

@@ -85,7 +85,7 @@ l'emportent.
 ## Nouveautés
 
 Les notes de version vivent dans [`docs/CHANGELOG.md`](docs/CHANGELOG.md). La
-ligne actuelle est `0.8.4`.
+ligne actuelle est `0.9.0`.
 
 ## Comment ça marche
 
@@ -424,8 +424,8 @@ Guards courants :
 
 ## Release actuelle
 
-- npm package : `repo-harness@0.8.4`
-- Generated workflow stamp : `repo-harness@0.8.4+template@0.8.4`
+- npm package : `repo-harness@0.9.0`
+- Generated workflow stamp : `repo-harness@0.9.0+template@0.9.0`
 - GitHub repository : `Ancienttwo/repo-harness`
 - Release history : [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.ja.md

@@ -75,7 +75,7 @@ review、checks、handoff と食い違う場合は、source artifacts を優先
 ## What's New
 
 リリースノートは [`docs/CHANGELOG.md`](docs/CHANGELOG.md) にあります。現在の
-ラインは `0.8.4` です。
+ラインは `0.9.0` です。
 
 ## 仕組み
 
@@ -398,8 +398,8 @@ hook がブロックしたときは、まず terminal の構造化された出
 
 ## 現在の Release
 
-- npm package：`repo-harness@0.8.4`
-- Generated workflow stamp：`repo-harness@0.8.4+template@0.8.4`
+- npm package：`repo-harness@0.9.0`
+- Generated workflow stamp：`repo-harness@0.9.0+template@0.9.0`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.md

@@ -1,7 +1,7 @@
 # repo-harness
 
 <p align="center">
-  <img src="docs/images/repo-harness-gptpro.png" alt="repo-harness architecture and ChatGPT Pro local planner workflow diagram" width="960">
+  <img src="docs/images/repo-harness-hook-carrot.png" alt="repo-harness hooks leading Codex and Claude forward with repo-local workflow state" width="900">
 </p>
 
 `repo-harness` turns Claude/Codex coding sessions into a repeatable repo-local
@@ -61,6 +61,12 @@ rollback. Then inspect the active contract, latest trace in
 review recommends pass, the card verdict is pass, and external acceptance is
 pass, `not_required`, or an explicit manual override.
 
+Runtime-heavy validators such as Unity, browser E2E, mobile simulators, hardware
+rigs, or staging smoke tests can publish external verification manifests under
+the ignored run-evidence surface. This is a manual convention today, not an
+automatic `repo-harness check` discovery or gate. See
+[`docs/reference-configs/external-tooling.md`](docs/reference-configs/external-tooling.md#external-verification-evidence).
+
 ## Agent Tracking Path
 
 Agents read source artifacts before derived summaries:
@@ -79,7 +85,7 @@ active plan, contract, review, checks, or handoff, the source artifacts win.
 ## What's New
 
 Release notes live in [`docs/CHANGELOG.md`](docs/CHANGELOG.md). The current line
-is `0.8.4`.
+is `0.9.0`.
 
 ## How It Works
 
@@ -93,6 +99,10 @@ The design has three layers:
 3. **Host adapters**: user-level `~/.claude/settings.json` and
    `~/.codex/hooks.json` route Claude/Codex events into `repo-harness-hook`.
 
+<p align="center">
+  <img src="docs/images/repo-harness-gptpro.png" alt="repo-harness architecture and ChatGPT Pro local planner workflow diagram" width="960">
+</p>
+
 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
@@ -269,9 +279,12 @@ repo-harness install
 `install` is the first-run global bootstrap path. It installs the current npm
 package as the global CLI, refreshes repo-harness skill aliases, installs
 user-level hook adapters, configures Waza runtime skills, persists a brain root
-under `~/.repo-harness/config.json`, and configures CodeGraph MCP. It does not
-apply repo-local workflow files to the current directory. `repo-harness init`
-remains a compatibility alias for existing scripts.
+under `~/.repo-harness/config.json`, and configures CodeGraph MCP. In an
+interactive terminal it asks Y/n before installing the external skills and
+CodeGraph pieces (Enter keeps today's default of installing both); non-TTY
+runs and `--json` stay unprompted with the same default-on behavior. It does
+not apply repo-local workflow files to the current directory. `repo-harness
+init` remains a compatibility alias for existing scripts.
 
 For an Agent-owned, read-only bootstrap audit, run `repo-harness setup check
 --json` or add `--check-updates` for version advisories. `setup check` is
@@ -599,8 +612,8 @@ Most common guards:
 
 ## Current Release
 
-- npm package: `repo-harness@0.8.4`
-- Generated workflow stamp: `repo-harness@0.8.4+template@0.8.4`
+- npm package: `repo-harness@0.9.0`
+- Generated workflow stamp: `repo-harness@0.9.0+template@0.9.0`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.zh-CN.md

@@ -52,6 +52,12 @@ verdict、change type、预期/实际改动文件、已通过命令、external a
 recommend pass、card verdict 为 pass，且 external acceptance 为 pass、not_required
 或明确 manual override 时，才进入 closeout。
 
+Unity、浏览器 E2E、mobile simulator、硬件测试和 staging smoke test 这类
+运行时重验证器，可以把 external verification manifest 写到被忽略的 run-evidence
+surface。当前这只是手动约定，不是 `repo-harness check` 已经会自动发现或 gate
+的能力。详见
+[`docs/reference-configs/external-tooling.md`](docs/reference-configs/external-tooling.md#external-verification-evidence)。
+
 ## Agent Tracking Path
 
 Agent 先读 source artifacts，再读派生摘要：
@@ -69,7 +75,7 @@ review、checks 或 handoff 冲突，以 source artifacts 为准。
 
 ## What's New
 
-Release notes 见 [`docs/CHANGELOG.md`](docs/CHANGELOG.md)，当前版本线是 `0.8.4`。
+Release notes 见 [`docs/CHANGELOG.md`](docs/CHANGELOG.md)，当前版本线是 `0.9.0`。
 
 ## 工作原理
 
@@ -445,8 +451,8 @@ hook block 工作时，先看 terminal 里的结构化输出。核心字段是
 
 ## 当前 Release
 
-- npm package：`repo-harness@0.8.4`
-- Generated workflow stamp：`repo-harness@0.8.4+template@0.8.4`
+- npm package：`repo-harness@0.9.0`
+- Generated workflow stamp：`repo-harness@0.9.0+template@0.9.0`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/assets/AGENTS.md

@@ -37,10 +37,10 @@ Owns the workflow-engine-contract-assets capability boundary declared in .ai/con
 - Architecture domain: `workflow-engine`
 - Architecture capability: `contract-assets`
 - Architecture module: `docs/architecture/modules/workflow-engine/contract-assets.md`
-- Last architecture event: 2026-05-29T02:15:07+0800
-- Last changed path: `tasks/workstreams/workflow-engine/contract-assets/cleanup-script-policy.md`
-- Severity: medium
-- Change type: workstream-sync
+- Last architecture event: 2026-07-05T04:35:33+0800
+- Last changed path: `.ai/harness/policy.json`
+- Severity: high
+- Change type: workflow-surface
 - Module responsibility: Keep this block aligned with the local boundary described by surrounding human-owned context.
 - Entrypoints: `.ai/harness/policy.json`
 - Allowed dependencies: Follow root `AGENTS.md` / `CLAUDE.md` and this local contract.
@@ -63,6 +63,6 @@ Owns the workflow-engine-contract-assets capability boundary declared in .ai/con
 ## Current Session Projection
 
 - Durable progress lives under `tasks/workstreams/workflow-engine/contract-assets`.
-- `tasks/current.md` is a tracked derived status snapshot, not a live lock or task source.
+- `tasks/current.md` is the tracked derived status snapshot; it is not a live lock or task source.
 - `tasks/todos.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
 <!-- END ARCHITECTURE CONTRACT -->

package/assets/CLAUDE.md

@@ -37,10 +37,10 @@ Owns the workflow-engine-contract-assets capability boundary declared in .ai/con
 - Architecture domain: `workflow-engine`
 - Architecture capability: `contract-assets`
 - Architecture module: `docs/architecture/modules/workflow-engine/contract-assets.md`
-- Last architecture event: 2026-05-29T02:15:07+0800
-- Last changed path: `tasks/workstreams/workflow-engine/contract-assets/cleanup-script-policy.md`
-- Severity: medium
-- Change type: workstream-sync
+- Last architecture event: 2026-07-05T04:35:33+0800
+- Last changed path: `.ai/harness/policy.json`
+- Severity: high
+- Change type: workflow-surface
 - Module responsibility: Keep this block aligned with the local boundary described by surrounding human-owned context.
 - Entrypoints: `.ai/harness/policy.json`
 - Allowed dependencies: Follow root `AGENTS.md` / `CLAUDE.md` and this local contract.
@@ -63,6 +63,6 @@ Owns the workflow-engine-contract-assets capability boundary declared in .ai/con
 ## Current Session Projection
 
 - Durable progress lives under `tasks/workstreams/workflow-engine/contract-assets`.
-- `tasks/current.md` is a tracked derived status snapshot, not a live lock or task source.
+- `tasks/current.md` is the tracked derived status snapshot; it is not a live lock or task source.
 - `tasks/todos.md` is the deferred-goal ledger; current execution slices stay in the active plan's `## Task Breakdown`.
 <!-- END ARCHITECTURE CONTRACT -->

package/assets/hooks/AGENTS.md

@@ -37,27 +37,27 @@ Owns the runtime-harness-hook-adapters capability boundary declared in .ai/conte
 ## Refresh Hints
 
 - `bun test tests/hook-runtime.test.ts tests/hook-contracts.test.ts tests/workflow-contract.test.ts`
-- `repo-harness run check-task-workflow --strict`
+- `bash scripts/check-task-workflow.sh --strict`
 <!-- END CAPABILITY CONTEXT -->
 
 <!-- BEGIN ARCHITECTURE CONTRACT -->
 ## Architecture Contract
 
-- Functional block: `.ai/hooks`
+- Functional block: `assets/hooks`
 - Capability ID: `runtime-harness-hook-adapters`
-- Matched prefix: `.ai/hooks`
+- Matched prefix: `assets/hooks`
 - Architecture domain: `runtime-harness`
 - Architecture capability: `hook-adapters`
 - Architecture module: `docs/architecture/modules/runtime-harness/hook-adapters.md`
-- Last architecture event: 2026-06-13T00:04:13+0800
-- Last changed path: `.ai/hooks/post-tool-observer.sh`
+- Last architecture event: 2026-07-05T13:45:11+0800
+- Last changed path: `assets/hooks/codex-delegation-advisor.sh`
 - Severity: high
 - Change type: workflow-surface
 - Module responsibility: Keep this block aligned with the local boundary described by surrounding human-owned context.
-- Entrypoints: `.ai/hooks`
+- Entrypoints: `assets/hooks`
 - Allowed dependencies: Follow root `AGENTS.md` / `CLAUDE.md` and this local contract.
 - Forbidden dependencies: Do not cross sibling app/service/package boundaries without an architecture snapshot or explicit plan.
-- Runtime path: `.ai/hooks`
+- Runtime path: `assets/hooks`
 - LSP/tooling profile: `typescript-lsp`
 - Verification: Use root required checks plus local commands recorded in this capability contract.
 - Latest snapshot: `(none yet)`

package/assets/hooks/CLAUDE.md

@@ -37,27 +37,27 @@ Owns the runtime-harness-hook-adapters capability boundary declared in .ai/conte
 ## Refresh Hints
 
 - `bun test tests/hook-runtime.test.ts tests/hook-contracts.test.ts tests/workflow-contract.test.ts`
-- `repo-harness run check-task-workflow --strict`
+- `bash scripts/check-task-workflow.sh --strict`
 <!-- END CAPABILITY CONTEXT -->
 
 <!-- BEGIN ARCHITECTURE CONTRACT -->
 ## Architecture Contract
 
-- Functional block: `.ai/hooks`
+- Functional block: `assets/hooks`
 - Capability ID: `runtime-harness-hook-adapters`
-- Matched prefix: `.ai/hooks`
+- Matched prefix: `assets/hooks`
 - Architecture domain: `runtime-harness`
 - Architecture capability: `hook-adapters`
 - Architecture module: `docs/architecture/modules/runtime-harness/hook-adapters.md`
-- Last architecture event: 2026-06-13T00:04:13+0800
-- Last changed path: `.ai/hooks/post-tool-observer.sh`
+- Last architecture event: 2026-07-05T13:45:11+0800
+- Last changed path: `assets/hooks/codex-delegation-advisor.sh`
 - Severity: high
 - Change type: workflow-surface
 - Module responsibility: Keep this block aligned with the local boundary described by surrounding human-owned context.
-- Entrypoints: `.ai/hooks`
+- Entrypoints: `assets/hooks`
 - Allowed dependencies: Follow root `AGENTS.md` / `CLAUDE.md` and this local contract.
 - Forbidden dependencies: Do not cross sibling app/service/package boundaries without an architecture snapshot or explicit plan.
-- Runtime path: `.ai/hooks`
+- Runtime path: `assets/hooks`
 - LSP/tooling profile: `typescript-lsp`
 - Verification: Use root required checks plus local commands recorded in this capability contract.
 - Latest snapshot: `(none yet)`

package/assets/hooks/codex-delegation-advisor.sh

@@ -94,6 +94,25 @@ JSON_INPUT="$input" REPO_ROOT="${HOOK_REPO_ROOT:-$(pwd)}" bun -e '
   if (!trigger) process.exit(0);
 
   const repoRoot = process.env.REPO_ROOT || process.cwd();
+
+  let policyDelegation = {};
+  try {
+    policyDelegation =
+      JSON.parse(fs.readFileSync(path.join(repoRoot, ".ai", "harness", "policy.json"), "utf8")).delegation || {};
+  } catch {
+    policyDelegation = {};
+  }
+  const maxAgents = Number.isInteger(policyDelegation.max_agents) ? policyDelegation.max_agents : 3;
+  const maxDepth = Number.isInteger(policyDelegation.max_depth) ? policyDelegation.max_depth : 1;
+  const preferredRunners =
+    Array.isArray(policyDelegation.preferred_runners) && policyDelegation.preferred_runners.length
+      ? policyDelegation.preferred_runners
+      : ["subagent"];
+  const fallbackRunner =
+    typeof policyDelegation.fallback_runner === "string" && policyDelegation.fallback_runner
+      ? policyDelegation.fallback_runner
+      : null;
+
   const stateDir = path.join(repoRoot, ".ai", "harness", "delegation");
   fs.mkdirSync(stateDir, { recursive: true });
 
@@ -107,10 +126,12 @@ JSON_INPUT="$input" REPO_ROOT="${HOOK_REPO_ROOT:-$(pwd)}" bun -e '
     spawned: false,
     fallback_used: false,
     mode: "explicit",
-    max_agents: 3,
-    max_depth: 1,
+    max_agents: maxAgents,
+    max_depth: maxDepth,
     allow_parallel_writers: false,
     stop_fallback: true,
+    preferred_runners: preferredRunners,
+    fallback_runner: fallbackRunner,
     trigger: trigger.name,
     prompt_hash: crypto.createHash("sha1").update(prompt).digest("hex"),
     scope_source: scope?.source || "unscoped",
@@ -132,20 +153,32 @@ JSON_INPUT="$input" REPO_ROOT="${HOOK_REPO_ROOT:-$(pwd)}" bun -e '
     "",
     "The current user prompt explicitly enabled bounded delegation.",
     "",
-    "If this task contains at least two independent, bounded workstreams, call spawn_agent before doing the corresponding work in the parent.",
+    "Treat the active task contract (tasks/contracts/<active-plan-stem>.contract.md) as the authoritative execution brief: Goal, Scope, Allowed Paths, and Exit Criteria. Do not re-derive scope from this conversation.",
+    "",
+    `Runner preference (policy delegation.preferred_runners): ${preferredRunners.join(", ")}. Native subagent (spawn_agent) is the preferred parallelism accelerator that consumes the contract brief. When spawn_agent is unavailable, sandboxed, or unreliable, degrade to ${fallbackRunner || "main-thread"} on the SAME contract via contract-run. Runner-availability degradation MUST be recorded in the contract-run manifest and MUST NOT silently succeed; it is a runner-availability fallback, not a product-semantics change.`,
+    "",
+    "If this task contains at least two independent, bounded workstreams, dispatch per the contract before doing the corresponding work in the parent; otherwise run it sequentially.",
     "",
     "Rules:",
-    "- Spawn no more than 3 agents.",
+    `- Spawn no more than ${maxAgents} agents.`,
     "- Use explorer for read-only code mapping.",
     "- Use worker only for an isolated implementation slice.",
     "- Use reviewer for correctness, regression, security, and missing-test review.",
     "- Never give two agents overlapping write ownership.",
-    "- Keep max spawn depth at 1.",
+    `- Keep max spawn depth at ${maxDepth}.`,
     "- Give every agent a precise scope and required return format.",
     "- Wait for all requested agents.",
     "- Reconcile contradictory findings in the parent.",
     "- Close completed agent threads.",
     "- Do not spawn for a trivial or strictly sequential task.",
+    "",
+    "Execution boundary: implement exactly the Goal, In scope items, Allowed Paths, and Exit Criteria in this brief. Treat absent requirements as forbidden design space, not as permission to improve.",
+    "",
+    "Do not add optional features, alternate UX, extra integrations, migration paths, compatibility behavior, fallback behavior, telemetry, broad cleanup, refactors, new abstractions, extra docs, or polish unless that work is explicitly listed under In scope or required by Exit Criteria.",
+    "",
+    "If you discover useful additional work, record it under Out of scope / Future work in the notes or review artifact. Do not implement it. Do not end with unsolicited offers to do more work.",
+    "",
+    "If the requested outcome cannot be completed without expanding scope, fail closed: stop, name the missing decision, and cite the exact file/section that blocks execution.",
   ].join("\n");
 
   process.stdout.write(`${JSON.stringify({

package/assets/hooks/lib/workflow-state.sh

@@ -1317,7 +1317,7 @@ workflow_review_rubric_version() {
 
 # Classify the top-of-file Review Rubric Version. Echoes one of:
 #   absent     - no rubric line at all (a genuine pre-rubric legacy artifact)
-#   1          - the supported modern rubric version
+#   1 or 2     - a supported rubric version (1 = legacy, 2 = current)
 #   malformed  - a rubric line is present but is not a supported version
 #                (non-numeric, 0, an unsupported number, or quote/space garbage)
 # A present-but-unsupported rubric means the artifact claims a schema this gate
@@ -1333,8 +1333,8 @@ workflow_review_rubric_class() {
   trimmed="${trimmed%"${trimmed##*[![:space:]]}"}"
   if [[ -z "$trimmed" ]]; then
     printf 'absent'
-  elif [[ "$trimmed" == "1" ]]; then
-    printf '1'
+  elif [[ "$trimmed" == "1" || "$trimmed" == "2" ]]; then
+    printf '%s' "$trimmed"
   else
     printf 'malformed'
   fi
@@ -1420,7 +1420,7 @@ workflow_review_freshness_status() {
     # path here — the external-acceptance gate is the authority that requires a
     # supported rubric (a rubric-less review fails external acceptance), so absent
     # is still blocked at every Done/finish/verify gate that enforces external.
-    if [[ "$rubric_class" == "1" ]]; then
+    if [[ "$rubric_class" != "absent" ]]; then
       printf 'missing\t-\tReview fingerprint is missing for rubric v%s; rerun /check and peer acceptance to record the current Reviewed Diff Fingerprint.\n' "$rubric_class"
       return 0
     fi
@@ -1570,7 +1570,7 @@ workflow_external_acceptance_status() {
   fi
 
   # Bind the peer's acceptance to the exact diff they reviewed. A supported rubric
-  # (v1) requires the External Acceptance section to carry its own current Reviewed
+  # (v1+) requires the External Acceptance section to carry its own current Reviewed
   # Diff Fingerprint and scope; otherwise a stale F1 acceptance keeps satisfying the
   # gate after the implementation moves to F2, because the top-of-file fingerprint
   # is agent-editable. An absent or malformed rubric fails closed here — external
@@ -1930,6 +1930,31 @@ ${changed_files}
 \`\`\`
 EOF_HANDOFF
 
+  cat > "$resume_file" <<EOF_RESUME
+# Codex Resume Packet
+<!-- generated-by: workflow_write_handoff v1 -->
+
+> **Generated**: $(date '+%Y-%m-%d %H:%M:%S')
+> **Reason**: ${reason}
+
+## Resume Prompt
+
+Start a fresh session for this task; do not rely on auto-compact or prior chat history. Read the source artifacts below, then the handoff, before continuing from Exact Next Step.
+
+- ${next_task}
+
+## Source Artifacts
+
+- Handoff: ${handoff_file}
+- Spec: ${spec_file}
+- Active plan: ${active_plan:-(none)}
+- Active contract: ${active_contract:-(none)}
+- Review: ${active_review:-(none)}
+- Notes: ${active_notes:-(none)}
+- Research: $(workflow_policy_get '.tasks.research_dir' 'docs/researches')/
+- Checks: ${checks_file}
+EOF_RESUME
+
   workflow_append_event "handoff_refresh" "$reason" "{\"source_plan\":\"$(workflow_json_escape "${source_plan:-}")\",\"parent_run_id\":\"$(workflow_json_escape "$parent_run_id")\"}"
   workflow_write_run_summary "$reason"
 }

package/assets/hooks/prompt-guard.sh

@@ -807,7 +807,7 @@ emit_review_fingerprint_prompt() {
   review_file="$(workflow_active_review || true)"
   echo "[ReviewFreshness] Current implementation diff fingerprint: ${fingerprint:-unknown}"
   echo "[ReviewFreshness] Record these review metadata lines in ${review_file:-tasks/reviews/<slug>.review.md}:"
-  echo "> **Review Rubric Version**: 1"
+  echo "> **Review Rubric Version**: 2"
   echo "> **Reviewed Diff Fingerprint**: ${fingerprint:-unknown}"
   echo "> **Reviewed Scope**: branch+staged+unstaged+untracked"
 }
@@ -865,9 +865,9 @@ emit_external_acceptance_prompt() {
   echo "[ExternalAcceptance] Diff scope for peer: branch diff against target, staged diff, unstaged diff, and untracked files."
   cat <<EOF_EXTERNAL_ACCEPTANCE
 [ExternalAcceptance] Prompt to send with $command:
-Review the current sprint for acceptance only. Do not run /check. Do not edit files. Do not write files. Inspect the diff scope, contract, review evidence, checks evidence, and Review Rubric v1, then return only a Markdown block that can be pasted into ${review_file:-tasks/reviews/<slug>.review.md}.
+Review the current sprint for acceptance only. Do not run /check. Do not edit files. Do not write files. Inspect the diff scope, contract, review evidence, checks evidence, and Review Rubric v2, then return only a Markdown block that can be pasted into ${review_file:-tasks/reviews/<slug>.review.md}.
 
-${rubric:-[ReviewRubric] Deep Diff Review Rubric v1 unavailable; use severity order P0/P1/P2/P3 and report no style-only nits.}
+${rubric:-[ReviewRubric] Deep Diff Review Rubric v2 unavailable; use severity order P0/P1/P2/P3 and report no style-only nits.}
 
 ## External Acceptance Advice
 > **External Acceptance**: pass
@@ -875,7 +875,7 @@ ${rubric:-[ReviewRubric] Deep Diff Review Rubric v1 unavailable; use severity or
 > **External Source**: $expected_source
 > **External Started**: YYYY-MM-DDTHH:MM:SS+0800
 > **External Completed**: YYYY-MM-DDTHH:MM:SS+0800
-> **Review Rubric Version**: 1
+> **Review Rubric Version**: 2
 > **Reviewed Diff Fingerprint**: ${fingerprint:-unknown}
 > **Reviewed Scope**: branch+staged+unstaged+untracked
 

package/assets/hooks/stop-orchestrator.sh

@@ -253,7 +253,7 @@ minimal_change_render_handoff_section() {
 }
 
 minimal_change_append_handoff() {
-  local handoff_file tmp_file
+  local handoff_file tmp_file resume_file
 
   [[ -n "$MINIMAL_CHANGE_REVIEW_VERDICT" ]] || return 0
   [[ "$MINIMAL_CHANGE_REVIEW_VERDICT" != "disabled" ]] || return 0
@@ -275,6 +275,14 @@ minimal_change_append_handoff() {
   printf '\n' >> "$tmp_file"
   minimal_change_render_handoff_section >> "$tmp_file"
   mv "$tmp_file" "$handoff_file"
+
+  # refresh_handoff (workflow_write_handoff) already wrote a resume packet
+  # whose mtime matched the handoff snapshot at that time; this function just
+  # mutated handoff_file again, so bump the resume packet's mtime to match or
+  # check_handoff_resume_pair sees it as stale. Its content does not
+  # reference minimal-change-review data, so no rewrite is needed.
+  resume_file="$(workflow_resume_packet_file)"
+  [[ -f "$resume_file" ]] && touch -r "$handoff_file" "$resume_file" 2>/dev/null || true
 }
 
 minimal_change_reason_suffix() {

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

@@ -113,6 +113,14 @@ JSON_INPUT="$HOOK_STDIN_JSON" REPO_ROOT="${HOOK_REPO_ROOT:-$(pwd)}" bun -e '
     "- recommended parent action",
     "",
     "Do not claim overall task completion.",
+    "",
+    "Execution boundary: implement exactly the Goal, In scope items, Allowed Paths, and Exit Criteria in this brief. Treat absent requirements as forbidden design space, not as permission to improve.",
+    "",
+    "Do not add optional features, alternate UX, extra integrations, migration paths, compatibility behavior, fallback behavior, telemetry, broad cleanup, refactors, new abstractions, extra docs, or polish unless that work is explicitly listed under In scope or required by Exit Criteria.",
+    "",
+    "If you discover useful additional work, record it under Out of scope / Future work in the notes or review artifact. Do not implement it. Do not end with unsolicited offers to do more work.",
+    "",
+    "If the requested outcome cannot be completed without expanding scope, fail closed: stop, name the missing decision, and cite the exact file/section that blocks execution.",
   ].join("\n");
 
   process.stdout.write(`${JSON.stringify({