@polymorphism-tech/morph-spec 4.8.11 → 4.8.14

package/README.md

@@ -1,379 +1,379 @@
-# morph-spec
-
-> Spec-driven development framework for multi-stack projects. Turns feature requests into implementation-ready code through structured, AI-orchestrated phases.
-
-**Package:** `@polymorphism-tech/morph-spec`
-**Version:** 4.8.11  
-**Requires:** Node.js 18+, 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.
-
-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.
-
----
-
-## Requirements
-
-- [Claude Code](https://claude.ai/code) (latest)
-- Node.js 18+
-- npm 9+ or pnpm
-
----
-
-## Installation
-
-Install the CLI globally:
-
-```bash
-npm install -g @polymorphism-tech/morph-spec
-```
-
-Then initialize in your project:
-
-```bash
-morph-spec init
-```
-
-### Init options
-
-
-| Flag         | Description                           |
-| ------------ | ------------------------------------- |
-| `--force`    | Overwrite existing installation       |
-| `--skip-mcp` | Skip MCP configuration prompt         |
-| `--path`     | Target directory (default: cwd)       |
-
-
-After init, open the project in Claude Code. The framework activates automatically via `.claude/settings.local.json`.
-
----
-
-## Project structure (after init)
-
-```
-your-project/
-├── CLAUDE.md                        # AI instructions for this project
-├── .morph/
-│   ├── config/
-│   │   └── config.json              # Project configuration
-│   ├── framework/
-│   │   ├── agents.json              # 38 agents in 4 tiers (READ-ONLY)
-│   │   ├── standards/               # Coding and architecture standards (READ-ONLY)
-│   │   └── templates/               # Code and IaC templates (READ-ONLY)
-│   ├── context/                     # Project context (README.md, standards.md)
-│   ├── features/                    # Active features
-│   │   └── {feature}/
-│   │       ├── 0-proposal/          # User story + acceptance criteria
-│   │       ├── 1-design/            # Technical spec, contracts, decisions
-│   │       ├── 2-ui/                # UI/UX design (optional, UI-heavy features)
-│   │       ├── 3-tasks/             # Atomic task list
-│   │       └── 4-implement/         # Recap and implementation notes
-│   └── state.json                   # READ-ONLY — managed by CLI only
-└── .claude/
-    ├── commands/                    # Slash commands
-    ├── skills/                      # Framework skills (flat .md files)
-    ├── agents/                      # Native subagents (38 agents)
-    ├── rules/                       # Path-scoped standards rules
-    └── settings.local.json          # Hooks configuration (10 hooks)
-```
-
----
-
-## Phase workflow
-
-Features move through structured phases. Some are optional depending on feature type.
-
-```
-proposal → setup → [uiux] → design → clarify → tasks → implement → [sync]
-```
-
-Phases in brackets are optional. `uiux` applies to UI-heavy features. `sync` is a post-implementation reconciliation step.
-
-### Phase outputs
-
-
-| Phase     | Directory      | Key files                                                     |
-| --------- | -------------- | ------------------------------------------------------------- |
-| Proposal  | `0-proposal/`  | `proposal.md`                                                 |
-| Design    | `1-design/`    | `spec.md`, `contracts.cs`, `decisions.md`                     |
-| UI/UX     | `2-ui/`        | `design-system.md`, `mockups.md`, `components.md`, `flows.md` |
-| Tasks     | `3-tasks/`     | `tasks.md`                                                    |
-| Implement | `4-implement/` | `recap.md`                                                    |
-
-
-### Approval gates
-
-- **Design gate** — Spec must be approved before moving to Tasks.
-- **Implementation gate** — Task list must be approved before implementation starts.
-
-Check gate status:
-
-```bash
-morph-spec approval-status {feature}
-```
-
----
-
-## Slash commands
-
-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-status`             | Feature status dashboard                                  |
-| `/morph-preflight`          | Pre-implementation validation                             |
-
-
----
-
-## CLI reference
-
-### Project management
-
-```bash
-morph-spec init                        # Initialize MORPH in current project
-morph-spec init --force                # Overwrite existing installation
-morph-spec update                      # Update framework files and re-analyze project
-morph-spec doctor                      # Check installation health
-morph-spec doctor --full               # Full health check (all file verifications)
-```
-
-### 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 task next {feature}         # Preview next task
-morph-spec status {feature}            # Feature status dashboard
-```
-
-### Validation
-
-```bash
-morph-spec validate                    # Run all validators
-morph-spec validate {validator}        # Run specific validator
-morph-spec validate-feature {feature}  # Content-aware feature validation
-```
-
----
-
-## Agent hierarchy
-
-morph-spec includes 38 agents organized in 4 tiers (3+4+26+5). 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 (3)
-
-
-| Agent                 | Role                                                   | Active    |
-| --------------------- | ------------------------------------------------------ | --------- |
-| `standards-architect` | Chief Architect — enforces standards across all phases | Always    |
-| `ai-system-architect` | AI/Agent system design and orchestration               | On-demand |
-| `po-pm-advisor`       | Product and project advisory                           | On-demand |
-
-
-### Tier 2 — Domain Leaders (4)
-
-
-| Agent              | Squad                     | Active    |
-| ------------------ | ------------------------- | --------- |
-| `dotnet-senior`    | Backend squad lead        | Always    |
-| `infra-architect`  | Infrastructure squad lead | Always    |
-| `domain-architect` | DDD & domain modeling     | On-demand |
-| `ui-designer`      | UI/UX squad lead          | On-demand |
-
-
-### Tier 3 — Specialists (26)
-
-Organized into squads:
-
-**Backend (10):** C#/.NET specialists, EF Core, Dapper, SignalR, CQRS, Domain modeling, API design, Auth, Background services, Testing
-
-**Frontend (3):** Blazor components, Next.js/React, CSS/design system
-
-**Infrastructure (5):** Azure Bicep, CI/CD pipelines, Containerization, Monitoring, Cost optimization
-
-**Quality/Cross (8):** Security review, Performance, Accessibility, Documentation, Code review, Migration, Integration, Data modeling
-
-### Tier 4 — Validators (5)
-
-
-| Agent                          | Validates                               |
-| ------------------------------ | --------------------------------------- |
-| `security-expert`              | Security vulnerabilities and compliance |
-| `architecture-expert`          | Architectural decisions and constraints |
-| `packages-validator`           | Package versions and compatibility      |
-| `design-system-validator`      | Design system adherence                 |
-| `blazor-concurrency-validator` | Blazor thread safety and concurrency    |
-
-
----
-
-## Hooks
-
-10 Claude Code hooks are installed into `.claude/settings.local.json` across 8 event types:
-
-
-| 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             |
-| `Notification`       | `approval-reminder.js`     | Reminds about pending approval gates                              |
-
-
-Protected files (via `permissions.deny`):
-
-- `.morph/state.json` — never edited directly, CLI only
-- `.morph/framework/`** — read-only framework content
-
----
-
-## Rules
-
-Path-scoped rules are installed to `.claude/rules/` and activate automatically based on file patterns:
-
-
-| 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/**`         |
-
-
----
-
-## Stack support
-
-
-| Technology                                  | Support                                          |
-| ------------------------------------------- | ------------------------------------------------ |
-| .NET 10 / ASP.NET Core                      | Full — C# contracts, EF Core, CQRS, Minimal API  |
-| Blazor (WebAssembly / Server / MAUI Hybrid) | Full — components, concurrency, design system    |
-| Next.js / React / TypeScript                | Full — components, routing, state management     |
-| Azure (Bicep)                               | Full — IaC templates, cost estimation, pipelines |
-| GitHub Actions                              | Full — CI/CD workflow templates                  |
-| Supabase                                    | Supported via MCP integration                    |
-
-
-TypeScript strict mode is enforced by default. See `.morph/framework/standards/` for all coding standards.
-
----
-
-## Update
-
-To update the framework files in an existing project:
-
-```bash
-morph-spec update
-```
-
-This re-syncs `.morph/framework/`, `.claude/skills/`, `.claude/agents/`, `.claude/rules/`, and `CLAUDE.md` with the installed package version. Your `.morph/config/config.json`, `.morph/context/`, and feature outputs are not touched.
-
-After updating, run `morph-spec doctor` to confirm the installation is healthy.
-
----
-
-## Key rules
-
-**Never skip phases.** Every feature starts with a proposal. No code is written until the design is approved and a task list exists.
-
-**Never edit protected files directly:**
-
-- `.morph/state.json` — use `morph-spec state set`
-- `.morph/framework/`** — read-only, updated by `morph-spec update`
-
-**Always document decisions.** Each feature has a `1-design/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.
-
----
-
-## Troubleshooting
-
-### `morph-spec: command not found`
-
-If you are using nvm-windows or a Node version manager, the global bin path may not be on `PATH` in your shell. Use `npx` instead:
-
-```bash
-npx @polymorphism-tech/morph-spec init
-```
-
-Or add the npm global bin to your PATH:
-
-```bash
-npm config get prefix
-# Add {prefix}/bin to your PATH
-```
-
-### `morph-spec doctor` reports issues
-
-Run doctor to see all checks:
-
-```bash
-morph-spec doctor
-```
-
-Common fixes:
-
-- **Missing `.claude/agents/`** — run `morph-spec update` to reinstall agents
-- **Missing `.claude/rules/`** — run `morph-spec update` to reinstall rules
-- **State version mismatch** — state auto-migrates on next CLI command; if it fails, back up and re-init
-- **Hooks not firing** — confirm `.claude/settings.local.json` exists and contains the `hooks` key
-
-### EPERM on Windows global install
-
-Windows may block global npm installs without elevated permissions. Options:
-
-1. Run terminal as Administrator (not recommended long-term)
-2. Change npm global prefix to a user-writable directory:
-
-```bat
-mkdir %APPDATA%\npm-global
-npm config set prefix %APPDATA%\npm-global
-:: Add %APPDATA%\npm-global to your PATH
-npm install -g @polymorphism-tech/morph-spec
-```
-
-1. Use `npx` for all CLI invocations
-
-### Hook not triggering on SessionStart
-
-Ensure `.claude/settings.local.json` is not gitignored in your project. The file must be present for Claude Code to load hooks. If it is missing, re-run `morph-spec init --force`.
-
----
-
-## 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`.
-
----
-
-## License
-
-Proprietary — see [LICENSE](./LICENSE).
-
-Code generated by morph-spec (contracts, templates, implementation output) belongs to you.
-
----
-
-*morph-spec v4.8.11 by [Polymorphism Tech](https://polymorphism.tech)*
+# morph-spec
+
+> Spec-driven development framework for multi-stack projects. Turns feature requests into implementation-ready code through structured, AI-orchestrated phases.
+
+**Package:** `@polymorphism-tech/morph-spec`
+**Version:** 4.8.14  
+**Requires:** Node.js 18+, 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.
+
+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.
+
+---
+
+## Requirements
+
+- [Claude Code](https://claude.ai/code) (latest)
+- Node.js 18+
+- npm 9+ or pnpm
+
+---
+
+## Installation
+
+Install the CLI globally:
+
+```bash
+npm install -g @polymorphism-tech/morph-spec
+```
+
+Then initialize in your project:
+
+```bash
+morph-spec init
+```
+
+### Init options
+
+
+| Flag         | Description                           |
+| ------------ | ------------------------------------- |
+| `--force`    | Overwrite existing installation       |
+| `--skip-mcp` | Skip MCP configuration prompt         |
+| `--path`     | Target directory (default: cwd)       |
+
+
+After init, open the project in Claude Code. The framework activates automatically via `.claude/settings.local.json`.
+
+---
+
+## Project structure (after init)
+
+```
+your-project/
+├── CLAUDE.md                        # AI instructions for this project
+├── .morph/
+│   ├── config/
+│   │   └── config.json              # Project configuration
+│   ├── framework/
+│   │   ├── agents.json              # 38 agents in 4 tiers (READ-ONLY)
+│   │   ├── standards/               # Coding and architecture standards (READ-ONLY)
+│   │   └── templates/               # Code and IaC templates (READ-ONLY)
+│   ├── context/                     # Project context (README.md, standards.md)
+│   ├── features/                    # Active features
+│   │   └── {feature}/
+│   │       ├── 0-proposal/          # User story + acceptance criteria
+│   │       ├── 1-design/            # Technical spec, contracts, decisions
+│   │       ├── 2-ui/                # UI/UX design (optional, UI-heavy features)
+│   │       ├── 3-tasks/             # Atomic task list
+│   │       └── 4-implement/         # Recap and implementation notes
+│   └── state.json                   # READ-ONLY — managed by CLI only
+└── .claude/
+    ├── commands/                    # Slash commands
+    ├── skills/                      # Framework skills (flat .md files)
+    ├── agents/                      # Native subagents (38 agents)
+    ├── rules/                       # Path-scoped standards rules
+    └── settings.local.json          # Hooks configuration (10 hooks)
+```
+
+---
+
+## Phase workflow
+
+Features move through structured phases. Some are optional depending on feature type.
+
+```
+proposal → setup → [uiux] → design → clarify → tasks → implement → [sync]
+```
+
+Phases in brackets are optional. `uiux` applies to UI-heavy features. `sync` is a post-implementation reconciliation step.
+
+### Phase outputs
+
+
+| Phase     | Directory      | Key files                                                     |
+| --------- | -------------- | ------------------------------------------------------------- |
+| Proposal  | `0-proposal/`  | `proposal.md`                                                 |
+| Design    | `1-design/`    | `spec.md`, `contracts.cs`, `decisions.md`                     |
+| UI/UX     | `2-ui/`        | `design-system.md`, `mockups.md`, `components.md`, `flows.md` |
+| Tasks     | `3-tasks/`     | `tasks.md`                                                    |
+| Implement | `4-implement/` | `recap.md`                                                    |
+
+
+### Approval gates
+
+- **Design gate** — Spec must be approved before moving to Tasks.
+- **Implementation gate** — Task list must be approved before implementation starts.
+
+Check gate status:
+
+```bash
+morph-spec approval-status {feature}
+```
+
+---
+
+## Slash commands
+
+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-status`             | Feature status dashboard                                  |
+| `/morph-preflight`          | Pre-implementation validation                             |
+
+
+---
+
+## CLI reference
+
+### Project management
+
+```bash
+morph-spec init                        # Initialize MORPH in current project
+morph-spec init --force                # Overwrite existing installation
+morph-spec update                      # Update framework files and re-analyze project
+morph-spec doctor                      # Check installation health
+morph-spec doctor --full               # Full health check (all file verifications)
+```
+
+### 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 task next {feature}         # Preview next task
+morph-spec status {feature}            # Feature status dashboard
+```
+
+### Validation
+
+```bash
+morph-spec validate                    # Run all validators
+morph-spec validate {validator}        # Run specific validator
+morph-spec validate-feature {feature}  # Content-aware feature validation
+```
+
+---
+
+## Agent hierarchy
+
+morph-spec includes 38 agents organized in 4 tiers (3+4+26+5). 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 (3)
+
+
+| Agent                 | Role                                                   | Active    |
+| --------------------- | ------------------------------------------------------ | --------- |
+| `standards-architect` | Chief Architect — enforces standards across all phases | Always    |
+| `ai-system-architect` | AI/Agent system design and orchestration               | On-demand |
+| `po-pm-advisor`       | Product and project advisory                           | On-demand |
+
+
+### Tier 2 — Domain Leaders (4)
+
+
+| Agent              | Squad                     | Active    |
+| ------------------ | ------------------------- | --------- |
+| `dotnet-senior`    | Backend squad lead        | Always    |
+| `infra-architect`  | Infrastructure squad lead | Always    |
+| `domain-architect` | DDD & domain modeling     | On-demand |
+| `ui-designer`      | UI/UX squad lead          | On-demand |
+
+
+### Tier 3 — Specialists (26)
+
+Organized into squads:
+
+**Backend (10):** C#/.NET specialists, EF Core, Dapper, SignalR, CQRS, Domain modeling, API design, Auth, Background services, Testing
+
+**Frontend (3):** Blazor components, Next.js/React, CSS/design system
+
+**Infrastructure (5):** Azure Bicep, CI/CD pipelines, Containerization, Monitoring, Cost optimization
+
+**Quality/Cross (8):** Security review, Performance, Accessibility, Documentation, Code review, Migration, Integration, Data modeling
+
+### Tier 4 — Validators (5)
+
+
+| Agent                          | Validates                               |
+| ------------------------------ | --------------------------------------- |
+| `security-expert`              | Security vulnerabilities and compliance |
+| `architecture-expert`          | Architectural decisions and constraints |
+| `packages-validator`           | Package versions and compatibility      |
+| `design-system-validator`      | Design system adherence                 |
+| `blazor-concurrency-validator` | Blazor thread safety and concurrency    |
+
+
+---
+
+## Hooks
+
+10 Claude Code hooks are installed into `.claude/settings.local.json` across 8 event types:
+
+
+| 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             |
+| `Notification`       | `approval-reminder.js`     | Reminds about pending approval gates                              |
+
+
+Protected files (via `permissions.deny`):
+
+- `.morph/state.json` — never edited directly, CLI only
+- `.morph/framework/`** — read-only framework content
+
+---
+
+## Rules
+
+Path-scoped rules are installed to `.claude/rules/` and activate automatically based on file patterns:
+
+
+| 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/**`         |
+
+
+---
+
+## Stack support
+
+
+| Technology                                  | Support                                          |
+| ------------------------------------------- | ------------------------------------------------ |
+| .NET 10 / ASP.NET Core                      | Full — C# contracts, EF Core, CQRS, Minimal API  |
+| Blazor (WebAssembly / Server / MAUI Hybrid) | Full — components, concurrency, design system    |
+| Next.js / React / TypeScript                | Full — components, routing, state management     |
+| Azure (Bicep)                               | Full — IaC templates, cost estimation, pipelines |
+| GitHub Actions                              | Full — CI/CD workflow templates                  |
+| Supabase                                    | Supported via MCP integration                    |
+
+
+TypeScript strict mode is enforced by default. See `.morph/framework/standards/` for all coding standards.
+
+---
+
+## Update
+
+To update the framework files in an existing project:
+
+```bash
+morph-spec update
+```
+
+This re-syncs `.morph/framework/`, `.claude/skills/`, `.claude/agents/`, `.claude/rules/`, and `CLAUDE.md` with the installed package version. Your `.morph/config/config.json`, `.morph/context/`, and feature outputs are not touched.
+
+After updating, run `morph-spec doctor` to confirm the installation is healthy.
+
+---
+
+## Key rules
+
+**Never skip phases.** Every feature starts with a proposal. No code is written until the design is approved and a task list exists.
+
+**Never edit protected files directly:**
+
+- `.morph/state.json` — use `morph-spec state set`
+- `.morph/framework/`** — read-only, updated by `morph-spec update`
+
+**Always document decisions.** Each feature has a `1-design/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.
+
+---
+
+## Troubleshooting
+
+### `morph-spec: command not found`
+
+If you are using nvm-windows or a Node version manager, the global bin path may not be on `PATH` in your shell. Use `npx` instead:
+
+```bash
+npx @polymorphism-tech/morph-spec init
+```
+
+Or add the npm global bin to your PATH:
+
+```bash
+npm config get prefix
+# Add {prefix}/bin to your PATH
+```
+
+### `morph-spec doctor` reports issues
+
+Run doctor to see all checks:
+
+```bash
+morph-spec doctor
+```
+
+Common fixes:
+
+- **Missing `.claude/agents/`** — run `morph-spec update` to reinstall agents
+- **Missing `.claude/rules/`** — run `morph-spec update` to reinstall rules
+- **State version mismatch** — state auto-migrates on next CLI command; if it fails, back up and re-init
+- **Hooks not firing** — confirm `.claude/settings.local.json` exists and contains the `hooks` key
+
+### EPERM on Windows global install
+
+Windows may block global npm installs without elevated permissions. Options:
+
+1. Run terminal as Administrator (not recommended long-term)
+2. Change npm global prefix to a user-writable directory:
+
+```bat
+mkdir %APPDATA%\npm-global
+npm config set prefix %APPDATA%\npm-global
+:: Add %APPDATA%\npm-global to your PATH
+npm install -g @polymorphism-tech/morph-spec
+```
+
+1. Use `npx` for all CLI invocations
+
+### Hook not triggering on SessionStart
+
+Ensure `.claude/settings.local.json` is not gitignored in your project. The file must be present for Claude Code to load hooks. If it is missing, re-run `morph-spec init --force`.
+
+---
+
+## 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`.
+
+---
+
+## License
+
+Proprietary — see [LICENSE](./LICENSE).
+
+Code generated by morph-spec (contracts, templates, implementation output) belongs to you.
+
+---
+
+*morph-spec v4.8.14 by [Polymorphism Tech](https://polymorphism.tech)*