npm - @polymorphism-tech/morph-spec - Versions diffs - 4.7.2 → 4.8.1 - Mend

@polymorphism-tech/morph-spec 4.7.2 → 4.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (346) hide show

package/README.md CHANGED Viewed

@@ -1,414 +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.7.2
-**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
-```
-Or use the interactive wizard:
-```bash
-morph-spec init --wizard
-```
-### Init options
-| Flag               | Description                               |
-| ------------------ | ----------------------------------------- |
-| `--wizard`         | Interactive step-by-step setup            |
-| `--skip-detection` | Skip auto-detection of stack and patterns |
-| `--force`          | Overwrite existing installation           |
-| `--skip-mcp`       | Skip MCP configuration prompt             |
-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              # 37 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 (37 agents)
-    ├── rules/                       # Path-scoped standards rules
-    └── settings.local.json          # Hooks configuration (11 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 state show {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 --wizard               # Interactive wizard setup
-morph-spec init --skip-detection       # Skip stack auto-detection
-morph-spec init --force                # Overwrite existing installation
-morph-spec update                      # Update framework files and re-analyze project
-morph-spec update --wizard             # Interactive update
-morph-spec update --skip-detection     # Skip detection during update
-morph-spec update --templates          # Update templates only
-morph-spec update --standards          # Update standards only
-morph-spec doctor                      # Check installation health
-morph-spec detect                      # Detect stack, architecture, patterns
-```
-### 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 state show {feature}        # Show phase + approval status
-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
-morph-spec diff {feature}              # Spec changes since last snapshot
-morph-spec rollback {feature}          # Rollback feature to previous phase
-```
-### Validation and standards
-```bash
-morph-spec validate                    # Run all validators
-morph-spec validate {validator}        # Run specific validator
-morph-spec standards --list            # List all 74 registered standards
-morph-spec standards --list --category {name}
-morph-spec standards --search {query}  # Search by name, tag, or ID
-morph-spec standards --show {id}       # Print standard content
-morph-spec standards --json            # Output as JSON
-```
-### Utilities
-```bash
-morph-spec cost {bicep-file}           # Estimate Azure resource costs
-morph-spec troubleshoot {keywords}     # Search known issues and solutions
-morph-spec state checkpoint {feature}  # Save state checkpoint
-```
----
-## Agent hierarchy
-morph-spec includes 37 agents organized in 4 tiers. 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 (3)
-| Agent             | Squad                     | Active    |
-| ----------------- | ------------------------- | --------- |
-| `dotnet-senior`   | Backend squad lead        | Always    |
-| `azure-architect` | Infrastructure squad lead | Always    |
-| `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
-11 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 (3000 char max) |
-| `UserPromptSubmit`   | `protect-spec-files.js`     | Guards spec files at approval gates                      |
-| `PreToolUse`         | Bash guard (prompt type)    | Detects destructive patterns inline                      |
-| `PreToolUse`         | `validate-feature-phase.js` | Validates phase transitions                              |
-| `PostToolUse`        | `track-output-creation.js`  | Tracks feature output files as they are written          |
-| `PostToolUse`        | `checkpoint-trigger.js`     | Auto-checkpoints every 3 completed tasks                 |
-| `PostToolUseFailure` | `handle-tool-failure.js`    | Logs failures to `.morph/logs/tool-failures.log`         |
-| `Stop`               | `session-summary.js`        | Writes session summary on stop                           |
-| `PreCompact`         | `compact-context.js`        | Preserves critical context before compaction             |
-| `Notification`       | `morph-notify.js`           | Routes approval gate notifications                       |
-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`, `**/*.tsx`, `**/*.ts`, `**/*.css`          |
-| `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 registry
-The framework ships 74 registered standards across 11 categories. Browse them:
-```bash
-morph-spec standards --list
-morph-spec standards --list --category csharp
-morph-spec standards --search "strict mode"
-morph-spec standards --show typescript-strict
-```
-Standards are stored in `.morph/framework/standards/STANDARDS.json` and sourced from `.morph/framework/standards/`.
----
-## License
-Proprietary — see [LICENSE](./LICENSE).
-Code generated by morph-spec (contracts, templates, implementation output) belongs to you.
----
-*morph-spec v4.7.0 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.1
+**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.1 by [Polymorphism Tech](https://polymorphism.tech)*