@tyroneross/build-loop 0.36.0 → 0.43.0

package/hooks/stop-transcript-sweep.sh

@@ -0,0 +1,173 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com>
+# SPDX-License-Identifier: Apache-2.0
+#
+# stop-transcript-sweep.sh — launch ONE background transcript sweep from the
+# Claude Code `Stop` hook.
+#
+#   $1 = sweep: all | decisions | corrections | findings | cost-ledger
+#
+#        `all` is the ONLY mode that should be REGISTERED as a hook. The four
+#        sweeps share a firing moment, an input, and an intent (extract signals
+#        from this session's transcript), so four registrations were four
+#        copies of one hook -- each re-resolving and re-normalizing the same
+#        transcript. One hook resolves once and fans out. The individual modes
+#        remain callable for testing and manual re-runs.
+#
+# WHY THIS EXISTS (the defect it fixes)
+# ------------------------------------
+# The four Stop-hook sweeps were previously guarded inline with
+# `if [ -n "$CLAUDE_TRANSCRIPT_PATH" ]; then ... fi`. **There is no
+# `CLAUDE_TRANSCRIPT_PATH` environment variable.** Claude Code delivers the
+# transcript path ONLY inside the stdin JSON payload, as `transcript_path`
+# (see https://code.claude.com/docs/en/hooks.md — documented hook env vars are
+# CLAUDE_PROJECT_DIR / CLAUDE_PLUGIN_ROOT / CLAUDE_PLUGIN_DATA / CLAUDE_EFFORT /
+# CLAUDE_CODE_REMOTE / CLAUDE_CODE_BRIDGE_SESSION_ID / CLAUDE_PLUGIN_OPTION_*).
+# The guard was therefore false in every real session, the python never
+# launched, and nothing logged — a completely silent failure. Forensics on
+# `~/.local/state/build-loop/scan.log` (2026-05-05 .. 2026-08-11) found 0
+# references to a real `~/.claude/projects/` transcript. See
+# `scripts/hooks/session_end_retro_sweep.py::resolve_transcript` for the same
+# note, and hooks/hooks.json SessionEnd for the pattern this mirrors.
+#
+# STDIN CONTRACT (verified live, 2026-08-14, Claude Code 2.1.232)
+# ---------------------------------------------------------------
+# Sibling hooks inside ONE matcher group run in PARALLEL and EACH command
+# process is spawned with its OWN stdin pipe carrying a full copy of the
+# payload. A three-sibling `cat > file` probe produced three byte-identical
+# 562-byte payloads (same md5), so draining stdin here cannot starve a later
+# hook. Reading stdin independently per entry is correct; no read-once-and-share
+# coordination is needed. (`scripts/hooks/stop_finalize.sh` already does
+# `INPUT=$(cat)` in this same group and has always worked, consistent with
+# this.)
+#
+# Contract:
+#   - Advisory + fail-open: ALWAYS exit 0; never emits `decision: block`.
+#   - Emits `{}` on stdout (valid Stop-hook JSON) and nothing on stderr.
+#   - Backgrounds the sweep (`nohup ... &`) so the hook returns in <500ms.
+#   - Minimal-PATH safe: hooks run under /usr/bin:/bin. python3 is resolved via
+#     `command -v` + absolute fallbacks (hooks/_resolve_python.sh); missing
+#     python → silent no-op exit 0.
+#   - Payload values reach python via ARGV / env, never by shell-string
+#     interpolation into python source (closes docs/SECURITY_FOLLOWUP_2026-05-05.md).
+#
+# See memory `reference_hooks_minimal_path_failopen`.
+
+set -u
+
+SWEEP="${1:-}"
+
+# Always emit valid no-op hook JSON and exit 0, whatever happened.
+_noop() {
+    printf '{}'
+    exit 0
+}
+
+[ -n "$SWEEP" ] || _noop
+
+# Read the Stop payload once. Empty/absent stdin is a normal no-op.
+# Empty stdin is NORMAL on a host that supplies no Stop payload (Codex). The
+# old `[ -n "$PAYLOAD" ] || _noop` here made every non-Claude host a silent
+# no-op before the transcript was ever looked for.
+PAYLOAD="$(cat 2>/dev/null || true)"
+
+# Resolve python3 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" ] || _noop
+
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PROJECT_DIR:-$PWD}}"
+
+# Extract transcript_path + cwd from the payload. The payload is passed through
+# the environment (never interpolated into the python source) so a value
+# containing quotes or shell metacharacters cannot inject.
+_BL_STOP_PAYLOAD="$PAYLOAD"
+export _BL_STOP_PAYLOAD
+# Two newline-separated lines: transcript_path, then cwd. Newlines are stripped
+# from the values so the line framing can't be spoofed by a crafted payload.
+_parsed="$(
+    "$_py" - <<'PY' 2>/dev/null
+import json, os
+try:
+    d = json.loads(os.environ.get("_BL_STOP_PAYLOAD", "") or "{}")
+    if not isinstance(d, dict):
+        d = {}
+except Exception:
+    d = {}
+
+
+def safe(v):
+    return " ".join(str(v or "").split("\n"))
+
+
+print(safe(d.get("transcript_path")))
+print(safe(d.get("cwd")))
+PY
+)" || _parsed=""
+
+TRANSCRIPT="$(printf '%s\n' "$_parsed" | sed -n '1p')"
+CWD="$(printf '%s\n' "$_parsed" | sed -n '2p')"
+[ -n "$CWD" ] || CWD="${CLAUDE_PROJECT_DIR:-$PWD}"
+
+STATE_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/build-loop"
+
+# No transcript in the payload: resolve the host's own session from CWD and
+# normalize it to the Claude shape every sweep below parses. One call does both
+# -- handing back a raw Codex path would move the no-op one step downstream.
+# Claude always supplies transcript_path, so this is for hosts that do not.
+if [ -z "$TRANSCRIPT" ]; then
+    _adapter="${PLUGIN_ROOT}/scripts/transcript_adapter.py"
+    if [ -f "$_adapter" ]; then
+        TRANSCRIPT="$("$_py" "$_adapter" --find-codex-session "$CWD" \
+            --cache-dir "$STATE_DIR/transcript-cache" 2>/dev/null)" || TRANSCRIPT=""
+    fi
+fi
+
+# Every sweep needs a transcript; check once rather than in each arm.
+[ -n "$TRANSCRIPT" ] || _noop
+
+_run_one() {
+    case "$1" in
+    decisions)
+        nohup "$_py" "${PLUGIN_ROOT}/scripts/scan_transcript_for_decisions.py" \
+            --workdir "$CWD" \
+            --transcript "$TRANSCRIPT" \
+            --log-file "${STATE_DIR}/scan.log" \
+            </dev/null >/dev/null 2>&1 &
+        ;;
+    corrections)
+        nohup env PYTHONPATH="${PLUGIN_ROOT}/scripts" "$_py" -m scan_corrections \
+            --workdir "$CWD" \
+            --transcript "$TRANSCRIPT" \
+            --source stop-hook \
+            </dev/null >/dev/null 2>&1 &
+        ;;
+    findings)
+        nohup env PYTHONPATH="${PLUGIN_ROOT}/scripts" "$_py" -m scan_findings \
+            --workdir "$CWD" \
+            --transcript "$TRANSCRIPT" \
+            --log-file "${STATE_DIR}/findings-scan.log" \
+            </dev/null >/dev/null 2>&1 &
+        ;;
+    cost-ledger)
+        # cost_ledger_hook.py parses the Stop payload itself (it needs
+        # session_id + cwd + transcript_path), so hand it the RAW payload on
+        # stdin rather than argv. printf writes and exits; the sweep stays
+        # detached.
+        printf '%s' "$PAYLOAD" \
+            | nohup "$_py" "${PLUGIN_ROOT}/scripts/cost_ledger_hook.py" \
+                >/dev/null 2>&1 &
+        ;;
+    esac
+}
+
+if [ "$SWEEP" = "all" ]; then
+    for one in decisions corrections findings cost-ledger; do
+        _run_one "$one"
+    done
+else
+    _run_one "$SWEEP"
+fi
+
+_noop

package/hooks/test_closeout.sh

@@ -32,7 +32,9 @@ make_project() {
     "current_session_id": "sess-itest",
     "started_by_session_id": "sess-itest",
     "last_heartbeat_at": "2999-01-01T00:00:00Z",
-    "run_label": "itest#001"
+    "run_label": "itest#001",
+    "run_worktree_branch": "bl/run-itest-001",
+    "run_worktree_path": ".build-loop/worktrees/run-itest-001"
   },
   "runs": []
 }
@@ -41,6 +43,7 @@ JSON
 }
 
 runs_count() { python3 -c "import json,sys;print(len(json.load(open(sys.argv[1])).get('runs',[])))" "$1/.build-loop/state.json"; }
+branch_ledger_ok() { python3 -c 'import json,sys;s=json.load(open(sys.argv[1]));r=s["runs"][0];x=r["createdRefs"][0];raise SystemExit(0 if s["execution"]=={} and x["branch"]=="bl/run-itest-001" and x["status"]=="open" and r["branch_closeout"]["status"]=="pending_external_merge" and "owner_release" not in r["branch_closeout"] else 1)' "$1/.build-loop/state.json"; }
 
 # --- 1. present + matching session → records + surfaces WARN + exit 0 -------
 P="$(make_project)"
@@ -51,7 +54,16 @@ if [ "$RC" -eq 0 ] && [ "$(runs_count "$P")" = "1" ] && printf '%s' "$OUT" | gre
 else
     bad "present+stakes (rc=$RC runs=$(runs_count "$P") out=$OUT)"
 fi
-[ -f "$P/.build-loop/closeout-pending/bl-itest-001.md" ] && ok "closeout-pending marker written" || bad "marker not written"
+if [ -f "$P/.build-loop/closeout-pending/bl-itest-001.md" ]; then
+    ok "closeout-pending marker written"
+else
+    bad "marker not written"
+fi
+if branch_ledger_ok "$P"; then
+    ok "Stop archived identity after persisting open branch ownership"
+else
+    bad "branch ownership missing or over-authorized"
+fi
 
 # --- 1b. second Stop in the same run → no-op (no double-record, no advisory) -
 OUT2="$(printf '{"session_id":"sess-itest"}' | CLAUDE_PROJECT_DIR="$P" CLAUDE_PLUGIN_ROOT="$REPO" bash "$HOOK" stop)"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tyroneross/build-loop",
-  "version": "0.36.0",
+  "version": "0.43.0",
   "publishConfig": {
     "registry": "https://npm.pkg.github.com",
     "access": "public"
@@ -9,7 +9,9 @@
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
   "bin": {
-    "build-loop-install": "bin/build-loop-install.js"
+    "build-loop-install": "bin/build-loop-install.js",
+    "build-loop-debugger": "bin/build-loop-debugger.js",
+    "build-loop-load-probe": "bin/build-loop-load-probe.js"
   },
   "exports": {
     ".": {
@@ -22,7 +24,6 @@
     "dist",
     "bin",
     "codex-skills",
-    "plugin-artifacts/codex",
     "assets",
     "commands",
     "skills",
@@ -30,9 +31,9 @@
     "scripts/_db_url.py",
     "scripts/blm.py",
     "scripts/blm_api.py",
-    "scripts/build_codex_plugin_artifact.py",
     "scripts/check_cache_sync.py",
     "scripts/embed_backend.py",
+    "scripts/groundwork_exchange.py",
     "scripts/install_memory.py",
     "scripts/lessons_index",
     "scripts/memory_context",
@@ -63,7 +64,8 @@
     "build": "tsc",
     "watch": "tsc --watch",
     "prepublishOnly": "npm run build",
-    "test": "python3 -m unittest scripts/test_commit_state_check.py scripts/test_bridge_preflight.py scripts/test_mcp_registration.py scripts/test_build_loop_install_cli.py && bash scripts/hooks/test_hooks.sh",
+    "test": "python3 -m unittest scripts/test_commit_state_check.py scripts/test_bridge_preflight.py scripts/test_mcp_registration.py scripts/test_build_loop_install_cli.py scripts/test_native_debugger.py scripts/test_reference_pointer_lint.py scripts/test_groundwork_exchange.py scripts/test_groundwork_exchange_distribution.py scripts/test_load_probe.py scripts/hooks/test_unbounded_load_gate.py && bash scripts/hooks/test_hooks.sh",
+    "test:groundwork-exchange": "python3 -m unittest scripts/test_groundwork_exchange.py scripts/test_groundwork_exchange_distribution.py",
     "benchmark": "node benchmark-scoring.js",
     "clean": "rm -rf dist",
     "plugin:prune-cache": "python3 scripts/prune_plugin_cache.py --source .",
@@ -71,8 +73,7 @@
     "plugin:sync-cache": "python3 scripts/sync_plugin_cache.py --source . --host claude && npm run codex:sync-cache",
     "plugin:sync-cache:hooks": "python3 scripts/sync_plugin_cache.py --source . --host all --install-git-hooks",
     "codex:prune-cache": "python3 scripts/prune_codex_plugin_cache.py --source .",
-    "codex:build-artifact": "python3 scripts/build_codex_plugin_artifact.py --source . --target plugin-artifacts/codex",
-    "codex:sync-cache": "npm run codex:build-artifact && python3 scripts/sync_plugin_cache.py --source plugin-artifacts/codex --host codex",
+    "codex:sync-cache": "python3 scripts/sync_plugin_cache.py --source . --host codex",
     "codex:prune-cache:apply": "python3 scripts/prune_codex_plugin_cache.py --source . --apply",
     "claude:prune-cache": "python3 scripts/prune_plugin_cache.py --source . --host claude",
     "claude:sync-cache": "python3 scripts/sync_plugin_cache.py --source . --host claude",

package/scripts/README.md

@@ -101,7 +101,7 @@ hygiene check as `scripts/` scales.
 | `plan_verify.py` | Deterministic plan grep-rules verifier |
 | `version_advisor.py` | Suggest semver bumps based on `release-pending.md` |
 | `ux_triage.py` | Sub-step D Gates 7/8 UX triage and UI coverage-gap queueing |
-| `ibr_quickpass.py` | Legacy explicit-only helper for user-requested IBR suite runs |
+| `ibr_quickpass.py` | Legacy helper for headless IBR suite runs; current UI verification policy lives in `references/ibr-ui-verification-policy.md` |
 | `optimize_loop.py`, `optimize_doe.py`, `metric_runner.py` | Optimization runner + DOE |
 | `systemic_rca_eval.py` | Experimental scorer for system-level RCA report shape: plain-language lead, failure-map depth, system-control terminal cause, evidence, tradeoffs/impact, and prevention control |
 | `systemic_rca_doe.py` | Experimental packet builder and results scorer for the systemic RCA DOE matrix |

package/scripts/_paths.py

@@ -36,6 +36,7 @@ inspection. They never mkdir or touch files; callers handle creation.
 """
 from __future__ import annotations
 
+import json
 import os
 import re
 import subprocess
@@ -396,6 +397,53 @@ def _canonical_repo_root(cwd_path: Path) -> Path | None:
         return None
 
 
+MEMORY_SLUG_PIN_KEY = "memoryProjectSlug"
+
+
+def _read_pinned_slug(repo_root: Path) -> str | None:
+    """Read the durable memory-project-slug PIN from a repo's config.
+
+    Field: ``<repo_root>/.build-loop/config.json`` -> top-level
+    ``"memoryProjectSlug"`` (camelCase, matching the existing ``selfReview``
+    / ``deploymentPolicy`` top-level keys in that file).
+
+    This is the anchor that survives a ``basename(repo_root)`` rename: the
+    2026-07-09 control-plane RCA (P0-4) found renaming
+    ``RossLabs-AI-Assistant`` silently orphaned 7 lessons under the old
+    ``ai-assistant`` slug, because the slug was derived purely from the
+    directory name with no durable pin. When this field is set, callers use
+    it verbatim instead of deriving a slug from ``repo_root.name``.
+
+    Returns ``None`` (never raises) when: the config file is absent,
+    unreadable, not valid JSON, not a JSON object, the field is missing or
+    not a non-empty string, or the value fails ``_safe_project_tag``
+    validation — every one of those falls through to the existing
+    dirname-derivation path, so a malformed pin degrades gracefully instead
+    of breaking resolution.
+    """
+    config_path = repo_root / ".build-loop" / "config.json"
+    if not config_path.is_file():
+        return None
+    try:
+        raw = config_path.read_text(encoding="utf-8")
+        data = json.loads(raw)
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    pinned = data.get(MEMORY_SLUG_PIN_KEY)
+    if not isinstance(pinned, str):
+        return None
+    pinned = pinned.strip()
+    if not pinned:
+        return None
+    try:
+        _safe_project_tag(pinned)
+    except ValueError:
+        return None
+    return pinned
+
+
 def derive_slug_from_cwd(cwd: Path | str | None = None) -> str:
     """Derive the project slug from a working directory.
 
@@ -406,6 +454,12 @@ def derive_slug_from_cwd(cwd: Path | str | None = None) -> str:
          ``~/.claude/plugins/build-loop`` resolves to ``~/dev/git-folder/build-loop``.
       2. Walk up looking for a ``.git`` entry (file OR dir — worktrees use
          a file). The deepest enclosing ``.git`` defines the repo root.
+      2.5. **Slug PIN check** (durable-slug-pin, added post P0-4 RCA):
+         if the canonical repo root (or, when that lookup fails, the
+         worktree-local repo root) has a valid ``memoryProjectSlug`` pin in
+         ``.build-loop/config.json`` (see ``_read_pinned_slug``), return it
+         verbatim and skip steps 3-4 entirely. A rename of the repo
+         directory no longer changes the slug once pinned.
       3. Slug base = ``basename(repo_root)`` lowercased; non-safe chars
          collapsed to ``-``; runs of ``-`` collapsed; leading/trailing
          ``-`` stripped; capped at 64 chars.
@@ -460,6 +514,17 @@ def derive_slug_from_cwd(cwd: Path | str | None = None) -> str:
         if canonical is not None:
             base_root = canonical
 
+    # Step 2.5 — durable slug PIN. Check the canonical root first (the
+    # preferred place to set the pin — shared by every worktree), then fall
+    # back to the worktree-local root. A hit here bypasses dirname
+    # derivation entirely, so a `basename(repo_root)` rename cannot change
+    # the resolved slug once pinned.
+    pinned = _read_pinned_slug(base_root)
+    if pinned is None and base_root != repo_root:
+        pinned = _read_pinned_slug(repo_root)
+    if pinned is not None:
+        return pinned
+
     base = base_root.name.lower()
     base = re.sub(r"[^a-z0-9._-]", "-", base)
     base = re.sub(r"-{2,}", "-", base).strip("-")