fix(ri-050): forge fails closed without providers; explicit typed simulation (#1275)

Reviewed-on: #1270

eslint.config.mjs

@@ -34,6 +34,7 @@ export default tseslint.config(
             'packages/storage/vitest.config.ts',
             'packages/mosaic/vitest.config.ts',
             'packages/mosaic/__tests__/*.ts',
+            'packages/forge/__tests__/*.ts',
             'tools/federation-harness/*.ts',
           ],
         },

packages/forge/PLAN.md

@@ -539,3 +539,43 @@ Not every brief needs full Board of Directors review. The classification system
 ### Backward compatibility
 
 Existing briefs without a `class` field are auto-classified. The default (no matching keywords) is `strategic`, so all existing runs get the full pipeline unless keywords trigger `technical`.
+
+---
+
+## Fail-Closed Execution & Explicit Simulation (SDLC-D-035)
+
+**Added:** 2026-08-17
+
+Forge fails closed when a required capability is missing. It never runs a
+pipeline with a stub executor and reports success.
+
+### Normal mode (default)
+
+- No task executor wired → the CLI exits nonzero with the typed capability
+  error `FORGE_NO_EXECUTOR`. No run is created.
+- A stage whose gate is approval-based (board approval, planning approvals,
+  remediation re-review, discovery/analysis attestations) records a typed
+  `waiting-for-authority` stage result and raises `FORGE_AUTHORITY_REQUIRED`.
+  It never passes vacuously.
+- A stage whose gate requires an unwired provider (AI reviewer, CI pipeline)
+  records a typed `blocked` stage result and raises `FORGE_NO_REVIEWER` /
+  `FORGE_NO_CI_PIPELINE`. The synthetic echo-review approval in `06-review`
+  and all vacuous `true` gates were removed.
+
+### Explicit simulation (`--simulate`)
+
+Opts into stub/synthetic execution. Every stage result, every gate result, and
+the run manifest carry the distinct typed status `simulated` (manifest also
+records `mode: "simulated"`). `simulated` is a non-satisfying outcome:
+`isSatisfyingOutcome()` and all completion/gate consumers treat only `passed`
+as satisfying. The CLI exits 0 for a simulated run only because the caller
+explicitly passed `--simulate`, and prints a loud SIMULATED banner.
+
+### Typed outcome model
+
+Every gate/task outcome is one of the closed set
+`passed | failed | blocked | error | waiting-for-authority | simulated |
+not-applicable`, with the reason recorded on the stage status and each gate
+result in `manifest.json`. Missing implementations, missing gate evidence,
+unknown stages, process errors, and timeouts map to fail-closed members —
+never to `passed`.

packages/forge/__tests__/fail-closed.test.ts

@@ -0,0 +1,319 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+
+import { generateBoardTasks } from '../src/board-tasks.js';
+import { STAGE_SPECS } from '../src/constants.js';
+import { ForgeCapabilityError } from '../src/errors.js';
+import {
+  evaluateStageGates,
+  gateLabel,
+  isCommandGate,
+  isSatisfyingOutcome,
+} from '../src/outcomes.js';
+import { loadManifest, runPipeline } from '../src/pipeline-runner.js';
+import type { ForgeTask, ForgeTaskResult, TaskExecutor } from '../src/types.js';
+
+/**
+ * Mock real executor that returns typed results.
+ *
+ * Command gates are "verified" by the mock so normal-mode runs can pass
+ * mechanically gated stages; authority/provider gates are never reported
+ * because they have no mechanical implementation.
+ */
+function createTypedExecutor(options?: {
+  failStage?: string;
+  gateOutcomes?: Record<string, 'passed' | 'failed' | 'simulated' | 'error' | 'blocked'>;
+}): TaskExecutor & { submittedTasks: ForgeTask[] } {
+  const submittedTasks: ForgeTask[] = [];
+  return {
+    submittedTasks,
+    async submitTask(task: ForgeTask) {
+      submittedTasks.push(task);
+    },
+    async waitForCompletion(taskId: string): Promise<ForgeTaskResult> {
+      const task = submittedTasks.find((t) => t.id === taskId);
+      const stageName = task?.metadata?.['stageName'] as string | undefined;
+
+      if (options?.failStage && stageName === options.failStage) {
+        return {
+          task_id: taskId,
+          outcome: 'failed',
+          reason: 'mock task failure',
+          completed_at: new Date().toISOString(),
+          exit_code: 1,
+          gate_results: [],
+        };
+      }
+
+      const gateResults = (task?.qualityGates ?? [])
+        .filter((gate) => isCommandGate(gate))
+        .map((gate) => {
+          const label = gateLabel(gate);
+          const outcome = options?.gateOutcomes?.[label] ?? 'passed';
+          return {
+            gate: label,
+            outcome,
+            reason: outcome === 'passed' ? 'mock verified' : `mock gate outcome: ${outcome}`,
+          };
+        });
+
+      return {
+        task_id: taskId,
+        outcome: 'passed',
+        reason: 'mock verified',
+        completed_at: new Date().toISOString(),
+        exit_code: 0,
+        gate_results: gateResults,
+      };
+    },
+    async getTaskStatus() {
+      return 'completed' as const;
+    },
+  };
+}
+
+describe('fail-closed: no executor wired', () => {
+  let tmpDir: string;
+  let briefPath: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'forge-failclosed-'));
+    briefPath = path.join(tmpDir, 'brief.md');
+    fs.writeFileSync(briefPath, '# Fix bug\n\nA bugfix for lint cleanup.');
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('throws a typed FORGE_NO_EXECUTOR capability error without --simulate', async () => {
+    await expect(
+      runPipeline(briefPath, tmpDir, {
+        // no executor, no simulate — must fail closed, never run with a stub
+        stages: ['00-intake'],
+      }),
+    ).rejects.toMatchObject({
+      name: 'ForgeCapabilityError',
+      code: 'FORGE_NO_EXECUTOR',
+      capability: 'task-executor',
+    });
+  });
+
+  it('does not create a run directory when failing closed on a missing executor', async () => {
+    try {
+      await runPipeline(briefPath, tmpDir, { stages: ['00-intake'] });
+    } catch {
+      // expected
+    }
+    expect(fs.existsSync(path.join(tmpDir, '.forge', 'runs'))).toBe(false);
+  });
+
+  it('completes with every result typed simulated when simulate is set', async () => {
+    const result = await runPipeline(briefPath, tmpDir, {
+      simulate: true,
+      stages: ['00-intake', '00b-discovery', '02-planning-1', '06-review'],
+    });
+
+    expect(result.manifest.mode).toBe('simulated');
+    expect(result.manifest.status).toBe('simulated');
+
+    for (const stage of result.stages) {
+      const stageStatus = result.manifest.stages[stage];
+      expect(stageStatus?.status, `stage ${stage}`).toBe('simulated');
+      expect(stageStatus?.status, `stage ${stage}`).not.toBe('passed');
+      expect(stageStatus?.reason, `stage ${stage}`).toBeTruthy();
+      for (const gateResult of stageStatus?.gateResults ?? []) {
+        expect(gateResult.outcome, `gate ${gateResult.gate} of ${stage}`).toBe('simulated');
+        expect(gateResult.outcome, `gate ${gateResult.gate} of ${stage}`).not.toBe('passed');
+      }
+    }
+
+    // The persisted manifest agrees.
+    const persisted = loadManifest(result.runDir);
+    expect(persisted.mode).toBe('simulated');
+    expect(persisted.status).toBe('simulated');
+    expect(persisted.stages['02-planning-1']?.status).toBe('simulated');
+  });
+});
+
+describe('fail-closed: typed outcome model', () => {
+  it('only passed satisfies the gate/dependency predicate', () => {
+    expect(isSatisfyingOutcome('passed')).toBe(true);
+    expect(isSatisfyingOutcome('failed')).toBe(false);
+    expect(isSatisfyingOutcome('blocked')).toBe(false);
+    expect(isSatisfyingOutcome('error')).toBe(false);
+    expect(isSatisfyingOutcome('waiting-for-authority')).toBe(false);
+    expect(isSatisfyingOutcome('simulated')).toBe(false);
+    expect(isSatisfyingOutcome('not-applicable')).toBe(false);
+  });
+
+  it('a simulated gate result cannot satisfy the stage gate evaluation', () => {
+    const evaluation = evaluateStageGates('05-coding', STAGE_SPECS['05-coding']!.qualityGates, {
+      task_id: 'FORGE-x-05',
+      outcome: 'passed',
+      reason: 'executor claims success',
+      completed_at: new Date().toISOString(),
+      exit_code: 0,
+      gate_results: [{ gate: 'pnpm lint', outcome: 'simulated', reason: 'simulated gate' }],
+    });
+    expect(isSatisfyingOutcome(evaluation.outcome)).toBe(false);
+    expect(evaluation.outcome).toBe('error');
+  });
+
+  it('a simulated task outcome cannot satisfy evaluation in normal mode', () => {
+    const evaluation = evaluateStageGates('00-intake', [], {
+      task_id: 'FORGE-x-00',
+      outcome: 'simulated',
+      reason: 'executor reported simulated',
+      completed_at: new Date().toISOString(),
+      exit_code: 0,
+      gate_results: [],
+    });
+    expect(isSatisfyingOutcome(evaluation.outcome)).toBe(false);
+  });
+
+  it('a missing gate result blocks the stage instead of passing vacuously', () => {
+    const evaluation = evaluateStageGates('05-coding', STAGE_SPECS['05-coding']!.qualityGates, {
+      task_id: 'FORGE-x-05',
+      outcome: 'passed',
+      reason: 'executor claims success',
+      completed_at: new Date().toISOString(),
+      exit_code: 0,
+      gate_results: [],
+    });
+    expect(evaluation.outcome).toBe('blocked');
+  });
+});
+
+describe('fail-closed: authority and provider gates', () => {
+  let tmpDir: string;
+  let briefPath: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'forge-authority-'));
+    briefPath = path.join(tmpDir, 'brief.md');
+    fs.writeFileSync(briefPath, '# Fix bug\n\nA bugfix for lint cleanup.');
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it.each(['02-planning-1', '03-planning-2', '04-planning-3', '07-remediate'])(
+    'planning/remediation stage %s yields waiting-for-authority (not passed) in normal mode',
+    async (stage) => {
+      const executor = createTypedExecutor();
+      let runDir: string | undefined;
+
+      try {
+        await runPipeline(briefPath, tmpDir, {
+          executor,
+          stages: [stage as string],
+        });
+        expect.unreachable('runPipeline should have failed closed');
+      } catch (err) {
+        expect(err).toBeInstanceOf(ForgeCapabilityError);
+        expect((err as ForgeCapabilityError).code).toBe('FORGE_AUTHORITY_REQUIRED');
+        runDir = path.join(tmpDir, '.forge', 'runs');
+      }
+
+      const runIds = fs.readdirSync(runDir!);
+      expect(runIds).toHaveLength(1);
+      const manifest = loadManifest(path.join(runDir!, runIds[0]!));
+      expect(manifest.stages[stage]?.status).toBe('waiting-for-authority');
+      expect(manifest.stages[stage]?.status).not.toBe('passed');
+      expect(manifest.status).toBe('waiting-for-authority');
+    },
+  );
+
+  it('review stage fails closed with a typed FORGE_NO_REVIEWER error in normal mode', async () => {
+    const executor = createTypedExecutor();
+
+    try {
+      await runPipeline(briefPath, tmpDir, {
+        executor,
+        stages: ['06-review'],
+      });
+      expect.unreachable('runPipeline should have failed closed');
+    } catch (err) {
+      expect(err).toBeInstanceOf(ForgeCapabilityError);
+      expect((err as ForgeCapabilityError).code).toBe('FORGE_NO_REVIEWER');
+      expect((err as ForgeCapabilityError).capability).toBe('reviewer');
+    }
+
+    const runsDir = path.join(tmpDir, '.forge', 'runs');
+    const runIds = fs.readdirSync(runsDir);
+    const manifest = loadManifest(path.join(runsDir, runIds[0]!));
+    expect(manifest.stages['06-review']?.status).toBe('blocked');
+    expect(manifest.stages['06-review']?.status).not.toBe('passed');
+    expect(manifest.status).toBe('failed');
+  });
+
+  it('review stage produces simulated results under --simulate', async () => {
+    const result = await runPipeline(briefPath, tmpDir, {
+      simulate: true,
+      stages: ['06-review'],
+    });
+
+    expect(result.manifest.mode).toBe('simulated');
+    expect(result.manifest.stages['06-review']?.status).toBe('simulated');
+    for (const gateResult of result.manifest.stages['06-review']?.gateResults ?? []) {
+      expect(gateResult.outcome).toBe('simulated');
+    }
+  });
+
+  it('deploy stage fails closed without a wired ci-pipeline provider in normal mode', async () => {
+    const executor = createTypedExecutor();
+
+    await expect(
+      runPipeline(briefPath, tmpDir, {
+        executor,
+        stages: ['09-deploy'],
+      }),
+    ).rejects.toMatchObject({
+      name: 'ForgeCapabilityError',
+      code: 'FORGE_NO_CI_PIPELINE',
+    });
+  });
+});
+
+describe('fail-closed: no vacuous gate commands remain', () => {
+  it('stage constants contain no echo/synthetic-approval, vacuous true, or empty gate commands', () => {
+    for (const [stageName, spec] of Object.entries(STAGE_SPECS)) {
+      for (const gate of spec.qualityGates) {
+        const serialized = JSON.stringify(gate);
+        // The echo-review synthetic approval must be gone.
+        expect(serialized, `stage ${stageName} gate ${serialized}`).not.toContain('echo');
+        expect(serialized, `stage ${stageName} gate ${serialized}`).not.toMatch(/"verdict"\s*:/);
+        expect(serialized, `stage ${stageName} gate ${serialized}`).not.toMatch(
+          /"summary"\s*:\s*"review-pass"/,
+        );
+        // No vacuous literal `true` gate.
+        expect(gate, `stage ${stageName}`).not.toBe('true');
+        // Command gates must carry a real, non-empty command.
+        if (isCommandGate(gate)) {
+          const command = typeof gate === 'string' ? gate : gate.command;
+          expect(command.trim().length, `stage ${stageName} gate ${serialized}`).toBeGreaterThan(0);
+        }
+      }
+    }
+  });
+
+  it('board tasks contain no vacuous true gates', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'forge-board-gates-'));
+    try {
+      const tasks = generateBoardTasks('# Brief', [], tmpDir, 'BOARD-TEST');
+      for (const task of tasks) {
+        for (const gate of task.qualityGates) {
+          expect(gate, `task ${task.id}`).not.toBe('true');
+          const serialized = JSON.stringify(gate);
+          expect(serialized, `task ${task.id} gate ${serialized}`).not.toContain('echo');
+        }
+      }
+    } finally {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+});

packages/forge/__tests__/pipeline-runner.test.ts

@@ -12,10 +12,10 @@ import {
   resumePipeline,
   getPipelineStatus,
 } from '../src/pipeline-runner.js';
-import type { ForgeTask, RunManifest, TaskExecutor } from '../src/types.js';
+import type { ForgeTask, ForgeTaskResult, RunManifest, TaskExecutor } from '../src/types.js';
-import type { TaskResult } from '@mosaicstack/macp';
+import { gateLabel, isCommandGate } from '../src/outcomes.js';
 
-/** Mock TaskExecutor that records submitted tasks and returns success. */
+/** Mock TaskExecutor that records submitted tasks and returns typed results. */
 function createMockExecutor(options?: {
   failStage?: string;
 }): TaskExecutor & { submittedTasks: ForgeTask[] } {
@@ -25,7 +25,7 @@ function createMockExecutor(options?: {
     async submitTask(task: ForgeTask) {
       submittedTasks.push(task);
     },
-    async waitForCompletion(taskId: string): Promise<TaskResult> {
+    async waitForCompletion(taskId: string): Promise<ForgeTaskResult> {
       const failStage = options?.failStage;
       const task = submittedTasks.find((t) => t.id === taskId);
       const stageName = task?.metadata?.['stageName'] as string | undefined;
@@ -33,7 +33,8 @@ function createMockExecutor(options?: {
       if (failStage && stageName === failStage) {
         return {
           task_id: taskId,
-          status: 'failed',
+          outcome: 'failed',
+          reason: 'mock task failure',
           completed_at: new Date().toISOString(),
           exit_code: 1,
           gate_results: [],
@@ -41,10 +42,17 @@ function createMockExecutor(options?: {
       }
       return {
         task_id: taskId,
-        status: 'completed',
+        outcome: 'passed',
+        reason: 'mock verified',
         completed_at: new Date().toISOString(),
         exit_code: 0,
-        gate_results: [],
+        gate_results: (task?.qualityGates ?? [])
+          .filter((gate) => isCommandGate(gate))
+          .map((gate) => ({
+            gate: gateLabel(gate),
+            outcome: 'passed' as const,
+            reason: 'mock verified',
+          })),
       };
     },
     async getTaskStatus() {
@@ -156,12 +164,13 @@ describe('runPipeline', () => {
     const executor = createMockExecutor();
     const result = await runPipeline(briefPath, tmpDir, {
       executor,
-      stages: ['00-intake', '00b-discovery'],
+      stages: ['00-intake', '05-coding'],
     });
 
     expect(result.runId).toMatch(/^\d{8}-\d{6}$/);
-    expect(result.stages).toEqual(['00-intake', '00b-discovery']);
+    expect(result.stages).toEqual(['00-intake', '05-coding']);
     expect(result.manifest.status).toBe('completed');
+    expect(result.manifest.mode).toBe('normal');
     expect(executor.submittedTasks).toHaveLength(2);
   });
 
@@ -180,12 +189,17 @@ describe('runPipeline', () => {
     const executor = createMockExecutor();
     const result = await runPipeline(briefPath, tmpDir, {
       executor,
-      stages: ['00-intake', '00b-discovery'],
+      stages: ['00-intake', '05-coding'],
     });
 
     const manifest = loadManifest(result.runDir);
     expect(manifest.stages['00-intake']?.status).toBe('passed');
-    expect(manifest.stages['00b-discovery']?.status).toBe('passed');
+    expect(manifest.stages['05-coding']?.status).toBe('passed');
+    expect(manifest.stages['05-coding']?.gateResults?.map((g) => g.outcome)).toEqual([
+      'passed',
+      'passed',
+      'passed',
+    ]);
   });
 
   it('respects CLI class override', async () => {
@@ -215,7 +229,7 @@ describe('runPipeline', () => {
     const executor = createMockExecutor();
     await runPipeline(briefPath, tmpDir, {
       executor,
-      stages: ['00-intake', '00b-discovery', '02-planning-1'],
+      stages: ['00-intake', '05-coding', '08-test'],
     });
 
     expect(executor.submittedTasks[0]!.dependsOn).toBeUndefined();
@@ -224,14 +238,14 @@ describe('runPipeline', () => {
   });
 
   it('handles stage failure', async () => {
-    const executor = createMockExecutor({ failStage: '00b-discovery' });
+    const executor = createMockExecutor({ failStage: '05-coding' });
 
     await expect(
       runPipeline(briefPath, tmpDir, {
         executor,
-        stages: ['00-intake', '00b-discovery'],
+        stages: ['00-intake', '05-coding'],
       }),
-    ).rejects.toThrow('Stage 00b-discovery failed');
+    ).rejects.toThrow('Stage 05-coding failed');
   });
 
   it('marks manifest as failed on stage failure', async () => {
@@ -270,30 +284,143 @@ describe('resumePipeline', () => {
     fs.rmSync(tmpDir, { recursive: true, force: true });
   });
 
-  it('resumes from first incomplete stage', async () => {
+  it('resumes from first incomplete stage and fails closed at the next provider gate', async () => {
-    // First run fails on discovery
+    // Simulate a run whose authority stages were approved out-of-band
-    const executor1 = createMockExecutor({ failStage: '00b-discovery' });
+    // (recorded as passed) and whose coding stage failed mechanically.
-    let runDir: string;
+    const runId = '20260101-000000';
+    const runDir = path.join(tmpDir, '.forge', 'runs', runId);
+    fs.mkdirSync(runDir, { recursive: true });
+    const passed = { status: 'passed' as const, startedAt: '2026-01-01T00:00:00Z' };
+    saveManifest(runDir, {
+      runId,
+      brief: briefPath,
+      codebase: tmpDir,
+      briefClass: 'hotfix',
+      classSource: 'frontmatter',
+      forceBoard: false,
+      mode: 'normal',
+      createdAt: '2026-01-01T00:00:00Z',
+      updatedAt: '2026-01-01T00:00:00Z',
+      currentStage: '05-coding',
+      status: 'failed',
+      stages: {
+        '00-intake': passed,
+        '00b-discovery': passed,
+        '02-planning-1': passed,
+        '03-planning-2': passed,
+        '04-planning-3': passed,
+        '05-coding': { status: 'failed', reason: 'gate failed' },
+      },
+    });
 
-    try {
+    // Resume re-runs 05-coding (the first non-passed stage), then fails
-      await runPipeline(briefPath, tmpDir, {
+    // closed at 06-review because no reviewer provider is wired.
-        executor: executor1,
+    const executor = createMockExecutor();
-        stages: ['00-intake', '00b-discovery', '02-planning-1'],
+    await expect(resumePipeline(runDir, executor)).rejects.toMatchObject({
-      });
+      name: 'ForgeCapabilityError',
-    } catch {
+      code: 'FORGE_NO_REVIEWER',
-      // expected
+    });
+
+    const manifest = loadManifest(runDir);
+    expect(manifest.stages['05-coding']?.status).toBe('passed');
+    expect(manifest.stages['06-review']?.status).toBe('blocked');
+    expect(manifest.status).toBe('failed');
+  });
+
+  it('resumes to completion as simulated under explicit simulate', async () => {
+    const runId = '20260101-000003';
+    const runDir = path.join(tmpDir, '.forge', 'runs', runId);
+    fs.mkdirSync(runDir, { recursive: true });
+    const passed = { status: 'passed' as const, startedAt: '2026-01-01T00:00:00Z' };
+    saveManifest(runDir, {
+      runId,
+      brief: briefPath,
+      codebase: tmpDir,
+      briefClass: 'hotfix',
+      classSource: 'frontmatter',
+      forceBoard: false,
+      mode: 'normal',
+      createdAt: '2026-01-01T00:00:00Z',
+      updatedAt: '2026-01-01T00:00:00Z',
+      currentStage: '05-coding',
+      status: 'failed',
+      stages: {
+        '00-intake': passed,
+        '00b-discovery': passed,
+        '02-planning-1': passed,
+        '03-planning-2': passed,
+        '04-planning-3': passed,
+        '05-coding': { status: 'failed', reason: 'gate failed' },
+      },
+    });
+
+    const result = await resumePipeline(runDir, undefined, { simulate: true });
+
+    expect(result.manifest.status).toBe('simulated');
+    expect(result.manifest.mode).toBe('simulated');
+    expect(result.stages[0]).toBe('05-coding');
+    for (const stage of result.stages) {
+      expect(result.manifest.stages[stage]?.status).toBe('simulated');
     }
+  });
 
-    const runsDir = path.join(tmpDir, '.forge', 'runs');
+  it('fails closed on resume when the next stage needs authority sign-off', async () => {
-    runDir = path.join(runsDir, fs.readdirSync(runsDir)[0]!);
+    const runId = '20260101-000001';
+    const runDir = path.join(tmpDir, '.forge', 'runs', runId);
+    fs.mkdirSync(runDir, { recursive: true });
+    saveManifest(runDir, {
+      runId,
+      brief: briefPath,
+      codebase: tmpDir,
+      briefClass: 'hotfix',
+      classSource: 'frontmatter',
+      forceBoard: false,
+      mode: 'normal',
+      createdAt: '2026-01-01T00:00:00Z',
+      updatedAt: '2026-01-01T00:00:00Z',
+      currentStage: '00-intake',
+      status: 'in_progress',
+      stages: {
+        '00-intake': { status: 'passed' },
+      },
+    });
 
-    // Resume should pick up from 00b-discovery
+    const executor = createMockExecutor();
-    const executor2 = createMockExecutor();
+    await expect(resumePipeline(runDir, executor)).rejects.toMatchObject({
-    const result = await resumePipeline(runDir, executor2);
+      name: 'ForgeCapabilityError',
+      code: 'FORGE_AUTHORITY_REQUIRED',
+    });
 
-    expect(result.manifest.status).toBe('completed');
+    const manifest = loadManifest(runDir);
-    // Should have re-run from 00b-discovery onward
+    expect(manifest.stages['00b-discovery']?.status).toBe('waiting-for-authority');
-    expect(result.stages[0]).toBe('00b-discovery');
+    expect(manifest.status).toBe('waiting-for-authority');
+  });
+
+  it('fails closed on resume without an executor or --simulate', async () => {
+    const runId = '20260101-000002';
+    const runDir = path.join(tmpDir, '.forge', 'runs', runId);
+    fs.mkdirSync(runDir, { recursive: true });
+    saveManifest(runDir, {
+      runId,
+      brief: briefPath,
+      codebase: tmpDir,
+      briefClass: 'hotfix',
+      classSource: 'frontmatter',
+      forceBoard: false,
+      mode: 'normal',
+      createdAt: '2026-01-01T00:00:00Z',
+      updatedAt: '2026-01-01T00:00:00Z',
+      currentStage: '00-intake',
+      status: 'in_progress',
+      stages: {
+        '00-intake': { status: 'passed' },
+      },
+    });
+
+    await expect(resumePipeline(runDir)).rejects.toMatchObject({
+      name: 'ForgeCapabilityError',
+      code: 'FORGE_NO_EXECUTOR',
+    });
   });
 });
 

packages/forge/src/board-tasks.ts

@@ -95,7 +95,14 @@ export function generateBoardTasks(
       briefPath,
       resultPath: resultRelPath,
       timeoutSeconds: 120,
-      qualityGates: ['true'],
+      qualityGates: [
+        {
+          kind: 'authority',
+          capability: 'board-approval',
+          reason:
+            'persona evaluation is judged by board synthesis (authority review); no mechanical gate exists',
+        },
+      ],
       metadata: {
         personaName: persona.name,
         personaSlug: persona.slug,
@@ -121,7 +128,13 @@ export function generateBoardTasks(
     timeoutSeconds: 120,
     dependsOn: personaTaskIds,
     dependsOnPolicy: 'all_terminal',
-    qualityGates: ['true'],
+    qualityGates: [
+      {
+        kind: 'authority',
+        capability: 'board-approval',
+        reason: 'board synthesis is an authority decision; no mechanical gate exists',
+      },
+    ],
     metadata: {
       resultOutputPath: synthesisResult,
       inputResultPaths: personaResultPaths,

packages/forge/src/cli.spec.ts

@@ -1,7 +1,11 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import { Command } from 'commander';
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
 
 import { registerForgeCommand } from './cli.js';
+import { loadManifest } from './pipeline-runner.js';
 
 describe('registerForgeCommand', () => {
   it('registers a "forge" command on the parent program', () => {
@@ -55,3 +59,94 @@ describe('registerForgeCommand', () => {
     }).not.toThrow();
   });
 });
+
+describe('forge run fail-closed behavior (SDLC-D-035)', () => {
+  let tmpDir: string;
+  let briefPath: string;
+  let errSpy: ReturnType<typeof vi.spyOn>;
+  let logSpy: ReturnType<typeof vi.spyOn>;
+  let prevExitCode: string | number | null | undefined;
+
+  const parse = (args: string[]) => {
+    const program = new Command();
+    registerForgeCommand(program);
+    return program.parseAsync(['forge', ...args], { from: 'user' });
+  };
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'forge-cli-failclosed-'));
+    briefPath = path.join(tmpDir, 'brief.md');
+    fs.writeFileSync(briefPath, '# Fix bug\n\nA bugfix for lint cleanup.');
+    errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    prevExitCode = process.exitCode;
+  });
+
+  afterEach(() => {
+    errSpy.mockRestore();
+    logSpy.mockRestore();
+    process.exitCode = prevExitCode;
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it('exits nonzero with a typed FORGE_NO_EXECUTOR error when no executor is wired and --simulate is absent', async () => {
+    await parse(['run', '--brief', briefPath, '--codebase', tmpDir]);
+
+    expect(process.exitCode).toBe(1);
+    const errText = errSpy.mock.calls.map((c) => c.join(' ')).join('\n');
+    expect(errText).toContain('FORGE_NO_EXECUTOR');
+    // It must never run the pipeline with a stub and report success.
+    expect(fs.existsSync(path.join(tmpDir, '.forge', 'runs'))).toBe(false);
+  });
+
+  it('completes with typed simulated results and exit 0 under explicit --simulate', async () => {
+    await parse(['run', '--brief', briefPath, '--codebase', tmpDir, '--simulate']);
+
+    expect(process.exitCode).toBeUndefined();
+
+    // Loud simulated-mode summary.
+    const logText = logSpy.mock.calls.map((c) => c.join(' ')).join('\n');
+    expect(logText).toContain('SIMULATED');
+
+    // Manifest records the mode and simulated per-result statuses.
+    const runsDir = path.join(tmpDir, '.forge', 'runs');
+    const runIds = fs.readdirSync(runsDir);
+    expect(runIds).toHaveLength(1);
+    const manifest = loadManifest(path.join(runsDir, runIds[0]!));
+    expect(manifest.mode).toBe('simulated');
+    expect(manifest.status).toBe('simulated');
+    for (const stageStatus of Object.values(manifest.stages)) {
+      expect(stageStatus?.status).toBe('simulated');
+      for (const gateResult of stageStatus?.gateResults ?? []) {
+        expect(gateResult.outcome).toBe('simulated');
+      }
+    }
+  });
+
+  it('resume exits nonzero with a typed FORGE_NO_EXECUTOR error without --simulate', async () => {
+    const runDir = path.join(tmpDir, '.forge', 'runs', '20260101-000000');
+    fs.mkdirSync(runDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(runDir, 'manifest.json'),
+      JSON.stringify({
+        runId: '20260101-000000',
+        brief: briefPath,
+        codebase: tmpDir,
+        briefClass: 'hotfix',
+        classSource: 'frontmatter',
+        forceBoard: false,
+        createdAt: '2026-01-01T00:00:00Z',
+        updatedAt: '2026-01-01T00:00:00Z',
+        currentStage: '00-intake',
+        status: 'in_progress',
+        stages: { '00-intake': { status: 'passed' } },
+      }),
+    );
+
+    await parse(['resume', '20260101-000000', '--project', tmpDir]);
+
+    expect(process.exitCode).toBe(1);
+    const errText = errSpy.mock.calls.map((c) => c.join(' ')).join('\n');
+    expect(errText).toContain('FORGE_NO_EXECUTOR');
+  });
+});

packages/forge/src/cli.ts

@@ -5,37 +5,47 @@ import type { Command } from 'commander';
 
 import { classifyBrief } from './brief-classifier.js';
 import { STAGE_LABELS, STAGE_SEQUENCE } from './constants.js';
+import { ForgeCapabilityError } from './errors.js';
 import { getEffectivePersonas, loadBoardPersonas } from './persona-loader.js';
 import { generateRunId, getPipelineStatus, loadManifest, runPipeline } from './pipeline-runner.js';
-import type { PipelineOptions, RunManifest, TaskExecutor } from './types.js';
+import { createSimulatedExecutor } from './simulated-executor.js';
-
+import type { PipelineOptions, RunManifest, RunMode } from './types.js';
-// ---------------------------------------------------------------------------
-// Stub executor — used when no real executor is wired at CLI invocation time.
-// ---------------------------------------------------------------------------
-
-const stubExecutor: TaskExecutor = {
-  async submitTask(task) {
-    console.log(`  [forge] stage submitted: ${task.id} (${task.title})`);
-  },
-  async waitForCompletion(taskId, _timeoutMs) {
-    console.log(`  [forge] stage complete:  ${taskId}`);
-    return {
-      task_id: taskId,
-      status: 'completed' as const,
-      completed_at: new Date().toISOString(),
-      exit_code: 0,
-      gate_results: [],
-    };
-  },
-  async getTaskStatus(_taskId) {
-    return 'completed' as const;
-  },
-};
 
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
+/** Resolve a run's effective mode, defaulting legacy manifests to normal. */
+function runModeOf(manifest: RunManifest): RunMode {
+  return manifest.mode ?? 'normal';
+}
+
+/** Print a loud banner so a simulated run can never be misread as verified. */
+function printSimulatedBanner(): void {
+  console.log('');
+  console.log('[forge] ===============================================================');
+  console.log('[forge] MODE: SIMULATED — no stage or gate was really executed.');
+  console.log('[forge] All results are synthetic and MUST NOT be read as verified');
+  console.log('[forge] success. Wire a real executor/providers and re-run to verify.');
+  console.log('[forge] ===============================================================');
+}
+
+/** Print a typed error line for fail-closed capability errors. */
+function printCapabilityError(err: ForgeCapabilityError): void {
+  console.error(`[forge] error ${err.code}: ${err.message}`);
+  console.error(`[forge] missing capability: ${err.capability}`);
+}
+
+/** Handle a pipeline error uniformly: typed capability errors get their code. */
+function handlePipelineError(err: unknown): void {
+  if (err instanceof ForgeCapabilityError) {
+    printCapabilityError(err);
+  } else {
+    console.error(`[forge] pipeline failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  process.exitCode = 1;
+}
+
 function formatDuration(startedAt?: string, completedAt?: string): string {
   if (!startedAt || !completedAt) return '-';
   const ms = new Date(completedAt).getTime() - new Date(startedAt).getTime();
@@ -44,19 +54,24 @@ function formatDuration(startedAt?: string, completedAt?: string): string {
 }
 
 function printManifestTable(manifest: RunManifest): void {
+  const mode = runModeOf(manifest);
   console.log(`\nRun ID : ${manifest.runId}`);
   console.log(`Status : ${manifest.status}`);
+  console.log(`Mode   : ${mode}`);
+  if (mode === 'simulated') {
+    console.log('WARNING: SIMULATED RUN — results are synthetic, not verified success.');
+  }
   console.log(`Brief  : ${manifest.brief}`);
   console.log(`Class  : ${manifest.briefClass} (${manifest.classSource})`);
   console.log(`Updated: ${manifest.updatedAt}`);
   console.log('');
-  console.log('Stage'.padEnd(22) + 'Status'.padEnd(14) + 'Duration');
+  console.log('Stage'.padEnd(22) + 'Status'.padEnd(24) + 'Duration');
-  console.log('-'.repeat(50));
+  console.log('-'.repeat(60));
   for (const stage of STAGE_SEQUENCE) {
     const s = manifest.stages[stage];
     if (!s) continue;
     const label = (STAGE_LABELS[stage] ?? stage).padEnd(22);
-    const status = s.status.padEnd(14);
+    const status = s.status.padEnd(24);
     const dur = formatDuration(s.startedAt, s.completedAt);
     console.log(`${label}${status}${dur}`);
   }
@@ -90,23 +105,58 @@ function listRecentRuns(projectRoot?: string): void {
   }
 
   console.log('\nRecent runs:');
-  console.log('Run ID'.padEnd(22) + 'Status'.padEnd(14) + 'Brief');
+  console.log('Run ID'.padEnd(22) + 'Status'.padEnd(24) + 'Mode'.padEnd(12) + 'Brief');
-  console.log('-'.repeat(70));
+  console.log('-'.repeat(80));
 
   for (const runId of entries) {
     const runDir = path.join(runsDir, runId);
     try {
       const manifest = loadManifest(runDir);
-      const status = manifest.status.padEnd(14);
+      const status = manifest.status.padEnd(24);
+      const mode = runModeOf(manifest).padEnd(12);
       const brief = path.basename(manifest.brief);
-      console.log(`${runId.padEnd(22)}${status}${brief}`);
+      console.log(`${runId.padEnd(22)}${status}${mode}${brief}`);
     } catch {
-      console.log(`${runId.padEnd(22)}${'(unreadable)'.padEnd(14)}`);
+      console.log(`${runId.padEnd(22)}${'(unreadable)'.padEnd(24)}`);
     }
   }
   console.log('');
 }
 
+/**
+ * Apply the exit-code policy for a finished pipeline run (SDLC-D-035):
+ *
+ * - exit 0 only for a verified `completed` normal run, or for an overall
+ *   `simulated` run when the caller explicitly passed --simulate;
+ * - anything else exits nonzero so it can never be read as success.
+ */
+function applyRunExitPolicy(result: { manifest: RunManifest; runDir: string }, simulate: boolean) {
+  const { manifest } = result;
+
+  if (runModeOf(manifest) === 'simulated') {
+    if (!simulate || manifest.status !== 'simulated') {
+      console.error(
+        '[forge] error FORGE_MODE_MISMATCH: run reports simulated results without an explicit, ' +
+          'consistent --simulate request; refusing to report success.',
+      );
+      process.exitCode = 1;
+      return;
+    }
+    printSimulatedBanner();
+    console.log(`[forge] run directory: ${result.runDir}`);
+    return; // exit 0 — the caller explicitly opted into simulation
+  }
+
+  if (manifest.status !== 'completed') {
+    console.error(`[forge] run did not complete: terminal status '${manifest.status}'`);
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log(`[forge] pipeline complete (mode: normal): ${manifest.runId}`);
+  console.log(`[forge] run directory: ${result.runDir}`);
+}
+
 // ---------------------------------------------------------------------------
 // Register function
 // ---------------------------------------------------------------------------
@@ -129,6 +179,11 @@ export function registerForgeCommand(parent: Command): void {
     .option('--config <path>', 'Path to forge config file (.forge/config.yaml)')
     .option('--codebase <path>', 'Codebase root to pass to the pipeline', process.cwd())
     .option('--dry-run', 'Print planned stages without executing', false)
+    .option(
+      '--simulate',
+      'Simulate execution without real providers (every result is typed simulated, never verified)',
+      false,
+    )
     .action(
       async (opts: {
         brief: string;
@@ -137,6 +192,7 @@ export function registerForgeCommand(parent: Command): void {
         config?: string;
         codebase: string;
         dryRun: boolean;
+        simulate: boolean;
       }) => {
         const briefPath = path.resolve(opts.brief);
 
@@ -149,14 +205,22 @@ export function registerForgeCommand(parent: Command): void {
         const briefContent = fs.readFileSync(briefPath, 'utf-8');
         const briefClass = classifyBrief(briefContent);
         const projectRoot = opts.codebase;
+        // A real executor is never wired at CLI invocation time today, so the
+        // only executor we may construct is the explicitly-requested simulated
+        // one. Normal mode fails closed with FORGE_NO_EXECUTOR.
+        const executor = opts.simulate ? createSimulatedExecutor() : undefined;
 
         if (opts.resume) {
           const runId = opts.runId ?? generateRunId();
           const runDir = resolveRunDir(runId, projectRoot);
           console.log(`[forge] resuming run: ${runId}`);
-          const { resumePipeline } = await import('./pipeline-runner.js');
+          try {
-          const result = await resumePipeline(runDir, stubExecutor);
+            const { resumePipeline } = await import('./pipeline-runner.js');
-          console.log(`[forge] pipeline complete: ${result.runId}`);
+            const result = await resumePipeline(runDir, executor, { simulate: opts.simulate });
+            applyRunExitPolicy(result, opts.simulate);
+          } catch (err) {
+            handlePipelineError(err);
+          }
           return;
         }
 
@@ -164,7 +228,8 @@ export function registerForgeCommand(parent: Command): void {
           briefClass,
           codebase: projectRoot,
           dryRun: opts.dryRun,
-          executor: stubExecutor,
+          executor,
+          simulate: opts.simulate,
         };
 
         if (opts.dryRun) {
@@ -180,16 +245,15 @@ export function registerForgeCommand(parent: Command): void {
 
         console.log(`[forge] starting pipeline for brief: ${briefPath}`);
         console.log(`[forge] classified as: ${briefClass}`);
+        if (opts.simulate) {
+          console.log('[forge] mode: SIMULATED (explicit --simulate)');
+        }
 
         try {
           const result = await runPipeline(briefPath, projectRoot, pipelineOptions);
-          console.log(`[forge] pipeline complete: ${result.runId}`);
+          applyRunExitPolicy(result, opts.simulate);
-          console.log(`[forge] run directory: ${result.runDir}`);
         } catch (err) {
-          console.error(
+          handlePipelineError(err);
-            `[forge] pipeline failed: ${err instanceof Error ? err.message : String(err)}`,
-          );
-          process.exitCode = 1;
         }
       },
     );
@@ -224,7 +288,12 @@ export function registerForgeCommand(parent: Command): void {
     .command('resume <runId>')
     .description('Resume a stopped or failed pipeline run')
     .option('--project <path>', 'Project root (defaults to cwd)', process.cwd())
-    .action(async (runId: string, opts: { project: string }) => {
+    .option(
+      '--simulate',
+      'Simulate execution without real providers (every result is typed simulated, never verified)',
+      false,
+    )
+    .action(async (runId: string, opts: { project: string; simulate: boolean }) => {
       const runDir = resolveRunDir(runId, opts.project);
 
       if (!fs.existsSync(runDir)) {
@@ -234,15 +303,20 @@ export function registerForgeCommand(parent: Command): void {
       }
 
       console.log(`[forge] resuming run: ${runId}`);
+      if (opts.simulate) {
+        console.log('[forge] mode: SIMULATED (explicit --simulate)');
+      }
+
+      // No real executor is wired at CLI invocation time; only the explicitly
+      // requested simulated executor may be constructed (fail closed otherwise).
+      const executor = opts.simulate ? createSimulatedExecutor() : undefined;
 
       try {
         const { resumePipeline } = await import('./pipeline-runner.js');
-        const result = await resumePipeline(runDir, stubExecutor);
+        const result = await resumePipeline(runDir, executor, { simulate: opts.simulate });
-        console.log(`[forge] pipeline complete: ${result.runId}`);
+        applyRunExitPolicy(result, opts.simulate);
-        console.log(`[forge] run directory: ${result.runDir}`);
       } catch (err) {
-        console.error(`[forge] resume failed: ${err instanceof Error ? err.message : String(err)}`);
+        handlePipelineError(err);
-        process.exitCode = 1;
       }
     });
 

packages/forge/src/constants.ts

@@ -9,7 +9,16 @@ export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.
 /** Pipeline asset directory (stages, agents, rails, gates, templates). */
 export const PIPELINE_DIR = path.join(PACKAGE_ROOT, 'pipeline');
 
-/** Stage specifications — defines every pipeline stage. */
+/** Stage specifications — defines every pipeline stage.
+ *\n * Gate semantics (SDLC-D-035): every gate is one of
+ * - a real command string / GateEntry a mechanical runner can execute,
+ * - an `authority` gate (human/board sign-off; produces waiting-for-authority),
+ * - a `provider` gate (requires a wired provider such as a reviewer or CI pipeline).
+ *
+ * Vacuous gates (`true`, echo'd synthetic approvals, placeholder ci-pipeline
+ * commands) are forbidden: a stage whose gate has no real implementation
+ * fails closed instead of passing.
+ */
 export const STAGE_SPECS: Record<string, StageSpec> = {
   '00-intake': {
     number: '00',
@@ -27,7 +36,13 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
     type: 'research',
     gate: 'discovery-complete',
     promptFile: '00b-discovery.md',
-    qualityGates: ['true'],
+    qualityGates: [
+      {
+        kind: 'authority',
+        capability: 'discovery-complete',
+        reason: 'discovery completion is attested by an authority; no mechanical check exists',
+      },
+    ],
   },
   '01-board': {
     number: '01',
@@ -36,7 +51,13 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
     type: 'review',
     gate: 'board-approval',
     promptFile: '01-board.md',
-    qualityGates: [{ type: 'ci-pipeline', command: 'board-approval (via board-tasks)' }],
+    qualityGates: [
+      {
+        kind: 'authority',
+        capability: 'board-approval',
+        reason: 'board approval is a board/human decision; no mechanical gate exists',
+      },
+    ],
   },
   '01b-brief-analyzer': {
     number: '01b',
@@ -45,7 +66,13 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
     type: 'research',
     gate: 'brief-analysis-complete',
     promptFile: '01-board.md',
-    qualityGates: ['true'],
+    qualityGates: [
+      {
+        kind: 'authority',
+        capability: 'brief-analysis-complete',
+        reason: 'brief analysis completion is attested by an authority; no mechanical check exists',
+      },
+    ],
   },
   '02-planning-1': {
     number: '02',
@@ -54,7 +81,13 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
     type: 'research',
     gate: 'architecture-approval',
     promptFile: '02-planning-1-architecture.md',
-    qualityGates: ['true'],
+    qualityGates: [
+      {
+        kind: 'authority',
+        capability: 'architecture-approval',
+        reason: 'ADR approval requires authority sign-off; no mechanical check exists',
+      },
+    ],
   },
   '03-planning-2': {
     number: '03',
@@ -63,7 +96,14 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
     type: 'research',
     gate: 'implementation-approval',
     promptFile: '03-planning-2-implementation.md',
-    qualityGates: ['true'],
+    qualityGates: [
+      {
+        kind: 'authority',
+        capability: 'implementation-approval',
+        reason:
+          'implementation spec approval requires authority sign-off; no mechanical check exists',
+      },
+    ],
   },
   '04-planning-3': {
     number: '04',
@@ -72,7 +112,14 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
     type: 'research',
     gate: 'decomposition-approval',
     promptFile: '04-planning-3-decomposition.md',
-    qualityGates: ['true'],
+    qualityGates: [
+      {
+        kind: 'authority',
+        capability: 'decomposition-approval',
+        reason:
+          'task decomposition approval requires authority sign-off; no mechanical check exists',
+      },
+    ],
   },
   '05-coding': {
     number: '05',
@@ -92,9 +139,10 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
     promptFile: '06-review.md',
     qualityGates: [
       {
-        type: 'ai-review',
+        kind: 'provider',
-        command:
+        capability: 'reviewer',
-          'echo \'{"summary":"review-pass","verdict":"approve","findings":[],"stats":{"blockers":0,"should_fix":0,"suggestions":0}}\'',
+        reason:
+          'review verdicts require a wired reviewer provider; synthetic approvals are not permitted',
       },
     ],
   },
@@ -105,7 +153,13 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
     type: 'coding',
     gate: 're-review',
     promptFile: '07-remediate.md',
-    qualityGates: ['true'],
+    qualityGates: [
+      {
+        kind: 'authority',
+        capability: 're-review',
+        reason: 'remediation re-review is an approval-based gate; no mechanical check exists',
+      },
+    ],
   },
   '08-test': {
     number: '08',
@@ -123,7 +177,13 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
     type: 'deploy',
     gate: 'deploy-verification',
     promptFile: '09-deploy.md',
-    qualityGates: [{ type: 'ci-pipeline', command: 'deploy-verification' }],
+    qualityGates: [
+      {
+        kind: 'provider',
+        capability: 'ci-pipeline',
+        reason: 'deploy verification requires a wired CI pipeline provider',
+      },
+    ],
   },
 };
 

packages/forge/src/errors.ts

@@ -0,0 +1,46 @@
+/**
+ * Typed fail-closed capability errors (SDLC-D-035).
+ *
+ * A Forge run must fail closed when a required capability (executor, reviewer
+ * provider, CI pipeline, authority sign-off) is missing. These typed errors
+ * name the missing capability so callers can distinguish "not wired" from
+ * ordinary execution failures.
+ */
+
+/** Closed set of typed Forge capability error codes. */
+export const FORGE_ERROR_CODES = [
+  'FORGE_NO_EXECUTOR',
+  'FORGE_NO_REVIEWER',
+  'FORGE_NO_CI_PIPELINE',
+  'FORGE_NO_PROVIDER',
+  'FORGE_AUTHORITY_REQUIRED',
+] as const;
+
+export type ForgeErrorCode = (typeof FORGE_ERROR_CODES)[number];
+
+/** Raised when a required capability is missing and the pipeline must fail closed. */
+export class ForgeCapabilityError extends Error {
+  /** Typed error code from the closed FORGE_ERROR_CODES set. */
+  readonly code: ForgeErrorCode;
+  /** The missing capability, e.g. `task-executor`, `reviewer`, `board-approval`. */
+  readonly capability: string;
+
+  constructor(code: ForgeErrorCode, capability: string, message: string) {
+    super(message);
+    this.name = 'ForgeCapabilityError';
+    this.code = code;
+    this.capability = capability;
+  }
+}
+
+/** Map a provider gate capability to its typed error code. */
+export function providerErrorCode(capability: string): ForgeErrorCode {
+  switch (capability) {
+    case 'reviewer':
+      return 'FORGE_NO_REVIEWER';
+    case 'ci-pipeline':
+      return 'FORGE_NO_CI_PIPELINE';
+    default:
+      return 'FORGE_NO_PROVIDER';
+  }
+}

packages/forge/src/index.ts

@@ -5,6 +5,13 @@ export type {
   StageSpec,
   BriefClass,
   ClassSource,
+  ForgeOutcome,
+  AuthorityGate,
+  ProviderGate,
+  ForgeGate,
+  ForgeGateResult,
+  ForgeTaskResult,
+  RunMode,
   StageStatus,
   RunManifest,
   ForgeTaskStatus,
@@ -81,5 +88,24 @@ export {
   getPipelineStatus,
 } from './pipeline-runner.js';
 
+// Fail-closed errors and typed outcome model (SDLC-D-035)
+export { FORGE_ERROR_CODES, ForgeCapabilityError, providerErrorCode } from './errors.js';
+export type { ForgeErrorCode } from './errors.js';
+export {
+  isSatisfyingOutcome,
+  isCapabilityGate,
+  isCommandGate,
+  gateLabel,
+  uniformGateResults,
+  simulatedGateResults,
+  waitingGateResults,
+  blockedGateResults,
+  evaluateStageGates,
+} from './outcomes.js';
+export type { StageEvaluation } from './outcomes.js';
+
+// Simulated executor (explicit --simulate only)
+export { createSimulatedExecutor } from './simulated-executor.js';
+
 // CLI
 export { registerForgeCommand } from './cli.js';

packages/forge/src/outcomes.ts

@@ -0,0 +1,147 @@
+import type { GateEntry } from '@mosaicstack/macp';
+
+import type {
+  AuthorityGate,
+  ForgeGate,
+  ForgeGateResult,
+  ForgeOutcome,
+  ForgeTaskResult,
+  ProviderGate,
+} from './types.js';
+
+/**
+ * Gate and dependency satisfaction predicate (SDLC-D-035).
+ *
+ * ONLY a verified `passed` outcome satisfies. Every other member of the closed
+ * outcome set — including `simulated` — is non-satisfying, so a simulated or
+ * authority-blocked result can never be read as success-by-verification.
+ */
+export function isSatisfyingOutcome(outcome: ForgeOutcome): boolean {
+  return outcome === 'passed';
+}
+
+/** Whether a gate is an authority or provider gate (capability-based, command-less). */
+export function isCapabilityGate(gate: ForgeGate): gate is AuthorityGate | ProviderGate {
+  if (typeof gate !== 'object' || gate === null) return false;
+  const kind = (gate as Record<string, unknown>)['kind'];
+  return kind === 'authority' || kind === 'provider';
+}
+
+/** Whether a gate definition carries a real command a mechanical runner can execute. */
+export function isCommandGate(gate: ForgeGate): gate is string | GateEntry {
+  if (typeof gate === 'string') {
+    return gate.trim().length > 0;
+  }
+  if (isCapabilityGate(gate)) {
+    // Authority and provider gates are satisfied by a capability, not a command.
+    return false;
+  }
+  return typeof gate.command === 'string' && gate.command.trim().length > 0;
+}
+
+/** Typed label identifying a gate in results and logs. */
+export function gateLabel(gate: ForgeGate): string {
+  if (typeof gate === 'string') return gate;
+  if (isCapabilityGate(gate)) return `${gate.kind}:${gate.capability}`;
+  return gate.command || gate.type || 'unnamed-gate';
+}
+
+/** Reason string stamped on every simulated gate result. */
+export const SIMULATED_GATE_REASON =
+  'simulated execution (--simulate): gate was not evaluated by a real implementation';
+
+/** Build typed gate results with a uniform outcome for a stage's declared gates. */
+export function uniformGateResults(
+  gates: ForgeGate[],
+  outcome: ForgeOutcome,
+  reason: string,
+): ForgeGateResult[] {
+  return gates.map((gate) => ({ gate: gateLabel(gate), outcome, reason }));
+}
+
+/** Typed simulated gate results — used exclusively in `--simulate` runs. */
+export function simulatedGateResults(gates: ForgeGate[]): ForgeGateResult[] {
+  return uniformGateResults(gates, 'simulated', SIMULATED_GATE_REASON);
+}
+
+/** Typed waiting-for-authority gate results for approval-based stages. */
+export function waitingGateResults(gates: ForgeGate[], reason: string): ForgeGateResult[] {
+  return uniformGateResults(gates, 'waiting-for-authority', reason);
+}
+
+/** Typed blocked gate results for stages whose provider capability is not wired. */
+export function blockedGateResults(gates: ForgeGate[], reason: string): ForgeGateResult[] {
+  return uniformGateResults(gates, 'blocked', reason);
+}
+
+/** Outcome of evaluating a completed stage in normal mode. */
+export interface StageEvaluation {
+  outcome: ForgeOutcome;
+  reason: string;
+  gateResults: ForgeGateResult[];
+}
+
+/**
+ * Evaluate a stage's declared gates against the executor's typed result.
+ *
+ * Fail-closed mapping:
+ * - a `simulated` task or gate outcome in normal mode maps to `error`
+ * - a missing gate result for a required command gate maps to `blocked`
+ * - a non-passing task outcome propagates as the stage outcome
+ * - only verified `passed` task and gate outcomes yield a `passed` stage
+ */
+export function evaluateStageGates(
+  stageName: string,
+  gates: ForgeGate[],
+  result: ForgeTaskResult,
+): StageEvaluation {
+  const gateResults = result.gate_results ?? [];
+
+  if (result.outcome === 'simulated') {
+    return {
+      outcome: 'error',
+      reason: `executor reported a simulated outcome for stage '${stageName}' in normal mode — refusing to treat simulated results as verified`,
+      gateResults,
+    };
+  }
+
+  if (!isSatisfyingOutcome(result.outcome)) {
+    return {
+      outcome: result.outcome,
+      reason: `task outcome is '${result.outcome}': ${result.reason}`,
+      gateResults,
+    };
+  }
+
+  for (const gate of gates) {
+    // Authority and provider gates are pre-flighted before execution; they have
+    // no mechanical result to verify here.
+    if (!isCommandGate(gate)) continue;
+
+    const label = gateLabel(gate);
+    const gateResult = gateResults.find((r) => r.gate === label);
+    if (!gateResult) {
+      return {
+        outcome: 'blocked',
+        reason: `no gate result was reported for required gate '${label}' (stage '${stageName}')`,
+        gateResults,
+      };
+    }
+    if (!isSatisfyingOutcome(gateResult.outcome)) {
+      return {
+        outcome: gateResult.outcome === 'simulated' ? 'error' : gateResult.outcome,
+        reason: `gate '${label}' outcome is '${gateResult.outcome}': ${gateResult.reason}`,
+        gateResults,
+      };
+    }
+  }
+
+  return {
+    outcome: 'passed',
+    reason:
+      gates.length === 0
+        ? "stage declares no gates; task outcome 'passed' accepted"
+        : 'all declared gates verified passed',
+    gateResults,
+  };
+}

packages/forge/src/pipeline-runner.ts

@@ -1,18 +1,33 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { STAGE_SEQUENCE } from './constants.js';
+import { STAGE_SEQUENCE, STAGE_SPECS } from './constants.js';
 import { determineBriefClass, stagesForClass } from './brief-classifier.js';
+import { ForgeCapabilityError, providerErrorCode } from './errors.js';
+import {
+  blockedGateResults,
+  evaluateStageGates,
+  isCapabilityGate,
+  simulatedGateResults,
+  waitingGateResults,
+} from './outcomes.js';
 import { mapStageToTask } from './stage-adapter.js';
+import { createSimulatedExecutor } from './simulated-executor.js';
 import type {
   ForgeTask,
+  ForgeTaskResult,
   PipelineOptions,
   PipelineResult,
   RunManifest,
+  RunMode,
   StageStatus,
   TaskExecutor,
 } from './types.js';
 
+/** Reason stamped on stages that complete under explicit simulation. */
+const SIMULATED_STAGE_REASON =
+  'simulated execution (--simulate): stage was not executed by a real executor';
+
 /**
  * Generate a timestamp-based run ID.
  */
@@ -47,6 +62,7 @@ function createManifest(opts: {
   briefClass: RunManifest['briefClass'];
   classSource: RunManifest['classSource'];
   forceBoard: boolean;
+  mode: RunMode;
   runDir: string;
 }): RunManifest {
   const ts = nowISO();
@@ -57,6 +73,7 @@ function createManifest(opts: {
     briefClass: opts.briefClass,
     classSource: opts.classSource,
     forceBoard: opts.forceBoard,
+    mode: opts.mode,
     createdAt: ts,
     updatedAt: ts,
     currentStage: '',
@@ -108,20 +125,199 @@ export function selectStages(stages?: string[], skipTo?: string): string[] {
   return selected.slice(skipIndex);
 }
 
+/**
+ * Fail closed when the required executor capability is missing (SDLC-D-035).
+ */
+function requireExecutor(executor: TaskExecutor | undefined, simulate: boolean): TaskExecutor {
+  if (executor) return executor;
+  if (simulate) return createSimulatedExecutor({ log: false });
+  throw new ForgeCapabilityError(
+    'FORGE_NO_EXECUTOR',
+    'task-executor',
+    'no task executor is wired; refusing to run the pipeline with a stub executor (fail closed). ' +
+      'Pass --simulate to opt into explicitly simulated execution.',
+  );
+}
+
+/**
+ * Pre-flight a stage's gates in normal mode (fail closed, SDLC-D-035).
+ *
+ * - authority gates: record a typed `waiting-for-authority` stage result and
+ *   raise FORGE_AUTHORITY_REQUIRED — approval-based gates never pass vacuously.
+ * - provider gates: record a typed `blocked` stage result and raise the typed
+ *   capability error for the missing provider.
+ *
+ * Returns the stage status to record when the pre-flight blocks, or undefined
+ * when the stage may proceed.
+ */
+function preflightStageGates(
+  stageName: string,
+  manifest: RunManifest,
+): { status: StageStatus; error: ForgeCapabilityError } | undefined {
+  const spec = STAGE_SPECS[stageName];
+  if (!spec) throw new Error(`Unknown Forge stage: ${stageName}`);
+
+  for (const gate of spec.qualityGates) {
+    if (!isCapabilityGate(gate)) continue;
+
+    const startedAt = manifest.stages[stageName]?.startedAt;
+    const completedAt = nowISO();
+
+    if (gate.kind === 'authority') {
+      const reason = `gate '${gate.capability}' requires authority sign-off; no mechanical implementation exists (${gate.reason})`;
+      return {
+        status: {
+          status: 'waiting-for-authority',
+          reason,
+          startedAt,
+          completedAt,
+          gateResults: waitingGateResults(spec.qualityGates, reason),
+        },
+        error: new ForgeCapabilityError(
+          'FORGE_AUTHORITY_REQUIRED',
+          gate.capability,
+          `stage '${stageName}' is blocked on authority gate '${gate.capability}': ${gate.reason}. ` +
+            'The pipeline fails closed instead of passing vacuously. Record the approval out-of-band ' +
+            'or run with --simulate for explicitly simulated execution.',
+        ),
+      };
+    }
+
+    const reason = `gate '${gate.capability}' requires provider '${gate.capability}' and none is wired (${gate.reason})`;
+    return {
+      status: {
+        status: 'blocked',
+        reason,
+        startedAt,
+        completedAt,
+        gateResults: blockedGateResults(spec.qualityGates, reason),
+      },
+      error: new ForgeCapabilityError(
+        providerErrorCode(gate.capability),
+        gate.capability,
+        `stage '${stageName}' requires provider '${gate.capability}' which is not wired: ${gate.reason}. ` +
+          'The pipeline fails closed instead of passing vacuously.',
+      ),
+    };
+  }
+
+  return undefined;
+}
+
+/**
+ * Execute the given stage tasks sequentially, updating the manifest.
+ *
+ * Normal mode requires a real executor and evaluates every declared command
+ * gate through the typed outcome model; any non-verified result fails closed.
+ * Simulate mode types every stage and gate result as `simulated`.
+ */
+async function executeStages(opts: {
+  manifest: RunManifest;
+  runDir: string;
+  tasks: ForgeTask[];
+  stageNames: string[];
+  executor: TaskExecutor;
+  simulate: boolean;
+}): Promise<void> {
+  const { manifest, runDir, tasks, stageNames, executor, simulate } = opts;
+
+  for (let i = 0; i < tasks.length; i++) {
+    const task = tasks[i]!;
+    const stageName = stageNames[i]!;
+    const spec = STAGE_SPECS[stageName];
+    if (!spec) throw new Error(`Unknown Forge stage: ${stageName}`);
+
+    // Update manifest: stage in progress
+    manifest.currentStage = stageName;
+    manifest.stages[stageName] = {
+      status: 'in_progress',
+      startedAt: nowISO(),
+    };
+    saveManifest(runDir, manifest);
+
+    // Fail-closed pre-flight (normal mode only): authority/provider gates have
+    // no mechanical implementation and must never pass vacuously.
+    if (!simulate) {
+      const blocked = preflightStageGates(stageName, manifest);
+      if (blocked) {
+        manifest.stages[stageName] = blocked.status;
+        manifest.status =
+          blocked.status.status === 'waiting-for-authority' ? 'waiting-for-authority' : 'failed';
+        saveManifest(runDir, manifest);
+        throw blocked.error;
+      }
+    }
+
+    let result: ForgeTaskResult;
+    try {
+      await executor.submitTask(task);
+      result = await executor.waitForCompletion(task.id, task.timeoutSeconds * 1000);
+    } catch (error) {
+      // Process errors (including timeouts) map to the fail-closed `error` outcome.
+      const reason = error instanceof Error ? error.message : String(error);
+      manifest.stages[stageName] = {
+        status: 'error',
+        reason: `executor error: ${reason}`,
+        startedAt: manifest.stages[stageName]?.startedAt,
+        completedAt: nowISO(),
+        gateResults: [],
+      };
+      manifest.status = 'failed';
+      saveManifest(runDir, manifest);
+      throw error instanceof Error ? error : new Error(reason);
+    }
+
+    if (simulate) {
+      manifest.stages[stageName] = {
+        status: 'simulated',
+        reason: SIMULATED_STAGE_REASON,
+        startedAt: manifest.stages[stageName]?.startedAt,
+        completedAt: nowISO(),
+        gateResults: simulatedGateResults(spec.qualityGates),
+      };
+      saveManifest(runDir, manifest);
+      continue;
+    }
+
+    const evaluation = evaluateStageGates(stageName, spec.qualityGates, result);
+    manifest.stages[stageName] = {
+      status: evaluation.outcome,
+      reason: evaluation.reason,
+      startedAt: manifest.stages[stageName]?.startedAt,
+      completedAt: nowISO(),
+      gateResults: evaluation.gateResults,
+    };
+
+    if (evaluation.outcome !== 'passed') {
+      manifest.status =
+        evaluation.outcome === 'waiting-for-authority' ? 'waiting-for-authority' : 'failed';
+      saveManifest(runDir, manifest);
+      throw new Error(`Stage ${stageName} ${evaluation.outcome}: ${evaluation.reason}`);
+    }
+
+    saveManifest(runDir, manifest);
+  }
+}
+
 /**
  * Run the Forge pipeline.
  *
- * 1. Classify the brief
+ * 1. Fail closed unless a real executor is wired or simulation is explicit
- * 2. Generate a run ID and create run directory
+ * 2. Classify the brief
- * 3. Map stages to tasks and submit to TaskExecutor
+ * 3. Generate a run ID and create run directory
- * 4. Track manifest with stage statuses
+ * 4. Map stages to tasks and submit to TaskExecutor
- * 5. Return pipeline result
+ * 5. Track manifest with typed stage outcomes
+ * 6. Return pipeline result
  */
 export async function runPipeline(
   briefPath: string,
   projectRoot: string,
   options: PipelineOptions,
 ): Promise<PipelineResult> {
+  const simulate = options.simulate ?? false;
+  const executor = requireExecutor(options.executor, simulate);
+  const mode: RunMode = simulate ? 'simulated' : 'normal';
+
   const resolvedRoot = path.resolve(projectRoot);
   const resolvedBrief = path.resolve(briefPath);
   const briefContent = fs.readFileSync(resolvedBrief, 'utf-8');
@@ -146,6 +342,7 @@ export async function runPipeline(
     briefClass,
     classSource,
     forceBoard: options.forceBoard ?? false,
+    mode,
     runDir,
   });
 
@@ -172,54 +369,10 @@ export async function runPipeline(
   }
 
   // Execute stages
-  const { executor } = options;
+  await executeStages({ manifest, runDir, tasks, stageNames: selectedStages, executor, simulate });
-  for (let i = 0; i < tasks.length; i++) {
-    const task = tasks[i]!;
-    const stageName = selectedStages[i]!;
 
-    // Update manifest: stage in progress
+  // All stages reached a terminal state for this mode
-    manifest.currentStage = stageName;
+  manifest.status = simulate ? 'simulated' : 'completed';
-    manifest.stages[stageName] = {
-      status: 'in_progress',
-      startedAt: nowISO(),
-    };
-    saveManifest(runDir, manifest);
-
-    try {
-      await executor.submitTask(task);
-      const result = await executor.waitForCompletion(task.id, task.timeoutSeconds * 1000);
-
-      // Update manifest: stage completed or failed
-      const stageStatus: StageStatus = {
-        status: result.status === 'completed' ? 'passed' : 'failed',
-        startedAt: manifest.stages[stageName]!.startedAt,
-        completedAt: nowISO(),
-      };
-      manifest.stages[stageName] = stageStatus;
-
-      if (result.status !== 'completed') {
-        manifest.status = 'failed';
-        saveManifest(runDir, manifest);
-        throw new Error(`Stage ${stageName} failed with status: ${result.status}`);
-      }
-
-      saveManifest(runDir, manifest);
-    } catch (error) {
-      if (!manifest.stages[stageName]?.completedAt) {
-        manifest.stages[stageName] = {
-          status: 'failed',
-          startedAt: manifest.stages[stageName]?.startedAt,
-          completedAt: nowISO(),
-        };
-      }
-      manifest.status = 'failed';
-      saveManifest(runDir, manifest);
-      throw error;
-    }
-  }
-
-  // All stages passed
-  manifest.status = 'completed';
   saveManifest(runDir, manifest);
 
   return {
@@ -234,22 +387,30 @@ export async function runPipeline(
 }
 
 /**
- * Resume a pipeline from the last incomplete stage.
+ * Resume a pipeline from the last non-passed stage.
  */
 export async function resumePipeline(
   runDir: string,
-  executor: TaskExecutor,
+  executor?: TaskExecutor,
+  options?: { simulate?: boolean },
 ): Promise<PipelineResult> {
+  const simulate = options?.simulate ?? false;
+  const wiredExecutor = requireExecutor(executor, simulate);
+  const mode: RunMode = simulate ? 'simulated' : 'normal';
+
   const manifest = loadManifest(runDir);
   const resolvedRoot = path.dirname(path.dirname(path.dirname(runDir))); // .forge/runs/{id} → project root
 
   const briefContent = fs.readFileSync(manifest.brief, 'utf-8');
   const allStages = stagesForClass(manifest.briefClass, manifest.forceBoard);
 
-  // Find first non-passed stage
+  manifest.mode = mode;
+
+  // Find first non-satisfying stage (only a verified `passed` counts as done;
+  // simulated and waiting-for-authority stages are re-run).
   const resumeFrom = allStages.find((s) => manifest.stages[s]?.status !== 'passed');
   if (!resumeFrom) {
-    manifest.status = 'completed';
+    manifest.status = mode === 'simulated' ? 'simulated' : 'completed';
     saveManifest(runDir, manifest);
     return {
       runId: manifest.runId,
@@ -284,49 +445,16 @@ export async function resumePipeline(
     tasks.push(task);
   }
 
-  for (let i = 0; i < tasks.length; i++) {
+  await executeStages({
-    const task = tasks[i]!;
+    manifest,
-    const stageName = remainingStages[i]!;
+    runDir,
+    tasks,
+    stageNames: remainingStages,
+    executor: wiredExecutor,
+    simulate,
+  });
 
-    manifest.currentStage = stageName;
+  manifest.status = simulate ? 'simulated' : 'completed';
-    manifest.stages[stageName] = {
-      status: 'in_progress',
-      startedAt: nowISO(),
-    };
-    saveManifest(runDir, manifest);
-
-    try {
-      await executor.submitTask(task);
-      const result = await executor.waitForCompletion(task.id, task.timeoutSeconds * 1000);
-
-      manifest.stages[stageName] = {
-        status: result.status === 'completed' ? 'passed' : 'failed',
-        startedAt: manifest.stages[stageName]!.startedAt,
-        completedAt: nowISO(),
-      };
-
-      if (result.status !== 'completed') {
-        manifest.status = 'failed';
-        saveManifest(runDir, manifest);
-        throw new Error(`Stage ${stageName} failed with status: ${result.status}`);
-      }
-
-      saveManifest(runDir, manifest);
-    } catch (error) {
-      if (!manifest.stages[stageName]?.completedAt) {
-        manifest.stages[stageName] = {
-          status: 'failed',
-          startedAt: manifest.stages[stageName]?.startedAt,
-          completedAt: nowISO(),
-        };
-      }
-      manifest.status = 'failed';
-      saveManifest(runDir, manifest);
-      throw error;
-    }
-  }
-
-  manifest.status = 'completed';
   saveManifest(runDir, manifest);
 
   return {

packages/forge/src/simulated-executor.ts

@@ -0,0 +1,32 @@
+import type { ForgeTask, ForgeTaskResult, TaskExecutor } from './types.js';
+
+/**
+ * Simulated executor — used ONLY when the caller explicitly passes --simulate.
+ *
+ * It submits no real work and returns typed `simulated` results so a simulated
+ * run can never be confused with a verified one. In normal mode (no --simulate)
+ * the CLI refuses to run at all with FORGE_NO_EXECUTOR instead of wiring this
+ * stub (fail closed, SDLC-D-035).
+ */
+export function createSimulatedExecutor(options?: { log?: boolean }): TaskExecutor {
+  const log = options?.log ?? true;
+  return {
+    async submitTask(task: ForgeTask) {
+      if (log) console.log(`  [forge:simulated] stage submitted: ${task.id} (${task.title})`);
+    },
+    async waitForCompletion(taskId: string): Promise<ForgeTaskResult> {
+      if (log) console.log(`  [forge:simulated] stage complete:  ${taskId}`);
+      return {
+        task_id: taskId,
+        outcome: 'simulated',
+        reason: 'no executor wired; simulated execution requested via --simulate',
+        completed_at: new Date().toISOString(),
+        exit_code: 0,
+        gate_results: [],
+      };
+    },
+    async getTaskStatus() {
+      return 'completed' as const;
+    },
+  };
+}

packages/forge/src/types.ts

@@ -1,4 +1,4 @@
-import type { GateEntry, TaskResult } from '@mosaicstack/macp';
+import type { GateEntry } from '@mosaicstack/macp';
 
 /** Stage dispatch mode. */
 export type StageDispatch = 'exec' | 'yolo' | 'pi';
@@ -6,6 +6,58 @@ export type StageDispatch = 'exec' | 'yolo' | 'pi';
 /** Stage type — determines agent selection and gate requirements. */
 export type StageType = 'research' | 'review' | 'coding' | 'deploy';
 
+/**
+ * Typed outcome for every gate and stage evaluation — closed set (SDLC-D-035).
+ *
+ * Only `passed` means "verified by a real implementation". `simulated` is
+ * produced exclusively in explicit `--simulate` runs and is never satisfying.
+ */
+export type ForgeOutcome =
+  | 'passed'
+  | 'failed'
+  | 'blocked'
+  | 'error'
+  | 'waiting-for-authority'
+  | 'simulated'
+  | 'not-applicable';
+
+/** A gate that requires authority (human/board) sign-off; no mechanical command can satisfy it. */
+export interface AuthorityGate {
+  kind: 'authority';
+  capability: string;
+  reason: string;
+}
+
+/** A gate that requires a wired provider (e.g. an AI reviewer, CI pipeline) to evaluate. */
+export interface ProviderGate {
+  kind: 'provider';
+  capability: string;
+  reason: string;
+}
+
+/** Forge quality gate: a real command, an authority sign-off, or a provider-backed check. */
+export type ForgeGate = string | GateEntry | AuthorityGate | ProviderGate;
+
+/** Typed result of evaluating a single quality gate. */
+export interface ForgeGateResult {
+  gate: string;
+  outcome: ForgeOutcome;
+  reason: string;
+  exitCode?: number;
+  output?: string;
+  timedOut?: boolean;
+}
+
+/** Typed result of a task/stage execution returned by a TaskExecutor. */
+export interface ForgeTaskResult {
+  task_id: string;
+  outcome: ForgeOutcome;
+  reason: string;
+  completed_at: string;
+  exit_code: number;
+  gate_results: ForgeGateResult[];
+}
+
 /** Stage specification — defines a single pipeline stage. */
 export interface StageSpec {
   number: string;
@@ -14,7 +66,7 @@ export interface StageSpec {
   type: StageType;
   gate: string;
   promptFile: string;
-  qualityGates: (string | GateEntry)[];
+  qualityGates: ForgeGate[];
 }
 
 /** Brief classification. */
@@ -25,11 +77,18 @@ export type ClassSource = 'cli' | 'frontmatter' | 'auto';
 
 /** Per-stage status within a run manifest. */
 export interface StageStatus {
-  status: 'pending' | 'in_progress' | 'passed' | 'failed';
+  status: 'pending' | 'in_progress' | ForgeOutcome;
+  /** Why the stage reached its current (terminal) outcome, when applicable. */
+  reason?: string;
   startedAt?: string;
   completedAt?: string;
+  /** Typed per-gate results recorded alongside the stage outcome. */
+  gateResults?: ForgeGateResult[];
 }
 
+/** Execution mode of a run. */
+export type RunMode = 'normal' | 'simulated';
+
 /** Run manifest — persisted to disk as manifest.json. */
 export interface RunManifest {
   runId: string;
@@ -38,10 +97,23 @@ export interface RunManifest {
   briefClass: BriefClass;
   classSource: ClassSource;
   forceBoard: boolean;
+  /**
+   * Execution mode. `simulated` runs stub execution; their results are typed
+   * `simulated` and must never be read as verified success. Optional because
+   * manifests written before this field existed default to `normal`.
+   */
+  mode?: RunMode;
   createdAt: string;
   updatedAt: string;
   currentStage: string;
-  status: 'in_progress' | 'completed' | 'failed' | 'interrupted' | 'rejected';
+  status:
+    | 'in_progress'
+    | 'completed'
+    | 'failed'
+    | 'interrupted'
+    | 'rejected'
+    | 'simulated'
+    | 'waiting-for-authority';
   stages: Record<string, StageStatus>;
 }
 
@@ -65,7 +137,7 @@ export interface ForgeTask {
   briefPath: string;
   resultPath: string;
   timeoutSeconds: number;
-  qualityGates: (string | GateEntry)[];
+  qualityGates: ForgeGate[];
   worktree?: string;
   command?: string;
   dependsOn?: string[];
@@ -76,7 +148,7 @@ export interface ForgeTask {
 /** Abstract task executor — decouples from packages/coord. */
 export interface TaskExecutor {
   submitTask(task: ForgeTask): Promise<void>;
-  waitForCompletion(taskId: string, timeoutMs: number): Promise<TaskResult>;
+  waitForCompletion(taskId: string, timeoutMs: number): Promise<ForgeTaskResult>;
   getTaskStatus(taskId: string): Promise<ForgeTaskStatus>;
 }
 
@@ -122,7 +194,16 @@ export interface PipelineOptions {
   stages?: string[];
   skipTo?: string;
   dryRun?: boolean;
-  executor: TaskExecutor;
+  /**
+   * Real task executor. Required in normal mode: the pipeline fails closed
+   * with FORGE_NO_EXECUTOR when it is absent.
+   */
+  executor?: TaskExecutor;
+  /**
+   * Explicit opt-in to simulated execution. Every stage and gate result is
+   * typed `simulated` and is never satisfying.
+   */
+  simulate?: boolean;
 }
 
 /** Pipeline run result. */

packages/mosaic/framework/tools/quality/test-enumeration-exclusions.txt

@@ -39,3 +39,20 @@ packages/mosaic/framework/tools/tmux/test-send-message-verdict.sh | requires rea
 # recorded judgement. These lines ARE that judgement, signed.)
 packages/mosaic/framework/tools/orchestrator/smoke-test.sh | behavior smoke checks for coord continue/run workflows, run manually by orchestrator seats; unmeasured in CI; #1017 burndown
 packages/mosaic/framework/tools/wake/validate-973/microtest-wake-assert.sh | #973 instrument self-test, run as a precondition of the validate-973 evidence procedure rather than as a standing CI suite; #1017 burndown candidate
+
+# --- tools/fleet: precondition is unsatisfiable in the CI image (#1271) ---
+# Signed by fred (sb-it-1-dt, 2026-08-16) at origin/next 476db12.
+# This suite asserts the launcher's behaviour when `mosaic` and `pi` are MISSING.
+# It shims fakes into $FAKE_BIN, but the constructed PANE_PATH always ends in the
+# real system path, so on a host that installs those binaries the missing-binary
+# cases cannot be measured at all. The suite's own guard (line 103) says so and
+# fails rather than reporting a pass it cannot back. That guard is correct.
+# The error was wiring the suite into CI: #1017 (c56483eb) enumerated it and
+# dropped this exclusion, and the CI image provides `pi` in the system path, so
+# it has failed on every pipeline since. Measured 2026-08-16 across pipelines
+# 2444 (#1256), 2438 (#1240) and 2441 (#1017-quality): exactly one FAIL line in
+# each full log, identical, this assertion; control `zzz-not-present-zzz` -> 0.
+# Burn-down and the full measurement are tracked in #1271; unwired by PR #1270.
+# Because test:framework-shell is one && chain and this sat at position 44 of 48,
+# the four suites after it had not run at all since the merge.
+packages/mosaic/framework/tools/fleet/test-start-agent-session.sh | precondition unsatisfiable in the CI image: asserts missing-binary behaviour, but PANE_PATH always ends in the system path and the image provides `pi` there; guard at line 103 fails by design rather than passing unmeasured. Burn down by controlling the tail of PANE_PATH inside the test. NOT by removing `pi` from the image: the CI image installs @earendil-works/[email protected] deliberately (measured in pipeline 2444's test-step log), and other suites depend on that pin. Burn-down tracked in #1271

packages/mosaic/package.json

@@ -25,7 +25,7 @@
     "lint": "eslint src",
     "typecheck": "tsc --noEmit",
     "test": "vitest run --passWithNoTests && pnpm run test:framework-shell",
-    "test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/promotion_binding_unittest.py && python3 src/lease-broker/promotion_trigger_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/receipt_observer_client_unittest.py && python3 src/lease-broker/invariant_r_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-tristate.sh && bash framework/tools/git/test-ci-queue-wait-github-checks.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-head-pin.sh && bash framework/tools/git/test-pr-merge-message-field.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/_scripts/test-mosaic-init-rce.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh && bash framework/tools/fleet/test-start-agent-session.sh && bash framework/tools/glpi/test-list-http-status.sh && bash framework/tools/orchestrator/test-board-roll.sh && bash framework/tools/woodpecker/test-ci-wait-exit-matrix.sh && bash framework/tools/_scripts/test-fleet-transport-check.sh"
+    "test:framework-shell": "bash framework/tools/quality/scripts/check-test-enumeration.sh && bash framework/tools/quality/scripts/test-check-test-enumeration.sh && python3 src/lease-broker/daemon_deadline_unittest.py && python3 src/lease-broker/normative_fragments_unittest.py && python3 src/lease-broker/promotion_binding_unittest.py && python3 src/lease-broker/promotion_trigger_unittest.py && python3 src/lease-broker/receipt_challenge_unittest.py && python3 src/lease-broker/context_recovery_unittest.py && python3 src/lease-broker/recovery_runtime_unittest.py && python3 src/lease-broker/recovery_b1_adversarial_unittest.py && python3 src/lease-broker/receipt_observer_client_unittest.py && python3 src/lease-broker/invariant_r_unittest.py && python3 src/lease-broker/framework_skill_portability_unittest.py && python3 src/mutator-gate/runtime_tools_unittest.py && python3 src/mutator-gate/runtime_launch_guard_unittest.py && python3 src/mutator-gate/version_coupling_unittest.py && python3 framework/tools/lease-broker/check-runtime-launches.py --root ../.. && bash framework/tools/codex/test-pr-diff-context.sh && bash framework/tools/qa/test-deps-preflight.sh && bash framework/tools/git/test-pr-review-gitea-comment.sh && bash framework/tools/git/test-pr-review-repo-host-override.sh && bash framework/tools/git/test-ci-queue-wait-branch-absent.sh && bash framework/tools/git/test-ci-queue-wait-tristate.sh && bash framework/tools/git/test-ci-queue-wait-github-checks.sh && bash framework/tools/git/test-pr-merge-queue-branch.sh && bash framework/tools/git/test-pr-merge-head-pin.sh && bash framework/tools/git/test-pr-merge-message-field.sh && bash framework/tools/git/test-git-credential-mosaic.sh && bash framework/tools/git/test-gitea-token-identity.sh && bash framework/tools/woodpecker/test-terminal-green-contract.sh && bash framework/tools/_scripts/test-install-ordering-guard.sh && bash framework/tools/_scripts/test-mosaic-init-rce.sh && bash framework/tools/tmux/agent-send.test.sh && bash framework/tools/wake/test-wake-store-ack.sh && bash framework/tools/wake/test-wake-store-enqueue-race.sh && bash framework/tools/wake/test-wake-digest-hmac.sh && bash framework/tools/wake/test-wake-digest-quarantine.sh && bash framework/tools/wake/test-wake-detector.sh && bash framework/tools/wake/test-wake-fn-oracle.sh && bash framework/tools/wake/test-wake-reconcile.sh && bash framework/tools/wake/test-wake-beacon.sh && bash framework/tools/wake/test-wake-preimage.sh && bash framework/tools/wake/test-wake-install.sh && bash framework/tools/glpi/test-list-http-status.sh && bash framework/tools/orchestrator/test-board-roll.sh && bash framework/tools/woodpecker/test-ci-wait-exit-matrix.sh && bash framework/tools/_scripts/test-fleet-transport-check.sh"
   },
   "dependencies": {
     "@mosaicstack/brain": "workspace:*",

packages/mosaic/src/cli.ts

@@ -20,7 +20,6 @@ import { registerMissionCommand } from './commands/mission.js';
 import { registerUninstallCommand } from './commands/uninstall.js';
 import { registerRestoreCommand } from './commands/restore.js';
 import { registerSkillCommand } from './commands/skill.js';
-import { registerStoreCommand } from './commands/store.js';
 // prdy is registered via launch.ts
 import { registerLaunchCommands } from './commands/launch.js';
 import { registerLeaseCapabilityProbe } from './commands/lease-activation-probe.js';
@@ -426,10 +425,6 @@ registerRestoreCommand(program);
 
 registerSkillCommand(program);
 
-// ─── store ───────────────────────────────────────────────────────────────────
-
-registerStoreCommand(program);
-
 // ─── telemetry ───────────────────────────────────────────────────────────────
 
 registerTelemetryCommand(program);

packages/mosaic/src/commands/store.spec.ts

@@ -1,458 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { Command } from 'commander';
-import {
-  existsSync,
-  lstatSync,
-  mkdirSync,
-  mkdtempSync,
-  readFileSync,
-  readdirSync,
-  rmSync,
-  symlinkSync,
-  writeFileSync,
-} from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import {
-  addStoreEntry,
-  getDefaultStorePaths,
-  listStoreEntries,
-  registerStoreCommand,
-  StoreError,
-  storeKindDir,
-  validateStoreKind,
-  validateStoreName,
-  validateStoreVersion,
-  type StorePaths,
-} from './store.js';
-
-/** Assert a typed StoreError with exactly the expected code. */
-function expectStoreError(run: () => unknown, code: string): void {
-  try {
-    run();
-  } catch (error) {
-    expect(error).toBeInstanceOf(StoreError);
-    expect((error as StoreError).code).toBe(code);
-    return;
-  }
-  throw new Error(`expected StoreError ${code}, but nothing threw`);
-}
-
-describe('vetted user store (W-F4)', () => {
-  let root: string;
-  let paths: StorePaths;
-  let sourceRoot: string;
-
-  beforeEach(() => {
-    root = mkdtempSync(join(tmpdir(), 'mosaic-store-cli-'));
-    paths = { userRoot: join(root, '.mosaic') };
-    sourceRoot = join(root, 'sources');
-    mkdirSync(sourceRoot, { recursive: true });
-  });
-
-  afterEach(() => {
-    rmSync(root, { recursive: true, force: true });
-  });
-
-  function createSource(name: string): string {
-    const dir = join(sourceRoot, name);
-    mkdirSync(dir, { recursive: true });
-    writeFileSync(join(dir, 'SKILL.md'), `# ${name}\n`);
-    return dir;
-  }
-
-  describe('name and version validation (before any filesystem call)', () => {
-    const invalidNames = [
-      '../../etc',
-      '/abs/path',
-      'a/b',
-      String.raw`a\b`,
-      '-rf',
-      '..',
-      'safe.',
-      'space name',
-      'line\nbreak',
-      'escape\u001B[31m',
-    ];
-
-    for (const name of invalidNames) {
-      it(`rejects name ${JSON.stringify(name)}`, () => {
-        expect(() => validateStoreName(name)).toThrow(StoreError);
-      });
-    }
-
-    const invalidVersions = ['', '-1', '1..0', 'a/b', '..', '1.0 beta', '/x'];
-    for (const version of invalidVersions) {
-      it(`rejects version ${JSON.stringify(version)}`, () => {
-        expect(() => validateStoreVersion(version)).toThrow(StoreError);
-      });
-    }
-
-    it('accepts semver-shaped versions including prerelease and build metadata', () => {
-      expect(() => validateStoreVersion('0.1.0-beta.1')).not.toThrow();
-      expect(() => validateStoreVersion('1.2.3+build.7')).not.toThrow();
-    });
-
-    it('rejects plural and unknown kinds', () => {
-      expectStoreError(() => validateStoreKind('plugins'), 'STORE_INVALID_KIND');
-      expectStoreError(() => validateStoreKind('widget'), 'STORE_INVALID_KIND');
-    });
-
-    it('accepts the two spec kinds', () => {
-      expect(() => validateStoreKind('plugin')).not.toThrow();
-      expect(() => validateStoreKind('skill')).not.toThrow();
-    });
-  });
-
-  describe('addStoreEntry', () => {
-    it('copies content into a versioned directory and writes the marker last', () => {
-      const result = addStoreEntry(
-        'skill',
-        'demo',
-        '1.0.0',
-        createSource('demo'),
-        'op',
-        undefined,
-        paths,
-      );
-      expect(result.status).toBe('added');
-      const entryPath = join(paths.userRoot, 'skills', 'demo', '1.0.0');
-      expect(result.entryPath).toBe(entryPath);
-      expect(existsSync(join(entryPath, 'SKILL.md'))).toBe(true);
-      expect(existsSync(join(entryPath, 'store-entry.json'))).toBe(true);
-      const meta = JSON.parse(readFileSync(join(entryPath, 'store-entry.json'), 'utf-8'));
-      expect(meta).toMatchObject({
-        schema: 1,
-        kind: 'skill',
-        name: 'demo',
-        version: '1.0.0',
-        vettedBy: 'op',
-      });
-      expect(typeof meta['vettedAt']).toBe('string');
-    });
-
-    it('writes plugins under plugins/ and skills under skills/', () => {
-      addStoreEntry('plugin', 'alpha', '0.1.0', createSource('alpha'), 'op', undefined, paths);
-      addStoreEntry('skill', 'beta', '2.0.0', createSource('beta'), 'op', undefined, paths);
-      expect(existsSync(join(paths.userRoot, 'plugins', 'alpha', '0.1.0'))).toBe(true);
-      expect(existsSync(join(paths.userRoot, 'skills', 'beta', '2.0.0'))).toBe(true);
-    });
-
-    it('is append-only: an existing version with a marker is refused, not overwritten', () => {
-      const sourceA = createSource('demo');
-      const sourceB = join(sourceRoot, 'demo-other');
-      mkdirSync(sourceB, { recursive: true });
-      writeFileSync(join(sourceB, 'SKILL.md'), '# changed\n');
-      addStoreEntry('skill', 'demo', '1.0.0', sourceA, 'op', undefined, paths);
-      expectStoreError(
-        () => addStoreEntry('skill', 'demo', '1.0.0', sourceB, 'op', undefined, paths),
-        'STORE_ALREADY_PRESENT',
-      );
-      expect(
-        readFileSync(join(paths.userRoot, 'skills', 'demo', '1.0.0', 'SKILL.md'), 'utf-8'),
-      ).toBe('# demo\n');
-    });
-
-    it('allows a second version alongside the first', () => {
-      addStoreEntry('skill', 'demo', '1.0.0', createSource('demo'), 'op', undefined, paths);
-      const result = addStoreEntry(
-        'skill',
-        'demo',
-        '1.1.0',
-        createSource('demo'),
-        'op',
-        undefined,
-        paths,
-      );
-      expect(result.status).toBe('added');
-      expect(readdirSync(join(paths.userRoot, 'skills', 'demo')).sort()).toEqual([
-        '1.0.0',
-        '1.1.0',
-      ]);
-    });
-
-    it('refuses an unmarked target directory by default and preserves its content', () => {
-      const unmarked = join(paths.userRoot, 'skills', 'demo', '1.0.0');
-      mkdirSync(unmarked, { recursive: true });
-      writeFileSync(join(unmarked, 'SKILL.md'), '# operator content\n');
-      expectStoreError(
-        () => addStoreEntry('skill', 'demo', '1.0.0', createSource('demo'), 'op', undefined, paths),
-        'STORE_TARGET_UNMARKED',
-      );
-      // The operator's hand-placed content survives the refusal.
-      expect(readFileSync(join(unmarked, 'SKILL.md'), 'utf-8')).toBe('# operator content\n');
-    });
-
-    it('reclaims an unmarked target only under explicit reclaim opt-in', () => {
-      const unmarked = join(paths.userRoot, 'skills', 'demo', '1.0.0');
-      mkdirSync(unmarked, { recursive: true });
-      writeFileSync(join(unmarked, 'SKILL.md'), '# torn write\n');
-      const result = addStoreEntry(
-        'skill',
-        'demo',
-        '1.0.0',
-        createSource('demo'),
-        'op',
-        undefined,
-        paths,
-        { reclaim: true },
-      );
-      expect(result.status).toBe('reclaimed-unmarked');
-      expect(readFileSync(join(unmarked, 'SKILL.md'), 'utf-8')).toBe('# demo\n');
-    });
-
-    it('reclaim can never destroy a marked, vetted entry (append-only holds under --reclaim)', () => {
-      addStoreEntry('skill', 'demo', '1.0.0', createSource('demo'), 'op', undefined, paths);
-      const marked = join(paths.userRoot, 'skills', 'demo', '1.0.0');
-      const vettedContent = readFileSync(join(marked, 'SKILL.md'), 'utf-8');
-      expectStoreError(
-        () =>
-          addStoreEntry('skill', 'demo', '1.0.0', createSource('demo'), 'op', undefined, paths, {
-            reclaim: true,
-          }),
-        'STORE_ALREADY_PRESENT',
-      );
-      // Load-bearing half: the throw alone does not prove nothing was deleted
-      // before it. Pins the marker-check-before-reclaim-check ordering against
-      // the guard-clause-migrates-upward refactor (review finding on b2124c6).
-      expect(readFileSync(join(marked, 'SKILL.md'), 'utf-8')).toBe(vettedContent);
-      expect(existsSync(join(marked, 'store-entry.json'))).toBe(true);
-    });
-
-    it('refuses a missing source with a typed error', () => {
-      expectStoreError(
-        () =>
-          addStoreEntry('skill', 'demo', '1.0.0', join(sourceRoot, 'nope'), 'op', undefined, paths),
-        'STORE_SOURCE_MISSING',
-      );
-    });
-
-    it('refuses a file (non-directory) source with a typed error', () => {
-      const filePath = join(sourceRoot, 'file.txt');
-      writeFileSync(filePath, 'x');
-      expectStoreError(
-        () => addStoreEntry('skill', 'demo', '1.0.0', filePath, 'op', undefined, paths),
-        'STORE_SOURCE_NOT_DIR',
-      );
-    });
-
-    it('refuses a symlinked source with a typed error and writes nothing', () => {
-      const real = createSource('demo');
-      const link = join(sourceRoot, 'demo-link');
-      symlinkSync(real, link);
-      expectStoreError(
-        () => addStoreEntry('skill', 'demo', '1.0.0', link, 'op', undefined, paths),
-        'STORE_SOURCE_SYMLINK',
-      );
-      expect(existsSync(join(paths.userRoot, 'skills', 'demo'))).toBe(false);
-    });
-
-    it('refuses a source tree containing nested symlinks and writes nothing', () => {
-      const src = createSource('demo');
-      const target = join(sourceRoot, 'elsewhere');
-      mkdirSync(target, { recursive: true });
-      symlinkSync(target, join(src, 'escape'));
-      expectStoreError(
-        () => addStoreEntry('skill', 'demo', '1.0.0', src, 'op', undefined, paths),
-        'STORE_SOURCE_SYMLINK',
-      );
-      expect(existsSync(join(paths.userRoot, 'skills', 'demo'))).toBe(false);
-    });
-
-    it('refuses adding from inside the store itself', () => {
-      const first = addStoreEntry(
-        'skill',
-        'demo',
-        '1.0.0',
-        createSource('demo'),
-        'op',
-        undefined,
-        paths,
-      );
-      expectStoreError(
-        () => addStoreEntry('skill', 'copy', '1.0.0', first.entryPath, 'op', undefined, paths),
-        'STORE_SOURCE_INSIDE_STORE',
-      );
-    });
-
-    it('refuses a symlinked user root ancestor', () => {
-      const linkedRoot = join(sourceRoot, 'linked-mosaic');
-      symlinkSync(paths.userRoot, linkedRoot);
-      expectStoreError(
-        () =>
-          addStoreEntry('skill', 'demo', '1.0.0', createSource('demo'), 'op', undefined, {
-            userRoot: linkedRoot,
-          }),
-        'STORE_SYMLINK_ROOT',
-      );
-    });
-
-    it('requires a non-empty vetting attribution', () => {
-      expectStoreError(
-        () => addStoreEntry('skill', 'demo', '1.0.0', createSource('demo'), '  ', undefined, paths),
-        'STORE_INVALID_VETTER',
-      );
-    });
-  });
-
-  describe('listStoreEntries', () => {
-    it('returns empty for an absent store without creating it', () => {
-      expect(listStoreEntries(paths)).toEqual([]);
-      expect(existsSync(paths.userRoot)).toBe(false);
-    });
-
-    it('lists entries deterministically with vetting metadata', () => {
-      addStoreEntry('plugin', 'alpha', '0.1.0', createSource('alpha'), 'fred', undefined, paths);
-      addStoreEntry('skill', 'beta', '2.0.0', createSource('beta'), 'fargo', 'looked fine', paths);
-      addStoreEntry('skill', 'beta', '2.1.0', createSource('beta'), 'fargo', undefined, paths);
-
-      const entries = listStoreEntries(paths);
-      expect(entries.map((e) => `${e.kind}:${e.name}:${e.version}`)).toEqual([
-        'plugin:alpha:0.1.0',
-        'skill:beta:2.0.0',
-        'skill:beta:2.1.0',
-      ]);
-      expect(entries[0]?.meta?.vettedBy).toBe('fred');
-      expect(entries[1]?.meta?.notes).toBe('looked fine');
-    });
-
-    it('classifies markerless version directories as incomplete', () => {
-      addStoreEntry('skill', 'demo', '1.0.0', createSource('demo'), 'op', undefined, paths);
-      mkdirSync(join(paths.userRoot, 'skills', 'demo', '2.0.0'), { recursive: true });
-      const entries = listStoreEntries(paths, { kind: 'skill', name: 'demo' });
-      expect(entries.find((e) => e.version === '1.0.0')?.status).toBe('vetted');
-      expect(entries.find((e) => e.version === '2.0.0')?.status).toBe('incomplete');
-    });
-
-    it('classifies malformed marker JSON as invalid-metadata, not vetted', () => {
-      addStoreEntry('skill', 'demo', '1.0.0', createSource('demo'), 'op', undefined, paths);
-      writeFileSync(
-        join(paths.userRoot, 'skills', 'demo', '1.0.0', 'store-entry.json'),
-        '{not json',
-      );
-      const entries = listStoreEntries(paths);
-      expect(entries[0]?.status).toBe('invalid-metadata');
-    });
-
-    it('surfaces foreign files (never mutates them)', () => {
-      mkdirSync(join(paths.userRoot, 'skills'), { recursive: true });
-      writeFileSync(join(paths.userRoot, 'skills', 'stray.txt'), 'x');
-      const entries = listStoreEntries(paths);
-      expect(entries[0]?.status).toBe('foreign');
-      expect(existsSync(join(paths.userRoot, 'skills', 'stray.txt'))).toBe(true);
-    });
-
-    it('filters by kind and name', () => {
-      addStoreEntry('plugin', 'alpha', '0.1.0', createSource('alpha'), 'op', undefined, paths);
-      addStoreEntry('skill', 'beta', '1.0.0', createSource('beta'), 'op', undefined, paths);
-      expect(listStoreEntries(paths, { kind: 'plugin' }).map((e) => e.name)).toEqual(['alpha']);
-      expect(listStoreEntries(paths, { name: 'beta' }).map((e) => e.name)).toEqual(['beta']);
-      expect(() => listStoreEntries(paths, { name: '../escape' })).toThrow(StoreError);
-    });
-  });
-
-  describe('default paths seam', () => {
-    it('honors MOSAIC_USER_HOME', () => {
-      const previous = process.env['MOSAIC_USER_HOME'];
-      try {
-        process.env['MOSAIC_USER_HOME'] = join(root, 'custom-user-home');
-        expect(getDefaultStorePaths().userRoot).toBe(join(root, 'custom-user-home'));
-        expect(storeKindDir('plugin')).toBe(join(root, 'custom-user-home', 'plugins'));
-      } finally {
-        if (previous === undefined) delete process.env['MOSAIC_USER_HOME'];
-        else process.env['MOSAIC_USER_HOME'] = previous;
-      }
-    });
-  });
-
-  describe('CLI', () => {
-    let previousExitCode: string | number | null | undefined;
-
-    beforeEach(() => {
-      previousExitCode = process.exitCode;
-      process.exitCode = undefined;
-    });
-
-    afterEach(() => {
-      process.exitCode = previousExitCode;
-    });
-
-    const parse = (args: string[]) => {
-      const program = new Command().exitOverride();
-      registerStoreCommand(program, paths);
-      return program.parseAsync(['node', 'mosaic', 'store', ...args]);
-    };
-
-    it('registers on the parent program and renders help', () => {
-      const program = new Command().exitOverride();
-      registerStoreCommand(program, paths);
-      const cmd = program.commands.find((c) => c.name() === 'store');
-      expect(cmd).toBeDefined();
-      expect(() => cmd?.helpInformation()).not.toThrow();
-    });
-
-    it('add exits nonzero with a typed code for an invalid name', async () => {
-      await parse([
-        'add',
-        'skill',
-        '../../etc',
-        '1.0.0',
-        '--from',
-        createSource('x'),
-        '--by',
-        'op',
-      ]);
-      expect(process.exitCode).toBe(1);
-    });
-
-    it('add exits nonzero when the kind is plural', async () => {
-      await parse(['add', 'skills', 'demo', '1.0.0', '--from', createSource('demo'), '--by', 'op']);
-      expect(process.exitCode).toBe(1);
-    });
-
-    it('add succeeds and creates the entry directory', async () => {
-      await parse(['add', 'skill', 'demo', '1.0.0', '--from', createSource('demo'), '--by', 'op']);
-      expect(process.exitCode).toBeUndefined();
-      expect(lstatSync(join(paths.userRoot, 'skills', 'demo', '1.0.0')).isDirectory()).toBe(true);
-    });
-
-    it('add requires --by (commander requiredOption)', async () => {
-      await expect(
-        parse(['add', 'skill', 'demo', '1.0.0', '--from', createSource('demo')]),
-      ).rejects.toThrow(/--by/);
-    });
-
-    it('add exits nonzero on an unmarked target without --reclaim, preserving content', async () => {
-      const unmarked = join(paths.userRoot, 'skills', 'demo', '1.0.0');
-      mkdirSync(unmarked, { recursive: true });
-      writeFileSync(join(unmarked, 'SKILL.md'), '# operator\n');
-      await parse(['add', 'skill', 'demo', '1.0.0', '--from', createSource('demo'), '--by', 'op']);
-      expect(process.exitCode).toBe(1);
-      expect(readFileSync(join(unmarked, 'SKILL.md'), 'utf-8')).toBe('# operator\n');
-    });
-
-    it('add --reclaim replaces the unmarked target and succeeds', async () => {
-      const unmarked = join(paths.userRoot, 'skills', 'demo', '1.0.0');
-      mkdirSync(unmarked, { recursive: true });
-      writeFileSync(join(unmarked, 'SKILL.md'), '# torn\n');
-      await parse([
-        'add',
-        'skill',
-        'demo',
-        '1.0.0',
-        '--from',
-        createSource('demo'),
-        '--by',
-        'op',
-        '--reclaim',
-      ]);
-      expect(process.exitCode).toBeUndefined();
-      expect(readFileSync(join(unmarked, 'SKILL.md'), 'utf-8')).toBe('# demo\n');
-    });
-
-    it('list exits 0 on an empty store', async () => {
-      await parse(['list']);
-      expect(process.exitCode).toBeUndefined();
-    });
-  });
-});

packages/mosaic/src/commands/store.ts

@@ -1,544 +0,0 @@
-import {
-  cpSync,
-  existsSync,
-  lstatSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  rmSync,
-  writeFileSync,
-  type Dirent,
-  type Stats,
-} from 'node:fs';
-import { isAbsolute, join, parse, relative, resolve, sep } from 'node:path';
-import type { Command } from 'commander';
-import { DEFAULT_MOSAIC_USER_HOME } from '../constants.js';
-
-/**
- * `mosaic store` — the vetted user store under `~/.mosaic/{plugins,skills}` (W-F4).
- *
- * Two roots with distinct ownership (HARNESS-HOMES design, frozen REV3):
- * - `~/.config/mosaic/` is the SYSTEM root: update-owned, replaceable wholesale.
- * - `~/.mosaic/` is the USER root: never touched by installs or updates.
- *
- * This module only ever writes under the USER root. The store is the vetting
- * boundary: content lands here only through an explicit `store add` carrying a
- * named vetting attribution, and every entry is versioned
- * (`store/<kind>s/<name>/<version>/`) with a `store-entry.json` marker written
- * LAST — a version directory without its marker is never a usable entry, and
- * an unmarked target is REFUSED by default: it may be this tool's own debris
- * from an interrupted add, or content the operator placed by hand, and the
- * code cannot tell those apart — so deletion happens only under an explicit
- * `--reclaim` opt-in, and the result status names what was done.
- *
- * Deferred by design (W-F6 and later): activation/symlink-install into agent
- * homes, `current`-pointer pinning, network acquisition. `add` accepts a local
- * source path only — no network, no credentials, ever.
- */
-
-export type StoreKind = 'plugin' | 'skill';
-export const STORE_KINDS: readonly StoreKind[] = ['plugin', 'skill'];
-
-/** On-disk metadata marker; written last so its presence commits an entry. */
-export const STORE_ENTRY_MARKER = 'store-entry.json';
-
-export interface StorePaths {
-  /** User data root, e.g. `~/.mosaic`. */
-  userRoot: string;
-}
-
-export interface StoreEntryMeta {
-  schema: 1;
-  kind: StoreKind;
-  name: string;
-  version: string;
-  /** Absolute source path the content was vetted from, as resolved at add time. */
-  sourcePath: string;
-  /** Operator who vouched for the content — required, non-empty. */
-  vettedBy: string;
-  /** ISO timestamp of the add. */
-  vettedAt: string;
-  /** Free-form vetting notes, if any. */
-  notes?: string;
-}
-
-export type StoreAddStatus = 'added' | 'reclaimed-unmarked';
-
-export interface StoreAddResult {
-  kind: StoreKind;
-  name: string;
-  version: string;
-  status: StoreAddStatus;
-  entryPath: string;
-  sourcePath: string;
-}
-
-export type StoreEntryStatus = 'vetted' | 'incomplete' | 'invalid-metadata' | 'foreign';
-
-export interface StoreListEntry {
-  kind: StoreKind;
-  name: string;
-  /** Undefined for name-level foreign files (not a directory at all). */
-  version?: string;
-  status: StoreEntryStatus;
-  entryPath: string;
-  meta?: StoreEntryMeta;
-}
-
-const SAFE_STORE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
-const SAFE_STORE_VERSION = /^[A-Za-z0-9][A-Za-z0-9._+-]*$/;
-
-export class StoreError extends Error {
-  public readonly code: string;
-
-  public constructor(code: string, message: string) {
-    super(message);
-    this.name = 'StoreError';
-    this.code = code;
-  }
-}
-
-/** Resolve the user store root while keeping tests injectable. */
-export function getDefaultStorePaths(): StorePaths {
-  const userRoot = process.env['MOSAIC_USER_HOME'] ?? DEFAULT_MOSAIC_USER_HOME;
-  return { userRoot };
-}
-
-/**
- * Reject a user-supplied name before any filesystem operation.
- * A store name identifies one directory under `store/<kind>s/`.
- */
-export function validateStoreName(name: string): void {
-  if (
-    name.length === 0 ||
-    name.startsWith('-') ||
-    name.endsWith('.') ||
-    name.includes('..') ||
-    name.includes('/') ||
-    name.includes('\\') ||
-    isAbsolute(name) ||
-    !SAFE_STORE_NAME.test(name)
-  ) {
-    throw new StoreError(
-      'STORE_INVALID_NAME',
-      `Invalid store name ${JSON.stringify(name)}: use letters, numbers, dots, underscores, or hyphens; start with a letter or number; and do not use paths, "..", or a leading "-".`,
-    );
-  }
-}
-
-/** Versions share the name discipline plus `+` (semver build metadata). */
-export function validateStoreVersion(version: string): void {
-  if (
-    version.length === 0 ||
-    version.startsWith('-') ||
-    version.endsWith('.') ||
-    version.includes('..') ||
-    version.includes('/') ||
-    version.includes('\\') ||
-    isAbsolute(version) ||
-    !SAFE_STORE_VERSION.test(version)
-  ) {
-    throw new StoreError(
-      'STORE_INVALID_VERSION',
-      `Invalid version ${JSON.stringify(version)}: use letters, numbers, dots, underscores, hyphens, or plus; start with a letter or number; and do not use paths, "..", or a leading "-".`,
-    );
-  }
-}
-
-export function validateStoreKind(kind: string): asserts kind is StoreKind {
-  if (!(STORE_KINDS as readonly string[]).includes(kind)) {
-    throw new StoreError(
-      'STORE_INVALID_KIND',
-      `Invalid store kind ${JSON.stringify(kind)}: expected one of ${STORE_KINDS.map((k) => `"${k}"`).join(', ')}.`,
-    );
-  }
-}
-
-function validateVettedBy(vettedBy: string): void {
-  if (vettedBy.trim().length === 0 || vettedBy.includes('\n') || vettedBy.length > 80) {
-    throw new StoreError(
-      'STORE_INVALID_VETTER',
-      'Invalid --by value: name the operator vouching for this content (single line, at most 80 characters).',
-    );
-  }
-}
-
-function lstatIfPresent(path: string): Stats | undefined {
-  try {
-    return lstatSync(path);
-  } catch (error: unknown) {
-    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') return undefined;
-    throw error;
-  }
-}
-
-function assertNoSymlinkAncestors(path: string): void {
-  const absolute = resolve(path);
-  const pathRoot = parse(absolute).root;
-  let current = pathRoot;
-
-  for (const segment of relative(pathRoot, absolute).split(sep)) {
-    if (segment.length === 0) continue;
-    current = join(current, segment);
-    const entry = lstatIfPresent(current);
-    if (!entry) break;
-    if (entry.isSymbolicLink()) {
-      throw new StoreError(
-        'STORE_SYMLINK_ROOT',
-        `Refusing symlink ancestor at ${current}; the user store root must resolve without symlink traversal.`,
-      );
-    }
-  }
-}
-
-/** `plugins` for plugin, `skills` for skill — plural on disk per the layout. */
-function kindDirName(kind: StoreKind): string {
-  return kind === 'plugin' ? 'plugins' : 'skills';
-}
-
-export function storeKindDir(kind: StoreKind, paths: StorePaths = getDefaultStorePaths()): string {
-  return join(paths.userRoot, kindDirName(kind));
-}
-
-function entryDir(kind: StoreKind, name: string, version: string, paths: StorePaths): string {
-  return join(storeKindDir(kind, paths), name, version);
-}
-
-function isInsideRoot(candidate: string, root: string): boolean {
-  const rel = relative(resolve(root), resolve(candidate));
-  return rel.length > 0 && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
-}
-
-/**
- * Refuse any symlink in the source tree — the vetting boundary copies real
- * content only, so a vetted entry can never carry a link that escapes it.
- *
- * NOTE: known check-then-use window between this walk and the `cpSync` below:
- * a symlink created concurrently with the add could slip through. Accepted
- * for a local, operator-run CLI; revisit before any unattended or networked
- * acquisition path exists.
- */
-function assertSourceTreeHasNoSymlinks(sourcePath: string): void {
-  const stack: string[] = [sourcePath];
-  while (stack.length > 0) {
-    const current = stack.pop()!;
-    for (const dirent of readdirSync(current, { withFileTypes: true })) {
-      const child = join(current, dirent.name);
-      if (dirent.isSymbolicLink()) {
-        throw new StoreError(
-          'STORE_SOURCE_SYMLINK',
-          `Refusing to vet content containing a symlink: ${child}. Resolve or remove symlinks before adding to the store.`,
-        );
-      }
-      if (dirent.isDirectory()) stack.push(child);
-    }
-  }
-}
-
-/**
- * Vet and add one versioned entry to the user store.
- *
- * Copies the source directory (real content, no symlinks) to
- * `<userRoot>/<kind>s/<name>/<version>/` and writes the `store-entry.json`
- * marker LAST: a crash mid-copy leaves at most a recoverable partial, never a
- * half-vetted entry that lists as present.
- */
-export function addStoreEntry(
-  kind: StoreKind,
-  name: string,
-  version: string,
-  sourcePath: string,
-  vettedBy: string,
-  notes: string | undefined,
-  paths: StorePaths = getDefaultStorePaths(),
-  options: { reclaim?: boolean } = {},
-): StoreAddResult {
-  validateStoreKind(kind);
-  validateStoreName(name);
-  validateStoreVersion(version);
-  validateVettedBy(vettedBy);
-  assertNoSymlinkAncestors(paths.userRoot);
-
-  const resolvedSource = resolve(sourcePath);
-  const source = lstatIfPresent(resolvedSource);
-  if (!source) {
-    throw new StoreError('STORE_SOURCE_MISSING', `Source path does not exist: ${resolvedSource}`);
-  }
-  if (source.isSymbolicLink()) {
-    throw new StoreError(
-      'STORE_SOURCE_SYMLINK',
-      `Refusing to vet a symlink as store content: ${resolvedSource} (points at ${resolve(sourcePath)}). Add the real directory.`,
-    );
-  }
-  if (!source.isDirectory()) {
-    throw new StoreError(
-      'STORE_SOURCE_NOT_DIR',
-      `Source path is not a directory: ${resolvedSource}`,
-    );
-  }
-  if (isInsideRoot(resolvedSource, paths.userRoot)) {
-    throw new StoreError(
-      'STORE_SOURCE_INSIDE_STORE',
-      `Refusing to add store content from inside the store itself: ${resolvedSource}`,
-    );
-  }
-  assertSourceTreeHasNoSymlinks(resolvedSource);
-
-  const target = entryDir(kind, name, version, paths);
-  const existing = lstatIfPresent(target);
-  let status: StoreAddStatus = 'added';
-  if (existing) {
-    if (existsSync(join(target, STORE_ENTRY_MARKER))) {
-      throw new StoreError(
-        'STORE_ALREADY_PRESENT',
-        `${kind} "${name}" version "${version}" is already present at ${target}; stores are append-only — add a new version instead.`,
-      );
-    }
-    // Unmarked target: either this tool's own debris from an interrupted add,
-    // or content the operator placed by hand — indistinguishable on disk. The
-    // USER root's contract is that tooling never destroys operator content,
-    // so deletion requires the explicit --reclaim opt-in (review finding on
-    // c23a71d7: silent rmSync under a benign-sounding status).
-    if (!options.reclaim) {
-      throw new StoreError(
-        'STORE_TARGET_UNMARKED',
-        `Target exists without ${STORE_ENTRY_MARKER}: ${target}. Refusing to delete unmarked content — if this is debris from an interrupted add, re-run with --reclaim to replace it.`,
-      );
-    }
-    rmSync(target, { recursive: true, force: true });
-    status = 'reclaimed-unmarked';
-  }
-
-  mkdirSync(target, { recursive: true });
-  cpSync(resolvedSource, target, { recursive: true });
-
-  const meta: StoreEntryMeta = {
-    schema: 1,
-    kind,
-    name,
-    version,
-    sourcePath: resolvedSource,
-    vettedBy: vettedBy.trim(),
-    vettedAt: new Date().toISOString(),
-    ...(notes === undefined ? {} : { notes }),
-  };
-  writeFileSync(join(target, STORE_ENTRY_MARKER), `${JSON.stringify(meta, null, 2)}\n`);
-
-  return { kind, name, version, status, entryPath: target, sourcePath: resolvedSource };
-}
-
-function readEntryMeta(markerPath: string): { meta?: StoreEntryMeta; status: StoreEntryStatus } {
-  let raw: string;
-  try {
-    raw = readFileSync(markerPath, 'utf-8');
-  } catch {
-    return { status: 'invalid-metadata' };
-  }
-  try {
-    const parsed = JSON.parse(raw) as StoreEntryMeta;
-    if (
-      parsed?.schema === 1 &&
-      (STORE_KINDS as readonly string[]).includes(parsed.kind) &&
-      typeof parsed.name === 'string' &&
-      typeof parsed.version === 'string' &&
-      typeof parsed.vettedBy === 'string' &&
-      typeof parsed.vettedAt === 'string'
-    ) {
-      return { meta: parsed, status: 'vetted' };
-    }
-  } catch {
-    // fall through
-  }
-  return { status: 'invalid-metadata' };
-}
-
-/**
- * Enumerate every store entry deterministically (kind, then name, then
- * version). Version directories without a marker list as `incomplete`; files
- * where directories were expected list as `foreign` — surfaced, never mutated.
- */
-export function listStoreEntries(
-  paths: StorePaths = getDefaultStorePaths(),
-  filter: { kind?: StoreKind; name?: string } = {},
-): StoreListEntry[] {
-  if (filter.name !== undefined) validateStoreName(filter.name);
-  assertNoSymlinkAncestors(paths.userRoot);
-
-  const kinds = filter.kind ? [filter.kind] : [...STORE_KINDS];
-  const entries: StoreListEntry[] = [];
-
-  for (const kind of kinds) {
-    const kindRoot = lstatIfPresent(storeKindDir(kind, paths));
-    if (!kindRoot) continue;
-    if (!kindRoot.isDirectory()) {
-      entries.push({
-        kind,
-        name: kindDirName(kind),
-        status: 'foreign',
-        entryPath: storeKindDir(kind, paths),
-      });
-      continue;
-    }
-
-    for (const nameDirent of readdirSync(storeKindDir(kind, paths), {
-      withFileTypes: true,
-    }).sort(byName) as Dirent[]) {
-      if (filter.name !== undefined && nameDirent.name !== filter.name) continue;
-      const namePath = join(storeKindDir(kind, paths), nameDirent.name);
-
-      if (!nameDirent.isDirectory()) {
-        entries.push({ kind, name: nameDirent.name, status: 'foreign', entryPath: namePath });
-        continue;
-      }
-
-      const versionDirents = readdirSync(namePath, { withFileTypes: true }).sort(byName);
-      if (versionDirents.length === 0) {
-        entries.push({ kind, name: nameDirent.name, status: 'incomplete', entryPath: namePath });
-        continue;
-      }
-      for (const versionDirent of versionDirents) {
-        const versionPath = join(namePath, versionDirent.name);
-        if (!versionDirent.isDirectory()) {
-          entries.push({
-            kind,
-            name: nameDirent.name,
-            version: versionDirent.name,
-            status: 'foreign',
-            entryPath: versionPath,
-          });
-          continue;
-        }
-        const markerPath = join(versionPath, STORE_ENTRY_MARKER);
-        if (!existsSync(markerPath)) {
-          entries.push({
-            kind,
-            name: nameDirent.name,
-            version: versionDirent.name,
-            status: 'incomplete',
-            entryPath: versionPath,
-          });
-          continue;
-        }
-        const { meta, status } = readEntryMeta(markerPath);
-        entries.push({
-          kind,
-          name: nameDirent.name,
-          version: versionDirent.name,
-          status,
-          entryPath: versionPath,
-          ...(meta === undefined ? {} : { meta }),
-        });
-      }
-    }
-  }
-
-  return entries;
-}
-
-function byName(a: Dirent, b: Dirent): number {
-  return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
-}
-
-function reportCommandError(error: unknown): void {
-  if (error instanceof StoreError) {
-    console.error(`store: ${error.code}: ${error.message}`);
-  } else {
-    console.error(error instanceof Error ? error.message : String(error));
-  }
-  process.exitCode = 1;
-}
-
-function displayStoreName(name: string): string {
-  return SAFE_STORE_NAME.test(name) ? name : JSON.stringify(name);
-}
-
-/** Register the `mosaic store` command group (W-F4). */
-export function registerStoreCommand(
-  program: Command,
-  paths: StorePaths = getDefaultStorePaths(),
-): void {
-  const store = program
-    .command('store')
-    .description('Manage the vetted user store under ~/.mosaic (plugins, skills)')
-    .configureHelp({ sortSubcommands: true });
-
-  store
-    .command('add <kind> <name> <version>')
-    .description(
-      'Vet and add a local plugin/skill directory to the user store (versioned, append-only)',
-    )
-    .requiredOption('--from <path>', 'Local source directory to vet (no network acquisition)')
-    .requiredOption('--by <operator>', 'Name of the operator vouching for this content')
-    .option('--notes <notes>', 'Vetting notes recorded in the entry metadata')
-    .option(
-      '--reclaim',
-      'Replace an existing UNMARKED target directory (e.g. debris from an interrupted add); refuses without this flag',
-    )
-    .action(
-      async (
-        kind: string,
-        name: string,
-        version: string,
-        opts: {
-          from: string;
-          by: string;
-          notes?: string;
-          reclaim: boolean;
-        },
-      ) => {
-        try {
-          const result = addStoreEntry(
-            kind as StoreKind,
-            name,
-            version,
-            opts.from,
-            opts.by,
-            opts.notes,
-            paths,
-            { reclaim: opts.reclaim },
-          );
-          const suffix =
-            result.status === 'reclaimed-unmarked' ? ' (replaced unmarked directory)' : '';
-          console.log(
-            `${result.kind} ${displayStoreName(result.name)} ${result.version}: added${suffix}`,
-          );
-          console.log(`  entry: ${result.entryPath}`);
-          console.log(`  vetted by ${opts.by.trim()}`);
-        } catch (error: unknown) {
-          reportCommandError(error);
-        }
-      },
-    );
-
-  store
-    .command('list')
-    .description('List store entries with vetting status')
-    .option('--kind <kind>', 'Filter by kind (plugin | skill)')
-    .option('--name <name>', 'Filter by entry name')
-    .action((opts: { kind?: string; name?: string }) => {
-      try {
-        let kind: StoreKind | undefined;
-        if (opts.kind !== undefined) {
-          validateStoreKind(opts.kind);
-          kind = opts.kind;
-        }
-        const entries = listStoreEntries(paths, {
-          ...(kind === undefined ? {} : { kind }),
-          ...(opts.name === undefined ? {} : { name: opts.name }),
-        });
-        if (entries.length === 0) {
-          console.log('No store entries found.');
-          return;
-        }
-        for (const entry of entries) {
-          const version = entry.version ?? '-';
-          const vetter = entry.meta?.vettedBy ?? '-';
-          console.log(
-            `${entry.status.padEnd(17)}${entry.kind.padEnd(8)}${displayStoreName(entry.name).padEnd(24)}${version.padEnd(16)}${vetter}`,
-          );
-        }
-      } catch (error: unknown) {
-        reportCommandError(error);
-      }
-    });
-}

packages/mosaic/src/constants.ts

@@ -5,13 +5,6 @@ export const VERSION = '0.0.2';
 
 export const DEFAULT_MOSAIC_HOME = join(homedir(), '.config', 'mosaic');
 
-/**
- * USER data root (HARNESS-HOMES two-root split): everything under here is user
- * content — never replaced or removed by installs, updates, or uninstallers.
- * Distinct from the SYSTEM root above, which is update-owned.
- */
-export const DEFAULT_MOSAIC_USER_HOME = join(homedir(), '.mosaic');
-
 export const DEFAULTS = {
   agentName: 'Assistant',
   roleDescription: 'execution partner and visibility engine',