workspace-maxxing 0.1.0

package/docs/superpowers/specs/2026-04-07-workspace-builder-logic-design.md

@@ -0,0 +1,179 @@
+# Workspace-Maxxing Design Spec — Sub-Project 2: Workspace Builder Logic
+
+> **Phase 2 of 4:** Helper scripts + enhanced skill instructions. Subsequent phases add autonomous iteration and benchmarking.
+
+## Context
+
+Sub-Project 1 delivered the npx CLI that installs a SKILL.md and ICM workspace templates. Sub-Project 2 adds executable helper scripts that the agent uses to scaffold, validate, and install tools for workspaces — replacing manual file creation with reliable, programmatic generation.
+
+## Architecture
+
+### Components
+
+#### 1. Scaffold Script (`scripts/scaffold.ts`)
+
+Generates ICM-compliant workspace structures from a JSON plan.
+
+**CLI Interface:**
+```bash
+node scripts/scaffold.ts --name "research" --stages "01-research,02-analysis,03-report" --output ./workspace
+```
+
+**What it creates:**
+- `SYSTEM.md` (Layer 0) with folder map matching the provided stages
+- `CONTEXT.md` (Layer 1) with routing table for each stage
+- Numbered stage folders, each with a `CONTEXT.md` (Layer 2)
+- `README.md` with usage instructions
+- `00-meta/tools.md` for tool inventory
+
+**Dependencies:** Node.js builtins only (`fs`, `path`, `process`)
+
+#### 2. Validate Script (`scripts/validate.ts`)
+
+Checks a workspace for ICM compliance.
+
+**CLI Interface:**
+```bash
+node scripts/validate.ts --workspace ./workspace
+```
+
+**What it checks:**
+- SYSTEM.md exists and contains a folder map
+- CONTEXT.md exists at root level
+- Every numbered folder has a CONTEXT.md
+- No empty CONTEXT.md files
+- One-way dependency compliance (downstream folders don't reference upstream in reverse)
+- No duplicate content across files (canonical source check — basic heuristic: flags any identical text blocks > 50 characters found in multiple files)
+
+**Output:** Prints pass/fail per check. Exit code 0 if all pass, 1 if any fail.
+
+**Dependencies:** Node.js builtins only
+
+#### 3. Install Tool Script (`scripts/install-tool.ts`)
+
+Installs tools and updates workspace inventory.
+
+**CLI Interface:**
+```bash
+node scripts/install-tool.ts --tool "pdf-lib" --manager npm --workspace ./workspace
+```
+
+**What it does:**
+- Runs the appropriate install command (`npm install`, `pip install`, etc.)
+- Updates `00-meta/tools.md` with the tool name, version, and timestamp
+- Supports managers: `npm`, `pip`, `npx` (global), `brew`
+
+**Dependencies:** Node.js builtins + `child_process` for running install commands
+
+#### 4. Enhanced SKILL.md
+
+Updated to include:
+- "## Available Scripts" section documenting all three scripts
+- Examples of how to invoke each script
+- Workflow: scaffold → validate → fix → install tools → validate → deliver
+- When to use scripts vs. manual file creation (scripts for structure, manual for content)
+
+### File Structure
+
+```
+workspace-maxxing/
+├── src/
+│   ├── scripts/
+│   │   ├── scaffold.ts       — Scaffold script source
+│   │   ├── validate.ts       — Validate script source
+│   │   └── install-tool.ts   — Install tool script source
+│   ├── index.ts              — Unchanged from Phase 1
+│   └── install.ts            — Modified: also copies scripts/
+├── templates/
+│   ├── SKILL.md              — Enhanced with script instructions
+│   └── .workspace-templates/
+│       └── scripts/          — Scripts copied during install
+│           ├── scaffold.ts
+│           ├── validate.ts
+│           └── install-tool.ts
+├── tests/
+│   ├── scaffold.test.ts
+│   ├── validate.test.ts
+│   └── install-tool.test.ts
+```
+
+### Data Flow
+
+```
+User: "Create a research workspace that outputs PDFs"
+  │
+  ▼
+Agent reads SKILL.md → sees Available Scripts section
+  │
+  ▼
+Agent proposes workspace structure to user
+  │
+  ▼
+User approves
+  │
+  ▼
+Agent runs: node scripts/scaffold.ts --name "research" --stages "01-research,02-analysis,03-pdf-export" --output ./workspace
+  │
+  ▼
+Agent runs: node scripts/validate.ts --workspace ./workspace
+  │
+  ├─ If FAIL → Agent reads errors, fixes workspace, re-validates
+  │
+  ▼
+Agent assesses tools → proposes pdf-lib, puppeteer, etc.
+  │
+  ▼
+User approves
+  │
+  ▼
+Agent runs: node scripts/install-tool.ts --tool "pdf-lib" --manager npm --workspace ./workspace
+  │
+  ▼
+Agent runs: node scripts/validate.ts --workspace ./workspace  (final check)
+  │
+  ▼
+Deliver: workspace + USAGE.md
+```
+
+### Changes to Existing Files
+
+**`src/install.ts`:** Add scripts directory to the copy list. When installing the skill, also copy `templates/.workspace-templates/scripts/` to the skill directory.
+
+**`templates/SKILL.md`:** Add "## Available Scripts" section with usage examples for all three scripts.
+
+### Error Handling
+
+- **scaffold.ts:** Fails if output directory already exists (with `--force` flag to overwrite). Fails if stages list is empty or malformed.
+- **validate.ts:** Never fails with exception — always returns structured output. Exit code indicates pass/fail.
+- **install-tool.ts:** Fails if install command returns non-zero exit code. Reports error message from the package manager.
+
+### Testing Strategy
+
+- **scaffold.test.ts:** Verify correct folder structure is created, SYSTEM.md has correct folder map, CONTEXT.md files exist for each stage
+- **validate.test.ts:** Create valid workspace → expect pass. Create invalid workspace (missing CONTEXT.md, empty files) → expect specific failures
+- **install-tool.test.ts:** Mock child_process.execSync, verify correct command is run and tools.md is updated
+- **Integration:** Run scaffold → validate → expect pass
+
+### Scope
+
+**In Scope (This Phase):**
+- Three helper scripts (scaffold, validate, install-tool)
+- Enhanced SKILL.md with script usage instructions
+- Installer updated to copy scripts
+- Tests for all three scripts
+
+**Out of Scope (Future Phases):**
+- Autonomous iteration engine (Phase 3)
+- Sub-agent orchestration framework (Phase 3)
+- Benchmark scoring system (Phase 4)
+- Multi-agent support (Phase 4)
+- Hill-climbing on scores (Phase 3)
+
+### Success Criteria
+
+1. `node scripts/scaffold.ts` creates valid ICM workspace from plan
+2. `node scripts/validate.ts` correctly identifies valid and invalid workspaces
+3. `node scripts/install-tool.ts` installs packages and updates inventory
+4. Enhanced SKILL.md documents all scripts with examples
+5. Installer copies scripts to skill directory
+6. All tests pass (Phase 1 + Phase 2)

package/docs/superpowers/specs/2026-04-07-workspace-maxxing-design.md

@@ -0,0 +1,227 @@
+# Workspace-Maxxing Design Spec
+
+## Sub-Project 1: npx CLI + Base Skill
+
+> **Phase 1 of 4:** Installer + skill foundation. Subsequent phases add workspace builder logic, autonomous iteration, and benchmarking.
+
+## Context
+
+Workspace-Maxxing is an npx-installable skill that enables AI coding agents (starting with OpenCode) to create, iterate on, and validate structured workspaces using the Interpretable Context Methodology (ICM) by Jake Van Clief. The workspace IS the skill — a folder structure with interconnected markdown files that doubles as an installable skill package.
+
+**Inspired by:**
+- [AutoAgent](https://github.com/kevinrgu/autoagent) — autonomous harness engineering via meta-agent iteration
+- [ICM Paper](https://arxiv.org/abs/2603.16021) — folder structure as agentic architecture
+- [Content-Agent-Routing-Promptbase](https://github.com/RinDig/Content-Agent-Routing-Promptbase) — layered routing architecture for AI context
+
+## Architecture
+
+### Layered Routing Model (ICM)
+
+```
+Layer 0 — SYSTEM.md (always loaded)
+  ├── Folder map + ID systems
+  ├── Core instructions for the agent
+  └── ~800 tokens
+
+Layer 1 — CONTEXT.md (routing table)
+  ├── Maps tasks to workspaces
+  └── ~300 tokens
+
+Layer 2 — Workspace CONTEXT.md (per-folder)
+  ├── What to load, in what order, for what task
+  └── ~200-500 tokens each
+
+Layer 3 — Content Files (selectively loaded)
+  ├── Actual reference material
+  └── ~500-3000 tokens each
+```
+
+### Core Principles
+
+1. **Canonical Sources** — Every piece of information lives in exactly one place. Files point to data, never duplicate it.
+2. **One-Way Dependencies** — A → B is fine. B → A creates O(n²) maintenance. If bidirectional, introduce C.
+3. **Selective Section Loading** — Route to sections of files, not entire files. Load only what the task needs.
+4. **Numbered Folders** — Represent workflow stages. 01-research → 02-draft → 03-review → 04-output.
+5. **Routing ≠ Content** — CONTEXT.md files tell agents what to load. They don't contain the knowledge itself.
+
+## System Design
+
+### Components
+
+#### 1. npx CLI (`src/index.ts`)
+
+Entry point. Parses arguments, delegates to installer.
+
+```
+npx workspace-maxxing --opencode
+```
+
+- `--opencode` — installs skill into `.agents/skills/workspace-maxxing/`
+- Future flags: `--claude`, `--copilot`, `--gemini`
+
+#### 2. Installer (`src/install.ts`)
+
+- Detects project root (nearest `.git` or `package.json`)
+- Creates `.agents/skills/workspace-maxxing/` directory
+- Copies `SKILL.md` and `.workspace-templates/` from package
+- Idempotent: safe to run multiple times
+- No runtime dependencies beyond Node.js builtins (`fs`, `path`)
+
+#### 3. Skill File (`templates/SKILL.md`)
+
+The core artifact. Instructions for OpenCode agents on how to:
+
+- **Intent Capture:** Understand what workspace the user wants
+- **Propose Structure:** Design workspace using ICM methodology
+- **Human Approval Gate:** Present plan, wait for approval
+- **Build Workspace:** Create numbered folders, markdown files, routing tables
+- **Tool Assessment:** Scan available tools, propose installations, get approval
+- **Autonomous Iteration:** After build, spawn sub-agents to test with diverse use cases, self-evaluate, update prompts, only involve human if confidence is low
+- **Final Output:** Deliver workspace + skill package + usage guide
+
+The SKILL.md must contain these sections:
+
+```markdown
+# Workspace-Maxxing Skill
+
+## Role
+You are a workspace architect. You create structured, ICM-compliant workspaces.
+
+## Process
+1. CAPTURE INTENT — Ask: "What workflow do you want to automate?"
+2. PROPOSE STRUCTURE — Design workspace with numbered folders, CONTEXT.md routing files, canonical sources
+3. GET APPROVAL — Present plan. Wait. Do not build until approved.
+4. BUILD WORKSPACE — Create folders, markdown files, routing tables
+5. ASSESS TOOLS — Scan environment. List available tools. Propose missing tools needed. Get approval.
+6. INSTALL TOOLS — After approval, install proposed tools
+7. TEST AUTONOMOUSLY — Spawn sub-agents with diverse test cases. Self-evaluate outputs.
+8. ITERATE — Update system prompts based on test results. Only involve human if confidence is low.
+9. DELIVER — Output: workspace folder + skill package + usage guide
+
+## ICM Rules
+- Canonical sources: each fact lives in exactly one file
+- One-way dependencies only: A → B, never B → A
+- Selective loading: route to sections, not whole files
+- Numbered folders for workflow stages
+
+## Output Format
+- workspace/ — the built workspace
+- .agents/skills/<workspace-name>/ — installable skill
+- USAGE.md — how to use this workspace in future sessions
+```
+
+#### 4. Workspace Templates (`templates/.workspace-templates/`)
+
+Base structure copied during install:
+
+```
+.workspace-templates/
+├── SYSTEM.md              # Layer 0 template (always loaded)
+├── CONTEXT.md             # Layer 1 routing template
+└── workspace/             # Example workspace skeleton
+    ├── 00-meta/
+    │   └── CONTEXT.md     # Workspace-level routing
+    ├── 01-input/
+    │   └── CONTEXT.md
+    ├── 02-process/
+    │   └── CONTEXT.md
+    ├── 03-output/
+    │   └── CONTEXT.md
+    └── README.md          # Usage guide template
+```
+
+### File Map (Project Structure)
+
+```
+workspace-maxxing/
+├── package.json
+├── tsconfig.json
+├── src/
+│   ├── index.ts           # CLI entry point
+│   └── install.ts         # File copying, path resolution
+├── templates/
+│   ├── SKILL.md           # Agent instructions (installed as skill)
+│   └── .workspace-templates/
+│       ├── SYSTEM.md      # Layer 0 template
+│       ├── CONTEXT.md     # Layer 1 routing template
+│       └── workspace/     # Workspace skeleton
+│           ├── 00-meta/CONTEXT.md
+│           ├── 01-input/CONTEXT.md
+│           ├── 02-process/CONTEXT.md
+│           ├── 03-output/CONTEXT.md
+│           └── README.md
+└── docs/
+    └── superpowers/
+        └── specs/
+            └── 2026-04-07-workspace-maxxing-design.md
+```
+
+### Data Flow
+
+```
+User runs: npx workspace-maxxing --opencode
+    │
+    ▼
+CLI parses args → calls installer
+    │
+    ▼
+Installer copies files to .agents/skills/workspace-maxxing/
+    │
+    ▼
+User opens new OpenCode session, invokes skill
+    │
+    ▼
+Agent reads SKILL.md → follows instructions:
+    1. Captures user intent ("create a research workspace")
+    2. Proposes workspace structure (ICM-based)
+    3. User approves
+    4. Agent builds workspace from templates + customization
+    5. Agent assesses available tools, proposes installations
+    6. User approves tool installations
+    7. Agent installs tools
+    8. Agent spawns sub-agents to test workspace
+    9. Sub-agents self-evaluate, update prompts
+    10. Human involved only if confidence is low
+    11. Final output: workspace + skill package + usage guide
+```
+
+### Error Handling
+
+- **Missing project root:** Warn user, install in current directory
+- **Existing skill directory:** Overwrite with confirmation message
+- **Failed file copy:** Abort, report which file failed, no partial state
+- **Invalid flag:** Show usage help with supported flags
+
+### Testing Strategy
+
+- **CLI tests:** Verify `--opencode` flag creates correct directory structure
+- **Installer tests:** Verify idempotency, correct file paths, no partial state on failure
+- **Template validation:** Verify all template files exist and are non-empty
+- **Integration test:** Run `npx workspace-maxxing --opencode` in temp directory, verify skill is loadable
+
+## Scope
+
+### In Scope (This Phase)
+
+- npx CLI with `--opencode` flag
+- Installer that copies skill files
+- SKILL.md with complete agent instructions for workspace creation
+- Workspace templates (ICM structure)
+- Basic tool assessment instructions in SKILL.md
+
+### Out of Scope (Future Phases)
+
+- Autonomous iteration engine (Phase 3)
+- Sub-agent orchestration framework (Phase 2)
+- Benchmark scoring system (Phase 4)
+- Multi-agent support --claude, --copilot, --gemini (Phase 4)
+- Hill-climbing on scores (Phase 3)
+- Human checkpoint UI (Phase 3)
+
+## Success Criteria
+
+1. `npx workspace-maxxing --opencode` installs a working skill
+2. OpenCode agent can read the skill and understand how to build workspaces
+3. Installed skill includes valid ICM-structured workspace templates
+4. Running installer twice produces same result (idempotent)
+5. Zero runtime dependencies beyond Node.js builtins

package/docs/superpowers/specs/2026-04-08-session-294c-subagent-invocation-design.md

@@ -0,0 +1,265 @@
+# Session 294c Workflow Quality and Sub-Agent Invocation Hardening - Design Spec
+
+## Overview
+
+This spec assesses `session-ses_294c.md` end-to-end and defines a corrective design so WorkflowMaxxing runs true agent-driven loops instead of simulated script loops. The core gap is that worker/fixer "sub-agents" were not actually spawned as agents; they were routed through local script dispatch, leading to fake passes, path churn, benchmark gaming, and unstable completion claims.
+
+## Goals
+
+1. Enforce real sub-agent execution for worker/fixer loops.
+2. Make agent-generated test-cases the canonical input to iteration.
+3. Prevent false completion claims when validation or threshold gates are not met.
+4. Remove brittle setup steps (`npm init`, ad-hoc TypeScript bootstrapping) from skill usage flow.
+5. Add deterministic diagnostics for runner failures and score inconsistencies.
+
+## Non-Goals
+
+1. No redesign of the ICM folder model.
+2. No replacement of benchmark methodology in this phase.
+3. No UI changes; this is workflow/runtime behavior hardening.
+
+## Transcript Assessment Method
+
+- Source: `C:\Users\E1560361\Desktop\npx-test-workspace\session-ses_294c.md`
+- Unit of review: each user query, then assistant reasoning/output sequence attached to that query.
+- Output: per-step quality rating and tagged defects.
+
+## Query-by-Query Process Assessment
+
+### Query 1
+User query: "workspace that will give me a daily digest of all things AI"
+
+| Step | Assistant Reasoning/Output | Quality | Tags |
+|---|---|---|---|
+| 1.1 | Loaded `workspace-maxxing` skill before implementation | Good | - |
+| 1.2 | Loaded `research` skill, but treated dispatch/load as execution | Poor | FLOW-SA-001 |
+| 1.3 | Performed repeated script/path inspection instead of executing sub-agent workflow contract | Poor | FLOW-SA-003, FLOW-PATH-001 |
+| 1.4 | Bootstrapped target workspace (`npm init`, `npm install`, custom `tsconfig`) to run copied scripts | Poor | FLOW-CLI-001 |
+| 1.5 | Used bash idioms in PowerShell (`&&`, `head`) causing avoidable failures | Poor | FLOW-CLI-002 |
+| 1.6 | Manually copied skill trees to satisfy incorrect runtime assumptions | Poor | FLOW-PATH-001 |
+| 1.7 | Generated `research-findings.md` manually by controller, not a spawned sub-agent | Mixed | FLOW-SA-003 |
+| 1.8 | Requested architecture approval before scaffold | Good | - |
+| 1.9 | Ran scaffold with `--force`, wiping runtime `.agents` state and re-copying manually | Poor | FLOW-STATE-001 |
+| 1.10 | Used `dispatch --skill validation` and interpreted "loaded successfully" as validation activity | Poor | FLOW-SA-001 |
+| 1.11 | Ran `validate.ts` directly and got real output | Good | - |
+| 1.12 | Claimed completion with score 33/100 and later 81/100 (<85 target) | Poor | FLOW-QUALITY-001 |
+
+### Query 2
+User query: "continue next steps"
+
+| Step | Assistant Reasoning/Output | Quality | Tags |
+|---|---|---|---|
+| 2.1 | Generated test-cases to `./workspace/test-cases.json` | Poor | FLOW-TEST-001 |
+| 2.2 | Ran orchestrator without runner and got explicit requirement error | Good diagnosis | - |
+| 2.3 | Framed manual fallback but still kept script-centric loop | Poor | FLOW-SA-003 |
+
+### Query 3
+User query: "2" (external runner)
+
+| Step | Assistant Reasoning/Output | Quality | Tags |
+|---|---|---|---|
+| 3.1 | Passed `--subagent-runner` command that calls `dispatch.ts` itself | Critical defect | FLOW-SA-002 |
+| 3.2 | Orchestrator escalated all batches; no true worker/fixer agent reasoning happened | Poor | FLOW-SA-002, FLOW-SA-003 |
+| 3.3 | Continued by manually editing stage docs to increase scores | Poor | FLOW-QUALITY-003 |
+
+### Query 4
+User query: user pasted iteration skill contract
+
+| Step | Assistant Reasoning/Output | Quality | Tags |
+|---|---|---|---|
+| 4.1 | Ran `iterate.ts` appropriately per user instruction | Good | - |
+| 4.2 | Accepted inconsistent outputs (`iterate` reports score 100 while benchmark remained 81) without reconciliation | Critical defect | FLOW-QUALITY-002 |
+| 4.3 | Optimized for benchmark keywords (Approach/Risks/Timeline/Resources etc.) rather than evidence-backed workflow quality | Poor | FLOW-QUALITY-003 |
+| 4.4 | Repeatedly ignored duplicate-content validation failures as "boilerplate" without rule-aware mitigation | Poor | FLOW-VAL-001 |
+
+## Defect Tag Catalog
+
+### FLOW-SA-001 - Dispatch/load conflated with execution
+Severity: High
+
+Symptom:
+- `dispatch.ts` result "Sub-skill loaded successfully" treated as if the skill had been executed.
+
+Impact:
+- Phases appear complete without real work.
+
+### FLOW-SA-002 - Runner recursion / fake external runner
+Severity: Critical
+
+Symptom:
+- `--subagent-runner` points to `dispatch.ts`, which itself returns simulated reports for worker/fixer when no true external runner emits structured output.
+
+Impact:
+- No actual sub-agent reasoning loop occurs.
+
+### FLOW-SA-003 - No true sub-agent spawn contract
+Severity: Critical
+
+Symptom:
+- No invocation path for real agent workers (for example, an explicit `npx` agent command or platform subagent primitive).
+
+Impact:
+- "Agent-driven" flow is script-driven simulation.
+
+### FLOW-CLI-001 - Environment bootstrapping in target workspace
+Severity: Medium
+
+Symptom:
+- `npm init`, dependency install, and compile steps executed in user target workspace during normal skill use.
+
+Impact:
+- Pollutes user workspace and adds unnecessary failure modes.
+
+### FLOW-CLI-002 - Shell dialect mismatch
+Severity: Medium
+
+Symptom:
+- Unix command idioms used in PowerShell.
+
+Impact:
+- Repeated avoidable command failures.
+
+### FLOW-PATH-001 - Fragile skill path assumptions
+Severity: High
+
+Symptom:
+- Manual copying/restructuring of skill folders required for dispatch path expectations.
+
+Impact:
+- Non-deterministic setup and brittle runtime behavior.
+
+### FLOW-STATE-001 - Runtime state destruction during scaffold
+Severity: Medium
+
+Symptom:
+- `--force` scaffold overwrote workspace and removed runtime state (`.agents/...`) requiring manual restoration.
+
+Impact:
+- Hidden regressions and operator confusion.
+
+### FLOW-TEST-001 - Non-canonical test-case path
+Severity: High
+
+Symptom:
+- Tests generated outside canonical `.agents/iteration/test-cases.json`.
+
+Impact:
+- Orchestrator/validator cannot rely on stable source-of-truth inputs.
+
+### FLOW-QUALITY-001 - Premature success claims
+Severity: Critical
+
+Symptom:
+- Completion claims made while score threshold not met (`81 < 85`).
+
+Impact:
+- False delivery confidence.
+
+### FLOW-QUALITY-002 - Score inconsistency not reconciled
+Severity: Critical
+
+Symptom:
+- Contradictory scoring outputs accepted without resolving source-of-truth.
+
+Impact:
+- Decision-making based on invalid state.
+
+### FLOW-QUALITY-003 - Benchmark gaming vs real improvement
+Severity: High
+
+Symptom:
+- Added keyword sections primarily to satisfy benchmark heuristics.
+
+Impact:
+- Inflated score not guaranteed to reflect real workflow quality.
+
+### FLOW-VAL-001 - Repeated validation failure rationalized away
+Severity: High
+
+Symptom:
+- Duplicate-content check kept failing, but process continued as if non-blocking.
+
+Impact:
+- Violates strict verification standard.
+
+## Gap vs Subagent-Driven-Development Skill
+
+Expected by `subagent-driven-development`:
+1. Fresh implementer subagent per task.
+2. Explicit spec-compliance reviewer subagent.
+3. Explicit code-quality reviewer subagent.
+4. Review loops before task completion.
+
+Observed in session:
+1. Controller performed manual edits directly.
+2. No implementer/spec-review/code-review subagent orchestration.
+3. No two-stage review gates.
+4. No task-level subagent lifecycle telemetry.
+
+Conclusion:
+- Current loop is not subagent-driven. It is script-dispatch-driven with simulated returns.
+
+## Target Design
+
+### 1) Real Runner Contract
+
+Define a strict external runner contract for worker/fixer:
+
+Input placeholders:
+- `{skill}`
+- `{workspace}`
+- `{batchId}`
+- `{testCaseId}`
+
+Output contract (JSON only):
+- `skill`, `status`, `timestamp`, `findings`, `recommendations`, `metrics`, `nextSkill`
+
+Hard rule:
+- Worker/fixer dispatch without valid runner output must fail, never "simulated pass".
+
+### 2) Canonical Agent-Generated Test-Cases
+
+- Authoritative file: `.agents/iteration/test-cases.json`
+- Required readiness marker: `.agents/iteration/.test-cases-ready`
+- Required metadata fields: `id`, `input`, `expected`, `generatedBy`, `timestamp`
+
+### 3) Quality Gate Hardening
+
+Release gate must require all:
+1. Benchmark score >= threshold.
+2. Validation passed with no blocking findings.
+3. No metric conflicts between `iterate.ts`, `benchmark.ts`, and orchestrator summary.
+
+### 4) Path and Setup Simplification
+
+- No local project bootstrap in target workspace.
+- Use packaged CLI and runtime scripts only.
+- Add preflight checks with explicit remediation text.
+
+### 5) Subagent Lifecycle Telemetry
+
+Store per invocation under `.agents/iteration/runs/`:
+- command template
+- rendered command
+- stdout/stderr (bounded)
+- parsed JSON
+- duration/exit code
+
+## Acceptance Criteria
+
+1. Worker/fixer loops fail fast if no real runner output is produced.
+2. Orchestrator uses `.agents/iteration/test-cases.json` as authoritative input.
+3. At least one integration test verifies runner execution actually occurs (not simulated path).
+4. Completion claim is blocked when score < threshold or validation has blocking findings.
+5. Session equivalent to 294c can run end-to-end without manual path surgery or local bootstrap.
+
+## Risks and Mitigations
+
+1. Risk: Runner command portability across shells.
+- Mitigation: document Windows-safe examples and parse command with explicit shell mode tests.
+
+2. Risk: Existing users rely on simulated fallback.
+- Mitigation: introduce explicit `--simulate` mode; default remains strict for worker/fixer.
+
+3. Risk: Benchmark heuristic can still be gamed.
+- Mitigation: add artifact-presence checks tied to stage-required evidence.