feat: deterministic quality hooks + prompt-lint (from autonomous research)

Researched Anthropic's orchestrator-worker system, 2026 parallel-agent orchestrators
(Conductor/Claude-Squad/claude-flow), Claude Code hooks, and DSPy/promptfoo. polylane
already covers most patterns (council=orchestrator-worker, corpus/brief=memory
externalization, tmux+worktrees=parallel isolation). Two genuine gaps, built minimally:

1. verify-gate.sh — a Stop HOOK (reuses the existing hook-install pattern) that BLOCKS
   a lane claiming DONE without a non-empty docs/verify-<lane>.md. The research lesson:
   hooks are the deterministic layer under a probabilistic agent — polylane baked
   quality into prompts (hope); this enforces it (no DONE without evidence). Registered
   via the existing settings snippet; installed beside graphify-nudge.
2. polylane-promptlint.sh — deterministic gate on GENERATED lane prompts before launch:
   asserts objective/OWN/FORBIDDEN/nonce-DONE/verify structure. DSPy is over-engineering
   for prompts generated fresh per lane (nothing to compile); this enforces the
   empirically-validated shape offline and catches the orchestrator dropping a block
   (the real marker-drift/missing-boundary bug class) before a pane spawns.

+16 tests (442->458). The marker-contract doc guard caught bare-marker drift in my own
new doc text (fixed). All 21 scripts shellcheck-clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: GHGuide

assets/settings-hook-snippet.json

@@ -1,5 +1,5 @@
 {
-  "_comment": "Merge this into <project>/.claude/settings.json (create the file if absent, or merge the hooks.PreToolUse array into an existing one). Registers a non-blocking nudge that fires on Grep/Glob and steers navigation to graphify-out/q.py. The lanes skill CANNOT write this file for you under auto-mode (self-modification guard) — hand this snippet to the user to paste/approve.",
+  "_comment": "Merge into <project>/.claude/settings.json (create if absent, or merge each array into the existing one). PreToolUse: a non-blocking nudge steering navigation to graphify-out/q.py. Stop: verify-gate BLOCKS a lane that claims DONE without writing its docs/verify-<lane>.md evidence — deterministic verification-before-completion. The lanes skill CANNOT write this file under auto-mode (self-modification guard) — hand this snippet to the user to paste/approve.",
   "hooks": {
     "PreToolUse": [
       {
@@ -8,6 +8,13 @@
           { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/graphify-nudge.sh\"" }
         ]
       }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/verify-gate.sh\"" }
+        ]
+      }
     ]
   }
 }

assets/verify-gate.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Stop hook — a lane may NOT finish having claimed DONE without leaving evidence.
+# If docs/status-<lane>.md says DONE but docs/verify-<lane>.md is missing/empty,
+# BLOCK (exit 2) so the agent must write the proof before stopping. The lane prompt
+# only ASKS for verification; this hook ENFORCES it deterministically (the research
+# lesson: hooks are the deterministic layer under a probabilistic agent).
+# Must exit 0 on every non-block path (missing dir, closed stdout, set -e callers).
+input=$(cat 2>/dev/null || true)
+# already retried once via a stop hook -> don't hard-loop; let the agent stop.
+case "$input" in *'"stop_hook_active":true'*) exit 0 ;; esac
+
+DIR="${CLAUDE_PROJECT_DIR:-.}"
+for s in "$DIR"/docs/status-*.md; do
+  [ -f "$s" ] || continue
+  head -1 "$s" 2>/dev/null | grep -q 'DONE' || continue
+  lane=$(basename "$s" .md); lane=${lane#status-}
+  if [ ! -s "$DIR/docs/verify-$lane.md" ]; then
+    echo "polylane verify-gate: lane '$lane' claims DONE in $s but docs/verify-$lane.md is missing/empty. Write the verification evidence (what you built + proof it works) before finishing." >&2
+    exit 2
+  fi
+done
+exit 0

bin/polylane-promptlint.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# polylane-promptlint.sh — deterministic gate on a GENERATED lane prompt before launch.
+# The orchestrator writes each .polylane/lanes/<lane>.txt with an LLM, so a block can be
+# dropped (the marker-drift + missing-OWN/FORBIDDEN bugs were exactly this). This lints
+# for the empirically-validated structure — objective, tool/file boundaries, the nonce
+# DONE contract, verify evidence — the way DSPy/promptfoo enforce prompt quality, but
+# cheap and offline (the prompts are generated fresh per lane, so there's nothing to
+# compile). Reports PROMPT-LINT: <lane> missing <what>; exit 6 if any lane fails.
+#   lint <lane-prompt-file> [<lane-name>]     one prompt
+#   lint-run <manifest>                        every lane's prompt in a run.json
+# Pure bash-3.2 + jq (jq only for lint-run); main-guarded.
+set -euo pipefail
+
+# required token -> human label. A prompt must contain each (case-insensitive).
+lint_one() {
+  local f="$1" lane="${2:-$(basename "$1" .txt)}" miss=""
+  [ -s "$f" ] || { echo "PROMPT-LINT: $lane empty-or-missing $f"; return 6; }
+  grep -qiE 'GOAL|/goal' "$f"        || miss="$miss objective(GOAL)"
+  grep -qi  'OWN'  "$f"              || miss="$miss ownership(OWN)"
+  grep -qi  'FORBIDDEN' "$f"         || miss="$miss boundaries(FORBIDDEN)"
+  grep -qE  'STATUS:.*DONE'  "$f"    || miss="$miss done-marker(STATUS:..DONE)"
+  grep -q   'run='  "$f"             || miss="$miss nonce(run=<RUN_ID>)"
+  grep -qi  'verify' "$f"            || miss="$miss verify-evidence"
+  if [ -n "$miss" ]; then echo "PROMPT-LINT: $lane missing$miss"; return 6; fi
+  return 0
+}
+
+lint_run() {
+  local mf="$1" rc=0 lane pf dir
+  command -v jq >/dev/null 2>&1 || { echo "polylane-promptlint: jq required for lint-run" >&2; return 2; }
+  dir=$(cd "$(dirname "$mf")/.." && pwd)   # .polylane/ -> project root
+  for lane in $(jq -r '.lanes[].name, .integrator.name' "$mf"); do
+    pf=$(jq -r --arg n "$lane" '(.lanes[],.integrator) | select(.name==$n) | .prompt_file' "$mf" | head -1)
+    case "$pf" in /*) : ;; *) pf="$dir/$pf" ;; esac
+    lint_one "$pf" "$lane" || rc=6
+  done
+  return $rc
+}
+
+if [ "${BASH_SOURCE[0]:-}" = "${0}" ]; then
+  case "${1:-}" in
+    lint)     shift; lint_one "$@" ;;
+    lint-run) shift; lint_run "${1:?usage: lint-run <manifest>}" ;;
+    *) echo "usage: polylane-promptlint.sh lint <prompt-file> [lane] | lint-run <manifest>" >&2; exit 2 ;;
+  esac
+fi

references/install-helpers.md

@@ -80,8 +80,13 @@ PROJECT="/absolute/path/to/target/project"  # the repo builders will edit
 
    mkdir -p "$PROJECT/.claude/hooks"
    cp "$SKILL_DIR/assets/graphify-nudge.sh" "$PROJECT/.claude/hooks/graphify-nudge.sh"
-   chmod +x "$PROJECT/.claude/hooks/graphify-nudge.sh"
+   cp "$SKILL_DIR/assets/verify-gate.sh"    "$PROJECT/.claude/hooks/verify-gate.sh"
+   chmod +x "$PROJECT/.claude/hooks/"*.sh
    ```
+   `verify-gate.sh` is a **Stop hook**: it BLOCKS a lane that writes `STATUS: <lane> DONE run=<RUN_ID>`
+   without leaving a non-empty `docs/verify-<lane>.md` — deterministic
+   verification-before-completion (the prompt asks; the hook enforces). Registered by the
+   same settings snippet below.
    Verify:
    ```bash
    python "$PROJECT/graphify-out/q.py" 2>&1 | head -1   # prints usage → q.py runs

references/planning.md

@@ -92,7 +92,8 @@ When the run finishes and the integrator issues GO on a **re-merge of current br
 - Every generated prompt bakes the done-signal: the lane writes `docs/status-<lane>.md` with first line exactly `STATUS: <lane> DONE run=<RUN_ID>` (per-lane, worktree-safe). `docs/parallel-status.md` is for cross-lane requests only — never the done signal.
 - Phase 5 defaults to one git worktree per lane (shared-index race — a shared tree lets one lane's commit bundle another's staged files); shared-tree only on explicit user opt-out.
 - The Phase 5 plan gate always shows the rough per-lane + total cost estimate computed from the `references/model-selection.md` price table (canonical for costs) — never ask for approval without the $ visible.
-- Phase 6 emits `.polylane/run.json` (frozen schema: `base` · `intensity` · `available_models[]` · `integrator{name,model,effort,branch,worktree,prompt_file}` · `lanes[]{name,model,effort,branch,worktree,prompt_file,own_globs}`) plus `.polylane/lanes/<lane>.txt` per lane, alongside the printed paste blocks. New keys (`intensity`, `available_models`, per-object `effort`) match Lc's `.polylane/SCHEMA.md`.
+- Phase 6 emits `.polylane/run.json` (frozen schema: `base` · `run_id` · `intensity` · `available_models[]` · `integrator{name,model,effort,branch,worktree,prompt_file}` · `lanes[]{name,model,effort,branch,worktree,prompt_file,own_globs}`) plus `.polylane/lanes/<lane>.txt` per lane, alongside the printed paste blocks. New keys (`intensity`, `available_models`, per-object `effort`) match Lc's `.polylane/SCHEMA.md`.
+- **Lint the generated prompts before launch (deterministic prompt-quality gate):** `bin/polylane-promptlint.sh lint-run .polylane/run.json` — asserts every lane prompt carries the validated structure (objective/GOAL, OWN + FORBIDDEN boundaries, the `STATUS: … DONE run=<RUN_ID>` marker, verify evidence). A `PROMPT-LINT: <lane> missing …` (rc 6) means the generator dropped a block — REGENERATE that prompt before spawning any pane (a malformed prompt otherwise silent-hangs or breaks isolation). This is the offline equivalent of a DSPy/promptfoo check: the prompts are generated fresh per lane, so there's nothing to compile — the lint enforces the empirically-validated shape instead.
 - Shared file between lanes → one lane owns it; the other requests edits via `docs/parallel-status.md`, never edits directly.
 - Exactly one lane may hold any shared physical resource (device/simulator/deploy target) — mutex via status file.
 - Project-specific facts (build recipes, device UDIDs, quirks) come from the project's CLAUDE.md — keep this skill generic.

tests/test-promptlint.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# polylane-promptlint.sh — a generated lane prompt must carry the validated structure
+# (objective, OWN/FORBIDDEN, nonce DONE marker, verify). Catches the orchestrator
+# dropping a block (the real marker-drift / missing-boundary bugs) before launch.
+. "$(cd "$(dirname "$0")" && pwd)/helpers.sh"
+LINT="$(cd "$(dirname "$RUNNER")" && pwd)/polylane-promptlint.sh"
+. "$LINT"
+
+make_tmpdir
+GOOD="$TEST_TMPDIR/good.txt"
+cat > "$GOOD" <<'P'
+/goal build the thing. OWN: src/x. FORBIDDEN: everything else.
+DONE-SIGNAL: STATUS: x DONE run=<RUN_ID>. Write docs/verify-x.md with proof.
+P
+assert_ok "lint-good" lint_one "$GOOD" x
+
+# each missing element fails with a named gap
+miss_test() {
+  local name="$1" drop="$2"
+  local f="$TEST_TMPDIR/$name.txt"
+  grep -viE "$drop" "$GOOD" > "$f" || true
+  assert_fail "lint-missing-$name" lint_one "$f" "$name"
+}
+miss_test objective  'GOAL|/goal'
+miss_test own        'OWN'
+miss_test forbidden  'FORBIDDEN'
+miss_test nonce      'run='
+miss_test verify     'verify'
+
+# the message names what's missing
+out=$(lint_one "$TEST_TMPDIR/nonce.txt" nonce 2>&1 || true)
+assert_contains "lint-names-gap" "nonce(run=" "$out"
+
+# empty prompt fails
+: > "$TEST_TMPDIR/empty.txt"
+assert_fail "lint-empty" lint_one "$TEST_TMPDIR/empty.txt" e
+
+finish

tests/test-verify-gate.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# assets/verify-gate.sh — Stop hook: block a lane that claims DONE without its
+# verify evidence file. Deterministic verification-before-completion.
+. "$(cd "$(dirname "$0")" && pwd)/helpers.sh"
+GATE="$(cd "$(dirname "$RUNNER")" && pwd)/../assets/verify-gate.sh"
+
+make_tmpdir
+mkdir -p "$TEST_TMPDIR/docs"
+run_gate() { CLAUDE_PROJECT_DIR="$TEST_TMPDIR" bash "$GATE" <<<'{}'; }
+
+# no status file at all -> allow (nothing claimed)
+assert_ok "gate-allows-when-no-status" run_gate
+
+# status DONE but NO verify -> BLOCK (exit 2)
+printf 'STATUS: alpha DONE run=r1\n' > "$TEST_TMPDIR/docs/status-alpha.md"
+assert_rc "gate-blocks-done-without-verify" 2 env CLAUDE_PROJECT_DIR="$TEST_TMPDIR" bash "$GATE" </dev/null
+
+# add the verify evidence -> allow
+printf 'built alpha; tests green\n' > "$TEST_TMPDIR/docs/verify-alpha.md"
+assert_ok "gate-allows-with-verify" run_gate
+
+# stop_hook_active -> never hard-loop, allow even if verify missing
+rm -f "$TEST_TMPDIR/docs/verify-alpha.md"
+assert_ok "gate-no-loop-when-active" sh -c "CLAUDE_PROJECT_DIR='$TEST_TMPDIR' bash '$GATE' <<<'{\"stop_hook_active\":true}'"
+
+finish