@tyroneross/build-loop 0.30.3 → 0.34.0

package/hooks/post-push-closeout.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com>
+# SPDX-License-Identifier: Apache-2.0
+#
+# post-push-closeout.sh — warm-context soft closeout after a `git push`.
+#
+# Triggered by Claude Code PostToolUse:Bash (see hooks/hooks.json). When the
+# command that just ran was a `git push`, fire the EXISTING closeout in the
+# BACKGROUND (nohup) while context is still warm. This complements — does NOT
+# replace — the crash-fallback path:
+#
+#   - pre-push (hooks/git/pre-push) arms .build-loop/closeout/armed.json.
+#   - next SessionStart (hooks/session-start-closeout.sh) drains the baton.
+#
+# This hook short-circuits that fallback in the common case by draining
+# immediately in the background. It reuses `python3 -m closeout` verbatim — NO
+# duplicated closeout logic. Because closeout writes durable memory + clears the
+# baton on success, the next SessionStart simply finds nothing to drain.
+#
+# Discipline: PostToolUse hooks observe; this one never blocks the tool result.
+# Fail-open (always exit 0). The actual closeout runs detached so a slow memory
+# write never stalls the agent's turn. Minimal-PATH safe (resolves python3 via
+# command -v); no bare `set -e`.
+
+set -u
+
+# PostToolUse passes the tool command; Claude Code exposes it as $TOOL_INPUT
+# (matching the sibling Bash matcher in hooks.json). Fall back to reading stdin
+# JSON if the env var is absent (host portability).
+CMD="${TOOL_INPUT:-}"
+if [ -z "$CMD" ]; then
+    # Best-effort: some hosts deliver the payload on stdin as JSON.
+    STDIN_JSON="$(cat 2>/dev/null || true)"
+    CMD="$STDIN_JSON"
+fi
+
+# Only act on a real `git push`. Anchor on the verb pair to avoid matching
+# `git push --help`-style noise loosely; a trailing `--dry-run` push still
+# closes out harmlessly (closeout is idempotent + fail-open).
+printf '%s' "$CMD" | grep -qE '\bgit[[:space:]]+push\b' || exit 0
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-${PWD}}"
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${PROJECT_DIR}}"
+
+# A closeout only makes sense inside a build-loop project.
+[ -d "${PROJECT_DIR}/.build-loop" ] || exit 0
+
+# 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" ] || exit 0
+
+CLOSEOUT_LOG_DIR="${PROJECT_DIR}/.build-loop/closeout"
+mkdir -p "$CLOSEOUT_LOG_DIR" 2>/dev/null || true
+RID="postpush-$(date -u +%Y%m%dT%H%M%SZ)"
+
+# Ensure the closeout package (scripts/closeout/) is importable regardless of
+# the invoking environment's PYTHONPATH (hooks run under minimal PATH; the package
+# is not installed globally — it lives under PLUGIN_ROOT/scripts/).
+export PYTHONPATH="${PLUGIN_ROOT}/scripts${PYTHONPATH:+:$PYTHONPATH}"
+
+# Fire the existing closeout in the background; never block the turn. On success
+# the closeout module clears the armed baton, so the SessionStart fallback finds
+# nothing to do. Detached + redirected so the agent's turn returns immediately.
+nohup "$_py" -m closeout \
+    --workdir "$PROJECT_DIR" \
+    --run-id "$RID" \
+    --source post-push \
+    --json \
+    >"${CLOSEOUT_LOG_DIR}/${RID}.stdout.json" 2>/dev/null &
+
+exit 0

package/hooks/session-start-closeout.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com>
+# SPDX-License-Identifier: Apache-2.0
+#
+# session-start-closeout.sh — drain a post-push armed baton and surface
+# pending-lesson candidates to the host coding agent.
+#
+# Triggered by Claude Code SessionStart (see hooks/hooks.json). Fail-open
+# (always ``exit 0``) so a broken hook can never wedge a session start.
+#
+# Two responsibilities:
+#   1. If ``.build-loop/closeout/armed.json`` exists, the previous session
+#      ran ``git push``. Drain the baton by invoking ``python3 -m closeout``
+#      with ``--source post-push-armed`` and delete the baton on success.
+#   2. Surface pending-lesson candidates (one-shot) so the host agent sees
+#      them in the next turn without having to re-discover them.
+#
+# Minimal PATH safe: resolves ``python3`` via ``command -v``; bare ``set -e``
+# is intentionally avoided.
+
+set -u
+
+# Resolve the project / plugin root.
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-${PWD}}"
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${PROJECT_DIR}}"
+
+# Resolve a python3 binary without depending on PATH being populated (shared helper).
+_HOOK_DIR="$(dirname "$0")"
+_py=""
+[ -f "${_HOOK_DIR}/_resolve_python.sh" ] && . "${_HOOK_DIR}/_resolve_python.sh"
+[ -n "$_py" ] || exit 0
+
+ARMED="${PROJECT_DIR}/.build-loop/closeout/armed.json"
+CLOSEOUT_LOG_DIR="${PROJECT_DIR}/.build-loop/closeout"
+mkdir -p "$CLOSEOUT_LOG_DIR" 2>/dev/null || true
+
+# Ensure the closeout package (scripts/closeout/) is importable in hook env.
+# PLUGIN_ROOT already resolves to the repo root (see above); scripts/ is the
+# package parent. Set once here so both the closeout call and surface_pending use it.
+export PYTHONPATH="${PLUGIN_ROOT}/scripts${PYTHONPATH:+:$PYTHONPATH}"
+
+# 1. Drain the armed baton if present.
+if [ -f "$ARMED" ]; then
+    RID="armed-$(date -u +%Y%m%dT%H%M%SZ)"
+    "$_py" -m closeout \
+        --workdir "$PROJECT_DIR" \
+        --run-id "$RID" \
+        --source post-push-armed \
+        --json \
+        2>/dev/null \
+        >"${CLOSEOUT_LOG_DIR}/${RID}.stdout.json" \
+        && rm -f "$ARMED" 2>/dev/null \
+        || true
+fi
+
+# 2. Surface pending-lesson candidates (quiet — nothing prints when empty).
+SURFACED="${CLOSEOUT_LOG_DIR}/surfaced-$(date -u +%Y%m%dT%H%M%SZ).md"
+"$_py" "${PLUGIN_ROOT}/scripts/surface_pending_lessons.py" \
+    --workdir "$PROJECT_DIR" \
+    --quiet \
+    2>/dev/null \
+    >"$SURFACED" \
+    || true
+# Drop the surfaced file when empty so the directory stays clean.
+if [ ! -s "$SURFACED" ]; then
+    rm -f "$SURFACED" 2>/dev/null || true
+fi
+
+exit 0

package/hooks/session-start-memory.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+# Bootstrap build-loop-memory on session start (idempotent, fail-open).
+# Seeds the central memory store (constitution.md, MEMORY.md, indexes/,
+# projects/) from the packaged PUBLIC seed only when the store is entirely
+# absent. install_memory.py is idempotent (skip-if-exists) and copies no
+# personal content. Never blocks, never overwrites, never errors the session.
+# Repair of a partial store is the user-facing `/build-loop:setup-memory` job.
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${CLAUDE_PROJECT_DIR:-$PWD}}"
+installer="${PLUGIN_ROOT}/scripts/install_memory.py"
+[ -f "$installer" ] || exit 0
+command -v python3 >/dev/null 2>&1 || exit 0
+
+# Seed only when the store ROOT dir is missing. Parse --check JSON properly so a
+# nested per-file "exists" cannot be mistaken for the top-level store flag.
+# (python3 -c, not a heredoc: a heredoc inside $() with an apostrophe trips
+# macOS bash 3.2 tokenization.)
+need="$(python3 -c '
+import json, subprocess, sys
+try:
+    out = subprocess.run([sys.executable, sys.argv[1], "--check", "--json"], capture_output=True, text=True, timeout=5).stdout
+    print("1" if not json.loads(out).get("exists") else "0")
+except Exception:
+    print("0")
+' "$installer")"
+[ "$need" = "1" ] && python3 "$installer" >/dev/null 2>&1
+exit 0

package/hooks/session-start-plugin-heal.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: Apache-2.0
+# Plugin-cache self-heal, fire-and-forget, plugin-relative.
+#
+# Heals a Claude Code plugin install whose versioned cache dir vanished while
+# another session was bound to it. Two cases:
+#   A) /plugin install archived the prior dir to ~/.claude/plugins/removed/
+#      → move it back to its registered installPath.
+#   B) /plugin update hard-deleted the prior dir after installing a newer one
+#      → create a symlink old→new so the frozen ${CLAUDE_PLUGIN_ROOT} path
+#        resolves to live scripts.
+#
+# Heals the NEXT session (CC re-resolves ${CLAUDE_PLUGIN_ROOT} only at session
+# start). Cannot save a currently-bound dead-path session — restart-or-symlink
+# remains the only in-session remedy.
+#
+# Opt out: BUILDLOOP_NO_PLUGIN_HEAL=1.
+D="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+. "$D/_session_start_lib.sh"
+ROOT="${CLAUDE_PLUGIN_ROOT:-$D/..}"
+# Heal only runs against ~/.claude (Claude Code's pre-validate-dir-exists is
+# the hazard; Codex doesn't have the same harness behaviour). Cheap-skip on
+# Codex hosts by path heuristic.
+case "$ROOT" in
+  */.codex/*) exit 0 ;;
+esac
+if [ "${BUILDLOOP_NO_PLUGIN_HEAL:-}" = "1" ]; then
+  exit 0
+fi
+if [ -f "$ROOT/scripts/hooks/plugin_dir_heal.py" ]; then
+  bl_fire_bg "$ROOT/scripts/hooks/plugin_dir_heal.py"
+fi
+exit 0

package/hooks/test_closeout.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com>
+# SPDX-License-Identifier: Apache-2.0
+#
+# test_closeout.sh — integration tests for hooks/closeout.sh + scripts/stop_closeout.py (f6).
+#
+# Exercises the bash shim end-to-end (the part the python unit tests can't cover):
+# self-gating, minimal-PATH safety, interpreter fail-open, and the session-id
+# stdin path. Run directly: bash hooks/test_closeout.sh
+
+set -u
+
+REPO="$(cd "$(dirname "$0")/.." && pwd)"
+HOOK="$REPO/hooks/closeout.sh"
+PASS=0
+FAIL=0
+
+ok()   { PASS=$((PASS+1)); printf '  ok   %s\n' "$1"; }
+bad()  { FAIL=$((FAIL+1)); printf '  FAIL %s\n' "$1"; }
+
+# Build a throwaway project with a recordable inline run (matching session,
+# stakes-gated, not yet in runs[]).
+make_project() {
+    local dir; dir="$(mktemp -d)"
+    mkdir -p "$dir/.build-loop"
+    cat >"$dir/.build-loop/state.json" <<'JSON'
+{
+  "phase": "done",
+  "triggers": {"riskSurfaceChange": true},
+  "execution": {
+    "build_loop_id": "bl-itest-001",
+    "current_session_id": "sess-itest",
+    "started_by_session_id": "sess-itest",
+    "last_heartbeat_at": "2999-01-01T00:00:00Z",
+    "run_label": "itest#001"
+  },
+  "runs": []
+}
+JSON
+    printf '%s' "$dir"
+}
+
+runs_count() { python3 -c "import json,sys;print(len(json.load(open(sys.argv[1])).get('runs',[])))" "$1/.build-loop/state.json"; }
+
+# --- 1. present + matching session → records + surfaces WARN + exit 0 -------
+P="$(make_project)"
+OUT="$(printf '{"session_id":"sess-itest"}' | CLAUDE_PROJECT_DIR="$P" CLAUDE_PLUGIN_ROOT="$REPO" bash "$HOOK" stop)"
+RC=$?
+if [ "$RC" -eq 0 ] && [ "$(runs_count "$P")" = "1" ] && printf '%s' "$OUT" | grep -q '"systemMessage"' && printf '%s' "$OUT" | grep -q 'WARN'; then
+    ok "present+stakes → append_run ran + WARN surfaced + exit 0"
+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"
+
+# --- 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)"
+if [ "$(runs_count "$P")" = "1" ] && ! printf '%s' "$OUT2" | grep -q 'systemMessage'; then
+    ok "second Stop same run → no-op"
+else
+    bad "second Stop not idempotent (runs=$(runs_count "$P") out=$OUT2)"
+fi
+
+# --- 1c. session-start surfaces the marker once, then archives it -----------
+OUT3="$(CLAUDE_PROJECT_DIR="$P" CLAUDE_PLUGIN_ROOT="$REPO" bash "$HOOK" session-start </dev/null)"
+if printf '%s' "$OUT3" | grep -q 'additionalContext' && printf '%s' "$OUT3" | grep -q 'bl-itest-001' \
+   && [ ! -f "$P/.build-loop/closeout-pending/bl-itest-001.md" ] \
+   && [ -f "$P/.build-loop/closeout-pending/surfaced/bl-itest-001.md" ]; then
+    ok "session-start surfaced marker once + archived"
+else
+    bad "session-start surfacing (out=$OUT3)"
+fi
+rm -rf "$P"
+
+# --- 2. no .build-loop/ → silent exit 0 ------------------------------------
+P2="$(mktemp -d)"
+OUT="$(printf '{"session_id":"x"}' | CLAUDE_PROJECT_DIR="$P2" CLAUDE_PLUGIN_ROOT="$REPO" bash "$HOOK" stop)"
+RC=$?
+if [ "$RC" -eq 0 ] && [ -z "$OUT" ]; then
+    ok "no .build-loop/ → silent exit 0"
+else
+    bad "no .build-loop (rc=$RC out=$OUT)"
+fi
+rm -rf "$P2"
+
+# --- 3. minimal PATH (/usr/bin:/bin — the real hook env) → still works ------
+P3="$(make_project)"
+OUT="$(printf '{"session_id":"sess-itest"}' | env -i PATH="/usr/bin:/bin" CLAUDE_PROJECT_DIR="$P3" CLAUDE_PLUGIN_ROOT="$REPO" bash "$HOOK" stop)"
+RC=$?
+if [ "$RC" -eq 0 ] && [ "$(runs_count "$P3")" = "1" ]; then
+    ok "minimal PATH=/usr/bin:/bin → records + exit 0"
+else
+    bad "minimal PATH (rc=$RC runs=$(runs_count "$P3") out=$OUT)"
+fi
+rm -rf "$P3"
+
+# --- 4. broken PATH (python not on PATH) → resolves via absolute fallback ---
+# Invoke bash by absolute path (so the harness itself survives the broken PATH);
+# inside, command -v python3 fails and the script must fall back to an absolute
+# python (/usr/bin/python3 …). Contract: exit 0, never crash, valid/empty JSON.
+P4="$(make_project)"
+OUT="$(printf '{"session_id":"sess-itest"}' | env -i PATH="/nonexistent" CLAUDE_PROJECT_DIR="$P4" CLAUDE_PLUGIN_ROOT="$REPO" /bin/bash "$HOOK" stop 2>/dev/null)"
+RC=$?
+if [ "$RC" -eq 0 ] && { [ -z "$OUT" ] || printf '%s' "$OUT" | python3 -c 'import json,sys;json.load(sys.stdin)' 2>/dev/null; }; then
+    ok "broken PATH → fail-open exit 0 (absolute-fallback python or silent skip)"
+else
+    bad "broken PATH not fail-open (rc=$RC out=$OUT)"
+fi
+rm -rf "$P4"
+
+# --- 5. helper script missing (fake plugin root) → silent exit 0 -----------
+P5="$(make_project)"
+FAKE="$(mktemp -d)"  # no scripts/stop_closeout.py here
+OUT="$(printf '{"session_id":"sess-itest"}' | CLAUDE_PROJECT_DIR="$P5" CLAUDE_PLUGIN_ROOT="$FAKE" bash "$HOOK" stop)"
+RC=$?
+if [ "$RC" -eq 0 ] && [ "$(runs_count "$P5")" = "0" ]; then
+    ok "missing helper script → silent exit 0 (no record)"
+else
+    bad "missing helper not fail-open (rc=$RC runs=$(runs_count "$P5") out=$OUT)"
+fi
+rm -rf "$P5" "$FAKE"
+
+printf '\n%d passed, %d failed\n' "$PASS" "$FAIL"
+[ "$FAIL" -eq 0 ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tyroneross/build-loop",
-  "version": "0.30.3",
+  "version": "0.34.0",
   "publishConfig": {
     "registry": "https://npm.pkg.github.com",
     "access": "public"
@@ -18,12 +18,14 @@
   "files": [
     "dist",
     "codex-skills",
+    "plugin-artifacts/codex",
     "commands",
     "skills",
     "scripts/_paths.py",
     "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/install_memory.py",
@@ -44,7 +46,7 @@
     ".cursor",
     ".claude-plugin",
     ".codex-plugin",
-    ".agents",
+    ".agents/plugins",
     "README.md",
     "AGENTS.md",
     "LICENSE",
@@ -61,10 +63,11 @@
     "clean": "rm -rf dist",
     "plugin:prune-cache": "python3 scripts/prune_plugin_cache.py --source .",
     "plugin:prune-cache:apply": "python3 scripts/prune_plugin_cache.py --source . --apply",
-    "plugin:sync-cache": "python3 scripts/sync_plugin_cache.py --source . --host all",
+    "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:sync-cache": "python3 scripts/sync_plugin_cache.py --source . --host codex",
+    "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: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/plugin-artifacts/codex/.codex-plugin/plugin.json

@@ -0,0 +1,41 @@
+{
+  "name": "build-loop",
+  "version": "0.33.0",
+  "description": "Multi-phase build orchestration with native debugging: assess, plan, execute, review, iterate. Plan-verify gate on Phase 2. Optional UI design gates. Native debug-loop, debugging-memory, and logging-tracer skills provide root-cause investigation without a bundled MCP server. Orchestrator owns when-to-fire; bundled skills own procedural detail; bridges are optional escalation hops to supporting plugins for extended capability.",
+  "author": {
+    "name": "Tyrone Ross",
+    "url": "https://github.com/tyroneross"
+  },
+  "homepage": "https://github.com/tyroneross/build-loop#readme",
+  "repository": "https://github.com/tyroneross/build-loop",
+  "license": "Apache-2.0",
+  "keywords": [
+    "development",
+    "orchestration",
+    "evaluation",
+    "iteration",
+    "build",
+    "tdd",
+    "fact-checking",
+    "code-quality",
+    "ui-validation",
+    "accessibility",
+    "design-rules",
+    "debug-loop",
+    "debugging",
+    "causal-tree",
+    "incident-memory"
+  ],
+  "skills": "./skills",
+  "interface": {
+    "displayName": "Build Loop",
+    "shortDescription": "Multi-phase build orchestration with review gates, UI validation, debugging, and a Codex subagent adapter.",
+    "longDescription": "Multi-phase build orchestration with native debugging: assess, plan, execute, review, iterate. Plan-verify gate on Phase 2. Optional UI design gates. Native debug-loop, debugging-memory, and logging-tracer skills provide root-cause investigation without a bundled MCP server. Orchestrator owns when-to-fire; bundled skills own procedural detail; bridges are optional escalation hops to supporting plugins for extended capability.",
+    "developerName": "Ross Labs",
+    "category": "Coding",
+    "capabilities": [
+      "Read",
+      "Write"
+    ]
+  }
+}