@geraldmaron/construct 1.0.12 → 1.0.15

package/commands/review/code.md

@@ -1,12 +1,6 @@
-<!--
-commands/review/code.md (Code review) correctness, regressions, security, test coverage
-
-Code review: correctness, regressions, security, test coverage
--->
 ---
 description: "Code review: correctness, regressions, security, test coverage"
 ---
-
 You are Construct. Review: $ARGUMENTS
 
 If no target specified, review all uncommitted changes (`git diff HEAD`).

package/commands/review/quality.md

@@ -1,12 +1,6 @@
-<!--
-commands/review/quality.md (Quality audit) complexity, naming, duplication, dead code, maintainability
-
-Quality audit: complexity, naming, duplication, dead code, maintainability
--->
 ---
 description: "Quality audit: complexity, naming, duplication, dead code, maintainability"
 ---
-
 You are Construct. Audit quality for: $ARGUMENTS
 
 Check:

package/commands/review/security.md

@@ -1,12 +1,6 @@
-<!--
-commands/review/security.md (Security scan) secrets, auth, injection, data exposure, dependency risk
-
-Security scan: secrets, auth, injection, data exposure, dependency risk
--->
 ---
 description: "Security scan: secrets, auth, injection, data exposure, dependency risk"
 ---
-
 You are Construct. Scan: $ARGUMENTS
 
 If no target specified, scan all uncommitted changes.

package/commands/ship/ready.md

@@ -1,12 +1,6 @@
-<!--
-commands/ship/ready.md (Pre-release check) is this ready to ship?
-
-Pre-release check: is this ready to ship?
--->
 ---
 description: "Pre-release check: is this ready to ship?"
 ---
-
 You are Construct. Check if the following is ready: $ARGUMENTS
 
 Check:

package/commands/ship/release.md

@@ -1,12 +1,6 @@
-<!--
-commands/ship/release.md (Release) plan rollout, changelog, rollback, and post-release verification
-
-Release: plan rollout, changelog, rollback, and post-release verification
--->
 ---
 description: "Release: plan rollout, changelog, rollback, and post-release verification"
 ---
-
 You are Construct. Release the following: $ARGUMENTS
 
 Readiness checklist:

package/commands/ship/status.md

@@ -1,12 +1,6 @@
-<!--
-commands/ship/status.md (Status) current project state, workflow, uncommitted changes, recent activity
-
-Status: current project state, workflow, uncommitted changes, recent activity
--->
 ---
 description: "Status: current project state, workflow, uncommitted changes, recent activity"
 ---
-
 You are Construct. Report status for: $ARGUMENTS
 
 Check and report:

package/commands/understand/docs.md

@@ -1,12 +1,6 @@
-<!--
-commands/understand/docs.md (Look up documentation) current behavior from primary sources, not training memory
-
-Look up documentation: current behavior from primary sources, not training memory
--->
 ---
 description: "Look up documentation: current behavior from primary sources, not training memory"
 ---
-
 You are Construct. Look up: $ARGUMENTS
 
 Do not answer from training knowledge for anything library-specific, version-specific, or API-specific. Search first.

package/commands/understand/research.md

@@ -1,12 +1,6 @@
-<!--
-commands/understand/research.md. Research a topic. Verify facts from primary sources, separate evidence from inference.
-
-Research a topic. Verify facts from primary sources, separate evidence from inference.
--->
 ---
 description: Research a topic. Verify facts from primary sources, separate evidence from inference.
 ---
-
 You are Construct. Research: $ARGUMENTS
 
 Source hierarchy: official docs → release notes/changelogs → source code → tracked issues → community resources.

package/commands/understand/this.md

@@ -1,12 +1,6 @@
-<!--
-commands/understand/this.md (Explore and understand something) trace execution paths, map structure, gather evidence
-
-Explore and understand something: trace execution paths, map structure, gather evidence
--->
 ---
 description: "Explore and understand something: trace execution paths, map structure, gather evidence"
 ---
-
 You are Construct. Explore and explain: $ARGUMENTS
 
 Gather evidence: do not propose solutions unless asked.

package/commands/understand/why.md

@@ -1,12 +1,6 @@
-<!--
-commands/understand/why.md (Investigate a failure) why is this broken, what is the root cause
-
-Investigate a failure: why is this broken, what is the root cause
--->
 ---
 description: "Investigate a failure: why is this broken, what is the root cause"
 ---
-
 You are Construct. Investigate: $ARGUMENTS
 
 1. Capture: exact error, stack trace, reproduction steps

package/commands/work/clean.md

@@ -1,12 +1,6 @@
-<!--
-commands/work/clean.md (Remove AI-generated code smells) verbosity, hedging, dead comments, generic names
-
-Remove AI-generated code smells: verbosity, hedging, dead comments, generic names
--->
 ---
 description: "Remove AI-generated code smells: verbosity, hedging, dead comments, generic names"
 ---
-
 You are cx-reviewer identifying AI slop in: $ARGUMENTS
 
 Then dispatch cx-engineer to apply the fixes.

package/commands/work/drive.md

@@ -1,12 +1,6 @@
-<!--
-commands/work/drive.md (Full autonomous execution) explore, plan, implement, verify, loop until done
-
-Full autonomous execution: explore, plan, implement, verify, loop until done
--->
 ---
 description: "Full autonomous execution: explore, plan, implement, verify, loop until done"
 ---
-
 You are Construct in drive mode. Execute $ARGUMENTS fully and autonomously without stopping for confirmation.
 
 ## Execution contract

package/commands/work/optimize-prompts.md

@@ -1,12 +1,6 @@
-<!--
-commands/work/optimize-prompts.md: Prompt optimization command.
-
-Runs the closed-loop prompt optimization workflow using telemetry trace data.
--->
 ---
 description: "Closed-loop prompt optimization: read telemetry traces, diagnose failures, push improved version to staging"
 ---
-
 You are cx-trace-reviewer running a prompt optimization cycle for: $ARGUMENTS
 
 If $ARGUMENTS is empty, optimize all agents with median quality score below 0.65 in the past 7 days.

package/commands/work/parallel-review.md

@@ -1,12 +1,6 @@
-<!--
-commands/work/parallel-review.md (Adversarial parallel review) 5 reviewers must agree before output ships
-
-Adversarial parallel review: 5 reviewers must agree before output ships
--->
 ---
 description: "Adversarial parallel review: 5 reviewers must agree before output ships"
 ---
-
 You are Construct running a parallel adversarial review of: $ARGUMENTS
 
 Dispatch the following 5 review roles concurrently:

package/lib/auto-docs.mjs

@@ -10,7 +10,8 @@
  * anything would change without writing files — the mode CI uses to detect drift.
  *
  * buildSite() is retained for compatibility; the public site now renders docs/
- * directly through Fumadocs and buildFumadocsReference() emits generated pages.
+ * directly through Next.js (apps/docs/) and buildFumadocsReference() emits
+ * generated reference Markdown into docs/reference/.
  */
 
 import fs from 'node:fs';
@@ -82,7 +83,7 @@ function buildCoreDocsContract() {
 
 const DIR_DESCRIPTIONS = {
   agents: 'Registry and generated platform adapter chains',
-  apps: 'User-facing apps shipped from this repo (e.g. apps/docs/, the Fumadocs docs site)',
+  apps: 'User-facing apps shipped from this repo (e.g. apps/docs/, the Next.js docs site)',
   bin: 'CLI entrypoint (`construct`)',
   claude: 'Claude Code integration (agents, settings template)',
   commands: 'Command prompt assets',
@@ -151,7 +152,7 @@ function buildHooksTable(rootDir) {
 }
 
 function buildAgentsTable(rootDir) {
-  const registryPath = path.join(rootDir, 'agents', 'registry.json');
+  const registryPath = path.join(rootDir, 'specialists', 'registry.json');
   let registry;
   try { registry = JSON.parse(fs.readFileSync(registryPath, 'utf8')); } catch { return ''; }
 
@@ -303,7 +304,7 @@ export function checkDocsCoverage({ rootDir } = {}) {
   return { covered, uncovered, total: covered.length + uncovered.length };
 }
 
-// Categories surfaced in the Fumadocs reference. Internal commands (e.g.,
+// Categories surfaced in the generated CLI reference. Internal commands (e.g.,
 // `construct hook <name>`) are not user-facing reference material.
 const REFERENCE_CATEGORIES = [
   'Core',
@@ -407,9 +408,12 @@ function renderAgentsPage(rootDir) {
 }
 
 /**
- * Emit MDX reference pages into docs/reference/ for the Fumadocs site.
- * Mirrors the data sources behind AUTO regions and buildSite() but writes
- * Markdown files Fumadocs can render directly (no MkDocs intermediate).
+ * Emit MDX reference pages into docs/reference/ for the Next.js docs site
+ * in apps/docs/. Mirrors the data sources behind AUTO regions and buildSite()
+ * but writes Markdown files the docs app can pull in directly (no MkDocs
+ * intermediate). Name kept for backwards compatibility with callers that
+ * still import buildFumadocsReference; the rendering layer is now plain
+ * Next.js + @next/mdx.
  */
 export function buildFumadocsReference({ rootDir } = {}) {
   rootDir = rootDir ?? process.cwd();

package/lib/beads-client.mjs

@@ -28,6 +28,21 @@ import {
   cleanupStaleQueue,
 } from './beads-lock.mjs';
 
+// Anchored bead-ID format. IDs reaching the bd shell boundary must match this;
+// regex-extracted IDs from PR bodies, agent transcripts, or intake packets get
+// re-validated here so a malformed value cannot reach the database. spawnSync
+// uses argv-array form so shell injection isn't the failure mode — log
+// corruption from a bogus ID is.
+
+const BEAD_ID_RE = /^[a-z]+-[a-z0-9]+$/;
+
+export function assertBeadId(id) {
+  if (typeof id !== 'string' || !BEAD_ID_RE.test(id)) {
+    throw new Error(`bd: invalid bead id ${JSON.stringify(id)} — expected prefix-suffix slug`);
+  }
+  return id;
+}
+
 import {
   concurrentRead,
   optimisticWrite,
@@ -253,7 +268,7 @@ async function runWithLegacyLock(args, opts, cwd, commandDesc) {
   if (!lock) {
     // Failed to get lock; add to queue if allowed
     const maxQueueWaitMs = opts.maxQueueWaitSeconds * 1000;
-    if (Date.now() - startWait + maxQueueWaitMs > maxQueueWaitMs) {
+    if (Date.now() - startWait > maxQueueWaitMs) {
       return {
         success: false,
         error: `Timeout waiting for lock after ${opts.timeoutSeconds}s`,
@@ -365,6 +380,7 @@ export async function listIssues(options = {}) {
  * Uses concurrent read (no locking needed).
  */
 export async function showIssue(id, options = {}) {
+  assertBeadId(id);
   return runBdJson(['show', id], { useOptimisticLocking: true, ...options });
 }
 
@@ -373,6 +389,7 @@ export async function showIssue(id, options = {}) {
  * Uses optimistic locking for better concurrency.
  */
 export async function claimIssue(id, options = {}) {
+  assertBeadId(id);
   // Use the specialized optimistic claim function
   const result = await claimBeadOptimistic(id, options);
   
@@ -388,6 +405,7 @@ export async function claimIssue(id, options = {}) {
  * Close an issue.
  */
 export async function closeIssue(id, options = {}) {
+  assertBeadId(id);
   return runBd(['close', id], options);
 }
 

package/lib/comment-lint.mjs

@@ -79,11 +79,15 @@ function requiresHeader(rel) {
 
 const JS_HEADER_RE = /^(?:#![^\n]*\n)?(?:\/\/[^\n]*\n)*\/\*\*[\s\S]*?\*\//;
 const MD_HEADER_RE = /^<!--[\s\S]*?-->/;
+const MD_YAML_HEADER_RE = /^---\n(?:[^\n]*\n)*?description:[\s\S]*?\n---/;
 const SH_HEADER_RE = /^#!.*\n(?:#[^\n]*\n)*/;
 
 function hasHeader(content, type) {
   if (type === 'js') return JS_HEADER_RE.test(content.trimStart());
-  if (type === 'md') return MD_HEADER_RE.test(content.trimStart());
+  if (type === 'md') {
+    const trimmed = content.trimStart();
+    return MD_HEADER_RE.test(trimmed) || MD_YAML_HEADER_RE.test(trimmed);
+  }
   return SH_HEADER_RE.test(content.trimStart());
 }
 

package/lib/context-state.mjs

@@ -1,8 +1,14 @@
 #!/usr/bin/env node
 /**
  * lib/context-state.mjs — compact project/session context persistence.
+ *
+ * Writes go through writeContextState, which uses write-to-tmp + atomic
+ * rename so concurrent writers from different hooks (pre-compact, Stop,
+ * context-window-recovery, tracking-surfaces) cannot leave a half-written
+ * JSON or markdown file behind. POSIX rename(2) is atomic for files on
+ * the same filesystem; the .cx directory always lives next to the target.
  */
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 
 export function contextJsonPath(rootDir) {
@@ -58,6 +64,12 @@ export function inspectContextState(rootDir) {
   };
 }
 
+function atomicWrite(targetPath, content) {
+  const tmpPath = `${targetPath}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmpPath, content, 'utf8');
+  renameSync(tmpPath, targetPath);
+}
+
 export function writeContextState(rootDir, state, { markdown = null } = {}) {
   const cxDir = join(rootDir, '.cx');
   mkdirSync(cxDir, { recursive: true });
@@ -67,10 +79,10 @@ export function writeContextState(rootDir, state, { markdown = null } = {}) {
     savedAt: new Date().toISOString(),
     ...state,
   };
-  writeFileSync(contextJsonPath(rootDir), `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+  atomicWrite(contextJsonPath(rootDir), `${JSON.stringify(payload, null, 2)}\n`);
 
   if (markdown !== null) {
-    writeFileSync(contextMarkdownPath(rootDir), markdown.endsWith('\n') ? markdown : `${markdown}\n`, 'utf8');
+    atomicWrite(contextMarkdownPath(rootDir), markdown.endsWith('\n') ? markdown : `${markdown}\n`);
   }
 
   return payload;

package/lib/contracts/validate.mjs

@@ -19,6 +19,8 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { POSTCONDITIONS, validateBinaryPostconditions } from '../specialists/postconditions.mjs';
+import { logViolation } from './violation-log.mjs';
 
 const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 const CONTRACTS_PATH = join(REPO_ROOT, 'specialists', 'contracts.json');
@@ -145,28 +147,62 @@ export function findContract({ producer, consumer, id, contractsPath = CONTRACTS
  *   { ok: true, contract }
  *   { ok: false, status: 'BLOCKED_CONTRACT', errors[], contract }
  *
- * Enforcement defaults to the value of process.env.CONSTRUCT_CONTRACT_ENFORCEMENT
- * ('warn' or 'block'), and may be overridden by the caller. In warn mode the
- * result includes errors but ok stays true so a session is not blocked.
+ * Enforcement defaults to `block` (CISA Secure-by-Design pledge —
+ * strong-default configurations). Callers can pass `enforcement: 'warn'`
+ * explicitly per-call when they genuinely need advisory mode.
+ *
+ * Binary postconditions are enforced when the producer has a rule table in
+ * `lib/specialists/postconditions.mjs`. The check is self-enforcing: if a
+ * producer has rules and the caller does not pass a `packet`, the call is
+ * itself a contract violation (MCP best-practice 2025 — no silent skip on
+ * tool-argument omission).
  */
 export function validateHandoff({
   producer,
   consumer,
   id,
   artifact,
+  packet,
   contractsPath = CONTRACTS_PATH,
   repoRoot = REPO_ROOT,
-  enforcement = process.env.CONSTRUCT_CONTRACT_ENFORCEMENT || 'warn',
+  enforcement = 'block',
 }) {
+  const errors = [];
+  const postconditionFailures = [];
+
+  // Binary postconditions are producer-bound invariants that fire regardless
+  // of whether the producer→consumer contract is registered in contracts.json.
+  // A producer with rules cannot have its packet validation skipped by
+  // claiming an unregistered consumer.
+  const hasBinaryRules = Array.isArray(POSTCONDITIONS[producer]) && POSTCONDITIONS[producer].length > 0;
+  if (hasBinaryRules) {
+    if (packet === undefined || packet === null) {
+      errors.push(`producer '${producer}' has binary postconditions; validateHandoff must be called with a packet argument`);
+    } else {
+      const binary = validateBinaryPostconditions(producer, packet);
+      for (const failure of binary.failures) {
+        errors.push(`[${failure.id}] ${failure.reason}`);
+        postconditionFailures.push(failure);
+      }
+    }
+  }
+
   const contract = findContract({ producer, consumer, id, contractsPath });
   if (!contract) {
+    if (errors.length > 0) {
+      logViolation(`${producer}->${consumer}`, 'output', errors, packet ?? artifact, {
+        verdict: postconditionFailures.length > 0 ? 'BLOCKED_CONTRACT' : 'CONTRACT_VIOLATION',
+        postconditionFailures,
+      });
+      return enforcement === 'block'
+        ? { ok: false, status: 'BLOCKED_CONTRACT', errors: [`no contract found for ${producer}→${consumer}${id ? ` id=${id}` : ''}`, ...errors], contract: null }
+        : { ok: true, warnings: [`no contract found for ${producer}→${consumer}`, ...errors], contract: null };
+    }
     return enforcement === 'block'
       ? { ok: false, status: 'BLOCKED_CONTRACT', errors: [`no contract found for ${producer}→${consumer}${id ? ` id=${id}` : ''}`], contract: null }
       : { ok: true, warnings: [`no contract found for ${producer}→${consumer}`], contract: null };
   }
 
-  const errors = [];
-
   // A handoff carries a producer's output, which is the consumer's input. The
   // input contract is what the consumer expects to receive; check mustContain
   // against that first. Output.schema validation only applies when the artifact
@@ -193,18 +229,26 @@ export function validateHandoff({
     }
   }
 
-  // Postcondition checks run against the artifact file on disk when the
-  // handoff envelope declares `artifactPath`. Resolved relative to repoRoot.
+  // Disk-artifact postconditions: frontmatter, sections, citations.
   const declaredArtifactPath = artifact?.artifactPath || artifact?.output?.artifactPath;
   if (declaredArtifactPath) {
     const absPath = isAbsolutePath(declaredArtifactPath)
       ? declaredArtifactPath
       : join(repoRoot, declaredArtifactPath);
-    const pcErrors = validatePostconditions({ contract, artifactPath: absPath });
+    const pcErrors = validateArtifactPostconditions({ contract, artifactPath: absPath });
     for (const e of pcErrors) errors.push(e);
   }
 
   if (errors.length === 0) return { ok: true, contract };
+
+  // Persist to the chain-hashed violation log so `construct doctor` and
+  // forensic replay see the failure. Best-effort; logging never throws.
+  const verdict = postconditionFailures.length > 0 ? 'BLOCKED_CONTRACT' : 'CONTRACT_VIOLATION';
+  logViolation(contract.id, 'output', errors, packet ?? artifact, {
+    verdict,
+    postconditionFailures,
+  });
+
   if (enforcement === 'block') return { ok: false, status: 'BLOCKED_CONTRACT', errors, contract };
   return { ok: true, warnings: errors, contract };
 }
@@ -272,7 +316,7 @@ function claimsHaveCitations(body) {
  * disk. Postconditions can be strings (descriptive, ignored here) or objects
  * with { id, check, field?, section? }. Returns an array of error strings.
  */
-export function validatePostconditions({ contract, artifactPath }) {
+export function validateArtifactPostconditions({ contract, artifactPath }) {
   if (!contract?.postconditions?.length) return [];
   if (!artifactPath || !existsSync(artifactPath)) {
     const structured = contract.postconditions.filter((p) => typeof p === 'object');

package/lib/contracts/violation-log.mjs

@@ -0,0 +1,154 @@
+/**
+ * lib/contracts/violation-log.mjs — tamper-evident append-only log for
+ * specialist-contract violations.
+ *
+ * Each record carries:
+ *   ts                  — ISO timestamp
+ *   sequence            — monotonic per-log counter, gap-detects truncation
+ *   prev_line_hash      — sha256 of the prior line, gap-detects modification
+ *   agent               — last-known active agent (from ~/.cx/last-agent.json)
+ *   contractId          — the contract that fired the violation
+ *   direction           — 'input' | 'output'
+ *   missing             — field names that failed shape validation
+ *   packet_keys         — Object.keys(packet) when packet is an object
+ *   verdict             — 'CONTRACT_VIOLATION' (default) or 'BLOCKED_CONTRACT'
+ *                         (binary postcondition failures)
+ *   postconditionFailures — [{id, reason}] when verdict is BLOCKED_CONTRACT
+ *
+ * The hash chain spans rotation: when the active file is empty (post-rotate),
+ * the tail is read from the most recent segment (gzipped or plain) via
+ * readLastLineAcrossSegments. The sequence counter follows the same path.
+ *
+ * Single owner of the file. All readers go through recentViolations or
+ * verifyChain; all writers go through logViolation.
+ */
+
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { appendBounded, readLastLineAcrossSegments } from '../logging/rotate.mjs';
+import { resolveProjectScopedPath } from '../project-root.mjs';
+
+const CX_DIR = join(homedir(), '.cx');
+const LAST_AGENT = join(CX_DIR, 'last-agent.json');
+
+// contract-violations are PROJECT-SCOPED: resolves to
+// <project>/.cx/contract-violations.jsonl when inside a project, falling
+// back to ~/.cx for standalone invocations. Resolved on every call so
+// cwd/HOME changes inside the same process (tests, harness reuse) route
+// correctly.
+
+function logFile() {
+  return resolveProjectScopedPath('contract-violations.jsonl', { ensureDir: false });
+}
+
+function sha256(input) { return createHash('sha256').update(input).digest('hex'); }
+
+function readLastAgent() {
+  try { return JSON.parse(readFileSync(LAST_AGENT, 'utf8'))?.agent || 'construct'; }
+  catch { return 'construct'; }
+}
+
+function readTailRecord() {
+  const file = logFile();
+  const lastLine = readLastLineAcrossSegments(file);
+  if (!lastLine) return null;
+  try { return JSON.parse(lastLine); }
+  catch { return null; }
+}
+
+function readPrevLineHash() {
+  const file = logFile();
+  const lastLine = readLastLineAcrossSegments(file);
+  return lastLine ? sha256(lastLine) : null;
+}
+
+function nextSequence() {
+  const tail = readTailRecord();
+  const prior = Number.isInteger(tail?.sequence) ? tail.sequence : 0;
+  return prior + 1;
+}
+
+/**
+ * Append a violation record. Best-effort: file I/O failures are swallowed
+ * so logging never crashes the caller.
+ */
+export function logViolation(contractId, direction, missing, packet, extra = {}) {
+  try {
+    const file = logFile();
+    mkdirSync(dirname(file), { recursive: true });
+    const record = {
+      ts: new Date().toISOString(),
+      sequence: nextSequence(),
+      agent: readLastAgent(),
+      contractId,
+      direction,
+      missing,
+      packet_keys: packet && typeof packet === 'object' ? Object.keys(packet) : null,
+      prev_line_hash: readPrevLineHash(),
+      ...extra,
+    };
+    appendBounded('contract-violations', file, JSON.stringify(record) + '\n');
+  } catch { /* logging is best-effort */ }
+}
+
+/**
+ * Read recent violations from the active log segment. Returns oldest-first.
+ * Rotated segments are intentionally not included — this is the doctor
+ * surface, scoped to the active window.
+ */
+export function recentViolations({ windowMs = 24 * 60 * 60 * 1000 } = {}) {
+  const file = logFile();
+  if (!existsSync(file)) return [];
+  try {
+    const cutoff = Date.now() - windowMs;
+    return readFileSync(file, 'utf8')
+      .trim()
+      .split('\n')
+      .filter(Boolean)
+      .map((line) => { try { return JSON.parse(line); } catch { return null; } })
+      .filter((r) => r && new Date(r.ts).getTime() >= cutoff);
+  } catch { return []; }
+}
+
+/**
+ * Walk the active log segment, asserting:
+ *   - each record's prev_line_hash matches sha256 of the prior line
+ *   - sequence numbers are monotonic with no gaps
+ *
+ * Returns { ok, brokenAt? } where brokenAt is { index, reason } on first
+ * failure. An empty / missing log is `{ ok: true }` (nothing to break).
+ */
+export function verifyChain() {
+  const file = logFile();
+  if (!existsSync(file)) return { ok: true };
+  try {
+    const lines = readFileSync(file, 'utf8').trim().split('\n').filter(Boolean);
+    let priorLine = null;
+    let priorSeq = null;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      let record;
+      try { record = JSON.parse(line); }
+      catch { return { ok: false, brokenAt: { index: i, reason: 'unparseable JSON' } }; }
+
+      if (priorLine !== null) {
+        const expectedHash = sha256(priorLine);
+        if (record.prev_line_hash !== expectedHash) {
+          return { ok: false, brokenAt: { index: i, reason: 'prev_line_hash mismatch' } };
+        }
+      }
+      if (Number.isInteger(record.sequence)) {
+        if (priorSeq !== null && record.sequence !== priorSeq + 1) {
+          return { ok: false, brokenAt: { index: i, reason: `sequence gap (expected ${priorSeq + 1}, got ${record.sequence})` } };
+        }
+        priorSeq = record.sequence;
+      }
+      priorLine = line;
+    }
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, brokenAt: { index: -1, reason: err.message } };
+  }
+}

package/lib/dashboard-static.mjs

@@ -1,8 +1,11 @@
 /**
  * lib/dashboard-static.mjs — build and sync the dashboard static bundle.
  *
- * Keeps `dashboard/dist/` and `lib/server/static/` aligned so the HTTP server
- * serves the current dashboard build from repo-owned assets.
+ * Keeps the Next.js static export at `apps/dashboard/out/` and the served
+ * tree at `lib/server/static/` aligned so the HTTP server picks up the
+ * current dashboard build without code changes. Pre-2.0 the dashboard
+ * lived at `dashboard/dist/`; the rebuild to Next.js (commit 84cd721)
+ * moved the source of truth into `apps/dashboard/out/`.
  */
 
 import fs from 'node:fs';
@@ -78,8 +81,8 @@ function removeEmptyDirs(dirPath, stopAt) {
 export function getDashboardPaths({ rootDir = process.cwd() } = {}) {
   return {
     rootDir,
-    dashboardDir: path.join(rootDir, 'dashboard'),
-    sourceDir: path.join(rootDir, 'dashboard', 'dist'),
+    dashboardDir: path.join(rootDir, 'apps', 'dashboard'),
+    sourceDir: path.join(rootDir, 'apps', 'dashboard', 'out'),
     targetDir: path.join(rootDir, 'lib', 'server', 'static'),
   };
 }