repo-harness 0.4.1 → 0.4.2

package/AGENTS.md

@@ -6,7 +6,7 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 
 - `tasks/current.md` for the tracked current-status snapshot derived from workflow artifacts
 - `tasks/todos.md` for deferred medium/long-term goals, not active execution checklists
-- `plans/prds/` for program-level sprint PRDs and ordered backlogs, operated by `scripts/sprint-backlog.sh` (Sprint = program layer; task contracts stay the execution slices)
+- `plans/prds/` for upper-layer PRDs; `plans/sprints/` for ordered sprint backlogs operated through `scripts/sprint-backlog.sh` (installed implementations live under `.ai/harness/scripts/`; 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

package/CLAUDE.md

@@ -6,7 +6,7 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 
 - `tasks/current.md` for the tracked current-status snapshot derived from workflow artifacts
 - `tasks/todos.md` for deferred medium/long-term goals, not active execution checklists
-- `plans/prds/` for program-level sprint PRDs and ordered backlogs, operated by `scripts/sprint-backlog.sh` (Sprint = program layer; task contracts stay the execution slices)
+- `plans/prds/` for upper-layer PRDs; `plans/sprints/` for ordered sprint backlogs operated through `scripts/sprint-backlog.sh` (installed implementations live under `.ai/harness/scripts/`; 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

package/README.es.md

@@ -345,8 +345,8 @@ Guards habituales:
 
 ## Release actual
 
-- npm package: `repo-harness@0.4.1`
-- Generated workflow stamp: `repo-harness@0.4.1+template@0.4.1`
+- npm package: `repo-harness@0.4.2`
+- Generated workflow stamp: `repo-harness@0.4.2+template@0.4.2`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.fr.md

@@ -350,8 +350,8 @@ Guards courants :
 
 ## Release actuelle
 
-- npm package : `repo-harness@0.4.1`
-- Generated workflow stamp : `repo-harness@0.4.1+template@0.4.1`
+- npm package : `repo-harness@0.4.2`
+- Generated workflow stamp : `repo-harness@0.4.2+template@0.4.2`
 - GitHub repository : `Ancienttwo/repo-harness`
 - Release history : [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.ja.md

@@ -312,8 +312,8 @@ hook がブロックしたときは、まず terminal の構造化された出
 
 ## 現在の Release
 
-- npm package：`repo-harness@0.4.1`
-- Generated workflow stamp：`repo-harness@0.4.1+template@0.4.1`
+- npm package：`repo-harness@0.4.2`
+- Generated workflow stamp：`repo-harness@0.4.2+template@0.4.2`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.md

@@ -34,21 +34,20 @@ 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.4.1
-
-- **Session-scoped CodeGraph nudges.** Hook stdin `session_id` now drives the
-  one-shot CodeGraph route hint, so stale local session files no longer suppress
-  or repeat guidance across independent Claude/Codex sessions.
-- **Central-first hook safety.** Generated and migrated repos stay on the
-  user-level hook runtime by default; repo-local top-level hook scripts are
-  pruned unless `.ai/harness/policy.json` explicitly pins `"hook_source": "repo"`.
-- **Workflow document migration.** Active workflow docs now use
-  `tasks/todos.md` for deferred goals and `docs/researches/*.md` for durable
-  research, with legacy `tasks/todo.md` and `tasks/research.md` treated as
-  migration inputs.
-- **Release-gate stability.** Runtime ignore rules cover transient
-  `tasks/.current.md.tmp.*` and `.claude/.plan-state/` state, and the default
-  Bun test timeout matches the release gate budget.
+## What's New in 0.4.2
+
+- **PRD-to-Sprint planning hierarchy.** `repo-harness-prd` now owns
+  upper-layer product requirements under `plans/prds/`, while
+  `repo-harness-sprint` derives ordered execution backlogs under
+  `plans/sprints/*.sprint.md`.
+- **Generated helper runtime isolation.** Downstream installs place real helper
+  implementations under `.ai/harness/scripts/` and keep root `scripts/*` as
+  compatibility wrappers; this self-host repo remains the source runtime.
+- **Subagent return-channel guard.** Managed hook routes include a guard that
+  keeps delegated runs reporting back through the parent session instead of
+  bypassing the file-backed contract.
+- **Release path alignment.** PRD/Sprint eval fixtures, workflow checks, and
+  command guidance now point at the same installed helper runtime.
 
 ## What repo-harness Does
 
@@ -119,7 +118,8 @@ delegation without changing the file-backed authority model.
 ```mermaid
 flowchart TD
   Program["Program goal or release theme"] --> Sprint{"Sprint layer needed?"}
-  Sprint -->|yes| SprintDoc["Sprint PRD + backlog<br/>plans/prds/*.prd.md"]
+  Sprint -->|yes| PRD["Upper-layer PRD<br/>plans/prds/*.prd.md"]
+  PRD --> SprintDoc["Sprint backlog<br/>plans/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
@@ -185,16 +185,17 @@ judgment in Claude-Fable before asking Codex to loop on execution:
    `plan-eng-review` for engineering plan review. The output should be the
    development documents that lock product intent, architecture, risks, and the
    evidence contract.
-2. Turn those documents into a PRD sprint under `plans/prds/`, with an
-   ordered backlog and detailed sub-plans for each execution slice.
+2. Turn those documents into an upper-layer PRD under `plans/prds/`, then into
+   an ordered sprint backlog under `plans/sprints/` with detailed sub-plans for
+   each execution slice.
 3. In Codex, create a Goal that points at that sprint file. The harness can then
    project each sprint item through the normal plan -> contract -> worktree ->
    verification flow.
 
 That handoff keeps long-running loops precise: Claude-Fable owns the broad
-front-loaded judgment, the PRD sprint is the durable source of truth, and Codex
-Goal mode resumes against a concrete sprint instead of reinterpreting the
-original chat.
+front-loaded judgment, the PRD remains the upper source of truth, the sprint
+backlog is the durable execution queue, and Codex Goal mode resumes against a
+concrete sprint instead of reinterpreting the original chat.
 
 ## First 5 Minutes
 
@@ -225,11 +226,11 @@ 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 and generated workflow stamp now share the `0.4.x` release line.
-The `0.4.1` package keeps first-run
+The `0.4.2` package keeps first-run
 global bootstrap (`repo-harness init`) separate from repo-local refresh
-(`repo-harness update`) while hardening session-scoped hook state, central-first
-hook execution, workflow-document migration, and release-gate stability on top
-of the `0.4.0` loop-engine surfaces.
+(`repo-harness update`) while adding the PRD-to-Sprint planning hierarchy,
+isolated generated-project helper runtime, subagent return-channel guard, and
+release-path alignment on top of the `0.4.0` loop-engine 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
@@ -289,7 +290,7 @@ The command should end with `=== Migration Report ===` and summarize:
 - `Host hook config target: user-level ~/.claude/settings.json and ~/.codex/hooks.json` to show the adapter layer
 - `Host hook adapters are user-level:` to remind the user to install global adapters and trust `~/.codex/hooks.json`
 - `Workflow migration:` to show the repo-local harness surfaces it will create or refresh
-- `Helper scripts:` to show the operational toolchain you get after apply
+- `Helper runtime:` to show `.ai/harness/scripts/*` implementations and `scripts/*` compatibility wrappers after apply
 - `--- External Tooling ---` to show default gstack/Waza/gbrain routing plus advisory install/update hints
 
 ### Next two commands
@@ -380,8 +381,8 @@ Most common guards:
 
 ## Current Release
 
-- npm package: `repo-harness@0.4.1`
-- Generated workflow stamp: `repo-harness@0.4.1+template@0.4.1`
+- npm package: `repo-harness@0.4.2`
+- Generated workflow stamp: `repo-harness@0.4.2+template@0.4.2`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -431,7 +432,8 @@ Most common guards:
 
 ## Acknowledgements and Workflow Influences
 
-`repo-harness` is built around a small set of external skills and repos that
+`repo-harness` is built around a small set of external skills, repos, and agent
+runtimes that
 proved useful while this project was being designed, debugged, and released.
 They are acknowledged here because they shaped the workflow contract, but they
 are not ordinary bundled product dependencies.
@@ -443,6 +445,20 @@ are not ordinary bundled product dependencies.
 | gstack skills and `gbrain` by [Garry Tan](https://x.com/garrytan) | Product discovery, plan review, design review, post-ship documentation hygiene, knowledge sync, handoff retrieval, and long-form repo memory | External operator workflow plus optional external CLI/index; advisory by default |
 | `mermaid` | Human-readable architecture and system-flow diagrams when Mermaid is not enough | Runtime-referenced skill, not vendored into generated repos |
 | CodeGraph (`@colbymchenry/codegraph`) | Symbol-aware navigation, impact tracing, and readiness checks for this self-host repo | Dev dependency in this repo; generated repos stay global-MCP-first unless policy opts in |
+| OpenAI Codex | Primary execution agent for repo-local implementation, verification, and GitHub contributor attribution when a commit materially includes Codex-authored work | External agent runtime; attribution is an explicit commit trailer, not hidden hook automation |
+
+### GitHub Contributor Attribution
+
+When Codex materially contributes to a commit, use GitHub's standard co-author
+trailer format at the end of the commit message:
+
+```text
+Co-authored-by: codex <codex@openai.com>
+```
+
+Keep this opt-in and visible per commit. Do not bake it into downstream
+repo-harness commit scripts or hooks unless that repo explicitly adopts the same
+policy.
 
 ## Action Command Skills
 
@@ -450,7 +466,8 @@ 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 `plans/prds/`, executed task-by-task through the contract flow)
+- Product planning layer: `repo-harness-prd` (upper-layer PRDs in `plans/prds/`, evidence-marked unknowns, sprint-consumable sections)
+- Sprint program layer: `repo-harness-sprint` (ordered sprint backlogs in `plans/sprints/`, each row expanded with `$think` before 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`
 

package/README.zh-CN.md

@@ -23,20 +23,19 @@ repo-local workflow 的自托管样例。
   做渐进式上下文加载：一份小而稳定的 root context（约 12KB），加上只在改到对应文件时才加载的
   capability 块。agent 读一份 1KB 的 capability 合约或查索引，而不是花上千 token 重新摸清结构。
 
-## 0.4.1 新特性
-
-- **Session-scoped CodeGraph 提醒。** Hook stdin 里的 `session_id` 现在会驱动
-  一次性 CodeGraph route hint，避免 stale 本地 session 文件跨 Claude/Codex
-  会话误抑制或重复提醒。
-- **Central-first hook safety。** Generated 和 migrated repos 默认继续使用
-  user-level hook runtime；只有 `.ai/harness/policy.json` 明确设置
-  `"hook_source": "repo"` 时，才保留 repo-local top-level hook scripts。
-- **Workflow 文档迁移。** Active workflow docs 统一使用 `tasks/todos.md`
-  记录 deferred goals，使用 `docs/researches/*.md` 保存 durable research；
-  legacy `tasks/todo.md` 和 `tasks/research.md` 只作为 migration inputs。
-- **Release-gate 稳定性。** Runtime ignore rules 覆盖
-  `tasks/.current.md.tmp.*` 和 `.claude/.plan-state/` 这类 transient state，
-  默认 Bun test timeout 也和 release gate budget 对齐。
+## 0.4.2 新特性
+
+- **PRD-to-Sprint planning hierarchy。** `repo-harness-prd` 负责
+  `plans/prds/` 下的上层产品需求，`repo-harness-sprint` 负责把 PRD 或明确
+  slice 推成 `plans/sprints/*.sprint.md` 下的有序执行 backlog。
+- **Generated helper runtime isolation。** 下游安装把真实 helper 实现放到
+  `.ai/harness/scripts/`，root `scripts/*` 只保留 compatibility wrappers；
+  自托管源码仓库继续以 root `scripts/` 作为 source runtime。
+- **Subagent return-channel guard。** Managed hook routes 增加 return-channel
+  guard，要求 delegated runs 回到 parent session 汇报，避免绕过 file-backed
+  contract。
+- **Release path alignment。** PRD/Sprint eval fixtures、workflow checks 和
+  command guidance 现在都指向同一个 installed helper runtime。
 
 ## 产品做什么
 
@@ -192,10 +191,10 @@ npx -y repo-harness update
 repo-local verification surfaces。
 
 npm package 和 generated workflow stamp 现在共用 `0.4.x` release line。
-`repo-harness@0.4.1` 继续把首次全局引导（`repo-harness init`）
+`repo-harness@0.4.2` 继续把首次全局引导（`repo-harness init`）
 和 repo-local 刷新（`repo-harness update`）拆开，并在 `0.4.0` loop-engine
-surfaces 之上强化 session-scoped hook state、central-first hook execution、
-workflow-document migration 和 release-gate stability。
+surfaces 之上加入 PRD-to-Sprint planning hierarchy、isolated generated-project
+helper runtime、subagent return-channel guard 和 release-path alignment。
 这些能力叠加在改名后的 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 之上。
@@ -334,8 +333,8 @@ hook block 工作时，先看 terminal 里的结构化输出。核心字段是
 
 ## 当前 Release
 
-- npm package：`repo-harness@0.4.1`
-- Generated workflow stamp：`repo-harness@0.4.1+template@0.4.1`
+- npm package：`repo-harness@0.4.2`
+- Generated workflow stamp：`repo-harness@0.4.2+template@0.4.2`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -373,6 +372,16 @@ decision rationale 的要求，来自他的贡献与启发。
 product discovery、plan/design review、release 文档、knowledge sync 和
 handoff retrieval 的工作流设计。
 
+感谢 OpenAI Codex 作为本仓库主要执行 agent 参与实现、验证和收口。Codex 对某个
+commit 有实质贡献时，GitHub contributor 署名使用显式 trailer：
+
+```text
+Co-authored-by: codex <codex@openai.com>
+```
+
+这条署名保持逐 commit 显式添加，不把它藏进下游 `repo-harness` commit 脚本或 hook
+里，除非目标仓库自己采用同样策略。
+
 ## Action Command Skills
 
 公共 command facades 在 `assets/skill-commands/`；它们保留 host skill discovery

package/SKILL.md

@@ -142,7 +142,8 @@ contract files:
 - `repo-harness-deploy`: check deploy and private operations configuration without publishing or deploying
 - `repo-harness-repair`: repair broken task sync, hook routing, handoff, context, policy, or helpers
 - `repo-harness-check`: run verification gates and report release or pre-merge readiness
-- `repo-harness-sprint`: plan a program-level sprint (PRD + ordered backlog) and drive backlog tasks through the task-contract flow
+- `repo-harness-prd`: generate an upper-layer PRD in `plans/prds/`
+- `repo-harness-sprint`: plan a sprint backlog in `plans/sprints/` from a PRD or source spec, then expand each row with `$think` before the task-contract flow
 
 Internal steps such as `hooks-init`, `docs-init`, and `create-project-dirs` are
 not public commands. They stay behind `init`, `scaffold`, `migrate`, and

package/assets/hooks/AGENTS.md

@@ -37,3 +37,39 @@ Owns the runtime-harness-hook-adapters capability boundary declared in .ai/conte
 - `bun test tests/hook-runtime.test.ts tests/hook-contracts.test.ts tests/workflow-contract.test.ts`
 - `bash scripts/check-task-workflow.sh --strict`
 <!-- END CAPABILITY CONTEXT -->
+
+<!-- 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-06-13T00:04:13+0800
+- Last changed path: `.ai/hooks/post-tool-observer.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`
+- 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`
+- 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`
+- Latest human diagram: `(none yet)`
+- Pending architecture request: `(none)`
+
+## Active Workstreams
+
+- (none yet)
+
+## Current Session Projection
+
+- Durable progress lives under `tasks/workstreams/runtime-harness/hook-adapters`.
+- `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/CLAUDE.md

@@ -37,3 +37,39 @@ Owns the runtime-harness-hook-adapters capability boundary declared in .ai/conte
 - `bun test tests/hook-runtime.test.ts tests/hook-contracts.test.ts tests/workflow-contract.test.ts`
 - `bash scripts/check-task-workflow.sh --strict`
 <!-- END CAPABILITY CONTEXT -->
+
+<!-- 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-06-13T00:04:13+0800
+- Last changed path: `.ai/hooks/post-tool-observer.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`
+- 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`
+- 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`
+- Latest human diagram: `(none yet)`
+- Pending architecture request: `(none)`
+
+## Active Workstreams
+
+- (none yet)
+
+## Current Session Projection
+
+- Durable progress lives under `tasks/workstreams/runtime-harness/hook-adapters`.
+- `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/codex.hooks.template.json

@@ -15,6 +15,12 @@
           { "type": "command", "command": "repo=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0; HOOK_HOST=codex HOOK_REPO_ROOT=\"$repo\" bash \"$repo/.ai/hooks/run-hook.sh\" worktree-guard.sh", "timeout": 30 },
           { "type": "command", "command": "repo=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0; HOOK_HOST=codex HOOK_REPO_ROOT=\"$repo\" bash \"$repo/.ai/hooks/run-hook.sh\" pre-edit-guard.sh", "timeout": 30 }
         ]
+      },
+      {
+        "matcher": "Task|Agent|SendUserMessage",
+        "hooks": [
+          { "type": "command", "command": "repo=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0; HOOK_HOST=codex HOOK_REPO_ROOT=\"$repo\" bash \"$repo/.ai/hooks/run-hook.sh\" subagent-return-channel-guard.sh", "timeout": 30 }
+        ]
       }
     ],
     "PostToolUse": [

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

@@ -15,6 +15,24 @@ workflow_rotate_events_file ".ai/harness/architecture/events.jsonl" 2>/dev/null
 
 resume_file="$(workflow_resume_packet_file)"
 
+helper_script_path() {
+  local helper_name="$1"
+  local helper_dir
+
+  helper_dir="$(workflow_policy_get '.harness.helper_runtime_dir' '.ai/harness/scripts')"
+  if [[ -f "$helper_dir/$helper_name" ]]; then
+    printf '%s/%s' "$helper_dir" "$helper_name"
+    return 0
+  fi
+
+  if [[ -f "scripts/$helper_name" ]]; then
+    printf '%s/%s' "scripts" "$helper_name"
+    return 0
+  fi
+
+  printf '%s/%s' "$helper_dir" "$helper_name"
+}
+
 resume_available() {
   [[ -f "$resume_file" ]] || return 1
   grep -Fq "<!-- generated-by: repo-harness codex-handoff-resume v1 -->" "$resume_file" || return 1
@@ -138,8 +156,10 @@ architecture_queue_pending() {
   local pending_count="0"
   local oldest_epoch="" oldest_days="unknown"
   local now_epoch request detected detected_date detected_epoch
+  local queue_script
 
   [[ -d "$requests_dir" ]] || return 1
+  queue_script="$(helper_script_path "architecture-queue.sh")"
 
   now_epoch="$(date '+%s' 2>/dev/null || true)"
   while IFS= read -r request; do
@@ -168,13 +188,13 @@ architecture_queue_pending() {
 ${pending_count} capabilities have pending architecture drift (oldest ${oldest_days}). Run:
 
 \`\`\`bash
-bash scripts/architecture-queue.sh status
+bash ${queue_script} status
 \`\`\`
 EOF_CONTEXT
 }
 
 pending_plan_capture_context() {
-  local active_plan summary draft_path prompt_slug kind source_ref capture_source source_arg
+  local active_plan summary draft_path prompt_slug kind source_ref capture_source source_arg capture_script
 
   workflow_pending_orchestration_is_fresh || return 1
   active_plan="$(get_active_plan || true)"
@@ -190,6 +210,7 @@ pending_plan_capture_context() {
   if [[ -n "$source_ref" ]]; then
     source_arg=" --source-ref <source-ref>"
   fi
+  capture_script="$(helper_script_path "capture-plan.sh")"
 
   cat <<EOF_CONTEXT
 # Pending Plan Capture
@@ -203,13 +224,13 @@ A host/thread planning discussion is pending capture and no active repo plan is
 Capture the decision-complete plan body:
 
 \`\`\`bash
-printf '%s\n' '<decision-complete plan body>' | bash scripts/capture-plan.sh --slug ${prompt_slug:-<slug>} --title <title> --status Draft --source ${capture_source} --orchestration-kind ${capture_source} --route planning${source_arg}
+printf '%s\n' '<decision-complete plan body>' | bash ${capture_script} --slug ${prompt_slug:-<slug>} --title <title> --status Draft --source ${capture_source} --orchestration-kind ${capture_source} --route planning${source_arg}
 \`\`\`
 
 If the user has already approved implementation:
 
 \`\`\`bash
-printf '%s\n' '<approved plan body>' | bash scripts/capture-plan.sh --slug ${prompt_slug:-<slug>} --title <title> --status Approved --source ${capture_source} --orchestration-kind ${capture_source} --route planning --execute${source_arg}
+printf '%s\n' '<approved plan body>' | bash ${capture_script} --slug ${prompt_slug:-<slug>} --title <title> --status Approved --source ${capture_source} --orchestration-kind ${capture_source} --route planning --execute${source_arg}
 \`\`\`
 EOF_CONTEXT
 }
@@ -276,6 +297,7 @@ EOF_CONTEXT
 active_sprint_context() {
   local marker=".ai/harness/sprint/active-sprint"
   local sprint_file status progress next_task
+  local sprint_script capture_script
 
   if [[ -f ".ai/harness/policy.json" ]] && command -v jq >/dev/null 2>&1; then
     marker="$(jq -r '.sprints.active_marker_file // empty' .ai/harness/policy.json 2>/dev/null || true)"
@@ -311,13 +333,16 @@ active_sprint_context() {
     }
     END { if (!found) print "(none)" }
   ' "$sprint_file")"
+  sprint_script="$(helper_script_path "sprint-backlog.sh")"
+  capture_script="$(helper_script_path "capture-plan.sh")"
 
   cat <<EOF_CONTEXT
 # Active Sprint
 
 - Sprint: \`${sprint_file}\` status=${status:-unknown} backlog=${progress}
 - Next sprint task: ${next_task}
-- Rule: run backlog tasks through the existing plan -> contract -> worktree flow (\`scripts/sprint-backlog.sh next\`); \`tasks/todos.md\` stays the deferred-goal ledger.
+- Rule: a Sprint is a long-task container. Use \`\$think\` to expand the next sprint task into a detailed \`plans/plan-*.md\`, then run the existing plan -> contract -> worktree flow. \`tasks/todos.md\` stays the deferred-goal ledger.
+- Entrypoint: inspect with \`${sprint_script} next\`; after \`\$think\` produces an approved plan, capture it with \`${capture_script} --source waza-think --source-ref sprint:${sprint_file}#${next_task}\`.
 EOF_CONTEXT
 }
 

package/assets/hooks/settings.template.json

@@ -15,6 +15,12 @@
           { "type": "command", "command": "repo=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0; HOOK_REPO_ROOT=\"$repo\" bash \"$repo/.ai/hooks/run-hook.sh\" worktree-guard.sh", "timeout": 30 },
           { "type": "command", "command": "repo=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0; HOOK_REPO_ROOT=\"$repo\" bash \"$repo/.ai/hooks/run-hook.sh\" pre-edit-guard.sh", "timeout": 30 }
         ]
+      },
+      {
+        "matcher": "Task|Agent|SendUserMessage",
+        "hooks": [
+          { "type": "command", "command": "repo=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0; HOOK_REPO_ROOT=\"$repo\" bash \"$repo/.ai/hooks/run-hook.sh\" subagent-return-channel-guard.sh", "timeout": 30 }
+        ]
       }
     ],
     "PostToolUse": [

package/assets/hooks/subagent-return-channel-guard.sh

@@ -0,0 +1,107 @@
+#!/bin/bash
+# Subagent Return Channel Guard — PreToolUse on Task|Agent|SendUserMessage.
+# Spawned subagents return only their final text to the caller. If they send a
+# report through SendUserMessage, the user may see it but the parent Agent tool
+# result receives only a tiny transition/final text. This guard appends that
+# return-channel contract to spawned agent prompts and blocks subagent
+# SendUserMessage calls that would bypass the caller.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+. "$SCRIPT_DIR/hook-input.sh"
+
+hook_read_stdin_once
+input="$HOOK_STDIN_JSON"
+[[ -n "$input" ]] || exit 0
+
+CONTRACT_MARKER="[repo-harness:return-channel]"
+CONTRACT_TEXT=$'\n\n[repo-harness:return-channel] Your final text message is the only channel returned to your caller. Put the complete findings/report in final text. Do not call SendUserMessage for report delivery; content sent through SendUserMessage is delivered outside the Agent tool result.'
+
+if command -v bun >/dev/null 2>&1; then
+  JSON_INPUT="$input" \
+  RETURN_CONTRACT_MARKER="$CONTRACT_MARKER" \
+  RETURN_CONTRACT_TEXT="$CONTRACT_TEXT" \
+  bun -e '
+    try {
+      const input = JSON.parse(process.env.JSON_INPUT ?? "");
+      const toolName = String(input.tool_name ?? "");
+      const marker = process.env.RETURN_CONTRACT_MARKER ?? "";
+      const contract = process.env.RETURN_CONTRACT_TEXT ?? "";
+
+      if (toolName === "Task" || toolName === "Agent") {
+        const toolInput = input.tool_input;
+        if (!toolInput || typeof toolInput !== "object" || Array.isArray(toolInput)) process.exit(0);
+        if (typeof toolInput.prompt !== "string" || toolInput.prompt.includes(marker)) process.exit(0);
+
+        process.stdout.write(JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "allow",
+            permissionDecisionReason: "subagent-return-channel-guard: delivery contract appended to spawn prompt",
+            updatedInput: {
+              ...toolInput,
+              prompt: toolInput.prompt + contract,
+            },
+          },
+        }) + "\n");
+        process.exit(0);
+      }
+
+      if (toolName === "SendUserMessage") {
+        const agentId = String(input.agent_id ?? "");
+        const transcriptPath = String(input.transcript_path ?? "");
+        if (!agentId && !transcriptPath.includes("/subagents/agent-")) process.exit(0);
+
+        process.stdout.write(JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "deny",
+            permissionDecisionReason: "subagent-return-channel-guard: SendUserMessage from a spawned subagent does not reach the caller Agent tool result. Put the full report in final text and end the subagent turn.",
+          },
+        }) + "\n");
+      }
+    } catch {
+      process.exit(0);
+    }
+  ' 2>/dev/null || true
+  exit 0
+fi
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+tool_name="$(printf '%s' "$input" | jq -r '.tool_name // empty' 2>/dev/null || true)"
+case "$tool_name" in
+  Task|Agent)
+    printf '%s' "$input" | jq -e '.tool_input | type == "object"' >/dev/null 2>&1 || exit 0
+    printf '%s' "$input" | jq -e '.tool_input.prompt | type == "string"' >/dev/null 2>&1 || exit 0
+    if printf '%s' "$input" | jq -e --arg marker "$CONTRACT_MARKER" '.tool_input.prompt | contains($marker)' >/dev/null 2>&1; then
+      exit 0
+    fi
+
+    printf '%s' "$input" | jq -c --arg contract "$CONTRACT_TEXT" '
+      .tool_input as $toolInput
+      | {
+          hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "allow",
+            permissionDecisionReason: "subagent-return-channel-guard: delivery contract appended to spawn prompt",
+            updatedInput: ($toolInput + {prompt: ($toolInput.prompt + $contract)})
+          }
+        }'
+    ;;
+  SendUserMessage)
+    agent_id="$(printf '%s' "$input" | jq -r '.agent_id // empty' 2>/dev/null || true)"
+    transcript_path="$(printf '%s' "$input" | jq -r '.transcript_path // empty' 2>/dev/null || true)"
+    [[ -n "$agent_id" || "$transcript_path" == *"/subagents/agent-"* ]] || exit 0
+
+    jq -nc '{
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: "subagent-return-channel-guard: SendUserMessage from a spawned subagent does not reach the caller Agent tool result. Put the full report in final text and end the subagent turn."
+      }
+    }'
+    ;;
+esac

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

@@ -44,13 +44,13 @@
 - 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.
-- Capture decision-complete Codex Plan mode, Waza `/think`, or `repo-harness-plan` outputs with `scripts/capture-plan.sh --slug <slug> --title <title>` so planning becomes a `plans/` artifact before implementation.
+- Treat contract-level execution as worktree-first: `.ai/harness/scripts/plan-to-todo.sh --plan <approved-plan>` starts a linked `codex/<slug>` worktree when policy enables it, and `.ai/harness/scripts/contract-worktree.sh finish` merges back only after Waza `/check` and sprint verification pass.
+- Capture decision-complete Codex Plan mode, Waza `/think`, or `repo-harness-plan` outputs with `.ai/harness/scripts/capture-plan.sh --slug <slug> --title <title>` so planning becomes a `plans/` artifact before implementation.
 - Route product discovery to gstack `office-hours`, complex engineering plans to gstack `plan-eng-review`, design plans to gstack `plan-design-review`, and daily small/medium planning, bug hunts, and checks to Waza `/think`, `/hunt`, and `/check`.
 - Route knowledge sync and handoff retrieval to `gbrain`.
-- Register valuable repo-authored docs in `.ai/harness/brain-manifest.json` with `sync.direction=repo-to-brain`; `scripts/sync-brain-docs.sh` and the PostEdit hook mirror only those explicit entries into the default brain vault.
+- Register valuable repo-authored docs in `.ai/harness/brain-manifest.json` with `sync.direction=repo-to-brain`; `.ai/harness/scripts/sync-brain-docs.sh` and the PostEdit hook mirror only those explicit entries into the default brain vault.
 - Codex automation profile is runtime-referenced, not vendored: required skills are `health`, `check`, and `mermaid` from `~/.codex/skills`.
 - CodeGraph is required agent readiness for code navigation; keep `.codegraph/` ignored and use it for P1/P2 discovery, not hook correctness.
 - Treat Waza as Codex-first: `~/.codex/skills` is the Codex runtime source; `~/.agents/skills` is skills CLI staging/cache only.
-- Use `docs/reference-configs/agentic-development-flow.md` for routing details and `docs/reference-configs/external-tooling.md` plus `bash scripts/check-agent-tooling.sh --host both --check-updates` for environment checks.
+- Use `docs/reference-configs/agentic-development-flow.md` for routing details and `docs/reference-configs/external-tooling.md` plus `bash .ai/harness/scripts/check-agent-tooling.sh --host both --check-updates` for environment checks.
 - If repo state conflicts with the task, use an isolated `codex/<task-slug>` worktree, validate with Waza `/check`, and merge back to `main` without unrelated dirty changes.