@smartmemory/compose 0.3.7 → 0.4.0

package/lib/deps.js

@@ -45,7 +45,16 @@ export function loadDeps(packageRoot) {
     const installOk = typeof dep?.install === 'string'
     const fallbackOk = dep?.fallback === null || typeof dep?.fallback === 'string'
     const optOk = typeof dep?.optional === 'boolean'
-    if (!(idOk && reqOk && installOk && fallbackOk && optOk)) {
+    // COMP-DEPS-AUTOINSTALL: `plugin` is optional and additive. When present it
+    // is the `<plugin>[@marketplace]` spec passed to `claude plugin install`.
+    // Its absence means "no automated install path" (several deps are prose,
+    // e.g. "user-installed skill at ~/.claude/skills/refactor/"), never an error.
+    const pluginOk = dep?.plugin === undefined || typeof dep?.plugin === 'string'
+    // `marketplace_source` is the `owner/repo` (or URL) used to register the
+    // marketplace when the plugin's marketplace is not configured yet — the
+    // normal state on a brand-new machine.
+    const srcOk = dep?.marketplace_source === undefined || typeof dep?.marketplace_source === 'string'
+    if (!(idOk && reqOk && installOk && fallbackOk && optOk && pluginOk && srcOk)) {
       console.warn(`Warning: skipping invalid dep entry in .compose-deps.json: ${JSON.stringify(dep)}`)
       continue
     }
@@ -93,6 +102,36 @@ export function loadDeps(packageRoot) {
  *   - <home>/.claude/plugins/marketplaces/<m>/.claude/commands/<n>.md           (pattern B')
  *   - <home>/.claude/plugins/cache/<marketplace>/<plugin>/<version>/skills/<s>/SKILL.md  (pattern C)
  */
+/**
+ * Read `~/.claude/plugins/installed_plugins.json` — Claude Code's authoritative
+ * record of which plugins are installed and where their tree lives.
+ *
+ * Returns `[{ plugin, installPath }]`, or `null` when the file is absent or
+ * unreadable, which the caller treats as "fall back to walking the cache".
+ * `null` and `[]` mean different things: `[]` is "nothing is installed".
+ */
+function readInstalledPluginPaths(home) {
+  const path = join(home, '.claude', 'plugins', 'installed_plugins.json')
+  if (!existsSync(path)) return null
+  let parsed
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf-8'))
+  } catch {
+    return null
+  }
+  const plugins = parsed?.plugins
+  if (!plugins || typeof plugins !== 'object') return null
+  const out = []
+  for (const [key, entries] of Object.entries(plugins)) {
+    // Key is "<plugin>@<marketplace>"; the namespace agents use is the plugin half.
+    const plugin = key.split('@')[0]
+    for (const entry of Array.isArray(entries) ? entries : []) {
+      if (typeof entry?.installPath === 'string') out.push({ plugin, installPath: entry.installPath })
+    }
+  }
+  return out
+}
+
 export function checkExternalSkills(deps, home = homedir()) {
   const userSkillsRoot = join(home, '.claude', 'skills')
   const marketplacesRoot = join(home, '.claude', 'plugins', 'marketplaces')
@@ -159,15 +198,34 @@ export function checkExternalSkills(deps, home = homedir()) {
   }
 
   // 3. Cache — pattern C: cache/<marketplace>/<plugin>/<version>/skills/<s>/SKILL.md
-  for (const marketplace of listDirs(cacheRoot)) {
-    for (const plugin of listDirs(join(cacheRoot, marketplace))) {
-      for (const version of listDirs(join(cacheRoot, marketplace, plugin))) {
-        const skillsDir = join(cacheRoot, marketplace, plugin, version, 'skills')
-        for (const s of listDirs(skillsDir)) {
-          if (existsSync(join(skillsDir, s, 'SKILL.md'))) addNs(plugin, s)
+  //
+  // COMP-DEPS-AUTOINSTALL: the cache OUTLIVES an uninstall — `claude plugin
+  // uninstall` drops the plugin from installed_plugins.json but leaves its
+  // cached tree on disk, so walking the cache alone reports an uninstalled
+  // plugin as present. Claude Code will not load it, and auto-install would
+  // never re-install it (nothing looks missing). When installed_plugins.json is
+  // readable it is the authority: only its recorded installPaths count. Older
+  // Claude Code versions have no such file — there, fall back to the cache walk
+  // rather than reporting every plugin missing.
+  const installedPaths = readInstalledPluginPaths(home)
+  if (installedPaths === null) {
+    for (const marketplace of listDirs(cacheRoot)) {
+      for (const plugin of listDirs(join(cacheRoot, marketplace))) {
+        for (const version of listDirs(join(cacheRoot, marketplace, plugin))) {
+          const skillsDir = join(cacheRoot, marketplace, plugin, version, 'skills')
+          for (const s of listDirs(skillsDir)) {
+            if (existsSync(join(skillsDir, s, 'SKILL.md'))) addNs(plugin, s)
+          }
         }
       }
     }
+  } else {
+    for (const { plugin, installPath } of installedPaths) {
+      const skillsDir = join(installPath, 'skills')
+      for (const s of listDirs(skillsDir)) {
+        if (existsSync(join(skillsDir, s, 'SKILL.md'))) addNs(plugin, s)
+      }
+    }
   }
 
   const present = []
@@ -206,6 +264,8 @@ export function buildDepReport(result) {
     id: d.id,
     required_for: d.required_for,
     install: d.install,
+    plugin: d.plugin ?? null,
+    marketplace_source: d.marketplace_source ?? null,
     fallback: d.fallback ?? null,
     optional: d.optional,
   })
@@ -263,6 +323,103 @@ export function buildBinaryReport(result) {
   }
 }
 
+/**
+ * COMP-DEPS-AUTOINSTALL — install the plugins that provide missing REQUIRED deps.
+ *
+ * Only deps carrying a `plugin` spec are installable; everything else stays a
+ * printed hint. Optional deps are never auto-installed: the ones we ship
+ * (interface-design, openai-codex) live in third-party marketplaces that would
+ * each need a `claude plugin marketplace add` first, which is a consent step of
+ * a different size than pulling a plugin from a marketplace the user already has.
+ *
+ * Several deps resolve to the SAME plugin (six superpowers skills, one plugin),
+ * so specs are deduped — six missing deps produce one install.
+ *
+ * Never throws and never blocks: a missing `claude` binary, a non-zero exit or a
+ * timeout all come back as data for the caller to print. `-y` is required
+ * whenever stdin/stdout is not a TTY, so it is always passed.
+ *
+ * @param {object} result - from checkExternalSkills
+ * @param {object} [opts]
+ * @param {(cmd:string,args:string[])=>{status:number|null,stderr?:string,error?:Error}} [opts.spawn]
+ * @param {boolean} [opts.enabled] - false short-circuits to a skip (opt-out flag / env)
+ * @returns {{installed:string[], failed:{spec:string,reason:string}[], skipped:string|null}}
+ */
+export function installMissingPlugins(result, opts = {}) {
+  const none = { installed: [], failed: [], skipped: null }
+  if (opts.enabled === false) return { ...none, skipped: 'disabled' }
+
+  const specs = [...new Set(
+    result.missing.filter(d => !d.optional && typeof d.plugin === 'string' && d.plugin).map(d => d.plugin),
+  )]
+  if (specs.length === 0) return none
+
+  const spawn = opts.spawn ?? ((cmd, args) => {
+    // 120s: installing clones a git repo, which is slow on a cold cache.
+    try {
+      return spawnSync(cmd, args, { encoding: 'utf-8', timeout: 120000, stdio: 'pipe' })
+    } catch (error) {
+      return { status: null, error }
+    }
+  })
+
+  // spec -> marketplace source, for the add-then-retry path below.
+  const sourceFor = new Map()
+  for (const d of result.missing) {
+    if (d.plugin && d.marketplace_source && !sourceFor.has(d.plugin)) {
+      sourceFor.set(d.plugin, d.marketplace_source)
+    }
+  }
+
+  const installed = []
+  const failed = []
+  const install = (spec) => spawn('claude', ['plugin', 'install', spec, '-y', '--scope', 'user'])
+
+  for (const spec of specs) {
+    let res = install(spec)
+
+    // A brand-new machine has no marketplaces registered, so the first install
+    // fails with "not found in marketplace". Register the declared source and
+    // retry exactly once — measured against a clean HOME, where the un-retried
+    // path leaves every required dep missing. Only ever adds the marketplace the
+    // manifest names, never one derived from the failure text.
+    const notFound = /not found in marketplace|marketplace .* not found|unknown marketplace/i
+      .test(`${res?.stderr ?? ''}${res?.stdout ?? ''}`)
+    if (res?.status !== 0 && notFound && sourceFor.has(spec)) {
+      const add = spawn('claude', ['plugin', 'marketplace', 'add', sourceFor.get(spec)])
+      if (add?.status === 0) res = install(spec)
+    }
+
+    if (res?.status === 0) { installed.push(spec); continue }
+    // ENOENT on the `claude` binary is a skip for the whole batch, not a failure
+    // of this spec: there is no install path at all on this machine.
+    if (res?.error?.code === 'ENOENT') {
+      return { installed, failed, skipped: 'the `claude` CLI is not on PATH' }
+    }
+    const reason = (res?.stderr || '').trim()
+      || res?.error?.message
+      || `exit ${res?.status ?? 'unknown'}`
+    failed.push({ spec, reason })
+  }
+  return { installed, failed, skipped: null }
+}
+
+/**
+ * Print what installMissingPlugins did. Returns nothing; the caller re-scans and
+ * prints the authoritative dep report afterwards.
+ */
+export function printInstallReport(report) {
+  if (report.skipped === 'disabled') return
+  if (!report.installed.length && !report.failed.length && !report.skipped) return
+
+  console.log('\nInstalling missing required plugins:')
+  for (const spec of report.installed) console.log(`  + ${spec}`)
+  for (const { spec, reason } of report.failed) {
+    console.log(`  ! ${spec} — install failed: ${reason}`)
+  }
+  if (report.skipped) console.log(`  - skipped: ${report.skipped}`)
+}
+
 /**
  * Print a human-readable external-binary report. Returns true if all required
  * (non-optional) binaries are present. Prints nothing when no binaries are declared.

package/lib/dir-lock.js

@@ -0,0 +1,170 @@
+/**
+ * lib/dir-lock.js — the one advisory lock, extracted.
+ *
+ * COMP-PLAN-IDEA-UNIFY S3b-1 (D17).
+ *
+ * `mkdir` is the primitive: it is atomic on every filesystem this runs on, and
+ * it fails with EEXIST rather than clobbering. Everything below exists to make
+ * that primitive survive the cases a bare `mkdirSync` does not.
+ *
+ * There were six independent copy-pasted versions of this in `lib/` when this
+ * module was written, and they did NOT agree — the weakest set its stale
+ * threshold equal to its acquire timeout, which makes ordinary contention
+ * indistinguishable from a crashed holder, so a busy lock gets stolen from a
+ * live owner. This is the hardened shape (from `lib/judgment-writer.js`),
+ * lifted so there is one implementation to reason about instead of six.
+ *
+ * The four things that are not obvious:
+ *
+ *  1. **An owner token inside the dir.** Without it, release cannot tell "my
+ *     lock" from "the lock that replaced mine after it was declared stale", so
+ *     a slow holder deletes the new owner's lock on the way out. This is the
+ *     ABA case and it is the reason release reads before it removes.
+ *
+ *  2. **A partial acquisition is undone.** If the dir is created but the token
+ *     write fails, every later release declines to remove a lock it cannot
+ *     prove is its own — stranding it until the stale window expires. So that
+ *     window is closed by hand rather than waited out.
+ *
+ *  3. **A heartbeat, and why the threshold is high.** The holder touches the
+ *     dir's mtime on a timer so a long-but-live operation is not mistaken for a
+ *     dead one. The timer runs on the event loop, so a SYNCHRONOUS block longer
+ *     than the stale threshold defeats it. 20s is set well above any sync
+ *     section this codebase produces (small-file fs I/O; long work is async).
+ *
+ *  4. **Stale reclaim is by mtime, not by pid.** A pid check cannot see across
+ *     containers or a reused pid, and this lock guards files that two clones
+ *     can reach.
+ *
+ * The lock is advisory: it coordinates writers that agree to use it. Nothing
+ * stops a writer that does not, which is why tool-owned canon also has the
+ * guard layer.
+ */
+
+import {
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  utimesSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+
+/** A holder is presumed dead once its mtime is this old. See note 3. */
+const LOCK_STALE_MS = 20000;
+/** How long to keep trying before giving up on a live holder. */
+const LOCK_ACQUIRE_TIMEOUT_MS = 30000;
+/** Keeps a live holder from being declared stale. */
+const LOCK_HEARTBEAT_MS = 1000;
+/** Poll interval while waiting on a holder. */
+const LOCK_RETRY_MS = 25;
+
+/** The holder's token, or null if it cannot be read (racing, or never written). */
+function readOwner(ownerFile) {
+  try { return readFileSync(ownerFile, 'utf8'); } catch { return null; }
+}
+
+export class DirLockTimeout extends Error {
+  constructor(path, ms) {
+    super(`dir-lock: timed out after ${ms}ms waiting for ${path}`);
+    this.name = 'DirLockTimeout';
+    this.code = 'DIR_LOCK_TIMEOUT';
+    this.path = path;
+  }
+}
+
+/**
+ * Acquire the lock at `path`, returning a release function.
+ *
+ * @param {string} path directory to create as the lock
+ * @returns {Promise<() => void>} release — idempotent, and a no-op if the lock
+ *   is no longer provably ours
+ */
+export async function acquireDirLock(path, { timeoutMs = LOCK_ACQUIRE_TIMEOUT_MS } = {}) {
+  const ownerFile = join(path, 'owner');
+  mkdirSync(dirname(path), { recursive: true });
+  const token = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  const start = Date.now();
+
+  for (;;) {
+    try {
+      mkdirSync(path);
+      try {
+        writeFileSync(ownerFile, token);
+      } catch (err) {
+        // Note 2: undo our own partial acquisition rather than strand the lock.
+        rmSync(path, { recursive: true, force: true });
+        throw err;
+      }
+      const heartbeat = setInterval(() => {
+        try {
+          utimesSync(path, new Date(), new Date());
+        } catch { /* stolen or gone — release will no-op */ }
+      }, LOCK_HEARTBEAT_MS);
+      heartbeat.unref?.();
+
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        clearInterval(heartbeat);
+        try {
+          // Note 1: only remove a lock still provably ours.
+          if (readFileSync(ownerFile, 'utf8') === token) {
+            rmSync(path, { recursive: true, force: true });
+          }
+        } catch { /* not ours anymore — leave it */ }
+      };
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      try {
+        const { mtimeMs } = statSync(path);
+        if (Date.now() - mtimeMs > LOCK_STALE_MS) {
+          // Reclaim is compare-and-delete, not blind delete. Two contenders can
+          // both stat the same stale lock and both decide to remove it; if the
+          // first then acquires a fresh one, a blind `rmSync` from the second
+          // deletes the NEW owner's lock and both proceed into the critical
+          // section. That is the ABA case on the acquire side — the release side
+          // already guarded against it, and this side did not.
+          //
+          // Re-reading the owner token and removing only if it still matches
+          // what we saw when we judged it stale closes the window: the winner
+          // rewrote the token, so the loser's compare fails and it retries.
+          const staleOwner = readOwner(ownerFile);
+          const { mtimeMs: recheck } = statSync(path);
+          if (recheck === mtimeMs && readOwner(ownerFile) === staleOwner) {
+            rmSync(path, { recursive: true, force: true });
+          }
+          continue;
+        }
+      } catch { /* stat raced the holder's release; loop and retry */ }
+      if (Date.now() - start > timeoutMs) {
+        throw new DirLockTimeout(path, timeoutMs);
+      }
+      await new Promise((r) => setTimeout(r, LOCK_RETRY_MS));
+    }
+  }
+}
+
+/**
+ * Run `fn` holding the lock at `path`. The lock is always released, including
+ * when `fn` throws.
+ *
+ * Not reentrant: calling this for the same path from inside `fn` deadlocks
+ * until the acquire timeout. Callers compose by locking once at the outermost
+ * mutating boundary.
+ *
+ * @template T
+ * @param {string} path
+ * @param {() => Promise<T>|T} fn
+ * @returns {Promise<T>}
+ */
+export async function withDirLock(path, fn) {
+  const release = await acquireDirLock(path);
+  try {
+    return await fn();
+  } finally {
+    release();
+  }
+}

package/lib/dispatch-ledger.js

@@ -37,9 +37,9 @@ export function resolveDispatchLedgerCwd(explicitCwd) {
 }
 
 export const DISPATCH_SITES = Object.freeze([
-  'build-step', 'consumer', 'review', 'review-repair', 'gsd', 'gate-qa',
-  'escalation', 'preflight', 'judge', 'design-chat', 'import', 'validation',
-  'new-project', 'unattributed',
+  'build-step', 'consumer', 'review', 'review-repair', 'policy-revision', 'gsd',
+  'gate-qa', 'escalation', 'preflight', 'judge', 'design-chat', 'import',
+  'validation', 'new-project', 'unattributed',
 ]);
 export const DISPATCH_OUTCOMES = Object.freeze(['ok', 'error', 'blocked']);
 export const SETTLEMENT_FAILURE_CLASSES = Object.freeze([

package/lib/feature-json.js

@@ -18,7 +18,7 @@ import { resolvePathValue } from './paths-core.js';
  * Identical to join(cwd, featuresDir) for plain relative dirs.
  * @returns {string} absolute features dir
  */
-function featuresBase(cwd, featuresDir) {
+export function featuresBase(cwd, featuresDir) {
   return resolvePathValue(cwd, featuresDir, 'features');
 }
 

package/lib/feature-reconciler.js

@@ -239,6 +239,14 @@ async function applyEntry(cwd, entry) {
       const writer = new VisionWriter(join(cwd, '.compose', 'data'));
       const item = await writer.findFeatureItem(entry.feature_code);
       if (!item) return { changed: false };
+      if (entry._visStatus === 'complete') {
+        // COMP-COMPLETION-GATE slice 3 (AC-16a): repair is a projection of
+        // canonical truth, so it routes through the self-verifying seam rather
+        // than a carve-out. completeItem re-reads feature.json (and the guard
+        // ledger when a resource exists) before writing, and stamps the tier.
+        await writer.completeItem(item.id, { featureCode: entry.feature_code, cwd });
+        return { changed: true };
+      }
       await writer.updateItemStatus(item.id, entry._visStatus);
       return { changed: true };
     }

package/lib/feature-validator.js

@@ -24,6 +24,16 @@
  *   - XREF_URL_UNCHECKED    (info)    url + reserved url-class providers
  *                                     (jira|linear|notion|obsidian) — recorded,
  *                                     not resolved
+ * Plus the 5 COMP-COVERAGE-GATE project-scope kinds, which describe Compose's
+ * OWN MCP tool surface rather than the workspace (see lib/coverage-gate.js):
+ *   - MISSING_EFFECT        (error)   tool definition declares no `effect`
+ *   - UNGATED_MUTATION      (warning) mutating tool named by no profile list
+ *   - ORPHAN_REGISTRY_TOOL  (warning) canon entry names a tool that is gone
+ *   - UNCOVERED_WRITE       (info)    declared canon write absent from that
+ *                                     entry's tool list (deny-message honesty)
+ *   - COVERAGE_CHECK_SKIPPED (warning) the check itself errored — never aborts
+ * These appear in `findings` AND, structured, under `result.coverage`.
+ *
  * Full catalog + trigger/degrade/gating contract:
  *   docs/features/COMP-MCP-VALIDATE/design.md
  */
@@ -46,6 +56,14 @@ import { SchemaValidator } from '../server/schema-validator.js';
 import {
   resolveRoadmapPathFromConfig, resolveFeaturesPathFromConfig, resolveJournalPathFromConfig,
 } from './project-paths.js';
+// COMP-COVERAGE-GATE slice 2. Imported from server/mcp-tool-defs.js, NEVER from
+// server/compose-mcp.js — the latter connects a StdioServerTransport at module
+// load and hangs any importer.
+import { TOOLS as MCP_TOOL_DEFS } from '../server/mcp-tool-defs.js';
+import { loadToolInventory } from './tool-inventory.js';
+import { canonEntries } from './canon-registry.js';
+import { PROFILE_POLICY, PHASE_REFINEMENT } from '../server/mcp-tool-policy.js';
+import { checkAuthorizationCoverage } from './coverage-gate.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -1130,6 +1148,44 @@ async function runExternalRefChecks(ctx, findings, options = {}) {
   }
 }
 
+/**
+ * COMP-COVERAGE-GATE slice 2 — authorization coverage of Compose's OWN MCP tool
+ * surface.
+ *
+ * Project-scoped, not feature-scoped: it is a property of the installation, not
+ * of any one feature, so it is deliberately absent from validateFeature.
+ *
+ * Pushes its findings into the main `findings` array (so the CLI exit code,
+ * --block-on and the REST severity rollup all pick them up with no fork) AND
+ * returns the structured section for callers that want the codes and
+ * remediations without re-parsing prose.
+ *
+ * Never throws: a coverage bug must not take down a validate run that is mostly
+ * about the workspace.
+ *
+ * @param {Array} findings — mutated in place
+ * @returns {{ findings: Array }}
+ */
+function runCoverageCheck(findings) {
+  try {
+    const inventory = loadToolInventory(MCP_TOOL_DEFS);
+    const result = checkAuthorizationCoverage({
+      inventory,
+      registry: canonEntries(),
+      policy: { PROFILE_POLICY, PHASE_REFINEMENT },
+    });
+    for (const f of result.findings) {
+      findings.push(finding(f.severity, f.code, null, f.remediation, 'coverage'));
+    }
+    return result;
+  } catch (e) {
+    findings.push(finding('warning', 'COVERAGE_CHECK_SKIPPED', null,
+      `authorization coverage check skipped (unexpected error): ${e && e.message ? e.message : e}`,
+      'coverage'));
+    return { findings: [] };
+  }
+}
+
 export async function validateProject(cwd, options = {}) {
   const ctx = loadValidationContext(cwd, options);
   const findings = [];
@@ -1234,5 +1290,12 @@ export async function validateProject(cwd, options = {}) {
   // false positive. Strip them in one place (robust against new such checks) and
   // record the skip as a single info finding. feature.json↔vision drift is left
   // intact — it doesn't involve the roadmap.
-  return { scope: 'project', validated_at: nowIso(), findings: applyNarrativeSuppression(findings, ctx) };
+  const coverage = runCoverageCheck(findings);
+
+  return {
+    scope: 'project',
+    validated_at: nowIso(),
+    findings: applyNarrativeSuppression(findings, ctx),
+    coverage,
+  };
 }

package/lib/feature-writer.js

@@ -193,6 +193,38 @@ export async function addRoadmapEntry(cwd, args) {
   if (!STATUSES.has(status)) {
     throw new Error(`feature-writer: invalid status "${status}"`);
   }
+  // COMP-COMPLETION-GATE: a feature cannot be BORN complete. This closed the
+  // single worst bypass found in the coverage audit — `compose roadmap add
+  // --status COMPLETE` (and proposeFollowup, which forwards caller status here)
+  // minted an already-finished feature in one command: no evidence, no
+  // lifecycle, no ledger entry, nothing to audit. Completion is a transition
+  // with evidence, never an initial condition.
+  //
+  // MIGRATION EXEMPTION. A migration is not minting a completion — it is
+  // transcribing one that already happened, from a ROADMAP row or an older
+  // layout into feature.json. Refusing those would make the migration tools
+  // unable to represent history that predates the gate. The exemption is
+  // explicit (callers pass a reason), narrow (creation only), and logged, so an
+  // exempt write is visible rather than silent. It is NOT a general escape
+  // hatch: ordinary callers have no reason to pass it, and `compose roadmap add`
+  // does not.
+  if (status === 'COMPLETE') {
+    if (!args._migration?.reason) {
+      const e = new Error(
+        'feature-writer: cannot create a feature with status COMPLETE. A completion must be ' +
+        'recorded through the completion gate (record_completion / `compose record-completion`), ' +
+        'which verifies the commit and test evidence and writes a guarded ledger entry. ' +
+        'Create the feature first, then complete it.',
+      );
+      e.code = 'COMPLETE_ON_CREATE_REFUSED';
+      throw e;
+    }
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[feature-writer] migration exemption: creating "${args.code}" as COMPLETE ` +
+      `without a completion record — ${args._migration.reason}`,
+    );
+  }
   // COMP-ROADMAP-PLAN: minimal type validation for the plan-handshake fields.
   if (args.profile !== undefined &&
       (typeof args.profile !== 'object' || args.profile === null || Array.isArray(args.profile))) {
@@ -343,7 +375,7 @@ function readRoadmapBase(roadmapPath) {
 // losslessness is surfaced by the validator (Task 6 / validate_project), not
 // blocked here. Return only the small diagnostic fields; `canonical` is the full
 // regenerated ROADMAP and must not leak into MCP writer results.
-async function roundtripGuard(cwd, provider, mutate, { force, label }) {
+export async function roundtripGuard(cwd, provider, mutate, { force, label }) {
   const current = await provider.listFeatures();
   const projected = mutate(current.map(f => ({ ...f })));
   const roadmapPath = resolveRoadmapPath(cwd);
@@ -379,7 +411,7 @@ async function roundtripGuard(cwd, provider, mutate, { force, label }) {
 // Routes through provider.appendEvent so GitHubProvider can post
 // <!--compose-event--> comments + mirror Projects v2. LocalFileProvider
 // delegates to feature-events.js#appendEvent producing byte-identical output.
-async function safeAppendEvent(cwd, event) {
+export async function safeAppendEvent(cwd, event) {
   try {
     const provider = await getProvider(cwd);
     await provider.appendEvent(event.code, event);
@@ -424,6 +456,29 @@ export async function setFeatureStatus(cwd, args) {
       return { code: args.code, from, to, ts: new Date().toISOString(), noop: true };
     }
 
+    // COMP-COMPLETION-GATE slice 3 (AC-9, Decision 8): COMPLETE is not a status
+    // this writer can set. Not with `force`, not with `derived`, not with an
+    // override token — unconditionally. A completion is a transition WITH
+    // evidence (a real commit, an attested test run, a guarded ledger entry),
+    // and the one place that verifies those is the completion gate, which then
+    // performs the COMPLETE write itself through `persistFeatureRaw`. Every
+    // other caller that used to reach COMPLETE through here was a bypass:
+    // `set_feature_status` (path 5), the reconciler's derived projection (path
+    // 10), `projectFeatureStatus(phase:'complete')`, and the sibling-repo
+    // xref-push. There is no marker that lets a caller through, because any
+    // marker this module exported would be importable by the callers it exists
+    // to refuse.
+    if (to === 'COMPLETE') {
+      const e = new Error(
+        `feature-writer: refusing to set ${args.code} to COMPLETE — status flips to COMPLETE go ` +
+        `through the completion gate only (record_completion / \`compose record-completion\` / ` +
+        `the build runner at terminalization), which verifies commit + test evidence and takes ` +
+        `the guarded transition. \`force\` and \`derived\` do not apply.`,
+      );
+      e.code = 'COMPLETE_VIA_GATE_ONLY';
+      throw e;
+    }
+
     const allowed = TRANSITIONS[from] ?? [];
     // `derived: true` marks a lifecycle-authoritative projection (COMP-MCP-ENFORCE
     // Slice 2, lifecycle-as-truth): the roadmap transition table is not the