@polymorphism-tech/morph-spec 4.21.0 → 5.0.1

package/CLAUDE.md

@@ -1,10 +1,12 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file provides guidance to Claude Code when working with code in **this repository** (the morph-spec CLI source).
 
 ## 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.
+morph-spec is a spec-driven development harness CLI (`@polymorphism-tech/morph-spec` v5). In v5 the CLI is purely an **installer mechanism** — once installed, Claude Code itself executes the workflow autonomously based on `framework/MORPH.md` (the NLH charter) and the core skills.
+
+This repo is the **framework source code** — not a project that uses morph-spec.
 
 ## Build & Test Commands
 
@@ -13,14 +15,10 @@ morph-spec is a spec-driven development framework CLI (`@polymorphism-tech/morph
 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
+node --test test/lib/state-manager.test.js
 
 # Coverage
-npm run test:coverage          # text + html + lcov
-npm run test:coverage:summary  # text-summary only
+npm run test:coverage
 
 # Generate JSDoc API docs
 npm run docs
@@ -35,109 +33,97 @@ No build step — pure ESM JavaScript, runs directly via Node.js 18+.
 
 ### 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
+- **`bin/morph-spec.js`** — Commander.js CLI entry point. v5 surface: install/inspect commands only. No more task/phase/dispatch commands.
+- **`src/commands/`** — CLI command handlers organized by domain (project/, state/, validation/, scaffold/, mcp/, context/, dashboard/).
+- **`src/core/`** — Core domain logic:
+  - `state/state-manager.js` — Atomic state I/O with process-ID temp files
+  - `paths/output-schema.js` — **Single source of truth** for the 13 v5 output types
   - `templates/` — Handlebars template registry and renderer
-  - `workflows/` — Workflow type detector (standard vs nodejs-cli)
+  - `workflows/` — Workflow type detector
 - **`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)
+  - `validators/` — Data-driven validators (architecture, css, design-system, nextjs)
+  - `generators/` — Code generation (mandate, recap, context)
   - `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.)
+  - `installers/` — Agents, skills, hooks installers
+- **`src/utils/`** — Shared utilities (logger, banner, file-copier, claude-settings-manager, agents-installer, skills-installer, hooks-installer)
 - **`framework/`** — Metadata installed into target projects (READ-ONLY at runtime):
-  - `agents.json` (v4.0.0)
-  - `phases.json` (7 phases incl. sync)
-  - `standards/STANDARDS.json`
-  - `hooks/claude-code/` — Hook scripts (fail-open design)
-  - `skills/` — Morph skills (level-0-meta + level-1-workflows)
+  - `MORPH.md` — NLH charter (the single source of behavioral truth)
+  - `CLAUDE.md` — Runtime instructions injected into target's `.claude/CLAUDE.md`
+  - `agents.json` (v5.0.0) — 7 domain personas, no tiers
+  - `phases.json` — 5 phases (proposal, uiux, plan, implement, review)
+  - `standards/STANDARDS.json` — index of available standards
+  - `hooks/claude-code/core/` — 6 fail-open guardrail hooks
+  - `skills/core/` — 7 core NLH skills (single source of truth)
   - `templates/` — Handlebars templates for code generation
+  - `mcp/registry.json` — MCP server registry
+  - `evals/rubrics/` — 4 dimension rubrics for morph-eval
 
 ### 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 (sync).
+**NLH (Natural Language Harness):** Behavior lives in `framework/MORPH.md` — read once per session by Claude. JS hooks are silent guardrails only, never orchestrators.
 
-**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.
+**Output schema as single source of truth:** `src/core/paths/output-schema.js` defines all output types. Run `npm run generate` after modifying it.
 
-**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 check `stateExists()` first and return `{}` if state is missing/corrupt. Hooks never throw or write state.
 
-**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 `${path}.tmp.${pid}` then renames.
 
-**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']` in YAML frontmatter or `stack: ['dotnet']` in `agents.json`. `setup-infra.js` reads `config.json → project.stack`, splits into tags, and installs only matching assets.
 
-**Stack-aware filtering:** Assets declare `stacks: ['dotnet']` in YAML frontmatter. `setup-infra.js` reads `config.json → project.stack`, splits into tags, and installs only matching assets. `stacks: ['*']` = universal.
+**Personas, not tiers:** `agents.json` has 7 flat domain personas (dotnet-senior, ef-modeler, maf-expert, nextjs-expert, ui-designer, infra-engineer, evaluator). No tier system — Claude assumes the 3 NLH roles (Orchestrator/Specialist/Evaluator) per MORPH.md.
 
 ### Phase Sequence
 
 ```
-proposal → [uiux] → design → plan → tasks → implement → [sync]
+proposal → [uiux] → plan → implement → review
 ```
 
-Phases in brackets are optional. Approval gates exist at: proposal, design, plan, tasks, uiux.
+Approval gates: Gate 1 (proposal), Gate 2 (plan), Gate 3 (review). `uiux` is optional.
 
 ### 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.
+State lives in `.morph/state.json`. Phase derived from filesystem (not stored). State tracks: features (status, taskList, approvalGates, outputs), metadata, 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
+- **Temp dirs:** `createTempDir()` / `cleanupTempDir()` from `test/helpers/test-utils.js`
+- **Mock state:** `createMockState(overrides)` and `createStateFile(tempDir, state)` from test-utils
 
 ## 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.
+- **ESM only** — `import`/`export`, package.json `"type": "module"`
+- **Output type normalization** — `normalizeOutputType()` auto-converts kebab-case to camelCase
+- **Template helpers** — Handlebars v2.0: pascalCase, camelCase, snakeCase, kebabCase, pluralize, plus comparison/logic helpers
+- **CLI structure** — Commands are thin wrappers; business logic in `src/core/` or `src/lib/`
 
 ## Framework Development Guardrails
 
-When modifying framework components, always verify the full scope of related files. A PostToolUse hook (`.claude/hooks/post-tool-use/framework-consistency-guard.js`) will remind you, but you should also proactively check.
+When modifying framework components, verify the full scope of related files.
 
 ### Dependency Matrix
 
-| When you modify... | Also verify... |
-|---------------------|----------------|
-| `framework/agents.json` | squad-templates/*.json, agents-installer.js (tier defaults), advance-phase.js (hardcoded agent lists), doctor.js (REQUIRED_AGENTS), agents-manager.js (validation rules), total_agents/tier counts |
-| `framework/standards/**` | STANDARDS.json (entry exists), agents.json (agents reference the standard), .md file exists at declared path |
-| `framework/hooks/claude-code/**` | hooks-installer.js (MORPH_HOOKS array + MORPH_PERMISSIONS), hook follows fail-open pattern |
-| `framework/skills/**` | phases.json (requiredSkills if phase-bound), skills-installer.js, SKILL.md frontmatter |
-| `framework/phases.json` | advance-phase.js, dispatch-agents.js, output-schema.js (phase mappings) |
-| `framework/templates/**` | REGISTRY.json (template registered) |
-| `src/core/paths/output-schema.js` | Run `npm run generate` to update phase-utils.js and skill markdown blocks |
-
-### Per-Domain Checklists
-
-**Agents** — required fields: tier, title, group, active_phases, reports_to, domains, keywords, validators, standards. If tier 3+: teammate.spawn_prompt. If stack-specific: stacks[]. Update total_agents/tier counts.
-
-**Standards** — STANDARDS.json entry needs: id, name, path, category, subcategory, tags, digest. At least one agent must reference it. If stack-specific: stacks[].
-
-**Hooks** — must be in MORPH_HOOKS array in hooks-installer.js. Must follow fail-open pattern. If needs permissions: add to MORPH_PERMISSIONS.
-
-**Skills** — SKILL.md with valid frontmatter. If phase-bound: in phases.json requiredSkills. If stack-specific: stacks[] frontmatter.
-
-**Phases** — index/folder consistent. requiredSkills reference existing dirs. advance-phase.js handles transitions.
-
-**Templates** — registered in REGISTRY.json. Uses only available Handlebars helpers.
-
-**Output Schema** — always run `npm run generate` after changes.
+| When you modify...              | Also verify...                                                                            |
+|----------------------------------|-------------------------------------------------------------------------------------------|
+| `framework/agents.json`          | agents-installer.js (test/utils/agents-installer.test.js), doctor.js (REQUIRED_AGENTS)    |
+| `framework/standards/**`         | STANDARDS.json entry exists, agents reference standard, .md file exists                   |
+| `framework/hooks/claude-code/**` | hooks-installer.js MORPH_HOOKS array, hook follows fail-open pattern                      |
+| `framework/skills/core/**`       | MORPH.md skills table, skills-installer.js, SKILL.md frontmatter                          |
+| `framework/phases.json`          | output-schema.js (phase mappings), test/framework/phases.test.js                          |
+| `framework/templates/**`         | REGISTRY.json (template registered), valid Handlebars helpers                             |
+| `src/core/paths/output-schema.js`| Run `npm run generate` to update phase-utils.js                                           |
+| `framework/MORPH.md`             | All core skills (cross-references), CLAUDE.md (slash command list)                        |
 
 ### Test Coverage
 
-Every `src/**/*.js` file should have a corresponding `test/**/*.test.js`. The consistency hook will warn when a test file is missing.
+Every `src/**/*.js` file should have a corresponding `test/**/*.test.js`.
 
 ## Framework vs Runtime Distinction
 
-- **This repo** (`morph-spec-framework/`) = the CLI tool source code
+- **This repo** = the CLI source (installer)
 - **`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
+- **`framework/CLAUDE.md`** = injected into target's `.claude/CLAUDE.md` (not for this repo)
+- **`framework/MORPH.md`** = the NLH charter — every behavioral change lands here, not in JS hooks
+
+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.21.0  
+**Version:** 4.22.1  
 **Requires:** Node.js 18+, Claude Code
 
 ---
@@ -364,4 +364,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v4.21.0 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v4.22.1 by [Polymorphism Tech](https://polymorphism.tech)*