spexcode 0.6.1 → 0.6.5

package/spec-cli/src/uploads.ts

@@ -1,253 +0,0 @@
-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 type { ReadableStream as NodeReadableStream } from 'node:stream/web'
-import { repoRoot } from './git.js'
-import { readUploadPolicy, type UploadPolicy } from './layout.js'
-
-// 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')
-
-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 class UploadError extends Error {
-  constructor(readonly status: number, message: string, readonly offset?: number) {
-    super(message)
-  }
-}
-
-const uploadPolicy = (): UploadPolicy => readUploadPolicy(repoRoot())
-
-export const evidenceMaxBytes = (): number => uploadPolicy().evidenceMaxBytes
-
-function ensureDirs(): void {
-  mkdirSync(STAGING_DIR, { recursive: true })
-}
-
-function safeName(name: string): string {
-  const base = basename(name || '').replace(/[^A-Za-z0-9._-]/g, '_').replace(/^\.+/, '')
-  return base || 'upload'
-}
-
-function validId(id: string): boolean {
-  return /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/i.test(id)
-}
-
-function metaPath(id: string): string {
-  return join(STAGING_DIR, `${id}.json`)
-}
-
-function partPath(id: string): string {
-  return join(STAGING_DIR, `${id}.part`)
-}
-
-function removeTransfer(id: string): void {
-  rmSync(metaPath(id), { force: true })
-  rmSync(partPath(id), { force: true })
-}
-
-function readMetaFile(id: string): UploadMeta | null {
-  if (!validId(id)) return null
-  try {
-    const meta = JSON.parse(readFileSync(metaPath(id), 'utf8')) as UploadMeta
-    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: UploadMeta): void {
-  const path = metaPath(meta.id)
-  const temp = `${path}.${process.pid}.${randomUUID()}.tmp`
-  writeFileSync(temp, JSON.stringify(meta) + '\n')
-  renameSync(temp, path)
-}
-
-function actualOffset(meta: UploadMeta): number {
-  try {
-    return statSync(partPath(meta.id)).size
-  } catch {
-    return 0
-  }
-}
-
-function status(meta: UploadMeta, policy: UploadPolicy): UploadStatus {
-  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: UploadMeta): UploadMeta {
-  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: string, policy: UploadPolicy): UploadMeta {
-  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: UploadPolicy): number {
-  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: number, policy: UploadPolicy): void {
-  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()): void {
-  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(): void {
-  const sweep = () => {
-    const policy = uploadPolicy()
-    cleanupExpiredUploads(policy)
-    const timer = setTimeout(sweep, policy.cleanupIntervalMs)
-    timer.unref()
-  }
-  sweep()
-}
-
-export function createUpload(name: unknown, size: unknown): UploadStatus {
-  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: UploadMeta = { version: 1, id: randomUUID(), name: safeName(name), size, offset: 0, createdAt: now, updatedAt: now }
-  writeMeta(meta)
-  return status(meta, policy)
-}
-
-export function uploadStatus(id: string): UploadStatus {
-  const policy = uploadPolicy()
-  return status(loadUpload(id, policy), policy)
-}
-
-export async function appendUpload(id: string, offset: unknown, body: ReadableStream<Uint8Array> | null, contentLength?: string): Promise<UploadStatus> {
-  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 as unknown as NodeReadableStream), 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 as 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: string): string {
-  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 as Error).message}`)
-  }
-}
-
-export function cancelUpload(id: string): void {
-  loadUpload(id, uploadPolicy())
-  removeTransfer(id)
-}

package/spec-cli/src/worktree-sources.ts

@@ -1,42 +0,0 @@
-import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
-import { git } from './git.js'
-
-export function seedWorktreeHostState(main: string, wt: string): void {
-  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: string, seeded: string[]): void {
-  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: string, f: string): boolean {
-  try { git(['-C', wt, 'check-ignore', '-q', f]); return true }
-  catch (e: any) {
-    if (e?.status === 1) return false   // check-ignore's documented "not ignored" exit
-    throw e
-  }
-}

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

@@ -1,8 +0,0 @@
----
-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>"` — give each 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), monitor with `spex session watch`, 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); to WAIT for a worker, background `spex session wait <id>` — it is edge-triggered: 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 — which is also how you wait for a dispatched merge to actually land; never block on `spex session watch stream`, which STREAMS forever and will freeze your turn. **Stay parked while your fleet runs:** `spex session new` registers its managed child watch automatically, and a managed watch's send delivery is a real wake-up, so park while those watches exist. For an existing governed worker run one-shot `spex session watch <child>`; use `watch list`/`watch cancel <child>` to manage the relation. With no governed parent address, background a `spex session wait <child>` instead. 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/templates/spec/project/.plugins/core/comment-altitude/spec.md

@@ -1,28 +0,0 @@
----
-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.
----
-Code comments are navigation aids, not a second specification. The owning spec body is the current contract:
-intent, invariants, externally observable behavior, and product policy belong there once, rather than being
-restated beside each implementation.
-
-Before retaining or adding a comment, ask in this order:
-
-1. Does it state intent or a contract? Put that fact in the owning spec body if it is not already there, then
-   remove the code comment.
-2. Does it explain a non-obvious local decision — ordering, a platform or library behavior, a measured pitfall,
-   or why an otherwise plausible implementation is unsafe? Keep a short comment beside the decision. It should
-   name the fact the reader cannot recover from code alone, not re-explain the whole feature.
-3. Does it merely translate the next line or restate a type/name? Remove it.
-
-Never turn subtraction into amnesia. A measured value, version-specific behavior, rejected alternative, or other
-implementation fact absent from the spec must remain in code unless it is truly product contract, in which case
-move the fact to the spec before deleting the comment. `@@@title - explanation` is reserved for the genuinely
-tricky local reasoning that survives this test; a tag is not a license to repeat the spec.
-
-This division gives each information channel one repair path: a changed product promise updates its spec; a changed
-implementation hazard updates its nearby comment; code that makes either false updates both as their distinct facts
-require. The rule complements [[spec-first]]: reading the contract first is what makes redundant code prose visible.

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

@@ -1,23 +0,0 @@
----
-title: core
-surface: system
-status: active
-hue: 200
-desc: A config plugin — the minimal spec-discipline contract folded into every launched agent.
-code:
----
-The CLI is noun-first: `spex <noun> <verb> [object] [flags]`. `spex help` is the authoritative command map;
-use a noun's `--help` for exact usage. Ordinary Git, shell, editor, branch, and worktree tools remain available;
-SpexCode commands manage only SpexCode state.
-
-Four disciplines, non-negotiable:
-
-1. SPEC FIRST. Before reading or changing governed code, read the governing spec BODY. Use `spex spec owner
-<path>` or `spex spec search <topic>` to find it; read neighboring bodies when the contract needs their context.
-The body is the contract; update it with code when intent changes.
-2. COMMIT BEFORE YOU DECLARE. Commit the spec and the code it justifies before declaring done or proposing merge.
-Independent intent gets its own sibling node; do not ride it on an assigned node.
-3. THE BODY IS A LIVING CURRENT-STATE DOCUMENT. Rewrite present intent in place; never add a `## vN` changelog.
-4. KEEP THE LOSS SIGNAL HONEST. Before declaring, run both: `spex spec lint` is the blocking correctness gate;
-`spex eval lint --changed` reports measurement gaps. Re-run changed eval scenarios through the real product, commit the verified tree, then
-file with `spex eval add`; the reading's `codeSha` must name that commit, and evidence must fit the behavior.

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

@@ -1,32 +0,0 @@
----
-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 — conflicts belong in YOUR worktree, never in the shared checkout
-
-Every worktree lands through ONE shared directory: the trunk checkout. Git refuses any merge while that
-directory's index holds an unresolved one, so a merge that stops to ask about conflicts holds the fleet's
-only landing door for as long as a human takes to think — while a merge that *cannot* conflict holds it for
-milliseconds. Land only the second kind.
-
-- **Sync first, in your own worktree.** Before you land, merge the trunk INTO your branch (`git merge
-  <base>`) right where you work: resolve every conflict there and re-run what proves your work — the tests,
-  the scenario you measured. Your worktree is the only place that has your context, your tooling, and nobody
-  waiting behind you.
-- **The landing itself must be trivial.** `git merge-base --is-ancestor <base> <branch>` must be TRUE at the
-  moment you land: your branch already contains the trunk, so the merge writes a commit and nothing else. If
-  it is false — the trunk moved while you were testing — do NOT land: sync again, then land. Resolving
-  conflicts *in the shared checkout* is the one forbidden move; it blocks everyone behind a half-merged index,
-  and it decides the conflict in the place with the least context about the other side.
-- **A busy door is a wait, not a race.** If the shared checkout is already mid-merge, you cannot land — wait
-  and retry, bounded. Never `git merge --abort` someone else's in-progress merge and never resolve their
-  conflicts for them: that is their work in flight, and aborting it destroys the part they had already
-  reasoned through. If your OWN landing ends up half-merged, abort yours and report rather than leaving the
-  trunk mid-state.
-- **An auto-merge is not a tested merge.** A clean merge proves the texts didn't overlap, not that the
-  combination works: two branches can each be green and their merge red. That is why the sync happens where
-  you can re-run the proof, and why "it merged without conflicts" is never the standard for landing.

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

@@ -1,9 +0,0 @@
----
-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:
----
-When you open an issue or change request through the repository's resolved forge, link it to the spec node(s) it serves by adding one line to its **body**: `Spec: <node-id>` (comma-separate several). The id is the node's **leaf** name — the folder under `.spec/…/<id>/spec.md`, e.g. `sessions`, never the slash-path. An unrecognized id silently links nothing, so use a real node id (`spex graph --json` lists them). This is the one linking marker on every forge.

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

@@ -1,15 +0,0 @@
----
-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 — keep the shared store identity-clean
-
-SpexCode's agent memory is keyed by the **main project**, so every agent running under this project — the main checkout AND every worktree — reads the **same** memory. That makes session- and role-specific facts toxic: one agent's note silently becomes every agent's belief. So, when deciding whether to record a memory:
-
-- **Never record session-specific content** — this task, this worktree's transient state, a one-off decision, who you're talking to right now. Memory is ONLY for durable, cross-session project/user facts.
-- **On a non-main worktree** (you are on a `node/<id>` branch, not the main checkout): do **not** record any memory for this session at all. Its work is transient and will merge or close; a durable lesson is recorded later, from main, once it has actually landed.
-- **Even on main, never record a transient ROLE or IDENTITY** — "I am the supervisor", "I'm the coordinator", "I'm the agent doing X". These are per-launch facts, not durable ones. Recording one makes the next launched agent read *itself* as that role, and several agents in one folder dissolve into mutual-supervision confusion (everyone thinks they're the supervisor, everyone watches everyone).

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

@@ -1,18 +0,0 @@
----
-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 — the fix's proof is a fail→pass pair
-
-If your task is to FIX A BUG, reproduce it *first*, as a measurement — before you touch the fix. A claim that something is broken is worth nothing until the loss signal shows it broken; a claim that you fixed it is worth nothing until the same signal shows it passing. So a bug fix is bracketed by two readings of ONE scenario:
-
-- **A — reproduce (fail).** Find the eval-core scenario whose expected the bug violates (if none fits, ADD one to the node's `eval.md` — a description + the expected correct behaviour), run it, and file the failing reading with evidence that SHOWS the bug: `spex eval add <node> --scenario <s> --fail --note "<what's wrong>"` plus an `--image`/`--video` of the actual broken behaviour. This is not ceremony — reproducing is how you learn what actually breaks, and a fix aimed at an unreproduced bug aims at a guess.
-- **B — fix, verify, commit, then file (pass).** Four moves, in order: make the code honor the spec; run the SAME scenario against your **working tree** until it actually passes — confidence is earned here, before any commit; **commit** the verified tree; only then file the passing reading, `spex eval add <node> --scenario <s> --pass`, so its `codeSha` names the very commit you measured (the sidecar append lands last, on top of it). Confidence and anchoring are two different acts: you test the uncommitted tree, but the reading's sha anchor can only land after the commit — this is NOT "commit first, then test" (blind commits with routine rollbacks are bad git). A git sha names only a commit and an uncommitted change has none, so a reading filed from a dirty tree is born mis-anchored — its `codeSha` is a HEAD that does not contain the change it claims to measure — and freshness later marking it stale is the mis-anchor being correctly exposed, not an engine bug. (A needs no such care: it measures the bug on the old, already-committed HEAD, so its anchor is honest as-is.)
-
-The two readings on the same scenario are the **A/B** — the error→correct transition, the fix's proof-of-work. eval already keeps per-scenario reading history, so the pair is durable and navigable end to end: the dashboard annotator flips between A (fail) and B (pass), and a trunk delivery (deliver-port) carries that pair as the evidence the fix is real. Don't skip A because the fix looks obvious — an obvious fix with no reproduced failure leaves the loss signal blind to exactly the regression you just closed.
-
-This does not apply to building new intent (there is no prior failure to reproduce) — it is the discipline for **repair**: keep the loss signal honest across a bug's whole lifecycle, not just at the end.

package/spec-dashboard/dist/assets/App-F9uaAVcH.js

@@ -1,2 +0,0 @@
-const __vite__mapDeps=(i,m=__vite__mapDeps,d=(m.f||(m.f=["assets/Dashboard-Ba_jhxp1.js","assets/index-DrVao0Ep.js","assets/index-CsI8DElI.css","assets/SessionWindow-CixDi4PI.js","assets/Thread-C6Go8HRh.js","assets/PageScroll-hT7UTLvD.js","assets/data-B-RQmit6.js","assets/Modal-CQgYymmr.js","assets/bindings-BC9vqpYU.js","assets/Dashboard-C5ap-Sga.css","assets/MobileApp-CHgEHORJ.js","assets/launch-BBH02b1v.js","assets/launch-Cp579UoJ.css","assets/ProjectsPage-CtXxakF9.js"])))=>i.map(i=>d[i]);
-import{u as N,r as a,j as n,I as D,a as B,P as k,i as z,_ as T,D as M,b as G}from"./index-DrVao0Ep.js";import{a as J,l as q,s as F,p as V}from"./data-B-RQmit6.js";const h=async e=>(e.headers.get("content-type")||"").includes("json")?e.json().catch(()=>null):null,H=5e3,O=(e,r,t)=>({title:typeof(e==null?void 0:e.title)=="string"&&e.title?e.title:r,icon:typeof(e==null?void 0:e.icon)=="string"&&e.icon?e.icon:t});function x(e){if(!e||typeof e!="object")return null;const r=e.id??e.projectId;return r?{id:String(r),identity:O(e.identity||{title:e.name,icon:e.icon},e.name||String(r),"spexcode"),root:typeof e.root=="string"?e.root:"",online:typeof e.online=="boolean"?e.online:null,url:e.url||"",port:e.port??null,gated:!!(e.gated??e.locked??e.hasPassword),configRevision:typeof e.configRevision=="string"?e.configRevision:""}:null}const W=e=>{const r=Array.isArray(e)?e:Array.isArray(e==null?void 0:e.projects)?e.projects:null;return r?r.map(x).filter(Boolean):null},Y=10;function ce(e,r,t=Y){const s=Array.isArray(e)?e:[],o=Math.max(1,Math.ceil(s.length/t)),l=Math.min(Math.max(1,Number.isInteger(r)?r:1),o);return{items:s.slice((l-1)*t,l*t),page:l,pageCount:o}}function Z(e,r,t){var s;if(!e)return t;if(!r)return null;if(r.state==="ok"){const o=(s=r.projects)==null?void 0:s.find(l=>l.id===e);return(o==null?void 0:o.identity)||{title:e,icon:"spexcode"}}return{title:(t==null?void 0:t.title)||e,icon:(t==null?void 0:t.icon)||"spexcode"}}const K=e=>(e==null?void 0:e.state)==="ok"?e.gateway.identity:{title:"Projects",icon:"gateway"},Q=e=>(e==null?void 0:e.title)||"SpexCode",R=(e,r)=>(r==null?void 0:r.state)==="absent"&&e&&e.state!=="absent"?e:r;async function X(){let e;try{e=await fetch("/projects",{cache:"no-store",headers:{Accept:"application/json"}})}catch{return{state:"absent"}}if(e.status===401)return{state:"denied",reason:"admin-login"};if(e.status===403)return{state:"denied",reason:"locked"};if(!e.ok)return{state:"absent"};const r=await h(e),t=W(r);if(!t)return{state:"absent"};const s=r!=null&&r.gateway&&typeof r.gateway=="object"?{identity:O(r.gateway,"Projects","gateway"),revision:typeof r.gateway.revision=="string"?r.gateway.revision:""}:{identity:{title:"Projects",icon:"gateway"},revision:""};return{state:"ok",adminGated:!!(r!=null&&r.adminGated),gateway:s,projects:t}}async function ie(e,{timeoutMs:r=2500}={}){try{const t=await fetch(`/p/${encodeURIComponent(e)}/health`,{cache:"no-store",signal:AbortSignal.timeout(r)});return!t.ok||t.redirected?"unreachable":(await t.text()).trim()==="ok"?"running":"unreachable"}catch{return"unreachable"}}async function C(e,r,t){let s;try{s=await fetch(e,{method:r,headers:{"Content-Type":"application/json",Accept:"application/json"},...r==="PUT"?{body:JSON.stringify({password:t})}:{}})}catch{return{ok:!1,error:"network"}}const o=await h(s)||{};return{ok:s.ok&&o.ok!==!1,status:s.status,...o.error?{error:o.error}:{}}}const le=(e,r)=>C(`/projects/${encodeURIComponent(e)}/password`,"PUT",r),ue=e=>C(`/projects/${encodeURIComponent(e)}/password`,"DELETE"),pe=e=>C("/projects/admin-password","PUT",e),de=()=>C("/projects/admin-password","DELETE");async function ee(e,r){const t=e==="admin"?"/login":`/p/${encodeURIComponent(e.projectId)}/login`;let s;try{s=await fetch(t,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({password:r})})}catch{return{ok:!1,error:"network"}}return s.status===401?{ok:!1,error:"wrong-password"}:s.status===403?{ok:!1,error:"locked"}:s.ok||s.redirected?{ok:!0}:{ok:!1,error:`http-${s.status}`}}async function fe(e=""){let r;try{const s=e?`?path=${encodeURIComponent(e)}`:"";r=await fetch(`/projects/browse${s}`,{cache:"no-store",headers:{Accept:"application/json"}})}catch{return{ok:!1,error:"network"}}const t=await h(r);return r.ok?typeof(t==null?void 0:t.path)!="string"||!Array.isArray(t==null?void 0:t.entries)?{ok:!1,error:"unexpected answer"}:{ok:!0,path:t.path,parent:typeof t.parent=="string"?t.parent:null,home:typeof t.home=="string"?t.home:t.path,gitRoot:typeof t.gitRoot=="string"?t.gitRoot:null,initialized:!!t.initialized,cataloged:!!t.cataloged,entries:t.entries.filter(s=>s&&typeof s.name=="string"&&typeof s.path=="string").map(s=>({name:s.name,path:s.path,git:!!s.git,initialized:!!s.initialized}))}:{ok:!1,status:r.status,error:(t==null?void 0:t.error)||`http-${r.status}`}}async function he(e,r={}){let t;try{t=await fetch("/projects",{method:"POST",headers:{"Content-Type":"application/json",Accept:"application/json"},body:JSON.stringify({root:e,...r})})}catch{return{ok:!1,error:"network"}}const s=await h(t);if(!t.ok)return{ok:!1,status:t.status,error:(s==null?void 0:s.error)||`http-${t.status}`,...s!=null&&s.init&&typeof s.init=="object"?{code:s.init.code??null,output:String(s.init.output??"")}:{}};const o=x(s);return o?{ok:!0,project:o,setup:s.setup??null}:{ok:!1,error:"unexpected answer"}}async function je(e){let r;try{r=await fetch(`/projects/${encodeURIComponent(e)}/config`,{cache:"no-store",headers:{Accept:"application/json"}})}catch{return{ok:!1,error:"network"}}const t=await h(r);return r.ok?typeof(t==null?void 0:t.content)!="string"||typeof(t==null?void 0:t.revision)!="string"?{ok:!1,error:"unexpected answer"}:{ok:!0,content:t.content,revision:t.revision}:{ok:!1,status:r.status,error:(t==null?void 0:t.error)||`http-${r.status}`}}async function me(e,r,t){let s;try{s=await fetch(`/projects/${encodeURIComponent(e)}/config`,{method:"PUT",headers:{"Content-Type":"application/json",Accept:"application/json"},body:JSON.stringify({content:r,revision:t})})}catch{return{ok:!1,error:"network"}}const o=await h(s);return s.ok?typeof(o==null?void 0:o.content)!="string"||typeof(o==null?void 0:o.revision)!="string"?{ok:!1,error:"unexpected answer"}:{ok:!0,content:o.content,revision:o.revision}:{ok:!1,status:s.status,error:(o==null?void 0:o.error)||`http-${s.status}`}}async function $(e,r,t){let s;try{s=await fetch(e,{method:"PUT",headers:{"Content-Type":"application/json",Accept:"application/json"},body:JSON.stringify({icon:r,revision:t})})}catch{return{ok:!1,error:"network"}}const o=await h(s);return s.ok?{ok:!0,...o}:{ok:!1,status:s.status,error:(o==null?void 0:o.error)||`http-${s.status}`}}const ke=(e,r)=>$("/projects/icon",e,r),ge=(e,r,t)=>$(`/projects/${encodeURIComponent(e)}/icon`,r,t);async function U(e,r,t={}){let s;try{s=await fetch(`/projects/${encodeURIComponent(e)}/${r}`,{method:"POST",headers:{"Content-Type":"application/json",Accept:"application/json"},body:JSON.stringify(t)})}catch{return{ok:!1,error:"network"}}const o=await h(s);return s.ok?!o||typeof o!="object"?{ok:!1,error:"unexpected answer"}:{ok:o.ok===!0,code:o.code??null,output:String(o.output??"")}:{ok:!1,status:s.status,error:(o==null?void 0:o.error)||`http-${s.status}`}}const we=(e,r)=>U(e,"init",{harness:r}),ye=e=>U(e,"doctor");async function Pe(e){let r;try{r=await fetch(`/projects/${encodeURIComponent(e)}/serve`,{method:"POST",headers:{Accept:"application/json"}})}catch{return{ok:!1,error:"network"}}const t=await h(r);return r.status===409?{ok:!0,already:!0,project:x(t==null?void 0:t.project)}:r.ok?{ok:!0,project:x(t==null?void 0:t.project)}:{ok:!1,status:r.status,error:(t==null?void 0:t.error)||`http-${r.status}`}}function I({scope:e,projectLabel:r,locked:t,onUnlocked:s}){const o=N(),[l,S]=a.useState(""),[j,A]=a.useState(!1),[g,P]=a.useState(null),m=e==="admin",p=async b=>{if(b.preventDefault(),!l||j)return;A(!0),P(null);const w=await ee(m?"admin":{projectId:e.projectId},l);A(!1),w.ok?(S(""),s()):P(w.error==="wrong-password"?o("credential.wrong"):o("credential.failed"))};return n.jsx("div",{className:"cred-wrap",children:n.jsxs("form",{className:"cred-card",onSubmit:p,children:[n.jsx("div",{className:"cred-brand",children:"$ spexcode"}),n.jsxs("div",{className:"cred-title",children:[n.jsx(D,{name:"lock",size:14,className:"cred-lock"}),t?o("credential.lockedTitle"):m?o("credential.adminTitle"):o("credential.projectTitle",{name:r||e&&e.projectId||""})]}),t?n.jsx("p",{className:"cred-sub",children:o("credential.lockedBody")}):n.jsxs(n.Fragment,{children:[n.jsx("p",{className:"cred-sub",children:o(m?"credential.adminBody":"credential.projectBody")}),g&&n.jsx("div",{className:"cred-err",children:g}),n.jsx("input",{className:"cred-input",type:"password",autoFocus:!0,required:!0,placeholder:"••••••••••","aria-label":o("credential.passwordLabel"),value:l,onChange:b=>S(b.target.value)}),n.jsx("button",{className:"cred-submit",type:"submit",disabled:j||!l,children:o(j?"credential.checking":"credential.unlock")})]})]})})}const te=a.lazy(()=>T(()=>import("./Dashboard-Ba_jhxp1.js").then(e=>e.D),__vite__mapDeps([0,1,2,3,4,5,6,7,8,9]))),re=a.lazy(()=>T(()=>import("./MobileApp-CHgEHORJ.js"),__vite__mapDeps([10,1,2,3,4,5,6,11,12]))),se=a.lazy(()=>T(()=>import("./ProjectsPage-CtXxakF9.js"),__vite__mapDeps([13,1,2,7,5,6])));window.addEventListener("vite:preloadError",e=>{const r=String(e.payload);sessionStorage.getItem("spexcode.chunkReload")!==r&&(sessionStorage.setItem("spexcode.chunkReload",r),e.preventDefault(),location.reload())});function oe(){const e=N(),r=B(),[t,s]=a.useState(null),[o,l]=a.useState(!1),S=a.useRef(new Map),j=a.useCallback((u,c)=>{s(J(u,S.current,c))},[]),[A,g]=a.useState(!1),[P,m]=a.useState(null),[p,b]=a.useState(null);a.useEffect(()=>{let u=!0;const c=()=>X().then(y=>{u&&b(L=>R(L,y))}).catch(()=>{u&&b(y=>R(y,{state:"absent"}))});c();const d=setInterval(c,H);return()=>{u=!1,clearInterval(d)}},[]);const w=a.useRef(0),f=a.useCallback(()=>{const u=++w.current;return q().then(c=>{if(!(u!==w.current||!c)){if(c.authRequired){m(c.authRequired);return}m(null),g(!1),j(c.board,!0),c.seal()}}).catch(()=>{u===w.current&&g(!0)})},[j]),v=!k&&!t&&!!p&&p.state!=="absent",E=!k&&!t&&p===null;a.useEffect(()=>{if(v||E)return;f();const u=F({onBoard:(d,y)=>{w.current++,g(!1),j(d,!!(y!=null&&y.authoritative))},onLegacyChange:()=>{f()},onStatus:l}),c=setInterval(()=>{f()},15e3);return()=>{u(),clearInterval(c)}},[f,j,v,E]);const _=t?V(t):null,i=k?Z(k,p,_):v?K(p):_;return a.useEffect(()=>{i&&(document.title=Q(i))},[i==null?void 0:i.title]),a.useEffect(()=>{if(!i)return;const u=v?M:G,c=z(i.icon,u);let d=document.querySelector("link[rel~='icon']");d||(d=document.createElement("link"),d.rel="icon",document.head.appendChild(d)),d.getAttribute("href")!==c&&d.setAttribute("href",c)},[i==null?void 0:i.icon,v]),P&&k?n.jsx(I,{scope:{projectId:k},projectLabel:(i==null?void 0:i.title)||k,onUnlocked:()=>{m(null),f()}}):t?n.jsx(a.Suspense,{fallback:n.jsx("div",{className:"loading",children:e("hud.loading")}),children:r?n.jsx(re,{specs:t.nodes,sessions:t.sessions,issuesStamp:t.issuesStamp,reloadBoard:f}):n.jsx(te,{specs:t.nodes,sessions:t.sessions,issuesStamp:t.issuesStamp,reload:f,identity:i,catalog:p,boardLive:o})}):v?n.jsx(a.Suspense,{fallback:n.jsx("div",{className:"loading",children:e("hud.loading")}),children:n.jsx(se,{})}):P?n.jsx(I,{scope:"admin",locked:P==="locked",onUnlocked:()=>{m(null),f()}}):A&&(k||p&&p.state==="absent")?n.jsxs("div",{className:"loading load-error",children:[n.jsx("span",{children:e("hud.loadError")}),n.jsx("button",{className:"load-retry",onClick:()=>{g(!1),f()},children:e("hud.retry")})]}):n.jsx("div",{className:"loading",children:e("hud.loading")})}const be=Object.freeze(Object.defineProperty({__proto__:null,default:oe},Symbol.toStringTag,{value:"Module"}));export{be as A,H as C,ce as a,I as b,de as c,fe as d,je as e,ye as f,ke as g,he as h,we as i,me as j,ge as k,X as l,Pe as m,ue as n,le as o,ie as p,pe as s};