repo-harness 0.8.0 → 0.8.2

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

@@ -33,7 +33,7 @@ repo-harness chatgpt browser-setup --repo . --profile-dir <user-selected-chrome-
 repo-harness chatgpt browser-doctor --repo . --provider oracle --json
 ```
 
-The Oracle path must fail closed rather than silently falling back to an unbound/default browser session. Use `browser-bind` only when the user explicitly asks for the experimental bridge provider; then report the printed `Local authorization URL: http://127.0.0.1:...` and `bridgeExtension=...`, keep the command running while they authorize, and stop it before `browser-consult --provider bridge`.
+The Oracle path must fail closed rather than silently falling back to an unbound/default browser session. Do not route through the removed Chrome extension provider or `browser-bind`.
 9. Use browser consult for planning, review, critique, and goal generation. Do not use it as the executor for code edits.
 10. Save useful results into repo-harness artifacts with repo-relative, timestamped `--write-output` paths such as:
 
@@ -53,7 +53,7 @@ repo-harness mcp serve --repo . --enable-chatgpt-browser
 ```
 
 14. 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.
-15. Native and bridge providers use the current ChatGPT Web model selection. Do not pass `--model` or `--thinking` with `--provider native` or `--provider bridge`; use Oracle when model selection is required.
+15. The 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
 
@@ -79,19 +79,14 @@ repo-harness chatgpt browser-consult \
   --write-output ".ai/harness/handoff/chatgpt-review-${stamp}.md"
 ```
 
-Bridge provider for an existing signed-in profile:
+Native diagnostics for a non-default automation profile:
 
 ```bash
-repo-harness chatgpt browser-doctor --repo . --provider bridge
-repo-harness chatgpt browser-setup --repo . --profile-dir <user-selected-chrome-profile-dir> --browser-channel chrome
-repo-harness chatgpt browser-bind --repo . --open
-repo-harness chatgpt browser-consult \
-  --repo . \
-  --provider bridge \
-  --prompt "Reply exactly OK"
+repo-harness chatgpt browser-setup --repo . --profile-dir <non-default-automation-user-data-dir> --browser-channel chrome
+repo-harness chatgpt browser-doctor --repo . --provider native --validate-session
 ```
 
-Use bridge/native providers only when the user is ready for a visible ChatGPT Web run. If login is required, have the user complete it from the local authorization page; do not request or handle credentials.
+Use native only when the user is ready for a visible ChatGPT Web diagnostic run. If login is required, have the user complete it in the selected non-default browser profile; do not request or handle credentials.
 
 Read the result:
 

package/AGENTS.md

@@ -30,11 +30,14 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 - Keep `assets/workflow-contract.v1.json` and `.ai/harness/workflow-contract.json` in sync.
 - Keep `CLAUDE.md` and `AGENTS.md` short; put detailed guidance in `docs/reference-configs/`.
 - Treat Codex auto-compact as a fallback only; use `.ai/harness/handoff/current.md` and `.ai/harness/handoff/resume.md` for long-task rollover.
+- Treat `.ai/harness/checks/*.latest.{json,md}` and `.ai/harness/runs/` as ignored runtime evidence cache; commit durable conclusions in `tasks/reviews/`, `tasks/contracts/`, `tasks/notes/`, or `docs/researches/` instead.
+- Treat architecture/spec/research docs as the human reading entrypoint. Before closing a workflow, promote durable conclusions into `docs/architecture/`, `docs/researches/`, `docs/spec.md`, or `tasks/lessons.md`; then archive fulfilled plan/contract/review/notes/todo artifacts so root workflow surfaces represent active work only. `.rgignore` hides archived workflow artifacts and runtime evidence from default `rg` searches; use explicit paths or `rg -uu` for audits.
 - Treat `_ref/` as an occasional ignored external reference checkout cache, not a commit surface or daily workflow. Agents may read or refresh it for comparison; when it influences a decision, cite the source repo plus commit/tag and path in `tasks/notes/` or `docs/researches/`.
 - Treat `deploy/` as the trackable deployment and operations surface for runbooks, submission materials, release checklists, helper scripts, ordered SQL files under `deploy/sql/`, and env examples.
 - Treat `_ops/` as ignored local operations state for secrets, real env files, provider state, artifacts, logs, and scratch files; do not commit or agent-edit `_ops/*`.
 - Treat contract-level task execution as worktree-first: `scripts/plan-to-todo.sh --plan <approved-plan>` starts `scripts/contract-worktree.sh start --plan <approved-plan>` when policy enables it, and completed blocks finish through Waza `/check` plus `scripts/contract-worktree.sh finish`.
-- After Codex Plan mode, Waza `/think`, or `repo-harness-plan` produces a decision-complete plan, capture it with `scripts/capture-plan.sh --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` or run `scripts/plan-to-todo.sh --plan <active-plan>`.
+- After Codex Plan mode, Waza `/think`, or `repo-harness-plan` produces a decision-complete work-package plan, capture it with `scripts/capture-plan.sh --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 `scripts/plan-to-todo.sh --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.
 - 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`.
 - Codex automation profile is runtime-referenced, not vendored: required skills are `health`, `check`, and `diagram-design` from `~/.codex/skills`.

package/CLAUDE.md

@@ -30,11 +30,14 @@ This repository self-hosts the `repo-harness` contract; the former `repo-harness
 - Keep `assets/workflow-contract.v1.json` and `.ai/harness/workflow-contract.json` in sync.
 - Keep `CLAUDE.md` and `AGENTS.md` short; put detailed guidance in `docs/reference-configs/`.
 - Treat Codex auto-compact as a fallback only; use `.ai/harness/handoff/current.md` and `.ai/harness/handoff/resume.md` for long-task rollover.
+- Treat `.ai/harness/checks/*.latest.{json,md}` and `.ai/harness/runs/` as ignored runtime evidence cache; commit durable conclusions in `tasks/reviews/`, `tasks/contracts/`, `tasks/notes/`, or `docs/researches/` instead.
+- Treat architecture/spec/research docs as the human reading entrypoint. Before closing a workflow, promote durable conclusions into `docs/architecture/`, `docs/researches/`, `docs/spec.md`, or `tasks/lessons.md`; then archive fulfilled plan/contract/review/notes/todo artifacts so root workflow surfaces represent active work only. `.rgignore` hides archived workflow artifacts and runtime evidence from default `rg` searches; use explicit paths or `rg -uu` for audits.
 - Treat `_ref/` as an occasional ignored external reference checkout cache, not a commit surface or daily workflow. Agents may read or refresh it for comparison; when it influences a decision, cite the source repo plus commit/tag and path in `tasks/notes/` or `docs/researches/`.
 - Treat `deploy/` as the trackable deployment and operations surface for runbooks, submission materials, release checklists, helper scripts, ordered SQL files under `deploy/sql/`, and env examples.
 - Treat `_ops/` as ignored local operations state for secrets, real env files, provider state, artifacts, logs, and scratch files; do not commit or agent-edit `_ops/*`.
 - Treat contract-level task execution as worktree-first: `scripts/plan-to-todo.sh --plan <approved-plan>` starts `scripts/contract-worktree.sh start --plan <approved-plan>` when policy enables it, and completed blocks finish through Waza `/check` plus `scripts/contract-worktree.sh finish`.
-- After Codex Plan mode, Waza `/think`, or `repo-harness-plan` produces a decision-complete plan, capture it with `scripts/capture-plan.sh --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` or run `scripts/plan-to-todo.sh --plan <active-plan>`.
+- After Codex Plan mode, Waza `/think`, or `repo-harness-plan` produces a decision-complete work-package plan, capture it with `scripts/capture-plan.sh --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 `scripts/plan-to-todo.sh --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.
 - 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`.
 - Codex automation profile is runtime-referenced, not vendored: required skills are `health`, `check`, and `diagram-design` from `~/.codex/skills`.

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.0`.
+actual es `0.8.2`.
 
 ## Cómo funciona
 
@@ -419,8 +419,8 @@ Guards habituales:
 
 ## Release actual
 
-- npm package: `repo-harness@0.8.0`
-- Generated workflow stamp: `repo-harness@0.8.0+template@0.8.0`
+- npm package: `repo-harness@0.8.2`
+- Generated workflow stamp: `repo-harness@0.8.2+template@0.8.2`
 - 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.0`.
+ligne actuelle est `0.8.2`.
 
 ## Comment ça marche
 
@@ -424,8 +424,8 @@ Guards courants :
 
 ## Release actuelle
 
-- npm package : `repo-harness@0.8.0`
-- Generated workflow stamp : `repo-harness@0.8.0+template@0.8.0`
+- npm package : `repo-harness@0.8.2`
+- Generated workflow stamp : `repo-harness@0.8.2+template@0.8.2`
 - 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.0` です。
+ラインは `0.8.2` です。
 
 ## 仕組み
 
@@ -398,8 +398,8 @@ hook がブロックしたときは、まず terminal の構造化された出
 
 ## 現在の Release
 
-- npm package：`repo-harness@0.8.0`
-- Generated workflow stamp：`repo-harness@0.8.0+template@0.8.0`
+- npm package：`repo-harness@0.8.2`
+- Generated workflow stamp：`repo-harness@0.8.2+template@0.8.2`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.md

@@ -30,9 +30,10 @@ Repository: `https://github.com/Ancienttwo/repo-harness`
   Codex, now and later — stay coordinated through the repo, not a thread.
   `.ai/hooks/session-start-context.sh` injects the prior session's resume packet
   (`.ai/harness/handoff/resume.md`, `tasks/current.md`) when a new session starts;
-  `finalize-handoff.sh` and `post-edit-guard.sh` write the next handoff back on stop
-  and after edits. A session can end mid-task and the next one resumes the exact next
-  step, blockers, and changed files without re-deriving them.
+  `stop-orchestrator.sh` writes the stop handoff, while `post-edit-guard.sh`
+  refreshes edit-time traces and task status after changes. A session can end
+  mid-task and the next one resumes the exact next step, blockers, and changed
+  files without re-deriving them.
 - **Token-lean by design.** Instead of grep-and-read loops that re-scan the repo every
   session, the harness leans on a pre-built CodeGraph index for structural queries
   (callers, callees, definitions) and on progressive context loading via
@@ -78,7 +79,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.0`.
+is `0.8.2`.
 
 ## How It Works
 
@@ -348,16 +349,78 @@ before applying anything.
 As an optional sidecar, `repo-harness mcp` exposes workflow artifacts to MCP
 clients through the default `planner` profile. ChatGPT acts as a
 planner/reviewer that reads state and moves an idea through PRD, checklist
-Sprint, and Codex goal handoff artifacts — with no source-code write access,
+Sprint, and Codex goal handoff artifacts — with no default source-code write access,
 arbitrary shell execution, or default Codex runner. Codex remains the executor.
 
-The same `planner` Connector also exposes read-only workspace tools for
-registered adopted repos. Use `discover_harness_repos` first, then pass
-`repo_path` to workflow tools and use `list_allowed_roots`, `open_workspace`,
-`tree`, `search_text`, and `read_text` to inspect non-ignored docs/source while
-retaining deny rules for secrets, private keys, `.git`, and dependency/build
-output. External non-repo local roots require explicit `--allow-root`
-authorization.
+The same `planner` Connector also exposes general repo tools for
+registered adopted repos. Use `discover_harness_repos` first, then call
+`list_allowed_roots` to get the stable `repo_id`. General repo reads use
+`repo_manifest`, `list_tree`, `stat_file`, `read_file`, `read_files`, and
+`search_text`. The write surface currently exposes `write_file`, `apply_patch`,
+`move_path`, `delete_path`, and `refresh_repo_index`, all rejected unless that
+registered repo is explicitly configured as `read_write`.
+`write_file` creates only with `must_not_exist: true`, replaces only with
+`expected_sha256`, and reports `before`, `after`, `diff`, `mutation_id`, and
+`index_state` after an atomic same-directory rename. `apply_patch` operates only
+on existing text files, requires `expected_sha256`, and accepts either structured
+`old_text`/`new_text` edits or guarded unified diff hunks. Patch precondition
+misses and stale hashes return `REVISION_CONFLICT` without writing. Successful
+file moves require a source `expected_sha256` plus `must_not_exist: true` for the
+target. Deletes require `expected_sha256`; v1 deletes regular files only and
+rejects directory or recursive deletes. Successful writes leave the index
+pending and append an index invalidation event under
+`.ai/harness/mcp/index-events.jsonl`; `refresh_repo_index` runs CodeGraph sync
+for the repo, invalidates reader snapshots, records refresh success or
+dead-letter failure in that same event log, and returns the new `snapshot_id`,
+`index_revision`, `index_state`, refresh strategy, and optional mutation lag when
+called with `mutation_id`. The CLI adapter reports `path_refresh_supported:false`
+when it must use repo-level sync for requested paths. The MCP audit log records
+actor/profile, repo id, operation, relative paths, hash summary, result, error
+code, duration, and mutation/index event ids without storing file bodies or
+patch text. The repo whitelist is the authorization boundary, `.ignore` is the
+only content exclusion source, paths are repo-relative, and authorized file
+content is not implicitly redacted. External non-repo local roots require
+explicit `--allow-root` authorization.
+
+When CodeGraph is initialized for a registered repo, the general reader merges
+CodeGraph indexed-file metadata into manifest/stat/read/search responses while
+keeping the filesystem walker as the complete manifest source of truth. Responses
+carry `snapshot_id`, `index_revision`, `ignore_digest`, and `indexed` metadata;
+stale client snapshots return `SNAPSHOT_STALE` instead of silently mixing
+versions. Responses also expose `snapshot_state`, snapshot TTL/expiry, and a
+bounded in-process snapshot cache marker. The public `snapshot_cache.key` is
+scoped by tool and repo-relative path set, while `snapshot_cache.snapshot_key`
+identifies the underlying repo snapshot. Entry metadata is cached separately by
+repo, registry revision, `.ignore` digest, relative path, and current stat
+signature, so unchanged warm manifest/stat/read calls avoid repeated file hash
+and binary probes without hiding file, registry, or `.ignore` changes. Explicit
+`snapshot_id` stat/read calls can reuse the cached snapshot and validate the
+requested file hash instead of rebuilding the full repo snapshot. If CodeGraph
+reports a now-missing indexed path or metadata that no longer matches the
+filesystem, the snapshot becomes `index_lagging` while authorized read/stat
+fallback stays available. Full-text search still falls back to the guarded
+filesystem path when CodeGraph cannot provide complete repo-text search.
+For large manifests, `repo_manifest` streams the visible tree and keeps only the
+requested page of entries in memory. Returned page entries include exact content
+hashes; non-page file content metadata is deferred and reported as
+`counts.content_deferred` until a later manifest page, `stat_file`, `read_file`,
+or `search_text` actually returns that content.
+
+For large-repo reader baselines, run:
+
+```bash
+bun run benchmark:mcp-reader -- --entries 10000 --json
+```
+
+Use `--entries all` for the full 10k/100k/500k fixture sequence when the local
+machine can spend the filesystem time.
+
+For the full tool reference, JSON examples, repo administrator guidance,
+privacy notes, migration guide, rollout flags, and known limits, see
+[`docs/reference-configs/general-repo-mcp.md`](docs/reference-configs/general-repo-mcp.md).
+For index stale, CodeGraph down, manifest incomplete, mutation conflict,
+reindex dead-letter, and rollback operations, see
+[`deploy/runbooks/general-repo-mcp-codegraph.md`](deploy/runbooks/general-repo-mcp-codegraph.md).
 
 This sidecar assumes the CLI is already installed from
 [First 5 Minutes](#first-5-minutes). Use it when you want ChatGPT to plan
@@ -454,10 +517,10 @@ implementation under `assets/hooks/` or a repo-pinned `.ai/hooks/` copy.
 
 | Route | Matcher | Scripts | Function |
 | --- | --- | --- | --- |
-| `SessionStart.default` | all sessions | `session-start-context.sh`, `security-sentinel.sh` | Injects prior handoff, sprint status, and read-only config-security findings before work starts. |
+| `SessionStart.default` | all sessions | `session-start-context.sh`, `minimal-change-context.sh`, `security-sentinel.sh` | Injects prior handoff, sprint status, minimal-change guidance, and read-only config-security findings before work starts. |
 | `PreToolUse.edit` | `Edit|Write` | `worktree-guard.sh`, `pre-edit-guard.sh` | Enforces worktree policy and plan/contract readiness before implementation edits. |
 | `PreToolUse.subagent` | `Task|Agent|SendUserMessage` | `subagent-return-channel-guard.sh` | Keeps delegated work returning through the parent session instead of leaking completion claims. |
-| `PostToolUse.edit` | `Edit|Write` | `post-edit-guard.sh` | Records edit traces, refreshes handoff/task status, and queues architecture drift when controlled files change. |
+| `PostToolUse.edit` | `Edit|Write` | `post-edit-guard.sh`, `minimal-change-observer.sh` | Records edit traces, refreshes handoff/task status, queues architecture drift, and writes bounded minimal-change evidence when controlled files change. |
 | `PostToolUse.bash` | `Bash` | `post-bash.sh` | Observes command results and captures verification evidence without replacing the command runner. |
 | `PostToolUse.always` | all tools | `post-tool-observer.sh` | Provides low-noise always-on trace and runtime observation; stale pinned copies soft-skip with a refresh hint. |
 | `UserPromptSubmit.default` | all prompts | `prompt-guard.sh` | Classifies prompt intent, routes planning/check/hunt hints, and renders host-safe workflow guidance. |
@@ -468,7 +531,7 @@ Codex-only routes are `UserPromptSubmit.delegation`,
 `PreToolUse.subagent` return-channel route and does not install those Codex
 delegation lifecycle entries.
 
-`SessionStart` resolves hooks central-first, then runs two ordered scripts before
+`SessionStart` resolves hooks central-first, then runs three ordered scripts before
 work begins:
 
 ```mermaid
@@ -480,7 +543,8 @@ flowchart LR
   Source -->|repo policy pin| Repo["repo .ai/hooks<br/>self-host development"]
   Central --> Ctx["session-start-context.sh<br/>resume + sprint + handoff context"]
   Repo --> Ctx
-  Ctx --> Sec["security-sentinel.sh<br/>read-only config scan, fingerprint-gated"]
+  Ctx --> Min["minimal-change-context.sh<br/>advice-only scope pressure"]
+  Min --> Sec["security-sentinel.sh<br/>read-only config scan, fingerprint-gated"]
   Sec --> SSOut["SessionStart additionalContext<br/>prior-session state + SecurityConfig findings"]
 ```
 
@@ -535,8 +599,8 @@ Most common guards:
 
 ## Current Release
 
-- npm package: `repo-harness@0.8.0`
-- Generated workflow stamp: `repo-harness@0.8.0+template@0.8.0`
+- npm package: `repo-harness@0.8.2`
+- Generated workflow stamp: `repo-harness@0.8.2+template@0.8.2`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/README.zh-CN.md

@@ -69,7 +69,7 @@ review、checks 或 handoff 冲突，以 source artifacts 为准。
 
 ## What's New
 
-Release notes 见 [`docs/CHANGELOG.md`](docs/CHANGELOG.md)，当前版本线是 `0.8.0`。
+Release notes 见 [`docs/CHANGELOG.md`](docs/CHANGELOG.md)，当前版本线是 `0.8.2`。
 
 ## 工作原理
 
@@ -445,8 +445,8 @@ hook block 工作时，先看 terminal 里的结构化输出。核心字段是
 
 ## 当前 Release
 
-- npm package：`repo-harness@0.8.0`
-- Generated workflow stamp：`repo-harness@0.8.0+template@0.8.0`
+- npm package：`repo-harness@0.8.2`
+- Generated workflow stamp：`repo-harness@0.8.2+template@0.8.2`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/assets/hooks/codex.hooks.template.json

@@ -4,6 +4,7 @@
       {
         "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\" session-start-context.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\" minimal-change-context.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\" security-sentinel.sh", "timeout": 30 }
         ]
       }
@@ -27,7 +28,8 @@
       {
         "matcher": "Edit|Write",
         "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\" post-edit-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\" post-edit-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\" minimal-change-observer.sh", "timeout": 30 }
         ]
       },
       {

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

@@ -115,12 +115,12 @@ run_edit_plan_gate() {
   if [[ -z "$gate_plan" || ! -f "$gate_plan" ]]; then
     echo "[PlanStatusGuard] No active plan covers implementation edit: $FILE_PATH"
     if [[ "$mode" == "advice" ]]; then
-      echo "[PlanStatusGuard] Advisory: capture the approved plan with bash scripts/capture-plan.sh --slug <slug> --title <title> --status Approved --execute"
+      echo "[PlanStatusGuard] Advisory: capture the approved plan with bash scripts/capture-plan.sh --slug <slug> --title <title> --artifact-level work-package --promotion-reason human_decision_boundary --status Approved --execute"
     else
       hook_structured_error \
         "PlanStatusGuard" \
         "Implementation edit to $FILE_PATH without an active plan." \
-        "Capture the approved planning output with bash scripts/capture-plan.sh --slug <slug> --title <title> --status Approved --execute, or set policy .guards.edit_plan_gate to advice/off for this repo." \
+        "Capture the approved planning output with bash scripts/capture-plan.sh --slug <slug> --title <title> --artifact-level work-package --promotion-reason human_decision_boundary --status Approved --execute, or set policy .guards.edit_plan_gate to advice/off for this repo." \
         "missing_artifact"
       exit 2
     fi

package/assets/hooks/prompt-guard.sh

@@ -530,8 +530,8 @@ emit_pending_orchestration_capture_gate() {
   [[ -n "$source_ref" ]] && source_arg=" --source-ref <source-ref>"
   echo "[PlanCaptureGate] Implementation requested while a pending plan/orchestration discussion has not been captured."
   echo "[PlanCaptureGate] $(workflow_pending_orchestration_summary)"
-  echo "[PlanCaptureGate] Capture the final plan body first; if implementation is already approved, use --status Approved --execute:"
-  echo "  printf '%s\n' '<approved plan body>' | bash scripts/capture-plan.sh --slug <slug> --title <title> --status Approved --source ${kind:-host-plan} --orchestration-kind ${kind:-host-plan} --route planning --execute${source_arg}"
+  echo "[PlanCaptureGate] Capture the final plan body first; if implementation is already approved, use --status Approved --execute with a work-package promotion reason:"
+  echo "  printf '%s\n' '<approved plan body>' | bash scripts/capture-plan.sh --slug <slug> --title <title> --artifact-level work-package --promotion-reason human_decision_boundary --status Approved --source ${kind:-host-plan} --orchestration-kind ${kind:-host-plan} --route planning --execute${source_arg}"
   return 0
 }
 
@@ -662,7 +662,7 @@ maybe_capture_embedded_approved_plan() {
   fi
 
   echo "[PlanCaptureGate] Embedded approved plan detected. Capturing and projecting before implementation."
-  if ! capture_output="$(printf '%s\n' "$body" | bash "scripts/capture-plan.sh" --slug "$slug" --title "$title" --status Approved --source user-approved-plan --route planning --execute 2>&1)"; then
+  if ! capture_output="$(printf '%s\n' "$body" | bash "scripts/capture-plan.sh" --slug "$slug" --title "$title" --artifact-level work-package --promotion-reason human_decision_boundary --status Approved --source user-approved-plan --route planning --execute 2>&1)"; then
     printf '%s\n' "$capture_output"
     hook_structured_error \
       "PlanCaptureGate" \
@@ -906,18 +906,18 @@ render_prompt_guard_action() {
       echo "[PlanCaptureGate] Approval detected before an active plan artifact exists."
       echo "[PlanCaptureGate] Let the agent run the approved-plan capture path now:"
       echo "  git status --short --branch -uall"
-      echo "  printf '%s\n' '<approved plan body>' | bash scripts/capture-plan.sh --slug <slug> --title <title> --status Approved --source waza-think --route planning --execute"
+      echo "  printf '%s\n' '<approved plan body>' | bash scripts/capture-plan.sh --slug <slug> --title <title> --artifact-level work-package --promotion-reason human_decision_boundary --status Approved --source waza-think --route planning --execute"
       exit 0
       ;;
     plan_status_no_active_block)
       echo "[PlanStatusGuard] Advisory: No active plan found in plans/. Implementation edits will be blocked at the edit layer until a plan is captured."
-      echo "[PlanStatusGuard] Capture the approved planning output with: bash scripts/capture-plan.sh --slug <slug> --title <title> --status Approved --execute"
+      echo "[PlanStatusGuard] Capture the approved planning output with: bash scripts/capture-plan.sh --slug <slug> --title <title> --artifact-level work-package --promotion-reason human_decision_boundary --status Approved --execute"
       echo "[PlanStatusGuard] If there is no captured planning output yet, run: bash scripts/ensure-task-workflow.sh --slug <slug> --title <title>"
       exit 0
       ;;
     plan_capture_draft_advice)
       echo "[PlanCaptureGate] Approval detected for $plan_status plan: $active_plan"
-      echo "[PlanCaptureGate] Recapture the exact approved plan body with --status Approved --execute, or mark this plan Approved and run:"
+      echo "[PlanCaptureGate] Recapture the exact approved plan body with --artifact-level work-package --promotion-reason <reason> --status Approved --execute, or mark this plan Approved and run:"
       echo "  bash scripts/plan-to-todo.sh --plan $active_plan"
       exit 0
       ;;

package/assets/hooks/run-hook.sh

@@ -89,17 +89,17 @@ hook_stdout_is_json_kind() {
 }
 
 # Codex swallows hook stdout differently from Claude: success stdout is
-# dropped for ordinary hooks. Only context/decision JSON for approved routes is
-# surfaced on success.
+# dropped for ordinary hooks. Only context JSON and SubagentStop decision JSON
+# for approved routes is surfaced on success. Stop decision JSON is deliberately
+# suppressed because current Codex Desktop rejects it as an unsupported content
+# type at turn finalization.
 if [[ "${HOOK_HOST:-}" == "codex" && "$HOOK_NAME" != "session-start-context.sh" ]]; then
   if ! tmp_stdout="$(mktemp)" || ! tmp_stderr="$(mktemp)"; then
     # No temp space: run unfiltered rather than silently dropping the hook.
     exec bash "$HOOK_PATH" "$@"
   fi
   if bash "$HOOK_PATH" "$@" >"$tmp_stdout" 2>"$tmp_stderr"; then
-    if [[ "$HOOK_NAME" == "stop-orchestrator.sh" ]] && hook_stdout_is_json_kind "$tmp_stdout" decision; then
-      cat "$tmp_stdout"
-    elif [[ "$HOOK_NAME" == "subagent-stop-quality.sh" ]] && hook_stdout_is_json_kind "$tmp_stdout" decision; then
+    if [[ "$HOOK_NAME" == "subagent-stop-quality.sh" ]] && hook_stdout_is_json_kind "$tmp_stdout" decision; then
       cat "$tmp_stdout"
     elif [[ "$HOOK_NAME" == "codex-delegation-advisor.sh" ]] && hook_stdout_is_json_kind "$tmp_stdout" user_prompt_context; then
       cat "$tmp_stdout"

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

@@ -378,7 +378,7 @@ printf '%s\n' '<decision-complete plan body>' | bash ${capture_script} --slug ${
 If the user has already approved implementation:
 
 \`\`\`bash
-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}
+printf '%s\n' '<approved plan body>' | bash ${capture_script} --slug ${prompt_slug:-<slug>} --title <title> --artifact-level work-package --promotion-reason human_decision_boundary --status Approved --source ${capture_source} --orchestration-kind ${capture_source} --route planning --execute${source_arg}
 \`\`\`
 EOF_CONTEXT
 }

package/assets/hooks/settings.template.json

@@ -4,6 +4,7 @@
       {
         "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\" session-start-context.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\" minimal-change-context.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\" security-sentinel.sh", "timeout": 30 }
         ]
       }
@@ -27,7 +28,8 @@
       {
         "matcher": "Edit|Write",
         "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\" post-edit-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\" post-edit-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\" minimal-change-observer.sh", "timeout": 30 }
         ]
       },
       {

package/assets/hooks/stop-orchestrator.sh

@@ -94,8 +94,46 @@ plan_completeness_shell_quote() {
   printf '%q' "$1"
 }
 
+plan_completeness_runtime_summary() {
+  local kind host prompt_slug draft_path source_ref expected_artifact cwd
+
+  kind="$(workflow_pending_orchestration_field kind 2>/dev/null || true)"
+  host="$(workflow_pending_orchestration_field host 2>/dev/null || true)"
+  prompt_slug="$(workflow_pending_orchestration_field prompt_slug 2>/dev/null || true)"
+  draft_path="$(workflow_pending_orchestration_field draft_plan_path 2>/dev/null || true)"
+  source_ref="$(workflow_pending_orchestration_field source_ref 2>/dev/null || true)"
+  expected_artifact="$(workflow_pending_orchestration_field expected_artifact 2>/dev/null || true)"
+  cwd="$(workflow_pending_orchestration_field cwd 2>/dev/null || true)"
+
+  printf 'kind=%s host=%s expected=%s slug=%s' "${kind:-unknown}" "${host:-unknown}" "${expected_artifact:-plan}" "${prompt_slug:-planning}"
+  [[ -n "$draft_path" ]] && printf ' draft=%s' "$draft_path"
+  [[ -n "$source_ref" ]] && printf ' source_ref=<source-ref>'
+  [[ -n "$cwd" ]] && printf ' cwd=%s' "$cwd"
+  printf '\n'
+}
+
+plan_completeness_guidance_title_arg() {
+  case "$1" in
+    waza-think)
+      printf '"Waza think planning output"'
+      ;;
+    dynamic-workflow)
+      printf '"Dynamic workflow planning output"'
+      ;;
+    codex-plan)
+      printf '"Codex planning output"'
+      ;;
+    repo-harness-plan)
+      printf '"repo-harness planning output"'
+      ;;
+    *)
+      printf '"Planning output"'
+      ;;
+  esac
+}
+
 plan_completeness_capture_guidance() {
-  local kind prompt_slug source_ref title source_arg
+  local kind prompt_slug source_ref title_arg source_arg
 
   kind="$(workflow_pending_orchestration_field kind 2>/dev/null || true)"
   prompt_slug="$(workflow_pending_orchestration_field prompt_slug 2>/dev/null || true)"
@@ -103,18 +141,20 @@ plan_completeness_capture_guidance() {
 
   kind="${kind:-host-plan}"
   prompt_slug="${prompt_slug:-planning}"
-  title="${source_ref:-$prompt_slug}"
+  title_arg="$(plan_completeness_guidance_title_arg "$kind")"
   source_arg=""
   if [[ -n "$source_ref" ]]; then
-    source_arg=" --source-ref $(plan_completeness_shell_quote "$source_ref")"
+    source_arg=' --source-ref "<source-ref>"'
   fi
 
   cat <<EOF_GUIDANCE
 If the planning answer is decision-complete, capture the final plan body before stopping:
-  printf '%s\n' '<decision-complete plan body>' | bash scripts/capture-plan.sh --slug $(plan_completeness_shell_quote "$prompt_slug") --title $(plan_completeness_shell_quote "$title") --status Draft --source $(plan_completeness_shell_quote "$kind") --orchestration-kind $(plan_completeness_shell_quote "$kind") --route planning${source_arg}
+  printf '%s\n' '<decision-complete plan body>' | bash scripts/capture-plan.sh --slug $(plan_completeness_shell_quote "$prompt_slug") --title ${title_arg} --status Draft --source $(plan_completeness_shell_quote "$kind") --orchestration-kind $(plan_completeness_shell_quote "$kind") --route planning${source_arg}
 
 If the user already approved implementation, use:
-  printf '%s\n' '<approved plan body>' | bash scripts/capture-plan.sh --slug $(plan_completeness_shell_quote "$prompt_slug") --title $(plan_completeness_shell_quote "$title") --status Approved --source $(plan_completeness_shell_quote "$kind") --orchestration-kind $(plan_completeness_shell_quote "$kind") --route planning --execute${source_arg}
+  printf '%s\n' '<approved plan body>' | bash scripts/capture-plan.sh --slug $(plan_completeness_shell_quote "$prompt_slug") --title ${title_arg} --artifact-level work-package --promotion-reason human_decision_boundary --status Approved --source $(plan_completeness_shell_quote "$kind") --orchestration-kind $(plan_completeness_shell_quote "$kind") --route planning --execute${source_arg}
+
+Use a short English title/source-ref alias in these runtime instructions; do not paste non-ASCII prompt text into command arguments.
 
 If the plan is not decision-complete, revise once for: goal/success criteria, scope/non-scope, constraints, P1/P2/P3, fragile assumption, rejected alternative, public API/config/file-interface changes, external dependency/API key requirements, tests, rollback/failure handling, phase independence, and no placeholders. Do not implement until capture succeeds.
 EOF_GUIDANCE
@@ -400,7 +440,7 @@ if should_run_plan_completeness_gate "$stop_hook_active" "$last_assistant_messag
   signature="$(plan_completeness_signature)"
   if [[ "$(plan_completeness_last_signature 2>/dev/null || true)" != "$signature" ]]; then
     plan_completeness_record_signature "$signature"
-    summary="$(workflow_pending_orchestration_summary)"
+    summary="$(plan_completeness_runtime_summary)"
     guidance="$(plan_completeness_capture_guidance)"
     emit_stop_block_json "[PlanCompletenessGate] A first planning answer was produced while pending orchestration is still open: ${summary}