@polymorphism-tech/morph-spec 4.8.19 → 4.10.0

package/docs/CHEATSHEET.md

@@ -1,203 +1,201 @@
-# 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.19 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} {task-id}        # mark task complete
+morph-spec task start {feature} {task-id}      # start a 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]    # level: manual|high|auto
+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}
+```
+
+---
+
+## 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               # 42 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.10.0 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -127,7 +127,7 @@ morph-spec phase advance my-feature
 Mark a task complete:
 
 ```bash
-morph-spec task done my-feature
+morph-spec task done my-feature T001
 ```
 
 Run validators at any time:
@@ -203,4 +203,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v4.8.19 by Polymorphism Tech*
+*morph-spec v4.10.0 by Polymorphism Tech*

package/framework/CLAUDE.md

@@ -1,77 +1,99 @@
-# MORPH-SPEC Runtime Instructions
-
-> by Polymorphism Tech — Spec-driven development for .NET/Blazor/Next.js/Azure
-
----
-
-## Project Context
-
-@.morph/context/README.md
-
----
-
-## Critical Rules
-
-**NEVER:**
-- Skip to code without a specification
-- Implement without design approval
-- Ignore standards in `.morph/framework/standards/`
-- Create infrastructure manually
-- Generate code without defined contracts
-
-**ALWAYS:**
-- Follow the mandatory phases
-- Generate outputs in `.morph/features/{feature}/`
-- Document decisions in `decisions.md`
-- Checkpoint every 3 implemented tasks
-- Use Infrastructure as Code
-
----
-
-## Quick Reference
-
-| Command | Purpose |
-|---------|---------|
-| `/morph-proposal {feature}` | Full spec pipeline (phases 1–4, pauses for approval) |
-| `/morph-apply {feature}` | Implement feature (phase 5) |
-| `/morph-status` | Feature status dashboard |
-| `/morph-preflight` | Pre-implementation validation |
-
----
-
-## State & Outputs
-
-| Path | Notes |
-|------|-------|
-| `.morph/state.json` | **READ-ONLY** — use `morph-spec` CLI to update |
-| `.morph/features/{feature}/{phase}/` | Feature outputs organized by phase |
-| `.morph/framework/` | **READ-ONLY** — framework files managed by morph-spec |
-| `.morph/config/config.json` | Project configuration (editable) |
-
----
-
-## Phase Sequence
-
-```
-proposal → setup → [uiux] → design → clarify → tasks → implement → [sync]
-```
-
-Use `morph-spec status {feature}` to see current phase and pending approval gates.
-
----
-
-## Agents
-
-Tier-1 and tier-2 MORPH agents are available as native subagents in `.claude/agents/`.
-They can be invoked directly by Claude Code during multi-agent workflows.
-
----
-
-## Context Window Tip
-
-When using 3+ MCPs, add `"experimental": { "mcpCliMode": true }` to `.claude/settings.json`.
-MCP tools load on-demand instead of all at startup — keeps context clean for actual work.
-
----
-
-*MORPH-SPEC by Polymorphism Tech*
+# MORPH-SPEC Runtime Instructions
+
+> by Polymorphism Tech — Spec-driven development for .NET/Blazor/Next.js/Azure
+
+---
+
+## Project Context
+
+@.morph/context/README.md
+
+---
+
+## Critical Rules
+
+**NEVER:**
+- Skip to code without a specification
+- Implement without design approval
+- Ignore standards in `.morph/framework/standards/`
+- Create infrastructure manually
+- Generate code without defined contracts
+- List questions as plain text — always use the `AskUserQuestion` tool
+
+**ALWAYS:**
+- Follow the mandatory phases
+- Generate outputs in `.morph/features/{feature}/`
+- Document decisions in `decisions.md`
+- Checkpoint every 3 implemented tasks
+- Use Infrastructure as Code
+- Use `AskUserQuestion` tool whenever asking the user anything (1–4 questions per call; split into sequential calls if more)
+
+---
+
+## Quick Reference
+
+| Command | Purpose |
+|---------|---------|
+| `/morph-proposal {feature}` | Full spec pipeline (phases 1–4, pauses for approval) |
+| `/morph-apply {feature}` | Implement feature (phase 5) |
+| `/morph-status` | Feature status dashboard |
+| `/morph-preflight` | Pre-implementation validation |
+
+---
+
+## State & Outputs
+
+| Path | Notes |
+|------|-------|
+| `.morph/state.json` | **READ-ONLY** — use `morph-spec` CLI to update |
+| `.morph/features/{feature}/{phase}/` | Feature outputs organized by phase |
+| `.morph/framework/` | **READ-ONLY** — framework files managed by morph-spec |
+| `.morph/config/config.json` | Project configuration (editable) |
+
+### mark-output types
+
+Use `morph-spec state mark-output <feature> <type>` with one of these exact type names:
+
+| Type | Phase | kebab alias |
+|------|-------|-------------|
+| `proposal` | proposal | — |
+| `schemaAnalysis` | design | `schema-analysis` |
+| `spec` | design | — |
+| `contracts` | design | — |
+| `contractsVsa` | design | `contracts-vsa` |
+| `decisions` | design | — |
+| `clarifications` | clarify | — |
+| `plan` | plan | — |
+| `tasks` | tasks | — |
+| `uiDesignSystem` | uiux | `ui-design-system` |
+| `uiMockups` | uiux | `ui-mockups` |
+| `uiComponents` | uiux | `ui-components` |
+| `uiFlows` | uiux | `ui-flows` |
+| `recap` | implement | — |
+---
+
+## Phase Sequence
+
+```
+proposal → setup → [uiux] → design → clarify → plan → tasks → implement → [sync]
+```
+
+Use `morph-spec status {feature}` to see current phase and pending approval gates.
+
+---
+
+## Agents
+
+Tier-1 and tier-2 MORPH agents are available as native subagents in `.claude/agents/`.
+They can be invoked directly by Claude Code during multi-agent workflows.
+
+---
+
+## Context Window Tip
+
+When using 3+ MCPs, add `"experimental": { "mcpCliMode": true }` to `.claude/settings.json`.
+MCP tools load on-demand instead of all at startup — keeps context clean for actual work.
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*