repo-harness 0.7.4 → 0.8.0

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.8.0`.
 
 ## 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.8.0`
+- Generated workflow stamp: `repo-harness@0.8.0+template@0.8.0`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -584,7 +584,7 @@ bun run benchmark:skills --eval repair-agents-task-sync
   - `scripts/create-project-dirs.sh`
 - Legacy-doc migrator: `scripts/migrate-workflow-docs.ts`
 
-## Generated vs Self-Hosted Hook Parity
+## Generated vs Self-Hosted Hook Projection
 
 - El comportamiento downstream de hooks lo define la salida generada desde `assets/hooks/` y `assets/reference-configs/`.
 - Este repo dogfoodea el mismo contract, pero el comportamiento self-host no se sincroniza mágicamente con los generated repos; cada cambio debe actualizar explícitamente ambas superficies cuando aplique.

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.8.0`.
 
 ## 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.8.0`
+- Generated workflow stamp : `repo-harness@0.8.0+template@0.8.0`
 - GitHub repository : `Ancienttwo/repo-harness`
 - Release history : [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -590,7 +590,7 @@ bun run benchmark:skills --eval repair-agents-task-sync
   - `scripts/create-project-dirs.sh`
 - Legacy-doc migrator : `scripts/migrate-workflow-docs.ts`
 
-## Generated vs Self-Hosted Hook Parity
+## Generated vs Self-Hosted Hook Projection
 
 - Le comportement downstream des hooks est défini par la sortie générée depuis `assets/hooks/` et `assets/reference-configs/`.
 - Ce repo dogfoode le même contract, mais le comportement self-host ne se synchronise pas magiquement avec les generated repos ; un changement doit mettre à jour explicitement les deux surfaces lorsque nécessaire.

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.8.0` です。
 
 ## 仕組み
 
@@ -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.8.0`
+- Generated workflow stamp：`repo-harness@0.8.0+template@0.8.0`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -558,7 +558,7 @@ bun run benchmark:skills --eval repair-agents-task-sync
   - `scripts/create-project-dirs.sh`
 - Legacy-doc migrator：`scripts/migrate-workflow-docs.ts`
 
-## Generated vs Self-Hosted Hook Parity
+## Generated vs Self-Hosted Hook Projection
 
 - Downstream hook behavior は `assets/hooks/` と `assets/reference-configs/` から生成される出力で定義されます。
 - この repo は同じ contract を dogfood しますが、self-host behavior は generated repos と自動同期されません。変更は両方の surface を明示的に更新する必要があります。

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.8.0`.
 
 ## 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:
 
@@ -397,13 +439,13 @@ and not arbitrary shell.
 
 ## Hook Authority Map
 
-- `.ai/hooks/` is the only shared hook implementation you should edit first.
+- `assets/hooks/` is the only human-authored shared hook implementation. This self-host repo keeps `.ai/hooks/` as a checked-in generated projection for `"hook_source": "repo"` dogfood.
 - `~/.claude/settings.json` is the user-level Claude adapter that dispatches into opted-in repos.
 - `~/.codex/hooks.json` is the user-level Codex adapter that dispatches into the same runner.
 - Repo-local `.claude/settings.json` and `.codex/hooks.json` hook adapters are legacy project-level config and should be retired during migration.
 - Codex must mark `~/.codex/hooks.json` as trusted in Codex Settings before those hooks run.
-- Debug in this order: user-level adapter config -> `repo-harness-hook` (or fallback `repo-harness hook`) -> route registry -> `.ai/hooks/*`.
-- If `repo-harness-hook` reports `.ai/hooks` drift, refresh the repo-local copy with `repo-harness adopt --repo <root>`.
+- Debug in this order: user-level adapter config -> `repo-harness-hook` (or fallback `repo-harness hook`) -> route registry -> active hook source.
+- For hook product changes, edit `assets/hooks/<path>`, run `bun run sync:hooks`, then verify with `bun run check:hooks`. Package-only templates are classified in `assets/hooks/projection.json` and are not projected into `.ai/hooks/`.
 
 The installed adapter owns eight shared managed hook routes. Codex also installs
 three Codex-only bounded-delegation routes. The route tuple
@@ -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.8.0`
+- Generated workflow stamp: `repo-harness@0.8.0+template@0.8.0`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -663,13 +705,11 @@ bun run benchmark:skills --eval repair-agents-task-sync
   - `scripts/init-project.sh`
   - `scripts/create-project-dirs.sh`
 
-## Generated vs Self-Hosted Hook Parity
+## Generated vs Self-Hosted Hook Projection
 
-- Downstream hook behavior is defined by generated output from `assets/hooks/` plus
-  `assets/reference-configs/`.
-- This repo dogfoods the same contract, but self-host behavior is not magically in
-  sync with generated repos unless a change explicitly updates both surfaces.
-- Every hook change should say whether it affects `self-host`, `generated`, or `both`.
+- Downstream hook behavior is defined by `assets/hooks/` plus `assets/reference-configs/`.
+- This repo dogfoods the same hook runtime through `.ai/hooks/`, but that tree is generated from `assets/hooks/projection.json`.
+- Every hook change should update canonical `assets/hooks/` once, run `bun run sync:hooks`, and include `bun run check:hooks` in verification.
 
 ## Package Manager Defaults
 

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.8.0`。
 
 ## 工作原理
 
@@ -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 解析、
@@ -353,12 +360,13 @@ repo-harness mcp serve --repo . --transport http --profile orchestrator --enable
 
 ## Hook Authority Map
 
-- `.ai/hooks/` 是唯一应该优先编辑的 shared hook implementation。
+- `assets/hooks/` 是唯一人工维护的 shared hook implementation。本仓库的 `.ai/hooks/` 是给 `"hook_source": "repo"` dogfood 使用的 checked-in generated projection。
 - `~/.claude/settings.json` 是 user-level Claude adapter，负责 dispatch 到 opted-in repos。
 - `~/.codex/hooks.json` 是 user-level Codex adapter，dispatch 到同一个 runner。
 - Repo-local `.claude/settings.json` 和 `.codex/hooks.json` hook adapters 是 legacy project-level config，迁移时应退休。
 - Codex 必须在 Settings 里信任 `~/.codex/hooks.json`，hooks 才会执行。
-- 调试顺序：user-level adapter config -> `repo-harness-hook` 或 fallback `repo-harness hook` -> route registry -> `.ai/hooks/*`。
+- 调试顺序：user-level adapter config -> `repo-harness-hook` 或 fallback `repo-harness hook` -> route registry -> active hook source。
+- Hook 产品变更只改 `assets/hooks/<path>`，然后运行 `bun run sync:hooks` 和 `bun run check:hooks`。Package-only templates 在 `assets/hooks/projection.json` 分类，不投影到 `.ai/hooks/`。
 
 
 The installed adapter owns eight managed hook routes. The route tuple
@@ -437,8 +445,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.8.0`
+- Generated workflow stamp：`repo-harness@0.8.0+template@0.8.0`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 
@@ -611,11 +619,11 @@ bun run benchmark:skills --eval repair-agents-task-sync
   - `scripts/create-project-dirs.sh`
 - Legacy-doc migrator：`scripts/migrate-workflow-docs.ts`
 
-## Generated vs Self-Hosted Hook Parity
+## Generated vs Self-Hosted Hook Projection
 
-- 下游 hook 行为由 `assets/hooks/` 和 `assets/reference-configs/` 的生成输出定义。
-- 本仓库 dogfood 同一套 contract，但 self-host 行为不会自动与 generated repos 同步；变更必须显式更新两侧 surface。
-- 每个 hook 变更都要说明影响 `self-host`、`generated` 还是 `both`。
+- 下游 hook 行为由 `assets/hooks/` 和 `assets/reference-configs/` 定义。
+- 本仓库通过 `.ai/hooks/` dogfood 同一套 hook runtime，但这棵树由 `assets/hooks/projection.json` 生成。
+- 每个 hook 变更只应更新 canonical `assets/hooks/`，运行 `bun run sync:hooks`，并在验证里包含 `bun run check:hooks`。
 
 ## Package Manager Defaults
 

package/assets/hooks/AGENTS.md

@@ -11,6 +11,8 @@ Keep this file focused on the local contract for this primary functional block.
 - Treat `.ai/context/context-map.json` as the index of discoverable context files.
 - Do not keep pushing context files deeper by default; add lower-level files only for a separately owned functional block with its own commands and invariants.
 - Prefer repo-local workflow artifacts over tool-specific chat memory.
+- `assets/hooks/` is the only human-authored hook source. Treat `.ai/hooks/` as the generated self-host projection; after editing hook files, run `bun run sync:hooks`, then `bun run check:hooks`.
+- Do not hand-edit generated `.ai/hooks/` drift. Classify package-only or repo-only exceptions in `assets/hooks/projection.json`.
 
 <!-- BEGIN CAPABILITY CONTEXT -->
 ## Capability Context

package/assets/hooks/CLAUDE.md

@@ -11,6 +11,8 @@ Keep this file focused on the local contract for this primary functional block.
 - Treat `.ai/context/context-map.json` as the index of discoverable context files.
 - Do not keep pushing context files deeper by default; add lower-level files only for a separately owned functional block with its own commands and invariants.
 - Prefer repo-local workflow artifacts over tool-specific chat memory.
+- `assets/hooks/` is the only human-authored hook source. Treat `.ai/hooks/` as the generated self-host projection; after editing hook files, run `bun run sync:hooks`, then `bun run check:hooks`.
+- Do not hand-edit generated `.ai/hooks/` drift. Classify package-only or repo-only exceptions in `assets/hooks/projection.json`.
 
 <!-- BEGIN CAPABILITY CONTEXT -->
 ## Capability Context

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

@@ -0,0 +1,77 @@
+#!/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'* ]]
+}
+
+repo_harness_hook_cli() {
+  local lib_dir hooks_dir repo_root source_cli source_hook_cli
+
+  lib_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  hooks_dir="$(cd "$lib_dir/.." && pwd)"
+  repo_root="$(cd "$hooks_dir/../.." 2>/dev/null && pwd)"
+  source_cli="$repo_root/src/cli/index.ts"
+  source_hook_cli="$repo_root/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" "$@"
+    return $?
+  fi
+
+  if [[ -f "$source_hook_cli" ]] && command -v bun >/dev/null 2>&1; then
+    bun "$source_hook_cli" "$@"
+    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" "$@"
+    return $?
+  fi
+
+  if [[ -n "${REPO_HARNESS_CLI:-}" && -f "${REPO_HARNESS_CLI:-}" ]] && command -v bun >/dev/null 2>&1; then
+    bun "$REPO_HARNESS_CLI" "$@"
+    return $?
+  fi
+
+  if [[ -f "$source_cli" ]] && command -v bun >/dev/null 2>&1; then
+    bun "$source_cli" "$@"
+    return $?
+  fi
+
+  if command -v repo-harness-hook >/dev/null 2>&1; then
+    repo-harness-hook "$@"
+    return $?
+  fi
+
+  if command -v repo-harness >/dev/null 2>&1; then
+    repo-harness "$@"
+    return $?
+  fi
+
+  return 127
+}
+
+minimal_change_hook_entry() {
+  repo_harness_hook_cli minimal-change "$@"
+}
+
+review_rubric_prompt() {
+  repo_harness_hook_cli review-rubric --format prompt 2>/dev/null || true
+}

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

@@ -1288,6 +1288,166 @@ workflow_review_recommends_pass() {
   grep -Eq '^> \*\*Recommendation\*\*:[[:space:]]*pass[[:space:]]*$' "$review_file"
 }
 
+workflow_review_metadata_field() {
+  local review_file="${1:-}"
+  local field="${2:-}"
+  [[ -n "$review_file" && -f "$review_file" && -n "$field" ]] || return 1
+  awk -v field="$field" '
+    # Top-of-file metadata only: stop at the first section heading so a
+    # section-level "> **<field>**:" line (e.g. the External Acceptance section
+    # carries its own Reviewed Diff Fingerprint) can never be read as a top-level
+    # value when the real header omits it.
+    /^## / { exit }
+    index($0, "> **" field "**:") == 1 {
+      sub("^> \\*\\*" field "\\*\\*:[[:space:]]*", "");
+      gsub(/\r/, "");
+      print;
+      exit;
+    }
+  ' "$review_file"
+}
+
+workflow_review_fingerprint() {
+  workflow_review_metadata_field "${1:-}" "Reviewed Diff Fingerprint"
+}
+
+workflow_review_rubric_version() {
+  workflow_review_metadata_field "${1:-}" "Review Rubric Version"
+}
+
+# Classify the top-of-file Review Rubric Version. Echoes one of:
+#   absent     - no rubric line at all (a genuine pre-rubric legacy artifact)
+#   1          - the supported modern rubric version
+#   malformed  - a rubric line is present but is not a supported version
+#                (non-numeric, 0, an unsupported number, or quote/space garbage)
+# A present-but-unsupported rubric means the artifact claims a schema this gate
+# cannot evaluate, so callers must fail closed rather than fall through to the
+# lenient legacy path. Only a genuinely absent rubric stays lenient.
+workflow_review_rubric_class() {
+  local raw trimmed
+  raw="$(workflow_review_rubric_version "${1:-}")"
+  # Trim surrounding whitespace WITHOUT xargs: an unbalanced quote in the value
+  # makes xargs fail and emit nothing, which would silently downgrade a malformed
+  # rubric to "absent" (legacy lenient) — exactly the fail-open this prevents.
+  trimmed="${raw#"${raw%%[![:space:]]*}"}"
+  trimmed="${trimmed%"${trimmed##*[![:space:]]}"}"
+  if [[ -z "$trimmed" ]]; then
+    printf 'absent'
+  elif [[ "$trimmed" == "1" ]]; then
+    printf '1'
+  else
+    printf 'malformed'
+  fi
+}
+
+workflow_hook_cli_json() {
+  if [[ -n "${REPO_HARNESS_HOOK_CLI:-}" && -f "${REPO_HARNESS_HOOK_CLI:-}" ]] && command -v bun >/dev/null 2>&1; then
+    bun "$REPO_HARNESS_HOOK_CLI" "$@"
+    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" "$@"
+    return $?
+  fi
+  if [[ -n "${REPO_HARNESS_CLI:-}" && -f "${REPO_HARNESS_CLI:-}" ]] && command -v bun >/dev/null 2>&1; then
+    bun "$REPO_HARNESS_CLI" "$@"
+    return $?
+  fi
+  if command -v repo-harness-hook >/dev/null 2>&1; then
+    repo-harness-hook "$@"
+    return $?
+  fi
+  if command -v repo-harness >/dev/null 2>&1; then
+    repo-harness "$@"
+    return $?
+  fi
+  return 127
+}
+
+workflow_json_field() {
+  local json="${1:-}"
+  local field="${2:-}"
+  [[ -n "$json" && -n "$field" ]] || return 1
+  if command -v jq >/dev/null 2>&1; then
+    printf '%s' "$json" | jq -r ".$field // empty" 2>/dev/null || true
+    return
+  fi
+  if command -v bun >/dev/null 2>&1; then
+    JSON_INPUT="$json" JSON_FIELD="$field" bun -e '
+      try {
+        const parsed = JSON.parse(process.env.JSON_INPUT ?? "");
+        const value = parsed?.[process.env.JSON_FIELD ?? ""];
+        if (value != null) process.stdout.write(String(value));
+      } catch {}
+    ' 2>/dev/null || true
+  fi
+}
+
+workflow_current_review_fingerprint_json() {
+  # Bind the fingerprint to the resolved target branch so base_rev tracks the
+  # target tip; without --base the CLI falls back to HEAD, making the branch diff
+  # HEAD...HEAD (empty) and blinding the gate to target movement.
+  local target
+  target="$(workflow_target_branch)"
+  workflow_hook_cli_json review-fingerprint --base "$target" --format json 2>/dev/null || true
+}
+
+workflow_current_review_fingerprint_value() {
+  local json status fingerprint
+  json="$(workflow_current_review_fingerprint_json)"
+  status="$(workflow_json_field "$json" "status")"
+  [[ "$status" == "ok" ]] || return 1
+  fingerprint="$(workflow_json_field "$json" "fingerprint")"
+  [[ -n "$fingerprint" ]] || return 1
+  printf '%s' "$fingerprint"
+}
+
+workflow_review_freshness_status() {
+  local review_file="${1:-}"
+  local reviewed rubric_class current_json current_status current_fingerprint current_scope
+
+  reviewed="$(workflow_review_fingerprint "$review_file" | xargs || true)"
+  rubric_class="$(workflow_review_rubric_class "$review_file")"
+  if [[ "$rubric_class" == "malformed" ]]; then
+    # A malformed/unsupported rubric claims a schema this gate cannot evaluate;
+    # fail closed at the freshness stage instead of treating it as legacy.
+    printf 'malformed_schema\t-\tReview Rubric Version is malformed or unsupported; rerun /check to record the review under a supported rubric, or record a Manual Override.\n'
+    return 0
+  fi
+  if [[ -z "$reviewed" || "$reviewed" == "pending" || "$reviewed" == "unknown" ]]; then
+    # A supported rubric (v1+) with no concrete fingerprint was never bound to the
+    # diff: fail closed (`missing`). An `absent` rubric stays on the advisory legacy
+    # path here — the external-acceptance gate is the authority that requires a
+    # supported rubric (a rubric-less review fails external acceptance), so absent
+    # is still blocked at every Done/finish/verify gate that enforces external.
+    if [[ "$rubric_class" == "1" ]]; then
+      printf 'missing\t-\tReview fingerprint is missing for rubric v%s; rerun /check and peer acceptance to record the current Reviewed Diff Fingerprint.\n' "$rubric_class"
+      return 0
+    fi
+    printf 'legacy_missing\t-\tReview fingerprint is missing; rerun /check to refresh the review metadata.\n'
+    return 0
+  fi
+  if ! [[ "$reviewed" =~ ^sha256:[0-9a-f]{64}$ ]]; then
+    printf 'malformed\t%s\tReview fingerprint is malformed; rerun /check and peer acceptance.\n' "$reviewed"
+    return 0
+  fi
+
+  current_json="$(workflow_current_review_fingerprint_json)"
+  current_status="$(workflow_json_field "$current_json" "status")"
+  current_fingerprint="$(workflow_json_field "$current_json" "fingerprint")"
+  current_scope="$(workflow_json_field "$current_json" "scope")"
+  if [[ "$current_status" != "ok" || -z "$current_fingerprint" ]]; then
+    printf 'unknown\t-\tCurrent implementation diff fingerprint is unknown; rerun /check after git state is readable.\n'
+    return 0
+  fi
+  if [[ "$reviewed" != "$current_fingerprint" ]]; then
+    printf 'stale\t%s\tReview is stale for current implementation diff fingerprint %s; rerun /check and peer acceptance.\n' "$reviewed" "$current_fingerprint"
+    return 0
+  fi
+
+  printf 'pass\t%s\tReview fingerprint is fresh for %s.\n' "$reviewed" "${current_scope:-branch+staged+unstaged+untracked}"
+}
+
 workflow_external_acceptance_expected_reviewer() {
   local host="${HOOK_HOST:-}"
 
@@ -1409,6 +1569,51 @@ workflow_external_acceptance_status() {
     return 0
   fi
 
+  # Bind the peer's acceptance to the exact diff they reviewed. A supported rubric
+  # (v1) requires the External Acceptance section to carry its own current Reviewed
+  # Diff Fingerprint and scope; otherwise a stale F1 acceptance keeps satisfying the
+  # gate after the implementation moves to F2, because the top-of-file fingerprint
+  # is agent-editable. An absent or malformed rubric fails closed here — external
+  # acceptance is the authority that requires a supported rubric; Manual Override
+  # above is the only escape for a genuine pre-rubric legacy artifact.
+  local rubric_class section_fp section_scope current_fp
+  rubric_class="$(workflow_review_rubric_class "$review_file")"
+  case "$rubric_class" in
+    absent)
+      # An absent rubric cannot be proven to predate the rubric (it may have been
+      # stripped to skip binding), so fail closed. Manual Override above is the
+      # escape hatch for a genuine pre-rubric legacy artifact.
+      printf 'fail\t%s\t%s\tReview Rubric Version is missing; rerun peer acceptance under a supported rubric or record a Manual Override.\n' "${reviewer:--}" "${source:--}"
+      return 0
+      ;;
+    malformed)
+      # An unsupported rubric must not silently disable the binding check.
+      printf 'fail\t%s\t%s\tReview Rubric Version is malformed or unsupported; rerun peer acceptance under a supported rubric or record a Manual Override.\n' "${reviewer:--}" "${source:--}"
+      return 0
+      ;;
+    *)
+      section_fp="$(workflow_external_acceptance_field "$section" "Reviewed Diff Fingerprint" | xargs || true)"
+      section_scope="$(workflow_external_acceptance_field "$section" "Reviewed Scope" | xargs || true)"
+      current_fp="$(workflow_current_review_fingerprint_value || true)"
+      if [[ -z "$current_fp" ]]; then
+        printf 'fail\t%s\t%s\tCurrent implementation diff fingerprint is unknown; rerun peer acceptance after git state is readable.\n' "${reviewer:--}" "${source:--}"
+        return 0
+      fi
+      if ! [[ "$section_fp" =~ ^sha256:[0-9a-f]{64}$ ]]; then
+        printf 'fail\t%s\t%s\tExternal acceptance is missing a valid Reviewed Diff Fingerprint for rubric v%s; rerun peer acceptance for the current diff.\n' "${reviewer:--}" "${source:--}" "$rubric_class"
+        return 0
+      fi
+      if [[ "$section_fp" != "$current_fp" ]]; then
+        printf 'fail\t%s\t%s\tExternal acceptance fingerprint %s is stale for current implementation diff %s; rerun peer acceptance.\n' "${reviewer:--}" "${source:--}" "$section_fp" "$current_fp"
+        return 0
+      fi
+      if [[ "$section_scope" != "branch+staged+unstaged+untracked" ]]; then
+        printf 'fail\t%s\t%s\tExternal acceptance scope is %s; expected branch+staged+unstaged+untracked.\n' "${reviewer:--}" "${source:--}" "${section_scope:-missing}"
+        return 0
+      fi
+      ;;
+  esac
+
   printf 'pass\t%s\t%s\tExternal acceptance passed.\n' "$reviewer" "$source"
 }
 

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/projection.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "canonical_root": "assets/hooks",
+  "projection_target": ".ai/hooks",
+  "package_only": [
+    "projection.json",
+    "codex.hooks.template.json",
+    "settings.template.json"
+  ],
+  "repo_only": []
+}