repo-harness 0.7.5 → 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.5`.
+actual es `0.8.0`.
 
 ## Cómo funciona
 
@@ -419,8 +419,8 @@ Guards habituales:
 
 ## Release actual
 
-- npm package: `repo-harness@0.7.5`
-- Generated workflow stamp: `repo-harness@0.7.5+template@0.7.5`
+- 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.5`.
+ligne actuelle est `0.8.0`.
 
 ## Comment ça marche
 
@@ -424,8 +424,8 @@ Guards courants :
 
 ## Release actuelle
 
-- npm package : `repo-harness@0.7.5`
-- Generated workflow stamp : `repo-harness@0.7.5+template@0.7.5`
+- 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.5` です。
+ラインは `0.8.0` です。
 
 ## 仕組み
 
@@ -398,8 +398,8 @@ hook がブロックしたときは、まず terminal の構造化された出
 
 ## 現在の Release
 
-- npm package：`repo-harness@0.7.5`
-- Generated workflow stamp：`repo-harness@0.7.5+template@0.7.5`
+- 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.5`.
+is `0.8.0`.
 
 ## How It Works
 
@@ -439,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
@@ -535,8 +535,8 @@ Most common guards:
 
 ## Current Release
 
-- npm package: `repo-harness@0.7.5`
-- Generated workflow stamp: `repo-harness@0.7.5+template@0.7.5`
+- 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)
 
@@ -705,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.5`。
+Release notes 见 [`docs/CHANGELOG.md`](docs/CHANGELOG.md)，当前版本线是 `0.8.0`。
 
 ## 工作原理
 
@@ -360,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
@@ -444,8 +445,8 @@ hook block 工作时，先看 terminal 里的结构化输出。核心字段是
 
 ## 当前 Release
 
-- npm package：`repo-harness@0.7.5`
-- Generated workflow stamp：`repo-harness@0.7.5+template@0.7.5`
+- 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)
 
@@ -618,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

@@ -21,32 +21,57 @@ minimal_change_post_edit_enabled() {
   [[ "$compact" == *'"post_edit_observer":true'* ]]
 }
 
-minimal_change_hook_entry() {
-  local lib_dir hooks_dir source_hook_cli
+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)"
-  source_hook_cli="$(cd "$hooks_dir/../.." 2>/dev/null && pwd)/src/cli/hook-entry.ts"
+  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" minimal-change "$@"
+    bun "$REPO_HARNESS_HOOK_CLI" "$@"
     return $?
   fi
 
   if [[ -f "$source_hook_cli" ]] && command -v bun >/dev/null 2>&1; then
-    bun "$source_hook_cli" minimal-change "$@"
+    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" minimal-change "$@"
+    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 minimal-change "$@"
+    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/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": []
+}

package/assets/hooks/prompt-guard.sh

@@ -770,11 +770,31 @@ emit_waza_route_hint() {
 
   if pg_fact REVIEW_RELEASE; then
     echo "[WazaRoute] Review/release intent detected. Default route: Waza /check."
+    emit_review_rubric_prompt
+    emit_review_fingerprint_prompt
     emit_external_acceptance_prompt review
     emit_cross_review_hint merge
   fi
 }
 
+emit_review_rubric_prompt() {
+  local rubric
+  rubric="$(review_rubric_prompt || true)"
+  [[ -n "$rubric" ]] || return 0
+  printf '%s\n' "$rubric"
+}
+
+emit_review_fingerprint_prompt() {
+  local fingerprint review_file
+  fingerprint="$(workflow_current_review_fingerprint_value || true)"
+  review_file="$(workflow_active_review || true)"
+  echo "[ReviewFreshness] Current implementation diff fingerprint: ${fingerprint:-unknown}"
+  echo "[ReviewFreshness] Record these review metadata lines in ${review_file:-tasks/reviews/<slug>.review.md}:"
+  echo "> **Review Rubric Version**: 1"
+  echo "> **Reviewed Diff Fingerprint**: ${fingerprint:-unknown}"
+  echo "> **Reviewed Scope**: branch+staged+unstaged+untracked"
+}
+
 # Cross-review advisory: nudge the agent to consider an independent second
 # opinion from a different-vendor model. Advisory only (echo, exit 0); the agent
 # decides whether to act. Host-aware: in Codex suggest claude-review, otherwise
@@ -800,7 +820,7 @@ emit_cross_review_hint() {
 
 emit_external_acceptance_prompt() {
   local mode="${1:-review}"
-  local expected_reviewer expected_source command active_plan_local contract_file_local review_file checks_file
+  local expected_reviewer expected_source command active_plan_local contract_file_local review_file checks_file rubric fingerprint
 
   expected_reviewer="$(workflow_external_acceptance_expected_reviewer)"
   expected_source="$(workflow_external_acceptance_expected_source "$expected_reviewer")"
@@ -814,6 +834,8 @@ emit_external_acceptance_prompt() {
   contract_file_local="$(workflow_active_contract || true)"
   review_file="$(workflow_active_review || true)"
   checks_file="$(workflow_checks_file)"
+  rubric="$(review_rubric_prompt || true)"
+  fingerprint="$(workflow_current_review_fingerprint_value || true)"
 
   echo "[ExternalAcceptance] Review/release intent detected. Start peer acceptance in parallel with local /check."
   echo "[ExternalAcceptance] Mode: $mode"
@@ -821,11 +843,14 @@ emit_external_acceptance_prompt() {
   echo "[ExternalAcceptance] Current contract: ${contract_file_local:-"(none)"}"
   echo "[ExternalAcceptance] Current review: ${review_file:-tasks/reviews/<slug>.review.md}"
   echo "[ExternalAcceptance] Current checks: $checks_file"
+  echo "[ExternalAcceptance] Current diff fingerprint: ${fingerprint:-unknown}"
   echo "[ExternalAcceptance] Peer reviewer: $expected_reviewer via $command"
   echo "[ExternalAcceptance] Diff scope for peer: branch diff against target, staged diff, unstaged diff, and untracked files."
   cat <<EOF_EXTERNAL_ACCEPTANCE
 [ExternalAcceptance] Prompt to send with $command:
-Review the current sprint for acceptance only. Do not run /check. Do not edit files. Do not write files. Inspect the diff scope, contract, review evidence, and checks evidence, then return only a Markdown block that can be pasted into ${review_file:-tasks/reviews/<slug>.review.md}.
+Review the current sprint for acceptance only. Do not run /check. Do not edit files. Do not write files. Inspect the diff scope, contract, review evidence, checks evidence, and Review Rubric v1, then return only a Markdown block that can be pasted into ${review_file:-tasks/reviews/<slug>.review.md}.
+
+${rubric:-[ReviewRubric] Deep Diff Review Rubric v1 unavailable; use severity order P0/P1/P2/P3 and report no style-only nits.}
 
 ## External Acceptance Advice
 > **External Acceptance**: pass
@@ -833,6 +858,9 @@ Review the current sprint for acceptance only. Do not run /check. Do not edit fi
 > **External Source**: $expected_source
 > **External Started**: YYYY-MM-DDTHH:MM:SS+0800
 > **External Completed**: YYYY-MM-DDTHH:MM:SS+0800
+> **Review Rubric Version**: 1
+> **Reviewed Diff Fingerprint**: ${fingerprint:-unknown}
+> **Reviewed Scope**: branch+staged+unstaged+untracked
 
 - P1 blockers: none
 - P2 advisories:
@@ -1119,6 +1147,27 @@ if [ "$done_intent" -eq 1 ]; then
     exit 2
   fi
 
+  review_freshness="$(workflow_review_freshness_status "$review_file")"
+  IFS=$'\t' read -r review_freshness_state review_fingerprint review_freshness_message <<< "$review_freshness"
+  case "$review_freshness_state" in
+    pass)
+      ;;
+    legacy_missing)
+      # Advisory only: an absent rubric is blocked downstream by the external
+      # acceptance gate, which requires a supported rubric.
+      echo "[ReviewFreshness] WARN: $review_freshness_message"
+      ;;
+    *)
+      echo "[ReviewFreshnessGuard] $review_freshness_message"
+      hook_structured_error \
+        "ReviewFreshnessGuard" \
+        "$review_freshness_message" \
+        "Rerun Waza /check and peer acceptance so $review_file records the current Reviewed Diff Fingerprint." \
+        "quality_gate"
+      exit 2
+      ;;
+  esac
+
   external_status="$(workflow_external_acceptance_status "$review_file")"
   IFS=$'\t' read -r external_state external_reviewer external_source external_message <<< "$external_status"
   if [ "$external_state" != "pass" ] && [ "$external_state" != "manual_override" ]; then

package/assets/hooks/stop-orchestrator.sh

@@ -385,6 +385,17 @@ refresh_handoff
 minimal_change_refresh_review
 minimal_change_append_handoff
 
+review_file="$(workflow_active_review || true)"
+if [[ -n "$review_file" && -f "$review_file" ]]; then
+  review_freshness="$(workflow_review_freshness_status "$review_file")"
+  IFS=$'\t' read -r review_freshness_state _review_fingerprint review_freshness_message <<< "$review_freshness"
+  case "$review_freshness_state" in
+    stale|malformed|malformed_schema|unknown|missing)
+      echo "[ReviewFreshness] $review_freshness_message" >&2
+      ;;
+  esac
+fi
+
 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