@polymorphism-tech/morph-spec 4.3.7 → 4.6.0

package/framework/skills/level-0-meta/tool-usage-guide/SKILL.md

@@ -0,0 +1,334 @@
+---
+name: tool-usage-guide
+description: Decision flowchart and per-phase reference for selecting the right Claude Code tool (Read, Grep, Glob, Bash, Task) or MCP tool in MORPH-SPEC workflows. Use when unsure which tool to use for a given action, when choosing between native tools and MCPs, or when deciding whether to use a subagent vs direct tools.
+user-invocable: true
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Tool Usage Guide for MORPH Workflows
+
+> Operational guide for selecting the correct Claude Code tools and MCP tools at each morph-spec phase. Each phase uses a distinct set of tools optimized for its goals.
+>
+> **Ref:** `framework/standards/integration/mcp/mcp-tools.md` for detailed MCP examples.
+
+---
+
+## Decision Flowchart
+
+```
+┌──────────────────────────────┐
+│ I need to complete an action │
+└──────────────┬───────────────┘
+               │
+               ▼
+┌───────────────────────────────────────┐
+│ Is it a SEARCH for a specific file,   │
+│ keyword, or function?                 │
+└──────┬──────────────────┬─────────────┘
+       │ YES              │ NO
+       ▼                  ▼
+  Use Glob/Grep     ┌─────────────────────────┐
+  or Read            │ Does it need STRUCTURED  │
+                     │ external data (schema,   │
+                     │ API docs, design tokens)?│
+                     └──┬──────────────┬────────┘
+                        │ YES          │ NO
+                        ▼              ▼
+                   Use MCP tool   ┌──────────────────┐
+                   (+ fallback)   │ Does it require   │
+                                  │ MULTI-STEP        │
+                                  │ exploration of     │
+                                  │ many files?        │
+                                  └──┬──────────┬─────┘
+                                     │ YES      │ NO
+                                     ▼          ▼
+                                 Use Task     Do it
+                                 (subagent)   directly
+```
+
+---
+
+## Tools Per Phase
+
+### Phase 0 — Proposal
+
+**Goal:** Understand the feature request and create proposal.md
+
+| Action | Tool | Why |
+|--------|------|-----|
+| Read project context | **Read** `.morph/context/README.md` | Single known file |
+| Read config | **Read** `.morph/config.json` | Single known file |
+| Find existing features | **Glob** `.morph/features/*/0-proposal/proposal.md` | Pattern search |
+| Detect project stack | **Bash** `npx morph-spec detect-agents --json "..."` | CLI command |
+| Research external requirement | **WebSearch** | Current information needed |
+| Render proposal template | **Bash** `npx morph-spec template render docs/proposal ...` | CLI command |
+| Update state | **Bash** `npx morph-spec state mark-output ...` | CLI command |
+
+**MCPs used:** None typically. GitHub MCP if feature comes from an issue.
+
+**Anti-patterns:**
+- ❌ Task agent to read proposal template (just use Read)
+- ❌ Bash `cat` to read files (use Read tool)
+- ❌ Bash `find` to locate files (use Glob tool)
+
+---
+
+### Phase 1 — Setup
+
+**Goal:** Load context, detect stack, activate agents
+
+| Action | Tool | Why |
+|--------|------|-----|
+| Verify feature state | **Bash** `npx morph-spec state get {feature}` | CLI command |
+| Detect agents + standards | **Bash** `npx morph-spec detect-agents --json "..."` | CLI command, returns JSON with standards |
+| Read project context | **Read** `.morph/context/README.md` | Single file |
+| Read config | **Read** `.morph/config.json` | Single file |
+| Scan project structure | **Glob** `src/**/*.{ts,tsx,cs}` | Understand codebase layout |
+| Get repo metadata | **GitHub MCP** `get_repo()` | Structured repo info (if MCP available) |
+| Update state | **Bash** `npx morph-spec state set ...` | CLI command |
+
+**MCPs used:** GitHub (optional — for repo metadata).
+
+**Anti-patterns:**
+- ❌ Task agent to detect project stack (detect-agents CLI does this)
+- ❌ WebSearch for project info (it's local, use Read/Glob)
+- ❌ Manual parsing of agents.json (detect-agents handles it)
+
+---
+
+### Phase 1.5 — UI/UX Design
+
+**Goal:** Create UI mockups, design system, component specs, user flows
+
+| Action | Tool | Why |
+|--------|------|-----|
+| Check existing design system | **Read** `.morph/context/design-system.md` | Single file |
+| Read user-provided screenshots | **Read** (image files) | Claude Code reads images natively |
+| Search for existing CSS variables | **Grep** `--root:` or `--color-` in `*.css,*.scss` | Find existing design tokens |
+| Find existing UI components | **Glob** `**/Components/**/*.razor` or `**/components/**/*.tsx` | Existing patterns |
+| Get Figma design tokens | **Figma MCP** `get_file({ fileKey })` | Extract colors, typography from Figma |
+| Look up component library API | **Context7 MCP** `query_docs({ libraryId, query })` | Accurate component props/events |
+| Preview de página existente | **Playwright MCP** `browser_navigate()` + `browser_take_screenshot()` | **WebFetch** URL |
+| Inspecionar estrutura da página | **Playwright MCP** `browser_snapshot()` | **WebFetch** + parse manual |
+| Testar layout responsivo | **Playwright MCP** `browser_resize()` + `browser_take_screenshot()` | Manual testing |
+| Search for design references | **WebSearch** + **WebFetch** | External inspiration |
+| Render UI templates | **Bash** `npx morph-spec template render docs/ui-mockups ...` | CLI command |
+| Generate design system from CSS | **Bash** `npx morph-spec generate design-system --scan` | CLI command |
+| Update state | **Bash** `npx morph-spec state mark-output ...` | CLI command |
+
+**MCPs used:** Figma (design tokens), Playwright (live preview, page inspection), Context7 (component docs).
+
+**Anti-patterns:**
+- ❌ WebSearch for MudBlazor docs (use Context7 MCP — more accurate)
+- ❌ Task agent to read a single screenshot (just use Read tool on the image)
+- ❌ Manually guessing component props (use Context7 to get real API)
+
+---
+
+### Phase 2 — Design (Technical Spec)
+
+**Goal:** Analyze schema, create spec.md, contracts.cs, decisions.md
+
+| Action | Tool | Why |
+|--------|------|-----|
+| Read proposal + UI specs | **Read** output files | Single known files |
+| Get database schema | **Supabase MCP** `list_tables()`, `get_table_schema()` | **PREFERRED** — real schema data |
+| Get table relationships | **Supabase MCP** `get_relationships()` | Real FK/constraint data |
+| Get RLS policies | **Supabase MCP** `query()` with pg_policies | Security analysis |
+| **Fallback:** Find query files | **Grep** `\.from\(` or `\.select\(` in `*.ts,*.tsx,*.js,*.cs` | When no DB MCP available |
+| **Fallback:** Find type definitions | **Glob** `src/**/types/**/*.ts` or `**/Entities/**/*.cs` | When no DB MCP available |
+| **Fallback:** Read query/type files | **Read** each matched file | Extract field names manually |
+| Look up library for ADR | **Context7 MCP** `query_docs()` | Compare library capabilities |
+| Check existing code patterns | **GitHub MCP** `search_code()` | Find patterns in large repos |
+| **Fallback:** Search codebase | **Grep** patterns across project | When no GitHub MCP |
+| Render contracts template | **Bash** `npx morph-spec template render code/dotnet/contracts/contracts.cs ...` | CLI command |
+| Render spec template | **Bash** `npx morph-spec template render docs/spec ...` | CLI command |
+| Render decisions template | **Bash** `npx morph-spec template render docs/decisions ...` | CLI command |
+| Create schema-analysis.md | **Write** to output directory | Document findings |
+| Update state | **Bash** `npx morph-spec state mark-output ...` | CLI command |
+
+**MCPs used:** Supabase (schema analysis), Context7 (library research), GitHub (code search).
+
+**Anti-patterns:**
+- ❌ Guessing field names without checking schema (use MCP or Grep first!)
+- ❌ Task agent to read a single spec file (just use Read)
+- ❌ WebSearch for database schema (use Supabase MCP or code analysis)
+- ❌ Manually writing contracts.cs from scratch (use template render)
+
+---
+
+### Phase 3 — Clarify
+
+**Goal:** Identify ambiguities, ask clarification questions, update spec
+
+| Action | Tool | Why |
+|--------|------|-----|
+| Read spec.md in detail | **Read** spec.md | Full content analysis |
+| Read contracts.cs | **Read** contracts.cs | Check contract consistency |
+| Read schema-analysis.md | **Read** schema-analysis.md | Cross-reference with spec |
+| Verify library capabilities | **Context7 MCP** `query_docs()` | Confirm feasibility of spec requirements |
+| Check known issues/limitations | **GitHub MCP** `search_issues()` | Library bugs affecting design |
+| Research edge case behavior | **WebSearch** | External knowledge for edge cases |
+| Update spec with clarifications | **Edit** spec.md | Preserve existing content, add sections |
+| Create clarifications.md | **Bash** `npx morph-spec template render docs/clarifications ...` | Use template |
+| Update state | **Bash** `npx morph-spec state mark-output ... clarifications` | CLI command |
+
+**MCPs used:** Context7 (validate feasibility), GitHub (known issues).
+
+**Anti-patterns:**
+- ❌ Task agent to read spec (just Read it directly)
+- ❌ Rewriting spec from scratch (use Edit to update sections)
+- ❌ Skipping schema-analysis.md cross-reference (critical for accuracy)
+
+---
+
+### Phase 4 — Tasks
+
+**Goal:** Break spec into tasks, define dependencies, set checkpoints
+
+| Action | Tool | Why |
+|--------|------|-----|
+| Read spec + contracts + decisions | **Read** all output files | Full context needed |
+| Analyze implementation complexity | **Grep** patterns in existing code | Estimate effort from codebase size |
+| Count existing similar patterns | **Glob** `**/Services/**/*.cs` | Understand scope |
+| Look up implementation patterns | **Context7 MCP** `query_docs()` | Estimate task complexity accurately |
+| Create GitHub issues from tasks | **GitHub MCP** `create_issue()` | Sync tasks to project management |
+| **Fallback:** Create issues via CLI | **Bash** `gh issue create ...` | When no GitHub MCP |
+| Render tasks template | **Bash** `npx morph-spec template render docs/tasks ...` | CLI command |
+| Update state with task count | **Bash** `npx morph-spec state set ... tasks.total N` | CLI command |
+
+**MCPs used:** Context7 (complexity estimation), GitHub (issue creation).
+
+**Anti-patterns:**
+- ❌ Task agent to break down a simple spec (do it directly, specs are already structured)
+- ✅ Task agent for complex specs with 50+ requirements (legitimate multi-step work)
+- ❌ Manually writing tasks.json without reading all outputs first
+
+---
+
+### Phase 5 — Implement
+
+**Goal:** Implement tasks, checkpoint every 3, create recap
+
+| Action | Tool | Why |
+|--------|------|-----|
+| Read task details | **Read** tasks.json, spec.md, contracts.cs | Implementation reference |
+| Create new files | **Write** new source files | New entities, services, pages |
+| Modify existing files | **Edit** existing source files | Add features to existing code |
+| Look up API during coding | **Context7 MCP** `query_docs()` | Accurate library usage |
+| Run database migrations | **Supabase MCP** `query()` | DDL statements directly |
+| **Fallback:** Run migrations | **Bash** `npx supabase migration ...` or `dotnet ef ...` | CLI tools |
+| Build project | **Bash** `dotnet build` or `npm run build` | Verify compilation |
+| Run tests | **Bash** `dotnet test` or `npm test` | Verify implementation |
+| Checkpoint validation | **Bash** `npx morph-spec checkpoint ...` | Every 3 tasks |
+| Create RLS policies | **Supabase MCP** `query()` | Security policies |
+| Create infrastructure | **Bash** `az bicep ...` or Bicep files via Write | IaC |
+| Create PR | **GitHub MCP** `create_pull_request()` or **Bash** `gh pr create` | Ship code |
+| Mark task done | **Bash** `npx morph-spec task done T001` | State tracking |
+| Smoke test feature no browser | **Playwright MCP** `browser_navigate()` + `browser_snapshot()` | Manual testing |
+| Verificar erros de console | **Playwright MCP** `browser_console_messages()` | Browser DevTools |
+| Screenshot para recap.md | **Playwright MCP** `browser_take_screenshot()` | Manual screenshot |
+| Multi-file refactoring | **Task** (subagent) | Complex parallel changes |
+| Update state | **Bash** `npx morph-spec state set ...` | CLI command |
+
+**MCPs used:** Supabase (migrations, RLS), Context7 (API lookup), GitHub (PRs), Playwright (smoke test, verification).
+
+**Anti-patterns:**
+- ❌ Task agent for a single file edit (use Edit directly)
+- ✅ Task agent for implementing a full service layer across 5+ files
+- ❌ Bash `cat` to create files (use Write tool)
+- ❌ Bash `sed` to modify code (use Edit tool)
+- ❌ Implementing without reading contracts.cs first (contracts are the source of truth)
+
+---
+
+## Tool Selection Rules
+
+### Claude Code Native Tools
+
+| Tool | When to Use | When NOT to Use |
+|------|-------------|-----------------|
+| **Read** | Read 1-3 specific known files | Don't use for searching |
+| **Glob** | Find files by name pattern | Don't use Bash `find` |
+| **Grep** | Search content across files | Don't use Bash `grep` or `rg` |
+| **Edit** | Modify existing files | Don't use Bash `sed` or `awk` |
+| **Write** | Create new files | Don't use Bash `echo >` or heredoc |
+| **Bash** | CLI commands, build, test, git | Don't use for file read/write/search |
+| **WebSearch** | Current external information | Don't use for local codebase info |
+| **WebFetch** | Specific URL content | Don't use for authenticated services |
+| **Task** (subagent) | Multi-file exploration, complex analysis | Don't use for single-file operations |
+
+### MCP Tools
+
+| MCP | When to Use | Fallback |
+|-----|-------------|----------|
+| **Supabase** | Schema analysis, migrations, RLS | Grep + Read code files |
+| **GitHub** | Issues, PRs, repo metadata, code search | Bash `gh` CLI |
+| **Figma** | Design tokens, component specs | Read CSS/SCSS files |
+| **Context7** | Library documentation lookups | WebSearch + WebFetch |
+| **Playwright** | Browser automation, screenshots, page inspection, smoke tests | WebFetch (read-only), Manual testing |
+| **Azure** | Cloud resource management | Bash `az` CLI |
+| **Docker** | Container management | Bash `docker` CLI |
+
+### The 3-Question Test
+
+Before choosing a tool, ask:
+
+1. **Is the data local or external?**
+   - Local → Read/Grep/Glob
+   - External structured → MCP
+   - External unstructured → WebSearch/WebFetch
+
+2. **Am I reading or writing?**
+   - Reading → Read/Grep/Glob/MCP
+   - Writing → Write/Edit/Bash (for CLI)
+
+3. **How many files are involved?**
+   - 1-3 files → Direct tools (Read, Edit, Write)
+   - 4+ files of known names → Parallel Read calls
+   - Unknown files needing exploration → Glob/Grep, then Read
+   - Complex multi-step analysis → Task subagent
+
+---
+
+## MCP Registry
+
+For the canonical list of MCPs, their tools, phase relevance, and fallbacks, see:
+
+**`framework/skills/level-0-meta/mcp-registry.json`**
+
+### Phase → MCP Quick Reference
+
+| Phase | Primary MCPs | Fallback |
+|-------|-------------|----------|
+| Proposal | Context7 | WebSearch |
+| Setup | GitHub | `gh` CLI |
+| UI/UX | Playwright, Figma, Context7 | WebFetch, Read CSS |
+| Design | Supabase, Context7, GitHub | Grep + Read code |
+| Clarify | Context7, GitHub | WebSearch |
+| Tasks | Context7, GitHub | WebSearch, `gh` CLI |
+| Implement | Supabase, Context7, Playwright, GitHub | CLI tools |
+
+### Detected Plugins & MCPs
+
+If `morph-spec init` was run with Claude Code environment detection, check `.morph/config/integrations.json` for the detected plugins and MCPs available in this project.
+
+---
+
+## Superpowers Integration
+
+When the `superpowers` plugin is installed, additional skills enhance each phase:
+
+| Phase | Superpowers Skill | Purpose |
+|-------|------------------|---------|
+| Setup | `using-git-worktrees` | Isolate feature work |
+| Design | `writing-plans`, `brainstorming` | Structure approach, explore alternatives |
+| Clarify | `systematic-debugging` | Investigate technical ambiguities |
+| Tasks | `writing-plans`, `executing-plans` | Plan and execute implementation |
+| Implement | `test-driven-development`, `systematic-debugging`, `requesting-code-review` | TDD, debug failures, review |
+
+See each phase skill for detailed integration instructions.
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/skills/level-0-meta/verification-before-completion/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: verification-before-completion
+description: Phase-specific verification checklists and morph-spec validation commands for confirming MORPH-SPEC outputs are complete and correct. Use before marking any task done, before advancing to the next phase, before committing, or before creating PRs.
+---
+
+# Verification Before Completion — MORPH-SPEC Integrated
+
+> Never claim work is complete without running verification. Evidence before assertions.
+>
+> **Script:** Run `node scripts/check-phase-outputs.mjs <feature> [phase]` to check required output files exist.
+
+## When to Use
+
+- Before marking any task as done (`morph-spec task done`)
+- Before advancing to the next phase
+- Before claiming a feature is complete
+- Before creating a PR or commit
+
+---
+
+## Phase-Specific Checklists
+
+### Phase 0 — Proposal
+
+- [ ] `proposal.md` exists in `.morph/features/{feature}/0-proposal/`
+- [ ] Proposal contains: Goal, Scope, Constraints, Success Criteria
+- [ ] `morph-spec state get {feature}` shows `phase: proposal`
+- [ ] `morph-spec state mark-output {feature} proposal` was called
+
+### Phase 1 — Setup
+
+- [ ] `morph-spec state get {feature}` shows `activeAgents` populated
+- [ ] Stack and architecture confirmed in context
+- [ ] State updated to `phase: setup`
+
+### Phase 1.5 — UI/UX (if applicable)
+
+- [ ] `ui-design-system.md` exists with color tokens, typography, spacing
+- [ ] `ui-mockups.md` exists with wireframes/ASCII mockups
+- [ ] `morph-spec validate-feature {feature} --phase uiux` passes
+
+### Phase 2 — Design
+
+- [ ] `spec.md` contains: Overview, Functional Requirements, Technical Architecture, Data Model
+- [ ] `contracts.cs` exists with DTOs matching `schema-analysis.md`
+- [ ] `decisions.md` contains at least 1 ADR
+- [ ] `morph-spec validate-feature {feature} --phase design` passes
+
+### Phase 3 — Clarify
+
+- [ ] All clarification questions answered by user
+- [ ] `spec.md` updated with Clarifications section
+- [ ] No unresolved ambiguities in spec
+
+### Phase 4 — Tasks
+
+- [ ] `tasks.md` or `tasks.json` exists
+- [ ] All tasks have: ID, title, description, dependencies
+- [ ] Checkpoints defined (every 3 tasks)
+- [ ] `morph-spec state set {feature} tasks.total N` called
+
+### Phase 5 — Implement
+
+- [ ] All tasks marked as completed
+- [ ] Build succeeds (`npm run build` or `dotnet build`)
+- [ ] Tests pass (`npm test` or `dotnet test`)
+- [ ] `recap.md` generated with implementation summary
+- [ ] `morph-spec validate-feature {feature}` passes all checks
+
+---
+
+## Verification Commands
+
+```bash
+# Run content-aware validation
+npx morph-spec validate-feature {feature-name}
+
+# Run with specific phase
+npx morph-spec validate-feature {feature-name} --phase design
+
+# Check feature status
+npx morph-spec status {feature-name} --verbose
+
+# Run full project validation
+npx morph-spec validate
+```
+
+---
+
+## Integration with Task Done
+
+Before running `morph-spec task done`:
+
+1. **Run the relevant test** for the task being completed
+2. **Run `morph-spec validate-feature`** if completing a checkpoint task
+3. **Read the task spec** and verify all acceptance criteria are met
+4. **Check for build errors** — run build command
+
+```bash
+# Verify before marking done
+npx morph-spec validate-feature {feature} --phase implement
+npx morph-spec task done {feature} T001
+```
+
+---
+
+## Integration with Checkpoints
+
+Every 3 tasks, run full checkpoint validation:
+
+```bash
+npx morph-spec checkpoint-save {feature}
+npx morph-spec validate-feature {feature}
+```
+
+If validation fails:
+1. **Do NOT mark the task as done**
+2. **Fix the issues** identified by validation
+3. **Re-run validation** until it passes
+4. **Then** mark the task as done
+
+---
+
+## Integration with Superpowers
+
+> Available when the `superpowers` plugin is installed.
+
+This skill replaces `superpowers:verification-before-completion` within morph-spec workflows. It adds:
+- Phase-specific checklists (not just generic verification)
+- `morph-spec validate-feature` integration
+- Checkpoint system integration
+- State tracking verification
+
+For verification **outside** morph-spec workflows, the original `superpowers:verification-before-completion` skill remains available.
+
+---
+
+## Anti-patterns
+
+- Never claim "tests pass" without actually running them
+- Never skip validation because "the change is small"
+- Never mark a task done if build is broken
+- Never advance phases without checking the phase checklist
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/skills/level-0-meta/verification-before-completion/scripts/check-phase-outputs.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * check-phase-outputs.mjs
+ *
+ * Verifies that required MORPH-SPEC output files exist for a feature/phase.
+ * Executed locally by Claude via Bash — output is returned to Claude.
+ *
+ * Usage:
+ *   node check-phase-outputs.mjs <feature> [phase]
+ *
+ * Examples:
+ *   node check-phase-outputs.mjs photo-processing design
+ *   node check-phase-outputs.mjs photo-processing        # checks all phases
+ *
+ * Output: JSON array of { phase, file, exists, required }
+ */
+
+import { existsSync } from 'fs';
+import { join } from 'path';
+
+const PHASE_OUTPUTS = {
+  proposal: [
+    { file: '0-proposal/proposal.md', required: true },
+  ],
+  design: [
+    { file: '1-design/spec.md', required: true },
+    { file: '1-design/contracts.cs', required: true },
+    { file: '1-design/decisions.md', required: true },
+    { file: '1-design/schema-analysis.md', required: false },
+  ],
+  uiux: [
+    { file: '2-ui/design-system.md', required: true },
+    { file: '2-ui/mockups.md', required: true },
+    { file: '2-ui/components.md', required: true },
+    { file: '2-ui/flows.md', required: false },
+  ],
+  tasks: [
+    { file: '3-tasks/tasks.md', required: true },
+  ],
+  implement: [
+    { file: '4-implement/recap.md', required: true },
+  ],
+};
+
+const feature = process.argv[2];
+const targetPhase = process.argv[3];
+
+if (!feature) {
+  console.error(JSON.stringify({ error: 'Usage: check-phase-outputs.mjs <feature> [phase]' }));
+  process.exit(1);
+}
+
+// Walk up to find .morph/ directory
+let cwd = process.cwd();
+let morphDir = null;
+for (let i = 0; i < 5; i++) {
+  const candidate = join(cwd, '.morph');
+  if (existsSync(candidate)) {
+    morphDir = candidate;
+    break;
+  }
+  const parent = join(cwd, '..');
+  if (parent === cwd) break;
+  cwd = parent;
+}
+
+if (!morphDir) {
+  console.error(JSON.stringify({ error: '.morph/ directory not found. Run from inside a MORPH-SPEC project.' }));
+  process.exit(1);
+}
+
+const featureDir = join(morphDir, 'features', feature);
+if (!existsSync(featureDir)) {
+  console.error(JSON.stringify({ error: `Feature directory not found: .morph/features/${feature}` }));
+  process.exit(1);
+}
+
+const phases = targetPhase
+  ? { [targetPhase]: PHASE_OUTPUTS[targetPhase] }
+  : PHASE_OUTPUTS;
+
+if (targetPhase && !PHASE_OUTPUTS[targetPhase]) {
+  console.error(JSON.stringify({ error: `Unknown phase: ${targetPhase}. Valid: ${Object.keys(PHASE_OUTPUTS).join(', ')}` }));
+  process.exit(1);
+}
+
+const results = [];
+let missingRequired = 0;
+
+for (const [phase, outputs] of Object.entries(phases)) {
+  for (const { file, required } of outputs) {
+    const fullPath = join(featureDir, file);
+    const exists = existsSync(fullPath);
+    if (required && !exists) missingRequired++;
+    results.push({ phase, file, exists, required });
+  }
+}
+
+const summary = {
+  feature,
+  featureDir: featureDir.replace(/\\/g, '/'),
+  checks: results.length,
+  passed: results.filter(r => r.exists).length,
+  missingRequired,
+  ready: missingRequired === 0,
+  results,
+};
+
+console.log(JSON.stringify(summary, null, 2));
+process.exit(missingRequired > 0 ? 1 : 0);