spexcode 0.6.1 → 0.6.5

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

@@ -1,15 +1,15 @@
 #!/usr/bin/env bash
 # @@@ harness.sh - the SHELL face of the [[harness-adapter]] (spec-cli/src/harness.ts). The hook scripts run
 # as pure shell, so they cannot import the TS adapter; this sourced library is its mirror. dispatch.sh sources
-# it and exports SPEXCODE_HARNESS (claude|codex|opencode) — baked into the shim by each adapter, so a hook learns its
+# it and exports SPEXCODE_HARNESS (claude|codex|opencode|zcode) — baked into the shim by each adapter, so a hook learns its
 # harness deterministically, never by sniffing the payload shape. EVERY harness-divergent payload-parse lives
 # HERE; the hook scripts stay harness-agnostic and just call hp_* (the one place Claude's tool names appear in
 # shell, plus codex's Bash-command mapping). The session-id + global-store resolution is harness-agnostic and
 # lives here too, so the six hooks no longer each repeat the git-common-dir → project-key dance.
-# SPEXCODE_HARNESS is claude|codex|opencode|pi|plugin: `plugin` is the bundle form ([[plugin-harness]]) and its
-# host (z-code/Claude) shares Claude's payload shape; `opencode`'s generated plugin ([[opencode-harness]]) and
-# `pi`'s generated extension ([[pi-harness]]) SYNTHESIZE claude-shaped payloads by construction — so every
-# `case "$SPEXCODE_HARNESS"` below routes all three through the claude branch via the default case; only codex
+# SPEXCODE_HARNESS is claude|codex|opencode|pi|zcode|plugin: `plugin` is the bundle form ([[plugin-harness]]) and its
+# host (adopter-a/Claude) shares Claude's payload shape; `opencode`'s generated plugin ([[opencode-harness]]),
+# `pi`'s generated extension ([[pi-harness]]), and z-code's native hook payload all share that Claude shape — so every
+# `case "$SPEXCODE_HARNESS"` below routes all four through the claude branch via the default case; only codex
 # keeps parse arms of its own.
 
 
@@ -68,11 +68,28 @@ hp_field() {
 # every child tool call fired mark-active against the PARENT's record — the parent read `working` forever and
 # every park/done declaration was clobbered within seconds (measured). Same staleness class the codex branch
 # already guards against (payload-first below); claude now follows the same rule.
+# The claude preference is RESOLUTION-AWARE, not blind. "Claude's payload id equals its governed record id"
+# holds only while the launched conversation lives: a compaction/continuation MINTS A NEW conversation id
+# while the record keeps the launched one, and a blindly-preferred payload id then resolves to no record at
+# all — hp_store_dir echoes a path nothing sits at, so every record-dependent hook (stop-gate, mark-active,
+# idle, session-fail) silently no-ops and the session reads `working` forever (measured: a live session froze
+# at `active` while its terminal still answered). So the payload wins only when a record actually answers to
+# it, and an unresolvable payload falls back to the launched SPEXCODE_SESSION_ID. This cannot reopen the
+# subagent bug above: a Task subagent's payload carries the PARENT's session_id, which DOES resolve, so the
+# preference is unchanged there — the divergent branch is reached only when the two ids differ AND the
+# payload names nothing. The common path costs one string compare (the ids are equal), never a store read.
 hp_session_id() {
   local pid
   case "$SPEXCODE_HARNESS" in
     codex) hp_field "$1" session_id ;;
-    *)     pid=$(hp_field "$1" session_id); printf '%s' "${pid:-$SPEXCODE_SESSION_ID}" ;;
+    *)     pid=$(hp_field "$1" session_id)
+           if [ -n "$pid" ] && [ -n "$SPEXCODE_SESSION_ID" ] && [ "$pid" != "$SPEXCODE_SESSION_ID" ] \
+              && [ ! -e "$(hp_store_dir "$pid")/session.json" ] \
+              && [ -e "$(hp_store_dir "$SPEXCODE_SESSION_ID")/session.json" ]; then
+             printf '%s' "$SPEXCODE_SESSION_ID"
+           else
+             printf '%s' "${pid:-$SPEXCODE_SESSION_ID}"
+           fi ;;
   esac
 }
 
@@ -91,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`.
@@ -129,6 +146,9 @@ hp_store_dir() {
   local rd; rd=$(hp_runtime_dir) || return 1
   local direct="$rd/sessions/$1"
   if [ -e "$direct/session.json" ]; then printf '%s' "$direct"; return 0; fi
+  # same two-halves-of-absence rule as layout.ts's readAliasedRecordEntry: an id owning a store dir is already
+  # one of ours, so its emptiness is settled and the alias grep is the wrong question (and a whole-store scan).
+  if [ -d "$direct" ]; then printf '%s' "$direct"; return 0; fi
   local hit
   hit=$(grep -lF "\"harness_session_id\": \"$1\"" "$rd"/sessions/*/session.json 2>/dev/null | head -1)
   [ -n "$hit" ] && { printf '%s' "${hit%/session.json}"; return 0; }

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

@@ -0,0 +1,47 @@
+{
+  "name": "@spexcode/spec-cli",
+  "version": "0.6.5",
+  "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/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/spec-core": "0.6.5",
+    "@spexcode/spec-eval": "0.6.5",
+    "@spexcode/spec-forge": "0.6.5"
+  },
+  "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/node_modules/@spexcode/spec-cli/templates/spec/project/.plugins/core/comment-altitude/spec.md

@@ -0,0 +1,9 @@
+---
+title: comment-altitude
+surface: system
+status: active
+hue: 200
+desc: A config plugin — code comments navigate non-obvious local reasoning; specs own product intent and contract.
+---
+Specs own intent, invariants, policy, and observable contracts. Comments only navigate non-obvious local decisions.
+`spex guide spec` has the comment-altitude details.

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/node_modules/@spexcode/spec-cli/templates/spec/project/.plugins/core/spec.md

@@ -0,0 +1,22 @@
+---
+title: core
+surface: system
+status: active
+hue: 200
+desc: A config plugin — the minimal spec-discipline contract folded into every launched agent.
+code:
+---
+Use noun-first CLI commands; `spex help` is the authoritative command map.
+
+Anything a human needs to inspect, whether a file or a local webpage, goes out through `spex session files add` or
+`spex session web add`: never paste an absolute path or `host:port`, and never start a static server yourself.
+
+When this session has a clearly running child session (`active` or `parked`), the parent is supervising rather
+than finished: declare `park`, not `done`/`awaiting`, until the child reports a settled state.
+
+1. **Spec first:** before governed code, read its spec body with `spex spec owner <path>` or `spex spec search`.
+   Update that current-state body with any changed intent.
+2. **Commit before declare:** commit the code and spec it justifies before done or merge; independent intent gets
+   its own node.
+3. **Keep the loss signal honest:** run `spex spec lint` (the blocking correctness gate) and `spex eval lint --changed`. Measure changed scenarios
+   through the real product, commit the verified tree, then file with `spex eval add`; the reading's `codeSha` must name that commit.

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.