fix(store): refuse unmarked targets by default; reclaim only under --reclaim (W-F4 review)

Resolves the review finding on c23a71d7: 'store add' silently deleted a markerless target directory and reported it as recovered-partial, but the code cannot distinguish its own interrupted-write debris from content the operator placed by hand — and the USER root's entire contract is that tooling never destroys operator content. - addStoreEntry now throws typed STORE_TARGET_UNMARKED on an unmarked target; deletion happens only when the caller passes { reclaim: true }. - CLI: 'store add' gains --reclaim ('replace an existing UNMARKED target directory; refuses without this flag'). - Status renamed recovered-partial -> reclaimed-unmarked so even the opted-in path names what it did (fix 2 folded into fix 1). - Spec: default-refusal test asserts operator content SURVIVES; opt-in test asserts replacement; two CLI tests cover exit codes. - Ordering test (second review round): 'reclaim can never destroy a marked, vetted entry' — adds a vetted entry, re-adds with reclaim:true, asserts STORE_ALREADY_PRESENT AND the original content + marker survive on disk. Pins marker-check-before-reclaim-check against the guard-clause-migrates-upward refactor; discrimination proven by sabotaging the order (1 failed, exactly this test) and restoring (49/49). - TOCTOU note added at assertSourceTreeHasNoSymlinks per review (known check-then-use window, accepted for a local operator-run CLI). Gates (settled set, rc-honest): store spec 49/49; package vitest 87 files / 1596 tests; package build+lint rc0; root build 25/25 + typecheck 45/45; prettier --check rc0 on all four touched files. c23a71d7 remains the reviewed object, untouched.
feat(mosaic): vetted user store — mosaic store add|list (W-F4)
2026-08-17 13:16:23 -05:00 · 2026-08-17 13:09:24 -05:00
20 changed files with 1218 additions and 1410 deletions
@@ -34,7 +34,6 @@ 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',
          ],
        },
@@ -539,43 +539,3 @@ 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`.
@@ -1,319 +0,0 @@
 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 });
    }
  });
 });
@@ -12,10 +12,10 @@ import {
  resumePipeline,
  getPipelineStatus,
 } from '../src/pipeline-runner.js';
-import type { ForgeTask, ForgeTaskResult, RunManifest, TaskExecutor } from '../src/types.js';
+import type { ForgeTask, RunManifest, TaskExecutor } from '../src/types.js';
-import { gateLabel, isCommandGate } from '../src/outcomes.js';
+import type { TaskResult } from '@mosaicstack/macp';
-/** Mock TaskExecutor that records submitted tasks and returns typed results. */
+/** Mock TaskExecutor that records submitted tasks and returns success. */
 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<ForgeTaskResult> {
+    async waitForCompletion(taskId: string): Promise<TaskResult> {
      const failStage = options?.failStage;
      const task = submittedTasks.find((t) => t.id === taskId);
      const stageName = task?.metadata?.['stageName'] as string | undefined;
@@ -33,8 +33,7 @@ function createMockExecutor(options?: {
      if (failStage && stageName === failStage) {
        return {
          task_id: taskId,
-          outcome: 'failed',
+          status: 'failed',
          reason: 'mock task failure',
          completed_at: new Date().toISOString(),
          exit_code: 1,
          gate_results: [],
@@ -42,17 +41,10 @@ function createMockExecutor(options?: {
      }
      return {
        task_id: taskId,
-        outcome: 'passed',
+        status: 'completed',
        reason: 'mock verified',
        completed_at: new Date().toISOString(),
        exit_code: 0,
-        gate_results: (task?.qualityGates ?? [])
+        gate_results: [],
          .filter((gate) => isCommandGate(gate))
          .map((gate) => ({
            gate: gateLabel(gate),
            outcome: 'passed' as const,
            reason: 'mock verified',
          })),
      };
    },
    async getTaskStatus() {
@@ -164,13 +156,12 @@ describe('runPipeline', () => {
    const executor = createMockExecutor();
    const result = await runPipeline(briefPath, tmpDir, {
      executor,
-      stages: ['00-intake', '05-coding'],
+      stages: ['00-intake', '00b-discovery'],
    });
    expect(result.runId).toMatch(/^\d{8}-\d{6}$/);
-    expect(result.stages).toEqual(['00-intake', '05-coding']);
+    expect(result.stages).toEqual(['00-intake', '00b-discovery']);
    expect(result.manifest.status).toBe('completed');
    expect(result.manifest.mode).toBe('normal');
    expect(executor.submittedTasks).toHaveLength(2);
  });
@@ -189,17 +180,12 @@ describe('runPipeline', () => {
    const executor = createMockExecutor();
    const result = await runPipeline(briefPath, tmpDir, {
      executor,
-      stages: ['00-intake', '05-coding'],
+      stages: ['00-intake', '00b-discovery'],
    });
    const manifest = loadManifest(result.runDir);
    expect(manifest.stages['00-intake']?.status).toBe('passed');
-    expect(manifest.stages['05-coding']?.status).toBe('passed');
+    expect(manifest.stages['00b-discovery']?.status).toBe('passed');
    expect(manifest.stages['05-coding']?.gateResults?.map((g) => g.outcome)).toEqual([
      'passed',
      'passed',
      'passed',
    ]);
  });
  it('respects CLI class override', async () => {
@@ -229,7 +215,7 @@ describe('runPipeline', () => {
    const executor = createMockExecutor();
    await runPipeline(briefPath, tmpDir, {
      executor,
-      stages: ['00-intake', '05-coding', '08-test'],
+      stages: ['00-intake', '00b-discovery', '02-planning-1'],
    });
    expect(executor.submittedTasks[0]!.dependsOn).toBeUndefined();
@@ -238,14 +224,14 @@ describe('runPipeline', () => {
  });
  it('handles stage failure', async () => {
-    const executor = createMockExecutor({ failStage: '05-coding' });
+    const executor = createMockExecutor({ failStage: '00b-discovery' });
    await expect(
      runPipeline(briefPath, tmpDir, {
        executor,
-        stages: ['00-intake', '05-coding'],
+        stages: ['00-intake', '00b-discovery'],
      }),
-    ).rejects.toThrow('Stage 05-coding failed');
+    ).rejects.toThrow('Stage 00b-discovery failed');
  });
  it('marks manifest as failed on stage failure', async () => {
@@ -284,143 +270,30 @@ describe('resumePipeline', () => {
    fs.rmSync(tmpDir, { recursive: true, force: true });
  });
-  it('resumes from first incomplete stage and fails closed at the next provider gate', async () => {
+  it('resumes from first incomplete stage', async () => {
-    // Simulate a run whose authority stages were approved out-of-band
+    // First run fails on discovery
-    // (recorded as passed) and whose coding stage failed mechanically.
+    const executor1 = createMockExecutor({ failStage: '00b-discovery' });
-    const runId = '20260101-000000';
+    let runDir: string;
    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' },
      },
    });
-    // Resume re-runs 05-coding (the first non-passed stage), then fails
+    try {
-    // closed at 06-review because no reviewer provider is wired.
+      await runPipeline(briefPath, tmpDir, {
-    const executor = createMockExecutor();
+        executor: executor1,
-    await expect(resumePipeline(runDir, executor)).rejects.toMatchObject({
+        stages: ['00-intake', '00b-discovery', '02-planning-1'],
-      name: 'ForgeCapabilityError',
+      });
-      code: 'FORGE_NO_REVIEWER',
+    } catch {
-    });
+      // 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');
    }
  });
-  it('fails closed on resume when the next stage needs authority sign-off', async () => {
+    const runsDir = path.join(tmpDir, '.forge', 'runs');
-    const runId = '20260101-000001';
+    runDir = path.join(runsDir, fs.readdirSync(runsDir)[0]!);
    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' },
      },
    });
-    const executor = createMockExecutor();
+    // Resume should pick up from 00b-discovery
-    await expect(resumePipeline(runDir, executor)).rejects.toMatchObject({
+    const executor2 = createMockExecutor();
-      name: 'ForgeCapabilityError',
+    const result = await resumePipeline(runDir, executor2);
      code: 'FORGE_AUTHORITY_REQUIRED',
    });
-    const manifest = loadManifest(runDir);
+    expect(result.manifest.status).toBe('completed');
-    expect(manifest.stages['00b-discovery']?.status).toBe('waiting-for-authority');
+    // Should have re-run from 00b-discovery onward
-    expect(manifest.status).toBe('waiting-for-authority');
+    expect(result.stages[0]).toBe('00b-discovery');
  });
  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',
    });
  });
 });
@@ -95,14 +95,7 @@ export function generateBoardTasks(
      briefPath,
      resultPath: resultRelPath,
      timeoutSeconds: 120,
-      qualityGates: [
+      qualityGates: ['true'],
        {
          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,
@@ -128,13 +121,7 @@ export function generateBoardTasks(
    timeoutSeconds: 120,
    dependsOn: personaTaskIds,
    dependsOnPolicy: 'all_terminal',
-    qualityGates: [
+    qualityGates: ['true'],
      {
        kind: 'authority',
        capability: 'board-approval',
        reason: 'board synthesis is an authority decision; no mechanical gate exists',
      },
    ],
    metadata: {
      resultOutputPath: synthesisResult,
      inputResultPaths: personaResultPaths,
@@ -1,11 +1,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { Command } from 'commander';
-import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import { describe, expect, it } from 'vitest';
 import { registerForgeCommand } from './cli.js';
 import { loadManifest } from './pipeline-runner.js';
 describe('registerForgeCommand', () => {
  it('registers a "forge" command on the parent program', () => {
@@ -59,94 +55,3 @@ 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');
  });
 });
@@ -5,47 +5,37 @@ 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 { createSimulatedExecutor } from './simulated-executor.js';
+import type { PipelineOptions, RunManifest, TaskExecutor } from './types.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();
@@ -54,24 +44,19 @@ 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(24) + 'Duration');
+  console.log('Stage'.padEnd(22) + 'Status'.padEnd(14) + 'Duration');
-  console.log('-'.repeat(60));
+  console.log('-'.repeat(50));
  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(24);
+    const status = s.status.padEnd(14);
    const dur = formatDuration(s.startedAt, s.completedAt);
    console.log(`${label}${status}${dur}`);
  }
@@ -105,58 +90,23 @@ function listRecentRuns(projectRoot?: string): void {
  }
  console.log('\nRecent runs:');
-  console.log('Run ID'.padEnd(22) + 'Status'.padEnd(24) + 'Mode'.padEnd(12) + 'Brief');
+  console.log('Run ID'.padEnd(22) + 'Status'.padEnd(14) + 'Brief');
-  console.log('-'.repeat(80));
+  console.log('-'.repeat(70));
  for (const runId of entries) {
    const runDir = path.join(runsDir, runId);
    try {
      const manifest = loadManifest(runDir);
-      const status = manifest.status.padEnd(24);
+      const status = manifest.status.padEnd(14);
      const mode = runModeOf(manifest).padEnd(12);
      const brief = path.basename(manifest.brief);
-      console.log(`${runId.padEnd(22)}${status}${mode}${brief}`);
+      console.log(`${runId.padEnd(22)}${status}${brief}`);
    } catch {
-      console.log(`${runId.padEnd(22)}${'(unreadable)'.padEnd(24)}`);
+      console.log(`${runId.padEnd(22)}${'(unreadable)'.padEnd(14)}`);
    }
  }
  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
 // ---------------------------------------------------------------------------
@@ -179,11 +129,6 @@ 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;
@@ -192,7 +137,6 @@ export function registerForgeCommand(parent: Command): void {
        config?: string;
        codebase: string;
        dryRun: boolean;
        simulate: boolean;
      }) => {
        const briefPath = path.resolve(opts.brief);
@@ -205,22 +149,14 @@ 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}`);
-          try {
+          const { resumePipeline } = await import('./pipeline-runner.js');
-            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);
          } catch (err) {
            handlePipelineError(err);
          }
          return;
        }
@@ -228,8 +164,7 @@ export function registerForgeCommand(parent: Command): void {
          briefClass,
          codebase: projectRoot,
          dryRun: opts.dryRun,
-          executor,
+          executor: stubExecutor,
          simulate: opts.simulate,
        };
        if (opts.dryRun) {
@@ -245,15 +180,16 @@ 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);
-          applyRunExitPolicy(result, opts.simulate);
+          console.log(`[forge] pipeline complete: ${result.runId}`);
          console.log(`[forge] run directory: ${result.runDir}`);
        } catch (err) {
-          handlePipelineError(err);
+          console.error(
            `[forge] pipeline failed: ${err instanceof Error ? err.message : String(err)}`,
          );
          process.exitCode = 1;
        }
      },
    );
@@ -288,12 +224,7 @@ 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())
-    .option(
+    .action(async (runId: string, opts: { project: string }) => {
      '--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)) {
@@ -303,20 +234,15 @@ 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, executor, { simulate: opts.simulate });
+        const result = await resumePipeline(runDir, stubExecutor);
-        applyRunExitPolicy(result, opts.simulate);
+        console.log(`[forge] pipeline complete: ${result.runId}`);
        console.log(`[forge] run directory: ${result.runDir}`);
      } catch (err) {
-        handlePipelineError(err);
+        console.error(`[forge] resume failed: ${err instanceof Error ? err.message : String(err)}`);
        process.exitCode = 1;
      }
    });
@@ -9,16 +9,7 @@ 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',
@@ -36,13 +27,7 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
    type: 'research',
    gate: 'discovery-complete',
    promptFile: '00b-discovery.md',
-    qualityGates: [
+    qualityGates: ['true'],
      {
        kind: 'authority',
        capability: 'discovery-complete',
        reason: 'discovery completion is attested by an authority; no mechanical check exists',
      },
    ],
  },
  '01-board': {
    number: '01',
@@ -51,13 +36,7 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
    type: 'review',
    gate: 'board-approval',
    promptFile: '01-board.md',
-    qualityGates: [
+    qualityGates: [{ type: 'ci-pipeline', command: 'board-approval (via board-tasks)' }],
      {
        kind: 'authority',
        capability: 'board-approval',
        reason: 'board approval is a board/human decision; no mechanical gate exists',
      },
    ],
  },
  '01b-brief-analyzer': {
    number: '01b',
@@ -66,13 +45,7 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
    type: 'research',
    gate: 'brief-analysis-complete',
    promptFile: '01-board.md',
-    qualityGates: [
+    qualityGates: ['true'],
      {
        kind: 'authority',
        capability: 'brief-analysis-complete',
        reason: 'brief analysis completion is attested by an authority; no mechanical check exists',
      },
    ],
  },
  '02-planning-1': {
    number: '02',
@@ -81,13 +54,7 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
    type: 'research',
    gate: 'architecture-approval',
    promptFile: '02-planning-1-architecture.md',
-    qualityGates: [
+    qualityGates: ['true'],
      {
        kind: 'authority',
        capability: 'architecture-approval',
        reason: 'ADR approval requires authority sign-off; no mechanical check exists',
      },
    ],
  },
  '03-planning-2': {
    number: '03',
@@ -96,14 +63,7 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
    type: 'research',
    gate: 'implementation-approval',
    promptFile: '03-planning-2-implementation.md',
-    qualityGates: [
+    qualityGates: ['true'],
      {
        kind: 'authority',
        capability: 'implementation-approval',
        reason:
          'implementation spec approval requires authority sign-off; no mechanical check exists',
      },
    ],
  },
  '04-planning-3': {
    number: '04',
@@ -112,14 +72,7 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
    type: 'research',
    gate: 'decomposition-approval',
    promptFile: '04-planning-3-decomposition.md',
-    qualityGates: [
+    qualityGates: ['true'],
      {
        kind: 'authority',
        capability: 'decomposition-approval',
        reason:
          'task decomposition approval requires authority sign-off; no mechanical check exists',
      },
    ],
  },
  '05-coding': {
    number: '05',
@@ -139,10 +92,9 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
    promptFile: '06-review.md',
    qualityGates: [
      {
-        kind: 'provider',
+        type: 'ai-review',
-        capability: 'reviewer',
+        command:
-        reason:
+          'echo \'{"summary":"review-pass","verdict":"approve","findings":[],"stats":{"blockers":0,"should_fix":0,"suggestions":0}}\'',
          'review verdicts require a wired reviewer provider; synthetic approvals are not permitted',
      },
    ],
  },
@@ -153,13 +105,7 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
    type: 'coding',
    gate: 're-review',
    promptFile: '07-remediate.md',
-    qualityGates: [
+    qualityGates: ['true'],
      {
        kind: 'authority',
        capability: 're-review',
        reason: 'remediation re-review is an approval-based gate; no mechanical check exists',
      },
    ],
  },
  '08-test': {
    number: '08',
@@ -177,13 +123,7 @@ export const STAGE_SPECS: Record<string, StageSpec> = {
    type: 'deploy',
    gate: 'deploy-verification',
    promptFile: '09-deploy.md',
-    qualityGates: [
+    qualityGates: [{ type: 'ci-pipeline', command: 'deploy-verification' }],
      {
        kind: 'provider',
        capability: 'ci-pipeline',
        reason: 'deploy verification requires a wired CI pipeline provider',
      },
    ],
  },
 };
@@ -1,46 +0,0 @@
 /**
 * 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';
  }
 }
@@ -5,13 +5,6 @@ export type {
  StageSpec,
  BriefClass,
  ClassSource,
  ForgeOutcome,
  AuthorityGate,
  ProviderGate,
  ForgeGate,
  ForgeGateResult,
  ForgeTaskResult,
  RunMode,
  StageStatus,
  RunManifest,
  ForgeTaskStatus,
@@ -88,24 +81,5 @@ 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';
@@ -1,147 +0,0 @@
 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,
  };
 }
@@ -1,33 +1,18 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { STAGE_SEQUENCE, STAGE_SPECS } from './constants.js';
+import { STAGE_SEQUENCE } 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.
 */
@@ -62,7 +47,6 @@ function createManifest(opts: {
  briefClass: RunManifest['briefClass'];
  classSource: RunManifest['classSource'];
  forceBoard: boolean;
  mode: RunMode;
  runDir: string;
 }): RunManifest {
  const ts = nowISO();
@@ -73,7 +57,6 @@ function createManifest(opts: {
    briefClass: opts.briefClass,
    classSource: opts.classSource,
    forceBoard: opts.forceBoard,
    mode: opts.mode,
    createdAt: ts,
    updatedAt: ts,
    currentStage: '',
@@ -125,199 +108,20 @@ 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. Fail closed unless a real executor is wired or simulation is explicit
+ * 1. Classify the brief
- * 2. Classify the brief
+ * 2. Generate a run ID and create run directory
- * 3. Generate a run ID and create run directory
+ * 3. Map stages to tasks and submit to TaskExecutor
- * 4. Map stages to tasks and submit to TaskExecutor
+ * 4. Track manifest with stage statuses
- * 5. Track manifest with typed stage outcomes
+ * 5. Return pipeline result
 * 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');
@@ -342,7 +146,6 @@ export async function runPipeline(
    briefClass,
    classSource,
    forceBoard: options.forceBoard ?? false,
    mode,
    runDir,
  });
@@ -369,10 +172,54 @@ export async function runPipeline(
  }
  // Execute stages
-  await executeStages({ manifest, runDir, tasks, stageNames: selectedStages, executor, simulate });
+  const { executor } = options;
  for (let i = 0; i < tasks.length; i++) {
    const task = tasks[i]!;
    const stageName = selectedStages[i]!;
-  // All stages reached a terminal state for this mode
+    // Update manifest: stage in progress
-  manifest.status = simulate ? 'simulated' : 'completed';
+    manifest.currentStage = stageName;
    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 {
@@ -387,30 +234,22 @@ export async function runPipeline(
 }
 /**
- * Resume a pipeline from the last non-passed stage.
+ * Resume a pipeline from the last incomplete 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);
-  manifest.mode = mode;
+  // Find first non-passed stage
  // 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 = mode === 'simulated' ? 'simulated' : 'completed';
+    manifest.status = 'completed';
    saveManifest(runDir, manifest);
    return {
      runId: manifest.runId,
@@ -445,16 +284,49 @@ export async function resumePipeline(
    tasks.push(task);
  }
-  await executeStages({
+  for (let i = 0; i < tasks.length; i++) {
-    manifest,
+    const task = tasks[i]!;
-    runDir,
+    const stageName = remainingStages[i]!;
    tasks,
    stageNames: remainingStages,
    executor: wiredExecutor,
    simulate,
  });
-  manifest.status = simulate ? 'simulated' : 'completed';
+    manifest.currentStage = stageName;
    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 {
@@ -1,32 +0,0 @@
 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;
    },
  };
 }
@@ -1,4 +1,4 @@
-import type { GateEntry } from '@mosaicstack/macp';
+import type { GateEntry, TaskResult } from '@mosaicstack/macp';
 /** Stage dispatch mode. */
 export type StageDispatch = 'exec' | 'yolo' | 'pi';
@@ -6,58 +6,6 @@ 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;
@@ -66,7 +14,7 @@ export interface StageSpec {
  type: StageType;
  gate: string;
  promptFile: string;
-  qualityGates: ForgeGate[];
+  qualityGates: (string | GateEntry)[];
 }
 /** Brief classification. */
@@ -77,18 +25,11 @@ export type ClassSource = 'cli' | 'frontmatter' | 'auto';
 /** Per-stage status within a run manifest. */
 export interface StageStatus {
-  status: 'pending' | 'in_progress' | ForgeOutcome;
+  status: 'pending' | 'in_progress' | 'passed' | 'failed';
  /** 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;
@@ -97,23 +38,10 @@ 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:
+  status: 'in_progress' | 'completed' | 'failed' | 'interrupted' | 'rejected';
    | 'in_progress'
    | 'completed'
    | 'failed'
    | 'interrupted'
    | 'rejected'
    | 'simulated'
    | 'waiting-for-authority';
  stages: Record<string, StageStatus>;
 }
@@ -137,7 +65,7 @@ export interface ForgeTask {
  briefPath: string;
  resultPath: string;
  timeoutSeconds: number;
-  qualityGates: ForgeGate[];
+  qualityGates: (string | GateEntry)[];
  worktree?: string;
  command?: string;
  dependsOn?: string[];
@@ -148,7 +76,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<ForgeTaskResult>;
+  waitForCompletion(taskId: string, timeoutMs: number): Promise<TaskResult>;
  getTaskStatus(taskId: string): Promise<ForgeTaskStatus>;
 }
@@ -194,16 +122,7 @@ 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. */
@@ -39,20 +39,3 @@ 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
@@ -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/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/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"
  },
  "dependencies": {
    "@mosaicstack/brain": "workspace:*",
@@ -20,6 +20,7 @@ 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';
@@ -425,6 +426,10 @@ registerRestoreCommand(program);
 registerSkillCommand(program);
 // ─── store ───────────────────────────────────────────────────────────────────
 registerStoreCommand(program);
 // ─── telemetry ───────────────────────────────────────────────────────────────
 registerTelemetryCommand(program);
@@ -0,0 +1,458 @@
 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();
    });
  });
 });
@@ -0,0 +1,544 @@
 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);
      }
    });
 }
@@ -5,6 +5,13 @@ 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',