spexcode 0.6.1 → 0.6.5

package/{spec-cli → node_modules/@spexcode/spec-cli}/templates/spec/project/.plugins/core/stop-gate/stop-gate.sh

@@ -1,14 +1,14 @@
 #!/usr/bin/env bash
 # @@@ stop-gate - a blocking Stop hook with TWO jobs, each with a HARD loop-break (never blocks more than
 # once on the same cause, never leaks a dishonest stop):
-#   (A) COMMIT GATE — a done/merge proposal (awaiting + merge|nothing) is rejected while the node branch has
+#   (A) COMMIT GATE — a done/merge proposal (awaiting + merge; legacy nothing remains readable) is rejected while the node branch has
 #       uncommitted work or 0 commits ahead of main; the dogfood ritual commits BEFORE proposing. Clean ->
 #       allow; dirty -> block once with the reason, escape on the continuation to `asking` (needs the human).
 #   (B) DECLARE GATE — a session may not stop in an undeclared (`active`) state:
 #         declared (awaiting/parked/error/asking) . allow (the agent reported; nothing to do)
 #         active, first stop  (stop_hook_active false) .. block ONCE — instruct the agent to declare
-#         active, the continuation (stop_hook_active true) auto-declare a safe default (awaiting/nothing if
-#                                          committed, else `asking` — needs the human) and allow. Guaranteed to end.
+#         active, the continuation (stop_hook_active true) auto-declare `asking` and allow. Guaranteed to end
+#                                          without inventing a completion state.
 # $SPEX is the PATH-independent CLI invocation (abs tsx + cli) injected by settingsArg, so the gate's own
 # auto-default AND the command it shows the agent both work even when `spex` is absent from PATH.
 # @@@ global store + governed gate - state lives in the per-session GLOBAL record session.json (keyed by the
@@ -65,12 +65,13 @@ eval_advisory() {
   n=$(printf '%s\n' "$out" | grep -cE 'eval-(drift|missing|coverage):')
   [ "${n:-0}" -gt 0 ] || return 0   # no gap in what you changed (or eval lint unavailable) -> nothing to nudge
   ids=$(printf '%s\n' "$out" | sed -n "s/.*eval-[a-z]*: '\([^']*\)'.*/\1/p" | awk '!seen[$0]++' | head -6 | paste -sd' ' -)
-  msg="eval — 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 eval lint --changed\` line tells you WHICH surface to run), compare to expected, and file it with \`spex eval add <node>\`; don't desk-check it, and don't defer to reviewing a recording after the fact. A FRONTEND node with no eval.md: give it one (a scenario — description + expected), since an obvious UI change should carry a loss signal. \`spex eval lint --changed\` lists them. (Advisory — fires once, not a gate.)"
+  msg=$($S internal hook-prompt stop-gate --variant eval --count "$n" --ids "$ids") || return 0
   esc=$(printf '%s' "$msg" | sed 's/\\/\\\\/g; s/"/\\"/g')
   printf '{"hookSpecificOutput":{"hookEventName":"Stop","additionalContext":"%s"}}\n' "$esc"
 }
 
-# @@@ commit gate - a declaration of done/merge (awaiting + proposal merge|nothing) is only honest once the
+# @@@ commit gate - a declaration of done/merge (awaiting + proposal merge; legacy nothing is accepted only
+# for backward-readable records) is only honest once the
 # node branch carries the work as COMMITS: the dogfood ritual commits spec+code BEFORE any proposal, yet a
 # dashboard-launched agent kept proposing merge with 0 commits / a dirty tree. So before allowing such a
 # declaration we run the deterministic check (`spex internal commit-gate`, which goes through git.ts's git()
@@ -79,8 +80,8 @@ eval_advisory() {
 # it) escape the loop by downgrading to `asking` (needs the human) with a clear note, so a FALSE "ready to
 # merge" never stands. (A propose-close declaration is exempt — it discards the worktree, so commits are moot.)
 # The PROPOSAL rides into the check: `merge` claims there is committed work to land (so 0-ahead blocks too),
-# `nothing` claims only that the work is committed (so a clean tree is the whole gate — a lane whose work
-# already merged may pause for the human without minting an empty commit to get through).
+# New public `done --propose nothing` calls trap before this hook; keep its legacy branch so historic records
+# stop normally instead of becoming corrupt.
 if [ "${status:-active}" = awaiting ] && { [ "$proposal" = merge ] || [ "$proposal" = nothing ]; }; then
   if gatemsg=$($S internal commit-gate "$proposal" 2>&1); then
     # nudge ONCE: emit on the natural stop, but STAY SILENT on the forced re-stop the additionalContext
@@ -93,28 +94,19 @@ if [ "${status:-active}" = awaiting ] && { [ "$proposal" = merge ] || [ "$propos
     $S session ask --session "$sid" --note "stopped with uncommitted work — commit your spec+code on the node branch, then re-declare done" >/dev/null 2>&1 || true
     exit 0
   fi
-  esc=$(printf '%s' "$gatemsg" | sed 's/[\\"]/\\&/g')
-  printf '{"decision":"block","reason":"Not ready to declare done: %s. The dogfood ritual lands every change as a git commit on your node branch BEFORE you propose. Commit your spec.md + code on this node branch (spec: <id> — <reason>, with a Session: trailer), then re-run %s session done --propose %s."}\n' "$esc" "$S" "$proposal"
+  reason=$($S internal hook-prompt stop-gate --variant commit --reason "$gatemsg" --cli "$S" --propose "$proposal") || exit 1
+  esc=$(printf '%s' "$reason" | sed 's/[\\"]/\\&/g')
+  printf '{"decision":"block","reason":"%s"}\n' "$esc"
   exit 0
 fi
 
-# any OTHER already-declared state (parked / error / asking / awaiting+close) -> let it stop.
+# Any other declared state (parked / error / asking / awaiting+close, plus legacy awaiting+nothing) stops.
 [ "${status:-active}" != "active" ] && exit 0
 
 if [ "$cont" = true ]; then
-  # the forced continuation also stopped without declaring -> escape the loop, don't block. Keep the commit
-  # gate airtight: default to awaiting/nothing only when the tree is actually clean; otherwise an undeclared
-  # stop with uncommitted work becomes `asking` (needs the human), never a false awaiting/done. The default
-  # IS `nothing`, so it is judged as `nothing` — an already-merged lane defaults honestly instead of being
-  # pushed to `asking` for having nothing left ahead of main.
-  if $S internal commit-gate nothing >/dev/null 2>&1; then
-    $S internal session-state awaiting --session "$sid" --propose nothing --note "auto: stopped without declaring" >/dev/null 2>&1 || true
-    # NOTE: no eval nudge on the auto-declare path. It only runs on the forced continuation (cont=true),
-    # where a guarded advisory could never fire anyway, and an unguarded one was a second loop vector (a
-    # mark-active tool call could re-enter this branch). The clean-done path above is the single nudge site.
-  else
-    $S session ask --session "$sid" --note "auto: stopped without declaring and with uncommitted work — commit your spec+code on the node branch, then declare" >/dev/null 2>&1 || true
-  fi
+  # The forced continuation also stopped without declaring. Escape into asking: no default may invent a
+  # completed lane, and the stopped agent now needs a human prompt to choose merge, close, ask, or park.
+  $S session ask --session "$sid" --note "auto: stopped without declaring — choose merge, close, ask, or park; done --propose nothing records no state" >/dev/null 2>&1 || true
   exit 0
 fi
 
@@ -129,19 +121,29 @@ fi
 # of the full-to-terse information gap is recoverable from the entry, none of it from memory.
 taught="$sdir/stop-gate-taught"
 if [ -f "$taught" ]; then
-  printf '{"decision":"block","reason":"undeclared stop — declare the ONE true state as your LAST call: `%s session <done --propose merge (review; ONLY clickable merge)|nothing (done; no merge)|close (close-pending) / park (parked; managed watch delivery or real background wake-up) / ask (asking; human reply)>`. Conditions: `%s help session`."}\n' "$S" "$S"
+  reason=$($S internal hook-prompt stop-gate --variant terse --cli "$S") || exit 1
+  esc=$(printf '%s' "$reason" | sed 's/[\\"]/\\&/g')
+  printf '{"decision":"block","reason":"%s"}\n' "$esc"
   exit 0
 fi
 touch "$taught" 2>/dev/null || true
 # The full 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
+# lists the four real states plus the `nothing` trap 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.
 # It ends with the ORDERING discipline — declare LAST, then stop — because a declaration followed by more
 # tool calls honestly re-flips the record to active (mark-active, by design) and re-blocks the next stop;
 # this block text is the one place every undeclared stopper is guaranteed to read, so the teaching that
 # kills the park->block->re-park loop at its source lives here.
-printf '{"decision":"block","reason":"Your session state is a CLAIM the graph, 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 human review. It declares REVIEW and is the ONLY proposal that offers a clickable merge.\\n  • done --propose nothing — committed, but you are NOT proposing a merge; paused for the human to look. It declares DONE, never a merge.\\n  • done --propose close — you PROPOSE discarding this worktree; the human performs the close. It declares CLOSE-PENDING, not merge. This is how a session ends ITSELF — never run `session close` on your own id, which would delete your worktree mid-turn.\\n  • ask --note <your-question> — you need the human: a real question, or you are simply stopped awaiting direction. It declares ASKING and resumes only when they reply.\\n  • park --note <what-you-await> — ONLY when a real wake-up will resume you: a managed spex session watch subscription whose send delivery reaches you, or a spex session wait you backgrounded/a running build/job. It declares PARKED and self-resumes. With neither, you are waiting on the human: use ask, never park as a default.\\n\\nDECLARE LAST, THEN STOP: finish everything else in the turn first — speak, send your messages, establish managed watches or arm background waits — and make the declaration your FINAL call. Any tool call AFTER it flips your record back to active (mark-active, by design: activity is activity), so the next stop re-blocks and demands a fresh declaration; declaring last kills that loop at its source.\\n\\n(This full explanation shows once per session; later undeclared stops get a one-line reminder. `%s help session` re-explains the choices any time.)"}\n' "$S" "$S"
+if [ -s "$sdir/files.json" ] && grep -qE '"[^"]+"' "$sdir/files.json"; then
+  reason=$($S internal hook-prompt stop-gate --variant artifact) || exit 1
+  esc=$(printf '%s' "$reason" | sed 's/[\\"]/\\&/g')
+  printf '{"decision":"block","reason":"%s"}\n' "$esc"
+  exit 0
+fi
+reason=$($S internal hook-prompt stop-gate --variant full --cli "$S") || exit 1
+esc=$(printf '%s' "$reason" | sed 's/\\/\\\\/g; s/"/\\"/g' | awk 'BEGIN{ORS=""} NR>1{print "\\n"} {print}')
+printf '{"decision":"block","reason":"%s"}\n' "$esc"
 exit 0

package/node_modules/@spexcode/spec-cli/templates/spec/project/.plugins/prompts/atomic-landing/spec.md

@@ -0,0 +1,15 @@
+---
+title: atomic-landing
+surface: system
+status: active
+hue: 30
+desc: A config plugin — the trunk checkout is the fleet's one landing door, so a merge must be trivial by the time it reaches it: sync and resolve in YOUR OWN worktree, land only when your branch already contains the trunk, and wait rather than race for a busy door.
+code:
+---
+## Landing is atomic
+
+1. In your worktree, merge `<base>` into the branch, resolve conflicts there, and rerun the proof.
+2. Immediately before landing, require `git merge-base --is-ancestor <base> <branch>`; otherwise sync again.
+3. A clean textual merge is not product proof; the synced branch's verification is required.
+
+`spex guide spec` has the shared-checkout mid-merge rule.

package/node_modules/@spexcode/spec-cli/templates/spec/project/.plugins/prompts/forge-link/spec.md

@@ -0,0 +1,10 @@
+---
+title: forge-link
+surface: system
+status: active
+hue: 280
+desc: A config plugin — agents link an issue or change request opened through the resolved forge to the spec node it serves via one `Spec: <id>` body line.
+code:
+---
+Every forge issue or change request body includes `Spec: <node-id>` (comma-separate several). Use each node's
+leaf directory name, not its slash path; `spex graph --json` lists valid ids.

package/node_modules/@spexcode/spec-cli/templates/spec/project/.plugins/prompts/memory-hygiene/spec.md

@@ -0,0 +1,13 @@
+---
+title: memory-hygiene
+surface: system
+status: active
+hue: 200
+desc: A config plugin — keep the project-keyed agent memory free of session- and role-specific facts, so N agents in one folder never inherit a confused identity.
+code:
+---
+## Memory hygiene
+
+Project memory is shared by the main checkout and all worktrees. Store only durable cross-session project/user
+facts. Never store this task, transient worktree state, a one-off decision, role, or identity. On a non-main
+`node/<id>` worktree, record no memory at all; land a durable lesson first, then record it from main.

package/node_modules/@spexcode/spec-cli/templates/spec/project/.plugins/prompts/reproduce-before-fix/spec.md

@@ -0,0 +1,12 @@
+---
+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, verify, commit, and file the passing eval. The fail→pass pair on one scenario is the fix's proof (the A/B).
+code:
+---
+## Reproduce before you fix
+
+For a bug fix, the fail→pass pair on one scenario is the repair proof. New intent has no prior failure to
+reproduce; `spex guide eval` has the A/B filing sequence.

package/node_modules/@spexcode/spec-core/dist/anchors.d.ts

@@ -0,0 +1,94 @@
+import { type DriftIndex, type DriftPathEvent } from './git.js';
+export type Unit = {
+    name: string;
+    kind: string;
+    start: number;
+    end: number;
+    typeOnly?: boolean;
+};
+export type Extractor = {
+    id: string;
+    claims(ext: string): boolean;
+    ready(): true | string;
+    extract(content: string, filename: string): Unit[];
+    memoKey: (filename: string) => string;
+};
+export type CodeEntry = {
+    path: string;
+    anchor: string | null;
+};
+export declare function parseCodeEntry(raw: string): CodeEntry;
+export type RelationEntry = {
+    path: string;
+    selectors: string[];
+};
+export type RelationParse = {
+    entries: RelationEntry[];
+    problems: string[];
+};
+export declare function relationClaimsPath(claim: string, file: string): boolean;
+export declare function parseRelation(raws: string[], relation: 'code' | 'related'): RelationParse;
+export declare function tsAstExtractor(root: string): Extractor;
+export type LangSpec = {
+    id: string;
+    extensions: string[];
+    decls: {
+        re: RegExp;
+        kind: string;
+        typeOnly?: boolean;
+        classOpener?: boolean;
+        declList?: boolean;
+        scopeOpener?: boolean;
+        memberOf?: {
+            parentKind: string;
+            kind: string;
+        };
+    }[];
+    member?: {
+        re: RegExp;
+        blacklist?: RegExp;
+    };
+    indentScopes?: {
+        decorator?: RegExp;
+    };
+    boundary: RegExp;
+};
+export declare function heuristicExtractor(spec: LangSpec): Extractor;
+export declare const JS_LANG_R5B: LangSpec;
+export declare const PYTHON_LANG: LangSpec;
+export declare function extractors(root: string): Extractor[];
+export declare function extractorFor(regs: Extractor[], ext: string): Extractor | null;
+export declare const extOf: (path: string) => string;
+export type AnchorResolution = {
+    ok: Unit;
+} | {
+    dead: true;
+} | {
+    ambiguous: number;
+};
+export type SelectorVerdict = {
+    selector: string;
+} & ({
+    ok: Unit;
+} | {
+    dead: true;
+} | {
+    ambiguous: number;
+});
+export declare function resolveSelectors(units: Unit[], selectors: readonly string[]): SelectorVerdict[];
+export declare function resolveAnchor(units: Unit[], symbol: string): AnchorResolution;
+export declare function selectorsHitRanges(units: readonly Unit[], symbols: readonly string[], ranges: readonly [number, number][]): string[];
+export declare function diffHunkRanges(patch: string, side?: 'old' | 'new'): [number, number][];
+export declare function windowEvents(idx: DriftIndex, sinceHash: string, path: string, nodeId?: string): DriftPathEvent[];
+export type AnchorHit = {
+    commit: string;
+    selectors: string[];
+    unparseable?: string;
+};
+export type AnchorHitQuery = {
+    win: DriftPathEvent[];
+    symbols: string[];
+};
+export declare function anchorHitQueries(root: string, queries: AnchorHitQuery[], regs: Extractor[]): Promise<AnchorHit[][]>;
+export declare function anchorHitExists(root: string, queries: AnchorHitQuery[], regs: Extractor[]): Promise<boolean[]>;
+export declare function anchorHitCommits(root: string, win: DriftPathEvent[], symbols: string[], regs: Extractor[]): Promise<AnchorHit[]>;