spexcode 0.1.5 → 0.2.0

package/spec-cli/templates/spec/project/.config/core/stop-gate/stop-gate.sh

@@ -45,13 +45,23 @@ cont=$(printf '%s' "$input" | sed -n 's/.*"stop_hook_active"[[:space:]]*:[[:spac
 # (NEVER a block decision: a gap is a heads-up, not a wall). FIRES ONCE: the additionalContext itself forces
 # one continuation, so the CALLER guards it on stop_hook_active — re-emitting on the forced re-stop is what
 # looped 31 turns and tripped the Stop-hook block cap. Called only on ALLOW paths, never alongside a block.
+#
+# SURFACE-NEUTRAL: a stale/unmeasured score is refreshed only by PRODUCING the measurement on the scenario's
+# OWN surface — a real run, never a desk check and never deferring to review a recording after the fact. The
+# nudge privileges NO surface: `scan --changed` carries each drift/missing scenario's tag on its finding line
+# ([[yatsu-core]]'s lint.scenarioTags — frontend-e2e / backend-api / cli / desktop / mobile), so the agent
+# reads there WHICH surface to run. One line covers all five surfaces; there is no per-surface branch.
 yatsu_advisory() {
   local out ids n msg esc
+  # Codex Stop hooks reject the Claude-family `hookSpecificOutput.additionalContext` shape on allow paths.
+  # Keep Codex Stop stdout empty unless it is a real block decision; the dispatcher still bridges block
+  # reasons to Codex stderr.
+  [ "${SPEXCODE_HARNESS:-claude}" = codex ] && return 0
   out=$($S yatsu scan --changed 2>&1)
   n=$(printf '%s\n' "$out" | grep -cE 'yatsu-(drift|missing|uncovered):')
   [ "${n:-0}" -gt 0 ] || return 0   # no gap in what you changed (or scan unavailable) -> nothing to nudge
   ids=$(printf '%s\n' "$out" | sed -n "s/.*yatsu-[a-z]*: '\([^']*\)'.*/\1/p" | awk '!seen[$0]++' | head -6 | paste -sd' ' -)
-  msg="yatsu — the loss signal the optimizer reads — flags ${n} gap(s) in nodes you changed: ${ids}. A node whose score went stale/unmeasured: re-measure it (run the scenario, compare to expected, \`spex yatsu eval <node>\`). A FRONTEND node with no yatsu.md: give it one (a scenario — description + expected), since an obvious UI change should carry a loss signal. \`spex yatsu scan --changed\` lists them. (Advisory — fires once, not a gate.)"
+  msg="yatsu — the loss signal the optimizer reads — flags ${n} gap(s) in nodes you changed: ${ids}. A node whose score went stale/unmeasured: re-measure it — PRODUCE the measurement YOURSELF with a real run of the scenario's actual surface (its tag on the \`spex yatsu scan --changed\` line tells you WHICH surface to run), compare to expected, and file it with \`spex yatsu eval <node>\`; don't desk-check it, and don't defer to reviewing a recording after the fact. A FRONTEND node with no yatsu.md: give it one (a scenario — description + expected), since an obvious UI change should carry a loss signal. \`spex yatsu scan --changed\` lists them. (Advisory — fires once, not a gate.)"
   esc=$(printf '%s' "$msg" | sed 's/\\/\\\\/g; s/"/\\"/g')
   printf '{"hookSpecificOutput":{"hookEventName":"Stop","additionalContext":"%s"}}\n' "$esc"
 }
@@ -99,10 +109,12 @@ if [ "$cont" = true ]; then
   exit 0
 fi
 
-# first stop in an undeclared state -> nudge exactly once with PATH-independent commands. The reason
-# EMPHASIZES that each state is a CLAIM others act on (not a box to tick to end the turn) and gives the
+# first stop in an undeclared state -> nudge exactly once. The reason names the PATH-independent CLI ($S)
+# ONCE as a shared `<CLI> session <choice>` prefix, then lists the five choices as a compact newline menu of
+# bare subcommands — so the terminal output stays legible instead of repeating the long abs path per option.
+# It EMPHASIZES that each state is a CLAIM others act on (not a box to tick to end the turn) and gives the
 # precise APPLICATION CONDITION for each — so the agent picks the TRUE one. park is policed hardest because
 # a false park (no real background task) reads on the board as "fine, self-resuming" when the agent actually
 # needs the human, which is the most damaging mislabel.
-printf '{"decision":"block","reason":"Your session state is a CLAIM the board, your supervisor, and other agents act on — not a box to tick to end the turn. Stopping undeclared makes your outcome a guess. Pick the ONE that is TRUE right now, by its condition, then stop. %s session done --propose merge = your spec+code are COMMITTED on the branch and genuinely ready for a human to review/merge (not just probably-done). %s session done --propose nothing = committed, but you are NOT proposing a merge; paused for the human to look. %s session park --note <what-you-await> = use ONLY when a real BACKGROUND TASK will wake you (a spex wait you backgrounded, a running build/job). If nothing is actually running to resume you, you are NOT parked — you are waiting on the human, so use ask. park claims leave-me-alone-I-self-resume; do not use it as a default to clear this gate. %s session done --propose close = you propose discarding this worktree. %s session ask --note <your-question> = you need the human: a real question, OR you are simply stopped awaiting their direction; you resume only when they reply. Choose by what is true."}\n' "$S" "$S" "$S" "$S" "$S"
+printf '{"decision":"block","reason":"Your session state is a CLAIM the board, your supervisor, and other agents act on — not a box to tick to end the turn. Stopping undeclared makes your outcome a guess. Pick the ONE that is TRUE right now and run `%s session <choice>`, choosing the <choice> whose condition holds:\\n  • done --propose merge  — spec+code COMMITTED on the branch and genuinely ready for a human to review/merge (not just probably-done).\\n  • done --propose nothing — committed, but you are NOT proposing a merge; paused for the human to look.\\n  • park --note <what-you-await> — ONLY when a real BACKGROUND TASK will wake you (a spex wait you backgrounded, a running build/job). If nothing is actually running to resume you, you are NOT parked — you are waiting on the human, so use ask; never use park as a default to clear this gate.\\n  • done --propose close — you propose discarding this worktree.\\n  • ask --note <your-question> — you need the human: a real question, or you are simply stopped awaiting direction; you resume only when they reply."}\n' "$S"
 exit 0

package/spec-cli/templates/spec/project/.config/extract/spec.md

@@ -1,6 +1,6 @@
 ---
 title: extract
-surface: slash
+surface: command
 status: active
 hue: 30
 desc: Reverse-engineer a faithful spec tree out of existing code — responsibility nodes at contract altitude, intent never fabricated.

package/spec-cli/templates/spec/project/.config/regroup/spec.md

@@ -1,6 +1,6 @@
 ---
 title: regroup
-surface: slash
+surface: command
 status: active
 hue: 130
 desc: Resolve a node's breadth — a flat fan-out of too many children — by lifting children onto their true owner or a new grouping layer, only along real seams.

package/spec-cli/templates/spec/project/.config/reproduce-before-fix/spec.md

@@ -0,0 +1,18 @@
+---
+title: reproduce-before-fix
+surface: system
+status: active
+hue: 140
+desc: A config plugin — a bug fix must first REPRODUCE the failure as a failing eval, then fix, then file the passing eval. The fail→pass pair on one scenario is the fix's proof (the A/B).
+code:
+---
+## Reproduce before you fix — the fix's proof is a fail→pass pair
+
+If your task is to FIX A BUG, reproduce it *first*, as a measurement — before you touch the fix. A claim that something is broken is worth nothing until the loss signal shows it broken; a claim that you fixed it is worth nothing until the same signal shows it passing. So a bug fix is bracketed by two readings of ONE scenario:
+
+- **A — reproduce (fail).** Find the yatsu scenario whose expected the bug violates (if none fits, ADD one to the node's `yatsu.md` — a description + the expected correct behaviour), run it, and file the failing reading with evidence that SHOWS the bug: `spex yatsu eval <node> --scenario <s> --fail --note "<what's wrong>"` plus an `--image`/`--video` of the actual broken behaviour. This is not ceremony — reproducing is how you learn what actually breaks, and a fix aimed at an unreproduced bug aims at a guess.
+- **B — fix, then re-measure (pass).** Make the code honor the spec, run the SAME scenario again, and file the passing reading with evidence of the corrected behaviour: `spex yatsu eval <node> --scenario <s> --pass`.
+
+The two readings on the same scenario are the **A/B** — the error→correct transition, the fix's proof-of-work. yatsu keeps per-scenario reading history, so the pair is durable and navigable end to end.
+
+Don't skip A because the fix looks obvious — an obvious fix with no reproduced failure leaves the loss signal blind to exactly the regression you just closed. This does not apply to building new intent (there is no prior failure to reproduce) — it is the discipline for **repair**: keep the loss signal honest across a bug's whole lifecycle, not just at the end.

package/spec-cli/templates/spec/project/.config/spec.md

@@ -6,10 +6,10 @@ desc: The instance home — this repo's DIY dev-flow plugins live here as skill-
 ---
 `.config/` is the **instance** of the config system: the concrete dev-flow plugins this repo ships for
 working in it. Each plugin is a skill-shaped node — its folder *is* the unit (a `spec.md` plus any
-co-located scripts) — living as a flat child of `.config/` and carrying a `surface: slash|system` field
+co-located scripts) — living as a flat child of `.config/` and carrying a `surface: command|system` field
 that names where it plugs in.
 
 The launcher's system gather and the new-session dropdown read from here. Only **active** plugins
 gather: a `pending` node is declared intent, not yet an active plugin. The seed ships `core`
-(`surface: system` — the spec-discipline contract folded into every agent) plus `tidy` and `health`
-(`surface: slash` — prompt presets); add your own by creating a sibling node with a `surface` field.
+(`surface: system` — the spec-discipline contract folded into every agent) plus command presets like
+`tidy`; add your own by creating a sibling node with a `surface` field.

package/spec-cli/templates/spec/project/.config/supervisor/spec.md

@@ -1,8 +1,8 @@
 ---
 title: supervisor
-surface: slash
+surface: command
 status: active
 hue: 280
 desc: Launch a supervisor agent that manages other agents from the main checkout to drive a goal to completion.
 ---
-You are a SpexCode supervisor — a **manager**, not a feature worker. Your work base is the main checkout (the repository root), NOT your own worktree: do all git via `git -C <root>`, everything else via the `spex` CLI, and never write feature code. **FIRST, read `<root>/CLAUDE.md` — specifically its "Supervising — the manager loop" section** — that is your complete playbook (dispatch → monitor → review → merge → close, and how to parallelize). Then drive the goal: decompose it into spec-node tasks and dispatch one worker per independent task (`spex new "<task>" --node <id>` — give each ONLY its task), monitor with `spex watch`, review proposals with `spex review <id>`, merge good ones with `git -C <root> merge --no-ff <branch>`, then close. Never let a worker self-merge; keep `spex lint` at 0 errors. To WAIT on a worker, POLL one-shot (`spex review <id>` or `spex ls` — both return immediately); never block on `spex watch`, which STREAMS forever and will freeze your turn. Two footguns that bite a fresh supervisor: (1) `spex session new --help` is NOT help — it CREATES a stray session; always dispatch with `spex new`. (2) Before `spex session close <id>`, confirm the merge landed (`git -C <root> log -1` shows HEAD at the new merge commit) — closing an unmerged branch discards the work. Report progress as you go and when the goal is complete. Your goal follows:
+You are a SpexCode supervisor — a **manager**, not a feature worker. Your work base is the main checkout (the repository root), NOT your own worktree: do all git via `git -C <root>`, everything else via the `spex` CLI, and never write feature code. **FIRST, read `<root>/CLAUDE.md` — specifically its "Supervising — the manager loop" section** — that is your complete playbook (dispatch → monitor → review → merge → close, and how to parallelize). Then drive the goal: decompose it into spec-node tasks and dispatch one worker per independent task (`spex new "<task>" --node <id>` — give each ONLY its task), monitor with `spex watch`, review proposals with `spex review <id>`, merge good ones with `git -C <root> merge --no-ff <branch>`, then close. Never let a worker self-merge; keep `spex lint` at 0 errors. To WAIT on a worker, POLL one-shot (`spex review <id>` or `spex ls` — both return immediately); never block on `spex watch`, which STREAMS forever and will freeze your turn. One footgun that bites a fresh supervisor: before `spex session close <id>`, confirm the merge landed (`git -C <root> log -1` shows HEAD at the new merge commit) — closing an unmerged branch discards the work. Report progress as you go and when the goal is complete. Your goal follows:

package/spec-cli/templates/spec/project/.config/tidy/spec.md

@@ -1,6 +1,6 @@
 ---
 title: tidy
-surface: slash
+surface: command
 status: active
 hue: 140
 desc: Rewrite a node's body to contract altitude — push mechanics into code comments, keep the contract, without going vague.

package/spec-cli/templates/spec/project/spec.md

@@ -14,6 +14,6 @@ your own project**, then grow child package/feature nodes beneath it (each its o
 
 `.config/` holds the dev-flow plugins this instance ships — skill-shaped flat child nodes, each tagged
 with a `surface` field: a `surface: system` node folds into every launched agent's system prompt as
-always-on contract (the seed ships `core`), and a `surface: slash` node is a prompt preset the
-new-session dropdown composes over target nodes (the seed ships `tidy` and `health`). Add, edit, or
+always-on contract (the seed ships `core`), and a `surface: command` node is a prompt preset the
+new-session dropdown composes over target nodes (the seed ships `tidy`). Add, edit, or
 remove plugins by editing those spec nodes.