@1agh/maude 0.22.2 → 0.24.0

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/);
+});

package/cli/lib/gitignore-block.mjs

@@ -0,0 +1,90 @@
+// Maude design-runtime .gitignore block — Phase 9 Task 9 (gitignore strategy).
+//
+// Single `full` strategy in v1.1 (DDR-056): canvases + their JSON snapshots
+// stay in git (cold backup, PR-reviewable .html diffs, bootstrap-from-clone),
+// while regenerable per-machine runtime state is ignored — even in linked mode.
+//
+// The rules live between `# maude:begin` / `# maude:end` markers so the writer
+// is idempotent: re-running replaces the block in place (never duplicates), and
+// anything the user authored outside the markers is untouched. `maude design
+// unlink` deliberately leaves the block — the rules are harmless in solo mode
+// (the ignored files just don't get created).
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export const BEGIN_MARKER = '# maude:begin';
+export const END_MARKER = '# maude:end';
+
+/**
+ * The runtime paths Maude ignores under the design root, relative to repo root.
+ * `designRel` defaults to `.design` (the only design root in v1.1 defaults).
+ */
+export function buildBlock(designRel = '.design') {
+  const root = designRel.replace(/\/+$/, '');
+  const lines = [
+    BEGIN_MARKER,
+    '# Maude design plugin runtime — gitignored even in linked mode (DDR-056).',
+    `${root}/_state/`, // binary CRDT logs (regenerable from hub)
+    `${root}/_server.json`,
+    `${root}/_server.log`,
+    `${root}/_active.json`,
+    `${root}/_sync.json`, // linked-mode offline/sync status (Task 8)
+    `${root}/_history/`,
+    `${root}/_canvas-state/`, // per-machine canvas undo/redo + scratch state
+    `${root}/_chat/`, // ACP transcripts (per-machine)
+    END_MARKER,
+  ];
+  return `${lines.join('\n')}\n`;
+}
+
+/** True when the file already contains a maude-managed block. */
+export function hasBlock(contents) {
+  return contents.includes(BEGIN_MARKER) && contents.includes(END_MARKER);
+}
+
+/**
+ * Replace the existing maude block in `contents`, or append a fresh one.
+ * Pure — returns the new file text. Preserves everything outside the markers.
+ */
+export function applyBlock(contents, block) {
+  if (!hasBlock(contents)) {
+    // Append with a single blank-line separator (avoid leading newline on an
+    // empty file; avoid double-blank when the file already ends in a newline).
+    if (contents.length === 0) return block;
+    const sep = contents.endsWith('\n') ? '\n' : '\n\n';
+    return `${contents}${sep}${block}`;
+  }
+  const begin = contents.indexOf(BEGIN_MARKER);
+  const endIdx = contents.indexOf(END_MARKER);
+  const after = endIdx + END_MARKER.length;
+  // Consume one trailing newline after END so we don't accumulate blank lines.
+  const tail = contents.slice(after).replace(/^\n/, '');
+  const head = contents.slice(0, begin);
+  return `${head}${block}${tail ? `\n${tail}` : ''}`;
+}
+
+/**
+ * Write (or refresh) the maude block in `<repoRoot>/.gitignore`.
+ *
+ * @param {string} repoRoot
+ * @param {{ designRel?: string, dryRun?: boolean }} [opts]
+ * @returns {{ action: 'created' | 'updated' | 'unchanged', path: string }}
+ */
+export function writeGitignoreBlock(repoRoot, { designRel = '.design', dryRun = false } = {}) {
+  const path = resolve(repoRoot, '.gitignore');
+  const existed = existsSync(path);
+  const current = existed ? readFileSync(path, 'utf8') : '';
+  const block = buildBlock(designRel);
+  const next = applyBlock(current, block);
+
+  let action;
+  if (!existed) action = 'created';
+  else if (next === current) action = 'unchanged';
+  else action = 'updated';
+
+  if (!dryRun && next !== current) {
+    writeFileSync(path, next, 'utf8');
+  }
+  return { action, path };
+}

package/cli/lib/gitignore-block.test.mjs

@@ -0,0 +1,123 @@
+// gitignore-block helper tests — Phase 9 Task 9 (DDR-056).
+
+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 {
+  BEGIN_MARKER,
+  END_MARKER,
+  applyBlock,
+  buildBlock,
+  hasBlock,
+  writeGitignoreBlock,
+} from './gitignore-block.mjs';
+
+function withRepo(fn) {
+  const dir = mkdtempSync(join(tmpdir(), 'maude-gitignore-'));
+  try {
+    return fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test('buildBlock includes the runtime paths and is marker-wrapped', () => {
+  const block = buildBlock('.design');
+  assert.ok(block.startsWith(BEGIN_MARKER));
+  assert.ok(block.trimEnd().endsWith(END_MARKER));
+  for (const p of [
+    '.design/_state/',
+    '.design/_server.json',
+    '.design/_active.json',
+    '.design/_sync.json',
+    '.design/_history/',
+    '.design/_chat/',
+  ]) {
+    assert.ok(block.includes(p), `missing ${p}`);
+  }
+  // Committed artifacts must NOT be ignored.
+  assert.ok(!block.includes('.design/config.json'));
+  assert.ok(!/\.design\/\*\.html/.test(block));
+});
+
+test('buildBlock honors a custom design root', () => {
+  const block = buildBlock('design');
+  assert.ok(block.includes('design/_server.json'));
+  assert.ok(!block.includes('.design/_server.json'));
+});
+
+test('writeGitignoreBlock creates .gitignore when absent', () => {
+  withRepo((dir) => {
+    const { action, path } = writeGitignoreBlock(dir);
+    assert.equal(action, 'created');
+    const text = readFileSync(path, 'utf8');
+    assert.ok(hasBlock(text));
+  });
+});
+
+test('writeGitignoreBlock is idempotent — second run is unchanged', () => {
+  withRepo((dir) => {
+    writeGitignoreBlock(dir);
+    const first = readFileSync(join(dir, '.gitignore'), 'utf8');
+    const { action } = writeGitignoreBlock(dir);
+    const second = readFileSync(join(dir, '.gitignore'), 'utf8');
+    assert.equal(action, 'unchanged');
+    assert.equal(first, second);
+    // Exactly one block — no duplication.
+    assert.equal(first.split(BEGIN_MARKER).length - 1, 1);
+  });
+});
+
+test('writeGitignoreBlock preserves user content outside the markers', () => {
+  withRepo((dir) => {
+    const userContent = 'node_modules/\n*.log\n.env\n';
+    writeFileSync(join(dir, '.gitignore'), userContent);
+    writeGitignoreBlock(dir);
+    const text = readFileSync(join(dir, '.gitignore'), 'utf8');
+    assert.ok(text.includes('node_modules/'));
+    assert.ok(text.includes('.env'));
+    assert.ok(hasBlock(text));
+  });
+});
+
+test('writeGitignoreBlock updates an existing block in place (no duplication)', () => {
+  withRepo((dir) => {
+    // Seed a stale block with a different design root.
+    const stale = `keep-me\n${buildBlock('olddesign')}trailing\n`;
+    writeFileSync(join(dir, '.gitignore'), stale);
+    const { action } = writeGitignoreBlock(dir, { designRel: '.design' });
+    assert.equal(action, 'updated');
+    const text = readFileSync(join(dir, '.gitignore'), 'utf8');
+    assert.equal(text.split(BEGIN_MARKER).length - 1, 1, 'still exactly one block');
+    assert.ok(text.includes('.design/_server.json'));
+    assert.ok(!text.includes('olddesign/_server.json'));
+    assert.ok(text.includes('keep-me'));
+    assert.ok(text.includes('trailing'));
+  });
+});
+
+test('writeGitignoreBlock --dry-run does not touch disk', () => {
+  withRepo((dir) => {
+    const { action } = writeGitignoreBlock(dir, { dryRun: true });
+    assert.equal(action, 'created');
+    // File was not actually written.
+    assert.throws(() => readFileSync(join(dir, '.gitignore'), 'utf8'));
+  });
+});
+
+test('applyBlock appends to a file lacking a trailing newline cleanly', () => {
+  const out = applyBlock('a\nb', buildBlock('.design'));
+  assert.ok(out.includes('a\nb'));
+  assert.ok(hasBlock(out));
+  // No run-together: marker starts on its own line.
+  assert.ok(out.includes(`\n${BEGIN_MARKER}`));
+});
+
+test('hasBlock detects both markers', () => {
+  assert.ok(hasBlock(`x\n${BEGIN_MARKER}\ny\n${END_MARKER}\n`));
+  assert.ok(!hasBlock('just user content'));
+  assert.ok(!hasBlock(BEGIN_MARKER)); // begin without end
+});

package/cli/lib/hubs-config.mjs

@@ -12,8 +12,15 @@
 //         "linkedAt": 1716800000000
 //       },
 //       ...
-//     }
+//     },
+//     "trusted": ["https://maude-hub-foo.fly.dev", ...]
 //   }
+//
+// `trusted` is the per-machine trust allowlist for non-loopback hubs (the
+// `maude design link` confirmation, DDR-054 F2). It lives here — NOT in a
+// committable repo file — on purpose: a committable allowlist would let an
+// attacker pre-seed trust via a PR and bypass the link-time confirmation
+// (trust laundering). Trust is a per-machine decision, like `~/.ssh/known_hosts`.
 
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
@@ -68,11 +75,20 @@ export function saveHubsConfig(config) {
   }
 }
 
-/** Upsert a hub entry. Same URL replaces the existing record. */
-export function addHub(url, token) {
+/**
+ * Upsert a hub entry. Same URL replaces the existing record. `extra` merges
+ * additional per-machine attestations (e.g. `adoptedAt` — the timestamp this
+ * machine pushed its local state up via `--adopt`, used by the sync runtime to
+ * avoid re-adopting; DDR-054 F4).
+ *
+ * @param {string} url
+ * @param {string} token
+ * @param {{ adoptedAt?: number }} [extra]
+ */
+export function addHub(url, token, extra = {}) {
   const norm = normalizeUrl(url);
   const cfg = loadHubsConfig();
-  cfg.hubs[norm] = { token, linkedAt: Date.now() };
+  cfg.hubs[norm] = { token, linkedAt: Date.now(), ...extra };
   saveHubsConfig(cfg);
   return cfg.hubs[norm];
 }
@@ -98,6 +114,28 @@ export function getHub(url) {
   return cfg.hubs[norm] ?? null;
 }
 
+/**
+ * Per-machine trust check for a non-loopback hub (DDR-054 F2). Trust is stored
+ * here, not in a committable repo file, so a malicious PR cannot pre-seed it.
+ */
+export function isHubTrusted(url) {
+  const norm = normalizeUrl(url);
+  const cfg = loadHubsConfig();
+  return Array.isArray(cfg.trusted) && cfg.trusted.includes(norm);
+}
+
+/** Record a hub as trusted on THIS machine. Idempotent. */
+export function trustHub(url) {
+  const norm = normalizeUrl(url);
+  const cfg = loadHubsConfig();
+  if (!Array.isArray(cfg.trusted)) cfg.trusted = [];
+  if (!cfg.trusted.includes(norm)) {
+    cfg.trusted.push(norm);
+    saveHubsConfig(cfg);
+  }
+  return norm;
+}
+
 /**
  * Normalize a hub URL so different spellings resolve to the same key:
  * - Trim trailing slash.

package/cli/lib/plugin-cli-reachability.test.mjs

@@ -0,0 +1,56 @@
+// DDR-061 + DDR-062 regression guard.
+//
+// DDR-061: a plugin must NEVER invoke a `cli/lib/*.mjs` module by a relative
+// path unconditionally: in a marketplace install the plugin is copied alone into
+// `cache/<marketplace>/<plugin>/<version>/`, so the sibling `cli/` does not
+// exist and the call crashes with MODULE_NOT_FOUND. The reachable contract is
+// the on-PATH `maude` binary (a declared plugin dependency).
+//
+// So any plugin file that runs `node … cli/lib/<x>.mjs` is only allowed when the
+// SAME file also offers a `command -v maude` fallback (the sibling-first /
+// maude-fallback pattern). This test fails loudly if a new straggler lands.
+//
+// DDR-062: plugin MARKDOWN must reach the dev-server bash helpers through
+// `maude design <verb>`, never `bash "$CLAUDE_PLUGIN_ROOT/dev-server/bin/<x>.sh"`.
+// The marketplace never copies the dev-server beside a plugin, and a flow
+// command's $CLAUDE_PLUGIN_ROOT points at plugins/flow (no dev-server/ at all).
+// Prose mentions of the path are fine; INVOCATIONS (bash/sh/exec/$( prefixed)
+// are banned.
+
+import assert from 'node:assert/strict';
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { test } from 'node:test';
+
+test('no plugin runs `node cli/lib/*.mjs` without an on-PATH maude fallback', () => {
+  const out = execSync(
+    String.raw`grep -rlE 'node[^\n]*cli/lib/[a-z0-9_-]+\.mjs' plugins/ || true`,
+    {
+      encoding: 'utf8',
+    }
+  );
+  const files = out.trim().split('\n').filter(Boolean);
+  const offenders = files.filter((f) => !/command -v maude/.test(readFileSync(f, 'utf8')));
+  assert.deepEqual(
+    offenders,
+    [],
+    `These plugin files invoke a relative cli/lib module with no \`command -v maude\` fallback — they will crash in a marketplace install (DDR-061). Route through \`maude <subcommand>\` or guard with a sibling-exists check + maude fallback:\n  ${offenders.join('\n  ')}`
+  );
+});
+
+test('no plugin markdown invokes a $CLAUDE_PLUGIN_ROOT/dev-server/bin/*.sh helper (DDR-062)', () => {
+  // INVOCATION = the bin path preceded by bash / sh / exec, or inside a $(…)
+  // command substitution. Prose mentions of the path (backtick-wrapped, no verb)
+  // are exempt — they don't run anything. Matches both the $CLAUDE_PLUGIN_ROOT
+  // form and the repo-relative `plugins/<x>/dev-server/bin/` form.
+  const pattern = String.raw`(bash|sh|exec) +"?(\$\{?CLAUDE_PLUGIN_ROOT\}?|plugins/[a-z]+)/dev-server/bin/[A-Za-z0-9_-]+\.sh|\$\("?\$?\{?CLAUDE_PLUGIN_ROOT\}?/dev-server/bin/[A-Za-z0-9_-]+\.sh`;
+  const out = execSync(`grep -rnE '${pattern}' plugins --include='*.md' || true`, {
+    encoding: 'utf8',
+  });
+  const hits = out.trim().split('\n').filter(Boolean);
+  assert.deepEqual(
+    hits,
+    [],
+    `These plugin markdown lines INVOKE a dev-server bin helper directly — they break in marketplace installs (the dev-server is never copied beside a plugin) and in flow commands (whose $CLAUDE_PLUGIN_ROOT has no dev-server/). Route through \`maude design <verb>\` instead (DDR-062):\n  ${hits.join('\n  ')}`
+  );
+});

package/cli/lib/preflight.mjs

@@ -12,7 +12,7 @@
 // because every consumer wants the same table format.
 
 import { spawnSync } from 'node:child_process';
-import { readFile } from 'node:fs/promises';
+import { readFile, writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 
 const SEM_RE = /(\d+)\.(\d+)\.(\d+)/;
@@ -172,10 +172,11 @@ function colorFor(g) {
 // ─── CLI entry — `node cli/lib/preflight.mjs --plugin design --json` ──────
 
 function parseFlags(args) {
-  const out = { plugin: null, mode: 'text' };
+  const out = { plugin: null, mode: 'text', cache: null };
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
     if (a === '--plugin') out.plugin = args[++i];
+    else if (a === '--cache') out.cache = args[++i];
     else if (a === '--json') out.mode = 'json';
     else if (a === '--shell-export') out.mode = 'shell-export';
     else if (a === '--quiet') out.mode = 'quiet';
@@ -184,17 +185,46 @@ function parseFlags(args) {
   return out;
 }
 
-function manifestPathForPlugin(pluginName) {
-  return resolve(`plugins/${pluginName}/dependencies.json`);
+// Cross-command short-circuit cache (Phase A, Task A15). Written after a
+// successful check so sibling commands within the freshness window skip the
+// whole preflight. Path is caller-supplied (design → <designRoot>/_preflight.json,
+// flow → .ai/state/_preflight.json) because this lib runs with cwd = the maude
+// package root when shelled from preflight.sh, not the target repo.
+async function writeCache(cachePath, env) {
+  const payload = {
+    checked: new Date().toISOString(),
+    plugin: env.plugin,
+    all_hard_pass: env.summary.allHardPass,
+    soft_warnings: env.results
+      .filter((r) => r.hardness === 'soft' && r.status === 'missing')
+      .map((r) => r.id),
+  };
+  try {
+    await writeFile(resolve(cachePath), `${JSON.stringify(payload, null, 2)}\n`);
+  } catch {
+    // Cache is a best-effort optimization; a write failure (read-only FS,
+    // missing parent dir) must never break the preflight itself.
+  }
+}
+
+function manifestPathForPlugin(pluginName, pkgRoot = process.cwd()) {
+  return resolve(pkgRoot, 'plugins', pluginName, 'dependencies.json');
 }
 
-async function main(argv) {
-  const flags = parseFlags(argv.slice(2));
+// Shared runnable for both the `maude preflight` command and the direct
+// `node cli/lib/preflight.mjs` entry. `pkgRoot` is where `plugins/<x>/
+// dependencies.json` lives (the maude package root) — resolved independently
+// of the caller's cwd, so the command works from any target repo. (DDR-061:
+// the marketplace install has no sibling cli/, so callers reach this through
+// the on-PATH `maude` binary, which passes its own package root as pkgRoot.)
+export async function runPreflight({ args, pkgRoot = process.cwd() }) {
+  const flags = parseFlags(args);
   if (!flags.plugin) {
-    process.stderr.write('preflight.mjs: pass --plugin <design|flow>\n');
+    process.stderr.write('preflight: pass --plugin <design|flow>\n');
     process.exit(2);
   }
-  const env = await checkAll(manifestPathForPlugin(flags.plugin));
+  const env = await checkAll(manifestPathForPlugin(flags.plugin, pkgRoot));
+  if (flags.cache) await writeCache(flags.cache, env);
   if (flags.mode === 'json') {
     process.stdout.write(`${JSON.stringify(env, null, 2)}\n`);
   } else if (flags.mode === 'shell-export') {
@@ -223,9 +253,10 @@ async function main(argv) {
   process.exit(env.summary.allHardPass ? 0 : 1);
 }
 
-// Entry guard — only run main() when invoked directly.
+// Entry guard — only run when invoked directly (`node cli/lib/preflight.mjs`).
+// The package root is the cwd here (preflight.sh `cd`s to it before exec).
 if (import.meta.url === `file://${process.argv[1]}`) {
-  main(process.argv).catch((err) => {
+  runPreflight({ args: process.argv.slice(2), pkgRoot: process.cwd() }).catch((err) => {
     process.stderr.write(`preflight: ${err.message}\n`);
     process.exit(1);
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1agh/maude",
-  "version": "0.22.2",
+  "version": "0.24.0",
   "description": "Marketplace of Claude Code plugins by Michal Dovrtěl: `design` (canvas-first design iteration) + `flow` (generic agentic workflow loop with .ai second brain). Ships the `maude` CLI (with `mdcc` legacy alias) to scaffold workspace, run the design dev server, and manage configs.",
   "type": "module",
   "engines": {
@@ -41,13 +41,13 @@
     "prepublishOnly": "bash scripts/check-version-parity.sh && bash plugins/design/dev-server/bin/check-runtime-bundles.sh"
   },
   "optionalDependencies": {
-    "@1agh/maude-darwin-arm64": "0.22.2",
-    "@1agh/maude-darwin-x64": "0.22.2",
-    "@1agh/maude-linux-arm64": "0.22.2",
-    "@1agh/maude-linux-arm64-musl": "0.22.2",
-    "@1agh/maude-linux-x64": "0.22.2",
-    "@1agh/maude-linux-x64-musl": "0.22.2",
-    "@1agh/maude-win32-x64": "0.22.2"
+    "@1agh/maude-darwin-arm64": "0.24.0",
+    "@1agh/maude-darwin-x64": "0.24.0",
+    "@1agh/maude-linux-arm64": "0.24.0",
+    "@1agh/maude-linux-arm64-musl": "0.24.0",
+    "@1agh/maude-linux-x64": "0.24.0",
+    "@1agh/maude-linux-x64-musl": "0.24.0",
+    "@1agh/maude-win32-x64": "0.24.0"
   },
   "files": [
     "cli",

package/plugins/design/dev-server/ai-banner.tsx

@@ -41,8 +41,8 @@ const BANNER_CSS = `
   align-items: center;
   gap: 10px;
   background: var(--maude-hud-accent-tint, oklch(92% 0.040 55));
-  color: var(--fg-0, #111);
-  border: 1px solid var(--border-default, rgba(0,0,0,0.16));
+  color: var(--maude-chrome-fg-0, #111);
+  border: 1px solid var(--maude-chrome-border, rgba(0,0,0,0.16));
   border-radius: var(--radius-md, 4px);
   box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);
   font-family: var(--font-sans, system-ui, -apple-system, sans-serif);