@smartmemory/compose 0.2.49-beta → 0.2.51-beta

package/lib/build.js

@@ -9,7 +9,7 @@
  */
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, renameSync, mkdtempSync, rmSync, symlinkSync } from 'node:fs';
-import { join, resolve, dirname } from 'node:path';
+import { join, resolve, dirname, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir, tmpdir } from 'node:os';
 import { execSync, execFileSync } from 'node:child_process';
@@ -18,6 +18,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { StratumMcpClient, StratumError } from './stratum-mcp-client.js';
 import { runAndNormalize, AgentTimeoutError, UserInterruptError, AgentError } from './result-normalizer.js';
 import { checkCapabilityViolation } from './capability-checker.js';
+import { preflightCodexWorktreeProbe, codexProbeAbortMessage } from './codex-preflight.js';
 import { buildStepPrompt, buildRetryPrompt, buildGateContext, clearAmbientContextCache, formatBounceForPrompt } from './step-prompt.js';
 import { promptGate } from './gate-prompt.js';
 import { VisionWriter, ServerUnreachableError } from './vision-writer.js';
@@ -35,7 +36,8 @@ import { rtkPrefix } from './rtk.js';
 
 import YAML from 'yaml';
 // feature-json direct imports removed — mutations now go through TrackerProvider (T9)
-import { loadFeaturesDir } from './project-paths.js';
+import { loadFeaturesDir, resolveContextPath, resolveRoadmapPath, resolveFeaturesPath } from './project-paths.js';
+import { vocabularyEnabled, injectVocabularyEnsure, tagVocabularyViolations } from './vocabulary-inject.js';
 
 // Lazy provider accessor — avoids circular import risk (factory → local-provider
 // does NOT import build.js, so a static import is safe, but lazy is used for
@@ -50,7 +52,7 @@ import { shouldRunCrossModel, LENS_DEFINITIONS } from './review-lenses.js';
 import { injectCertInstructions } from './cert-inject.js';
 import { buildReviewPrompt } from './review-prompt.js';
 import { normalizeCrossModelResult } from './review-normalize.js';
-import { detectTestFramework, scaffoldTestFramework } from './test-bootstrap.js';
+import { detectTestFramework, scaffoldTestFramework, parseTestSummary, deriveTestsPass, isTestFile } from './test-bootstrap.js';
 import { classifyStepAsTier, evaluateTiers } from './gate-tiers.js';
 import { mapFilesToRoutes, classifyRoutes, isDocsOnlyDiff } from './qa-scoping.js';
 import { computeCompositeScore } from './health-score.js';
@@ -473,6 +475,47 @@ function clearPriorDirtyLenses(composeDir) {
   if (existsSync(p)) unlinkSync(p);
 }
 
+// COMP-TEST-BOOTSTRAP-4-1: repo-relative test files touched since HEAD
+// (changed-vs-HEAD + untracked), filtered to test paths. Used to scope the
+// post-coverage test-review pass to the tests this build produced.
+function listChangedTestFiles(cwd) {
+  try {
+    const out = execSync('git diff --name-only HEAD 2>/dev/null; git ls-files --others --exclude-standard 2>/dev/null', {
+      cwd, encoding: 'utf-8', timeout: 5000,
+    }).trim();
+    if (!out) return [];
+    return [...new Set(out.split('\n').map(s => s.trim()).filter(Boolean))].filter(isTestFile);
+  } catch {
+    return [];
+  }
+}
+
+// COMP-TEST-BOOTSTRAP-4-1: the pre-coverage test-file snapshot is persisted to a
+// sidecar (not just in-memory context) so a build that RESUMES after coverage and
+// lands on test_review still has the correct baseline — otherwise scope would widen
+// to every changed test file. Mirrors the prior_dirty_lenses sidecar pattern.
+function preCoverageTestsPath(composeDir) {
+  return join(composeDir, 'pre_coverage_tests.json');
+}
+
+function persistPreCoverageTests(composeDir, files) {
+  mkdirSync(composeDir, { recursive: true });
+  writeFileSync(preCoverageTestsPath(composeDir), JSON.stringify(files ?? [], null, 2));
+}
+
+function loadPreCoverageTests(composeDir) {
+  try {
+    return new Set(JSON.parse(readFileSync(preCoverageTestsPath(composeDir), 'utf-8')));
+  } catch {
+    return new Set();
+  }
+}
+
+function clearPreCoverageTests(composeDir) {
+  const p = preCoverageTestsPath(composeDir);
+  if (existsSync(p)) unlinkSync(p);
+}
+
 /**
  * Check whether a process with the given PID is still alive.
  */
@@ -605,10 +648,19 @@ export async function runBuild(featureCode, opts = {}) {
   // `docs/features/<featureCode>/`. Callers must use this (not inline
   // string concatenation) so the bug-mode path stays in sync.
   // COMP-MCP-MIGRATION-2: feature-mode honors paths.features override.
+  // COMP-PATHS-EXTERNAL D7: two representations on purpose.
+  //  - `featuresDir` stays RELATIVE (loadFeaturesDir): it flows into
+  //    context.featuresDir → the MCP-enforcement guard, which matches against
+  //    repo-relative `git status` output. External artifacts live in another
+  //    repo and are out of that guard's scope by construction; making this
+  //    absolute would break the relative match. triage consumers are
+  //    absolute-safe (resolvePathValue) so the relative value is fine there too.
+  //  - `resolveItemDir` resolves the actual FILESYSTEM dir via
+  //    resolveFeaturesPath (absolute — handles absolute/../-escaping config).
   const featuresDir = loadFeaturesDir(cwd);
   const resolveItemDir = (code) => isBugMode
     ? join(cwd, 'docs', 'bugs', code)
-    : join(cwd, featuresDir, code);
+    : join(resolveFeaturesPath(cwd), code);
 
   // COMP-MCP-MIGRATION-1: per-build correlation ID stamped onto every audit
   // row written during this run, so `executeShipStep`'s pre-stage scan can
@@ -663,7 +715,7 @@ export async function runBuild(featureCode, opts = {}) {
   }
   let composeConfig = {};
   try { composeConfig = JSON.parse(readFileSync(configPath, 'utf-8')); } catch { /* use defaults */ }
-  const contextDirPath = join(cwd, composeConfig.paths?.context ?? 'docs/context');
+  const contextDirPath = resolveContextPath(cwd);
 
   // COMP-PAR-MERGE-QUEUE-CONSUMER-RETRY (D5): per-task pre-merge gate is opt-in.
   // Resolve ONCE and thread into startFresh's planInputs only when the capability
@@ -737,28 +789,38 @@ export async function runBuild(featureCode, opts = {}) {
   // verifyPipelineIntegrity() re-reads from disk, so we must compare against the original file content.
   const specFileHash = _sha256(specYaml);
 
-  // Apply triage profile to spec — toggle skip_if on skippable steps
-  if (buildProfile) {
+  // Apply spec mutations: triage profile (skip_if toggles) + STRAT-VOCAB-3
+  // vocabulary-ensure injection. Parsed once, applied conditionally, stringified
+  // once. The tamper hash above is taken from the on-disk file BEFORE mutation,
+  // so in-memory edits here don't trip verifyPipelineIntegrity (same pattern the
+  // triage profile already relied on).
+  const vocabOn = vocabularyEnabled(cwd, composeConfig);
+  if (buildProfile || vocabOn) {
     try {
       const specObj = YAML.parse(specYaml);
-      const flows = specObj?.flows ?? {};
-      // Find the build flow (or first flow)
-      const flowKey = Object.keys(flows).includes('build') ? 'build' : Object.keys(flows)[0];
-      const steps = flows[flowKey]?.steps ?? [];
-      const skippableSteps = ['prd', 'architecture', 'verification', 'report'];
-      for (const step of steps) {
-        if (!skippableSteps.includes(step.id)) continue;
-        const needsKey = `needs_${step.id}`;
-        if (buildProfile[needsKey] === true) {
-          // Enable step — remove skip_if/skip_reason
-          delete step.skip_if;
-          delete step.skip_reason;
-        } else if (buildProfile[needsKey] === false) {
-          // Disable step — mark as unconditionally skipped
-          step.skip_if = 'true';
-          step.skip_reason = `Skipped by triage (tier ${_buildTierLabel})`;
+      if (buildProfile) {
+        const flows = specObj?.flows ?? {};
+        // Find the build flow (or first flow)
+        const flowKey = Object.keys(flows).includes('build') ? 'build' : Object.keys(flows)[0];
+        const steps = flows[flowKey]?.steps ?? [];
+        const skippableSteps = ['prd', 'architecture', 'verification', 'report'];
+        for (const step of steps) {
+          if (!skippableSteps.includes(step.id)) continue;
+          const needsKey = `needs_${step.id}`;
+          if (buildProfile[needsKey] === true) {
+            // Enable step — remove skip_if/skip_reason
+            delete step.skip_if;
+            delete step.skip_reason;
+          } else if (buildProfile[needsKey] === false) {
+            // Disable step — mark as unconditionally skipped
+            step.skip_if = 'true';
+            step.skip_reason = `Skipped by triage (tier ${_buildTierLabel})`;
+          }
         }
       }
+      // STRAT-VOCAB-3: append vocabulary_compliance to the EXECUTED flow's review
+      // step (extractFlowName resolves the same flow Stratum will run).
+      if (vocabOn) injectVocabularyEnsure(specObj, extractFlowName(specYaml, templateName));
       specYaml = YAML.stringify(specObj);
     } catch (err) {
       // Non-fatal — fall back to unmodified spec
@@ -864,6 +926,33 @@ export async function runBuild(featureCode, opts = {}) {
     let response;
     let isFreshStart = true;
 
+    // COMP-CODEX-IMPL: implementer/reviewer roles. A FRESH start derives them from
+    // the flag (--codex flips Claude-implements/Codex-reviews → Codex/Claude); the
+    // `roles` snapshot below carries those flag-derived values into startFresh.
+    //
+    // A RESUME instead restores roles from active-build state — the build context is
+    // rebuilt locally each invocation, so a `--codex` build resumed WITHOUT the flag
+    // must keep its Codex role (else fix-routing + cross-model suppression silently
+    // revert). Restoration is gated on ACTUALLY resuming (done in the resume branches
+    // below), never eagerly — otherwise a completed `--codex` build's persisted role
+    // would bleed into a later plain `compose build <same-code>` that starts fresh
+    // (Codex impl-review finding #1).
+    let implementerAgent = opts.codex ? 'codex' : 'claude';
+    let reviewerAgent = opts.codex ? 'claude' : 'codex';
+    const roles = { implementerAgent, reviewerAgent };
+    // Restore persisted roles when (and only when) a resume actually happens.
+    const restoreRolesFromActive = (src) => {
+      if (mode !== 'feature' || !src || !src.implementerAgent) return;
+      if (src.implementerAgent !== implementerAgent) {
+        console.warn(
+          `⚠ Resuming ${featureCode}: build started with implementer=${src.implementerAgent}; ` +
+          `honoring the persisted role over the current invocation's flag.`
+        );
+      }
+      implementerAgent = src.implementerAgent;
+      reviewerAgent = src.reviewerAgent ?? reviewerAgent;
+    };
+
     // COMP-FIX-HARD T8: explicit `--resume` flag (compose fix <code> --resume).
     // When opts.resumeFlowId is set, skip stratum.plan entirely and resume the
     // given flow. CLI validates the flowId belongs to this code before calling.
@@ -888,6 +977,9 @@ export async function runBuild(featureCode, opts = {}) {
       console.log(`Resuming flow ${opts.resumeFlowId} for ${featureCode}...`);
       response = await stratum.resume(opts.resumeFlowId);
       isFreshStart = false;
+      // COMP-CODEX-IMPL: this is a real resume — restore roles from persisted state
+      // (the refresh-write below then persists the restored roles, not flag-derived).
+      restoreRolesFromActive(activeNow);
       // Refresh active-build.json so streaming/UI sees this as the live build.
       const flowName = extractFlowName(specYaml, templateName);
       writeActiveBuild(dataDir, {
@@ -904,6 +996,9 @@ export async function runBuild(featureCode, opts = {}) {
         violations: [],
         status: 'running',
         resumedAt: new Date().toISOString(),
+        // COMP-CODEX-IMPL: carry the (restored or default) roles forward on resume-refresh.
+        implementerAgent,
+        reviewerAgent,
       });
     } else if (active && active.featureCode === featureCode && active.flowId) {
       // Same feature — try to resume or start fresh
@@ -916,10 +1011,10 @@ export async function runBuild(featureCode, opts = {}) {
           `Previous build for ${featureCode} was in ${active.mode} mode, ` +
           `current invocation is ${mode} mode. Starting fresh.`
         );
-        response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode, preMergeGate);
+        response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode, preMergeGate, roles);
       } else if (active.status && active.status !== 'running') {
         console.log(`Previous build ${active.status}. Starting fresh.`);
-        response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode, preMergeGate);
+        response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode, preMergeGate, roles);
       } else if (active.pid && active.pid !== process.pid && isProcessAlive(active.pid)) {
         // Same feature, different live process — block
         throw new Error(
@@ -932,10 +1027,12 @@ export async function runBuild(featureCode, opts = {}) {
           response = await stratum.resume(active.flowId);
           if (isTerminalFlow(response.status)) {
             console.log(`Previous build already ${response.status}. Starting fresh.`);
-            response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode, preMergeGate);
+            response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode, preMergeGate, roles);
           } else {
             console.log(`Resuming from step: ${response.step_id}`);
             isFreshStart = false;
+            // COMP-CODEX-IMPL: real resume — restore roles from the persisted build.
+            restoreRolesFromActive(active);
           }
         } catch (err) {
           const recoverable = err?.code === 'flow_not_found'
@@ -943,7 +1040,7 @@ export async function runBuild(featureCode, opts = {}) {
             || err?.message?.includes('No active flow');
           if (recoverable) {
             console.log('Previous flow not found. Starting fresh.');
-            response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode, preMergeGate);
+            response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode, preMergeGate, roles);
           } else {
             throw err;
           }
@@ -953,7 +1050,54 @@ export async function runBuild(featureCode, opts = {}) {
       // Different feature or no active build — start fresh.
       // active-build.json is last-writer-wins: concurrent builds for
       // different features are allowed; the UI shows the most recent.
-      response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode, preMergeGate);
+      response = await startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode, preMergeGate, roles);
+    }
+
+    // COMP-CODEX-IMPL: verify Codex can write inside a detached git worktree (the
+    // execute step's isolation primitive) before any step dispatches. Runs on the
+    // EFFECTIVE role — after resume restoration above — so a resumed Codex build is
+    // probed too (cached per-repo, so resume is normally a no-op); gating on the
+    // pre-restore flag would skip resumed Codex builds (Codex impl-review finding).
+    // The plan/resume above only created the flow object; no agent/worktree work has
+    // happened yet, so aborting here still means we never reach `execute` (Codex
+    // review finding #2). Cached + skippable via COMPOSE_SKIP_CODEX_PROBE.
+    if (implementerAgent === 'codex') {
+      const probe = await preflightCodexWorktreeProbe({
+        cwd: agentCwd,
+        stratum,
+        dataDir,
+        ts: new Date().toISOString().replace(/[:.]/g, '-'),
+      });
+      if (!probe.ok) {
+        // The plan/resume above already persisted feature.json=IN_PROGRESS and
+        // active-build.json='running'. A preflight abort throws before the normal
+        // terminal handlers run, so roll BOTH back here (mirrors the killed/failed
+        // teardown) — otherwise a build that never dispatched a step strands stale
+        // state (Codex impl-review findings).
+        if (!isBugMode) {
+          try {
+            const _bp = await getBuildProvider(cwd);
+            const _feat = await _bp.getFeature(featureCode);
+            if (_feat) await _bp.persistFeatureRaw(featureCode, { ..._feat, status: 'PLANNED' });
+          } catch { /* best-effort */ }
+        }
+        // Identity-guarded active-build downgrade: active-build.json is last-writer-wins
+        // across concurrent feature builds and the probe can sit up to its timeout, so
+        // only downgrade if the on-disk state is still THIS build (same pattern as
+        // persistHealthGateDowngrade) — never clobber a concurrent build's state.
+        try {
+          const cur = readActiveBuild(dataDir);
+          const sameFlow = !cur?.flowId || !response?.flow_id || cur.flowId === response.flow_id;
+          const sameFeature = !cur?.featureCode || cur.featureCode === featureCode;
+          if (cur && sameFlow && sameFeature) {
+            writeActiveBuild(dataDir, { ...cur, status: 'aborted', completedAt: new Date().toISOString() });
+          }
+        } catch { /* best-effort cleanup */ }
+        throw new Error(codexProbeAbortMessage(probe.reason));
+      }
+      if (!probe.cached && !probe.skipped) {
+        console.log(`✓ Codex worktree probe passed — ${probe.reason}`);
+      }
     }
 
     // Update vision state
@@ -962,6 +1106,9 @@ export async function runBuild(featureCode, opts = {}) {
     // Stream writer — instantiated after plan/resume succeeds to prevent
     // a rejected/duplicate invocation from truncating an active build's stream.
     // Only truncate on fresh starts; resumed builds append to existing stream.
+    // COMP-TEST-BOOTSTRAP-4-1: clear any stale pre-coverage test snapshot on a fresh
+    // start (it is per-build; a resume must keep the prior session's snapshot).
+    if (isFreshStart) clearPreCoverageTests(composeDir);
     streamWriter = new BuildStreamWriter(composeDir, featureCode, { truncate: isFreshStart });
     streamWriter.write({
       type: isFreshStart ? 'build_start' : 'build_resume',
@@ -1002,10 +1149,17 @@ export async function runBuild(featureCode, opts = {}) {
       contextDir: contextDirPath,
       stepHistory,
       mode,
+      // COMP-BUILD-QUICK-1: the pipeline template (e.g. 'build-quick') so the ship
+      // step can stamp built_via onto feature.json for the validator's exemption.
+      templateName,
       enforceMcpForFeatureMgmt,
       build_id,
       buildStartedAt,
       featuresDir,
+      // COMP-CODEX-IMPL: roles drive fix-routing (fixer = implementer) and Codex
+      // self-review suppression. Restored from active-build state on resume (above).
+      implementerAgent,
+      reviewerAgent,
       ...(isBugMode ? { bug_code: featureCode } : {}),
     };
 
@@ -1594,6 +1748,14 @@ export async function runBuild(featureCode, opts = {}) {
         // If no test framework is detected and no test directory exists, scaffold first.
         // If the project has no tests at all (truly empty), skip coverage gracefully.
         if (childFlowName === 'coverage_check') {
+          // COMP-TEST-BOOTSTRAP-4-1: snapshot test files present BEFORE coverage runs,
+          // so the later test_review step can review only the tests coverage generates.
+          // Persisted to a sidecar so a resume landing on test_review keeps the baseline.
+          {
+            const preCov = listChangedTestFiles(agentCwd);
+            context._preCoverageTestFiles = new Set(preCov);
+            persistPreCoverageTests(composeDir, preCov);
+          }
           const detected = detectTestFramework(agentCwd);
           const hasTestDir = existsSync(join(agentCwd, 'test')) ||
                              existsSync(join(agentCwd, 'tests')) ||
@@ -1641,6 +1803,37 @@ export async function runBuild(featureCode, opts = {}) {
           }
         }
 
+        // COMP-TEST-BOOTSTRAP-4-1: the test_review step reviews the test files the
+        // coverage step produced this build (the implementation review runs BEFORE
+        // coverage, so generated tests are never otherwise reviewed). Scope to NEW
+        // test files (not present before coverage); skip the step entirely when none.
+        if (childFlowName === 'test_review') {
+          // Resume-safe: fall back to the sidecar when the in-memory snapshot is absent
+          // (a build resumed after coverage rebuilds context fresh).
+          const preCoverage = context._preCoverageTestFiles ?? loadPreCoverageTests(composeDir);
+          const generatedTests = listChangedTestFiles(agentCwd).filter(f => !preCoverage.has(f));
+          if (generatedTests.length === 0) {
+            progress.subFlowStep('test_review', 'skipped — no generated tests');
+            const skipResult = { clean: true, summary: 'No generated test files this build — test review skipped', findings: [] };
+            buildSignals.test_review = skipResult;
+            streamWriter?.write({ type: 'test_review', clean: true, summary: skipResult.summary, findings: [] });
+            verifyPipelineIntegrity(specPath, specFileHash);
+            response = await stratum.stepDone(parentFlowId, parentStepId, { status: 'ok', output: skipResult });
+            continue;
+          }
+          // Inject the exact file list into the review intent (child-flow inputs are
+          // declarative; intent-append is the established runtime-injection pattern).
+          if (response.child_step?.intent !== undefined) {
+            response = {
+              ...response,
+              child_step: {
+                ...response.child_step,
+                intent: `${response.child_step.intent}\n\nGenerated test files to review (written this build):\n${generatedTests.map(f => `- ${f}`).join('\n')}`,
+              },
+            };
+          }
+        }
+
         let childResult = await executeChildFlow(
           response, stratum, context,
           visionWriter, itemId, dataDir, opts.gateOpts ?? {}, progress,
@@ -1649,7 +1842,12 @@ export async function runBuild(featureCode, opts = {}) {
 
         // STRAT-REV-7: After review child flow completes, run cross-model synthesis if diff is large.
         // If cross-model ran, skip the pipeline's separate codex_review step (avoid duplicate Codex pass).
-        if (childFlowName === 'parallel_review' && childResult?.output && (context.filesChanged?.length ?? 0) > 0) {
+        // COMP-CODEX-IMPL: when Codex is the IMPLEMENTER, this Codex second-opinion pass
+        // would be Codex reviewing its own diff — suppress it. The Claude parallel_review
+        // lenses already provide cross-model review of Codex's implementation.
+        if (childFlowName === 'parallel_review' && context.implementerAgent === 'codex') {
+          streamWriter?.write({ type: 'cross_model_review', status: 'codex_skipped', reason: 'Codex is the implementer — its own diff is reviewed by Claude lenses, not a Codex second opinion' });
+        } else if (childFlowName === 'parallel_review' && childResult?.output && (context.filesChanged?.length ?? 0) > 0) {
           const mergedResult = childResult.output;
           const synthesized = await runCrossModelReview(
             mergedResult,
@@ -1677,6 +1875,18 @@ export async function runBuild(featureCode, opts = {}) {
           buildSignals.test_coverage = childResult.output;
         } else if (childFlowName === 'parallel_review' && childResult?.output != null) {
           buildSignals.review_findings = childResult.output;
+        } else if (childFlowName === 'test_review' && childResult?.output != null) {
+          // COMP-TEST-BOOTSTRAP-4-1: advisory — never blocks ship. Surface findings on
+          // the build stream (buildSignals alone is not read by any consumer) so the
+          // cockpit/report can show them.
+          const tr = childResult.output;
+          buildSignals.test_review = tr;
+          streamWriter?.write({
+            type: 'test_review',
+            clean: tr.clean ?? true,
+            summary: typeof tr.summary === 'string' ? tr.summary : '',
+            findings: Array.isArray(tr.findings) ? tr.findings : [],
+          });
         }
 
         // Report child completion envelope to parent flow step.
@@ -1739,7 +1949,8 @@ export async function runBuild(featureCode, opts = {}) {
         }
         progress.retry('build', stepId, response.agent);
         const violations = response.violations ?? [];
-        if (violations.length > 0) progress.findings(violations);
+        // STRAT-VOCAB-3: surface vocabulary violations as must-fix (they block ship).
+        if (violations.length > 0) progress.findings(tagVocabularyViolations(violations));
         // STRAT-REV-5: defensive fallback — for non-flow-step paths named 'review'.
         // For flow-steps the ensure fires inside executeChildFlow (see handler below).
         if ((response.step_id ?? stepId) === 'review') {
@@ -2219,6 +2430,43 @@ export function maybeEmitSectionsAfterPlanGate(stepId, featureDir, opts = {}) {
 // Ship step — runs git commit in-process (not via agent)
 // ---------------------------------------------------------------------------
 
+/**
+ * The git repository toplevel that contains `dir`, or null if `dir` is not
+ * inside any git work tree. Used so ship decides commit ownership per-file by
+ * containing repo, not by assuming the workspace root == the repo
+ * (COMP-PATHS-EXTERNAL D6a).
+ */
+function gitToplevel(dir) {
+  try {
+    return execSync('git rev-parse --show-toplevel', {
+      cwd: dir, encoding: 'utf-8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim() || null;
+  } catch { return null; }
+}
+
+/**
+ * For each owned artifact (ROADMAP, the feature folder) that resolves into a
+ * git repo OTHER than the build's repo, log a one-line "commit it there"
+ * notice. v1 does not auto-commit other repos (that is COMP-PATHS-EXTERNAL-1).
+ * Artifacts in the build's own repo, or in no repo at all, produce no notice.
+ */
+function noticeExternalArtifacts(cwd, featureCode, buildToplevel) {
+  try {
+    const candidates = [
+      ['ROADMAP.md', resolveRoadmapPath(cwd)],
+      ['feature folder', join(resolveFeaturesPath(cwd), featureCode)],
+    ];
+    for (const [label, abs] of candidates) {
+      if (!existsSync(abs)) continue;
+      const top = gitToplevel(dirname(abs));
+      if (top && top !== buildToplevel) {
+        // eslint-disable-next-line no-console
+        console.warn(`[build/ship] 📝 wrote ${label} in ${top} — commit it there (Compose does not auto-commit other repos in v1)`);
+      }
+    }
+  } catch { /* notice is best-effort */ }
+}
+
 /**
  * Execute the ship step: run tests, stage feature files, commit.
  * Returns a PhaseResult-shaped object.
@@ -2231,6 +2479,11 @@ export async function executeShipStep(featureCode, agentCwd, cwd, context, descr
     ? `docs/bugs/${featureCode}`
     : `${featuresDir}/${featureCode}`;
 
+  // COMP-BUILD-QUICK-1: when a feature was built via the trimmed quick lifecycle
+  // (which omits the report phase by design), stamp built_via onto feature.json so
+  // the validator exempts it from MISSING_COMPLETION_REPORT. Null for normal builds.
+  const builtVia = context?.templateName === 'build-quick' ? 'build-quick' : null;
+
   try {
     // 0. Check if we're in a git repository — if not, skip git operations
     let isGitRepo = false;
@@ -2240,22 +2493,57 @@ export async function executeShipStep(featureCode, agentCwd, cwd, context, descr
     } catch { /* not a git repo */ }
 
     if (!isGitRepo) {
+      // COMP-PATHS-EXTERNAL D6b: there is no repo to commit into (e.g. a
+      // forge-top-shaped workspace), but the lifecycle must still advance —
+      // record a commit-less completion (null-SHA) so status flips to COMPLETE.
+      // Best-effort: a completion failure must not fail ship.
+      let completionWarning = null;
+      if (featureCode) {
+        try {
+          const { recordCompletion } = await import('./completion-writer.js');
+          await recordCompletion(cwd, {
+            feature_code: featureCode,
+            // commit_sha omitted — non-git workspace, stamped with the null-SHA
+            // COMP-TEST-BOOTSTRAP-4: this path returns before the test run, so
+            // there is no parsed signal — degrade to true (no block).
+            tests_pass: true,
+            files_changed: [],
+            notes: description.split('\n')[0].slice(0, 72),
+            ...(builtVia ? { built_via: builtVia } : {}),
+          });
+        } catch (err) {
+          completionWarning = `completion record failed (${err.code || 'UNKNOWN'}): ${err.message}`;
+          // eslint-disable-next-line no-console
+          console.warn(`[build/ship] ${featureCode}: ${completionWarning}`);
+        }
+      }
       return {
         phase: 'ship',
         artifact: 'no-git',
         outcome: 'complete',
-        summary: 'No git repository — commit skipped (non-fatal)',
+        summary: 'No git repository — wrote artifacts, recorded completion (commit skipped)',
+        commit: null,
+        ...(completionWarning ? { completionWarning } : {}),
       };
     }
 
     // 1. Run feature-relevant tests (best-effort — don't block ship on test infra issues)
     if (progress) progress.toolUse('ship', 'Running tests...');
+    // COMP-TEST-BOOTSTRAP-4: parse the run output into a structured signal and
+    // derive a real tests_pass for the completion attestation. Degrades to
+    // `true` (no block) whenever the output can't be parsed — see deriveTestsPass.
+    let testSummary = { test_count: 0, pass_rate: 0, parsed: false };
     try {
       // COMP-TEST-BOOTSTRAP item 128: use detected test command instead of hard-coded npm test
       const testFramework = detectTestFramework(agentCwd);
       const testCommand = testFramework?.command ?? 'npm test';
-      execSync(`${testCommand} 2>&1 || true`, { cwd: agentCwd, encoding: 'utf-8', timeout: 120_000 });
-    } catch { /* test runner not available or timed out — proceed */ }
+      const testOutput = execSync(`${testCommand} 2>&1 || true`, { cwd: agentCwd, encoding: 'utf-8', timeout: 120_000 });
+      testSummary = parseTestSummary(testFramework?.framework, testOutput);
+    } catch { /* test runner not available or timed out — proceed (testSummary stays unparsed) */ }
+    const testsPass = deriveTestsPass(testSummary);
+    if (progress && testSummary.parsed) {
+      progress.toolUse('ship', `Tests: ${testSummary.test_count} run, ${testSummary.pass_rate}% passing`);
+    }
 
     // 2. Collect files to stage
     const filesToStage = new Set();
@@ -2316,6 +2604,18 @@ export async function executeShipStep(featureCode, agentCwd, cwd, context, descr
         const dataDir = join(cwd, '.compose', 'data');
         const mode = readEnforcementMode(dataDir);
         if (mode !== 'off') {
+          // COMP-PATHS-EXTERNAL: the pre-stage guard matches repo-relative
+          // `git status`, so relocated canon (an external paths.roadmap /
+          // paths.features) is OUT of its scope — unauthorized edits there are
+          // NOT enforced. Surface that visibly instead of failing silently.
+          // Full external-canon enforcement needs cross-repo dirty detection
+          // (tracked with COMP-PATHS-EXTERNAL-1).
+          for (const [label, abs] of [['paths.roadmap', resolveRoadmapPath(cwd)], ['paths.features', resolveFeaturesPath(cwd)]]) {
+            if (relative(cwd, abs).startsWith('..')) {
+              // eslint-disable-next-line no-console
+              console.warn(`[ship] MCP enforcement (${mode}) does NOT cover external ${label} (${abs}) — edits there are unguarded in v1.`);
+            }
+          }
           const events = readEvents(cwd, { since: context.buildStartedAt });
           const { violations } = scanGuarded({
             dirtyFiles: featureFiles,
@@ -2427,9 +2727,12 @@ export async function executeShipStep(featureCode, agentCwd, cwd, context, descr
         await recordCompletion(cwd, {
           feature_code: featureCode,
           commit_sha: sha,
-          tests_pass: true,
+          // COMP-TEST-BOOTSTRAP-4: derived from the parsed test run above
+          // (true when unparseable — never a false block).
+          tests_pass: testsPass,
           files_changed: filesChanged,
           notes: shortDesc,
+          ...(builtVia ? { built_via: builtVia } : {}),
         });
         if (progress) progress.toolUse('ship', `Recorded completion for ${featureCode}`);
       } catch (err) {
@@ -2441,6 +2744,11 @@ export async function executeShipStep(featureCode, agentCwd, cwd, context, descr
       }
     }
 
+    // COMP-PATHS-EXTERNAL D6a: if ROADMAP / the feature folder resolved into a
+    // DIFFERENT git repo, they were written but not committed here — tell the
+    // user to commit them there (v1 does not auto-commit other repos).
+    noticeExternalArtifacts(cwd, featureCode, gitToplevel(agentCwd));
+
     return {
       phase: 'ship',
       artifact: sha ?? '',
@@ -2907,7 +3215,8 @@ export async function executeChildFlow(
         });
       }
       const violations = resp.violations ?? [];
-      if (violations.length > 0 && progress) progress.findings(violations);
+      // STRAT-VOCAB-3: surface vocabulary violations as must-fix (they block ship).
+      if (violations.length > 0 && progress) progress.findings(tagVocabularyViolations(violations));
       // STRAT-REV-5: flow-step ensures fire here (inside executeChildFlow), not in the
       // main dispatch loop — persist dirty lenses so triage selectively re-runs on retry.
       if (resp.step_id === 'review') {
@@ -2918,7 +3227,14 @@ export async function executeChildFlow(
         }
       }
       const stepAgent = resp.agent ?? 'claude';
-      const fixAgent = stepAgent === 'codex' ? 'claude' : stepAgent;
+      // COMP-CODEX-IMPL: the fixer is the IMPLEMENTER — whoever wrote the code fixes
+      // the review findings against it. This replaces the old hardcoded
+      // `stepAgent === 'codex' ? 'claude' : stepAgent` swap, which assumed codex is
+      // always the reviewer and claude always the implementer; that assumption inverts
+      // under --codex. Default (implementer=claude) reproduces the old outcome exactly:
+      // a codex reviewer's finding is fixed by claude, the implementer. (stepAgent is
+      // still the reviewer, used for the retry display below.)
+      const fixAgent = context.implementerAgent || 'claude';
 
       if (progress) {
         progress.fix(childFlowName, fixAgent, resp.step_id);
@@ -4299,7 +4615,7 @@ export async function executeParallelDispatch(
   }
 }
 
-export async function startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode = 'feature', preMergeGate) {
+export async function startFresh(stratum, specYaml, featureCode, description, dataDir, templateName, mode = 'feature', preMergeGate, roles) {
   const flowName = extractFlowName(specYaml, templateName);
   console.log(`Starting ${flowName} for ${featureCode}...`);
   // COMP-FIX-HARD T4: bug-mode flows take input as { task: <description> }
@@ -4308,9 +4624,14 @@ export async function startFresh(stratum, specYaml, featureCode, description, da
   // COMP-PAR-MERGE-QUEUE-CONSUMER-RETRY (D5): fold pre_merge_gate into the
   // feature plan envelope ONLY when resolved (undefined ⇒ key omitted, not [])
   // so the default-OFF path is byte-identical to pre-feature behavior.
+  // COMP-CODEX-IMPL: feature flows always carry implementer_agent/reviewer_agent so
+  // the interpolated execute/review agents (STRAT-AGENT-INTERP) always resolve.
+  // Defaults reproduce today's behavior (claude implements, codex reviews) byte-identically.
+  const implementerAgent = roles?.implementerAgent ?? 'claude';
+  const reviewerAgent = roles?.reviewerAgent ?? 'codex';
   const planInputs = mode === 'bug'
     ? { task: description }
-    : { featureCode, description, ...(preMergeGate !== undefined ? { pre_merge_gate: preMergeGate } : {}) };
+    : { featureCode, description, implementer_agent: implementerAgent, reviewer_agent: reviewerAgent, ...(preMergeGate !== undefined ? { pre_merge_gate: preMergeGate } : {}) };
   const response = await stratum.plan(specYaml, flowName, planInputs);
 
   writeActiveBuild(dataDir, {
@@ -4327,6 +4648,10 @@ export async function startFresh(stratum, specYaml, featureCode, description, da
     violations: [],
     status: 'running',
     startedAt: new Date().toISOString(),
+    // COMP-CODEX-IMPL: roles are durable across resume (the build context is rebuilt
+    // locally each invocation, so a resume without --codex must restore them).
+    implementerAgent,
+    reviewerAgent,
   });
 
   return response;