sofia-cli 0.1.1

package/specs/004-dev-resume-hardening/contracts/cli.md

@@ -0,0 +1,160 @@
+# CLI Contracts: Dev Resume & Hardening
+
+**Feature**: 004-dev-resume-hardening  
+**Date**: 2026-03-01
+
+## `sofia dev` Command Contract
+
+### Synopsis
+
+```
+sofia dev --session <id> [--force] [--max-iterations <n>] [--output-dir <path>] [--debug]
+```
+
+### Resume Behavior (New)
+
+| Session State                                | `--force` | Behavior                                       |
+| -------------------------------------------- | --------- | ---------------------------------------------- |
+| `poc` undefined                              | N/A       | Fresh run: scaffold → install → iterate from 1 |
+| `poc.finalStatus` = `'success'`              | `false`   | Exit with "PoC already complete" message       |
+| `poc.finalStatus` = `'success'`              | `true`    | Reset poc → fresh run                          |
+| `poc.finalStatus` = `'failed'`/`'partial'`   | `false`   | Resume from last iteration (default)           |
+| `poc.finalStatus` = `'failed'`/`'partial'`   | `true`    | Reset poc → fresh run                          |
+| `poc.finalStatus` undefined + iterations > 0 | `false`   | Resume from last completed iteration           |
+| `poc.finalStatus` undefined + iterations > 0 | `true`    | Reset poc → fresh run                          |
+
+### Exit Codes
+
+| Code | Meaning                                                        |
+| ---- | -------------------------------------------------------------- |
+| `0`  | PoC completed successfully (tests passing) or already complete |
+| `0`  | PoC resumed and completed                                      |
+| `1`  | Error during execution                                         |
+| `0`  | User interrupted (Ctrl+C) — session saved for resume           |
+
+### Info-Level Resume Logs (FR-007a)
+
+All resume decisions produce info-level log messages (visible without `--debug`):
+
+```
+Resuming session abc123 from iteration 5 (4 completed iterations found)
+Re-running incomplete iteration 4 (no test results recorded)
+Skipping scaffold — output directory and .sofia-metadata.json present
+Re-running dependency installation (npm install)
+Selected template: node-ts-vitest (matched 'typescript' in architecture notes)
+```
+
+### `--force` Reset Contract
+
+When `--force` is specified:
+
+1. Delete output directory (`rm -rf <outputDir>`)
+2. Clear `session.poc` entirely (`session.poc = undefined`)
+3. Persist session (`store.save(session)`)
+4. Proceed with fresh scaffold → install → iterate from 1
+
+**Post-condition**: `session.poc.iterations` is empty after first `updateSessionPoc` call.
+
+---
+
+## Template Registry Contract
+
+### Template Selection
+
+```typescript
+// Input: plan's architectureNotes + dependencies
+// Output: TemplateEntry
+selectTemplate(registry, architectureNotes?, dependencies?): TemplateEntry
+```
+
+**Selection rules** (first match wins, case-insensitive):
+
+1. Concatenate `architectureNotes` + `dependencies` into search text
+2. For each registry entry (in registration order), check if any `matchPattern` appears in search text
+3. If match found → return that entry
+4. If no match → return `node-ts-vitest` (default)
+
+### Registered Templates
+
+#### `node-ts-vitest` (default)
+
+| Field          | Value                                                                                                                     |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| installCommand | `npm install`                                                                                                             |
+| testCommand    | `npm test -- --reporter=json`                                                                                             |
+| matchPatterns  | `typescript`, `node`, `vitest`, `ts`                                                                                      |
+| files          | `.gitignore`, `package.json`, `tsconfig.json`, `README.md`, `src/index.ts`, `tests/index.test.ts`, `.sofia-metadata.json` |
+
+#### `python-pytest`
+
+| Field          | Value                                                                                                                                       |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| installCommand | `pip install -r requirements.txt`                                                                                                           |
+| testCommand    | `pytest --tb=short -q --json-report --json-report-file=-`                                                                                   |
+| matchPatterns  | `python`, `fastapi`, `flask`, `django`, `pytest`                                                                                            |
+| files          | `.gitignore`, `requirements.txt`, `pytest.ini`, `README.md`, `src/__init__.py`, `src/main.py`, `tests/test_main.py`, `.sofia-metadata.json` |
+
+---
+
+## Workshop → Dev Transition Contract
+
+### Plan Phase Completion Output
+
+When the Plan phase completes in `sofia workshop`, the following message MUST be displayed:
+
+```markdown
+### Ready for PoC Generation
+
+The Plan phase is complete. To generate the proof-of-concept, run:
+```
+
+sofia dev --session <actual-session-id>
+
+```
+
+This will scaffold a project matching your plan's technology stack, install dependencies,
+and iteratively generate code until all tests pass.
+```
+
+### Interactive Mode Offer (FR-021, SHOULD)
+
+In interactive mode, after the above message, the system SHOULD offer:
+
+```
+? Would you like to start PoC development now? (Y/n)
+```
+
+- **Yes** (default): Invoke `developCommand` internally with the current session
+- **No**: Save session and exit with the command displayed above
+
+---
+
+## `.sofia-metadata.json` Extended Schema
+
+```json
+{
+  "sessionId": "string",
+  "featureSpec": "string",
+  "generatedAt": "ISO 8601 string",
+  "ideaTitle": "string",
+  "totalIterations": 0,
+  "finalStatus": "string | null",
+  "terminationReason": "string | null",
+  "techStack": {
+    "language": "string",
+    "runtime": "string",
+    "testRunner": "string"
+  },
+  "templateId": "string",
+  "todos": {
+    "totalInitial": 0,
+    "remaining": 0,
+    "markers": ["string"]
+  }
+}
+```
+
+New fields:
+
+- `templateId`: Which template was used (for resume context)
+- `todos`: TODO marker tracking (FR-022)

package/specs/004-dev-resume-hardening/data-model.md

@@ -0,0 +1,321 @@
+# Data Model: Dev Resume & Hardening
+
+**Feature**: 004-dev-resume-hardening  
+**Date**: 2026-03-01
+
+## Entity Overview
+
+```
+┌──────────────────────┐     uses      ┌──────────────────────┐
+│   CheckpointState    │◄─────────────│  developCommand.ts    │
+│  (runtime derived)   │               │  (entry point)       │
+└──────────┬───────────┘               └──────────┬───────────┘
+           │                                      │
+           │ reads from                           │ passes to
+           ▼                                      ▼
+┌──────────────────────┐               ┌──────────────────────┐
+│ PocDevelopmentState  │◄──────────────│    RalphLoop         │
+│  (session.poc)       │   updates     │  (seeds iterations)  │
+│  [EXISTING SCHEMA]   │               └──────────┬───────────┘
+└──────────────────────┘                          │
+                                                  │ uses
+                                                  ▼
+                                       ┌──────────────────────┐
+                                       │   TemplateRegistry   │
+                                       │  (template lookup)   │
+                                       └──────────┬───────────┘
+                                                  │
+                                                  │ contains
+                                                  ▼
+                                       ┌──────────────────────┐
+                                       │   TemplateEntry      │
+                                       │  (scaffold config)   │
+                                       └──────────────────────┘
+```
+
+## Entity Definitions
+
+### CheckpointState (New — runtime-only, not persisted)
+
+Derived from existing `session.poc` to determine resume behavior. This is NOT a new schema — it's a convenience type used by `developCommand.ts` and `RalphLoop.run()` to make resume decisions.
+
+```typescript
+export interface CheckpointState {
+  /** Whether a prior PoC run exists */
+  hasPriorRun: boolean;
+  /** Number of fully completed iterations (with testResults) */
+  completedIterations: number;
+  /** Whether the last iteration was interrupted (no testResults) */
+  lastIterationIncomplete: boolean;
+  /** The iteration number to resume from */
+  resumeFromIteration: number;
+  /** Whether scaffolding can be skipped (output dir + metadata exist) */
+  canSkipScaffold: boolean;
+  /** Final status from prior run, if any */
+  priorFinalStatus: 'success' | 'failed' | 'partial' | undefined;
+  /** Prior iterations for LLM context seeding */
+  priorIterations: PocIteration[];
+}
+```
+
+**Derivation logic**:
+
+```typescript
+function deriveCheckpointState(session: WorkshopSession, outputDir: string): CheckpointState {
+  const poc = session.poc;
+  if (!poc || poc.iterations.length === 0) {
+    return {
+      hasPriorRun: false,
+      completedIterations: 0,
+      lastIterationIncomplete: false,
+      resumeFromIteration: 1,
+      canSkipScaffold: false,
+      priorFinalStatus: undefined,
+      priorIterations: [],
+    };
+  }
+
+  const lastIter = poc.iterations[poc.iterations.length - 1];
+  const lastIncomplete = !lastIter.testResults && lastIter.outcome !== 'scaffold';
+  const completedIters = lastIncomplete ? poc.iterations.slice(0, -1) : poc.iterations;
+
+  const metadataExists = existsSync(join(outputDir, '.sofia-metadata.json'));
+
+  return {
+    hasPriorRun: true,
+    completedIterations: completedIters.length,
+    lastIterationIncomplete: lastIncomplete,
+    resumeFromIteration: completedIters.length + 1,
+    canSkipScaffold: metadataExists,
+    priorFinalStatus: poc.finalStatus,
+    priorIterations: completedIters,
+  };
+}
+```
+
+**Validation rules**:
+
+- `resumeFromIteration` >= 1
+- `completedIterations` >= 0
+- If `lastIterationIncomplete`, the incomplete iteration is excluded from `priorIterations`
+- `canSkipScaffold` requires both output directory AND `.sofia-metadata.json` to exist
+
+---
+
+### TemplateEntry (New — code-defined)
+
+A single scaffold template configuration. Registered in the `TemplateRegistry`.
+
+```typescript
+export interface TemplateEntry {
+  /** Unique template identifier */
+  id: string;
+  /** Human-readable name for logging */
+  displayName: string;
+  /** Scaffold file definitions */
+  files: TemplateFile[];
+  /** Technology stack for session state */
+  techStack: TechStack;
+  /** Command to install dependencies (e.g., 'npm install') */
+  installCommand: string;
+  /** Command to run tests with JSON output (e.g., 'npm test -- --reporter=json') */
+  testCommand: string;
+  /** Keywords to match from plan's architectureNotes/dependencies */
+  matchPatterns: string[];
+}
+```
+
+**Validation rules**:
+
+- `id` must be unique within the registry
+- `files` must include `.sofia-metadata.json`
+- `installCommand` must be non-empty
+- `testCommand` must be non-empty
+- `matchPatterns` must contain at least one pattern (case-insensitive matching)
+
+**Predefined entries**:
+
+| id               | displayName                   | matchPatterns                                        | installCommand                    | testCommand                                               |
+| ---------------- | ----------------------------- | ---------------------------------------------------- | --------------------------------- | --------------------------------------------------------- |
+| `node-ts-vitest` | TypeScript + Node.js + Vitest | `['typescript', 'node', 'vitest', 'ts']`             | `npm install`                     | `npm test -- --reporter=json`                             |
+| `python-pytest`  | Python + pytest               | `['python', 'fastapi', 'flask', 'django', 'pytest']` | `pip install -r requirements.txt` | `pytest --tb=short -q --json-report --json-report-file=-` |
+
+---
+
+### TemplateRegistry (New — code-defined)
+
+Registry type and selection function. Simple map + match-first-wins logic.
+
+```typescript
+export type TemplateRegistry = Map<string, TemplateEntry>;
+
+export function selectTemplate(
+  registry: TemplateRegistry,
+  architectureNotes?: string,
+  dependencies?: string[],
+): TemplateEntry {
+  const searchText = [architectureNotes ?? '', ...(dependencies ?? [])].join(' ').toLowerCase();
+
+  for (const entry of registry.values()) {
+    if (entry.matchPatterns.some((p) => searchText.includes(p.toLowerCase()))) {
+      return entry;
+    }
+  }
+
+  // Default fallback
+  return registry.get('node-ts-vitest')!;
+}
+```
+
+---
+
+### TestFixtureProject (New — test infrastructure)
+
+A minimal project in `tests/fixtures/test-fixture-project/` used by testRunner integration tests. Not a runtime entity — exists only in the test suite.
+
+```
+tests/fixtures/test-fixture-project/
+├── package.json          # minimal: { "scripts": { "test": "vitest run --reporter=json" } }
+├── vitest.config.ts      # minimal config
+├── src/
+│   └── add.ts            # function add(a, b) { return a + b; }
+└── tests/
+    ├── passing.test.ts   # test('adds numbers', () => expect(add(1,2)).toBe(3))
+    ├── failing.test.ts   # test('fails', () => expect(1).toBe(2))
+    └── hanging.test.ts   # test('hangs', async () => await new Promise(() => {}))
+```
+
+**Purpose**: Enables FR-016 through FR-019 (real subprocess testing of testRunner).
+
+---
+
+### SofiaMetadata (Extended — file-system artifact)
+
+Current schema in `.sofia-metadata.json` (pocScaffolder.ts L243-L260), extended with TODO tracking.
+
+```typescript
+interface SofiaMetadata {
+  sessionId: string;
+  featureSpec: string;
+  generatedAt: string;
+  ideaTitle: string;
+  totalIterations: number;
+  finalStatus: string | null;
+  terminationReason: string | null;
+  techStack: {
+    language: string;
+    runtime: string;
+    testRunner: string;
+  };
+  // NEW: FR-022 — scaffold TODO tracking
+  todos?: {
+    totalInitial: number;
+    remaining: number;
+    markers: string[]; // e.g., ["src/main.py:12: TODO: Implement business logic"]
+  };
+}
+```
+
+---
+
+## Existing Entities (Modified)
+
+### TechStack (session.ts — schema extension)
+
+The existing `techStackSchema` may need two optional fields for template-defined commands:
+
+```typescript
+export const techStackSchema = z.object({
+  language: z.string(),
+  framework: z.string().optional(),
+  testRunner: z.string(),
+  buildCommand: z.string().optional(),
+  runtime: z.string(),
+  // Potential additions for Feature 004:
+  installCommand: z.string().optional(), // 'npm install' | 'pip install -r requirements.txt'
+  testCommand: z.string().optional(), // full test command with reporter flags
+});
+```
+
+**Note**: These fields could live solely on `TemplateEntry` rather than in the persisted session schema. If they're only needed at scaffold/runtime and not for resume, keeping them off the session avoids schema migration. Decision: keep `installCommand` and `testCommand` on `TemplateEntry` only. The existing `testRunner` field on `TechStack` (e.g., `'npm test'`) is sufficient for session display purposes.
+
+### PocDevelopmentState (session.ts — no schema change)
+
+The existing schema already supports everything needed for resume:
+
+- `iterations: PocIteration[]` — seeded on resume
+- `finalStatus?: 'success' | 'failed' | 'partial'` — undefined = resumable
+- `terminationReason?` — read for status messages
+- `techStack?` — preserved on resume
+
+No schema migration required. The `.passthrough()` on `WorkshopSession` provides forward compatibility.
+
+## State Transitions
+
+### PoC Lifecycle States
+
+```
+                     ┌──────────┐
+         first run   │  No PoC  │  session.poc = undefined
+                     └────┬─────┘
+                          │ sofia dev --session X
+                          ▼
+                     ┌──────────┐
+                     │ Running  │  finalStatus = undefined, iterations growing
+                     └────┬─────┘
+                          │
+              ┌───────────┼───────────┐
+              ▼           ▼           ▼
+        ┌──────────┐ ┌──────────┐ ┌──────────┐
+        │ Success  │ │ Partial  │ │ Failed   │
+        │ final=   │ │ final=   │ │ final=   │
+        │'success' │ │'partial' │ │'failed'  │
+        └──────────┘ └────┬─────┘ └────┬─────┘
+                          │            │
+                          ▼            ▼
+                     ┌──────────┐ ┌──────────┐
+              resume │Resumable │ │Resumable │ resume
+        (FR-001/006) │ w/prior  │ │ w/prior  │ (FR-006)
+                     └────┬─────┘ └────┬─────┘
+                          │            │
+                          ▼            ▼
+                     ┌──────────┐
+                     │ Running  │  (loop continues from prior state)
+                     └──────────┘
+
+        ┌──────────────────────────┐
+        │  Interrupted (SIGINT)    │  finalStatus = undefined
+        │  iterations.length > 0   │  (directly resumable via FR-001)
+        └──────────────────────────┘
+
+        Any state + --force → No PoC (FR-008/009/010)
+```
+
+### Resume Decision Tree
+
+```
+sofia dev --session X
+│
+├── session.poc undefined?
+│   └── YES → Fresh run (scaffold + install + iterate from 1)
+│
+├── session.poc.finalStatus === 'success'?
+│   └── YES → Display "PoC complete" message, exit (FR-005)
+│
+├── session.poc.finalStatus === 'failed' | 'partial'?
+│   └── YES → Default to resume, allow --force override (FR-006)
+│       └── Resume: seed iterations, start from N+1
+│
+├── session.poc.finalStatus undefined + iterations.length > 0?
+│   └── YES → Resume (interrupted session) (FR-001)
+│       ├── Last iteration has testResults?
+│       │   └── YES → Start from iterations.length + 1
+│       │   └── NO → Pop incomplete, start from iterations.length (FR-001a)
+│       ├── Output dir exists + .sofia-metadata.json?
+│       │   └── YES → Skip scaffold (FR-002)
+│       │   └── NO → Re-scaffold (FR-007)
+│       └── Always re-run npm install (FR-003)
+│
+└── --force flag set?
+    └── YES → Clear poc + delete dir → Fresh run (FR-008/009/010)
+```

package/specs/004-dev-resume-hardening/plan.md

@@ -0,0 +1,107 @@
+# Implementation Plan: Dev Resume & Hardening
+
+**Branch**: `004-dev-resume-hardening` | **Date**: 2026-03-01 | **Spec**: [spec.md](spec.md)
+**Input**: Feature specification from `/specs/004-dev-resume-hardening/spec.md`
+
+## Summary
+
+Harden the `sofia dev` command for production use by implementing resume/checkpoint support (seeding `RalphLoop.run()` from persisted `session.poc.iterations`), fixing `--force` to reset both output directory and session state, introducing a template registry for multi-language PoC scaffolding (starting with `python-pytest`), increasing `testRunner.ts` coverage from 45% to 80%+, and adding workshop→dev transition guidance. The core change is making `RalphLoop` read existing iteration state on startup instead of always starting from `iterations = []`.
+
+## Technical Context
+
+**Language/Version**: TypeScript (ES2022 target) on Node.js ≥ 20 LTS, ESM (`"type": "module"`)  
+**Primary Dependencies**: `@github/copilot-sdk` ^0.1.28, `commander` ^11.1.0, `zod` ^4.3.6, `pino` ^8.17.2, `ora` ^7.0.1, `chalk` ^5.2.0  
+**Storage**: Local JSON files via `SessionStore` (atomic write-then-rename to `.sofia/sessions/<id>.json`)  
+**Testing**: Vitest ^4.0.18 with `@vitest/coverage-v8`; `node-pty` ^1.0.0 for PTY E2E tests  
+**Target Platform**: Linux/macOS/Windows CLI (Node.js LTS)  
+**Project Type**: CLI application  
+**Performance Goals**: Resume detection adds <500ms overhead to `sofia dev` startup (SC-004-007)  
+**Constraints**: No breaking changes to session schema (`.passthrough()` ensures forward compatibility); template registry must be extensible without modifying core scaffolder/loop logic  
+**Scale/Scope**: ~936 lines in `ralphLoop.ts`, ~267 lines in `testRunner.ts`, ~444 lines in `pocScaffolder.ts`, ~267 lines in `developCommand.ts`; 48 existing test files (33 unit, 11 integration, 3 E2E, 1 live)
+
+## Constitution Check
+
+_GATE: Must pass before Phase 0 research. Re-check after Phase 1 design._
+
+| Gate                            | Status  | Evidence                                                                                                                                                                                                                         |
+| ------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Outcome-first discovery**     | ✅ PASS | Resume/checkpoint directly addresses user-reported pain (lost iteration progress on interruption). SC-004-001 through SC-004-007 define measurable outcomes tied to facilitator productivity.                                    |
+| **Secure-by-default**           | ✅ PASS | No new secrets, tokens, or PII handling. Resume reads existing session state from local files already governed by least-privilege. Info-level resume logs contain only iteration numbers and decision flags — no sensitive data. |
+| **Node.js + TypeScript**        | ✅ PASS | All implementation in TypeScript/Node.js using existing SDK patterns. Template registry extends current `PocScaffolder` without introducing new runtimes.                                                                        |
+| **MCP-first**                   | ✅ PASS | No new external integrations introduced. Template registry is code-defined (internal). Existing MCP connections (GitHub, Context7) remain unchanged.                                                                             |
+| **Test-first (NON-NEGOTIABLE)** | ✅ PASS | Spec mandates TDD via constitution. Every task phase starts with failing tests. US4 explicitly targets testRunner coverage from 45% → 80%+.                                                                                      |
+| **CLI transparency**            | ✅ PASS | FR-007a mandates info-level resume decision logging. FR-005/FR-006 require clear completion/status messages. FR-020 requires actionable next-step guidance with exact command.                                                   |
+
+All gates pass. No exceptions required.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/004-dev-resume-hardening/
+├── plan.md              # This file
+├── research.md          # Phase 0 output
+├── data-model.md        # Phase 1 output
+├── quickstart.md        # Phase 1 output
+├── contracts/           # Phase 1 output
+└── tasks.md             # Phase 2 output (created by /speckit.tasks)
+```
+
+### Source Code (repository root)
+
+```text
+src/
+├── cli/
+│   └── developCommand.ts        # Modified: resume detection, --force session reset
+├── develop/
+│   ├── ralphLoop.ts             # Modified: seed iterations from session, skip scaffold
+│   ├── pocScaffolder.ts         # Modified: extract template registry, add python-pytest
+│   ├── templateRegistry.ts      # New: template registry with selection logic
+│   └── testRunner.ts            # Unchanged (tests added, not code)
+├── phases/
+│   └── phaseHandlers.ts         # Modified: Plan phase → dev transition guidance
+├── sessions/
+│   └── sessionManager.ts        # Possibly modified: backtrack for --force poc reset
+└── shared/
+    └── schemas/
+        └── session.ts           # Possibly extended: TechStack install/test commands
+
+tests/
+├── unit/
+│   ├── cli/
+│   │   └── developCommand.spec.ts     # Extended: resume + --force scenarios
+│   └── develop/
+│       ├── ralphLoop.spec.ts          # Extended: resume iteration seeding
+│       ├── pocScaffolder.spec.ts      # Extended: template registry selection
+│       └── templateRegistry.spec.ts   # New: registry unit tests
+├── integration/
+│   ├── ralphLoopFlow.spec.ts          # Extended: full resume flow
+│   ├── ralphLoopPartial.spec.ts       # Extended: partial resume scenarios
+│   └── testRunnerReal.spec.ts         # New: real fixture-based testRunner tests
+├── e2e/
+│   └── developPty.spec.ts            # New: PTY-based interactive E2E
+└── fixtures/
+    └── test-fixture-project/          # New: minimal Vitest project for testRunner tests
+```
+
+**Structure Decision**: Single project (Option 1) — consistent with existing repo layout. New files are limited to `templateRegistry.ts`, test files, and test fixture. All changes extend existing modules.
+
+## Complexity Tracking
+
+> No constitution violations. All gates pass.
+
+## Post-Design Constitution Re-Check
+
+_Re-evaluated after Phase 1 design artifacts (data-model.md, contracts/, quickstart.md)._
+
+| Gate                            | Status  | Post-Design Evidence                                                                                                                                                    |
+| ------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Outcome-first discovery**     | ✅ PASS | CheckpointState derivation directly maps to resume UX outcomes. TemplateRegistry enables multi-language PoC — ties to broader workshop value.                           |
+| **Secure-by-default**           | ✅ PASS | No new data flows. CheckpointState is derived from existing session data. Template registry is code-defined, no external fetches. TODO tracking scans local files only. |
+| **Node.js + TypeScript**        | ✅ PASS | All new types (CheckpointState, TemplateEntry, TemplateRegistry) are TypeScript interfaces. No schema migration needed — existing Zod schemas support resume as-is.     |
+| **MCP-first**                   | ✅ PASS | No new external integrations. Feature is internal hardening.                                                                                                            |
+| **Test-first (NON-NEGOTIABLE)** | ✅ PASS | Quickstart outlines TDD workflow. TestFixtureProject entity provides real subprocess testing. Data model specifies testable derivation logic (deriveCheckpointState).   |
+| **CLI transparency**            | ✅ PASS | Contracts define exact info-level log messages for every resume decision. Workshop→dev transition contract specifies exact command output.                              |
+
+All gates pass post-design. No exceptions required.