@polymorphism-tech/morph-spec 4.11.0 → 4.12.0

package/CLAUDE.md

@@ -1,3 +1,107 @@
-# Project
+# CLAUDE.md
 
-@.claude/CLAUDE.md
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Is
+
+morph-spec is a spec-driven development framework CLI (`@polymorphism-tech/morph-spec`). It orchestrates AI-first feature development through structured phases with approval gates. This repo is the **framework source code** — not a project that uses morph-spec.
+
+## Build & Test Commands
+
+```bash
+# Run all tests (sequential — required due to process.chdir state)
+npm test
+
+# Run a single test file
+node --test test/commands/task-done.test.js
+
+# Run tests matching a name pattern
+node --test --test-name-pattern="should advance phase" test/commands/advance-phase.test.js
+
+# Coverage
+npm run test:coverage          # text + html + lcov
+npm run test:coverage:summary  # text-summary only
+
+# Generate JSDoc API docs
+npm run docs
+
+# Regenerate derived reference files from output-schema.js
+npm run generate
+```
+
+No build step — pure ESM JavaScript, runs directly via Node.js 18+.
+
+## Architecture
+
+### Module Layout
+
+- **`bin/morph-spec.js`** — Commander.js CLI entry point. All commands registered here.
+- **`src/commands/`** — CLI command handlers organized by domain (state/, tasks/, agents/, validation/, trust/, etc.)
+- **`src/core/`** — Core domain logic (not CLI-coupled):
+  - `state/state-manager.js` — Atomic state I/O with process-ID temp files to prevent race conditions
+  - `paths/output-schema.js` — **Single source of truth** for all 15 output types, their filenames, phase directories, and gate associations
+  - `templates/` — Handlebars template registry and renderer
+  - `workflows/` — Workflow type detector (standard vs nodejs-cli)
+- **`src/lib/`** — Libraries and subsystems:
+  - `validators/` — 25+ data-driven validators (architecture, blazor, css, design-system, nextjs, etc.)
+  - `generators/` — Code generation (design-system, context, recap, metadata)
+  - `trust/trust-manager.js` — 3-level trust model (manual/high/auto)
+  - `stack-filter.js` — Stack-aware asset filtering via YAML frontmatter `stacks:` tags
+  - `hooks/` — Hook executor
+  - `installers/` — Agents, skills, hooks installers for target projects
+- **`src/utils/`** — Shared utilities (logger, banner, file-copier, claude-settings-manager, etc.)
+- **`framework/`** — Metadata installed into target projects (READ-ONLY at runtime):
+  - `agents.json` (v4.0.0, 46 agents in 4 tiers)
+  - `phases.json` (8 phases + sync)
+  - `standards/STANDARDS.json` (86 entries)
+  - `hooks/claude-code/` — Hook scripts (10 hooks, fail-open design)
+  - `skills/` — Morph skills (level-0-meta + level-1-workflows)
+  - `templates/` — Handlebars templates for code generation
+
+### Key Architectural Patterns
+
+**Dual-layer phase tracking:** Phase is derived from filesystem (`derivePhase()` scans for highest-numbered phase folder) — state.json only overrides for lightweight phases (setup, clarify, sync).
+
+**Output schema as single source of truth:** `src/core/paths/output-schema.js` defines all output types. Run `npm run generate` after modifying it to update derived reference files.
+
+**Data-driven validation:** `agents.json` lists validators per agent. The validation runner reads active agents from state and orchestrates only relevant validators.
+
+**Fail-open hooks:** All hooks in `framework/hooks/claude-code/` check `stateExists()` first and return `{}` (empty/pass-through) if state is missing or corrupt. Hooks never throw or write state.
+
+**Atomic state writes:** `state-manager.js` writes to a process-ID temp file then renames, preventing corruption from concurrent CLI invocations.
+
+**Stack-aware filtering:** Assets declare `stacks: ['dotnet', 'blazor']` in YAML frontmatter. `setup-infra.js` reads `config.json → project.stack`, splits into tags, and installs only matching assets. `stacks: ['*']` = universal.
+
+### Phase Sequence
+
+```
+proposal → setup → [uiux] → design → clarify → plan → tasks → implement → [sync]
+```
+
+Phases in brackets are optional. Approval gates exist at: proposal, design, plan, tasks, uiux.
+
+### State Schema (v5.0.0)
+
+State lives in `.morph/state.json` in target projects. Phase and outputs are **derived from filesystem**, not stored in state. State tracks: features (status, activeAgents, taskList, trustConfig, metadata), project info, and version.
+
+## Testing Conventions
+
+- **Framework:** Node.js native `node:test` — no Jest or Mocha
+- **Concurrency:** Always sequential (`--test-concurrency=1`) — tests use `process.chdir()`
+- **Temp dirs:** Use `createTempDir()` / `cleanupTempDir()` from `test/helpers/test-utils.js` — creates dirs with `morph-test-` prefix
+- **Mock state:** Use `createMockState(overrides)` and `createStateFile(tempDir, state)` from test-utils
+- **Pattern:** Each test creates a temp dir, chdir into it, sets up mock state/filesystem, runs the function, asserts, then restores cwd and cleans up in afterEach
+
+## Code Conventions
+
+- **ESM only** — all files use `import`/`export`, package.json has `"type": "module"`
+- **Output type normalization** — `normalizeOutputType()` auto-converts kebab-case to camelCase via regex
+- **Template helpers** — Handlebars v2.0 helpers: pascalCase, camelCase, snakeCase, kebabCase, pluralize, plus comparison/logic helpers
+- **CLI structure** — Commands are thin wrappers that delegate to `src/core/` or `src/lib/` modules. Keep business logic out of command files.
+
+## Framework vs Runtime Distinction
+
+- **This repo** (`morph-spec-framework/`) = the CLI tool source code
+- **`framework/`** = files installed into target projects via `morph-spec init`
+- **`framework/CLAUDE.md`** = the CLAUDE.md injected into target projects (not for this repo)
+- When editing `framework/` files, you're changing what gets installed in user projects, not runtime behavior of the CLI itself

package/README.md

@@ -3,7 +3,7 @@
 > Spec-driven development framework for multi-stack projects. Turns feature requests into implementation-ready code through structured, AI-orchestrated phases.
 
 **Package:** `@polymorphism-tech/morph-spec`
-**Version:** 4.11.0  
+**Version:** 4.12.0  
 **Requires:** Node.js 18+, Claude Code
 
 ---
@@ -370,4 +370,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v4.11.0 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v4.12.0 by [Polymorphism Tech](https://polymorphism.tech)*

package/bin/morph-spec.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 import { program } from 'commander';
 import chalk from 'chalk';
@@ -38,7 +38,7 @@ import {
 } from '../src/commands/agents/manage-agents.js';
 
 // Task commands
-import { taskDoneCommand, taskStartCommand, taskNextCommand } from '../src/commands/tasks/task.js';
+import { taskDoneCommand, taskStartCommand, taskNextCommand, taskBulkStartCommand, taskBulkDoneCommand, taskAnnotateCommand } from '../src/commands/tasks/task.js';
 
 // Scope escalation commands
 import { scopeEscalateCommand } from '../src/commands/scope/escalate.js';
@@ -153,7 +153,9 @@ const taskCommand = program
 taskCommand
   .command('done <feature> <task-ids...>')
   .description('Mark tasks as completed (runs validation first)')
-  .option('--skip-validation', 'Skip code validation (not recommended)')
+  .option('--note <text>', 'Add a deviation note explaining why task was done differently than planned')
+  .option('--skip-validation', 'Skip code validation (budget-limited, requires --reason)')
+  .option('--reason <text>', 'Reason for skipping validation (required with --skip-validation)')
   .option('--dry-run', 'Show validation results without marking tasks as complete')
   .action((feature, taskIds, options) => taskDoneCommand(feature, taskIds, options));
 
@@ -173,6 +175,32 @@ taskCommand
   .option('--into <subtasks...>', 'Sub-task definitions ("T017a: Title")')
   .action((feature, taskId, options) => taskExpandCommand(feature, taskId, options));
 
+taskCommand
+  .command('bulk-start <feature> [range]')
+  .description('Start multiple tasks at once (mark as in_progress)')
+  .option('--all', 'Start all pending tasks with met dependencies')
+  .option('--from <id>', 'Start of task range (e.g. T007)')
+  .option('--to <id>', 'End of task range (e.g. T014)')
+  .action((feature, range, options) => taskBulkStartCommand(feature, range, options));
+
+taskCommand
+  .command('bulk-done <feature> [range]')
+  .description('Complete multiple tasks with a single validation pass')
+  .option('--all', 'Complete all non-completed tasks')
+  .option('--from <id>', 'Start of task range (e.g. T007)')
+  .option('--to <id>', 'End of task range (e.g. T014)')
+  .option('--note <text>', 'Add a deviation note explaining why tasks were done differently than planned')
+  .option('--skip-validation', 'Skip code validation (budget-limited, requires --reason)')
+  .option('--reason <text>', 'Reason for skipping validation (required with --skip-validation)')
+  .option('--dry-run', 'Show validation results without marking tasks as complete')
+  .action((feature, range, options) => taskBulkDoneCommand(feature, range, options));
+
+taskCommand
+  .command('annotate <feature> <task-id> <text>')
+  .description('Add a note to a task (deviation, context, or blocker resolution)')
+  .option('--type <type>', 'Note type: deviation | context | blocker-resolved', 'deviation')
+  .action((feature, taskId, text, options) => taskAnnotateCommand(feature, taskId, text, options));
+
 // Generation commands
 const generateCommand = program
   .command('generate')