repo-harness 0.6.0 → 0.7.0

package/.agents/skills/repo-harness-chatgpt-browser/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: repo-harness-chatgpt-browser
+description: Use when the user wants Codex to consult their logged-in ChatGPT Web session through repo-harness browser engine for planning, architecture review, PRD critique, or Codex goal generation.
+---
+
+# repo-harness ChatGPT Browser
+
+Use this skill when the user asks to consult ChatGPT Web, GPT Pro, browser GPT, or a logged-in ChatGPT account through repo-harness.
+
+## Rules
+
+1. This uses the user's logged-in ChatGPT Web browser session, not the OpenAI API.
+2. Do not ask for or handle passwords, SSO secrets, 2FA codes, cookies, browser storage, or tokens.
+3. Before a non-dry-run consult, state that it may create or continue a real ChatGPT Web conversation.
+4. Prefer dry-run first when files are involved:
+
+```bash
+repo-harness chatgpt browser-consult --repo . --dry-run --prompt "<prompt>" --file <path>
+```
+
+5. For readiness, run:
+
+```bash
+repo-harness chatgpt browser-doctor --repo .
+```
+
+6. Use browser consult for planning, review, critique, and goal generation. Do not use it as the executor for code edits.
+7. Save useful results into repo-harness artifacts with repo-relative `--write-output` paths such as:
+
+```text
+.ai/harness/handoff/chatgpt-review.md
+.ai/harness/handoff/codex-goal.md
+plans/prds/*.prd.md
+plans/sprints/*.sprint.md
+```
+
+8. If login, captcha, workspace picker, or SSO is required, stop and ask the user to complete it in the browser.
+9. Do not enable remote CDP unless the user explicitly asked for remote browser control and the security boundary is documented.
+10. For MCP usage, require the server to be started with:
+
+```bash
+repo-harness mcp serve --repo . --enable-chatgpt-browser
+```
+
+11. Do not rely on provider stdout `Artifact:` / `Output:` paths being imported. Browser engine session records save prompt, transcript, output, metadata, and trusted provider IDs; ordinary stdout paths are ignored.
+12. Native provider uses the current ChatGPT Web model selection. Do not pass `--model` or `--thinking` with `--provider native`; use Oracle when model selection is required.
+
+## Common Commands
+
+Dry-run consult:
+
+```bash
+repo-harness chatgpt browser-consult \
+  --repo . \
+  --dry-run \
+  --prompt "Review this sprint and return execution risks." \
+  --file plans/sprints/example.sprint.md
+```
+
+Oracle provider consult:
+
+```bash
+repo-harness chatgpt browser-consult \
+  --repo . \
+  --provider oracle \
+  --prompt "Review this PRD and return risks plus a smallest next step." \
+  --file plans/prds/example.prd.md \
+  --write-output .ai/harness/handoff/chatgpt-review.md
+```
+
+Native provider spike:
+
+```bash
+repo-harness chatgpt browser-doctor --repo . --provider native
+repo-harness chatgpt browser-consult \
+  --repo . \
+  --provider native \
+  --browser-channel chrome \
+  --keep-browser \
+  --prompt "Reply exactly OK"
+```
+
+Use native provider only when the user is ready for a visible ChatGPT Web run. If login is required, keep the browser open and have the user complete login manually; do not request or handle credentials.
+
+Read the result:
+
+```bash
+repo-harness chatgpt browser-list --repo .
+repo-harness chatgpt browser-session --repo . <sessionId>
+repo-harness chatgpt browser-open --repo . <sessionId>
+```
+
+Continue from a saved session:
+
+```bash
+repo-harness chatgpt browser-followup \
+  --repo . \
+  --session <sessionId> \
+  --prompt "Challenge the previous result and return the smallest next step."
+```
+
+Plan cleanup before deleting local session records:
+
+```bash
+repo-harness chatgpt browser-cleanup --repo . --status dry_run --limit 20
+```

package/README.es.md

@@ -56,17 +56,17 @@ En un repositorio adoptado, la superficie se mantiene pequeña:
 | `tasks/contracts/`, `tasks/reviews/` y `.ai/harness/checks/` | Scope, verificación y evidencia de review para probar que el trabajo terminó. |
 | `.ai/harness/handoff/` y `tasks/current.md` | Session journal y estado resumible, derivados de workflow artifacts en vez de chat memory. |
 
-## Novedades en 0.6.0
-
-- **Transactional adoption plans.** `repo-harness adopt --dry-run --json` ahora
-  emite un operation plan protocol v1 con IDs estables, summary, content hashes
-  y rollback metadata.
-- **Bootstrap files gestionados por el manifest.** Los templates iniciales
-  `docs/spec.md`, `tasks/todos.md`, `tasks/current.md` y `tasks/lessons.md`
-  ahora salen del workflow contract manifest, no de strings locales del planner.
-- **Apply TypeScript experimental.** `repo-harness adopt --experimental-ts-apply`
-  puede aplicar el safe operation subset con atomic writes, target locks,
-  backups y preflight rejection para boundaries self-host no soportadas.
+## Novedades en 0.7.0
+
+- **ChatGPT browser engine.** `repo-harness chatgpt browser-*` crea sesiones
+  ChatGPT Web repo-locales con archivos revisados por policy, sin usar OpenAI API.
+- **MCP browser tools opt-in.** `repo-harness mcp serve
+  --enable-chatgpt-browser` expone consult/read/list/continue/open; por defecto
+  estos tools siguen desactivados.
+- **Oracle y native providers.** El engine incluye un Oracle browser wrapper y
+  un spike native vía Chrome instalado + CDP local.
+- **Hosted CI y release smoke.** El repo añade un GitHub CI gate y un tarball
+  install smoke que arranca los binarios empaquetados de `repo-harness`.
 
 ## Qué hace el producto
 
@@ -383,8 +383,8 @@ Guards habituales:
 
 ## Release actual
 
-- npm package: `repo-harness@0.6.0`
-- Generated workflow stamp: `repo-harness@0.6.0+template@0.6.0`
+- npm package: `repo-harness@0.7.0`
+- Generated workflow stamp: `repo-harness@0.7.0+template@0.7.0`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.fr.md

@@ -56,18 +56,17 @@ Dans un dépôt adopté, la surface à comprendre reste volontairement réduite
 | `tasks/contracts/`, `tasks/reviews/` et `.ai/harness/checks/` | Scope, vérification et preuves de review pour démontrer que le travail est terminé. |
 | `.ai/harness/handoff/` et `tasks/current.md` | Session journal et état resumable dérivés des workflow artifacts plutôt que de la chat memory. |
 
-## Nouveautés de la 0.6.0
-
-- **Transactional adoption plans.** `repo-harness adopt --dry-run --json` émet
-  maintenant un operation plan protocol v1 avec IDs stables, summary, content
-  hashes et rollback metadata.
-- **Bootstrap files gérés par le manifest.** Les templates initiaux
-  `docs/spec.md`, `tasks/todos.md`, `tasks/current.md` et `tasks/lessons.md`
-  viennent désormais du workflow contract manifest plutôt que de strings locales
-  au planner.
-- **Apply TypeScript expérimental.** `repo-harness adopt --experimental-ts-apply`
-  peut appliquer le safe operation subset avec atomic writes, target locks,
-  backups et preflight rejection des boundaries self-host non prises en charge.
+## Nouveautés de la 0.7.0
+
+- **ChatGPT browser engine.** `repo-harness chatgpt browser-*` crée des sessions
+  ChatGPT Web repo-locales avec des fichiers contrôlés par policy, sans OpenAI API.
+- **MCP browser tools opt-in.** `repo-harness mcp serve
+  --enable-chatgpt-browser` expose consult/read/list/continue/open, désactivés
+  par défaut.
+- **Oracle et native providers.** Le moteur inclut un Oracle browser wrapper et
+  un spike native via Chrome installé et CDP local.
+- **Hosted CI et release smoke.** Le dépôt ajoute un GitHub CI gate et un
+  tarball install smoke qui démarre les binaires packagés `repo-harness`.
 
 ## Ce que fait le produit
 
@@ -388,8 +387,8 @@ Guards courants :
 
 ## Release actuelle
 
-- npm package : `repo-harness@0.6.0`
-- Generated workflow stamp : `repo-harness@0.6.0+template@0.6.0`
+- npm package : `repo-harness@0.7.0`
+- Generated workflow stamp : `repo-harness@0.7.0+template@0.7.0`
 - GitHub repository : `Ancienttwo/repo-harness`
 - Release history : [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.ja.md

@@ -47,11 +47,12 @@ Agent に完全な PRD または Sprint を渡せば、あとは review and `nex
 | `tasks/contracts/`, `tasks/reviews/`, `.ai/harness/checks/` | 作業完了を証明する scope、verification、review evidence。 |
 | `.ai/harness/handoff/` と `tasks/current.md` | chat memory ではなく workflow artifacts から派生する session journal と resumable status。 |
 
-## 0.6.0 の新機能
+## 0.7.0 の新機能
 
-- **Transactional adoption plans。** `repo-harness adopt --dry-run --json` は、安定した ID、summary、content hash、rollback metadata を含む protocol v1 operation plan を出力します。
-- **Manifest-owned bootstrap files。** 初期 `docs/spec.md`、`tasks/todos.md`、`tasks/current.md`、`tasks/lessons.md` templates は、planner-local strings ではなく workflow contract manifest から来るようになりました。
-- **Experimental TypeScript apply。** `repo-harness adopt --experimental-ts-apply` は、atomic writes、target locks、backups、unsupported self-host boundary の preflight rejection を使って safe operation subset を適用できます。
+- **ChatGPT browser engine。** `repo-harness chatgpt browser-*` は、OpenAI API を使わず、policy-checked な repo-local ChatGPT Web consult session を作れます。
+- **Opt-in MCP browser tools。** `repo-harness mcp serve --enable-chatgpt-browser` のときだけ consult/read/list/continue/open tools を公開し、デフォルトでは無効です。
+- **Oracle and native providers。** Oracle browser wrapper と、installed Chrome + local CDP を使う native spike を含みます。
+- **Hosted CI and release smoke。** GitHub CI gate と、packaged `repo-harness` binaries を起動する tarball install smoke を追加しました。
 
 ## repo-harness は何をするか
 
@@ -351,8 +352,8 @@ hook がブロックしたときは、まず terminal の構造化された出
 
 ## 現在の Release
 
-- npm package：`repo-harness@0.6.0`
-- Generated workflow stamp：`repo-harness@0.6.0+template@0.6.0`
+- npm package：`repo-harness@0.7.0`
+- Generated workflow stamp：`repo-harness@0.7.0+template@0.7.0`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.md

@@ -50,17 +50,43 @@ In an adopted repo, the surface area is intentionally small:
 | `tasks/contracts/`, `tasks/reviews/`, and `.ai/harness/checks/` | Scope, verification, and review evidence for proving the work is done. |
 | `.ai/harness/handoff/` and `tasks/current.md` | Session journal and resumable status, derived from workflow artifacts instead of chat memory. |
 
-## What's New in 0.6.0
-
-- **Transactional adoption plans.** `repo-harness adopt --dry-run --json` now
-  emits a protocol v1 operation plan with stable IDs, summaries, content hashes,
-  and rollback metadata.
-- **Manifest-owned bootstrap files.** The initial `docs/spec.md`,
-  `tasks/todos.md`, `tasks/current.md`, and `tasks/lessons.md` templates now
-  come from the workflow contract manifest instead of planner-local strings.
-- **Experimental TypeScript apply.** `repo-harness adopt --experimental-ts-apply`
-  can apply the safe operation subset with atomic writes, target locks, backups,
-  and preflight rejection for unsupported self-host boundaries.
+## Human Review Path
+
+Start with `tasks/reviews/<task>.review.md`. The `## Human Review Card` is the
+one-screen decision surface: verdict, change type, intended vs actual files,
+commands passed, external acceptance, residual risk, reviewer action, and
+rollback. Then inspect the active contract, latest trace in
+`.ai/harness/checks/latest.json`, and the changed files. Accept only when the
+review recommends pass, the card verdict is pass, and external acceptance is
+pass, `not_required`, or an explicit manual override.
+
+## Agent Tracking Path
+
+Agents read source artifacts before derived summaries:
+
+| Agent reads first | Human reviews first |
+| --- | --- |
+| Current user prompt and referenced files | `tasks/reviews/<task>.review.md` Human Review Card |
+| `AGENTS.md` / `CLAUDE.md` | Changed files and diff |
+| Active plan in `.ai/harness/active-plan` | Active contract allowed paths and exit criteria |
+| Active contract in `tasks/contracts/` | `.ai/harness/checks/latest.json` and run trace |
+| Latest handoff in `.ai/harness/handoff/` | Residual risks and rollback |
+
+`tasks/current.md` is only an orientation snapshot. If it disagrees with the
+active plan, contract, review, checks, or handoff, the source artifacts win.
+
+## What's New in 0.7.0
+
+- **ChatGPT browser engine.** `repo-harness chatgpt browser-*` can create
+  policy-checked, repo-local ChatGPT Web consult sessions without using the
+  OpenAI API.
+- **Opt-in MCP browser tools.** `repo-harness mcp serve
+  --enable-chatgpt-browser` exposes consult/read/list/continue/open tools while
+  keeping them disabled by default.
+- **Oracle and native providers.** The engine supports an Oracle browser wrapper
+  plus a native installed-Chrome CDP spike for logged-in ChatGPT Web runs.
+- **Hosted CI and release smoke.** The repo now ships a GitHub CI gate and a
+  tarball install smoke that starts the packaged `repo-harness` binaries.
 
 ## What repo-harness Does
 
@@ -74,11 +100,71 @@ target repository so Claude, Codex, and humans can agree on:
 - which checks and review evidence prove the work is done
 - how hooks should warn, block, trace, and hand off work across sessions
 
-It is not an agent gateway, product runtime, database service, or MCP server.
 The product boundary is deliberately boring: inspect a repo, install or refresh
 workflow files, route host events through repo-local hooks, and verify that the
 workflow surfaces stay consistent.
 
+As an optional sidecar, `repo-harness mcp` exposes only workflow artifacts to
+MCP clients. ChatGPT can use it as a planner/reviewer to read state and move an
+idea through PRD, checklist Sprint, and Codex goal handoff artifacts; it does
+not get source-code write access, arbitrary shell execution, or a default Codex
+runner. Codex remains the executor. The generated manual setup guide lives at
+`docs/repo-harness-chatgpt-mcp-setup.md`, and the local CLI handoff is
+`repo-harness mcp prepare-goal --prd <prd> --sprint <sprint>`.
+
+### MCP Connector Quickstart
+
+Use the MCP sidecar when you want ChatGPT to plan against the real repo state
+and Codex to execute the resulting file-backed Sprint.
+
+```bash
+repo-harness mcp setup chatgpt --repo .
+repo-harness mcp serve --repo . --transport http --host 127.0.0.1 --port 8765 --profile planner
+```
+
+Expose that local server through an HTTPS tunnel and create a ChatGPT Connector
+with the `/mcp` URL. The generated guide is written to:
+
+```text
+docs/repo-harness-chatgpt-mcp-setup.md
+```
+
+The human workflow is:
+
+1. ChatGPT reads repo-harness workflow files through MCP.
+2. ChatGPT writes a PRD with `write_prd_from_idea`.
+3. ChatGPT writes a checklist Sprint with `write_checklist_sprint`.
+4. ChatGPT prepares `.ai/harness/handoff/codex-goal.md` with `prepare_codex_goal_from_sprint`.
+5. Codex runs the host-native `/goal` prompt and stages each completed Sprint phase.
+
+Local fallback for the last handoff step:
+
+```bash
+repo-harness mcp prepare-goal --repo . --prd plans/prds/<feature>.prd.md --sprint plans/sprints/<feature>.sprint.md
+```
+
+The agent-facing Skill is installed at:
+
+```text
+.agents/skills/repo-harness-chatgpt-bridge/SKILL.md
+```
+
+That Skill tells Codex how to consume ChatGPT-produced PRD/Sprint/Goal artifacts
+without granting ChatGPT source-code writes or shell execution.
+
+Dev Mode can opt into local agent execution through MCP. This is off by default.
+When the user enables the `orchestrator` profile with the dev runner setting,
+ChatGPT can call `run_agent_goal`, which reads only
+`.ai/harness/handoff/codex-goal.md` and runs the fixed handoff through an
+allowed local CLI such as `codex exec` or `claude -p`.
+
+```bash
+repo-harness mcp serve --repo . --transport http --profile orchestrator --enable-dev-runner --dev-runner-agents codex
+```
+
+This setting is for local Developer Mode only. It is timeout-bounded, audited,
+and not arbitrary shell.
+
 ## How It Works
 
 The design has three layers:
@@ -464,8 +550,8 @@ Most common guards:
 
 ## Current Release
 
-- npm package: `repo-harness@0.6.0`
-- Generated workflow stamp: `repo-harness@0.6.0+template@0.6.0`
+- npm package: `repo-harness@0.7.0`
+- Generated workflow stamp: `repo-harness@0.7.0+template@0.7.0`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.zh-CN.md

@@ -43,16 +43,40 @@ handoff、检查结果和 review evidence 写回项目文件，让下一个 agen
 | `tasks/contracts/`、`tasks/reviews/`、`.ai/harness/checks/` | 证明完成所需的 scope、verification 和 review evidence。 |
 | `.ai/harness/handoff/` 和 `tasks/current.md` | session journal 与可恢复状态，从 workflow artifacts 派生，而不是依赖聊天记忆。 |
 
-## 0.6.0 新特性
+## Human Review Path
 
-- **事务型 adoption plan。** `repo-harness adopt --dry-run --json` 现在输出
-  protocol v1 operation plan，包含稳定 ID、summary、content hash 和 rollback metadata。
-- **Manifest-owned bootstrap 文件。** 初始 `docs/spec.md`、`tasks/todos.md`、
-  `tasks/current.md`、`tasks/lessons.md` 模板改由 workflow contract manifest 管理，
-  不再放在 planner 本地字符串里。
-- **实验性 TypeScript apply。** `repo-harness adopt --experimental-ts-apply`
-  可以执行 safe operation subset，并使用 atomic write、target lock、backup 和
-  unsupported self-host boundary preflight。
+先读 `tasks/reviews/<task>.review.md`。`## Human Review Card` 是一屏决策面：
+verdict、change type、预期/实际改动文件、已通过命令、external acceptance、
+残余风险、reviewer action 和 rollback。然后检查 active contract、
+`.ai/harness/checks/latest.json` 里的 latest trace，以及实际 diff。只有当 review
+recommend pass、card verdict 为 pass，且 external acceptance 为 pass、not_required
+或明确 manual override 时，才进入 closeout。
+
+## Agent Tracking Path
+
+Agent 先读 source artifacts，再读派生摘要：
+
+| Agent reads first | Human reviews first |
+| --- | --- |
+| 当前用户 prompt 和引用文件 | `tasks/reviews/<task>.review.md` 的 Human Review Card |
+| `AGENTS.md` / `CLAUDE.md` | changed files 和 diff |
+| `.ai/harness/active-plan` 指向的 active plan | active contract 的 allowed paths 和 exit criteria |
+| `tasks/contracts/` 下的 active contract | `.ai/harness/checks/latest.json` 和 run trace |
+| `.ai/harness/handoff/` 下的 latest handoff | 残余风险和 rollback |
+
+`tasks/current.md` 只是 orientation snapshot。如果它和 active plan、contract、
+review、checks 或 handoff 冲突，以 source artifacts 为准。
+
+## 0.7.0 新特性
+
+- **ChatGPT browser engine。** `repo-harness chatgpt browser-*` 可以用
+  policy-checked 文件输入创建 repo-local ChatGPT Web consult session，不走 OpenAI API。
+- **Opt-in MCP browser tools。** `repo-harness mcp serve
+  --enable-chatgpt-browser` 才会暴露 consult/read/list/continue/open 工具，默认关闭。
+- **Oracle 和 native provider。** Browser engine 支持 Oracle browser wrapper，
+  也支持基于本机已安装 Chrome CDP 的 logged-in ChatGPT Web spike。
+- **Hosted CI 和 release smoke。** 仓库新增 GitHub CI gate，并用 tarball install
+  smoke 验证 packaged `repo-harness` binaries 能启动。
 
 ## 产品做什么
 
@@ -418,8 +442,8 @@ hook block 工作时，先看 terminal 里的结构化输出。核心字段是
 
 ## 当前 Release
 
-- npm package：`repo-harness@0.6.0`
-- Generated workflow stamp：`repo-harness@0.6.0+template@0.6.0`
+- npm package：`repo-harness@0.7.0`
+- Generated workflow stamp：`repo-harness@0.7.0+template@0.7.0`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

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

@@ -362,9 +362,31 @@ workflow_preferred_or_legacy_path() {
   fi
 }
 
+workflow_plan_declared_path() {
+  local plan_file="$1"
+  local label="$2"
+  [[ -f "$plan_file" ]] || return 1
+  awk -v label="$label" '
+    BEGIN { pattern = "^> \\*\\*" label "\\*\\*:" }
+    $0 ~ pattern {
+      sub(pattern "[[:space:]]*", "")
+      gsub(/`/, "")
+      gsub(/\r/, "")
+      print
+      exit
+    }
+  ' "$plan_file" | xargs
+}
+
 derive_contract_path() {
   local plan_file="$1"
-  local stem slug
+  local stem slug explicit
+
+  explicit="$(workflow_plan_declared_path "$plan_file" "Task Contract" || workflow_plan_declared_path "$plan_file" "Sprint Contract" || true)"
+  if [[ -n "$explicit" ]]; then
+    printf '%s' "$explicit"
+    return 0
+  fi
 
   stem="$(workflow_plan_artifact_stem_from_path "$plan_file" || true)"
   slug="$(workflow_plan_slug_from_path "$plan_file" || true)"
@@ -574,6 +596,7 @@ workflow_next_action() {
 
     if [[ "$total" -gt "$done" ]]; then
       message="${next_pending:-continue active plan Task Breakdown}"
+      message="If a major module was just completed, stage its coherent diff first; then continue the next Task Breakdown item: ${message}"
       printf 'task\t-\t%s\n' "$message"
       return 0
     fi
@@ -583,17 +606,17 @@ workflow_next_action() {
     checks_file="$(workflow_checks_file)"
 
     if [[ -z "$review_file" || ! -f "$review_file" ]]; then
-      printf 'check\t/check\tRun /check and record a sprint review before finishing this worktree.\n'
+      printf 'check\t/check\tStage the completed module diff first; then run /check and record a sprint review before finishing this worktree.\n'
       return 0
     fi
 
     if ! workflow_review_recommends_pass "$review_file"; then
-      printf 'check\t/check\tRun /check until %s records Recommendation: pass.\n' "$review_file"
+      printf 'check\t/check\tStage the completed module diff first; then run /check until %s records Recommendation: pass.\n' "$review_file"
       return 0
     fi
 
     if [[ -z "$contract_file" || ! -f "$contract_file" ]]; then
-      printf 'check\t/check\tRegenerate the active sprint contract, then run /check.\n'
+      printf 'check\t/check\tStage the completed module diff first; then regenerate the active sprint contract and run /check.\n'
       return 0
     fi
 
@@ -601,17 +624,17 @@ workflow_next_action() {
     IFS=$'\t' read -r external_state external_reviewer external_source external_message <<< "$external_status"
     if [[ "$external_state" != "pass" && "$external_state" != "manual_override" ]]; then
       expected_source="$(workflow_external_acceptance_expected_source)"
-      printf 'check\t/check\t%s Run external acceptance via %s and record ## External Acceptance Advice in %s.\n' "${external_message:-External acceptance is missing.}" "$expected_source" "$review_file"
+      printf 'check\t/check\tStage the completed module diff first; then %s Run external acceptance via %s and record ## External Acceptance Advice in %s.\n' "${external_message:-External acceptance is missing.}" "$expected_source" "$review_file"
       return 0
     fi
 
     if [[ ! -f "$checks_file" ]]; then
-      printf 'check\t/check\tRun /check and verify-sprint so %s exists.\n' "$checks_file"
+      printf 'check\t/check\tStage the completed module diff first; then run /check and verify-sprint so %s exists.\n' "$checks_file"
       return 0
     fi
 
     if ! checks_error="$(workflow_checks_pass "$checks_file" "$contract_file" "$review_file")"; then
-      printf 'check\t/check\t%s\n' "$checks_error"
+      printf 'check\t/check\tStage the completed module diff first; then resolve check evidence: %s\n' "$checks_error"
       return 0
     fi
 
@@ -1053,9 +1076,14 @@ workflow_active_contract() {
 }
 
 workflow_active_review() {
-  local active_plan stem slug reviews_dir
+  local active_plan stem slug reviews_dir explicit
   active_plan="$(get_active_plan || true)"
   [[ -n "$active_plan" ]] || return 1
+  explicit="$(workflow_plan_declared_path "$active_plan" "Task Review" || workflow_plan_declared_path "$active_plan" "Sprint Review" || true)"
+  if [[ -n "$explicit" ]]; then
+    printf '%s' "$explicit"
+    return 0
+  fi
   stem="$(workflow_plan_artifact_stem_from_path "$active_plan" || true)"
   slug="$(workflow_plan_slug_from_path "$active_plan" || true)"
   [[ -n "$stem" && -n "$slug" ]] || return 1
@@ -1064,9 +1092,14 @@ workflow_active_review() {
 }
 
 workflow_active_notes() {
-  local active_plan stem slug notes_dir
+  local active_plan stem slug notes_dir explicit
   active_plan="$(get_active_plan || true)"
   [[ -n "$active_plan" ]] || return 1
+  explicit="$(workflow_plan_declared_path "$active_plan" "Implementation Notes" || workflow_plan_declared_path "$active_plan" "Notes File" || true)"
+  if [[ -n "$explicit" ]]; then
+    printf '%s' "$explicit"
+    return 0
+  fi
   stem="$(workflow_plan_artifact_stem_from_path "$active_plan" || true)"
   slug="$(workflow_plan_slug_from_path "$active_plan" || true)"
   [[ -n "$stem" && -n "$slug" ]] || return 1
@@ -1099,8 +1132,8 @@ workflow_with_lock() {
   while ! mkdir "$lock_dir" 2>/dev/null; do
     if [[ "$waited" -ge 40 ]]; then
       now="$(date +%s)"
-      mtime="$(stat -f '%m' "$lock_dir" 2>/dev/null || stat -c '%Y' "$lock_dir" 2>/dev/null || echo 0)"
-      if [[ "${mtime:-0}" -gt 0 && $((now - mtime)) -ge 60 ]]; then
+      mtime="$(stat -c '%Y' "$lock_dir" 2>/dev/null || stat -f '%m' "$lock_dir" 2>/dev/null || echo 0)"
+      if [[ "${mtime:-0}" =~ ^[0-9]+$ && "${mtime:-0}" -gt 0 && $((now - mtime)) -ge 60 ]]; then
         rmdir "$lock_dir" 2>/dev/null || true
         waited=0
         continue
@@ -1502,7 +1535,8 @@ workflow_write_handoff() {
   local reason="${1:-session-stop}"
   local handoff_file active_plan active_contract active_review active_notes checks_file next_task changed_files diff_stat spec_file source_plan parent_run_id supersedes
   local next_action next_stage next_command next_message
-  local resume_file trace_file recent_commands blockers decisions goal
+  local resume_file trace_file recent_commands blockers decisions goal latest_trace_file
+  local active_sprint active_sprint_row
   local changed_count untracked_count
 
   workflow_ensure_harness_surface
@@ -1514,6 +1548,26 @@ workflow_write_handoff() {
   active_contract="$(workflow_active_contract || true)"
   active_review="$(workflow_active_review || true)"
   active_notes="$(workflow_active_notes || true)"
+  active_sprint=""
+  if [[ -f ".ai/harness/sprint/active-sprint" ]]; then
+    active_sprint="$(cat ".ai/harness/sprint/active-sprint" 2>/dev/null | xargs)"
+  fi
+  active_sprint_row="(none)"
+  if [[ -n "$active_sprint" && -f "$active_sprint" ]]; then
+    active_sprint_row="$(
+      awk -v plan="$active_plan" '
+        /^\|[[:space:]]*[0-9]+[[:space:]]*\|/ {
+          if (plan != "" && index($0, plan) > 0) {
+            print
+            found = 1
+            exit
+          }
+        }
+        END { if (!found) exit 1 }
+      ' "$active_sprint" 2>/dev/null || true
+    )"
+    active_sprint_row="${active_sprint_row:-Active sprint: ${active_sprint}}"
+  fi
   source_plan="$(get_todo_source_plan || true)"
   if [[ "$source_plan" == "(none)" ]]; then
     source_plan=""
@@ -1585,6 +1639,12 @@ workflow_write_handoff() {
   fi
   decisions="Use filesystem artifacts as source of truth; treat SQLite/thread state as a rebuildable read model only."
   blockers="(none recorded)"
+  if [[ -f "$checks_file" ]] && command -v jq >/dev/null 2>&1; then
+    latest_trace_file="$(jq -r '.run_file // empty' "$checks_file" 2>/dev/null || true)"
+  else
+    latest_trace_file=""
+  fi
+  latest_trace_file="${latest_trace_file:-$checks_file}"
 
   cat > "$handoff_file" <<EOF_HANDOFF
 # Harness Handoff
@@ -1613,11 +1673,21 @@ ${recent_commands}
 ## Checks
 
 - Checks file: ${checks_file}
+- Latest trace: ${latest_trace_file}
 
 ## Blockers
 
 - ${blockers}
 
+## Active Artifacts
+
+- Active plan: ${active_plan:-(none)}
+- Active contract: ${active_contract:-(none)}
+- Active sprint row: ${active_sprint_row}
+- Review file: ${active_review:-(none)}
+- Latest trace/checks file: ${latest_trace_file}
+- Resume packet: ${resume_file}
+
 ## Exact Next Step
 
 - ${next_task}
@@ -1625,7 +1695,7 @@ ${recent_commands}
 ## Resume Prompt
 
 - Resume packet: ${resume_file}
-- Start a fresh Codex session and read this handoff before continuing; do not rely on auto-compact.
+- Start a fresh Codex session and read source artifacts first, then this handoff, before continuing; do not rely on auto-compact.
 
 ## Source Artifacts
 

package/assets/reference-configs/agentic-development-flow.md

@@ -58,6 +58,13 @@ work, or shared contracts, report the P1/P2/P3 evidence explicitly.
 
 ## Daily Flow
 
+| Agent reads first | Human reviews first |
+|-----------|---------|
+| Current user prompt and referenced files | Human Review Card in `tasks/reviews/<task>.review.md` |
+| `AGENTS.md` / `CLAUDE.md` and active plan | Changed files and active contract scope |
+| Active contract, notes, latest checks, and handoff | Latest trace/checks, residual risk, rollback |
+| `tasks/current.md` only for orientation | External acceptance or manual override |
+
 1. Route the request by intent before reading broadly.
 2. Read the repo-local contract first: `AGENTS.md` or `CLAUDE.md`, `tasks/todos.md`, `tasks/lessons.md`, and `.ai/harness/policy.json`.
 3. Use the selected skill or mode to produce either an approved plan, a root cause, or a review verdict.

package/assets/reference-configs/document-generation.md

@@ -31,6 +31,7 @@ Create these only when the agent has concrete repo evidence or the user asks:
 - Prefer short docs that name sources, owners, and verification commands.
 - Let capability `CLAUDE.md` and `AGENTS.md` carry local contract projections; root docs stay concise.
 - Keep complete workstream TODOs in `tasks/workstreams/<domain>/<capability>/`; contract blocks should link to them instead of becoming task logs.
+- Keep onboarding docs split by reader: agents read active source artifacts first; humans review the Human Review Card, diff, latest trace, and rollback first.
 - Hooks may create `docs/architecture/requests/*.md`; agents own semantic snapshots, embedded Mermaid, and optional `mermaid` HTML output.
 - Archive handled architecture requests with `.ai/harness/scripts/archive-architecture-request.sh`; keep `docs/architecture/requests/` pending-only and preserve handled requests under `docs/architecture/requests/archive/YYYY/`.
 - When both Mermaid and HTML exist, keep the Mermaid in Markdown as the semantic source and make the HTML link back to that Markdown source.