@polymorphism-tech/morph-spec 4.7.2 → 4.8.1

package/docs/ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # morph-spec Architecture
 
-> System design reference for morph-spec v4.6.0
+> System design reference for morph-spec v4.8.1
 
 ---
 
@@ -11,7 +11,7 @@ morph-spec is a CLI tool that scaffolds a spec-driven development workflow on to
 The framework has three main concerns:
 
 1. **State** — tracking features, phases, and outputs in `.morph/state.json`
-2. **Agents** — 37 specialized agents organized in 4 tiers, installed as native Claude Code subagents
+2. **Agents** — 38 specialized agents organized in 4 tiers, installed as native Claude Code subagents
 3. **Workflow** — 8 phases from proposal through implementation, enforced via hooks and guards
 
 ---
@@ -24,21 +24,22 @@ Tier 1 — Orchestrators (3)
   ai-system-architect   on-demand — multi-agent / AI system design
   po-pm-advisor         on-demand — requirements, business value
 
-Tier 2 — Domain Leaders (3)
-  dotnet-senior         always active — Backend Squad lead
+Tier 2 — Domain Leaders (4)
+  dotnet-senior         always active — Backend Squad lead (skipped for non-.NET)
   infra-architect       always active — Infrastructure Squad Leader (cloud-agnostic)
+  domain-architect      on-demand — DDD analysis and bounded context design
   ui-designer           on-demand — UI/UX Squad lead
 
-Tier 3 — Specialists (27)
+Tier 3 — Specialists (26)
   Backend (10)          ef-modeler, event-architect, api-designer, nosql-cache-expert,
-                        ddd-expert, hangfire-orchestrator, ms-agent-expert,
-                        asaas-financial, clerk-auth, resend-email
+                        hangfire-orchestrator, ms-agent-expert,
+                        asaas-financial, clerk-auth, resend-email, ddd-expert
   Frontend (3)          blazor-builder, nextjs-expert, css-specialist
   Infrastructure (6)    azure-architect, bicep-architect, devops-engineer,
                         container-specialist, observability-expert, azure-identity
-  Quality/Cross (8)     testing-specialist, code-analyzer, troubleshooting-expert,
+  Quality/Cross (7)     testing-specialist, code-analyzer, troubleshooting-expert,
                         load-testing-expert, documentation-specialist,
-                        migration-specialist, integration-specialist, data-modeler
+                        migration-specialist, integration-specialist
 
 Tier 4 — Validators (5)
   security-expert       SQL injection, XSS, hardcoded secrets
@@ -70,11 +71,13 @@ maxTurns: 20
 ---
 ```
 
-Both sets are updated by `morph-spec update` and `morph-spec update-agents`.
+Both sets are updated by `morph-spec update`.
 
 ### Agent detection
 
-When a feature is created, `detect-agents` matches keywords in the feature description against `agents.json` keyword lists. Matched agents are stored in `state.json` under the feature's `activeAgents` array. The active agent set determines which standards are loaded and which validators run.
+When a feature is created, Claude reads `agents.json` directly and matches keywords in the feature description against each agent's keyword list. Matched agents are stored in `state.json` under the feature's `activeAgents` array. The active agent set determines which standards are loaded and which validators run.
+
+> Note: Some skill files reference `npx morph-spec detect-agents --json` — this is not a real CLI command. Agent detection is performed by Claude reading `agents.json` inline, not by a subprocess.
 
 ---
 
@@ -107,15 +110,15 @@ Canonical phase definitions live in `framework/phases.json`.
 
 ```
 framework/
-├── agents.json              # 37 agents definition (v3.1.0)
+├── agents.json              # 38 agents definition (v3.2.0)
 ├── phases.json              # 8 phase definitions
 ├── CLAUDE_runtime.md        # copied to .claude/CLAUDE.md on init
 ├── agents/                  # tier 1-2 agent markdown files
 ├── hooks/
-│   ├── claude-code/         # 11 Claude Code hook scripts
+│   ├── claude-code/         # 10 Claude Code hook scripts
 │   │   └── shared/          # state-reader, phase-utils, hook-response, stdin-reader
 │   └── git/                 # pre-commit, commit-msg, pre-push
-├── rules/                   # 5 rule files (copied to .claude/rules/)
+├── rules/                   # 6 rule files (copied to .claude/rules/)
 ├── skills/
 │   ├── README.md
 │   ├── level-0-meta/        # 7 meta skills (brainstorming, code-review, etc.)
@@ -126,7 +129,7 @@ framework/
 │   └── level-1-workflows/   # 8 workflow skills (phase-proposal, phase-design, etc.)
 │       └── {skill}/
 │           └── SKILL.md
-├── standards/               # 74 standards, 11 categories
+├── standards/               # 82 standards, 11 categories
 │   ├── STANDARDS.json       # registry (regenerate: node scripts/generate-standards-registry.js)
 │   ├── core/
 │   ├── backend/
@@ -160,7 +163,7 @@ framework/
 │   └── 4-implement/
 ├── checkpoints/
 ├── logs/tool-failures.log
-└── state.json               # READ-ONLY
+└── state.json               # READ-ONLY — gitignored, managed by CLI only
 
 .claude/
 ├── CLAUDE.md                # runtime instructions
@@ -172,11 +175,12 @@ framework/
 │   ├── morph-{id}.md        # tier 1-2 (from framework/agents/)
 │   └── morph-domain-{name}.md # tier 3 (from framework/skills/level-2-domains/)
 ├── rules/                   # path-scoped rules (from framework/rules/)
-│   ├── morph-workflow.md    # always active
-│   ├── csharp-standards.md
-│   ├── frontend-standards.md
-│   ├── testing-standards.md
-│   └── infrastructure-standards.md
+│   ├── morph-workflow.md    # always active (no paths: filter)
+│   ├── csharp-standards.md  # paths: **/*.cs, **/*.csproj
+│   ├── frontend-standards.md # paths: **/*.razor, **/*.css, **/*.scss
+│   ├── nextjs-standards.md  # paths: **/*.tsx, **/*.ts
+│   ├── testing-standards.md # paths: tests/**, **/*.test.*, **/*Tests.cs
+│   └── infrastructure-standards.md # paths: **/*.bicep, **/Dockerfile, ...
 └── settings.local.json      # hooks, permissions.deny, env vars
 ```
 
@@ -212,20 +216,22 @@ Each skill lives in its own directory under `framework/skills/{level}/{skill-nam
 
 ## Hooks system
 
-11 Claude Code hooks are configured in `.claude/settings.local.json`. All hooks fail-open (catch + exit 0) to prevent blocking Claude Code on errors.
+10 Claude Code hooks are configured in `.claude/settings.local.json`. All hooks fail-open (catch + exit 0) to prevent blocking Claude Code on errors.
 
 | Event | Hook | Function |
 |-------|------|----------|
-| `SessionStart` | `inject-morph-context.js` | Injects active feature `1-design/spec.md` (3000 char max) into context |
-| `UserPromptSubmit` | `protect-spec-files.js` | Guards spec files after design gate approval |
-| `PreToolUse` (Bash) | Prompt-type inline guard | Detects destructive shell patterns in Claude's reasoning |
-| `PreToolUse` (Write/Edit) | `validate-feature-phase.js` | Validates write targets against current phase |
-| `PostToolUse` (Write) | `track-output-creation.js` | Detects when feature output files are created; updates state directly via JSON I/O (no subprocess) |
-| `PostToolUse` (any) | `checkpoint-trigger.js` | Triggers auto-checkpoint every 3 completed tasks |
+| `SessionStart` | `inject-morph-context.js` | Injects active feature `1-design/spec.md` (configurable char limit) into context |
+| `UserPromptSubmit` | `enrich-prompt.js` | Scans prompt for feature names/intent; injects phase hints and approval syntax |
+| `PreToolUse` (Write\|Edit) | `protect-spec-files.js` | Blocks edits to spec/contracts after design gate is approved |
+| `PreToolUse` (Write\|Edit) | `enforce-phase-writes.js` | Validates write targets are in the correct phase subfolder |
+| `PreToolUse` (Bash) | Prompt-type inline guard (`type: "prompt"`) | Detects destructive shell patterns; no subprocess |
+| `PostToolUse` (Bash) | `dispatch.js` | Auto-checkpoint via `morph-spec checkpoint-save` every 3 completed tasks |
 | `PostToolUseFailure` | `handle-tool-failure.js` | Appends failure details to `.morph/logs/tool-failures.log` |
-| `Stop` | `session-summary.js` | Writes session summary |
-| `PreCompact` | `compact-context.js` | Preserves critical state before context compaction |
-| `Notification` | `morph-notify.js` | Routes approval gate notifications |
+| `Stop` | `validate-completion.js` | Warns about incomplete tasks, missing outputs, or pending approval gates |
+| `PreCompact` | `save-morph-context.js` | Snapshots state to `.morph/memory/pre-compact-{ts}.json` |
+| `Notification` | `approval-reminder.js` | Reminds about pending approval gates when Claude is idle |
+
+> Note: `.morph/state.json` and `.morph/framework/**` are protected via native `permissions.deny` in `settings.local.json` — not a hook.
 
 Shared utilities live in `framework/hooks/claude-code/shared/`:
 - `state-reader.js` — reads `.morph/state.json` without subprocess
@@ -282,7 +288,7 @@ Feature outputs (spec.md, contracts.cs, tasks.md, etc.) are tracked by scanning
 
 ## Standards registry
 
-74 standards across 11 categories are registered in `framework/standards/STANDARDS.json`. Each entry has an `id`, `name`, `path`, `scope`, `layer`, and `keywords`.
+82 standards across 11 categories are registered in `framework/standards/STANDARDS.json`. Each entry has an `id`, `name`, `path`, `scope`, `layer`, and `keywords`.
 
 Regenerate the registry after adding standards:
 
@@ -290,15 +296,6 @@ Regenerate the registry after adding standards:
 node scripts/generate-standards-registry.js
 ```
 
-Browse via CLI:
-
-```bash
-morph-spec standards --list
-morph-spec standards --list --category backend
-morph-spec standards --search "async"
-morph-spec standards --show csharp-naming
-```
-
 ---
 
 ## Workflow configs
@@ -320,12 +317,12 @@ Trust levels (`low`, `medium`, `high`, `maximum`) control how many approval gate
 
 ## CLI internals
 
-- **Entry point:** `bin/morph-spec.js` — Commander.js, 110+ commands
-- **Commands:** `src/commands/` — organized into subdirectories by domain
+- **Entry point:** `bin/morph-spec.js` — Commander.js, ~20 framework-internal commands + 3 user commands (`init`, `update`, `doctor`)
+- **Commands:** `src/commands/` — organized into subdirectories by domain (project, state, tasks, validation, templates, trust, mcp)
 - **Libraries:** `src/lib/` — state, validators, templates, agents, detection
-- **Templates engine:** Handlebars v2.0 with helpers (pascalCase, camelCase, snakeCase, pluralize)
-- **Test suite:** `test/` — Node.js built-in test runner, 625+ tests
+- **Templates engine:** Handlebars v2.0 with helpers (pascalCase, camelCase, snakeCase, kebabCase, pluralize)
+- **Test suite:** `test/` — Node.js built-in test runner, 670+ tests
 
 ---
 
-*morph-spec v4.6.0 by Polymorphism Tech*
+*morph-spec v4.8.1 by Polymorphism Tech*

package/docs/CHEATSHEET.md

@@ -1,221 +1,203 @@
-# morph-spec Cheat Sheet
-
-## Setup
-
-```bash
-npm install -g @polymorphism-tech/morph-spec   # install 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 --version
-```
-
----
-
-## Phase workflow
-
-```
-proposal → setup → [uiux] → design → clarify → tasks → implement → [sync]
-```
-
-Phases in brackets are optional.
-
-| Phase | Directory | Output files | Gate |
-|-------|-----------|--------------|------|
-| proposal | `0-proposal/` | `proposal.md` | ✅ Approval |
-| setup | *(no output)* | context loaded | — |
-| uiux *(optional)* | `2-ui/` | `design-system.md`, `mockups.md`, `components.md`, `flows.md` | ✅ Approval |
-| design | `1-design/` | `spec.md`, `contracts.cs`, `decisions.md` | ✅ Approval |
-| clarify | `1-design/` | spec updated | — |
-| tasks | `3-tasks/` | `tasks.md` | ✅ Approval |
-| implement | `4-implement/` | code + `recap.md` | — |
-| sync *(optional)* | `.morph/context/` | standards updated | — |
-
----
-
-## 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-status` | Project-wide feature status dashboard |
-| `/morph-preflight` | Pre-implementation validation (7 checks) |
-
----
-
-## CLI — project management
-
-```bash
-morph-spec init [--wizard] [--force] [--skip-detection] [--skip-mcp]
-morph-spec update [--wizard] [--templates] [--standards]
-morph-spec doctor
-morph-spec detect [--verbose]
-morph-spec update-agents                       # refresh .claude/agents/
-```
-
----
-
-## CLI — feature workflow
-
-```bash
-morph-spec state list                          # all features
-morph-spec state get {feature} [--json]        # feature detail
-morph-spec state show {feature}                # phase + approval status
-morph-spec state set {feature} {key} {value}   # update property
-morph-spec state checkpoint {feature} "note"   # manual checkpoint
-morph-spec phase advance {feature}             # advance to next phase
-morph-spec status {feature} [--json] [--verbose]
-morph-spec diff {feature}                      # spec changes since snapshot
-morph-spec diff-save {feature}                 # save snapshot
-morph-spec rollback {feature} --to {phase}     # revert to phase
-morph-spec task done {feature}                 # mark task complete
-morph-spec task start {feature}                # start next task
-morph-spec task next {feature}                 # preview next task
-```
-
----
-
-## 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-blazor [path]
-morph-spec validate-blazor-state [path]
-morph-spec analyze-blazor-concurrency [path]
-morph-spec validate-css [path]
-morph-spec validate-feature {feature} [--phase {phase}] [--json]
-```
-
----
-
-## CLI — standards
-
-```bash
-morph-spec standards --list
-morph-spec standards --list --category {name}  # categories: core, backend, frontend, infra, ...
-morph-spec standards --search {query}
-morph-spec standards --show {id}
-morph-spec standards --json
-```
-
----
-
-## CLI — utilities
-
-```bash
-morph-spec cost {bicep-file}                   # Azure cost estimate
-morph-spec cost {bicep-file} --verbose
-morph-spec cost {bicep-file} --strict          # exit 1 if over limit
-morph-spec troubleshoot {keywords}
-morph-spec troubleshoot --category {name}
-morph-spec session-summary {feature}
-```
-
----
-
-## State — mark-output
-
-```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
-```
-
----
-
-## State — agents
-
-```bash
-morph-spec state add-agent {feature} {agent-id}
-morph-spec state remove-agent {feature} {agent-id}
-morph-spec detect-agents "{description}"          # detect agents for request
-morph-spec detect-agents --json "{description}"   # with standards
-morph-spec detect-agents --ids-only "{description}"
-```
-
----
-
-## Checkpoints
-
-```bash
-morph-spec checkpoint-save {feature}
-morph-spec checkpoint-restore {feature}
-morph-spec checkpoint-list {feature}
-```
-
----
-
-## Directory structure
-
-```
-.morph/
-├── config/
-│   └── config.json               # project config (editable)
-├── framework/                    # READ-ONLY
-│   ├── agents.json               # 37 agents, 4 tiers
-│   ├── standards/                # 74 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/spec.md, contracts.cs, decisions.md
-│       ├── 2-ui/design-system.md, mockups.md, components.md, flows.md
-│       ├── 3-tasks/tasks.md
-│       └── 4-implement/recap.md
-├── checkpoints/
-├── logs/
-└── state.json                    # READ-ONLY — CLI managed
-
-.claude/
-├── commands/                     # slash commands
-├── skills/                       # framework skills (SKILL.md per dir)
-├── agents/                       # native subagents (37)
-│   ├── morph-{id}.md             # tier 1-2 agents
-│   └── morph-domain-{name}.md   # tier 3 domain agents
-├── rules/                        # path-scoped rules (5 files)
-└── settings.local.json           # hooks (11)
-```
-
----
-
-## Protected files
-
-These files are never edited directly. Use 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 |
-
----
-
-## Links
-
-- [QUICKSTART.md](QUICKSTART.md) — step-by-step guide
-- [ARCHITECTURE.md](ARCHITECTURE.md) — system design
-- [CHANGELOG.md](../CHANGELOG.md) — release history
-- [npm](https://www.npmjs.com/package/@polymorphism-tech/morph-spec)
-- support@polymorphism.com.br
-
----
-
-*morph-spec v4.6.0 by Polymorphism Tech*
+# morph-spec Cheat Sheet
+
+## Setup
+
+```bash
+npm install -g @polymorphism-tech/morph-spec   # install 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 --version
+```
+
+---
+
+## Phase workflow
+
+```
+proposal → setup → [uiux] → design → clarify → tasks → implement → [sync]
+```
+
+Phases in brackets are optional.
+
+| Phase | Directory | Output files | Gate |
+|-------|-----------|--------------|------|
+| proposal | `0-proposal/` | `proposal.md` | ✅ Approval |
+| setup | *(no output)* | context loaded | — |
+| uiux *(optional)* | `2-ui/` | `design-system.md`, `mockups.md`, `components.md`, `flows.md` | ✅ Approval |
+| design | `1-design/` | `spec.md`, `contracts.cs`, `decisions.md` | ✅ Approval |
+| clarify | `1-design/` | spec updated | — |
+| tasks | `3-tasks/` | `tasks.md` | ✅ Approval |
+| implement | `4-implement/` | code + `recap.md` | — |
+| sync *(optional)* | `.morph/context/` | standards updated | — |
+
+---
+
+## 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-status` | Project-wide feature status dashboard |
+| `/morph-preflight` | Pre-implementation validation (7 checks) |
+
+---
+
+## CLI — project management
+
+```bash
+morph-spec init [--force] [--skip-mcp]
+morph-spec update [--templates] [--standards]
+morph-spec doctor
+```
+
+---
+
+## 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}                 # mark task complete
+morph-spec task start {feature}                # start next task
+morph-spec task next {feature}                 # preview next task
+```
+
+---
+
+## 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]
+```
+
+---
+
+## CLI — utilities
+
+```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]
+morph-spec mcp setup [name] [--list] [--auto]
+```
+
+---
+
+## State — mark-output
+
+```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
+```
+
+---
+
+## State — agents
+
+```bash
+morph-spec state add-agent {feature} {agent-id}
+morph-spec state remove-agent {feature} {agent-id}
+```
+
+---
+
+## Checkpoints
+
+```bash
+morph-spec checkpoint-save {feature}
+morph-spec checkpoint-restore {feature}
+morph-spec checkpoint-list {feature}
+```
+
+---
+
+## Approvals
+
+```bash
+morph-spec approve {feature} {gate}            # approve a gate
+morph-spec approval-status {feature}           # show gate status
+```
+
+---
+
+## Directory structure
+
+```
+.morph/
+├── config/
+│   └── config.json               # project config (editable)
+├── framework/                    # READ-ONLY
+│   ├── agents.json               # 38 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/spec.md, contracts.cs, decisions.md
+│       ├── 2-ui/design-system.md, mockups.md, components.md, flows.md
+│       ├── 3-tasks/tasks.md
+│       └── 4-implement/recap.md
+├── checkpoints/
+├── logs/
+└── state.json                    # READ-ONLY — CLI managed
+
+.claude/
+├── commands/                     # slash commands
+├── skills/                       # framework skills (SKILL.md per dir)
+├── agents/                       # native subagents (38)
+│   ├── 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 (11)
+```
+
+---
+
+## Protected files
+
+These files are never edited directly. Use 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 |
+
+---
+
+## Links
+
+- [QUICKSTART.md](QUICKSTART.md) — step-by-step guide
+- [ARCHITECTURE.md](ARCHITECTURE.md) — system design
+- [CHANGELOG.md](../CHANGELOG.md) — release history
+- [npm](https://www.npmjs.com/package/@polymorphism-tech/morph-spec)
+- support@polymorphism.com.br
+
+---
+
+*morph-spec v4.8.1 by Polymorphism Tech*