@1agh/maude 0.23.0 → 0.24.0

package/cli/lib/cache.test.mjs

@@ -0,0 +1,303 @@
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { test } from 'node:test';
+import {
+  check,
+  clear,
+  getOrCompute,
+  list,
+  resolveCacheRoot,
+  sha8,
+  stats,
+  write,
+} from './cache.mjs';
+
+function tmpCache() {
+  const dir = mkdtempSync(join(tmpdir(), 'maude-cache-'));
+  return { cacheDir: dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+test('write then check returns the same payload', () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    write('research/domain', 'finance.abc12345', { mood: ['calm'], n: 3 }, {}, { cacheDir });
+    const hit = check('research/domain', 'finance.abc12345', { cacheDir });
+    assert.ok(hit);
+    assert.deepEqual(hit.value, { mood: ['calm'], n: 3 });
+    assert.equal(typeof hit.ageMs, 'number');
+    assert.ok(hit.ageMs >= 0);
+  } finally {
+    cleanup();
+  }
+});
+
+test('first write drops a README documenting the invalidation policy', () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    write('research/domain', 'k', { x: 1 }, {}, { cacheDir });
+    const readme = readFileSync(join(cacheDir, 'README.md'), 'utf8');
+    assert.match(readme, /Invalidation policy/);
+    assert.match(readme, /research\/domain/);
+  } finally {
+    cleanup();
+  }
+});
+
+test('check returns null on miss', () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    assert.equal(check('research/domain', 'nope', { cacheDir }), null);
+  } finally {
+    cleanup();
+  }
+});
+
+test('check returns null on corrupt entry', () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    const { path } = write('codebase-intelligence', 'deadbeef', { x: 1 }, {}, { cacheDir });
+    writeFileSync(path, '{ this is not json', 'utf8');
+    assert.equal(check('codebase-intelligence', 'deadbeef', { cacheDir }), null);
+  } finally {
+    cleanup();
+  }
+});
+
+test('getOrCompute serves fresh cache without calling compute', async () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    write('design-context', 'ds/tok1', { tokens: 12 }, {}, { cacheDir });
+    let called = false;
+    const v = await getOrCompute({
+      cacheDir,
+      layer: 'design-context',
+      key: 'ds/tok1',
+      ttlMs: 60_000,
+      compute: () => {
+        called = true;
+        return { tokens: 999 };
+      },
+    });
+    assert.deepEqual(v, { tokens: 12 });
+    assert.equal(called, false, 'compute must not run on a fresh hit');
+  } finally {
+    cleanup();
+  }
+});
+
+test('getOrCompute runs compute on miss and caches the result', async () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    let calls = 0;
+    const opts = {
+      cacheDir,
+      layer: 'codebase-intelligence',
+      key: 'sha-aaa',
+      ttlMs: 60_000,
+      compute: () => {
+        calls += 1;
+        return { files: calls };
+      },
+    };
+    const first = await getOrCompute(opts);
+    const second = await getOrCompute(opts);
+    assert.deepEqual(first, { files: 1 });
+    assert.deepEqual(second, { files: 1 }, 'second call must read cache, not recompute');
+    assert.equal(calls, 1);
+  } finally {
+    cleanup();
+  }
+});
+
+test('getOrCompute recomputes past the ttl window', async () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    const { path } = write('security', 'head1', { audit: 'old' }, {}, { cacheDir });
+    // Backdate the stored writtenAt to 2 h ago (past a 1 h ttl).
+    const stored = JSON.parse(readFileSync(path, 'utf8'));
+    stored.writtenAt = Date.now() - 2 * 60 * 60 * 1000;
+    writeFileSync(path, JSON.stringify(stored), 'utf8');
+    const v = await getOrCompute({
+      cacheDir,
+      layer: 'security',
+      key: 'head1',
+      ttlMs: 60 * 60 * 1000,
+      compute: () => ({ audit: 'fresh' }),
+    });
+    assert.deepEqual(v, { audit: 'fresh' });
+  } finally {
+    cleanup();
+  }
+});
+
+test('getOrCompute force bypasses a fresh hit', async () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    write('research/domain', 'x', { v: 'cached' }, {}, { cacheDir });
+    const v = await getOrCompute({
+      cacheDir,
+      layer: 'research/domain',
+      key: 'x',
+      ttlMs: 60_000,
+      force: true,
+      compute: () => ({ v: 'recomputed' }),
+    });
+    assert.deepEqual(v, { v: 'recomputed' });
+  } finally {
+    cleanup();
+  }
+});
+
+test('getOrCompute serves a stale entry when compute throws (within maxAge)', async () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    const { path } = write('research/domain', 'stale', { v: 'old-but-usable' }, {}, { cacheDir });
+    const stored = JSON.parse(readFileSync(path, 'utf8'));
+    stored.writtenAt = Date.now() - 10 * 24 * 60 * 60 * 1000; // 10 days old
+    writeFileSync(path, JSON.stringify(stored), 'utf8');
+    const v = await getOrCompute({
+      cacheDir,
+      layer: 'research/domain',
+      key: 'stale',
+      ttlMs: 7 * 24 * 60 * 60 * 1000, // 7 day fresh window → stale
+      maxAgeMs: 30 * 24 * 60 * 60 * 1000, // 30 day ceiling → still usable
+      compute: () => {
+        throw new Error('websearch down');
+      },
+    });
+    assert.deepEqual(v, { v: 'old-but-usable' });
+  } finally {
+    cleanup();
+  }
+});
+
+test('getOrCompute propagates the error when no usable stale entry exists', async () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    await assert.rejects(
+      getOrCompute({
+        cacheDir,
+        layer: 'research/domain',
+        key: 'missing',
+        compute: () => {
+          throw new Error('boom');
+        },
+      }),
+      /boom/
+    );
+  } finally {
+    cleanup();
+  }
+});
+
+test('concurrent writes to the same key never corrupt the file', async () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    await Promise.all(
+      Array.from({ length: 25 }, (_, i) =>
+        Promise.resolve().then(() =>
+          write('codebase-intelligence', 'race', { i }, {}, { cacheDir })
+        )
+      )
+    );
+    const hit = check('codebase-intelligence', 'race', { cacheDir });
+    assert.ok(hit, 'entry must be readable after concurrent writes');
+    assert.equal(typeof hit.value.i, 'number');
+    assert.ok(hit.value.i >= 0 && hit.value.i < 25);
+  } finally {
+    cleanup();
+  }
+});
+
+test('path traversal in layer or key is rejected', () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    assert.throws(() => write('../escape', 'k', {}, {}, { cacheDir }), /escapes cache root/);
+    assert.throws(() => check('research', '../../etc/passwd', { cacheDir }), /escapes cache root/);
+  } finally {
+    cleanup();
+  }
+});
+
+test('clear(layer) removes only that layer; clear() wipes all but README', () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    write('research/domain', 'a', { x: 1 }, {}, { cacheDir });
+    write('research/domain', 'b', { x: 2 }, {}, { cacheDir });
+    write('codebase-intelligence', 'c', { x: 3 }, {}, { cacheDir });
+    writeFileSync(join(cacheDir, 'README.md'), '# cache', 'utf8');
+
+    clear('research/domain', undefined, { cacheDir });
+    assert.equal(check('research/domain', 'a', { cacheDir }), null);
+    assert.ok(check('codebase-intelligence', 'c', { cacheDir }), 'other layer survives');
+
+    clear(undefined, undefined, { cacheDir });
+    assert.equal(check('codebase-intelligence', 'c', { cacheDir }), null);
+    assert.equal(readFileSync(join(cacheDir, 'README.md'), 'utf8'), '# cache', 'README preserved');
+  } finally {
+    cleanup();
+  }
+});
+
+test('list reports layers with entry counts and bytes', () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    write('research/domain', 'a', { x: 1 }, {}, { cacheDir });
+    write('research/domain', 'b', { x: 2 }, {}, { cacheDir });
+    write('design-context', 'ds/t', { x: 3 }, {}, { cacheDir });
+    const layers = list({ cacheDir });
+    const byName = Object.fromEntries(layers.map((l) => [l.layer, l]));
+    assert.equal(byName.research.entries, 2);
+    assert.equal(byName['design-context'].entries, 1);
+    assert.ok(byName.research.bytes > 0);
+  } finally {
+    cleanup();
+  }
+});
+
+test('stats accumulate hits and misses per layer', async () => {
+  const { cacheDir, cleanup } = tmpCache();
+  try {
+    const base = {
+      cacheDir,
+      layer: 'research/domain',
+      key: 'k',
+      ttlMs: 60_000,
+      compute: () => ({ v: 1 }),
+    };
+    await getOrCompute(base); // miss
+    await getOrCompute(base); // hit
+    await getOrCompute(base); // hit
+    const s = stats({ cacheDir });
+    assert.equal(s.misses['research/domain'], 1);
+    assert.equal(s.hits['research/domain'], 2);
+  } finally {
+    cleanup();
+  }
+});
+
+test('resolveCacheRoot honors MAUDE_CACHE_DIR then CLAUDE_PROJECT_DIR', () => {
+  const prev = { m: process.env.MAUDE_CACHE_DIR, c: process.env.CLAUDE_PROJECT_DIR };
+  try {
+    process.env.MAUDE_CACHE_DIR = '/tmp/explicit-cache';
+    assert.equal(resolveCacheRoot(), '/tmp/explicit-cache');
+    Reflect.deleteProperty(process.env, 'MAUDE_CACHE_DIR');
+    process.env.CLAUDE_PROJECT_DIR = '/tmp/proj';
+    assert.equal(resolveCacheRoot(), join('/tmp/proj', '.ai/cache'));
+  } finally {
+    if (prev.m === undefined) Reflect.deleteProperty(process.env, 'MAUDE_CACHE_DIR');
+    else process.env.MAUDE_CACHE_DIR = prev.m;
+    if (prev.c === undefined) Reflect.deleteProperty(process.env, 'CLAUDE_PROJECT_DIR');
+    else process.env.CLAUDE_PROJECT_DIR = prev.c;
+  }
+});
+
+test('sha8 is stable and 8 hex chars', () => {
+  const a = sha8('finance dashboard');
+  const b = sha8('finance dashboard');
+  assert.equal(a, b);
+  assert.match(a, /^[0-9a-f]{8}$/);
+  assert.notEqual(sha8('finance dashboard'), sha8('ecommerce checkout'));
+});

package/cli/lib/design-link.mjs

@@ -15,6 +15,7 @@ import { dirname, resolve } from 'node:path';
 import { createInterface } from 'node:readline';
 
 import { parseArgs } from './argv.mjs';
+import { BEGIN_MARKER, writeGitignoreBlock } from './gitignore-block.mjs';
 import { addHub, getHub, isHubTrusted, normalizeUrl, removeHub, trustHub } from './hubs-config.mjs';
 
 const DESIGN_CONFIG_PATH = '.design/config.json';
@@ -127,6 +128,13 @@ export async function runLink({ args, cwd = process.cwd(), forceAdopt = false })
   // already trusted on this machine.
   if (!alreadyTrusted) trustHub(normUrl);
 
+  // Phase 9 Task 9 (DDR-056) — solo→linked transition. On --adopt, offer to add
+  // the design-runtime .gitignore block if it's missing, so the shared repo
+  // ignores per-machine runtime state. Default yes; --yes / non-TTY auto-adds.
+  if (adopt) {
+    await maybeWriteGitignoreBlock(cwd, !!flags.yes);
+  }
+
   process.stdout.write(
     `[design link] linked ${cwd} to ${normUrl}.\n  token:   stored in ~/.config/maude/hubs.json (per-machine, never committed)\n  config:  .design/config.json.linkedHub = { url, linkedAt${adopt ? ', adopt: true' : ''} }\n  hub:     ${probe.ok ? `v${probe.version}, uptime ${Math.round((probe.uptimeMs ?? 0) / 1000)}s, ${probe.tokenCount} token(s) (${probe.authMode})` : 'NOT REACHED — linked anyway (--force)'}\n\nNext step: start 'maude design serve' — the linked sync agent ${adopt ? 'will push local state up to the hub on first connect' : 'will mirror hub state to disk on first connect'}.\n`
   );
@@ -200,6 +208,7 @@ export async function runStatus({ args, cwd = process.cwd() }) {
   const url = cfg.linkedHub.url;
   const hubRecord = getHub(url);
   const probe = await probeHealth(url);
+  const sync = readSyncState(resolve(cwd, '.design', '_sync.json'));
 
   const payload = {
     mode: 'linked',
@@ -216,9 +225,9 @@ export async function runStatus({ args, cwd = process.cwd() }) {
           authMode: probe.authMode,
         }
       : { reachable: false, error: probe.error },
-    // Sync agent surfaces ('lastSync', 'pendingOps', 'conflictState') land
-    // in Phase 9 Task 4. For now report n/a.
-    sync: { agent: 'not-implemented' },
+    // Task 8 — the running sync agent writes `.design/_sync.json` with the live
+    // offline/online state, queued-op count, last sync, and conflict log.
+    sync: sync ?? { agent: 'idle', detail: 'no _sync.json — sync agent not running' },
   };
 
   if (flags.json) {
@@ -227,11 +236,55 @@ export async function runStatus({ args, cwd = process.cwd() }) {
   }
 
   const uptimeS = Math.round((probe.uptimeMs ?? 0) / 1000);
+  const syncLine = sync?.notSyncable
+    ? `linked but 0 syncable canvases — ${sync.reason}`
+    : sync
+      ? `${sync.state}${sync.sharedDoc ? ' [shared-doc]' : ''}${sync.queuedOps ? ` — ${sync.queuedOps} edit(s) queued` : ''}${
+          sync.lastSyncAt ? `, last sync ${new Date(sync.lastSyncAt).toISOString()}` : ''
+        }${sync.conflicts?.length ? `, ${sync.conflicts.length} conflict notice(s)` : ''}`
+      : 'idle (start `maude design serve` in linked mode)';
   process.stdout.write(
-    `Maude design — linked mode\n  hub URL:      ${url}\n  linked at:    ${new Date(cfg.linkedHub.linkedAt).toISOString()}\n  adopt mode:   ${cfg.linkedHub.adopt ? 'yes (push-on-first-sync)' : 'no (hub-wins)'}\n  token stored: ${hubRecord ? 'yes (~/.config/maude/hubs.json)' : "NO — re-run 'maude design link'"}\n  hub status:   ${probe.ok ? `up — v${probe.version}, ${uptimeS}s uptime, ${probe.tokenCount} token(s), ${probe.authMode}` : `UNREACHABLE — ${probe.error}`}\n  sync agent:   not-implemented (Phase 9 Task 4 follow-up)\n`
+    `Maude design — linked mode\n  hub URL:      ${url}\n  linked at:    ${new Date(cfg.linkedHub.linkedAt).toISOString()}\n  adopt mode:   ${cfg.linkedHub.adopt ? 'yes (push-on-first-sync)' : 'no (hub-wins)'}\n  token stored: ${hubRecord ? 'yes (~/.config/maude/hubs.json)' : "NO — re-run 'maude design link'"}\n  hub status:   ${probe.ok ? `up — v${probe.version}, ${uptimeS}s uptime, ${probe.tokenCount} token(s), ${probe.authMode}` : `UNREACHABLE — ${probe.error}`}\n  sync agent:   ${syncLine}\n`
   );
 }
 
+/**
+ * On --adopt, add the design-runtime .gitignore block if missing. Prompts
+ * [Y/n] in a TTY (default yes); auto-adds with --yes or non-interactively.
+ * Idempotent — a repo that already has the block is left untouched.
+ */
+async function maybeWriteGitignoreBlock(cwd, assumeYes) {
+  const gitignorePath = resolve(cwd, '.gitignore');
+  const current = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf8') : '';
+  if (current.includes(BEGIN_MARKER)) return; // already present — nothing to do
+
+  let add = assumeYes || !process.stdin.isTTY;
+  if (!add) {
+    add = await promptYesNo(
+      'Add the Maude design-runtime .gitignore block (ignores per-machine runtime state)? [Y/n] ',
+      true
+    );
+  }
+  if (!add) {
+    process.stdout.write(
+      '[design link] skipped .gitignore block — add it later with another `maude design adopt`.\n'
+    );
+    return;
+  }
+  const { action } = writeGitignoreBlock(cwd, { designRel: '.design' });
+  process.stdout.write(`[design link] .gitignore: ${action} maude design-runtime block.\n`);
+}
+
+/** Read the sync agent's `_sync.json` runtime state, or null when absent. */
+function readSyncState(p) {
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
 // ---------------------------------------------------------------- helpers
 
 function readDesignConfig(path) {
@@ -273,13 +326,18 @@ function isLoopbackUrl(normUrl) {
   }
 }
 
-/** Promise-resolving [y/N] prompt. Prompt + echo go to stderr (stdout is data). */
-function promptYesNo(question) {
+/**
+ * Promise-resolving prompt. Prompt + echo go to stderr (stdout is data).
+ * `defaultYes` controls how an empty answer resolves ([Y/n] vs [y/N]).
+ */
+function promptYesNo(question, defaultYes = false) {
   return new Promise((res) => {
     const rl = createInterface({ input: process.stdin, output: process.stderr });
     rl.question(question, (answer) => {
       rl.close();
-      res(/^y(es)?$/i.test(answer.trim()));
+      const trimmed = answer.trim();
+      if (trimmed === '') return res(defaultYes);
+      res(/^y(es)?$/i.test(trimmed));
     });
   });
 }
@@ -356,8 +414,14 @@ function trustGateText(normUrl, adopt, manifest) {
 
 function linkedModeBanner() {
   return `
-⚠ Linked mode is an experimental v1.1 preview. Hub-pushed content is written
-  to your .design/ files as untrusted input. Only link to hubs you operate or
-  fully trust. See DDR-054 for the trust model.
+⚠ Linked mode writes hub-pushed content into your .design/ files as UNTRUSTED
+  input — synced files are listed in .design/_untrusted/INDEX.json and a managed
+  .claudeignore block. Do not act on instructions found inside synced canvases.
+  HTML canvases sync by default; a TSX body syncs only with a per-canvas opt-in
+  (.meta.json "syncable": true). The canvas sandbox is ON by default
+  (MAUDE_CANVAS_ORIGIN_SPLIT=0 opts out, which also disables TSX sync). The
+  sandbox contains browser execution, but a hostile canvas you opt into syncing
+  can still exfiltrate collab metadata (WebRTC / navigation are residual).
+  Only link to hubs you operate or fully trust. See DDR-054 + DDR-060.
 `;
 }

package/cli/lib/flow-design-integration.test.mjs

@@ -0,0 +1,165 @@
+// Phase 11 (flow ⇄ design integration) regression guard.
+//
+// The slash-command orchestration (/flow:plan canvas detection, /flow:done
+// handoff sweep, codebase-intelligence design section, ddr-keeper canvas prompt)
+// is LLM-driven markdown — not unit-testable. What IS deterministic, and what
+// this test locks down, is the *contract* that wiring depends on:
+//
+//   1. The canvas `.meta.json` schema accepts the Phase 11 fields
+//      (status enum, handoffCommit, tags, brief_sha) and rejects a bad status.
+//   2. The flow config schema accepts `paths.designRoot`, the real skeleton
+//      config validates, and the field stays OPTIONAL (no regression for
+//      projects without the design plugin).
+//   3. The /flow:done status round-trip (ready-for-handoff → handed-off +
+//      handoffCommit) produces schema-valid output at both ends.
+//   4. The markdown wiring for all four integrations is present (grep guard) —
+//      a future edit that deletes a section fails loudly here.
+
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { test } from 'node:test';
+import addFormats from 'ajv-formats';
+import Ajv2020 from 'ajv/dist/2020.js';
+import { lintConfig } from './config-lint.mjs';
+
+const read = (p) => readFileSync(resolve(p), 'utf8');
+const readJson = (p) => JSON.parse(read(p));
+
+const META_SCHEMA = readJson('plugins/design/dev-server/canvas-meta.schema.json');
+const FLOW_SCHEMA = readJson('plugins/flow/.claude-plugin/config.schema.json');
+const SKELETON = readJson('plugins/flow/templates/ai-skeleton/workflows.config.json');
+
+const ajv = new Ajv2020({ allErrors: true, strict: false });
+addFormats(ajv);
+const validateMeta = ajv.compile(META_SCHEMA);
+
+// ── 1. canvas-meta schema accepts the Phase 11 fields ──────────────────────
+
+test('canvas-meta: accepts status + tags (ready-for-handoff)', () => {
+  const ok = validateMeta({
+    title: 'Dark Mode Toggle',
+    sections: [{ id: 'hero', label: 'Hero' }],
+    tags: ['dark-mode'],
+    status: 'ready-for-handoff',
+  });
+  assert.equal(ok, true, JSON.stringify(validateMeta.errors));
+});
+
+test('canvas-meta: accepts handed-off + handoffCommit + brief_sha', () => {
+  const ok = validateMeta({
+    title: 'Settings',
+    sections: [],
+    status: 'handed-off',
+    handoffCommit: '8dd832b',
+    brief_sha: 'abc123def456',
+  });
+  assert.equal(ok, true, JSON.stringify(validateMeta.errors));
+});
+
+test('canvas-meta: every status enum value is accepted', () => {
+  for (const status of ['draft', 'in-review', 'ready-for-handoff', 'handed-off']) {
+    const ok = validateMeta({ title: 'X', sections: [], status });
+    assert.equal(ok, true, `status=${status}: ${JSON.stringify(validateMeta.errors)}`);
+  }
+});
+
+test('canvas-meta: a bogus status enum is REJECTED', () => {
+  const ok = validateMeta({ title: 'X', sections: [], status: 'shipped' });
+  assert.equal(ok, false, 'expected status="shipped" to be rejected by the enum');
+});
+
+test('canvas-meta: back-compat — a sidecar without any Phase 11 field still validates', () => {
+  const ok = validateMeta({ title: 'Legacy', sections: [{ id: 's', label: 'S' }] });
+  assert.equal(ok, true, JSON.stringify(validateMeta.errors));
+});
+
+test('canvas-meta: tags must be unique strings', () => {
+  assert.equal(validateMeta({ title: 'X', sections: [], tags: ['a', 'a'] }), false);
+  assert.equal(validateMeta({ title: 'X', sections: [], tags: [1, 2] }), false);
+});
+
+// ── 2. flow config schema: paths.designRoot ────────────────────────────────
+
+test('flow config: the real skeleton config (with paths.designRoot) validates', async () => {
+  const r = await lintConfig({ config: SKELETON, schema: FLOW_SCHEMA });
+  assert.equal(r.ok, true, JSON.stringify(r.errors));
+});
+
+test('flow config: skeleton declares paths.designRoot = .design', () => {
+  assert.equal(SKELETON.paths.designRoot, '.design');
+});
+
+test('flow config: paths.designRoot is OPTIONAL (no-regression for non-design projects)', async () => {
+  const r = await lintConfig({
+    config: { name: 'x', paths: { prd: '.ai/x-prd.md' } },
+    schema: FLOW_SCHEMA,
+  });
+  assert.equal(r.ok, true, JSON.stringify(r.errors));
+});
+
+test('flow config: a non-string paths.designRoot is rejected', async () => {
+  const r = await lintConfig({
+    config: { name: 'x', paths: { designRoot: 42 } },
+    schema: FLOW_SCHEMA,
+  });
+  assert.equal(r.ok, false);
+});
+
+test('flow config: paths.designRoot carries a default of .design', () => {
+  assert.equal(FLOW_SCHEMA.properties.paths.properties.designRoot.default, '.design');
+});
+
+// ── 3. /flow:done status round-trip stays schema-valid ─────────────────────
+
+test('done sweep round-trip: ready-for-handoff → handed-off + handoffCommit both valid', () => {
+  const before = { title: 'Canvas', sections: [], status: 'ready-for-handoff', tags: ['feat'] };
+  assert.equal(validateMeta(before), true, `before: ${JSON.stringify(validateMeta.errors)}`);
+
+  // what /flow:done step 5b writes:
+  const after = { ...before, status: 'handed-off', handoffCommit: 'deadbeef0123' };
+  assert.equal(validateMeta(after), true, `after: ${JSON.stringify(validateMeta.errors)}`);
+});
+
+// ── 4. markdown wiring guards (a deleted section fails here) ────────────────
+
+const PLAN = read('plugins/flow/commands/plan.md');
+const DONE = read('plugins/flow/commands/done.md');
+const MAP_CMD = read('plugins/flow/commands/setup-codebase-map.md');
+const CI_SKILL = read('plugins/flow/skills/codebase-intelligence/SKILL.md');
+const DDR_SKILL = read('plugins/flow/skills/ddr-keeper/SKILL.md');
+const RECORD_DDR = read('plugins/flow/commands/record-ddr.md');
+
+test('wiring: /flow:plan has Design Canvas Detection', () => {
+  assert.match(PLAN, /Design Canvas Detection/);
+  assert.match(PLAN, /paths\.designRoot/);
+  assert.match(PLAN, /### Design canvases/); // the Context References subsection
+});
+
+test('wiring: /flow:done has the handoff sweep + soft-gate DDR-066 reference', () => {
+  assert.match(DONE, /Design handoff sweep/);
+  assert.match(DONE, /ready-for-handoff/);
+  assert.match(DONE, /handed-off/);
+  assert.match(DONE, /handoffCommit/);
+  assert.match(DONE, /DDR-066/);
+});
+
+test('wiring: codebase map command + skill have the Design artifacts section', () => {
+  assert.match(MAP_CMD, /Map Design Artifacts/);
+  assert.match(MAP_CMD, /## Design artifacts/);
+  assert.match(CI_SKILL, /Design Artifact Scanning/);
+  assert.match(CI_SKILL, /### Design artifacts/);
+});
+
+test('wiring: ddr-keeper + record-ddr have the canvas-reference prompt', () => {
+  assert.match(DDR_SKILL, /Canvas reference for UI-affecting decisions/);
+  assert.match(DDR_SKILL, /Related canvas/);
+  assert.match(RECORD_DDR, /Related canvas/);
+});
+
+test('wiring: DDR-066 exists and is indexed', () => {
+  const ddr = read('.ai/decisions/DDR-066-soft-handoff-prompt-in-flow-done.md');
+  assert.match(ddr, /soft prompt/i);
+  const index = read('.ai/decisions/README.md');
+  assert.match(index, /DDR-066/);
+});