@smartmemory/compose 0.3.6-beta → 0.3.8

package/server/completion-projection.js

@@ -0,0 +1,228 @@
+/**
+ * server/completion-projection.js — COMP-COMPLETION-GATE slice 3 (§2.3b).
+ *
+ * The self-verifying projection: ONE predicate that decides whether a vision
+ * item may be shown as `complete`, and FOUR transports that apply it —
+ *
+ *   verifiedCompleteProjection({ item, featureCode, cwd, … })
+ *      ├── POST /api/vision/items/:id/completion-projection   (the gate over REST)
+ *      ├── applyVerifiedProjection(store, …)                    (in-process: the
+ *      │       /lifecycle/complete route, the startup scanner, the reconciler)
+ *      └── VisionWriter.completeItem direct mode                (no server running)
+ *
+ * The property that matters: the predicate carries NO authority of its own. It
+ * re-reads canonical state — feature.json, and the guard ledger when a guard
+ * resource exists — and refuses unless the completion is ALREADY recorded
+ * there. A caller who can satisfy it could simply have read the same truth, so
+ * it can be public without reopening the bypass AC-10/AC-16 close. There is no
+ * token, no secret, and nothing to forge.
+ *
+ * Three verification tiers, stamped on the projection so a reader can never
+ * mistake a weaker one for a stronger one (AC-16b):
+ *
+ *   'guarded'                — a guard resource exists and its state is complete
+ *   'canonical-status-only'  — feature.json is COMPLETE, no guard resource exists
+ *                              (the 230 legacy features; startup seeding)
+ *   'document-derived'       — no feature.json at all; the scanner derived
+ *                              completion from documents (unmanaged folders).
+ *                              Display state, never a completion compose vouches for.
+ *
+ * Only `guard_not_found` means legacy. Any other guard outcome — timeout, spawn
+ * failure, corrupt registry — fails CLOSED (§2.3b, round 5).
+ */
+
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+import { readFeature, featuresBase } from '../lib/feature-json.js';
+import { loadFeaturesDir } from '../lib/project-paths.js';
+import { resolveMode } from '../lib/lifecycle-modes.js';
+import { guardEnabled, currentGuardState } from '../lib/completion-gate.js';
+import { resourceId } from './lifecycle-guard.js';
+
+export const VERIFIED_BY = Object.freeze({
+  GUARDED: 'guarded',
+  CANONICAL: 'canonical-status-only',
+  DOCUMENT: 'document-derived',
+});
+
+/**
+ * The guard states that attest a completion (COMP-LIFECYCLE-BACKFILL S1-1).
+ * `complete` is a walked lifecycle; `complete_backfilled` is one reconstructed
+ * from evidence after the fact. Both are terminal and both verify — the state
+ * itself is what tells a reader which one it was.
+ */
+export const GUARDED_TERMINAL_STATES = new Set(['complete', 'complete_backfilled']);
+
+/** The mode a vision item's lifecycle runs under; build when unstated. */
+export function itemMode(item) {
+  return resolveMode(item?.lifecycle?.mode ?? 'build');
+}
+
+/**
+ * A MANAGED build-mode feature item: it is bound to a feature code by its
+ * lifecycle, that lifecycle is build mode, and the workspace has a feature.json
+ * for the code. This is the exact set the general status writers refuse
+ * `complete` for (AC-10, AC-16). Everything else — fix/plan items, UI-created
+ * items with no lifecycle, the `compose new` kickoff item (a build-mode item
+ * with no feature.json) — is not a feature completion the gate governs, and
+ * keeps its existing path (§2.3d; design §1.3 "documented, not changed").
+ */
+export function isManagedBuildItem(item, cwd) {
+  const code = item?.lifecycle?.featureCode;
+  if (!code || itemMode(item) !== 'build') return false;
+  // EXISTENCE, not parseability: a present-but-malformed feature.json is a
+  // managed feature whose canon is broken, and the refusals must still apply
+  // (Codex r1 #1 — a corrupt file must not read as "unmanaged, anything goes").
+  return canonicalFile(cwd, code).exists;
+}
+
+/** feature.json for `code`: whether it exists, and its parsed content (null when unreadable). */
+export function canonicalFile(cwd, code) {
+  const dir = loadFeaturesDir(cwd);
+  const file = path.join(featuresBase(cwd, dir), code, 'feature.json');
+  const exists = existsSync(file);
+  return { exists, file, feature: exists ? readFeature(cwd, code, dir) : null };
+}
+
+/**
+ * Decide whether `item` may be projected as complete for `featureCode`.
+ *
+ * @param {object}  a
+ * @param {object}  a.item                the vision item (any transport's copy)
+ * @param {string}  a.featureCode
+ * @param {string}  a.cwd                 workspace root (feature.json, capabilities, resourceId)
+ * @param {boolean} [a.consultGuard=true] read the guard ledger (async subprocess). The
+ *                                        synchronous startup path passes false (§2.3b).
+ * @param {boolean} [a.allowDocumentDerived=false] scanner only: accept a folder with no
+ *                                        feature.json as the weakest tier
+ * @returns {Promise<{ok:boolean, verified_by?:string, reasons:string[], guardState?:string|null}>}
+ */
+export async function verifiedCompleteProjection({
+  item, featureCode, cwd, consultGuard = true, allowDocumentDerived = false,
+  guardEnabledOverride = undefined,
+}) {
+  const reasons = [];
+  if (!item) return { ok: false, reasons: ['vision item not found'] };
+  if (!featureCode) return { ok: false, reasons: ['featureCode is required'] };
+  if (!cwd) return { ok: false, reasons: ['cwd is required'] };
+
+  // 3. the item is bound to this feature. An unbound item (no lifecycle) may be
+  //    projected only when its id or featureCode field names the code — the
+  //    same match `findFeatureItem` uses — so the scanner's freshly created
+  //    items and legacy UI items are reachable, but a lifecycle bound to a
+  //    DIFFERENT code is never overwritten.
+  const bound = item.lifecycle?.featureCode;
+  if (bound && bound !== featureCode) {
+    return { ok: false, reasons: [`item ${item.id} is bound to ${bound}, not ${featureCode}`] };
+  }
+  if (!bound && item.id !== featureCode && item.featureCode !== featureCode && item.title !== featureCode) {
+    return { ok: false, reasons: [`item ${item.id} is not bound to ${featureCode}`] };
+  }
+
+  // 1. canonical status
+  const canon = canonicalFile(cwd, featureCode);
+  if (canon.exists && !canon.feature) {
+    // Present but unreadable: canon is BROKEN, not absent. Never downgrade to
+    // the document tier; nothing can be verified against a corrupt file.
+    return { ok: false, reasons: [`feature.json for ${featureCode} exists but could not be parsed — refusing to project a completion against broken canon`] };
+  }
+  const feature = canon.feature;
+  if (!feature) {
+    if (allowDocumentDerived) {
+      return { ok: true, verified_by: VERIFIED_BY.DOCUMENT, reasons: [] };
+    }
+    return { ok: false, reasons: [`no feature.json for ${featureCode} — nothing canonical records a completion`] };
+  }
+  if (feature.status !== 'COMPLETE') {
+    reasons.push(`feature.json for ${featureCode} reads ${feature.status ?? '(no status)'}, not COMPLETE`);
+    return { ok: false, reasons };
+  }
+
+  // 2. the guard, only if a resource exists — and only when the workspace has
+  //    the guard enabled; with it off no resource can have been created by
+  //    compose and there is no stratum to ask.
+  // COMP-LIFECYCLE-BACKFILL §5.10a/R3-7: `guardEnabledOverride` is an
+  // OPERATION-level override of a WORKSPACE-level config read. The config
+  // answers "is the guard on in this workspace now"; a resumed completion needs
+  // "was the guard on for THIS operation" — the flag it persisted. Read with
+  // `??`, never `||`: a persisted `false` must not fall through to live config.
+  const guardOn = guardEnabledOverride ?? guardEnabled(cwd);
+  if (!consultGuard || !guardOn) {
+    return { ok: true, verified_by: VERIFIED_BY.CANONICAL, reasons: [], guardState: null };
+  }
+  const rid = resourceId(featureCode, cwd, itemMode(item));
+  const g = await currentGuardState(rid);
+  if (g.error) {
+    // Fail closed. An unreachable guard is not a legacy feature.
+    return {
+      ok: false,
+      reasons: [`guard state for ${featureCode} could not be read (${g.error.code || g.error.error_type || 'error'}: ${g.error.message || ''}) — refusing rather than downgrading the verification tier`],
+      guardState: null,
+    };
+  }
+  if (g.state === null) {
+    return { ok: true, verified_by: VERIFIED_BY.CANONICAL, reasons: [], guardState: null };
+  }
+  // COMP-LIFECYCLE-BACKFILL: both terminals verify a completion. `complete` is a
+  // walked lifecycle; `complete_backfilled` is one reconstructed from evidence.
+  // The state itself is the provenance signal (Decision 11), so the stamp keeps
+  // the ACTUAL state rather than flattening the two.
+  if (!GUARDED_TERMINAL_STATES.has(g.state)) {
+    return { ok: false, reasons: [`guard for ${featureCode} is in state "${g.state}", not a completion terminal`], guardState: g.state };
+  }
+  return { ok: true, verified_by: VERIFIED_BY.GUARDED, reasons: [], guardState: g.state };
+}
+
+/**
+ * The projection record written next to `status: 'complete'`.
+ * @param {{ok:true, verified_by:string}} verdict
+ * @param {{commitSha?:string, ledgerRef?:string, source?:string}} [evidence]
+ */
+export function projectionStamp(verdict, evidence = {}) {
+  return {
+    verified_by: verdict.verified_by,
+    at: new Date().toISOString(),
+    ...(evidence.commitSha ? { commit_sha: evidence.commitSha } : {}),
+    ...(evidence.ledgerRef ? { ledger_ref: evidence.ledgerRef } : {}),
+    ...(evidence.source ? { source: evidence.source } : {}),
+  };
+}
+
+/**
+ * In-process transport: verify, then write to the live VisionStore.
+ * Used by the /lifecycle/complete route, the reconciler, and the startup
+ * scanner (the latter with `consultGuard:false, allowDocumentDerived:true`).
+ *
+ * @returns {Promise<{ok:boolean, verified_by?:string, reasons:string[], item?:object}>}
+ */
+export async function applyVerifiedProjection(store, {
+  itemId, featureCode, cwd, consultGuard = true, allowDocumentDerived = false, evidence = {},
+  guardEnabledOverride = undefined,
+}) {
+  const item = store.items.get(itemId);
+  const v = await verifiedCompleteProjection({
+    item, featureCode, cwd, consultGuard, allowDocumentDerived, guardEnabledOverride,
+  });
+  if (!v.ok) return v;
+  const prior = { status: item.status, completion_projection: item.completion_projection ?? null };
+  const updated = store.updateItem(itemId, {
+    status: 'complete',
+    completion_projection: projectionStamp(v, evidence),
+  });
+  // `_save` swallows disk failures into a boolean the store records. A
+  // projection that only reached memory is not a projection: it vanishes on
+  // restart with no partial result and no recovery identity (Codex r1 #2).
+  // Roll the live item back so memory and disk agree, and report the failure.
+  if (store.lastSaveOk === false) {
+    try { store.updateItem(itemId, prior); } catch { /* best-effort rollback */ }
+    return { ok: false, reasons: [`vision-state could not be persisted for ${itemId} — projection rolled back`] };
+  }
+  return { ok: true, verified_by: v.verified_by, reasons: [], item: updated };
+}
+
+/** True when `p` is inside the workspace's features dir (used by the allowlist test's docs). */
+export function isFeatureJsonPath(cwd, p) {
+  const base = path.resolve(cwd, loadFeaturesDir(cwd));
+  return path.resolve(p).startsWith(base) && existsSync(p);
+}

package/server/compose-mcp-tools.js

@@ -9,7 +9,7 @@ import fs from 'node:fs';
 import http from 'node:http';
 import path from 'node:path';
 import { ArtifactManager, artifactKeysForMode } from './artifact-manager.js';
-import { getTargetRoot, getDataDir, resolveProjectPath, switchProject, setCurrentWorkspaceId, loadProjectConfig, isLifecycleEnabled } from './project-root.js';
+import { getTargetRoot, getDataDir, resolveProjectPath, switchProject, setCurrentWorkspaceId, getCurrentWorkspaceId, loadProjectConfig, isLifecycleEnabled } from './project-root.js';
 import { resolveProfile, isToolAllowed } from './mcp-tool-policy.js';
 import { getRoadmap } from '../lib/get-roadmap.js';
 
@@ -19,7 +19,7 @@ import { getRoadmap } from '../lib/get-roadmap.js';
  * status/roadmap mutation is the bypass STRAT-GUARD exists to close, so it is
  * rejected unless it carries a valid out-of-band override token (the agent
  * cannot mint it). Guard off → legacy behavior (no-op). Internal callers
- * (recordCompletion → setFeatureStatus directly) never pass through here.
+ * (the completion gate → persistFeatureRaw) never pass through here.
  *
  * @param {object} args tool args (may carry force / override_token)
  * @param {string} toolName for the error message
@@ -474,6 +474,29 @@ export async function toolAddChangelogEntry(args) {
   return addChangelogEntry(getTargetRoot(), args);
 }
 
+/**
+ * COMP-CANON-OVERRIDE — mint a single-use, path-scoped canon override.
+ *
+ * `actor` is deliberately not forwarded from args: it is stamped by the writer
+ * per Decision 3 and must never be caller-supplied.
+ */
+export async function toolCanonOverrideGrant(args) {
+  const { mintGrant } = await import('../lib/canon-override.js');
+  const { loadFeaturesDir } = await import('../lib/project-paths.js');
+  const root = getTargetRoot();
+  const grant = mintGrant(root, {
+    path: args?.path,
+    reason: args?.reason,
+    operation: args?.operation,
+    featuresDir: loadFeaturesDir(root),
+  });
+  return {
+    ...grant,
+    recorded_in: '.compose/canon-overrides.jsonl',
+    note: 'Single-use and path-scoped. Audit tooling for the Claude Write/Edit path, not enforcement.',
+  };
+}
+
 export async function toolGetChangelogEntries(args) {
   const { getChangelogEntries } = await import('../lib/changelog-writer.js');
   return getChangelogEntries(getTargetRoot(), args);
@@ -498,9 +521,45 @@ export async function toolGetJournalEntries(args) {
 // ---------------------------------------------------------------------------
 
 export async function toolRecordCompletion(args) {
-  await assertCompletionEvidence(args);
+  // COMP-COMPLETION-GATE slice 1: route the deliberate completion path through
+  // the gate, which verifies the same evidence AND takes a guarded transition —
+  // the step that has never happened for any real feature (design.md §1).
+  //
+  // `set_status:false` is not a completion: it records evidence without moving
+  // the feature, so it must not drive the guard to a terminal state. It keeps
+  // the evidence check and the original write.
+  const cwd = getTargetRoot();
   const { recordCompletion } = await import('../lib/completion-writer.js');
-  return recordCompletion(getTargetRoot(), args);
+  const { completionGate } = await import('../lib/completion-gate.js');
+
+  if (args?.set_status === false) {
+    await assertCompletionEvidence(args);
+    return recordCompletion(cwd, args);
+  }
+
+  const gated = await completionGate({
+    featureCode: args?.feature_code,
+    commitSha: args?.commit_sha,
+    testsPass: args?.tests_pass,
+    filesChanged: args?.files_changed || [],
+    notes: args?.notes,
+    force: args?.force,
+    builtVia: args?.built_via,
+    idempotencyKey: args?.idempotency_key,
+    workspaceRoot: cwd,
+  });
+  if (!gated.ok) {
+    const e = new Error(
+      `record_completion: refused at ${gated.refusedAt} — ${gated.reasons.join('; ')}`,
+    );
+    // Preserve the established code for the evidence case so existing callers
+    // and tests keep matching on it; the guard cases get their own.
+    e.code = gated.refusedAt === 'evidence'
+      ? 'COMPLETION_EVIDENCE_REQUIRED'
+      : 'COMPLETION_GATE_REFUSED';
+    throw e;
+  }
+  return gated.result;
 }
 
 export async function toolGetCompletions(args) {
@@ -627,8 +686,8 @@ export async function toolBindSession({ featureCode, profile } = {}) {
   // differ from the request arg) so the anchor never drifts. The trusted env
   // profile is the floor; the bind `profile` arg may only NARROW it.
   const boundCode = (body && typeof body === 'object' && body.featureCode) || featureCode;
-  if (boundCode) _boundFeatureCode = boundCode;
-  _sessionProfile = resolveProfile(process.env.COMPOSE_SESSION_PROFILE, profile);
+  if (boundCode) sessionContext().featureCode = boundCode;
+  sessionContext().profile = resolveProfile(process.env.COMPOSE_SESSION_PROFILE, profile);
   return body;
 }
 
@@ -649,10 +708,14 @@ async function _postLifecycle(itemId, action, body) {
   }
   const { status, body: respBody } = result;
   if (status >= 400) {
-    const errMsg = (respBody && typeof respBody === 'object' && respBody.error)
-      ? respBody.error
-      : `HTTP ${status}: ${typeof respBody === 'string' ? respBody : JSON.stringify(respBody)}`;
-    throw new Error(errMsg);
+    const body = respBody && typeof respBody === 'object' ? respBody : null;
+    if (body) {
+      const parts = [body.error ?? `HTTP ${status}`];
+      if (Array.isArray(body.reasons) && body.reasons.length) parts.push(body.reasons.join('; '));
+      if (body.hint) parts.push(`hint: ${body.hint}`);
+      throw new Error(parts.join(' — '));
+    }
+    throw new Error(`HTTP ${status}: ${typeof respBody === 'string' ? respBody : JSON.stringify(respBody)}`);
   }
   return respBody;
 }
@@ -682,7 +745,8 @@ async function _postGate(gateId, action, body) {
 async function _httpRequest(method, urlPath, body = null) {
   const port = resolvePort();
   const headers = { 'Content-Type': 'application/json' };
-  if (_binding?.id) headers['X-Compose-Workspace-Id'] = _binding.id;
+  const workspaceId = getCurrentWorkspaceId() || _binding?.id;
+  if (workspaceId) headers['X-Compose-Workspace-Id'] = workspaceId;
   let payload = null;
   if (body !== null && body !== undefined) {
     payload = JSON.stringify(body);
@@ -725,6 +789,17 @@ export async function toolCompleteFeature({ id, commit_sha, tests_pass, files_ch
   return _postLifecycle(id, 'complete', body);
 }
 
+export async function toolBackfillCompletion({ id, commit_sha, tests_pass, files_changed, notes, reason, occurrences }) {
+  const body = {};
+  if (commit_sha !== undefined) body.commit_sha = commit_sha;
+  if (tests_pass !== undefined) body.tests_pass = tests_pass;
+  if (files_changed !== undefined) body.files_changed = files_changed;
+  if (notes !== undefined) body.notes = notes;
+  body.reason = reason;
+  body.occurrences = occurrences ?? [];
+  return _postLifecycle(id, 'backfill', body);
+}
+
 export async function toolIterationStart({ id, loopType, maxIterations }) {
   return _postLifecycle(id, 'iteration/start', { loopType, maxIterations });
 }
@@ -835,11 +910,31 @@ export async function toolJudgmentLedgerAppend(args) {
   return judgmentLedgerAppend(getTargetRoot(), args);
 }
 
+export async function toolJudgmentPersonWrite(args) {
+  const { judgmentPersonWrite } = await import('../lib/judgment-writer.js');
+  return judgmentPersonWrite(getTargetRoot(), args);
+}
+
+export async function toolJudgmentSituationWrite(args) {
+  const { judgmentSituationWrite } = await import('../lib/judgment-writer.js');
+  return judgmentSituationWrite(getTargetRoot(), args);
+}
+
+export async function toolJudgmentGoalWrite(args) {
+  const { judgmentGoalWrite } = await import('../lib/judgment-writer.js');
+  return judgmentGoalWrite(getTargetRoot(), args);
+}
+
 export async function toolGetJudgmentState() {
   const { getJudgmentState } = await import('../lib/judgment-writer.js');
   return getJudgmentState(getTargetRoot());
 }
 
+export async function toolGetJudgmentTrace(args = {}) {
+  const { getJudgmentTrace } = await import('../lib/judgment-writer.js');
+  return getJudgmentTrace(getTargetRoot(), args.slug);
+}
+
 // ---------------------------------------------------------------------------
 // COMP-MCP-ENFORCE-1 — phase-scoped MCP tool gate (profile × phase)
 //
@@ -847,26 +942,32 @@ export async function toolGetJudgmentState() {
 // rewrite its own launch env); bind_session may only NARROW it. The bound
 // feature anchor (_boundFeatureCode) lets the gate resolve the current phase
 // on-disk and check that re-permitted mutations target the bound feature.
-// All process-global by intent (one MCP child per session).
+// One MCP child may rebind while older calls await; keep policy state per root.
 // ---------------------------------------------------------------------------
 
-let _sessionProfile = resolveProfile(process.env.COMPOSE_SESSION_PROFILE, null);
-let _boundFeatureCode = null;
+const sessionContexts = new Map();
+function sessionContext() {
+  const root = getTargetRoot();
+  if (!sessionContexts.has(root)) {
+    sessionContexts.set(root, { profile: resolveProfile(process.env.COMPOSE_SESSION_PROFILE, null), featureCode: null });
+  }
+  return sessionContexts.get(root);
+}
 
-export function _getSessionProfile() { return _sessionProfile; }
-export function _getBoundFeatureCode() { return _boundFeatureCode; }
+export function _getSessionProfile() { return sessionContext().profile; }
+export function _getBoundFeatureCode() { return sessionContext().featureCode; }
 /** @internal test seam */
 export function _testOnly_setSessionContext({ profile, boundFeatureCode } = {}) {
-  if (profile !== undefined) _sessionProfile = profile;
-  if (boundFeatureCode !== undefined) _boundFeatureCode = boundFeatureCode;
+  if (profile !== undefined) sessionContext().profile = profile;
+  if (boundFeatureCode !== undefined) sessionContext().featureCode = boundFeatureCode;
 }
 
 /** The bound feature's current lifecycle phase from vision-state.json, or null. */
 export function resolveBoundPhase() {
-  if (!_boundFeatureCode) return null;
+  if (!sessionContext().featureCode) return null;
   try {
     const { items } = loadVisionState();
-    const item = items.find((i) => i.lifecycle?.featureCode === _boundFeatureCode);
+    const item = items.find((i) => i.lifecycle?.featureCode === sessionContext().featureCode);
     return item?.lifecycle?.currentPhase ?? null;
   } catch {
     return null;
@@ -894,9 +995,9 @@ function _resolveTargetFeatureCode(tool, args = {}) {
 }
 
 function _targetMatchesBoundFeature(tool, args) {
-  if (!_boundFeatureCode) return false;
+  if (!sessionContext().featureCode) return false;
   const code = _resolveTargetFeatureCode(tool, args);
-  return code !== null && code === _boundFeatureCode;
+  return code !== null && code === sessionContext().featureCode;
 }
 
 /**
@@ -914,7 +1015,7 @@ export function assertToolPhaseAllowed(tool, args = {}, _testCtx) {
   if (!guardOn) return;
   if (_overrideOk(args)) return;
 
-  const profile = _testCtx?.profile ?? _sessionProfile;
+  const profile = _testCtx?.profile ?? sessionContext().profile;
   const phase = _testCtx?.phase ?? resolveBoundPhase();
   const targetMatchesBoundFeature = _testCtx?.targetMatches ?? _targetMatchesBoundFeature(tool, args);
 
@@ -931,4 +1032,3 @@ export function assertToolPhaseAllowed(tool, args = {}, _testCtx) {
     throw e;
   }
 }
-