@polymorphism-tech/morph-spec 8.2.1 → 8.4.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.4.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
@@ -181,8 +184,8 @@ morph-spec verify {feature} [task]     # Deterministic build+tests+validators ch
 ### Work-type routing
 
 ```bash
-morph-spec create {feature} --type feature|bug|chore|hotfix   # Explicit birth: type dimensions the pipeline
-morph-spec create {feature} --request "<free text>"           # Deterministic detector classifies the type
+morph-spec create {feature} --type feature|bug|chore|hotfix --description "<what/why>"   # Explicit birth: type dimensions the pipeline, description is required
+morph-spec create {feature} --request "<free text>"           # Detector classifies the type AND seeds the description
 morph-spec retype {feature} {newType}                          # Change work type mid-flight (blocked after Gate 3)
 morph-spec dag {feature} [--mermaid]                            # DAG dispatch decision; --mermaid emits a flowchart
 ```
@@ -190,7 +193,7 @@ morph-spec dag {feature} [--mermaid]                            # DAG dispatch d
 ### Worktrees (parallel development)
 
 ```bash
-morph-spec create {feature} --worktree   # Birth the feature already isolated in its own worktree
+morph-spec create {feature} --description "<what/why>" --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 (requires Gate 3)
@@ -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.4.0 by [Polymorphism Tech](https://polymorphism.tech)*

package/bin/morph-spec.js

@@ -35,6 +35,8 @@ import { gateDecisionCommand } from '../src/commands/state/gate-decision.js';
 import { createCommand } from '../src/commands/state/create.js';
 import { retypeCommand } from '../src/commands/state/retype.js';
 import { handoffCommand } from '../src/commands/state/handoff.js';
+import { listCommand } from '../src/commands/state/list.js';
+import { deleteCommand } from '../src/commands/state/delete.js';
 
 // === Tasks ===
 import { dagCommand } from '../src/commands/tasks/dag.js';
@@ -56,6 +58,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'));
 
@@ -123,13 +128,22 @@ program
   .option('-v, --verbose', 'Show detailed output')
   .action(statusCommand);
 
+program
+  .command('list')
+  .description('List every feature × status × gates (G1/G2/G3) × workType — the audit board')
+  .option('--all', 'Include archived features (.morph/archive)')
+  .option('--archived', 'Include archived features (alias of --all)')
+  .option('--json', 'Output as JSON')
+  .action((options) => listCommand(options));
+
 // ─── Approval gates (dev-only) ────────────────────────────────────────────
 program
   .command('approve <feature> <gate>')
-  .description('Approve a phase gate (proposal, plan, review)')
+  .description('Approve a phase gate (proposal, plan, review). Enforces gate order (N requires N-1)')
   .option('--approver <name>', 'Name of approver (default: current user when interactive, "auto" otherwise)')
   .option('--mode <mode>', 'Approval mode: "user" or "auto" (default: detected from TTY)')
   .option('--notes <notes>', 'Approval notes')
+  .option('--force', 'Approve out of order (bypass the gate-monotonicity check)')
   .action((feature, gate, options) => approveCommand(feature, gate, options));
 
 program
@@ -139,6 +153,7 @@ program
   .option('--mode <mode>', 'Approval mode: "user" or "auto" (default: detected from TTY)')
   .option('--design', 'From proposal, advance into the optional design (uiux) phase instead of plan')
   .option('--notes <notes>', 'Approval notes')
+  .option('--force', 'Advance even if a prerequisite gate is unapproved (out-of-order recovery)')
   .action((feature, options) => advanceCommand(feature, options));
 
 program
@@ -148,6 +163,15 @@ program
   .option('--force', 'Archive even if Gate 3 (review) is not approved')
   .action((feature, options) => archiveCommand(feature, options));
 
+program
+  .command('delete <feature>')
+  .description('Delete a feature (hard by default; --archive marks it abandoned). Refuses if a gate is approved unless --force')
+  .option('--archive', 'Soft delete: move to .morph/archive with status "abandoned" instead of removing')
+  .option('--force', 'Delete even when a gate is approved')
+  .option('--no-git', 'Skip git staging of the removal')
+  .option('--json', 'Output as JSON')
+  .action((feature, options) => deleteCommand(feature, options));
+
 program
   .command('approval-status <feature>')
   .description('Show approval status for all gates')
@@ -175,6 +199,8 @@ program
 program
   .command('create <feature>')
   .description('Classify work type (--type/--request), scaffold + stamp policy gates, and create the canonical feature.json (explicit birth — see framework/schemas/feature.schema.json)')
+  .option('--name <name>', 'Human-readable feature name (default: the slug)')
+  .option('--description <text>', 'What/why of the feature — required at birth unless --request is given (it seeds the description)')
   .option('--status <status>', 'Initial feature status (default: in_progress)')
   .option('--type <type>', 'Work type: feature|bug|chore|hotfix (default: feature) — see src/core/work-types.js')
   .option('--request <text>', 'Free-text request classified by the deterministic detector; tie/none exits 2 with candidates for an LLM/user decision (feature NOT created)')
@@ -344,4 +370,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.4.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",