@tyroneross/build-loop 0.30.3 → 0.35.0

package/agents/plan-critic.md

@@ -18,7 +18,7 @@ description: |
   user: "Run plan-critic on the proposed plan"
   assistant: "I'll dispatch plan-critic to surface scope-split overlaps, missing alternatives, and headline drift."
   </example>
-model: sonnet
+model: fable
 color: purple
 tools: ["Read", "Grep", "Glob"]
 ---
@@ -34,9 +34,10 @@ You are an adversarial plan critic. You have no ability to fix files — only to
 
 ## Severity policy
 
-- All your findings cap at **WARN**. You do not block.
-- Only `plan_verify.py` emits BLOCKERs.
-- The orchestrator decides whether your WARNs require plan revision.
+- All your **emitted** findings cap at **WARN** — you report problems, you never decide whether the run halts (single-judge bias is documented; the gate is the orchestrator's, not yours).
+- Only `plan_verify.py` emits deterministic BLOCKERs. Your findings are reasoning-level.
+- **The orchestrator gates on your WARNs conditionally:** on high-stakes plans (`synthesisDensity > 5`, `triggers.riskSurfaceChange`, `stakes >= medium`, or `dispatch_tier: frontier`) your WARNs are treated as **blocking** — Phase 2 does not finish until each is revised or explicitly overridden. On all other plans they stay **advisory** (today's behavior). This is the cheapest way to put a Frontier verdict on the high-stakes plan path before any implementer runs.
+- Ground every finding in an **objective signal** — *what in the plan* fails, with a `file:line` and the rule it violates — never "I'm unsure about this." Self-reported confidence is never a gate trigger; overconfidence is documented.
 
 ## What to flag
 
@@ -47,6 +48,7 @@ You are an adversarial plan critic. You have no ability to fix files — only to
 | **MECE scope** | Phase splits / file ownership splits are mutually exclusive and collectively exhaustive. Flag overlapping owners (same file in two phases) and unowned responsibilities (required behavior with no phase). |
 | **Headline drift** | Section headlines align with the stated intent across the doc. Flag when a section's claims contradict its own header or the plan's top-level goal. |
 | **Verification depth** | Factual assertions about repo state (callers, imports, package presence) cite a specific verification command or path — not just "verified". |
+| **Activation Map adequacy** | When the plan proposes a new event-driven / call-site component but has NO `## Activation Map`, WARN even if `plan_verify` stayed silent (its keyword heuristic has bounded recall — you are the recall backstop). When the plan has an `## Activation Map` (required for new event-driven / call-site components — `plan_verify` enforces the section's presence and that each entry carries `trigger:` + `verified-live:`), grade whether each `trigger:` names a *real host event or call site*, not an aspiration. Inadequate: "runs at review time", "fires when needed", "on the relevant event". Adequate: "PostToolUse:Bash matcher in hooks/hooks.json", "SessionStart hook", "pre-commit hook in .pre-commit-config.yaml". WARN on any vague trigger, and WARN on any `verified-live: pending` entry that has no corresponding verification task before Report. |
 
 ## Required output shape
 
@@ -55,7 +57,7 @@ Emit a list of findings, each conforming to the Plan Evidence Contract used by `
 ```json
 {
   "claim_text": "...",
-  "claim_kind": "less_invasive_shim|marker_adequacy|scope_mece|headline_drift|verification_depth",
+  "claim_kind": "less_invasive_shim|marker_adequacy|scope_mece|headline_drift|verification_depth|activation_map_adequacy",
   "subject": {"path": null, "symbol": null, "noun": null},
   "verification_command": null,
   "evidence": {"file": "<plan-path>", "line": 42, "snippet": "..."},
@@ -63,7 +65,7 @@ Emit a list of findings, each conforming to the Plan Evidence Contract used by `
   "marker": null,
   "severity": "WARN",
   "confidence": "low|medium|high",
-  "rule_id": "alternatives-considered|marker-adequacy|scope-mece|headline-drift|verification-depth"
+  "rule_id": "alternatives-considered|marker-adequacy|scope-mece|headline-drift|verification-depth|activation-map-adequacy"
 }
 ```
 

package/agents/promotion-reviewer.md

@@ -14,7 +14,7 @@ description: |
   user: "Promote this experiment"
   assistant: "I'll run promotion-reviewer first to surface any policy variances, then present the verdict + diff for user confirmation."
   </example>
-model: opus
+model: fable
 color: purple
 tools: ["Read", "Grep", "Glob"]
 ---

package/agents/retrospective-synthesizer.md

@@ -65,9 +65,23 @@ The Python pipeline produces deterministic bullets from captured signals. When y
 
 If you do enrich, re-write the active file using `Edit` (preserving the headers; only adding new bullets under existing section headers). Skip enrichment when the deterministic output already captures everything.
 
-## Step 3 — Return envelope
+## Step 3 — Emit closeout status (mandatory)
 
-Return the JSON envelope verbatim from Step 1 (plus an `enrichment_applied: true|false` flag if you modified the file in Step 2). Example shape:
+After Step 2, run the machine-readable closeout — this is the durable enforcement layer for the build-loop memory closeout contract:
+
+```bash
+python3 -m closeout \
+  --workdir "$WORKDIR" \
+  --run-id "$RUN_ID" \
+  --source post-push \
+  --json
+```
+
+The script emits exactly one `closeout_status`: `wrote_memory` | `queued_pending_lesson` | `no_durable_lesson`. Copy it into your envelope under `closeout_status` and `closeout_reason`. The script is non-raising; on degraded internal error it returns exit 0 with `error:` populated — surface that under `closeout_error` and continue. A skipped closeout on a run with durable signal is a DETECTABLE failure (asserted by `scripts/closeout/test_status.py`), so this step is non-optional.
+
+## Step 4 — Return envelope
+
+Return the JSON envelope verbatim from Step 1 (plus an `enrichment_applied: true|false` flag if you modified the file in Step 2, plus `closeout_status` / `closeout_reason` / `closeout_error` from Step 3). Example shape:
 
 ```json
 {
@@ -78,7 +92,10 @@ Return the JSON envelope verbatim from Step 1 (plus an `enrichment_applied: true
   "status":              "ok",
   "reason":              null,
   "meta":                { "run_id": "...", "prompt_count": 24, "cluster_count": 2, "transcript_present": true },
-  "enrichment_applied":  false
+  "enrichment_applied":  false,
+  "closeout_status":     "wrote_memory | queued_pending_lesson | no_durable_lesson",
+  "closeout_reason":     "human-readable reason",
+  "closeout_error":      null
 }
 ```
 

package/agents/scope-auditor.md

@@ -1,7 +1,7 @@
 ---
 name: scope-auditor
 description: Read-only Plan→Execute boundary check. For every commit that changes a public function/component/type signature, traces every caller-site outside the commit's owned-files, then either confirms `internal_only: true` or appends the missing caller files to the appropriate commit's owned-files list. Prevents the "fan-out scope-blindness" defect class observed in round-2 of dispatch-pattern testing (example-app 2026-05-07).
-model: opus
+model: fable
 tools: ["Read", "Grep", "Glob"]
 ---
 

package/agents/security-reviewer.md

@@ -14,7 +14,7 @@ description: |
   user: "Security check on the auth changes"
   assistant: "I'll use the security-reviewer agent — diff vs OWASP Web A01/A03 + LLM06 + ASI03 — and emit a structured findings report."
   </example>
-model: claude-sonnet-4-6
+model: fable
 color: red
 tools: ["Read", "Grep", "Glob"]
 ---

package/agents/self-improvement-architect.md

@@ -115,7 +115,7 @@ Keep the Experiment section small otherwise: one metric, one decision rule, expl
 ## Constraints
 
 - **No invention**. If the pattern evidence is weak, flag it in your synthesis output (`warning: low-signal pattern, artifact is speculative`) and produce a minimal skill.
-- **No promotion authority**. You draft, never promote. Promotion is Opus 4.7 territory via build-orchestrator.
+- **No promotion authority**. You draft, never promote. Promotion verdict is `promotion-reviewer` (Fable) territory, dispatched via build-orchestrator.
 - **No changes outside `.build-loop/`**. Experimental artifacts are project-local.
 - **Include a removal pointer**. The user must be able to delete your artifact with one command.
 - **Use `plugin-dev` skills**. Do not wing the SKILL.md format. Load the reference.

package/commands/{handoff.md → compose-handoff.md}

@@ -79,7 +79,7 @@ Present the full output. Also note:
 
 To launch a fresh session after handoff, re-run with `--launch`:
 ```
-/build-loop:handoff --launch
+/build-loop:compose-handoff --launch
 ```
 
 {{/if}}
@@ -90,18 +90,18 @@ To launch a fresh session after handoff, re-run with `--launch`:
 
 **Emit to stdout (default)**
 ```
-/build-loop:handoff
+/build-loop:compose-handoff
 ```
 
 **Write to file**
 ```
-/build-loop:handoff --workdir /path/to/repo
+/build-loop:compose-handoff --workdir /path/to/repo
 ```
 (Use `--output` flag in the script directly for file output.)
 
 **Emit + launch fresh session**
 ```
-/build-loop:handoff --launch
+/build-loop:compose-handoff --launch
 ```
 
 **JSON envelope (for programmatic use)**

package/commands/{optimize.md → optimize-run.md}

@@ -1,5 +1,5 @@
 ---
-name: optimize
+name: optimize-run
 description: "(Advanced override — `/build-loop:run` auto-routes here; use this only to force the mode.) Run autonomous metric-driven optimization. Detects available targets or accepts a specific one."
 argument-hint: "[target]"
 ---

package/commands/{agent-rally-point.md → rally-point.md}

@@ -178,7 +178,7 @@ python3 ${CLAUDE_PLUGIN_ROOT}/scripts/coordination_bootstrap.py \
   --json
 ```
 
-Example invocation: `/agent-rally-point init v0130-feature-x "Add new feature X across orchestrator + bootstrap + tests"`
+Example invocation: `/build-loop:rally-point init v0130-feature-x "Add new feature X across orchestrator + bootstrap + tests"`
 
 Example output:
 
@@ -220,7 +220,7 @@ python3 ${CLAUDE_PLUGIN_ROOT}/scripts/agent_rally.py lead <op> \
 - `relinquish` — give up the lead so the next `claim` succeeds immediately.
 - `status` — read the current lead + `lease_valid`.
 
-Example: `/agent-rally-point lead status`
+Example: `/build-loop:rally-point lead status`
 
 ### `escalate <reason>`
 
@@ -269,7 +269,7 @@ Shows the subcommand reference table (replaces what the no-args case used to do
 Outputs:
 
 ```
-/agent-rally-point — inspect or invoke build-loop's multi-session coordination
+/build-loop:rally-point — inspect or invoke build-loop's multi-session coordination
 
 Subcommands:
   status (default)        Sensor poll: active peers, unresolved verdicts, coord file

package/commands/{research.md → research-run.md}

@@ -1,5 +1,5 @@
 ---
-name: research
+name: research-run
 description: "(Advanced override — `/build-loop:run` auto-routes here; use this only to force the mode.) Generate a repo-grounded research packet without committing to build. Pre-decision analysis."
 argument-hint: "[topic]"
 ---

package/commands/setup-memory.md

@@ -0,0 +1,32 @@
+---
+description: "Set up or verify the build-loop central memory store (build-loop-memory). Guided and idempotent — copies only the packaged public seed, never overwrites your content. Safe to re-run."
+argument-hint: "[--check]"
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+{{#if ARGUMENTS}}
+{{#contains ARGUMENTS "--check"}}
+Run `python3 "${CLAUDE_PLUGIN_ROOT:-$PWD}/scripts/install_memory.py" --check` and report the memory store status: which template files and which lanes (`indexes/`, `projects/`) exist vs are missing. Do not write anything.
+{{else}}
+Run `python3 "${CLAUDE_PLUGIN_ROOT:-$PWD}/scripts/install_memory.py" --guided` and report what was seeded vs already present, then surface the installer's printed next steps to the user.
+{{/contains}}
+{{else}}
+Run `python3 "${CLAUDE_PLUGIN_ROOT:-$PWD}/scripts/install_memory.py" --guided` and report what was seeded vs already present, then surface the installer's printed next steps to the user.
+{{/if}}
+
+---
+
+## Reference
+
+**Guided setup (idempotent — public seed only, no personal content):**
+```
+/build-loop:setup-memory
+```
+
+**Status check (no writes):**
+```
+/build-loop:setup-memory --check
+```
+
+The store lives at `memory_store_root()`. Resolution: an env override (`$BUILD_LOOP_MEMORY_STORE_ROOT` / `$BUILD_LOOP_MEMORY_ROOT` / `$AGENT_MEMORY_ROOT`), else a pre-existing legacy `~/dev/git-folder/build-loop-memory` if it is already on disk, else the neutral fresh-install default `~/.build-loop-memory`. On a fresh machine it is also bootstrapped automatically on session start by `hooks/session-start-memory.sh` when entirely absent; this command is the manual / repair path and the way to see what's present. Research packets, project lessons, decisions, and debugging memory all persist under this store.

package/commands/{plan-verify.md → verify-plan.md}

@@ -1,5 +1,5 @@
 ---
-name: plan-verify
+name: verify-plan
 description: "Deterministic verifier for plan markdown — grep-checkable rules (delete-with-callers, numeric-drift, route-change-evidence, package-state, missing-evidence). Run before accepting a Phase 2 plan."
 argument-hint: "<plan.md>"
 ---

package/docs/agent-surface-policy.md

@@ -1,25 +1,42 @@
 # Agent Surface Policy
 
-Build Loop exposes a small public entrypoint set and keeps implementation
-helpers internal.
+Build Loop keeps one user-facing Codex entrypoint while preserving the richer
+Claude Code skill tree for hosts that can route helpers internally.
 
 ## Public Entry Points
 
-These are the only skills that should appear as user-facing Build Loop choices:
+Codex must expose exactly one user-facing Build Loop choice:
 
-- `build-loop` — main multi-step code workflow
-- `debug-loop` — root-cause debugging workflow
-- `optimize` — metric-driven optimization
-- `research` — repo-grounded pre-build research
-- `knowledge` — durable decisions and lessons
-- `handoff` — compose a durable handoff from build-loop run state (BL-4)
+- `build-loop` — main workflow and router for build, fix, debug, optimize,
+  research, knowledge capture, handoff, and plugin-test work
+
+Claude Code may expose advanced direct overrides in its command/skill surface
+where useful:
+
+- `build-loop`
+- `debug-loop`
+- `optimize`
+- `research`
+- `knowledge`
+- `handoff`
 
 ## Host Rules
 
-Codex and ChatGPT use `.codex-plugin/plugin.json`, which points at
-`./codex-skills`. That directory contains wrapper skills for the public
-entrypoints only. The full `./skills` tree still ships in the package for
-internal references.
+Codex and ChatGPT install from `plugin-artifacts/codex`, not from the source
+repo root. Codex auto-discovers root `skills/*/SKILL.md` files and manifest
+skill paths supplement that default, so installing the source root leaks every
+internal helper into the picker. The artifact is generated by:
+
+```bash
+python3 scripts/build_codex_plugin_artifact.py --source . --target plugin-artifacts/codex
+```
+
+The artifact contains one `skills/build-loop/SKILL.md` copied from the
+canonical workflow and `.codex-plugin/plugin.json` rewritten to
+`"skills": "./skills"`. It must not contain any other `SKILL.md` files.
+
+The local Codex marketplace (`.agents/plugins/marketplace.json`) points at this
+artifact. Release and marketplace updates must do the same.
 
 Claude Code keeps `.claude-plugin/plugin.json` pointed at `./skills` because
 commands and orchestrator agents load internal skills by qualified name. Helper
@@ -27,19 +44,20 @@ skills must set `user-invocable: false`; the public entrypoints set
 `user-invocable: true`.
 
 Cursor and other AGENTS.md-style tools should treat `AGENTS.md` plus this file
-as the routing contract. Start from the public entrypoints above. Read helper
-files under `skills/` only when the active entrypoint, a command, or an
-orchestrator instruction explicitly references them.
+as the routing contract. Start from `build-loop`. Read helper files under
+`skills/` only when the active entrypoint, a command, or an orchestrator
+instruction explicitly references them.
 
 ## Cache Hygiene
 
 Plugin cache pruning is explicit and auditable:
 
 ```bash
+npm run codex:sync-cache
 python3 scripts/prune_plugin_cache.py --source . --apply
 ```
 
-The command keeps the current host manifest version and deletes older verified
-cache directories for the same plugin. It checks both `.codex-plugin/plugin.json`
-and `.claude-plugin/plugin.json` by default. Use `--host codex` or
-`--host claude` for a single host.
+`npm run codex:sync-cache` rebuilds the slim artifact first, then syncs that
+artifact into the Codex cache. The prune command keeps the current host manifest
+version and deletes older verified cache directories for the same plugin. Use
+`--host codex` or `--host claude` for a single host.

package/docs/memory-setup.md

@@ -1,12 +1,17 @@
 # Memory Setup
 
 Build-loop's advisory judges and the Phase 1 Assess memory-load step read from
-one consolidated tree under `~/dev/git-folder/build-loop-memory/` by default:
+one consolidated tree. The root (`<memory-root>` below) is resolved by
+`scripts/_paths.memory_store_root()`:
+
+1. an env override — `$BUILD_LOOP_MEMORY_STORE_ROOT` / `$BUILD_LOOP_MEMORY_ROOT` / `$AGENT_MEMORY_ROOT`;
+2. else a pre-existing legacy `~/dev/git-folder/build-loop-memory` if it is already on disk (installs that predate the neutral default keep their location with zero config);
+3. else the neutral fresh-install default `~/.build-loop-memory`.
 
 | Tier | Location | Owner | Versioning |
 |---|---|---|---|
-| Global | `~/dev/git-folder/build-loop-memory/` plus top-level lanes such as `lessons/` | This user | **Should be in a private git repo** (your lessons live here) |
-| Project | `~/dev/git-folder/build-loop-memory/projects/<slug>/` (slug derived via `scripts/_paths.derive_slug_from_cwd` — basename of the git repo root, lowercased + normalized; `workers/` sub-component becomes `<slug>/workers`) | This user | Same private repo as global |
+| Global | `<memory-root>/` plus top-level lanes such as `lessons/` | This user | **Should be in a private git repo** (your lessons live here) |
+| Project | `<memory-root>/projects/<slug>/` (slug derived via `scripts/_paths.derive_slug_from_cwd` — basename of the git repo root, lowercased + normalized; `workers/` sub-component becomes `<slug>/workers`) | This user | Same private repo as global |
 
 > **History** — until PR 3 of the memory-consolidation series (merged 2026-05-13), the legacy per-repo location was also read by `memory_facade._resolve_memory_dirs` as a transitional shim. As of PR 3, only the consolidated tree is read; any pre-migration content still at the legacy path is invisible. Operators with such content should run `scripts/migrate_project_memory.py --apply` (idempotent), then `scripts/cleanup_legacy_memory_stubs.py --apply` to remove the now-inert `.MOVED.md` stubs.
 
@@ -20,10 +25,10 @@ operator preferences that are not appropriate for public distribution.
 
 ```bash
 # Guided terminal install. This validates the packaged public seed first, then
-# creates ~/dev/git-folder/build-loop-memory/ with scaffold-only files.
+# creates <memory-root>/ with scaffold-only files.
 python3 ${CLAUDE_PLUGIN_ROOT}/scripts/install_memory.py --guided
 
-# Bootstrap with templates (creates ~/dev/git-folder/build-loop-memory/ if missing,
+# Bootstrap with templates (creates <memory-root>/ if missing,
 # seeds constitution.md + MEMORY.md from templates/memory/, plus indexes/ and projects/)
 python3 ${CLAUDE_PLUGIN_ROOT}/scripts/install_memory.py
 
@@ -37,7 +42,7 @@ python3 ${CLAUDE_PLUGIN_ROOT}/scripts/install_memory.py --validate-seed
 This creates:
 
 ```
-~/dev/git-folder/build-loop-memory/
+<memory-root>/
 ├── constitution.md     # template — replace with your invariants
 ├── MEMORY.md           # template — index for entries you add
 ├── indexes/            # rebuildable local indexes, including semantic_facts.sqlite
@@ -79,7 +84,7 @@ The repo should contain `constitution.md` and `MEMORY.md` plus your existing les
 
 ```bash
 python3 scripts/install_memory.py
-cd ~/dev/git-folder/build-loop-memory
+cd <memory-root>   # default ~/.build-loop-memory on a fresh install
 git init
 git add constitution.md MEMORY.md
 git commit -m "init: build-loop memory scaffolding"
@@ -150,7 +155,7 @@ Keep `MEMORY.md` under ~200 lines; entries past that get truncated when loaded i
 ## What about decisions?
 
 The **canonical decision store** is
-`~/dev/git-folder/build-loop-memory/projects/<project>/decisions/`. It is
+`<memory-root>/projects/<project>/decisions/`. It is
 project-tagged and written by `scripts/write_decision.py` — it captures the
 discrete "we decided X" events of any project.
 
@@ -158,11 +163,11 @@ The top-level `lessons/` lane is for **cross-project lessons** — patterns and
 feedback that apply broadly, not project-specific decisions.
 
 ```
-~/dev/git-folder/build-loop-memory/                  # canonical root
-~/dev/git-folder/build-loop-memory/lessons/          # cross-project lessons
-~/dev/git-folder/build-loop-memory/indexes/updates.jsonl  # global update ledger
-~/dev/git-folder/build-loop-memory/projects/<slug>/  # project-local memory
-~/dev/git-folder/build-loop-memory/projects/_archive/<slug>/  # retired projects, still queryable
+<memory-root>/                  # canonical root
+<memory-root>/lessons/          # cross-project lessons
+<memory-root>/indexes/updates.jsonl  # global update ledger
+<memory-root>/projects/<slug>/  # project-local memory
+<memory-root>/projects/_archive/<slug>/  # retired projects, still queryable
 <repo>/.build-loop/memory/                           # legacy project location — no longer read (PR 3 removed the shim); migrate via scripts/migrate_project_memory.py
 <repo>/.episodic/decisions/                          # legacy local decision store (migration/archive)
 ```
@@ -215,7 +220,7 @@ If any of these fail, see `references/memory-systems.md` for the full backend to
 
 ## Privacy
 
-Treat `~/dev/git-folder/build-loop-memory/` as containing potentially-sensitive context:
+Treat `<memory-root>/` as containing potentially-sensitive context:
 
 - Operator preferences, project-specific decisions, client names if you write them in
 - Constitution rules may reveal architectural patterns from past projects

package/hooks/_resolve_python.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com>
+# SPDX-License-Identifier: Apache-2.0
+#
+# _resolve_python.sh — source (don't exec) to set `$_py` to a usable python3
+# without depending on a populated PATH. Hooks run under a minimal PATH
+# (/usr/bin:/bin), so resolve via `command -v` then absolute fallbacks. Sets
+# `_py=""` when none is found.
+#
+#   . "$(dirname "$0")/_resolve_python.sh"
+#   [ -n "$_py" ] || exit 0
+#
+# Single source of truth for the resolver shared by closeout.sh,
+# session-start-closeout.sh, and post-push-closeout.sh. See memory
+# `reference_hooks_minimal_path_failopen`.
+
+_py=""
+for _candidate in python3 python; do
+    if command -v "$_candidate" >/dev/null 2>&1; then
+        _py="$_candidate"
+        break
+    fi
+done
+for _fallback in /usr/bin/python3 /usr/local/bin/python3 /opt/homebrew/bin/python3; do
+    if [ -z "$_py" ] && [ -x "$_fallback" ]; then
+        _py="$_fallback"
+    fi
+done

package/hooks/closeout.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com>
+# SPDX-License-Identifier: Apache-2.0
+#
+# closeout.sh — structural run-close shim for INLINE build-loop runs (f6).
+#
+# Backs the Claude Code `Stop` hook and the Codex `Stop` equivalent (see
+# hooks/hooks.json + .codex/hooks.json). Thin minimal-PATH-safe wrapper around
+# scripts/stop_closeout.py, which holds the (tested) logic. Mirrors the existing
+# `commit_state_check.py --hook` invocation pattern.
+#
+#   $1 = mode: "stop" (default) | "session-start"
+#
+# Contract:
+#   - Advisory + fail-open: ALWAYS exit 0; never `decision: block`.
+#   - Self-gates on `.build-loop/` presence (walk up); silent elsewhere — safe
+#     to install globally.
+#   - Minimal-PATH safe: hooks run under /usr/bin:/bin. Resolve python3 via
+#     `command -v` + absolute fallbacks; missing → silent exit 0.
+#   - stdin (the hook JSON payload, carrying session_id) is forwarded to python
+#     untouched so stop_closeout.py can read the session id.
+#
+# See memory `reference_hooks_minimal_path_failopen`.
+
+set -u
+
+MODE="${1:-stop}"
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-${PWD}}"
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${PROJECT_DIR}}"
+
+# Walk up from the project dir to find a `.build-loop/`. Absent → silent exit 0
+# (this hook is safe to install globally; it does nothing outside a build-loop repo).
+_dir="$PROJECT_DIR"
+_found=""
+for _ in 1 2 3 4 5 6 7 8; do
+    if [ -d "${_dir}/.build-loop" ]; then
+        _found="$_dir"
+        break
+    fi
+    _parent="$(dirname "$_dir")"
+    [ "$_parent" = "$_dir" ] && break
+    _dir="$_parent"
+done
+[ -n "$_found" ] || exit 0
+
+# Resolve a python3 binary without depending on a populated PATH (shared helper).
+_HOOK_DIR="$(dirname "$0")"
+_py=""
+[ -f "${_HOOK_DIR}/_resolve_python.sh" ] && . "${_HOOK_DIR}/_resolve_python.sh"
+[ -n "$_py" ] || exit 0
+
+SCRIPT="${PLUGIN_ROOT}/scripts/stop_closeout.py"
+[ -f "$SCRIPT" ] || exit 0
+
+# Emit whatever the helper prints (valid hook JSON), then exit 0 no matter what.
+"$_py" "$SCRIPT" --workdir "$_found" --mode "$MODE" --hook 2>/dev/null || printf '{}'
+exit 0

package/hooks/git/pre-push

@@ -65,11 +65,18 @@ def _repo_root() -> Path:
     return Path.cwd()
 
 
-def _fail_open(reason: str) -> int:
-    """Internal-error path: print to stderr, return 0 (allow push)."""
+def _fail_open(reason: str, *, repo: Path | None = None) -> int:
+    """Internal-error path: print to stderr, return 0 (allow push).
+
+    Even on the internal-error fail-open path we still ARM the post-push
+    closeout baton: a missing ``push_hold`` import shouldn't silently drop
+    the durable-memory contract for ad-hoc pushes.
+    """
     sys.stderr.write(
         f"[build-loop pre-push] internal error — allowing push: {reason}\n"
     )
+    if repo is not None:
+        _arm_post_push_closeout(repo)
     return 0
 
 
@@ -110,7 +117,59 @@ def _format_block_message(verdict: dict) -> str:
     )
 
 
+def _arm_post_push_closeout(repo: Path) -> None:
+    """Drop a tiny JSON baton at ``.build-loop/closeout/armed.json``.
+
+    Git has no native client-side post-push hook. We arm a baton here so the
+    next session-start handler (``hooks/session-start-closeout.sh``) drains it
+    by invoking ``python3 -m closeout --source post-push-armed``.
+
+    Fail-open by design — any error is silently swallowed; an armed baton is a
+    nice-to-have, never a push blocker.
+    """
+    try:
+        from datetime import datetime, timezone
+        import json as _json
+        import subprocess as _sp
+        import tempfile as _tf
+
+        bl_dir = repo / ".build-loop" / "closeout"
+        bl_dir.mkdir(parents=True, exist_ok=True)
+        head = ""
+        try:
+            head = _sp.check_output(
+                ["git", "rev-parse", "HEAD"],
+                cwd=str(repo),
+                stderr=_sp.DEVNULL,
+                text=True,
+            ).strip()
+        except (_sp.CalledProcessError, FileNotFoundError, OSError):
+            pass
+
+        payload = {
+            "armed_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+            "source": "post-push-armed",
+            "head_sha": head or None,
+        }
+        target = bl_dir / "armed.json"
+        fd, tmp = _tf.mkstemp(dir=str(bl_dir), prefix=".armed-", suffix=".json")
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                _json.dump(payload, fh, indent=2, sort_keys=True)
+                fh.write("\n")
+            os.replace(tmp, target)
+        finally:
+            if os.path.exists(tmp):
+                try:
+                    os.unlink(tmp)
+                except OSError:
+                    pass
+    except Exception:  # noqa: BLE001 — never break a push for the baton
+        return
+
+
 def main() -> int:
+    repo: Path | None = None
     try:
         repo = _repo_root()
         scripts_dir = repo / "scripts"
@@ -119,22 +178,26 @@ def main() -> int:
         try:
             import push_hold  # type: ignore
         except Exception as exc:  # pragma: no cover — exercised by installer test
-            return _fail_open(f"could not import push_hold: {exc!r}")
+            return _fail_open(f"could not import push_hold: {exc!r}", repo=repo)
 
         try:
             stdin_lines = sys.stdin.readlines()
         except OSError as exc:
-            return _fail_open(f"could not read stdin: {exc!r}")
+            return _fail_open(f"could not read stdin: {exc!r}", repo=repo)
 
         verdict = push_hold.evaluate_push(repo, stdin_lines, env=os.environ)
         action = verdict.get("action", "allow")
         if action == "block":
             sys.stderr.write(_format_block_message(verdict))
             return int(verdict.get("exit_code") or 1)
-        # allow / bypass / anything else → exit 0
+        # allow / bypass / anything else → exit 0.
+        # Arm the post-push closeout baton BEFORE the push completes — git has
+        # no native client-side post-push hook, so the next session-start
+        # drains the baton via ``python3 -m closeout --source post-push-armed``.
+        _arm_post_push_closeout(repo)
         return 0
     except Exception as exc:  # noqa: BLE001 — broad on purpose; we MUST fail-open
-        return _fail_open(f"unhandled exception: {exc!r}")
+        return _fail_open(f"unhandled exception: {exc!r}", repo=repo)
 
 
 if __name__ == "__main__":