repo-harness 0.7.4 → 0.7.5

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

package/README.md

@@ -78,7 +78,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.7.4`.
+is `0.7.5`.
 
 ## How It Works
 
@@ -97,6 +97,15 @@ it resolves hooks central-first through the packaged install or
 `~/.repo-harness/hooks/`, with repo policy able to pin self-host development
 back to `.ai/hooks/*`.
 
+Minimal-change hooks sit inside that same route surface without adding a public
+adapter route. `SessionStart` and allowed execution prompts print advisory
+context when policy opts in, `PostToolUse.edit` can write bounded change signals
+to `.ai/harness/checks/minimal-change.latest.json` when
+`post_edit_observer:true` is explicitly enabled, and `Stop` records the latest
+review summary in the handoff. Missing or malformed policy defaults to off; even
+`mode: "enforce"` is normalized to advisory behavior so tests, contracts, and
+human review stay the enforcement boundary.
+
 For `UserPromptSubmit`, the public adapter contract stays
 `repo-harness-hook UserPromptSubmit --route default`. The CLI route registry
 dispatches that route to `.ai/hooks/prompt-guard.sh`. The shell hook remains the
@@ -336,22 +345,55 @@ before applying anything.
 
 ## MCP Connector Quickstart
 
-As an optional sidecar, `repo-harness mcp` exposes only workflow artifacts to
-MCP clients. 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, arbitrary shell execution, or default Codex runner.
-Codex remains the executor.
+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,
+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.
 
 This sidecar assumes the CLI is already installed from
 [First 5 Minutes](#first-5-minutes). Use it when you want ChatGPT to plan
 against the real repo state and Codex to execute the resulting file-backed
 Sprint.
 
+The ChatGPT Connector registers one endpoint URL, not one repository per URL.
+Adopted repos are discovered from `~/.repo-harness/registered-repos.json`, which
+is updated by `repo-harness adopt`, `repo-harness init`, and user-scope ChatGPT
+setup. Stale registry entries are ignored unless the live repo still has
+repo-harness adoption markers.
+
 ```bash
 repo-harness mcp setup chatgpt --repo .
 repo-harness mcp serve --repo . --transport http --host 127.0.0.1 --port 8765 --profile planner
 ```
 
+User-scope global Connector setup:
+
+```bash
+repo-harness mcp setup chatgpt --scope user --repo . --endpoint <https-url>/mcp
+repo-harness mcp serve --repo . --transport http --host 127.0.0.1 --port 8765 --profile planner
+```
+
+Optional external reader roots:
+
+```bash
+repo-harness mcp setup chatgpt \
+  --scope user \
+  --repo . \
+  --enable-reader \
+  --allow-root "$HOME/Documents" \
+  --allow-root "$HOME/Projects" \
+  --endpoint <https-url>/mcp
+```
+
 Expose that local server through an HTTPS tunnel and create a ChatGPT Connector
 with the `/mcp` URL. The generated guide is written to:
 
@@ -493,8 +535,8 @@ Most common guards:
 
 ## Current Release
 
-- npm package: `repo-harness@0.7.4`
-- Generated workflow stamp: `repo-harness@0.7.4+template@0.7.4`
+- npm package: `repo-harness@0.7.5`
+- Generated workflow stamp: `repo-harness@0.7.5+template@0.7.5`
 - 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.7.4`。
+Release notes 见 [`docs/CHANGELOG.md`](docs/CHANGELOG.md)，当前版本线是 `0.7.5`。
 
 ## 工作原理
 
@@ -86,6 +86,13 @@ Release notes 见 [`docs/CHANGELOG.md`](docs/CHANGELOG.md)，当前版本线是
    时按 central-first 解析 packaged install 或 `~/.repo-harness/hooks/`，repo policy
    也可以把自托管开发钉回 `.ai/hooks/*`。
 
+minimal-change hooks 复用同一套路由 surface，不新增公开 adapter route。`SessionStart`
+和允许执行的 prompt 只在 policy opt in 时打印 advisory context；只有显式启用
+`post_edit_observer:true` 时，`PostToolUse.edit` 才会把有界改动信号写到
+`.ai/harness/checks/minimal-change.latest.json`，`Stop` 把最新 review 摘要写进 handoff。
+缺失或损坏的 policy 默认 off；即使配置 `mode: "enforce"` 也会归一化为 advisory 行为，
+真正的 enforcement boundary 仍然是 tests、contracts 和 human review。
+
 对 `UserPromptSubmit` 来说，公开 adapter contract 仍然是
 `repo-harness-hook UserPromptSubmit --route default`。CLI route registry 会把这个
 route dispatch 到 `.ai/hooks/prompt-guard.sh`。Shell hook 继续负责 host JSON 解析、
@@ -437,8 +444,8 @@ hook block 工作时，先看 terminal 里的结构化输出。核心字段是
 
 ## 当前 Release
 
-- npm package：`repo-harness@0.7.4`
-- Generated workflow stamp：`repo-harness@0.7.4+template@0.7.4`
+- npm package：`repo-harness@0.7.5`
+- Generated workflow stamp：`repo-harness@0.7.5+template@0.7.5`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/assets/hooks/lib/minimal-change.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# Shared minimal-change hook adapter helpers.
+
+minimal_change_post_edit_enabled() {
+  local repo_root policy_file mode observer compact
+
+  repo_root="${HOOK_REPO_ROOT:-$(pwd)}"
+  policy_file="$repo_root/.ai/harness/policy.json"
+  [[ -f "$policy_file" ]] || return 1
+
+  if command -v jq >/dev/null 2>&1; then
+    mode="$(jq -r '.minimal_change.mode // "off"' "$policy_file" 2>/dev/null || true)"
+    observer="$(jq -r '.minimal_change.post_edit_observer // false' "$policy_file" 2>/dev/null || true)"
+    [[ "$mode" != "off" && "$observer" == "true" ]]
+    return $?
+  fi
+
+  compact="$(tr -d '[:space:]' < "$policy_file" 2>/dev/null || true)"
+  [[ "$compact" == *'"minimal_change":{'* ]] || return 1
+  [[ "$compact" == *'"mode":"advice"'* || "$compact" == *'"mode":"enforce"'* ]] || return 1
+  [[ "$compact" == *'"post_edit_observer":true'* ]]
+}
+
+minimal_change_hook_entry() {
+  local lib_dir hooks_dir source_hook_cli
+
+  lib_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  hooks_dir="$(cd "$lib_dir/.." && pwd)"
+  source_hook_cli="$(cd "$hooks_dir/../.." 2>/dev/null && pwd)/src/cli/hook-entry.ts"
+
+  if [[ -n "${REPO_HARNESS_HOOK_CLI:-}" && -f "${REPO_HARNESS_HOOK_CLI:-}" ]] && command -v bun >/dev/null 2>&1; then
+    bun "$REPO_HARNESS_HOOK_CLI" minimal-change "$@"
+    return $?
+  fi
+
+  if [[ -f "$source_hook_cli" ]] && command -v bun >/dev/null 2>&1; then
+    bun "$source_hook_cli" minimal-change "$@"
+    return $?
+  fi
+
+  if [[ -n "${HOOK_REPO_ROOT:-}" && -f "$HOOK_REPO_ROOT/src/cli/hook-entry.ts" ]] && command -v bun >/dev/null 2>&1; then
+    bun "$HOOK_REPO_ROOT/src/cli/hook-entry.ts" minimal-change "$@"
+    return $?
+  fi
+
+  if command -v repo-harness-hook >/dev/null 2>&1; then
+    repo-harness-hook minimal-change "$@"
+    return $?
+  fi
+
+  return 127
+}

package/assets/hooks/minimal-change-context.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+# Minimal-change advisory context — SessionStart.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+. "$SCRIPT_DIR/hook-input.sh"
+# shellcheck source=/dev/null
+. "$SCRIPT_DIR/lib/minimal-change.sh"
+
+if output="$(minimal_change_hook_entry context --phase session 2>/dev/null)"; then
+  [[ -n "$output" ]] && printf '%s\n' "$output"
+fi
+
+exit 0

package/assets/hooks/minimal-change-observer.sh

@@ -0,0 +1,18 @@
+#!/bin/bash
+# Minimal-change objective signal observer — PostToolUse on Edit|Write.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=/dev/null
+. "$SCRIPT_DIR/hook-input.sh"
+# shellcheck source=/dev/null
+. "$SCRIPT_DIR/lib/minimal-change.sh"
+
+file_path="$(hook_get_file_path "${1:-}")"
+[[ -z "$file_path" ]] && exit 0
+minimal_change_post_edit_enabled || exit 0
+
+minimal_change_hook_entry signals --phase post-edit --path "$file_path" >/dev/null 2>&1 || true
+
+exit 0

package/assets/hooks/prompt-guard.sh

@@ -22,6 +22,10 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 . "$SCRIPT_DIR/lib/workflow-state.sh"
 # shellcheck source=/dev/null
 . "$SCRIPT_DIR/lib/session-state.sh"
+if [[ -f "$SCRIPT_DIR/lib/minimal-change.sh" ]]; then
+  # shellcheck source=/dev/null
+  . "$SCRIPT_DIR/lib/minimal-change.sh"
+fi
 
 # --- Filesystem/worktree helpers (shell-owned authority) ---
 
@@ -186,6 +190,111 @@ prompt_intent_text() {
   fi
 }
 
+prompt_nearest_existing_path() {
+  local path="$1"
+  while [[ "$path" != "/" && ! -e "$path" && ! -L "$path" ]]; do
+    path="$(dirname "$path")"
+  done
+  [[ -e "$path" || -L "$path" ]] || return 1
+  printf '%s' "$path"
+}
+
+prompt_resolve_probe_path() {
+  local path="$1"
+  local base target hops followed state
+  hops=0
+  followed=0
+
+  while true; do
+    path="$(prompt_nearest_existing_path "$path")" || {
+      printf 'SKIP\t%s' "$1"
+      return 0
+    }
+    if [[ ! -L "$path" ]]; then
+      state="OK"
+      [[ "$followed" -eq 1 ]] && state="OK_SYMLINK"
+      printf '%s\t%s' "$state" "$path"
+      return 0
+    fi
+
+    hops=$((hops + 1))
+    if [[ "$hops" -gt 20 ]]; then
+      printf 'FAIL\t%s' "$path"
+      return 0
+    fi
+    target="$(readlink "$path" 2>/dev/null || true)"
+    if [[ -z "$target" ]]; then
+      printf 'FAIL\t%s' "$path"
+      return 0
+    fi
+    followed=1
+
+    if [[ "$target" == /* ]]; then
+      path="$target"
+    else
+      base="$(dirname "$path")"
+      path="$base/$target"
+    fi
+  done
+}
+
+prompt_foreign_repo_root() {
+  local current_root current_real candidates raw candidate probe_record probe_state probe dir dir_real root root_real
+  current_root="${HOOK_REPO_ROOT:-$(pwd)}"
+  current_real="$(cd "$current_root" 2>/dev/null && pwd -P || true)"
+  [[ -n "$current_real" ]] || current_real="$current_root"
+
+  candidates="$(printf '%s\n' "$PROMPT_INTENT_TEXT" | awk '
+    {
+      line = $0
+      while (match(line, /\/[^[:space:]<>"`]+/)) {
+        print substr(line, RSTART, RLENGTH)
+        line = substr(line, RSTART + RLENGTH)
+      }
+    }
+  ' | sed -E 's/[][),.;:]+$//' | sort -u)"
+
+  while IFS= read -r raw || [[ -n "$raw" ]]; do
+    [[ -n "$raw" ]] || continue
+    candidate="$raw"
+
+    probe_record="$(prompt_resolve_probe_path "$candidate")"
+    probe_state="${probe_record%%$'\t'*}"
+    probe="${probe_record#*$'\t'}"
+    if [[ "$probe_state" == "FAIL" ]]; then
+      printf '%s' "$probe"
+      return 0
+    fi
+    [[ "$probe_state" == "OK" || "$probe_state" == "OK_SYMLINK" ]] || continue
+    [[ -n "$probe" ]] || continue
+    if [[ -d "$probe" ]]; then
+      dir="$probe"
+    else
+      dir="$(dirname "$probe")"
+    fi
+    dir_real="$(cd "$dir" 2>/dev/null && pwd -P || true)"
+    [[ -n "$dir_real" ]] || continue
+
+    root="$(git -C "$dir_real" rev-parse --show-toplevel 2>/dev/null || true)"
+    if [[ -z "$root" ]]; then
+      if [[ "$probe_state" == "OK_SYMLINK" && "$dir_real" != "$current_real" && "$dir_real" != "$current_real"/* ]]; then
+        printf '%s' "$dir_real"
+        return 0
+      fi
+      continue
+    fi
+    root_real="$(cd "$root" 2>/dev/null && pwd -P || true)"
+    [[ -n "$root_real" ]] || root_real="$root"
+
+    if [[ "$root_real" != "$current_real" ]]; then
+      printf '%s' "$root"
+      return 0
+    fi
+  done <<< "$candidates"
+
+  return 1
+}
+
 # --- Decision engine invocation ---
 
 prompt_guard_decision_command() {
@@ -429,6 +538,14 @@ emit_pending_orchestration_capture_gate() {
 maybe_start_plan_workflow() {
   pg_fact THINK_PLAN_START || return 0
 
+  local foreign_repo
+  foreign_repo="$(prompt_foreign_repo_root || true)"
+  if [[ -n "$foreign_repo" ]]; then
+    echo "[RepoIsolationGate] Think/plan intent references a different git repo: $foreign_repo"
+    echo "[RepoIsolationGate] Skipping automatic Draft plan workflow in ${HOOK_REPO_ROOT:-$(pwd)}. Continue from the referenced repo before creating repo-local workflow files."
+    return 0
+  fi
+
   if [[ ! -x "scripts/ensure-task-workflow.sh" ]]; then
     echo "[PlanStartGate] Think/plan intent detected, but scripts/ensure-task-workflow.sh is missing. Continue with planning and capture manually."
     return 0
@@ -508,6 +625,14 @@ normalize_plan_slug() {
 maybe_capture_embedded_approved_plan() {
   pg_fact EMBEDDED_APPROVED_PLAN || pg_fact PLAN_SHAPED_MARKDOWN || return 0
 
+  local foreign_repo
+  foreign_repo="$(prompt_foreign_repo_root || true)"
+  if [[ -n "$foreign_repo" ]]; then
+    echo "[RepoIsolationGate] Embedded plan references a different git repo: $foreign_repo"
+    echo "[RepoIsolationGate] Skipping capture-plan in ${HOOK_REPO_ROOT:-$(pwd)}. Re-run the prompt from the referenced repo before projecting workflow files."
+    return 0
+  fi
+
   if [[ ! -x "scripts/capture-plan.sh" ]]; then
     echo "[PlanCaptureGate] Embedded approved plan detected, but scripts/capture-plan.sh is missing."
     hook_structured_error \
@@ -860,6 +985,19 @@ emit_workflow_file_guards() {
   fi
 }
 
+emit_minimal_change_prompt_advice() {
+  local output
+
+  [[ "${PG_ACTION:-}" == "allow" ]] || return 0
+  [[ -n "${PG_INTENT:-}" ]] || return 0
+  declare -F minimal_change_hook_entry >/dev/null 2>&1 || return 0
+
+  if output="$(minimal_change_hook_entry context --phase prompt --intent "$PG_INTENT" 2>/dev/null)"; then
+    [[ -n "$output" ]] && printf '%s\n' "$output"
+  fi
+  return 0
+}
+
 # --- Main flow ---
 
 PROMPT_TEXT="$(hook_get_prompt "${1:-}")"
@@ -893,8 +1031,14 @@ plan_start_intent=0
 pg_fact PLAN_START && plan_start_intent=1
 
 plan_research_ready=1
+plan_repo_isolation_skip=0
 if [ "$plan_start_intent" -eq 1 ]; then
-  if ! has_research_for_new_plan; then
+  foreign_repo="$(prompt_foreign_repo_root || true)"
+  if [[ -n "$foreign_repo" ]]; then
+    plan_repo_isolation_skip=1
+    echo "[RepoIsolationGate] Think/plan intent references a different git repo: $foreign_repo"
+    echo "[RepoIsolationGate] Skipping automatic Draft plan workflow in ${HOOK_REPO_ROOT:-$(pwd)}. Continue from the referenced repo before creating repo-local workflow files."
+  elif ! has_research_for_new_plan; then
     latest_plan="$(get_latest_plan || true)"
     if [[ -n "$latest_plan" ]]; then
       plan_research_ready=0
@@ -908,7 +1052,9 @@ if [ "$plan_start_intent" -eq 1 ]; then
 fi
 
 if [ "$implement_intent" -eq 0 ] && [ "$done_intent" -eq 0 ]; then
-  if [ "$plan_start_intent" -eq 1 ] && [ "$plan_research_ready" -eq 0 ]; then
+  if [ "$plan_start_intent" -eq 1 ] && [ "$plan_repo_isolation_skip" -eq 1 ]; then
+    :
+  elif [ "$plan_start_intent" -eq 1 ] && [ "$plan_research_ready" -eq 0 ]; then
     echo "[PlanStartGate] Skipping automatic Draft plan workflow until research is refreshed."
   else
     maybe_start_plan_workflow
@@ -929,6 +1075,7 @@ if [ "$implement_intent" -eq 1 ]; then
   prompt_guard_refresh_state
   prompt_guard_engine_call
   render_prompt_guard_action "$PG_ACTION"
+  emit_minimal_change_prompt_advice
 fi
 
 if [ "$done_intent" -eq 1 ]; then

package/assets/hooks/stop-orchestrator.sh

@@ -10,6 +10,17 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 . "$SCRIPT_DIR/hook-input.sh"
 # shellcheck source=/dev/null
 . "$SCRIPT_DIR/lib/workflow-state.sh"
+if [[ -f "$SCRIPT_DIR/lib/minimal-change.sh" ]]; then
+  # shellcheck source=/dev/null
+  . "$SCRIPT_DIR/lib/minimal-change.sh"
+fi
+
+MINIMAL_CHANGE_REVIEW_SUMMARY=""
+MINIMAL_CHANGE_REVIEW_VERDICT=""
+MINIMAL_CHANGE_REVIEW_PATH=""
+MINIMAL_CHANGE_REVIEW_FINDINGS="0"
+MINIMAL_CHANGE_HANDOFF_BEGIN="<!-- repo-harness:minimal-change-review begin -->"
+MINIMAL_CHANGE_HANDOFF_END="<!-- repo-harness:minimal-change-review end -->"
 
 plan_completeness_state_file() {
   workflow_repo_relative_path \
@@ -131,6 +142,106 @@ emit_stop_block_json() {
   printf '{"decision":"block","reason":"%s"}\n' "$(workflow_json_escape "$reason")"
 }
 
+minimal_change_parse_review_json() {
+  local raw="$1"
+  local parsed
+
+  if command -v jq >/dev/null 2>&1; then
+    parsed="$(printf '%s' "$raw" | jq -r '
+      def line($finding):
+        "- [" + ($finding.tag // "review") + "] " + ($finding.path // ".") + ": " + ($finding.question // $finding.evidence // "review required");
+      [
+        (.verdict // "unknown"),
+        (.report_path // ".ai/harness/checks/minimal-change.latest.json"),
+        ((.findings // []) | length | tostring),
+        (
+          if (.verdict // "unknown") == "disabled" then ""
+          elif (.findings // [] | length) == 0 then ""
+          else
+            "[MinimalChange] Non-blocking review (" + (.report_path // ".ai/harness/checks/minimal-change.latest.json") + "):\n" +
+            ((.findings // [])[0:5] | map(line(.)) | join("\n"))
+          end
+        )
+      ] | @tsv
+    ' 2>/dev/null)" || return 1
+  elif command -v bun >/dev/null 2>&1; then
+    parsed="$(MINIMAL_CHANGE_RAW="$raw" bun -e '
+      const report = JSON.parse(process.env.MINIMAL_CHANGE_RAW || "{}");
+      const findings = Array.isArray(report.findings) ? report.findings : [];
+      const path = report.report_path || ".ai/harness/checks/minimal-change.latest.json";
+      let summary = "";
+      if (report.verdict !== "disabled" && findings.length > 0) {
+        summary = `[MinimalChange] Non-blocking review (${path}):\n` + findings.slice(0, 5).map((finding) => {
+          const tag = finding.tag || "review";
+          const file = finding.path || ".";
+          const question = finding.question || finding.evidence || "review required";
+          return `- [${tag}] ${file}: ${question}`;
+        }).join("\n");
+      }
+      console.log([report.verdict || "unknown", path, String(findings.length), summary].join("\t"));
+    ' 2>/dev/null)" || return 1
+  else
+    return 1
+  fi
+
+  IFS=$'\t' read -r \
+    MINIMAL_CHANGE_REVIEW_VERDICT \
+    MINIMAL_CHANGE_REVIEW_PATH \
+    MINIMAL_CHANGE_REVIEW_FINDINGS \
+    MINIMAL_CHANGE_REVIEW_SUMMARY <<< "$parsed"
+}
+
+minimal_change_refresh_review() {
+  local raw
+
+  declare -F minimal_change_hook_entry >/dev/null 2>&1 || return 0
+  raw="$(minimal_change_hook_entry review --phase stop 2>/dev/null || true)"
+  [[ "$raw" == \{* ]] || return 0
+  minimal_change_parse_review_json "$raw" || return 0
+}
+
+minimal_change_render_handoff_section() {
+  printf '%s\n' "$MINIMAL_CHANGE_HANDOFF_BEGIN"
+  printf '\n## Minimal Change Review\n\n'
+  printf -- '- Report: `%s`\n' "${MINIMAL_CHANGE_REVIEW_PATH:-.ai/harness/checks/minimal-change.latest.json}"
+  printf -- '- Verdict: `%s`\n' "${MINIMAL_CHANGE_REVIEW_VERDICT:-unknown}"
+  printf -- '- Findings: `%s`\n' "${MINIMAL_CHANGE_REVIEW_FINDINGS:-0}"
+  if [[ -n "$MINIMAL_CHANGE_REVIEW_SUMMARY" ]]; then
+    printf '\n%s\n' "$MINIMAL_CHANGE_REVIEW_SUMMARY"
+  fi
+  printf '\n%s\n' "$MINIMAL_CHANGE_HANDOFF_END"
+}
+
+minimal_change_append_handoff() {
+  local handoff_file tmp_file
+
+  [[ -n "$MINIMAL_CHANGE_REVIEW_VERDICT" ]] || return 0
+  [[ "$MINIMAL_CHANGE_REVIEW_VERDICT" != "disabled" ]] || return 0
+  handoff_file="$(workflow_handoff_file)"
+  mkdir -p "$(dirname "$handoff_file")"
+  tmp_file="$(mktemp "${handoff_file}.minimal-change.XXXXXX")" || return 0
+
+  if [[ -f "$handoff_file" ]]; then
+    awk -v begin="$MINIMAL_CHANGE_HANDOFF_BEGIN" -v end="$MINIMAL_CHANGE_HANDOFF_END" '
+      $0 == begin { skip = 1; next }
+      $0 == end { skip = 0; next }
+      !skip { print }
+    ' "$handoff_file" > "$tmp_file" || {
+      rm -f "$tmp_file"
+      return 0
+    }
+  fi
+
+  printf '\n' >> "$tmp_file"
+  minimal_change_render_handoff_section >> "$tmp_file"
+  mv "$tmp_file" "$handoff_file"
+}
+
+minimal_change_reason_suffix() {
+  [[ -n "$MINIMAL_CHANGE_REVIEW_SUMMARY" ]] || return 0
+  printf '\n\n%s' "$MINIMAL_CHANGE_REVIEW_SUMMARY"
+}
+
 delegation_state_paths_json() {
   local state_dir
 
@@ -262,11 +373,18 @@ should_run_plan_completeness_gate() {
   assistant_message_looks_like_plan "$last_message"
 }
 
-refresh_handoff
-
 stop_hook_active="$(hook_json_get '.stop_hook_active' 'false')"
 last_assistant_message="$(hook_json_get '.last_assistant_message' '')"
 
+if [[ "$stop_hook_active" == "true" ]]; then
+  exit 0
+fi
+
+refresh_handoff
+
+minimal_change_refresh_review
+minimal_change_append_handoff
+
 if should_run_plan_completeness_gate "$stop_hook_active" "$last_assistant_message"; then
   signature="$(plan_completeness_signature)"
   if [[ "$(plan_completeness_last_signature 2>/dev/null || true)" != "$signature" ]]; then
@@ -275,12 +393,12 @@ if should_run_plan_completeness_gate "$stop_hook_active" "$last_assistant_messag
     guidance="$(plan_completeness_capture_guidance)"
     emit_stop_block_json "[PlanCompletenessGate] A first planning answer was produced while pending orchestration is still open: ${summary}
 
-${guidance}"
+${guidance}$(minimal_change_reason_suffix)"
     exit 0
   fi
 fi
 
 if delegation_should_block "$stop_hook_active"; then
   delegation_mark_fallback_used
-  emit_stop_block_json "[DelegationFallback] This turn explicitly requested bounded delegation, but no SubagentStart event was observed. Continue the task now by spawning the independent explorer/reviewer or isolated worker workstreams first when at least two independent workstreams exist, wait for them, reconcile their findings in the parent, then complete the response. Do not spawn for a trivial or strictly sequential task."
+  emit_stop_block_json "[DelegationFallback] This turn explicitly requested bounded delegation, but no SubagentStart event was observed. Continue the task now by spawning the independent explorer/reviewer or isolated worker workstreams first when at least two independent workstreams exist, wait for them, reconcile their findings in the parent, then complete the response. Do not spawn for a trivial or strictly sequential task.$(minimal_change_reason_suffix)"
 fi