ruvnet-brain 4.0.1 → 4.0.2

package/plugin/skills/brain-console/SKILL.md

@@ -10,8 +10,10 @@ Treat `/rvbc`, `/rvcb`, `/brain-console`, and `/ruvnet-brain:configure` as equal
 Never correct the user's spelling.
 
 1. Say one short sentence: "Opening it now; it scans live while you watch."
-2. Locate `scripts/onboarding-console.mjs` from the current repository. If it is not present,
-   check `~/Code/ruvnet-brain/scripts/onboarding-console.mjs`. Do not invent another path.
+2. Resolve the installed runtime at
+   `${RUVNET_BRAIN_KB:-$HOME/.cache/ruvnet-brain/kb}/.console-runtime/scripts/onboarding-console.mjs`.
+   A current-repository `scripts/onboarding-console.mjs` is allowed only for an explicit developer
+   checkout. Never fall back to a guessed `~/Code` path.
 3. Run `node <resolved-script> --serve --open` in the background.
 4. Give the URL immediately. Do not promise a duration; the page reports its own scan progress.
 

package/plugin/skills/release-proof/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: release-proof
+description: Fail-closed exact-artifact release and deployment authority. Use before saying a release is ready, pushing a release commit, publishing npm packages, creating GitHub releases, deploying production, closing release-blocking issues, or claiming all gates are green. Requires clean immutable lineage, zero open issues, exact-SHA GitHub success, nonzero no-skip QE, packed-artifact host tests, installed Brain/RVF proof, independent graders, and post-publication byte verification.
+---
+
+# Release Proof
+
+Treat release as a two-seal transaction. Never publish from a source checkout merely because its
+tests pass. Never turn `UNKNOWN`, `SKIP`, `todo`, `0 tests`, dirty state, or an agent report into
+green.
+
+## Non-bypassable rules
+
+1. Use the exact source SHA and one packed-artifact SHA-256 everywhere.
+2. Require zero open GitHub issues for RuvNet Brain. A local fix is not a closed issue.
+3. Require every named GitHub workflow to complete successfully on the exact candidate SHA.
+4. Reject any test/QE result with zero tests, skips, todos, unknowns, pending jobs, or failures.
+5. Require two distinct independent graders scoring at least 95, each bound to the SHA and digest.
+6. Install the sealed artifact into virgin Claude Code and Codex homes; test their real entrypoints.
+7. Require the active Brain registry to contain the `ruvnet-brain` RVF store and require narrow,
+   broad, and concurrent cited searches to complete within 80% of their deadline.
+8. Publish only through the protected release workflow. Never run `npm publish` or `gh release
+   create` locally.
+9. After publication, download npm and GitHub artifacts, compare their bytes with the seal, install
+   both hosts again, query the active MCP again, and require `published-surface-probe` green.
+10. Close an issue only after posting its acceptance evidence. Never close from source inspection.
+
+## Candidate seal
+
+Generate the receipt from commands in the protected candidate workflow. Do not hand-author it.
+Validate it from the repository with:
+
+```bash
+node scripts/release-proof.mjs --candidate release-evidence/candidate-receipt.json
+```
+
+From an installed Claude plugin, run:
+
+```bash
+node "$CLAUDE_PLUGIN_ROOT/skills/release-proof/scripts/release-proof.mjs" \
+  --candidate release-evidence/candidate-receipt.json
+```
+
+Exit 0 is the only candidate seal. Read every failure code; repair the system, regenerate evidence,
+and rerun. Do not edit the receipt to remove a failure.
+
+## Publication seal
+
+After the protected publisher completes, validate both receipts:
+
+```bash
+node scripts/release-proof.mjs \
+  --candidate release-evidence/candidate-receipt.json \
+  --publication release-evidence/publication-receipt.json
+```
+
+Only exit 0 permits “shipped,” “deployed,” “green,” or “ready.” If publication occurred but this
+seal fails, say `PUBLICATION DEGRADED`, preserve the previous known-good release, and repair or
+roll back through the release workflow.
+
+## Evidence and issue handling
+
+For each issue:
+
+1. Reproduce the original symptom against the old/public artifact.
+2. Run its acceptance criteria against the sealed candidate.
+3. Disable or mutate the fix; the regression must fail.
+4. Post SHA, artifact digest, commands, results, and untested limits to the issue.
+5. Close only after the GitHub evidence is visible and exact-SHA required checks are green.
+
+Read [references/receipt-contract.md](references/receipt-contract.md) for receipt fields and failure
+semantics. Store the protocol and final release receipt in Ruflo/AgentDB only after the publication
+seal passes.
+
+## Status language
+
+- Candidate seal absent or failed: `NOT READY`.
+- Candidate sealed, not published: `SEALED, NOT SHIPPED`.
+- Published, publication seal pending: `PUBLISHED, NOT VERIFIED`.
+- Publication seal failed: `PUBLICATION DEGRADED`.
+- Both seals exit 0: `SHIPPED AND VERIFIED`.

package/plugin/skills/release-proof/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Release Proof"
+  short_description: "Fail-closed exact-artifact release authority"
+  default_prompt: "Prove this release candidate end to end and refuse publication unless every required gate is green."

package/plugin/skills/release-proof/references/receipt-contract.md

@@ -0,0 +1,38 @@
+# Receipt contract
+
+The authority accepts schema version 1 JSON. Receipts are append-only evidence artifacts generated
+by protected workflows, never editable status documents.
+
+## Candidate receipt
+
+Required bindings:
+
+- `sha`, `tree`, `dirty:false`
+- `artifact.path`, `artifact.sha256`, `artifact.sourceSha`
+- exact-SHA release-vector verdict with zero unknown/skipped
+- aggregate tests with nonzero total, all passed, zero failed/skipped/todo
+- fresh coverage floor and zero critical/high security findings
+- zero open GitHub issues
+- required GitHub workflow results on the same SHA
+- virgin-home Claude and Codex results on the same artifact digest
+- installed Brain self-RVF plus narrow, broad, and concurrent cited search timings
+- nonzero Agentic QE totals with zero failed/skipped
+- two distinct independent grader receipts at 95 or higher, bound to SHA and digest
+
+## Publication receipt
+
+Required bindings:
+
+- candidate SHA and artifact digest
+- npm and GitHub release bytes matching the candidate digest
+- clean installed Claude and Codex results from the public package
+- installed Brain self-RVF and broad search within 80 percent of deadline
+- successful exact-SHA `published-surface-probe`
+
+## Failure semantics
+
+Any missing field, malformed digest, mismatched SHA, dirty tree, open issue, absent/pending/red
+workflow, skipped/todo/zero-test result, missing RVF store, uncited search, deadline-margin breach,
+low/missing grader, or public byte mismatch is `FAIL`. There is no warning state and no score
+average. The authority never publishes; publication belongs to the protected workflow after the
+candidate seal.

package/plugin/skills/release-proof/scripts/release-proof.mjs

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+// Fail-closed release authority. It validates evidence bound to one clean source SHA and one
+// packed-artifact digest. It never publishes and never converts UNKNOWN/SKIP/zero work into PASS.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+export const REQUIRED_CHECKS = ['ci', 'integration-linux', 'stranger-matrix', 'ux-qe'];
+
+const fail = (code, detail) => ({ code, detail });
+const cleanHex = (value, length) => new RegExp(`^[a-f0-9]{${length}}$`, 'i').test(String(value || ''));
+const digestOf = (receipt) => String(receipt?.artifact?.sha256 || '').replace(/^sha256:/, '');
+
+export function evaluateCandidateReceipt(receipt) {
+  const failures = [];
+  const sha = String(receipt?.sha || '');
+  const digest = digestOf(receipt);
+
+  if (receipt?.schemaVersion !== 1 || receipt?.phase !== 'candidate') failures.push(fail('INVALID_RECEIPT', 'schemaVersion=1 and phase=candidate are required'));
+  if (!cleanHex(sha, 40) || !cleanHex(receipt?.tree, 40)) failures.push(fail('INVALID_LINEAGE', 'candidate SHA and tree must be full git object ids'));
+  if (receipt?.dirty !== false) failures.push(fail('DIRTY_WORKTREE', 'release candidates must come from a clean worktree'));
+  if (!cleanHex(digest, 64)) failures.push(fail('INVALID_ARTIFACT_DIGEST', 'artifact SHA-256 is missing or malformed'));
+  if (receipt?.artifact?.sourceSha !== sha) failures.push(fail('ARTIFACT_SOURCE_MISMATCH', 'packed artifact is not bound to the candidate SHA'));
+
+  const vector = receipt?.releaseVector || {};
+  if (vector.verdict !== 'PASS' || vector.sha !== sha || vector.unknown !== 0 || vector.skipped !== 0) {
+    failures.push(fail('RELEASE_VECTOR_NOT_PASS', 'release vector must PASS on the exact SHA with zero UNKNOWN/SKIP'));
+  }
+
+  const tests = receipt?.tests || {};
+  if (!(tests.total > 0)) failures.push(fail('ZERO_TESTS', 'a zero-test run is never evidence'));
+  if (tests.failed !== 0 || tests.skipped !== 0 || tests.todo !== 0 || tests.passed !== tests.total) {
+    failures.push(fail('TESTS_NOT_ALL_EXECUTED', 'all discovered tests must execute and pass; skipped/todo are release failures'));
+  }
+  const coverage = receipt?.coverage || {};
+  if (coverage.status !== 'PASS' || !(coverage.lines >= coverage.requiredLines)) failures.push(fail('COVERAGE_NOT_PASS', 'fresh exact-SHA coverage must meet the floor'));
+  const security = receipt?.security || {};
+  if (security.status !== 'PASS' || security.critical !== 0 || security.high !== 0) failures.push(fail('SECURITY_NOT_PASS', 'security must pass with zero critical/high findings'));
+
+  const openIssues = Array.isArray(receipt?.issues?.open) ? receipt.issues.open : null;
+  if (openIssues === null || openIssues.length > 0) failures.push(fail('OPEN_ISSUES', openIssues === null ? 'open-issue evidence missing' : `${openIssues.length} issue(s) remain open`));
+
+  if (receipt?.github?.sha !== sha) failures.push(fail('GITHUB_SHA_MISMATCH', 'GitHub evidence is not bound to candidate SHA'));
+  const checks = Array.isArray(receipt?.github?.checks) ? receipt.github.checks : [];
+  for (const name of REQUIRED_CHECKS) {
+    const matches = checks.filter((check) => check?.name === name);
+    if (matches.length === 0) failures.push(fail('REQUIRED_CHECK_MISSING', `${name} has no exact-SHA result`));
+    else if (!matches.some((check) => check.status === 'completed' && check.conclusion === 'success')) failures.push(fail('REQUIRED_CHECK_NOT_GREEN', `${name} is not completed/success`));
+  }
+
+  for (const hostName of ['claude', 'codex']) {
+    const host = receipt?.hosts?.[hostName];
+    if (host?.status !== 'PASS') failures.push(fail('HOST_NOT_PASS', `${hostName} clean-install acceptance did not pass`));
+    if (host?.artifactSha256 !== digest) failures.push(fail('HOST_ARTIFACT_MISMATCH', `${hostName} did not install the sealed artifact`));
+  }
+
+  const brain = receipt?.brain || {};
+  if (brain.status !== 'PASS') failures.push(fail('BRAIN_NOT_PASS', 'installed MCP search acceptance did not pass'));
+  if (brain.selfStore !== true) failures.push(fail('BRAIN_SELF_STORE_MISSING', 'active RVF registry does not contain ruvnet-brain'));
+  if (brain.citedSelfSource !== true) failures.push(fail('BRAIN_SELF_CITATION_MISSING', 'installed Brain did not cite its own source'));
+  const deadline = Number(brain.deadlineMs);
+  const observed = Math.max(Number(brain.narrowMs), Number(brain.broadMs), Number(brain.concurrentMs));
+  if (!(deadline > 0) || !Number.isFinite(observed) || observed > deadline * 0.8) failures.push(fail('BRAIN_DEADLINE_MARGIN', 'searches must finish within 80% of deadline'));
+
+  const qe = receipt?.qe || {};
+  if (!(qe.total > 0)) failures.push(fail('QE_ZERO_TESTS', 'Agentic QE executed zero tests'));
+  if (qe.status !== 'PASS' || qe.failed !== 0 || qe.skipped !== 0 || qe.passed !== qe.total) failures.push(fail('QE_NOT_PASS', 'Agentic QE must run a nonzero fleet with zero failed/skipped tests'));
+
+  const graders = Array.isArray(receipt?.graders) ? receipt.graders : [];
+  const independent = graders.filter((grader) => grader?.independent === true);
+  if (independent.length < 2 || new Set(independent.map((grader) => grader.id)).size < 2) failures.push(fail('INDEPENDENT_GRADERS', 'two distinct independent graders are required'));
+  for (const grader of independent) {
+    if (!(grader.score >= 95)) failures.push(fail('GRADER_BELOW_95', `${grader.id || 'grader'} scored ${grader.score ?? 'UNKNOWN'}`));
+    if (grader.sha !== sha || grader.artifactSha256 !== digest) failures.push(fail('GRADER_BINDING_MISMATCH', `${grader.id || 'grader'} is not bound to the seal`));
+  }
+
+  return { verdict: failures.length === 0 ? 'PASS' : 'FAIL', sha, artifactSha256: digest, failures };
+}
+
+export function evaluatePublicationReceipt(candidate, publication) {
+  const candidateResult = evaluateCandidateReceipt(candidate);
+  const failures = [...candidateResult.failures];
+  const sha = candidateResult.sha;
+  const digest = candidateResult.artifactSha256;
+  if (publication?.schemaVersion !== 1 || publication?.phase !== 'publication') failures.push(fail('INVALID_PUBLICATION_RECEIPT', 'schemaVersion=1 and phase=publication are required'));
+  if (publication?.sha !== sha || publication?.artifactSha256 !== digest) failures.push(fail('PUBLICATION_SEAL_MISMATCH', 'publication does not reference candidate seal'));
+  for (const surface of ['npm', 'githubRelease']) {
+    const item = publication?.[surface];
+    if (item?.sha !== sha || item?.artifactSha256 !== digest) failures.push(fail('PUBLIC_ARTIFACT_MISMATCH', `${surface} differs from candidate seal`));
+  }
+  for (const hostName of ['claude', 'codex']) {
+    const host = publication?.installed?.[hostName];
+    if (host?.status !== 'PASS' || host?.artifactSha256 !== digest) failures.push(fail('PUBLIC_HOST_NOT_PASS', `${hostName} is not running sealed public artifact`));
+  }
+  const brain = publication?.brain || {};
+  if (brain.status !== 'PASS' || brain.selfStore !== true || !(brain.broadMs <= Number(brain.deadlineMs) * 0.8)) failures.push(fail('PUBLIC_BRAIN_NOT_PASS', 'public installed Brain acceptance failed'));
+  const probes = Array.isArray(publication?.postPublicationChecks) ? publication.postPublicationChecks : [];
+  const probe = probes.find((check) => check?.name === 'published-surface-probe' && check?.sha === sha);
+  if (probe?.status !== 'completed' || probe?.conclusion !== 'success') failures.push(fail('POST_PUBLICATION_CHECK_NOT_GREEN', 'published-surface-probe is not green'));
+  return { verdict: failures.length === 0 ? 'PASS' : 'FAIL', sha, artifactSha256: digest, failures };
+}
+
+export function evaluateLivePreflight(observed) {
+  const failures = [];
+  if (observed?.dirty !== false) failures.push(fail('DIRTY_WORKTREE', 'local worktree is dirty'));
+  if (observed?.localSha !== observed?.remoteSha) failures.push(fail('REMOTE_SHA_MISMATCH', 'local HEAD is not origin/main'));
+  if (!Array.isArray(observed?.openIssues) || observed.openIssues.length > 0) failures.push(fail('OPEN_ISSUES', `${observed?.openIssues?.length ?? 'unknown'} issue(s) open`));
+  if (!Array.isArray(observed?.failedRuns) || observed.failedRuns.length > 0) failures.push(fail('GITHUB_FAILURES', `${observed?.failedRuns?.length ?? 'unknown'} recent failed run(s)`));
+  if (observed?.activeSelfStore !== true) failures.push(fail('BRAIN_SELF_STORE_MISSING', 'installed active registry lacks ruvnet-brain'));
+  if (observed?.branchEnforceAdmins !== true) failures.push(fail('ADMIN_BYPASS_ENABLED', 'main protection does not enforce required checks for admins'));
+  if (observed?.productionProtected !== true) failures.push(fail('PRODUCTION_ENV_UNPROTECTED', 'production environment has no required reviewer protection'));
+  if (observed?.releaseVector !== 'PASS') failures.push(fail('RELEASE_VECTOR_NOT_PASS', `release vector is ${observed?.releaseVector ?? 'UNKNOWN'}`));
+  return { verdict: failures.length === 0 ? 'PASS' : 'FAIL', observed, failures };
+}
+
+export function latestRunsByWorkflow(runs) {
+  const latest = new Map();
+  for (const run of Array.isArray(runs) ? runs : []) {
+    const prior = latest.get(run.workflowName);
+    if (!prior || Number(run.databaseId || 0) > Number(prior.databaseId || 0)) latest.set(run.workflowName, run);
+  }
+  return [...latest.values()];
+}
+
+function command(cmd, args, options = {}) {
+  const result = spawnSync(cmd, args, { encoding: 'utf8', ...options });
+  return {
+    status: result.status,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+    error: result.error,
+  };
+}
+
+function jsonCommand(cmd, args, options = {}) {
+  const result = command(cmd, args, options);
+  if (result.status !== 0) return null;
+  try { return JSON.parse(result.stdout); } catch { return null; }
+}
+
+export function collectLivePreflight({ root = process.cwd(), repo = 'stuinfla/ruvnet-brain', includeVector = true } = {}) {
+  const git = (args) => command('git', args, { cwd: root });
+  const localSha = git(['rev-parse', 'HEAD']).stdout.trim();
+  const dirty = Boolean(git(['status', '--porcelain']).stdout.trim());
+  git(['fetch', '--quiet', 'origin', 'main']);
+  const remoteSha = git(['rev-parse', 'origin/main']).stdout.trim();
+  const openIssues = jsonCommand('gh', ['issue', 'list', '--repo', repo, '--state', 'open', '--limit', '100', '--json', 'number,title,url']) ?? null;
+  const runs = jsonCommand('gh', ['run', 'list', '--repo', repo, '--limit', '50', '--json', 'databaseId,workflowName,headSha,status,conclusion,url']) ?? null;
+  const failedRuns = Array.isArray(runs)
+    ? latestRunsByWorkflow(runs.filter((run) => run.headSha === remoteSha))
+      .filter((run) => run.status !== 'completed' || run.conclusion !== 'success')
+    : null;
+  const protection = jsonCommand('gh', ['api', `repos/${repo}/branches/main/protection`]);
+  const environments = jsonCommand('gh', ['api', `repos/${repo}/environments`]);
+  const production = environments?.environments?.find((environment) => environment.name === 'Production – ruvnet-brain');
+  let activeSelfStore = false;
+  try {
+    const source = JSON.parse(fs.readFileSync(path.join(process.env.HOME || '', '.cache/ruvnet-brain/kb/SOURCE.json'), 'utf8'));
+    const stores = source.sources || source.repos || {};
+    activeSelfStore = Boolean(stores['ruvnet-brain']);
+  } catch {}
+  let releaseVector = 'UNKNOWN';
+  if (includeVector) {
+    const vector = jsonCommand(process.execPath, [path.join(root, 'scripts/release-vector.mjs'), '--json'], { cwd: root });
+    releaseVector = vector?.verdict || 'UNKNOWN';
+  }
+  return {
+    localSha,
+    remoteSha,
+    dirty,
+    openIssues,
+    failedRuns,
+    activeSelfStore,
+    branchEnforceAdmins: protection?.enforce_admins?.enabled === true,
+    productionProtected: Array.isArray(production?.protection_rules) && production.protection_rules.length > 0 && production.can_admins_bypass === false,
+    releaseVector,
+  };
+}
+
+const readJson = (file) => JSON.parse(fs.readFileSync(path.resolve(file), 'utf8'));
+const argument = (args, flag) => {
+  const index = args.indexOf(flag);
+  return index >= 0 ? args[index + 1] : null;
+};
+
+export function main(args = process.argv.slice(2)) {
+  if (args.includes('--status')) {
+    const result = evaluateLivePreflight(collectLivePreflight({ includeVector: !args.includes('--quick') }));
+    console.log(JSON.stringify(result, null, 2));
+    return result.verdict === 'PASS' ? 0 : 1;
+  }
+  const candidatePath = argument(args, '--candidate');
+  const publicationPath = argument(args, '--publication');
+  if (!candidatePath) {
+    console.error('Usage: release-proof.mjs --candidate <candidate-receipt.json> [--publication <publication-receipt.json>]');
+    return 2;
+  }
+  try {
+    const candidate = readJson(candidatePath);
+    const result = publicationPath ? evaluatePublicationReceipt(candidate, readJson(publicationPath)) : evaluateCandidateReceipt(candidate);
+    console.log(JSON.stringify(result, null, 2));
+    return result.verdict === 'PASS' ? 0 : 1;
+  } catch (error) {
+    console.error(`release-proof: ${error.message}`);
+    return 2;
+  }
+}
+
+if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url) process.exitCode = main();

package/plugin/skills/ruvnet-brain/PLAYBOOK.md

@@ -1,6 +1,6 @@
 # THE PLAYBOOK — the standing build playbook, in full
 
-Updated: 2026-07-27 | Version 1.0.0
+Updated: 2026-07-30 | Version 1.0.1
 Created: 2026-07-27
 
 **Read this before your first build response in a session.** `plugin/scripts/session-start.sh`
@@ -41,6 +41,10 @@ the exact lie that makes people distrust rUv's code.
   token exchange", not "does RuvNet apply") — the useful hit can be in ANY of the 32 repos, never
   trust memory about what the corpus does or doesn't have.
 - Check project memory (ruflo memory search / AgentDB) for prior decisions on this area.
+- Diagnose memory only through one canonical absolute path: store a unique key with
+  `ruflo memory store --path <project>/.swarm/memory.db`, retrieve that exact key with the same
+  `--path`, then confirm the exact row through SQLite. A semantic-search miss, DB/WAL mtime,
+  daemon startup, or `[OK] Data stored successfully` alone proves neither failure nor success.
 - Invoke Ruflo MCP tools first for capabilities they already expose. For a CLI-only interface,
   use the brain's `ruvnet_cli_help` then `ruvnet_cli_run` tools with literal argv; never guess flags
   by reconstructing a raw shell command.

package/plugin/skills/rvbc/SKILL.md

@@ -1,17 +1,20 @@
 ---
 name: rvbc
-description: Open the RuvNet Brain Console in Codex when the user mentions "rvbc", asks for the Brain Console, or wants to configure or inspect RuvNet Brain. This is the native Codex alias for the Claude-only /rvbc command.
-updated: 2026-07-29
+description: Open the RuvNet Brain Console in Claude Code and Codex when the user says "Configure RuvNet Brain", mentions "rvbc", asks for the Brain Console, or wants to configure or inspect RuvNet Brain. Claude Code supports /rvbc; Codex invokes the native $ruvnet-brain:rvbc skill.
+updated: 2026-07-30
 ---
 
 # RuvNet Brain Console
 
-Codex invokes this skill as `$ruvnet-brain:rvbc`; custom plugin slash commands are not part of the
-Codex CLI slash-command surface.
+“Configure RuvNet Brain” opens this Console in Claude Code and Codex. Claude Code also supports
+`/rvbc`; Codex invokes this skill as `$ruvnet-brain:rvbc` because custom plugin slash commands are
+not part of the Codex CLI slash-command surface.
 
 1. Say one short sentence: "Opening it now; it scans live while you watch."
-2. Locate `scripts/onboarding-console.mjs` from the current repository. If it is not present,
-   check `~/Code/ruvnet-brain/scripts/onboarding-console.mjs`. Do not invent another path.
+2. Resolve the installed runtime at
+   `${RUVNET_BRAIN_KB:-$HOME/.cache/ruvnet-brain/kb}/.console-runtime/scripts/onboarding-console.mjs`.
+   A current-repository `scripts/onboarding-console.mjs` is allowed only for an explicit developer
+   checkout. Never fall back to a guessed `~/Code` path.
 3. Run `node <resolved-script> --serve --open` in the background.
 4. Give the URL immediately. Do not promise a duration; the page reports its own scan progress.
 

package/scripts/adr-backfill.mjs

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * adr-backfill.mjs — lift status and dates into frontmatter where tooling can read them.
+ *
+ * THE GAP, measured 2026-07-22: 12 of 32 ADRs carried NO frontmatter status and NO dates, and 9
+ * more had a creation date but no `updated`. The owner's requirement is exact: *"One thing I ALWAYS
+ * want you to do is indicate in an ADR what the status is... they should have a time and date
+ * stamped on when they were initially written and a time and date stamped on the last time they
+ * were updated and why. That way I know I'm never looking at out-of-date documents."*
+ *
+ * NOTHING HERE IS INVENTED, and that constraint is the whole design:
+ *
+ *   status   LIFTED from the document's own body. All 12 already say `**Status**: Accepted (date)`
+ *            — the information was never missing, it just sat where no tool could read it. A status
+ *            is a judgement; deriving one from git would be fabrication, so a document that does
+ *            not state its own status is REPORTED and skipped, never guessed at.
+ *   date     LIFTED from the body's `**Date**:`, falling back to git's first-commit date.
+ *   updated  DERIVED from `git log -1` — the last commit that actually touched the file. A typed
+ *            date can be wrong; a git object cannot.
+ *
+ * Every written value is therefore traceable to either the document itself or the repository's
+ * history. This matters because a fabricated timestamp is worse than a missing one: a missing
+ * stamp is visibly unknown, while a wrong stamp is confidently misleading — the exact failure mode
+ * this project has paid for repeatedly.
+ *
+ *   node scripts/adr-backfill.mjs           report what WOULD change (default; writes nothing)
+ *   node scripts/adr-backfill.mjs --apply   write it
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+const REPO = path.resolve(import.meta.dirname, '..');
+const ADR_DIR = path.join(REPO, 'docs', 'adr');
+const apply = process.argv.includes('--apply');
+
+const git = (args) => {
+  try { return execFileSync('git', args, { cwd: REPO, encoding: 'utf8' }).trim(); }
+  catch { return ''; }
+};
+
+/** First-commit date — the honest "created", when the body does not state one. */
+const gitCreated = (rel) =>
+  (git(['log', '--follow', '--diff-filter=A', '--format=%ad', '--date=short', '--', rel]).split('\n').filter(Boolean).pop() || '');
+
+/** Last commit that touched the file — the honest "updated". */
+const gitUpdated = (rel) => git(['log', '-1', '--format=%ad', '--date=short', '--', rel]);
+
+const VALID = ['Proposed', 'Accepted', 'Implemented', 'Superseded', 'Deprecated'];
+
+function parseBody(src) {
+  // `**Status**: Accepted (2026-06-27)` → Accepted, 2026-06-27
+  const sm = src.match(/^\*\*Status\*\*:\s*([A-Za-z]+)(?:\s*\((\d{4}-\d{2}-\d{2})\))?/m);
+  const dm = src.match(/^\*\*Date\*\*:\s*(\d{4}-\d{2}-\d{2})/m);
+  const status = sm && VALID.find((v) => v.toLowerCase() === sm[1].toLowerCase());
+  return { status: status || null, statusDate: sm?.[2] || null, date: dm?.[1] || null };
+}
+
+function frontmatter(src) {
+  const lines = src.split('\n');
+  if (lines[0]?.trim() !== '---') return null;
+  const end = lines.findIndex((l, i) => i > 0 && l.trim() === '---');
+  if (end < 0) return null;
+  const keys = {};
+  for (let i = 1; i < end; i++) {
+    const m = lines[i].match(/^(\w+):\s*(.*)$/);
+    if (m) keys[m[1]] = m[2];
+  }
+  return { keys, end, lines };
+}
+
+const results = [];
+for (const f of fs.readdirSync(ADR_DIR).filter((n) => /^\d{4}-.*\.md$/.test(n)).sort()) {
+  const rel = path.join('docs', 'adr', f);
+  const abs = path.join(ADR_DIR, f);
+  const src = fs.readFileSync(abs, 'utf8');
+  const fm = frontmatter(src);
+  if (!fm) { results.push({ f, skip: 'no frontmatter block to extend' }); continue; }
+
+  const body = parseBody(src);
+  const need = {};
+  if (!fm.keys.status && body.status) need.status = body.status;
+  if (!fm.keys.date) { const d = body.date || body.statusDate || gitCreated(rel); if (d) need.date = d; }
+  if (!fm.keys.updated) { const u = gitUpdated(rel); if (u) need.updated = u; }
+
+  if (!fm.keys.status && !body.status) {
+    // A status is a judgement. Refuse to guess; report it so a human can decide.
+    results.push({ f, skip: 'no status stated anywhere — a human must set this, it cannot be derived' });
+    continue;
+  }
+  if (!Object.keys(need).length) { results.push({ f, ok: true }); continue; }
+
+  if (apply) {
+    const insert = Object.entries(need).map(([k, v]) => `${k}: ${v}`);
+    const out = [...fm.lines.slice(0, fm.end), ...insert, ...fm.lines.slice(fm.end)];
+    fs.writeFileSync(abs, out.join('\n'));
+  }
+  results.push({ f, need });
+}
+
+const changed = results.filter((r) => r.need);
+const skipped = results.filter((r) => r.skip);
+console.log(`\n  ${results.length} ADR(s) · ${changed.length} ${apply ? 'updated' : 'would change'} · ${skipped.length} skipped · ${results.filter((r) => r.ok).length} already complete\n`);
+for (const r of changed) console.log(`    ${apply ? '✓' : '·'} ${r.f}  +${Object.entries(r.need).map(([k, v]) => `${k}=${v}`).join(' +')}`);
+for (const r of skipped) console.log(`    ⚠ ${r.f}  — ${r.skip}`);
+if (!apply && changed.length) console.log(`\n  Nothing written. Re-run with --apply.\n`);
+else console.log('');