@polymorphism-tech/morph-spec 8.2.1 → 8.3.0

package/README.md

@@ -3,14 +3,14 @@
 > 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:** 8.2.1  
+**Version:** 8.3.0  
 **Requires:** Node.js 22+, Claude Code
 
 ---
 
 ## What it does
 
-morph-spec enforces a spec-first development workflow. When you ask for a feature, it does not write code immediately. It runs through structured phases (proposal, design, tasks) with approval gates before a single line of implementation is generated. Each phase produces traceable output files. Every decision is documented.
+morph-spec enforces a spec-first development workflow. When you ask for a feature, it does not write code immediately. It runs through structured phases (proposal, plan, implement) with approval gates before a single line of implementation is generated. Each phase produces traceable output files. Every decision is documented.
 
 It integrates natively with Claude Code: skills become slash commands, agents become native subagents, hooks inject state context automatically, and rules enforce standards based on file paths.
 
@@ -61,7 +61,7 @@ your-project/
 │   ├── config/
 │   │   └── config.json              # Project configuration
 │   ├── framework/
-│   │   ├── agents.json              # 22 agents in 4 tiers (READ-ONLY)
+│   │   ├── agents.json              # 8 domain personas (READ-ONLY)
 │   │   ├── standards/               # Coding and architecture standards (READ-ONLY)
 │   │   └── templates/               # Code and IaC templates (READ-ONLY)
 │   ├── context/                     # Project context (README.md, standards.md)
@@ -76,9 +76,9 @@ your-project/
 └── .claude/
     ├── commands/                    # Slash commands
     ├── skills/                      # Framework skills (flat .md files)
-    ├── agents/                      # Native subagents (22 agents)
-    ├── rules/                       # Path-scoped standards rules
-    └── settings.local.json          # Hooks configuration (10 hooks)
+    ├── agents/                      # Native subagents (one morph-{id}.md per persona)
+    ├── rules/                       # Stack-aware, path-scoped standards rules
+    └── settings.local.json          # Hooks configuration
 ```
 
 ---
@@ -88,10 +88,10 @@ your-project/
 Features move through structured phases. Some are optional depending on feature type.
 
 ```
-proposal → [design] → plan → implement → review
+proposal → [uiux] → plan → implement → review
 ```
 
-`design` is optional — applies only to UI-heavy features.
+`uiux` is optional — applies only to UI-heavy features.
 
 ### Phase outputs
 
@@ -134,13 +134,15 @@ Independent features can also be developed **in parallel, each isolated in its o
 These commands are available inside Claude Code after init.
 
 
-| Command                     | Description                                               |
-| --------------------------- | --------------------------------------------------------- |
-| `/morph-proposal {feature}` | Full spec pipeline (phases 0-4, pauses at approval gates) |
-| `/morph-apply {feature}`    | Implement approved feature (phase 5)                      |
-| `/morph-hotfix {feature}`   | Surgical hotfix ADW — scout → fix → human Gate 3 → ship    |
-| `/morph-status`             | Feature status dashboard                                  |
-| `/morph-preflight`          | Pre-implementation validation                             |
+| Command                       | Description                                             |
+| ------------------------------ | ---------------------------------------------------------- |
+| `/morph-proposal {feature}`    | Business understanding + plan (Gates 1 and 2)                |
+| `/morph-apply {feature}`       | Autonomous execution + review (Gate 3)                        |
+| `/morph-hotfix {feature}`      | Surgical hotfix ADW — scout → fix → human Gate 3 → ship         |
+| `/morph-status [feature]`      | Status of the active (or specified) feature                      |
+| `/morph-archive {feature}`     | Archive a completed feature (after Gate 3)                          |
+| `/morph-preflight`             | Pre-deploy validation (specs, contracts, tests, infra)                |
+| `/morph-troubleshoot [error]`  | Root-cause diagnosis for .NET/Next.js errors                            |
 
 
 ---
@@ -160,15 +162,16 @@ morph-spec doctor --full               # Full health check (all file verificatio
 ### Feature workflow
 
 ```bash
-morph-spec state list                  # List all features and their states
-morph-spec state get {feature}         # Get feature state
-morph-spec state set {feature} {key} {value}
-morph-spec phase advance {feature}     # Advance to next phase
-morph-spec task done {feature}         # Mark current task complete
-morph-spec task start {feature}        # Start next task
-morph-spec status {feature}            # Feature status dashboard
+morph-spec fleet                              # Every active feature (root + worktrees): phase, gates, activity
+morph-spec status {feature}                    # Feature status dashboard
+morph-spec approve {feature} {gate}            # Approve a phase gate (proposal, plan, review)
+morph-spec advance {feature}                   # Approve the current gate and scaffold the next phase folder
+morph-spec approval-status {feature}           # Show approval status for all gates
+morph-spec archive {feature}                   # Archive a completed feature (after Gate 3)
 ```
 
+Task progress within a feature is tracked with the native `TaskCreate`/`TaskUpdate` tools, persisted to `tasks.json` — there is no separate CLI command for starting or completing a task.
+
 ### Validation
 
 ```bash
@@ -199,92 +202,59 @@ morph-spec worktree list [--json]        # List active feature worktrees with ph
 
 ---
 
-## Agent hierarchy
-
-morph-spec includes 22 agents organized in 4 tiers (2+3+13+4). Tier 1-2 agents are installed as native Claude Code subagents in `.claude/agents/`. Tier 3 domain agents are installed as `.claude/agents/morph-domain-{name}.md`.
-
-### Tier 1 — Orchestrators (2)
-
-
-| Agent                 | Role                                                   | Active    |
-| --------------------- | ------------------------------------------------------ | --------- |
-| `standards-architect` | Chief Architect — enforces standards across all phases | Always    |
-| `ai-system-architect` | AI/Agent system design and orchestration               | On-demand |
-
-
-### Tier 2 — Domain Leaders (3)
-
-
-| Agent              | Squad                     | Active    |
-| ------------------ | ------------------------- | --------- |
-| `dotnet-senior`    | Backend squad lead        | Always    |
-| `nextjs-expert`    | Frontend squad lead       | Always    |
-| `infra-architect`  | Infrastructure squad lead | Always    |
+## Agent model
 
+morph-spec dispatches 8 flat domain personas — no tiers, no hierarchy — defined in `.morph/framework/agents.json` (single source of truth) and installed identically to `.claude/agents/morph-{id}.md`. Claude picks the right persona per task from the domains/keywords in `agents.json`, then dispatches it via the `Agent` tool.
 
-### Tier 3 — Specialists (13)
-
-Organized into squads:
-
-**Backend (6):** ef-modeler, hangfire-orchestrator, ms-agent-expert, supabase-expert, vector-search-expert, morph-spec-architect
-
-**Frontend (3):** css-specialist, ui-designer, seo-growth-hacker
-
-**Integrations (3):** asaas-financial, clerk-auth, resend-email
-
-**Security (1):** security-expert
-
-### Tier 4 — Validators (4)
-
-
-| Agent                          | Validates                               |
-| ------------------------------ | --------------------------------------- |
-| `architecture-expert`          | Architectural decisions and constraints |
-| `packages-validator`           | Package versions and compatibility      |
-| `design-system-validator`      | Design system adherence                 |
-| `nextjs-component-validator`   | Next.js component structure and naming  |
+| Persona          | Domain                                | Model  |
+| ---------------- | -------------------------------------- | ------ |
+| `dotnet-senior`   | Backend (.NET, VSA)                    | sonnet |
+| `ef-modeler`      | EF Core / Postgres modeling            | sonnet |
+| `maf-expert`      | Microsoft Agent Framework               | sonnet |
+| `nextjs-expert`   | Frontend (Next.js/React)                | sonnet |
+| `ui-designer`     | UI/UX, design systems                    | sonnet |
+| `infra-engineer`  | Jobs, deployment, observability          | sonnet |
+| `evaluator`       | Independent code/architecture review (Gate 3) | opus |
+| `scout`           | Read-only codebase diagnosis             | haiku  |
 
+`morph-spec doctor` detects drift between `agents.json` and the generated `.claude/agents/morph-*.md` files — never hand-edit the generated files.
 
 ---
 
 ## Hooks
 
-10 Claude Code hooks are installed into `.claude/settings.local.json` across 8 event types:
+Guardrail hooks are installed into `.claude/settings.local.json` across 7 event bindings. All are **fail-open** — they check that state exists first and silently no-op on missing/corrupt state; they never throw, write state, or orchestrate.
 
 
-| Event                | Hook                       | Purpose                                                           |
-| -------------------- | -------------------------- | ----------------------------------------------------------------- |
-| `SessionStart`       | `inject-morph-context.js`  | Injects active feature spec into context (configurable char max)  |
-| `UserPromptSubmit`   | `enrich-prompt.js`         | Context-aware prompt enrichment, wrong-phase warnings             |
-| `PreToolUse`         | Bash guard (prompt type)   | Detects destructive patterns inline via Claude's reasoning        |
-| `PreToolUse`         | `protect-spec-files.js`    | Blocks edits to spec files after approval gate                    |
-| `PreToolUse`         | `enforce-phase-writes.js`  | Ensures writes go to the correct phase directory                  |
-| `PostToolUse`        | `dispatch.js`              | Triggers auto-checkpoints on task completion                      |
-| `PostToolUseFailure` | `handle-tool-failure.js`   | Logs failures to `.morph/logs/tool-failures.log`                  |
-| `Stop`               | `validate-completion.js`   | Warns about incomplete tasks/missing outputs/pending gates        |
-| `PreCompact`         | `save-morph-context.js`    | Snapshots state to `.morph/memory/` before compaction             |
+| Event                      | Hook(s)                                                              | Purpose                                                                     |
+| --------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `SessionStart`              | `worktree-context.js`                                                   | Injects feature identity (worktree) or active-feature summary (root)           |
+| `PreToolUse` (Write\|Edit)  | `protect-spec-files.js`, `enforce-phase-writes.js`                       | Blocks edits to the frozen plan contract post-Gate-2; enforces phase folders    |
+| `PreToolUse` (Bash)         | `pre-bash-denylist.js`                                                   | Detects destructive shell patterns                                              |
+| `PostToolUse`               | `post-edit-typecheck.js`, `tasks-json-guard.js`, `trace-autogen.js`       | Stack-aware typecheck; guards `tasks.json` plan-contract edits; auto-generates execution traces |
+| `PostToolUse`               | `state-sync.js`, `gate-guard.js`, `loop-detect.js`                        | Syncs feature state; enforces gate ordering; detects repeated-action loops       |
+| `Stop`                      | `validate-completion.js`                                                  | Warns about incomplete tasks, missing outputs, or pending approval gates         |
 
 
 Protected files (via `permissions.deny`):
 
-- `.morph/state.json` — never edited directly, CLI only
-- `.morph/framework/`** — read-only framework content
+- `.morph/state.json` — never edited directly, derived from `feature.json` files
+- `.morph/framework/` — read-only framework content
 
 ---
 
 ## Rules
 
-Path-scoped rules are installed to `.claude/rules/` and activate automatically based on file patterns:
-
+Rules are installed to `.claude/rules/` based on your detected stack (`stacks:` frontmatter, same tagging mechanism as agents and templates) and activate automatically based on file path patterns (`paths:` frontmatter). A subset of the current set:
 
-| Rule file                     | Applies to                                               |
-| ----------------------------- | -------------------------------------------------------- |
-| `morph-workflow.md`           | Always active — spec-first mandate, phase commands       |
-| `csharp-standards.md`         | `**/*.cs`, `**/*.csproj`                                 |
-| `frontend-standards.md`       | `**/*.razor`, `**/*.css`, `**/*.scss`                    |
-| `nextjs-standards.md`         | `**/*.tsx`, `**/*.ts`                                    |
-| `testing-standards.md`        | `tests/`**, `**/*.test.*`, `**/*.spec.*`, `**/*Tests.cs` |
-| `infrastructure-standards.md` | `**/*.bicep`, `**/Dockerfile`, `**/pipelines/**`         |
+| Rule file                     | Applies to                                     | Stack     |
+| ----------------------------- | ------------------------------------------------- | --------- |
+| `morph-workflow.md`           | Always active — spec-first mandate                 | any       |
+| `csharp-standards.md`         | `**/*.cs`, `**/*.csproj`                            | dotnet    |
+| `frontend-standards.md`       | `**/*.tsx`, `**/*.css`, `**/*.scss`                 | nextjs    |
+| `nextjs-standards.md`         | Next.js-specific patterns                           | nextjs    |
+| `ai-agents-standards.md`      | `**/Agents/**`, `**/*Agent*.cs`                     | dotnet    |
+| `infrastructure-standards.md` | `**/Dockerfile*`, `**/docker-compose*`, `**/.github/**` | docker |
 
 
 ---
@@ -292,11 +262,12 @@ Path-scoped rules are installed to `.claude/rules/` and activate automatically b
 ## Stack support
 
 
-| Technology                                  | Support                                          |
-| ------------------------------------------- | ------------------------------------------------ |
-| .NET 10 / ASP.NET Core                      | Full — C# contracts, EF Core, CQRS, Minimal API  |
-| Next.js / React / TypeScript                | Full — components, routing, state management     |
-| Supabase                                    | Supported via CLI (local Docker)                 |
+| Technology                                  | Support                                                    |
+| ------------------------------------------- | ------------------------------------------------------------- |
+| .NET 10 / ASP.NET Core                      | Full — VSA with direct handlers, result pattern, Minimal API   |
+| EF Core / Neon (Postgres)                   | Full — migrations, Neon Auth (Better Auth)                     |
+| Next.js / React / TypeScript                | Full — components, routing, state management                  |
+| Microsoft Agent Framework (MAF)             | Full — single-agent + structured output + tools + RAG          |
 
 
 TypeScript strict mode is enforced by default. See `.morph/framework/standards/` for all coding standards.
@@ -323,12 +294,12 @@ After updating, run `morph-spec doctor` to confirm the installation is healthy.
 
 **Never edit protected files directly:**
 
-- `.morph/state.json` — use `morph-spec state set`
-- `.morph/framework/`** — read-only, updated by `morph-spec update`
+- `.morph/state.json` — derived automatically from `feature.json`; use `morph-spec approve`/`advance`/`score`/`gate-decision` to change feature state
+- `.morph/framework/` — read-only, updated by `morph-spec update`
 
-**Always document decisions.** Each feature has a `2-design/decisions.md`. Architectural choices go there, not in commit messages.
+**Always document decisions.** Each feature can have a `2-plan/decisions.md`. Architectural choices go there, not in commit messages.
 
-**Checkpoints every 3 tasks.** The framework auto-validates architecture compliance, package versions, and security after every third completed task.
+**Validators run after every task.** `morph-spec verify` runs the build + test + validator chain relevant to your stack; `morph-eval` scores the result — a score below 9 triggers an autonomous correction loop rather than a pause.
 
 ---
 
@@ -382,7 +353,7 @@ Ensure `.claude/settings.local.json` is not gitignored in your project. The file
 
 ## Standards
 
-The framework ships 82 registered standards across 11 categories, stored in `.morph/framework/standards/STANDARDS.json`. Standards are enforced via path-scoped rules installed to `.claude/rules/` during `morph-spec init`.
+The framework ships 60 registered standards across 7 categories (`ai-agents`, `architecture`, `backend`, `data`, `frontend`, `infrastructure`, `integration`), stored in `.morph/framework/standards/STANDARDS.json`. Standards are looked up on demand (by keyword/alias) rather than preloaded wholesale into context, and enforced via stack-aware, path-scoped rules installed to `.claude/rules/` during `morph-spec init`.
 
 ---
 
@@ -394,4 +365,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v8.2.1 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v8.3.0 by [Polymorphism Tech](https://polymorphism.tech)*

package/bin/morph-spec.js

@@ -56,6 +56,9 @@ import { contextRefreshCommand } from '../src/commands/context/context-refresh.j
 // === Dashboard ===
 import { dashboardCommand } from '../src/commands/dashboard/dashboard.js';
 
+// === Observability ===
+import { telemetryCommand } from '../src/commands/observability/telemetry.js';
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
 
@@ -344,4 +347,13 @@ program
   .option('--no-open', 'Don\'t auto-open browser')
   .action(dashboardCommand);
 
+// ─── Observability ────────────────────────────────────────────────────────
+program
+  .command('telemetry')
+  .description('Summarize the harness execution path from .morph/logs/events.jsonl (skills, personas, standards read, tool mix, prompts)')
+  .option('--json', 'Output the aggregate as JSON')
+  .option('--feature <name>', 'Narrow the summary to a single feature')
+  .option('--limit <n>', 'How many recent prompts to show (default 10)', (v) => parseInt(v, 10))
+  .action((options) => telemetryCommand(options));
+
 program.parse();

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "8.2.1",
+  "version": "8.3.0",
   "displayName": "MORPH-SPEC Framework",
   "description": "Spec-driven development with 38 agents and 8-phase workflow for .NET/Blazor/Next.js/Azure",
   "publisher": "polymorphism-tech",

package/docs/CHEATSHEET.md

@@ -5,10 +5,12 @@
 ```bash
 npm install -g @polymorphism-tech/morph-spec@latest --prefer-online   # install/upgrade globally
 morph-spec init                                 # initialize project
-morph-spec init --wizard                        # interactive wizard
-morph-spec init --force                         # overwrite existing
-morph-spec update                               # sync framework files
-morph-spec doctor                               # health check
+morph-spec init --force                         # overwrite existing install
+morph-spec init --skip-mcp                      # skip interactive MCP setup
+morph-spec setup-infra                          # headless install, no prompts (used by init internally)
+morph-spec setup-infra --reinstall              # re-install only stack-aware assets (rules/skills/agents)
+morph-spec update                               # sync framework templates/standards to the installed version
+morph-spec doctor                               # health check (agents/rules drift, hook config, etc.)
 morph-spec --version
 ```
 
@@ -21,162 +23,113 @@ morph-spec --version
 ## Phase workflow
 
 ```
-proposal → [uiux] → design → plan → tasks → implement → [sync]
+proposal → [uiux] → plan → implement → review
 ```
 
-Phases in brackets are optional.
+`uiux` is optional. Which of the 5 phases actually run for a given feature is also shaped by its **work type** (see below) — a `chore` skips straight to implement, a `hotfix` runs a different pipeline entirely.
 
-| Phase | Directory | Output files | Gate |
-|-------|-----------|--------------|------|
-| proposal | `0-proposal/` | `proposal.md` | ✅ Approval |
-| uiux *(optional)* | `1-design/` | `design-system.md`, `mockups.md`, `components.md`, `flows.md` | ✅ Approval |
-| design | `2-design/` | `spec.md`, `contracts.cs`, `decisions.md` | ✅ Approval |
-| plan | `3-plan/` | `plan.md` | ✅ Approval |
-| tasks | `4-tasks/` | `tasks.md` | ✅ Approval |
-| implement | `3-implement/` | code + `recap.md` | — |
-| sync *(optional)* | — | standards updated | — |
+| Phase | Folder | Gate |
+|-------|--------|------|
+| proposal | `0-proposal/` | ✅ Gate 1 |
+| uiux *(optional)* | `1-design/` | ✅ |
+| plan | `2-plan/` | ✅ Gate 2 |
+| implement | `3-implement/` | — (auto-advance between tasks) |
+| review | `4-review/` | ✅ Gate 3 |
 
 ---
 
 ## Slash commands (Claude Code)
 
-| Command | Description |
-|---------|-------------|
-| `/morph-proposal {feature}` | Full spec pipeline — phases 0–4 with approval gates |
-| `/morph-apply {feature}` | Implement approved feature — phase 5 |
-| `/morph-hotfix {feature}` | Surgical hotfix ADW — scout → fix → human Gate 3 → ship |
-| `/morph-status` | Project-wide feature status dashboard |
-| `/morph-preflight` | Pre-implementation validation (7 checks) |
+| Command | Purpose |
+|---------|---------|
+| `/morph-proposal {feature}` | Business understanding + plan (Gates 1 and 2). Step 0 routes by work type (`feature`/`bug`/`chore`/`hotfix`) |
+| `/morph-hotfix {feature}` | Surgical hotfix ADW (scout → fix → human gate → ship) |
+| `/morph-apply {feature}` | Autonomous execution + review (Gate 3) |
+| `/morph-status [feature]` | Status of the active (or specified) feature |
+| `/morph-archive {feature}` | Archive a completed feature (after Gate 3) |
+| `/morph-preflight` | Pre-deploy validation (specs, contracts, tests, infra) |
+| `/morph-troubleshoot [error]` | Root-cause diagnosis for .NET/Next.js errors |
 
 ---
 
-## CLI — project management
+## CLI — approvals & phase advance
 
 ```bash
-morph-spec init [--force] [--skip-mcp]
-morph-spec update [--templates] [--standards]
-morph-spec doctor
+morph-spec approve {feature} {gate} [--mode auto] [--approver name] [--notes text]
+morph-spec advance {feature} [--design]         # approve current gate + scaffold next phase folder in one step
+morph-spec approval-status {feature} [--json]
+morph-spec unapprove {feature} {gate} [--reason text]   # recovery only
+morph-spec archive {feature} [--force] [--no-git]
 ```
 
 ---
 
-## CLI — feature workflow
-
-```bash
-morph-spec state list                          # all features
-morph-spec state get {feature} [--json]        # feature detail
-morph-spec state set {feature} {key} {value}   # update property
-morph-spec phase advance {feature}             # advance to next phase
-morph-spec status {feature} [--json] [--verbose]
-morph-spec task done {feature} {task-id}        # mark task complete
-morph-spec task start {feature} {task-id}      # start a task (dispatch gate)
-```
-
----
-
-## CLI — validation
-
-```bash
-morph-spec validate                            # all validators
-morph-spec validate architecture
-morph-spec validate packages
-morph-spec validate contrast [--wcag-aaa]
-morph-spec validate-feature {feature} [--phase {phase}] [--json]
-morph-spec verify {feature} [task] [--json]    # deterministic build+tests+validators chain, before the LLM judge
-```
-
----
-
-## CLI — work-type routing
+## CLI — feature birth & work-type routing
 
 Every feature is born with a **work type** that dimensions its pipeline: `feature` (full proposal → [uiux] → plan → implement → review), `bug` (lean), `chore` (fast-track straight to implement), `hotfix` (scout → surgical fix → human Gate 3 always, even under `trust: auto`).
 
 ```bash
 morph-spec create {feature} --type feature|bug|chore|hotfix
-morph-spec create {feature} --request "<free text>"     # deterministic detector classifies the type
-morph-spec retype {feature} {newType}                    # change type mid-flight (blocked after Gate 3)
+morph-spec create {feature} --request "<free text>"      # deterministic detector classifies the type
+morph-spec retype {feature} {newType}                     # change type mid-flight (blocked after Gate 3)
 ```
 
 ---
 
-## CLI — worktrees (parallel development / fleet)
-
-One feature = one git worktree = one Claude Code instance. Independent features run side by side without stepping on each other's state; a SessionStart hook injects each worktree's feature identity, allocated ports and handoff pointer into context. Each worktree gets a deterministic port block (`.morph/worktree.env`) and a regenerable handoff document.
+## CLI — state (server-side, timestamped)
 
 ```bash
-morph-spec create {feature} --worktree     # birth the feature already isolated in its own worktree
-morph-spec worktree setup {feature}        # create .worktrees/{feature}/ on branch morph/{feature}
-morph-spec worktree link [--all]           # relink shared infra (node_modules, .claude, .morph/framework)
-morph-spec worktree finish {feature}       # merge --no-ff back to the primary root, clean up + release ports (requires Gate 3)
-morph-spec worktree list [--json]          # active feature worktrees with phase/gate status
-morph-spec handoff {feature} [--json]      # regenerate the compressed session-handoff doc (pointers, not copies)
-morph-spec fleet [--json]                  # fleet view: every active feature (root + worktrees) with phase/gates/ports/handoff/activity
+morph-spec score {feature} {task} {score} [--dims "9.5,9,9,9"]   # writes taskScores
+morph-spec gate-decision {feature} {gate} --pause <bool> [--reason] [--signals json]   # writes gateDecisions
 ```
 
----
-
-## CLI — DAG
-
-```bash
-morph-spec dag {feature} [--json]          # sequential vs parallel dispatch decision (effort-weighted)
-morph-spec dag {feature} --mermaid         # emit the tasks.json DAG as a Mermaid flowchart
-```
+Never hand-edit `taskScores`/`gateDecisions`/`approvalGates` in `feature.json` — always go through these commands (they collide with the `state-sync` hook otherwise).
 
 ---
 
-## CLI — utilities
+## CLI — validation
 
 ```bash
-morph-spec generate recap {feature}           # auto-generate recap.md
-morph-spec template render {id} {output} {vars-json}
-morph-spec trust status [feature]
-morph-spec trust set {feature} {level} [reason]    # level: manual|high|auto
-morph-spec mcp setup [name] [--list] [--auto]
+morph-spec validate [architecture|packages|contrast] [--wcag-aaa]
+morph-spec validate-feature {feature} [--phase {phase}] [--json]   # alias: vf
+morph-spec verify {feature} [task] [--json] [--skip-tests] [--skip-build]   # deterministic build+test+validator chain, before the LLM judge
 ```
 
 ---
 
-## State — mark-output
+## CLI — DAG
 
 ```bash
-morph-spec state mark-output {feature} proposal
-morph-spec state mark-output {feature} spec
-morph-spec state mark-output {feature} contracts
-morph-spec state mark-output {feature} decisions
-morph-spec state mark-output {feature} tasks
-morph-spec state mark-output {feature} recap
-
-# UI outputs (camelCase or kebab-case both work)
-morph-spec state mark-output {feature} uiDesignSystem
-morph-spec state mark-output {feature} uiMockups
-morph-spec state mark-output {feature} uiComponents
-morph-spec state mark-output {feature} uiFlows
+morph-spec dag {feature} [--json]          # sequential vs parallel dispatch decision (effort-weighted)
+morph-spec dag {feature} --mermaid         # emit the tasks.json DAG as a Mermaid flowchart
 ```
 
 ---
 
-## State — agents
-
-```bash
-morph-spec state add-agent {feature} {agent-id}
-morph-spec state remove-agent {feature} {agent-id}
-```
-
----
+## CLI — worktrees (parallel development / fleet)
 
-## Checkpoints
+One feature = one git worktree = one Claude Code instance. Each worktree gets its own deterministic port block (`.morph/worktree.env`) and a regenerable handoff document.
 
 ```bash
-morph-spec checkpoint-save {feature}
+morph-spec create {feature} --worktree     # birth the feature already isolated in its own worktree
+morph-spec worktree setup {feature}        # create .worktrees/{feature}/ on branch morph/{feature}
+morph-spec worktree link [--all]           # relink shared infra (node_modules[, .claude, .morph/framework])
+morph-spec worktree finish {feature}       # merge --no-ff back to the primary root, clean up + release ports (requires Gate 3)
+morph-spec worktree list [--json]          # active feature worktrees with phase/gate status
+morph-spec handoff {feature} [--json]      # regenerate the compressed session-handoff doc (pointers, not copies)
+morph-spec fleet [--json]                  # every active feature (root + worktrees) with phase/gates/ports/handoff/activity
 ```
 
 ---
 
-## Approvals
+## CLI — scaffolding & misc
 
 ```bash
-morph-spec approve {feature} {gate}            # approve a gate
-morph-spec approval-status {feature}           # show gate status
+morph-spec scaffold dotnet {feature} {slice-name} [--dry-run]   # generate a VSA feature slice
+morph-spec scaffold nextjs {feature} [--dry-run]                # generate a feature page + components
+morph-spec context refresh                                       # rescan project, regenerate .morph/context/README.md
+morph-spec mcp setup [name] [--list] [--auto]
+morph-spec dashboard [--port 3200]                                # open the inspector dashboard
 ```
 
 ---
@@ -185,47 +138,35 @@ morph-spec approval-status {feature}           # show gate status
 
 ```
 .morph/
-├── config/
-│   └── config.json               # project config (editable)
+├── config/config.json           # project config (editable)
 ├── framework/                    # READ-ONLY
-│   ├── agents.json               # 22 agents, 4 tiers
-│   ├── standards/                # 82 standards across 11 categories
-│   └── templates/                # code and IaC templates
-├── context/                      # project context (editable)
-│   ├── README.md
-│   └── standards.md
-├── features/
-│   └── {feature}/
-│       ├── 0-proposal/proposal.md
-│       ├── 1-design/design-system.md, mockups.md, components.md, flows.md
-│       ├── 2-design/spec.md, contracts.cs, decisions.md
-│       ├── 3-tasks/tasks.md
-│       └── 4-implement/recap.md
-├── checkpoints/
-├── logs/
-└── state.json                    # READ-ONLY — CLI managed
+│   ├── agents.json                # 8 domain personas
+│   ├── standards/                 # standards registry
+│   └── templates/                 # code, IaC, and context templates
+├── context/                       # project context (editable)
+├── features/{feature}/
+│   ├── feature.json                # authoritative, committed
+│   ├── handoff.md
+│   └── 0-proposal/ 1-design/ 2-plan/ 3-implement/ 4-review/
+└── state.json                      # gitignored, derived index — never hand-edited
 
 .claude/
-├── commands/                     # slash commands
+├── commands/                    # slash commands
 ├── skills/                       # framework skills (SKILL.md per dir)
-├── agents/                       # native subagents (22)
-│   ├── morph-{id}.md             # tier 1-2 agents
-│   └── morph-domain-{name}.md   # tier 3 domain agents
-├── rules/                        # path-scoped rules (6 files)
-└── settings.local.json           # hooks (10)
+├── agents/morph-{id}.md           # generated subagents (one per persona, no tiers)
+└── settings.local.json            # hooks + permissions.deny
 ```
 
 ---
 
 ## Protected files
 
-These files are never edited directly. Use CLI commands or `morph-spec update` instead:
+Never edited directly — go through CLI commands or `morph-spec update` instead:
 
 | Path | Protected by |
 |------|-------------|
-| `.morph/state.json` | `permissions.deny` |
-| `.morph/framework/**` | `permissions.deny` |
-| Approved spec/contracts | `protect-spec-files.js` hook |
+| `.morph/state.json`, `.morph/framework/**` | `permissions.deny` |
+| `tasks.json` plan contract (`title`/`description`/`dependencies`/`effort`/`doneCriteria`/`group`) after Gate 2 | `protect-spec-files` hook (semantic diff) |
 
 ---
 
@@ -239,4 +180,4 @@ These files are never edited directly. Use CLI commands or `morph-spec update` i
 
 ---
 
-*morph-spec v8.2.1 by Polymorphism Tech*
+*morph-spec v8.3.0 by Polymorphism Tech*