@1agh/maude 0.49.2 → 0.51.0

package/cli/commands/hub-workspace.mjs

@@ -13,7 +13,7 @@
 // It does NOT claim to own the deployment afterwards — see `operatorDuties`.
 
 import { spawn } from 'node:child_process';
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 
@@ -26,6 +26,7 @@ import {
   renderEnv,
   validateWorkspaceConfig,
   verificationPlan,
+  workspaceBaseUrl,
 } from '../lib/workspace-plan.mjs';
 
 export function usage() {
@@ -45,6 +46,13 @@ export function usage() {
   --s3-secret-access-key SECRET
   --s3-region REGION       default "auto"
   --dev-minio              run a local MinIO under the compose 'dev' profile
+  --local                  TESTING: serve plain HTTP on localhost, no
+                           certificate, no ACME. --domain defaults to
+                           "localhost" and must stay a loopback NAME.
+                           Lets you exercise the whole stack — and every
+                           verification step — on a laptop, with no domain and
+                           no paid account. Never serve a real workspace this
+                           way: sign-in passwords would travel in the clear.
   --seed-repo URL          clone an existing project; omit to start fresh
   --image-tag TAG          default "latest" — pin it before you rely on this
   --config FILE            read all of the above from a JSON file
@@ -63,7 +71,9 @@ export function usage() {
 }
 
 export async function run({ args, pkgRoot }) {
-  const { flags } = parseArgs(args, { booleans: ['dry-run', 'json', 'dev-minio'] });
+  const { flags } = parseArgs(args, {
+    booleans: ['help', 'dry-run', 'json', 'dev-minio', 'local'],
+  });
   if (flags.help) {
     process.stdout.write(usage());
     return;
@@ -79,6 +89,7 @@ export async function run({ args, pkgRoot }) {
       ? { adminPassword: flags['admin-password'] ?? raw.adminPassword }
       : {}),
     devMinio: flags['dev-minio'] === true || raw.devMinio === true,
+    local: flags.local === true || raw.local === true,
     seedRepo: flags['seed-repo'] ?? raw.seedRepo,
     imageTag: flags['image-tag'] ?? raw.imageTag,
     ...(flags['s3-endpoint'] || raw.s3
@@ -169,12 +180,27 @@ export async function run({ args, pkgRoot }) {
 
   process.stdout.write(`Wrote ${files.map((f) => f.name).join(', ')} to ${outDir}\n`);
   process.stdout.write('Starting the stack…\n');
-  const up = await sh('docker', ['compose', 'up', '-d'], { cwd: outDir });
+  // `--dev-minio` renders MinIO behind the `dev` compose profile, and a profile
+  // service does NOT start on a plain `compose up`. Rendering the bucket into
+  // the hub's config while never starting the bucket is the shape of failure
+  // that reports "storage configured" and then cannot store anything.
+  const composeArgs = config.s3?.dev
+    ? ['compose', '--profile', 'dev', 'up', '-d']
+    : ['compose', 'up', '-d'];
+  const up = await sh('docker', composeArgs, { cwd: outDir });
   if (up.code !== 0) {
     process.stderr.write(`docker compose up failed:\n${up.stderr}\n`);
     process.exit(1);
   }
 
+  // `compose up -d` returns when the containers are STARTED, not when they are
+  // SERVING. Verifying immediately reported "the workspace answers — ✗
+  // unreachable" against a stack that was healthy three seconds later: a false
+  // failure, which corrodes trust in the suite exactly as fast as a false pass.
+  // Bounded, and it gives up rather than waiting forever — a stack that never
+  // comes up must still be reported.
+  await waitForHealth(workspaceBaseUrl(config));
+
   // Verification is the deliverable. A URL printed without a proven round-trip
   // tells the operator something this command does not know.
   process.stdout.write('\nVerifying — this is the part that matters:\n');
@@ -202,7 +228,7 @@ export async function run({ args, pkgRoot }) {
     printDuties(duties);
     process.stdout.write(
       failed === 0
-        ? `\nWorkspace verified: https://${config.domain}\n`
+        ? `\nWorkspace verified: ${workspaceBaseUrl(config)}\n`
         : `\n${failed} check(s) did NOT pass. The stack is running but is not proven — fix and re-run.\n`
     );
   }
@@ -260,6 +286,29 @@ function sh(cmd, args, opts = {}) {
   });
 }
 
+/**
+ * Poll `/health` until the stack is serving, or give up.
+ *
+ * Deliberately silent on success and NEVER fatal: if the wait expires, the
+ * verification steps run anyway and report the real failure. This function
+ * removes a timing artefact; it must not become a second place that decides
+ * whether the deployment is good.
+ */
+async function waitForHealth(base, { timeoutMs = 45_000, intervalMs = 1_000 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  let announced = false;
+  while (Date.now() < deadline) {
+    const res = await tryFetch(`${base}/health`);
+    if (res.ok) return true;
+    if (!announced) {
+      process.stdout.write('Waiting for the stack to answer…\n');
+      announced = true;
+    }
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  return false;
+}
+
 async function which(bin) {
   const res = await sh(process.platform === 'win32' ? 'where' : 'which', [bin]);
   return res.code === 0;
@@ -272,8 +321,8 @@ async function which(bin) {
  * NEVER reports success. Counting an unrun check as passed is the single
  * fastest way to make a verification suite worthless.
  */
-async function runVerification(step, { config, hubSecret }) {
-  const base = `https://${config.domain}`;
+async function runVerification(step, { config, hubSecret, adminPassword, outDir, pkgRoot }) {
+  const base = workspaceBaseUrl(config);
   switch (step.id) {
     case 'health': {
       const res = await tryFetch(`${base}/health`);
@@ -285,6 +334,16 @@ async function runVerification(step, { config, hubSecret }) {
       });
       return res.ok ? { ok: true } : { ok: false, note: res.note };
     }
+    case 'user-signin':
+      return verifySignin(base, config.adminEmail, adminPassword);
+    case 'git-commit':
+      return verifyGitHistory(outDir);
+    case 's3-object':
+      return verifyBucketRoundTrip(config, pkgRoot);
+    case 's3-no-expiry':
+      return verifyNoLifecycle(config, pkgRoot);
+    case 'restore-drill':
+      return verifyRestoreDrill(config);
     default:
       return {
         ok: false,
@@ -294,6 +353,234 @@ async function runVerification(step, { config, hubSecret }) {
   }
 }
 
+/**
+ * The credential the operator is about to be handed actually works.
+ *
+ * This is the check that would have caught the shipped bug where a provisioned
+ * workspace had no users at all: every other check passed, the URL printed,
+ * and the first person to try the login was the one who found out.
+ */
+async function verifySignin(base, email, password) {
+  if (!password) return { ok: false, note: 'no admin password was generated' };
+  try {
+    const res = await fetch(`${base}/auth/login`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email, password }),
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) return { ok: false, note: `HTTP ${res.status} — the first user cannot sign in` };
+    const body = await res.json().catch(() => null);
+    return body?.token ? { ok: true } : { ok: false, note: 'login returned no session token' };
+  } catch (err) {
+    return { ok: false, note: err.name === 'TimeoutError' ? 'timed out' : 'unreachable' };
+  }
+}
+
+/**
+ * The server-side checkout has real commits (Cloud Phase 16).
+ *
+ * Read from INSIDE the container, because that is where the history lives.
+ * Checking a path on the operator's laptop would pass on a machine that
+ * happens to have a repo and tell us nothing about the deployment.
+ */
+async function verifyGitHistory(outDir) {
+  const probe = await sh(
+    'docker',
+    ['compose', 'exec', '-T', 'hub', 'git', '-C', '/repo', 'log', '-1', '--format=%H %an'],
+    { cwd: outDir }
+  );
+  if (probe.code !== 0) {
+    const err = `${probe.stderr}`.toLowerCase();
+    // A fresh workspace has no commits because nobody has edited anything yet.
+    // That is the NORMAL state five seconds after provisioning, and reporting
+    // it as a failure trains the operator to ignore a red mark — which is
+    // precisely what makes a real one invisible later. Skipped says the truth:
+    // this was not proven, and here is what would prove it.
+    if (err.includes('does not have any commits') || err.includes('bad default revision')) {
+      return {
+        ok: false,
+        skipped: true,
+        note: 'the checkout is ready but empty — edit a canvas, then re-run to prove autosave commits',
+      };
+    }
+    if (err.includes('not a git repository')) {
+      return {
+        ok: false,
+        note: 'the workspace has no checkout — server-side history is not running',
+      };
+    }
+    if (err.includes('executable file not found') || err.includes('not found')) {
+      return { ok: false, note: 'git is missing from the hub image — history cannot be kept' };
+    }
+    return { ok: false, note: `git log failed: ${probe.stderr.trim().slice(0, 120)}` };
+  }
+  const line = probe.stdout.trim();
+  if (!line) {
+    return {
+      ok: false,
+      skipped: true,
+      note: 'the checkout is ready but empty — edit a canvas, then re-run',
+    };
+  }
+  return { ok: true, note: `HEAD by ${line.split(' ').slice(1).join(' ') || 'unknown'}` };
+}
+
+/** Load the hub's S3 client from the installed package. */
+async function loadS3(pkgRoot) {
+  for (const candidate of [
+    resolve(pkgRoot, 'apps/hub/src/s3.mjs'),
+    resolve(pkgRoot, '../apps/hub/src/s3.mjs'),
+  ]) {
+    const mod = await import(`file://${candidate}`).catch(() => null);
+    if (mod) return mod;
+  }
+  return null;
+}
+
+function s3ConfigFrom(config) {
+  const s = config.s3;
+  // The dev MinIO endpoint (`http://minio:9000`) is a compose-network name.
+  // These checks run on the OPERATOR's machine, which cannot resolve it — but
+  // the compose file publishes the port, so loopback is the same bucket.
+  const endpoint = s.dev ? s.endpoint.replace('//minio:', '//127.0.0.1:') : s.endpoint;
+  return {
+    endpoint,
+    bucket: s.bucket,
+    accessKeyId: s.accessKeyId,
+    secretAccessKey: s.secretAccessKey,
+    region: s.region ?? 'auto',
+  };
+}
+
+/**
+ * A real object goes into the bucket and comes back out.
+ *
+ * Content-addressed, so the sentinel is indistinguishable from a genuine
+ * asset — and it is removed afterwards, because a verification step that
+ * litters a customer's bucket is a verification step people turn off.
+ */
+async function verifyBucketRoundTrip(config, pkgRoot) {
+  if (!config.s3) return { ok: false, skipped: true, note: 'no object storage configured' };
+  const s3 = await loadS3(pkgRoot);
+  if (!s3)
+    return { ok: false, skipped: true, note: 'the hub S3 client was not found in this install' };
+  const cfg = s3ConfigFrom(config);
+  const bytes = Buffer.from(`maude workspace-up sentinel\n`);
+  const key = `assets/${createHash('sha256').update(bytes).digest('hex').slice(0, 8)}.bin`;
+  try {
+    // The stack was declared healthy by the HUB's health check; object storage
+    // is a different container and may still be starting. A one-shot attempt
+    // here reported "fetch failed" against a MinIO that was serving four
+    // seconds later — a false failure, which corrodes the suite as fast as a
+    // false pass.
+    await retry(() => s3.putObject(cfg, key, bytes), { attempts: 6, delayMs: 2000 });
+    const head = await s3.headObject(cfg, key);
+    if (!head) return { ok: false, note: 'the object was written but could not be read back' };
+    if (head.size !== bytes.length) {
+      return { ok: false, note: `read back ${head.size} bytes, wrote ${bytes.length}` };
+    }
+    return { ok: true };
+  } catch (err) {
+    if (/NoSuchBucket/i.test(err.message)) {
+      return {
+        ok: false,
+        note: `the bucket "${cfg.bucket}" does not exist at ${cfg.endpoint} — create it, then re-run`,
+      };
+    }
+    if (/InvalidAccessKeyId|SignatureDoesNotMatch/i.test(err.message)) {
+      return { ok: false, note: 'object storage rejected the credentials' };
+    }
+    return { ok: false, note: `bucket rejected the round trip: ${err.message.slice(0, 120)}` };
+  } finally {
+    await s3.deleteObject(s3ConfigFrom(config), key).catch(() => {});
+  }
+}
+
+/**
+ * No lifecycle rule can expire the media.
+ *
+ * The quiet catastrophe this guards: assets are content-addressed and
+ * referenced from git history forever, so an expiry rule deletes objects that
+ * canvases still point at, with no recovery path and no error at the time.
+ *
+ * A bucket with NO lifecycle configuration answers 404 — that is the pass.
+ */
+async function verifyNoLifecycle(config, pkgRoot) {
+  if (!config.s3) return { ok: false, skipped: true, note: 'no object storage configured' };
+  const s3 = await loadS3(pkgRoot);
+  if (!s3?.signRequest) {
+    return { ok: false, skipped: true, note: 'the hub S3 client was not found in this install' };
+  }
+  const cfg = s3ConfigFrom(config);
+  try {
+    const signed = s3.signRequest(cfg, { method: 'GET', key: '', query: { lifecycle: '' } });
+    const res = await fetch(signed.url, {
+      method: 'GET',
+      headers: signed.headers,
+      signal: AbortSignal.timeout(15_000),
+    });
+    if (res.status === 404) return { ok: true, note: 'no lifecycle configuration' };
+    if (!res.ok) {
+      // Cannot read the config ⇒ cannot claim it is safe. Skipped, never passed.
+      return {
+        ok: false,
+        skipped: true,
+        note: `could not read lifecycle config (HTTP ${res.status})`,
+      };
+    }
+    const xml = await res.text();
+    const rules = xml.match(/<Rule>/g)?.length ?? 0;
+    if (rules === 0) return { ok: true, note: 'no lifecycle rules' };
+    // Any rule at all is reported. Deciding which prefixes a rule matches from
+    // its XML is exactly the kind of parsing that is wrong in the one case
+    // that matters, so this reports rather than adjudicates.
+    return {
+      ok: false,
+      note: `${rules} lifecycle rule(s) on this bucket — confirm none can expire assets/`,
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      skipped: true,
+      note: `lifecycle check failed: ${err.message.slice(0, 100)}`,
+    };
+  }
+}
+
+/** A backup nobody has restored is a hypothesis. Runs the real drill. */
+async function verifyRestoreDrill(config) {
+  if (!config.s3) return { ok: false, skipped: true, note: 'no backup target configured' };
+  // The drill needs the hub's own data dir, which lives inside the container.
+  // Deliberately left to the operator's `maude hub restore-drill` rather than
+  // reaching into a volume from out here: a half-run drill that reports
+  // success is worse than an honest skip, and this is the one check whose
+  // whole point is that somebody actually did it.
+  return {
+    ok: false,
+    skipped: true,
+    note: 'run `maude hub restore-drill` against this deployment — it needs the hub data dir',
+  };
+}
+
+/** Retry a flaky-at-startup operation. Rethrows the LAST error, so the
+ *  reported cause is the real one rather than "timed out". */
+async function retry(fn, { attempts, delayMs }) {
+  let last;
+  for (let i = 0; i < attempts; i++) {
+    try {
+      return await fn();
+    } catch (err) {
+      last = err;
+      // A definitive answer from the service is not worth retrying — only the
+      // "not listening yet" shape is.
+      if (!/fetch failed|ECONNREFUSED|socket hang up/i.test(err.message)) throw err;
+      if (i < attempts - 1) await new Promise((r) => setTimeout(r, delayMs));
+    }
+  }
+  throw last;
+}
+
 async function tryFetch(url, init) {
   try {
     const ctrl = new AbortController();
@@ -312,7 +599,7 @@ async function tryFetch(url, init) {
 function printDryRun({ config, outDir, files, plan, duties, reusedSecret }) {
   process.stdout.write(
     `maude hub workspace-up — DRY RUN, nothing was written\n\n` +
-      `  workspace   https://${config.domain}\n` +
+      `  workspace   ${workspaceBaseUrl(config)}${config.local ? '  (LOCAL — plain HTTP)' : ''}\n` +
       `  first user  ${config.adminEmail}\n` +
       `  storage     ${config.s3 ? `${config.s3.bucket} @ ${config.s3.endpoint}${config.s3.dev ? ' (dev MinIO)' : ''}` : 'none — media stays in git'}\n` +
       `  project     ${config.seedRepo ?? 'starts fresh'}\n` +

package/cli/commands/init.mjs

@@ -195,7 +195,7 @@ export async function run({ args, pkgRoot }) {
   }
 
   printSummary(result);
-  printNextSteps(projectName, claudeMdExists);
+  printNextSteps(projectName, claudeMdExists, Boolean(resolveKgBin()), Boolean(flags.kg));
 }
 
 /** KGAI_BIN (desktop-staged sidecar) → `kg` on PATH → null. Mirrors kg.mjs. */
@@ -242,7 +242,7 @@ function printSummary({ created, replaced, skipped }) {
   }
 }
 
-function printNextSteps(name, claudeMdExists) {
+function printNextSteps(name, claudeMdExists, kgAvailable = false, usedKg = false) {
   process.stdout.write('\nNext steps:\n');
   process.stdout.write('  1. In Claude Code: /plugin marketplace add 1aGh/maude\n');
   process.stdout.write('                     /plugin install flow@maude\n');
@@ -261,4 +261,35 @@ function printNextSteps(name, claudeMdExists) {
   }
   process.stdout.write(`  4. Create .ai/${name}-prd.md with your product brief.\n`);
   process.stdout.write('  5. /flow:status to see where you are; /flow:plan to start work.\n');
+  printKgOffer(kgAvailable, usedKg);
+}
+
+/**
+ * Surface the knowledge-graph choice at scaffold time.
+ *
+ * Without this, `--kg` is discoverable only by reading `--help` — so a fresh
+ * user never learns the option exists at the one moment it is cheapest to take
+ * (an empty `.ai/` needs no migration). Deliberately NOT shown when `kg` is
+ * absent: advertising a backend the user would first have to go install is
+ * noise, and `mode:auto` picks it up by itself if they ever do.
+ */
+function printKgOffer(kgAvailable, usedKg) {
+  if (!kgAvailable) return;
+  if (usedKg) {
+    process.stdout.write(
+      '\nkgai: this workspace uses the knowledge graph as its decision memory.\n' +
+        '      `maude kg doctor` to confirm · `maude kg search "<topic>"` to read it back.\n'
+    );
+    return;
+  }
+  process.stdout.write(
+    '\nkgai: `kg` is installed on this machine, and this workspace was scaffolded\n' +
+      '      CLASSIC (markdown decisions + STATE.md history). Both work; the graph\n' +
+      '      makes "what did we decide about X" a query instead of a grep, and gives\n' +
+      '      the gitignored .ai/logs/ verdicts a copy that travels.\n' +
+      '      To switch now (empty workspace — nothing to migrate):\n' +
+      '        maude init --kg --force\n' +
+      '      Later, once you have decisions on disk, use the migration instead:\n' +
+      '        maude kg import --dry-run --archive     (then drop --dry-run)\n'
+  );
 }

package/cli/commands/kg.mjs

@@ -12,8 +12,9 @@
 // or an informative message — a command's classic `.ai/` path is unaffected.
 
 import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join, resolve } from 'node:path';
 import { parseArgs } from '../lib/argv.mjs';
 
 const CONFIG_PATH = '.ai/workflows.config.json';
@@ -30,6 +31,7 @@ const VERBS = new Set([
   'ingest',
   'scope',
   'import',
+  'record-log',
   'help',
 ]);
 
@@ -131,15 +133,19 @@ function kgEnv() {
 }
 
 /** Spawn the resolved `kg` with the given args, inheriting stdio. Returns exit status. */
-function runKg(state, kgArgs, { timeoutMs } = {}) {
+function runKg(state, kgArgs, { timeoutMs, swallowStdout } = {}) {
   if (!state.kgBin) {
     process.stderr.write(
       'maude kg: the `kg` CLI is not available. kgai is capability-gated — install it (see docs/kgai-onboarding.md) or use classic `.ai/` mode.\n'
     );
     return 127;
   }
+  // `swallowStdout` is for verbs that print their OWN one-line summary — `kg
+  // ingest` dumps a ~25-line JSON receipt per call, and a command that records
+  // a verdict on every run would bury the agent's real output in it. stderr
+  // still passes through, so a genuine failure is never hidden.
   const child = spawnSync(state.kgBin, kgArgs, {
-    stdio: 'inherit',
+    stdio: swallowStdout ? ['inherit', 'pipe', 'inherit'] : 'inherit',
     env: kgEnv(),
     ...(timeoutMs ? { timeout: timeoutMs } : {}),
   });
@@ -276,6 +282,117 @@ async function verbImport(state, args, pkgRoot) {
   });
 }
 
+// ── verb: record-log (keep the graph fed as verdicts are written) ───────────
+//
+// WHY this exists rather than a JSON blob per command: `.ai/logs/**` is
+// GITIGNORED, so for RCAs / reviews / audits the graph is the only inheritable
+// copy. The Phase-5 migration put 120 of them in — but nothing kept feeding it,
+// so the corpus began decaying the moment migration finished. Seven flow
+// commands and six design ones now call this as they write.
+//
+// It delegates to `buildLogDecision`, the SAME builder the bulk importer uses,
+// because a second hand-rolled shape would fork the corpus: a node recorded
+// today has to land on the same shelf as the ones migration created (same slug
+// rule, props, ABOUT/scope/EVIDENCE_FOR edges) or `kg search` returns half an
+// answer. Re-recording is safe — identity is `hash(kind:name)`, props MERGE.
+async function verbRecordLog(state, args, pkgRoot) {
+  const { flags } = parseArgs(args, { booleans: ['dry-run', 'quiet'] });
+  // Inactive is the COMMON case downstream, and it must be a clean no-op so a
+  // command can call this unconditionally instead of re-deriving the gate.
+  if (!state.active) return 0;
+
+  const file = flags.file;
+  if (!file) {
+    process.stderr.write('maude kg record-log: --file <path> is required.\n');
+    return 1;
+  }
+  const abs = resolve(state.projectRoot, file);
+  if (!existsSync(abs)) {
+    // A verdict the caller says it wrote but didn't is a caller bug, not a
+    // reason to fail the command that produced real work — warn and move on.
+    process.stderr.write(`maude kg record-log: no such file: ${abs} — nothing recorded.\n`);
+    return 0;
+  }
+
+  const libPath = join(pkgRoot, 'cli', 'lib', 'ddr-to-kgai.mjs');
+  if (!existsSync(libPath)) {
+    process.stderr.write('maude kg record-log: builder unavailable in this build.\n');
+    return 0;
+  }
+  const { LOG_KINDS, buildLogDecision } = await import(libPath);
+
+  // Kind: explicit wins; else infer from the parent dir via the SAME table the
+  // importer keys on, so `.ai/logs/rca/x.md` → `rca` either way.
+  const parent = abs.split('/').slice(-2, -1)[0] ?? '';
+  const kind = flags.kind || LOG_KINDS[parent];
+  if (!kind) {
+    process.stderr.write(
+      `maude kg record-log: cannot infer kind from "${parent}/" — pass --kind (known: ${Object.values(
+        LOG_KINDS
+      ).join(', ')}).\n`
+    );
+    return 1;
+  }
+
+  const rel = abs.startsWith(`${state.projectRoot}/`)
+    ? abs.slice(state.projectRoot.length + 1)
+    : abs;
+
+  // Slug collision guard. Identity is `hash(kind:name)`, so two files sharing a
+  // basename become ONE node and the second silently overwrites the first's
+  // props — measured: recording `_history/settings/critique/001-PANEL.md` then
+  // `_history/login/critique/001-PANEL.md` left a single node pointing at login,
+  // with the settings critique gone. Flow logs are safe (their basenames are
+  // already unique across `.ai/logs/<kind>/`) and must keep the bare slug to
+  // match the migrated corpus — but anything attached to a specific element
+  // (`--about canvas:foo`) is per-element by nature, so qualify it with that
+  // element's name. Doing it HERE rather than in each caller means six design
+  // commands can't each forget it.
+  const aboutName = flags.about ? String(flags.about).split(':').slice(1).join(':') : '';
+  const derivedSlug =
+    flags.slug ||
+    (aboutName
+      ? `${aboutName}-${basename(abs).replace(/\.md$/, '')}`.replace(/\//g, '-')
+      : undefined);
+
+  const built = buildLogDecision(abs, kind, state.scope, {
+    pathRel: rel,
+    about: flags.about, // e.g. canvas:<slug> for a design verdict
+    link: flags.link, // e.g. EVALUATES
+    slug: derivedSlug,
+  });
+
+  if (flags['dry-run']) {
+    process.stdout.write(`${JSON.stringify({ decisions: [built.decision] }, null, 2)}\n`);
+    return 0;
+  }
+  // Temp file + `kg ingest --file`, matching the importer: the same plumbing
+  // that ingested 310 decisions during migration, so no new stdin path to get
+  // wrong (and a verdict body is far past comfortable argv size anyway).
+  const tmp = join(tmpdir(), `kg-record-${kind}-${built.slug}.json`);
+  writeFileSync(tmp, JSON.stringify({ decisions: [built.decision] }));
+  const status = runKg(state, ['ingest', '--file', tmp], {
+    timeoutMs: 30000,
+    swallowStdout: true,
+  });
+  try {
+    rmSync(tmp, { force: true });
+  } catch {
+    /* best-effort temp cleanup */
+  }
+  if (status !== 0) {
+    // Same contract as `sync`: never fail the caller's real work over memory.
+    process.stderr.write(`maude kg record-log: ingest failed for ${rel} — the file is on disk.\n`);
+    return 0;
+  }
+  if (!flags.quiet) {
+    process.stdout.write(
+      `[kg] recorded ${kind}:${built.slug}${built.citedCount ? ` (${built.citedCount} EVIDENCE_FOR)` : ''}\n`
+    );
+  }
+  return 0;
+}
+
 // ── passthrough verbs (context / ingest) ───────────────────────────────────
 function verbPassthrough(verb, state, args) {
   if (!state.active) {
@@ -311,6 +428,11 @@ function usage() {
   ingest <args…>          Record a decision + scope tags (passthrough to \`kg ingest\`).
   scope                   Print the resolved scope ({repo, dept}).
   import [--dry-run …]    Migrate .ai/decisions/ + .design/ into kgai (Phase 5).
+  record-log --file F     Record ONE verdict file (RCA / review / audit / critique) as a
+    [--kind K]            graph node, shaped exactly like the migrated corpus. Kind is
+    [--about E --link L]  inferred from the parent dir; --about/--link attach a design
+    [--slug S] [--quiet]  verdict to canvas:<slug> instead of area:<kind>. Silent no-op
+    [--dry-run]           when inactive, so callers invoke it unconditionally.
   --root <path>           Project root (default $CLAUDE_PROJECT_DIR or cwd).
 
 kgai is capability-gated + opt-out. When \`kg\` is absent or mode:off, verbs no-op cleanly
@@ -357,6 +479,9 @@ export async function run({ args, pkgRoot }) {
     case 'import':
       status = await verbImport(state, args.slice(1), pkgRoot);
       break;
+    case 'record-log':
+      status = await verbRecordLog(state, args.slice(1), pkgRoot);
+      break;
     case 'context':
     case 'ingest':
       status = verbPassthrough(verb, state, args);