spexcode 0.6.2 → 0.6.6

package/node_modules/@spexcode/spec-cli/dist/uploads.d.ts

@@ -0,0 +1,36 @@
+import { type UploadPolicy } from '@spexcode/spec-core';
+type UploadMeta = {
+    version: 1;
+    id: string;
+    name: string;
+    size: number;
+    offset: number;
+    createdAt: number;
+    updatedAt: number;
+};
+export type UploadStatus = Pick<UploadMeta, 'id' | 'name' | 'size' | 'offset'> & Pick<UploadPolicy, 'chunkBytes' | 'concurrency' | 'requestTimeoutMs' | 'retryLimit' | 'retryDelayMs'>;
+export declare class UploadError extends Error {
+    readonly status: number;
+    readonly offset?: number | undefined;
+    constructor(status: number, message: string, offset?: number | undefined);
+}
+export declare const evidenceMaxBytes: () => number;
+export declare function cleanupExpiredUploads(policy?: Required<{
+    maxBytes?: number;
+    chunkBytes?: number;
+    concurrency?: number;
+    requestTimeoutMs?: number;
+    retryLimit?: number;
+    retryDelayMs?: number;
+    incompleteTtlMs?: number;
+    cleanupIntervalMs?: number;
+    minFreeBytes?: number;
+    evidenceMaxBytes?: number;
+}>): void;
+export declare function startUploadReaper(): void;
+export declare function createUpload(name: unknown, size: unknown): UploadStatus;
+export declare function uploadStatus(id: string): UploadStatus;
+export declare function appendUpload(id: string, offset: unknown, body: ReadableStream<Uint8Array> | null, contentLength?: string): Promise<UploadStatus>;
+export declare function completeUpload(id: string): string;
+export declare function cancelUpload(id: string): void;
+export {};

package/node_modules/@spexcode/spec-cli/dist/uploads.js

@@ -0,0 +1,243 @@
+import { randomUUID } from 'node:crypto';
+import { createWriteStream, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, statfsSync, truncateSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { repoRoot } from '@spexcode/spec-core';
+import { readUploadPolicy } from '@spexcode/spec-core';
+// The backend's tmpdir is the worker's filesystem. Completed files stay directly under this sink; private
+// metadata and partial bytes live below .staging until an exact-length transfer is promoted atomically.
+const UPLOAD_DIR = join(tmpdir(), 'spexcode-uploads');
+const STAGING_DIR = join(UPLOAD_DIR, '.staging');
+export class UploadError extends Error {
+    status;
+    offset;
+    constructor(status, message, offset) {
+        super(message);
+        this.status = status;
+        this.offset = offset;
+    }
+}
+const uploadPolicy = () => readUploadPolicy(repoRoot());
+export const evidenceMaxBytes = () => uploadPolicy().evidenceMaxBytes;
+function ensureDirs() {
+    mkdirSync(STAGING_DIR, { recursive: true });
+}
+function safeName(name) {
+    const base = basename(name || '').replace(/[^A-Za-z0-9._-]/g, '_').replace(/^\.+/, '');
+    return base || 'upload';
+}
+function validId(id) {
+    return /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/i.test(id);
+}
+function metaPath(id) {
+    return join(STAGING_DIR, `${id}.json`);
+}
+function partPath(id) {
+    return join(STAGING_DIR, `${id}.part`);
+}
+function removeTransfer(id) {
+    rmSync(metaPath(id), { force: true });
+    rmSync(partPath(id), { force: true });
+}
+function readMetaFile(id) {
+    if (!validId(id))
+        return null;
+    try {
+        const meta = JSON.parse(readFileSync(metaPath(id), 'utf8'));
+        if (meta.version !== 1 || meta.id !== id || typeof meta.name !== 'string' ||
+            !Number.isSafeInteger(meta.size) || meta.size <= 0 ||
+            !Number.isSafeInteger(meta.offset) || meta.offset < 0 || meta.offset > meta.size ||
+            !Number.isSafeInteger(meta.createdAt) || !Number.isSafeInteger(meta.updatedAt))
+            return null;
+        return meta;
+    }
+    catch {
+        return null;
+    }
+}
+function writeMeta(meta) {
+    const path = metaPath(meta.id);
+    const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    writeFileSync(temp, JSON.stringify(meta) + '\n');
+    renameSync(temp, path);
+}
+function actualOffset(meta) {
+    try {
+        return statSync(partPath(meta.id)).size;
+    }
+    catch {
+        return 0;
+    }
+}
+function status(meta, policy) {
+    const { chunkBytes, concurrency, requestTimeoutMs, retryLimit, retryDelayMs } = policy;
+    return { id: meta.id, name: meta.name, size: meta.size, offset: meta.offset, chunkBytes, concurrency, requestTimeoutMs, retryLimit, retryDelayMs };
+}
+function syncOffset(meta) {
+    const offset = actualOffset(meta);
+    if (offset > meta.size)
+        throw new UploadError(409, 'upload staging file exceeds its declared length');
+    if (offset !== meta.offset) {
+        meta.offset = offset;
+        meta.updatedAt = Date.now();
+        writeMeta(meta);
+    }
+    return meta;
+}
+function loadUpload(id, policy) {
+    const meta = readMetaFile(id);
+    if (!meta)
+        throw new UploadError(404, 'upload not found');
+    if (Date.now() - meta.updatedAt > policy.incompleteTtlMs) {
+        removeTransfer(id);
+        throw new UploadError(404, 'upload expired');
+    }
+    return syncOffset(meta);
+}
+function reservedBytes(policy) {
+    let total = 0;
+    for (const entry of readdirSync(STAGING_DIR, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith('.json'))
+            continue;
+        const meta = readMetaFile(entry.name.slice(0, -5));
+        if (!meta || Date.now() - meta.updatedAt > policy.incompleteTtlMs)
+            continue;
+        total += Math.max(0, meta.size - actualOffset(meta));
+    }
+    return total;
+}
+function reserveCapacity(size, policy) {
+    let available = 0;
+    try {
+        const fs = statfsSync(UPLOAD_DIR);
+        available = Number(fs.bavail) * Number(fs.bsize);
+    }
+    catch {
+        // A filesystem that cannot report capacity will still fail loudly during the stream write.
+        return;
+    }
+    if (size > Math.max(0, available - policy.minFreeBytes - reservedBytes(policy))) {
+        throw new UploadError(507, 'insufficient backend disk capacity for this upload');
+    }
+}
+export function cleanupExpiredUploads(policy = uploadPolicy()) {
+    ensureDirs();
+    const now = Date.now();
+    for (const entry of readdirSync(STAGING_DIR, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith('.json'))
+            continue;
+        const id = entry.name.slice(0, -5);
+        const meta = readMetaFile(id);
+        if (!meta || now - meta.updatedAt > policy.incompleteTtlMs)
+            removeTransfer(id);
+    }
+    for (const entry of readdirSync(STAGING_DIR, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith('.part'))
+            continue;
+        const id = entry.name.slice(0, -5);
+        if (readMetaFile(id))
+            continue;
+        try {
+            if (now - statSync(partPath(id)).mtimeMs > policy.incompleteTtlMs)
+                rmSync(partPath(id), { force: true });
+        }
+        catch { /* raced a cancellation or another cleanup pass */ }
+    }
+}
+export function startUploadReaper() {
+    const sweep = () => {
+        const policy = uploadPolicy();
+        cleanupExpiredUploads(policy);
+        const timer = setTimeout(sweep, policy.cleanupIntervalMs);
+        timer.unref();
+    };
+    sweep();
+}
+export function createUpload(name, size) {
+    const policy = uploadPolicy();
+    if (typeof name !== 'string' || !name.trim())
+        throw new UploadError(400, 'file name is required');
+    if (typeof size !== 'number' || !Number.isSafeInteger(size) || size <= 0)
+        throw new UploadError(400, 'file must not be empty');
+    if (size > policy.maxBytes)
+        throw new UploadError(413, 'file exceeds the configured upload limit');
+    ensureDirs();
+    cleanupExpiredUploads(policy);
+    reserveCapacity(size, policy);
+    const now = Date.now();
+    const meta = { version: 1, id: randomUUID(), name: safeName(name), size, offset: 0, createdAt: now, updatedAt: now };
+    writeMeta(meta);
+    return status(meta, policy);
+}
+export function uploadStatus(id) {
+    const policy = uploadPolicy();
+    return status(loadUpload(id, policy), policy);
+}
+export async function appendUpload(id, offset, body, contentLength) {
+    const policy = uploadPolicy();
+    const meta = loadUpload(id, policy);
+    if (typeof offset !== 'number' || !Number.isSafeInteger(offset) || offset < 0)
+        throw new UploadError(400, 'upload offset must be a non-negative integer');
+    if (offset !== meta.offset)
+        throw new UploadError(409, 'upload offset does not match the committed bytes', meta.offset);
+    if (!body)
+        throw new UploadError(400, 'upload chunk is required');
+    const declared = contentLength == null ? null : Number(contentLength);
+    if (declared != null && (!Number.isSafeInteger(declared) || declared <= 0))
+        throw new UploadError(400, 'content-length must be a positive integer');
+    if (declared != null && (declared > policy.chunkBytes || meta.offset + declared > meta.size)) {
+        throw new UploadError(413, 'upload chunk exceeds its declared bounds');
+    }
+    let written = 0;
+    const before = meta.offset;
+    const limiter = new Transform({
+        transform(chunk, _encoding, callback) {
+            written += chunk.length;
+            if (written > policy.chunkBytes || before + written > meta.size) {
+                callback(new UploadError(413, 'upload chunk exceeds its declared bounds'));
+                return;
+            }
+            callback(null, chunk);
+        },
+    });
+    try {
+        await pipeline(Readable.fromWeb(body), limiter, createWriteStream(partPath(id), { flags: 'a' }));
+    }
+    catch (error) {
+        if (error instanceof UploadError) {
+            truncateSync(partPath(id), before);
+            throw error;
+        }
+        // An interrupted connection may have committed a valid prefix. The next GET reports its actual length.
+        meta.offset = actualOffset(meta);
+        meta.updatedAt = Date.now();
+        writeMeta(meta);
+        throw new UploadError(500, `upload write failed: ${error.message}`);
+    }
+    if (written === 0)
+        throw new UploadError(400, 'upload chunk is empty');
+    meta.offset = actualOffset(meta);
+    meta.updatedAt = Date.now();
+    writeMeta(meta);
+    return status(meta, policy);
+}
+export function completeUpload(id) {
+    const meta = loadUpload(id, uploadPolicy());
+    if (meta.offset !== meta.size)
+        throw new UploadError(409, `upload is incomplete (${meta.offset} of ${meta.size} bytes)`, meta.offset);
+    const path = join(UPLOAD_DIR, `${Date.now().toString(36)}-${meta.id}-${safeName(meta.name)}`);
+    try {
+        renameSync(partPath(id), path);
+        rmSync(metaPath(id), { force: true });
+        return path;
+    }
+    catch (error) {
+        throw new UploadError(500, `upload completion failed: ${error.message}`);
+    }
+}
+export function cancelUpload(id) {
+    loadUpload(id, uploadPolicy());
+    removeTransfer(id);
+}

package/node_modules/@spexcode/spec-cli/dist/worktree-sources.d.ts

@@ -0,0 +1 @@
+export declare function seedWorktreeHostState(main: string, wt: string): void;

package/node_modules/@spexcode/spec-cli/dist/worktree-sources.js

@@ -0,0 +1,47 @@
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { git } from '@spexcode/spec-core';
+export function seedWorktreeHostState(main, wt) {
+    const f = 'spexcode.local.json';
+    try {
+        if (!existsSync(join(main, f)) || existsSync(join(wt, f)))
+            return;
+        copyFileSync(join(main, f), join(wt, f));
+    }
+    catch (e) {
+        console.error(`spexcode: could not seed ${f} from ${main} into worktree ${wt} — that worker runs on defaults (${e})`);
+        return;
+    }
+    hideSeededFromGit(wt, [f]);
+}
+// what we seed, we hide: a seeded entry git still sees is force-add bait (a real PR once carried seeded
+// files into a product repo). `.git/info/exclude` lives in the COMMON git dir, so one write hides the entry
+// in every linked worktree AND the main checkout. Only entries seeded by THIS call and reported un-ignored
+// by `git check-ignore` are written: idempotent across dispatches, and a repo whose materialize already ignores
+// the overlay (materialize's block under any policy) writes nothing — the self-heal for a half-configured repo.
+function hideSeededFromGit(wt, seeded) {
+    for (const f of seeded) {
+        try {
+            if (isIgnored(wt, f))
+                continue;
+            const exclude = join(git(['-C', wt, 'rev-parse', '--path-format=absolute', '--git-common-dir']).trim(), 'info', 'exclude');
+            mkdirSync(dirname(exclude), { recursive: true });
+            const cur = existsSync(exclude) ? readFileSync(exclude, 'utf8') : '';
+            appendFileSync(exclude, `${cur && !cur.endsWith('\n') ? '\n' : ''}${f}\n`);
+        }
+        catch (e) {
+            console.error(`spexcode: could not hide seeded ${f} in the shared info/exclude for ${wt} — it will show untracked there (${e})`);
+        }
+    }
+}
+function isIgnored(wt, f) {
+    try {
+        git(['-C', wt, 'check-ignore', '-q', f]);
+        return true;
+    }
+    catch (e) {
+        if (e?.status === 1)
+            return false; // check-ignore's documented "not ignored" exit
+        throw e;
+    }
+}

package/{spec-cli → node_modules/@spexcode/spec-cli}/hooks/dispatch.sh

@@ -16,14 +16,14 @@
 # session-worktree creation, and the pre-commit/post-checkout/post-merge hooks). .plugins edits are
 # git-transactional: they take effect at the commit/checkout/merge that carries them, like any other source.
 set -u
-# args: `<harness> <Event>`. A harness id as $1 (claude|codex|opencode|pi|plugin) is consumed; otherwise we keep
+# args: `<harness> <Event>`. A harness id as $1 (claude|codex|opencode|pi|zcode|plugin) is consumed; otherwise we keep
 # $1 as the event and default the harness to claude — so a stale shim still written as `dispatch.sh <Event>`
 # keeps working. `plugin` is the bundle form ([[plugin-harness]]), `opencode` the generated event-bus plugin
-# ([[opencode-harness]]), and `pi` the generated extension ([[pi-harness]]): all three SYNTHESIZE claude-shaped
-# payloads (Claude tool names + file_path), so they join the claude branch in harness.sh via the default case —
-# no parse arm of their own.
+# ([[opencode-harness]]), `pi` the generated extension ([[pi-harness]]), and `zcode` the native adapter: all four
+# carry Claude-shaped payloads (Claude tool names + file_path), so they join the claude branch in harness.sh via
+# the default case — no parse arm of their own.
 harness=claude
-case "${1:-}" in claude|codex|opencode|pi|plugin) harness="$1"; shift ;; esac
+case "${1:-}" in claude|codex|opencode|pi|zcode|plugin) harness="$1"; shift ;; esac
 event="${1:?usage: dispatch.sh <harness> <Event>}"
 export SPEXCODE_HARNESS="$harness"
 # the harness.sh path (the adapter's shell mirror) — sibling of this script; hook handlers source it, and we

package/{spec-cli → node_modules/@spexcode/spec-cli}/hooks/harness.sh

@@ -108,7 +108,7 @@ hp_is_subagent() {
   printf '%s' "${1%%\"tool_input\"*}" | grep -q '"agent_id"[[:space:]]*:' && printf 1
 }
 
-# the per-PROJECT GLOBAL runtime dir (mirrors spec-cli/src/layout.ts `runtimeRoot`): <store>/projects/<enc>,
+# the per-PROJECT GLOBAL runtime dir (mirrors packages/spec-core/src/layout.ts `runtimeRoot`): <store>/projects/<enc>,
 # keyed by the project (dirname of the ABSOLUTE git-common-dir, so the answer is identical from main or any
 # worktree). The per-session dirs and the per-tree materialize slots (hp_tree_dir) live under it.
 # Echoes the dir; returns non-zero (echoing nothing) when git can't resolve, so a caller can `|| exit 0`.

package/node_modules/@spexcode/spec-cli/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@spexcode/spec-cli",
+  "version": "0.6.6",
+  "type": "module",
+  "description": "SpexCode CLI + server. The root spexcode package delegates to this compiled package; dashboard assets live in @spexcode/spec-dashboard.",
+  "bin": {
+    "spex": "bin/spex.mjs"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./bin/spex.mjs": "./bin/spex.mjs",
+    "./ranker": "./dist/ranker.js",
+    "./eval-host": "./dist/eval-host.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "templates",
+    "hooks"
+  ],
+  "bundledDependencies": [
+    "@spexcode/spec-core",
+    "@spexcode/session-core",
+    "@spexcode/spec-eval",
+    "@spexcode/spec-forge"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node ../scripts/build-dist.mjs",
+    "prepublishOnly": "node ../scripts/release-publish.mjs --from-package-publish",
+    "serve": "npm run build && node bin/spex.mjs serve",
+    "lint": "npm run build && node bin/spex.mjs spec lint",
+    "test": "tsx --import ../scripts/test-home.mjs --test src/*.test.ts"
+  },
+  "dependencies": {
+    "@spexcode/session-core": "0.6.6",
+    "@spexcode/spec-core": "0.6.6",
+    "@spexcode/spec-eval": "0.6.6",
+    "@spexcode/spec-forge": "0.6.6"
+  },
+  "devDependencies": {
+    "@types/node": "^20.16.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  }
+}

package/node_modules/@spexcode/spec-cli/templates/spec/project/.plugins/commands/supervisor/spec.md

@@ -0,0 +1,8 @@
+---
+title: supervisor
+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. This preset IS your complete playbook (dispatch → monitor → review → merge → close, and how to parallelize) — the CLI's own `spex help session` is the reference for every verb's exact semantics. Drive the goal: decompose it into worker-sized tasks and dispatch one worker per independent task (`spex session new "<task>"` creates the parent-child relation and automatically installs your managed `parent` watch; inspect that existing relation/source with `spex session watch list`, so do NOT add a manual watch for this child — give it ONLY its task; a task about one specific node mentions it as `[[<id>]]`, which only sets the branch name and board attribution; the session's real node links come from what it edits), review proposals with `spex session review <id>`, dispatch the merge of good ones back to their own session (`spex session merge <id>`; the doer syncs the base into its own worktree first, so what reaches `<root>` is a trivial merge) and confirm it landed, then close. `<root>` is the fleet's ONE landing door — it takes one landing at a time, so a worker whose merge finds it mid-merge waits rather than racing, and you never fix up another lane's half-merged index yourself. Never let a worker self-merge; keep `spex spec lint` at 0 errors. To READ a worker's current state, use the one-shot snapshots (`spex session review <id>` or `spex session ls` — both return immediately); for a local next-lifecycle-edge read when no managed delivery exists, background `spex session wait <id>` — it returns only when it OBSERVES the worker transition from non-actionable into an actionable status (an already-actionable arrival state does not return it), printing the observed status path; `spex session watch stream` is human-only and STREAMS forever, so never block on it. **Stay parked while your fleet runs:** `spex session new`'s managed watch delivery is a real wake-up, so park while it exists. A manual `spex session watch <id>` is deliberate ongoing supervision of an existing session, not a one-off wait: it adds your `manual` source, and every future AUTHORED state transition is queued as a message to the watcher until `spex session watch cancel <id>` removes that source. That creates continuing traffic/noise, so use manual watch only when you want that consequence; `watch list` inspects the relation/source and `watch cancel` removes only the manual source. An `@<session>` explanation request is point-to-point: use `spex session send <id> "<question>"`; the reply hint returns over send, never watch/wait. Only go `asking` when you genuinely need the human. This matters because the dashboard **folds each child under you and shows YOUR own status for the whole group** (session-nesting, no child-status aggregation), so a supervisor that stays parked-while-they-run is what makes that folded group status honest. Two footguns that bite a fresh supervisor. First: 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. Second: `<id>` always names a WORKER YOU DISPATCHED, spelled out — never `.` and never your own id. `.` means the session running the command, so `close .` deletes your own worktree, branch and record mid-turn and takes your fleet's manager down with it; your own ending is a declaration (`done --propose close`), never a close you run on yourself. **DRAIN THE ISSUES** (issues / local-issues) as part of your loop: `spex issue ls` lists every open concern in one place — the taste concerns finished sessions recorded locally, AND the forge's issues, store-tagged. Cluster the same concern yourself (use judgment — duplicates are a recurrence SIGNAL, not noise; fold them into one) and weigh by recurrence AND novelty — **recurrence is salience, not importance, so never just fix the highest count**: a sharp single-voice concern can outrank a popular gripe. For the ones worth acting on, `spex session new "<task>"` a worker to land it (mention the concern's node as `[[<id>]]` if it has one), then `spex issue ls resolve <id> --as accepted|landed` (or `rejected`, with a reply saying why) so the store reflects the decision. Report progress as you go and when the goal is complete. Your goal follows:

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

@@ -37,7 +37,7 @@ EOF
 [ -n "$owner" ] || exit 0
 
 mkdir -p "$sdir"; : > "$sent"
-reason="Before accessing governed source $path, read its governing spec FIRST: $owner. Read the relevant NEIGHBORS too: the parent that scopes it, the siblings it borders, and the children that refine it. Then reconcile deliberately: change the spec if the intent is changing, or make the code honor it. The one forbidden move is code that silently diverges from its spec. (Fires once per session, at the first governed code read.)"
+reason=$($S internal hook-prompt spec-first --path "$path" --owner "$owner") || 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/{spec-cli → node_modules/@spexcode/spec-cli}/templates/spec/project/.plugins/core/spec-of-file/spec-of-file.sh

@@ -60,6 +60,7 @@ done <<EOF
 $paths
 EOF
 [ -n "$msg" ] || exit 0
+msg=$($S internal hook-prompt spec-of-file --details "$msg") || exit 1
 esc=$(printf '%s' "$msg" | sed 's/\\/\\\\/g; s/"/\\"/g' | awk 'BEGIN{ORS=""} NR>1{print "\\n"} {print}')
 printf '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"%s"}}\n' "$esc"
 exit 0

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

@@ -10,9 +10,9 @@ block: true
 ---
 The blocking stop gate, with two jobs, each holding a hard loop-break so it never blocks twice on the same cause and never lets a dishonest stop through.
 
-The COMMIT gate keeps a done/merge proposal honest: such a proposal is rejected while the branch still carries uncommitted work or is zero commits ahead of main, because the ritual commits the spec and code BEFORE proposing. Clean work is allowed to stop; a dirty proposal blocks once with the reason, and if the agent ignores it the gate escapes by downgrading to `asking` so a false "ready to merge" can never stand.
+The COMMIT gate keeps a done/merge proposal honest: such a proposal is rejected while the branch still carries uncommitted work or is zero commits ahead of main, because the ritual commits the spec and code BEFORE proposing. Clean work is allowed to stop; a dirty proposal blocks once with the reason, and if the agent ignores it the gate escapes by downgrading to `asking` so a false "ready to merge" can never stand. `done --propose nothing` is a porcelain trap, not a declaration: it writes no state and names merge, close, ask, and park as the real destinations; legacy `nothing` records remain readable.
 
-The DECLARE gate refuses to let a session stop in an undeclared `active` state, since a state is a claim the board and other agents act on, not a box ticked to end a turn. A declared state stops freely; an undeclared first stop emits `{"decision":"block"}` and the dispatcher exits 2 so the harness actually interrupts the stop and shows the reason; on the forced continuation it auto-declares a safe default — committed work becomes `awaiting`, otherwise `asking` — so the loop is guaranteed to end.
+The DECLARE gate refuses to let a session stop in an undeclared `active` state, since a state is a claim the board and other agents act on, not a box ticked to end a turn. A declared state stops freely; an undeclared first stop emits `{"decision":"block"}` and the dispatcher exits 2 so the harness actually interrupts the stop and shows the reason; on the forced continuation it declares `asking`, so the loop is guaranteed to end without inventing a completion state. state owns the choice: a posted file or web artifact, a reported finding/recommendation awaiting a human decision, or any handoff awaiting human direction selects `asking`; `close-pending` requires genuinely settled work with no such outstanding decision or follow-up.
 
 The block text is where the declaration ritual is taught, so it is written to be read at two depths. The FULL teaching text prints once per session: it names the PATH-independent CLI once as a shared prefix, lists the five choices as a compact menu each with its application condition (park policed hardest — a false park is the most damaging mislabel). A real wake source is either a background job or a managed session-follow subscription whose normal send delivery will re-enter the parent; a caller without that address must still arm background `session wait`. It ends with the ordering discipline: declare LAST, then stop — a declaration followed by more tool calls honestly re-flips the record to active ([[mark-active]], by design), so making the declaration the turn's final call is what eliminates the park→block→re-park loop at its source. Every later undeclared stop in the same session gets a ONE-LINE version instead (a heavy session hits the gate 15-20 times a night; re-printing the full menu is token noise). The once-sentinel is a plain file beside the session record in the global store — the same per-session-sentinel mechanism as the CLI's note-truncation notice, never a second scheme. The terse line stays self-explanatory: it carries the command menu, the declare-LAST reminder, and the `spex help session` recovery entry, so an agent that never saw the full text (a compacted context) recovers every choice's condition from the entry rather than from memory — the whole full-to-terse information gap is closable from the line itself.
 

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