@polymorphism-tech/morph-spec 4.7.2 → 4.8.4

package/docs/examples/order-management/spec.md

@@ -1,162 +0,0 @@
-# Feature Specification: Order Management
-
-| Field | Value |
-|-------|-------|
-| **ID** | order-management |
-| **Status** | Approved |
-| **Created** | 2026-02-23 |
-| **Stack** | .NET 10 / Blazor Server / EF Core |
-| **Complexity** | Medium |
-| **Agents** | Core: All / Specialists: domain-architect, ef-modeler, event-architect |
-
----
-
-## Overview
-
-**Problem:** Usuários precisam criar e gerenciar pedidos com rastreamento de status.
-
-**Solution:** Aggregate Order com factory method, invariants de estado, e Domain Events para notificações.
-
-**Success Criteria:**
-- [ ] Order CRUD com validações de negócio
-- [ ] Status tracking com transições controladas
-- [ ] Notificação ao confirmar pedido
-
----
-
-## Requirements
-
-**Functional:**
-FR001: Criar pedido com mínimo 1 item | FR002: Confirmar pedido (Draft → Confirmed) | FR003: Cancelar pedido (Draft/Confirmed → Cancelled) | FR004: Calcular total automaticamente
-
-**Non-Functional:**
-NFR001: Performance - operações < 200ms | NFR002: Consistência - invariants garantidas em toda operação
-
----
-
-## User Stories
-
-### US001: Criar Pedido
-**As** usuário autenticado **I want** criar um pedido com itens **so that** posso comprar produtos
-
-**Acceptance Criteria:**
-1. Pedido criado com status Draft
-2. Total calculado na criação
-
-**Edge Cases:** Lista de itens vazia → erro 400
-
----
-
-## Technical Design
-
-### Stack
-| Component | Technology |
-|-----------|------------|
-| Frontend | Blazor Server |
-| Backend | .NET 10 / C# 14 |
-| Database | Azure SQL / EF Core |
-
-### Data Model
-
-#### Order
-| Column | Type | Constraints |
-|--------|------|-------------|
-| Id | Guid | PK |
-| UserId | Guid | FK (reference by ID — cross-aggregate) |
-| Status | OrderStatus | Enum |
-| CreatedAt | datetime2 | Default: GETUTCDATE() |
-| UpdatedAt | datetime2 | Nullable |
-
-#### OrderItem (owned entity)
-| Column | Type | Constraints |
-|--------|------|-------------|
-| Id | Guid | PK |
-| OrderId | Guid | FK |
-| ProductId | Guid | Reference by ID |
-| Quantity | int | > 0 |
-| UnitPrice | decimal(18,2) | > 0 |
-
-### Contracts
-> **Ref:** `framework/templates/code/dotnet/contracts/contracts-level2.cs`
-
----
-
-## Domain Complexity
-
-**Nível:** 2 — Business Logic
-
-**Justificativa:** Order tem estados com transições controladas (Draft → Confirmed → Cancelled),
-invariants de negócio (não confirmar sem itens, não adicionar itens a pedido confirmado),
-cálculo derivado (Total), e outros módulos precisam reagir (NotificationService ao OrderConfirmed).
-
-**Padrões Aplicados:**
-- AggregateRoot com factory method estático
-- Value Objects: Money (UnitPrice, Total)
-- Domain Events: OrderCreatedEvent, OrderConfirmedEvent, OrderCancelledEvent
-- CQRS com MediatR
-
-**Padrões Omitidos:**
-- Bounded Contexts — sistema single-domain, desnecessário
-
----
-
-## Aggregate Blueprint (Nível 2+ apenas)
-
-### Aggregate Root: Order
-
-**Invariants:**
-- Order só pode ser Confirmado se Status == Draft E tiver pelo menos 1 item
-- Order Confirmado não pode receber mais itens (AddItem lança DomainException)
-- Order Cancelado não pode ser reativado (estado terminal)
-
-**Estados e Transições:**
-```
-{Draft} → Confirm() → {Confirmed}
-{Draft} → Cancel()  → {Cancelled}
-{Confirmed} → Cancel() → {Cancelled}
-```
-
-**Domain Events:**
-- `OrderCreatedEvent` — publicado ao criar (Create factory method)
-- `OrderConfirmedEvent` — publicado ao confirmar (Confirm method)
-- `OrderCancelledEvent` — publicado ao cancelar (Cancel method)
-
-**Value Objects:**
-- `Money` — UnitPrice e Total não são decimals simples: têm validação (> 0) e operações (Add, Multiply)
-
-**Referências Cross-Aggregate (por ID):**
-- `UserId: Guid` — nunca `User User { get; }`
-- `ProductId: Guid` em OrderItem — nunca `Product Product { get; }`
-
-### Linguagem Ubíqua
-
-| Termo | Definição | Código |
-|-------|-----------|--------|
-| Order | Pedido de compra de um usuário | `Order` (AggregateRoot) |
-| Draft | Pedido criado, ainda editável | `OrderStatus.Draft` |
-| Confirmed | Pedido submetido, não editável | `OrderStatus.Confirmed` |
-| Cancelled | Pedido cancelado, estado terminal | `OrderStatus.Cancelled` |
-| Confirm | Ato de finalizar e submeter um pedido | `Order.Confirm()` |
-| OrderItem | Linha de produto dentro de um pedido | `OrderItem` (Entity owned) |
-| Total | Soma calculada de todos os itens | `Order.Total` (property calculada) |
-
----
-
-## Flows
-
-### Confirmar Pedido
-**Trigger:** Usuário clica "Confirmar Pedido"
-1. Frontend → `POST /api/orders/{id}/confirm`
-2. API → `ConfirmOrderCommand(OrderId)`
-3. Handler → `repository.GetAsync(id)` → `order.Confirm()` → `repository.UpdateAsync(order)`
-4. `OrderConfirmedEvent` publicado → NotificationService envia email
-**End State:** Order.Status = Confirmed
-
----
-
-## Definition of Done
-- [ ] Aggregate implementado com todos os invariants
-- [ ] Domain Events publicados e consumidos
-- [ ] Testes unitários do Aggregate (sem EF)
-- [ ] Testes de integração do Handler
-- [ ] API endpoint documentado

package/docs/plans/2026-02-22-claude-docs-morph-alignment-analysis.md

@@ -1,512 +0,0 @@
-# Claude Code Native Alignment Analysis — Morph-Spec Framework
-
-**Date:** 2026-02-22
-**Source docs:** `code.claude.com/docs/en` (common-workflows, hooks-guide, sub-agents, skills, best-practices, settings)
-**Scope:** Architectural comparison, gap analysis, concrete improvement recommendations
-
----
-
-## 1. Executive Summary
-
-Morph-Spec has strong alignment in some areas (CLAUDE.md design, native `permissions.deny`, agents installer, rules files) but significant **over-engineering in three zones**: the hooks infrastructure, the skills/agents taxonomy, and the state machine's relationship to Claude Code's own session and permission mechanisms.
-
-The framework's core value — **spec-driven phase gating** — is real and irreplaceable by anything Claude Code provides natively. The problem is that the scaffolding around it uses complex custom Node.js infrastructure where simple YAML frontmatter or jq one-liners would suffice.
-
----
-
-## 2. Claude Code Native Features Reference
-
-The following features are **platform-native** and require zero custom code:
-
-| Feature | What CC provides | Location |
-|---|---|---|
-| **Skills** | SKILL.md files, `/slash-commands`, `$ARGUMENTS`, `context: fork`, scoped hooks, `allowed-tools`, `disable-model-invocation` | `.claude/skills/<name>/SKILL.md` |
-| **Subagents** | Markdown+frontmatter, automatic delegation, `tools`, `model`, `permissionMode`, `maxTurns`, `memory`, `isolation: worktree`, scoped hooks, preloaded skills | `.claude/agents/<name>.md` |
-| **Hooks** | 17 lifecycle events, `command`/`prompt`/`agent` types, matchers, exit-code control, JSON output for structured decisions, async execution | `settings.json` → `hooks` |
-| **Permissions** | `allow/deny/ask` rules with glob patterns, `defaultMode`, `additionalDirectories`, `disableBypassPermissionsMode` | `settings.json` → `permissions` |
-| **Memory / CLAUDE.md** | Multi-level CLAUDE.md (`~/.claude/`, `.claude/`, project root, subdirs), `@path/to/import` syntax | Any `CLAUDE.md` |
-| **Agent persistent memory** | `memory: user/project/local` in subagent frontmatter, auto-managed `MEMORY.md` per agent | `.claude/agent-memory/<name>/` |
-| **Plan Mode** | Read-only exploration before writing, `defaultMode: "plan"`, Shift+Tab toggle, `--permission-mode plan` | Platform |
-| **Worktrees** | `--worktree`, `isolation: worktree` in subagent frontmatter, auto-cleanup | Platform |
-| **Session management** | `--continue`, `--resume`, `/rename`, session picker, `--from-pr` | Platform |
-| **Statusline** | `statusLine.type: "command"` in `settings.json` | `settings.json` |
-| **Schema validation** | `$schema` in settings.json | `settings.json` |
-
-### Key design principles from CC docs:
-
-1. **Hooks are deterministic; CLAUDE.md is advisory** — hooks guarantee enforcement; instructions are guidance
-2. **Skills are context-loaded knowledge; subagents are isolated executors** — different tools for different jobs
-3. **CLAUDE.md should be short** — only things Claude can't infer; bloated CLAUDE.md is ignored
-4. **Subagent description drives delegation** — no manual "tier" system needed; Claude matches by description
-5. **Persistent agent memory** (`memory: project`) replaces custom context persistence
-6. **Skill `context: fork`** runs skills in isolation — subagents aren't always needed
-7. **`prompt`/`agent` hook types** — CC supports LLM-evaluated hooks natively; no custom prompt engineering needed
-8. **`allowed-tools` in skill frontmatter** — scoped permission for skill duration, no custom validation
-
----
-
-## 3. Morph-Spec Architecture vs CC Native: Feature-by-Feature
-
-### 3.1 Skills System
-
-**Current:**
-```
-framework/skills/
-  level-0-meta/         → 6 skills (brainstorming, code-review, etc.)
-  level-1-workflows/    → 8 skills (phase-proposal, phase-design, etc.)
-  level-2-domains/      → 22 skills (blazor-builder, azure-architect, etc.)
-  level-3-technologies/ → NOT installed
-  level-4-patterns/     → NOT installed
-```
-`skills-installer.js` copies level-0 + level-1 **FLAT** to `.claude/skills/` (no subdirectories, no supporting files).
-
-**Assessment:**
-
-| Aspect | Status | Issue |
-|---|---|---|
-| YAML frontmatter with `name` + `description` | ✅ Aligned | — |
-| `/slash-command` invocation | ✅ Aligned | — |
-| Level hierarchy (0–4) | ⚠️ Overhead | CC uses flat dirs + description matching — levels add no CC value |
-| Levels 2–4 never installed | ❌ Dead code | 22+ domain skills built but never deployed to users |
-| Installed FLAT (no dirs) | ⚠️ Limitation | No supporting files possible; `context: fork`, `allowed-tools`, `hooks` frontmatter unused |
-| level-2-domains as skills | ⚠️ Wrong type | Domain specialists (blazor-builder, azure-architect) are **subagents**, not skills — they need isolated execution, tool access, and persistent memory |
-
-**What's missing from skills:**
-- No `context: fork` + `agent:` for isolated phase execution
-- No `$ARGUMENTS` in phase workflow skills (could pass feature name)
-- No `allowed-tools` scoping per skill
-- No `hooks:` frontmatter for skill-scoped lifecycle events
-- No `memory:` for persistent skill context
-- No `disable-model-invocation: true` on dangerous phase skills (e.g. `phase-implement`)
-
----
-
-### 3.2 Agents System
-
-**Current:**
-- `framework/agents.json` — 37 agents in 4 tiers, custom JSON format
-- `agents-installer.js` transpiles tier-1/2 agents to `.claude/agents/morph-{id}.md`
-- Tiers 3–4 (Specialists + Validators) are NOT installed as agents
-
-**Assessment:**
-
-| Aspect | Status | Issue |
-|---|---|---|
-| Agents installed to `.claude/agents/` | ✅ Aligned | — |
-| YAML frontmatter + description | ✅ Aligned | — |
-| Tier 1/2 as agents | ✅ Reasonable | These are orchestrators/leaders — appropriate as persistent subagents |
-| Tier 3/4 NOT installed | ❌ Dead code | 31 specialists built but unused by CC native delegation |
-| Custom 4-tier taxonomy | ⚠️ Overhead | CC delegates by description alone — tiers are an organizational concept with no runtime effect |
-| `agents.json` → `.md` transpilation | ⚠️ Adapter complexity | Extra build step; agents could be authored directly as `.md` files |
-| No `memory: project` in agents | ❌ Gap | Agents lose context between sessions; CC provides this natively |
-| No `isolation: worktree` for parallel work | ❌ Gap | Parallel agent execution doesn't use CC's native worktree isolation |
-| No `skills` preloading in agent frontmatter | ❌ Gap | Agents could have domain standards pre-injected from standards library |
-| No `maxTurns` guard | ❌ Gap | Runaway agents not bounded |
-
----
-
-### 3.3 Hooks System
-
-**Current:**
-```
-framework/hooks/
-  shared/           → 4 Node.js modules (state-reader, hook-response, stdin-reader, phase-utils)
-  claude-code/
-    session-start/inject-morph-context.js
-    user-prompt/enrich-prompt.js
-    pre-tool-use/protect-readonly-files.js  (deprecated — replaced by permissions.deny)
-    pre-tool-use/protect-spec-files.js
-    pre-tool-use/enforce-phase-writes.js
-    pre-tool-use/validate-bash-commands.js
-    post-tool-use/dispatch.js
-    post-tool-use/track-output-creation.js
-    post-tool-use/handle-tool-failure.js
-    pre-compact/save-morph-context.js
-    stop/validate-completion.js
-    notification/approval-reminder.js
-```
-
-**Assessment:**
-
-| Hook | Value | Issue |
-|---|---|---|
-| `inject-morph-context.js` | ✅ High — state summary is unique | Partially overlaps with CLAUDE.md `@.morph/context/README.md` import; could be a `prompt`-type hook for lighter weight |
-| `enrich-prompt.js` | ⚠️ Medium | User prompt enrichment is potentially noisy; a `UserPromptSubmit` hook with `additionalContext` is correct CC pattern |
-| `protect-readonly-files.js` | ❌ DEAD — replaced by `permissions.deny` | Remove from installer |
-| `protect-spec-files.js` | ✅ Legitimate — approval gate logic | Cannot be replaced by static `permissions.deny`; keep |
-| `enforce-phase-writes.js` | ✅ High value — phase enforcement | Core morph-spec logic; irreplaceable |
-| `validate-bash-commands.js` | ⚠️ Medium | Could use CC's `PreToolUse` with `prompt` type hook instead of custom Node.js |
-| `track-output-creation.js` | ✅ Unique — state sync | Essential morph-specific; direct JSON I/O is correct |
-| `dispatch.js` | ❌ Unclear | PostToolUse dispatcher — unclear what it dispatches beyond existing hooks |
-| `handle-tool-failure.js` | ✅ Reasonable | Failure logging; CC's `PostToolUseFailure` is the right event |
-| `save-morph-context.js` | ✅ Reasonable | Pre-compact state preservation; CC's `PreCompact` with `compact` matcher |
-| `validate-completion.js` | ⚠️ Complexity | Stop-hook completion validation; could be `agent`-type hook with tool access |
-| `approval-reminder.js` | ⚠️ Low value | Notification hook for approval reminders; CLAUDE.md + phase skill is sufficient |
-| **4 shared Node.js modules** | ❌ Over-engineering | Complex infrastructure for what CC recommends as bash/jq scripts; ESM imports add startup overhead |
-
-**The fundamental problem with the hooks architecture:**
-
-CC recommends hooks as simple shell commands with `jq` for JSON parsing. Morph-spec has built a custom Node.js framework *around* the hooks with shared utilities, ESM modules, and an internal API (`block()`, `pass()`, `injectContext()`). This:
-- Adds ~100ms+ startup overhead per hook invocation (Node.js + ESM)
-- Creates a custom abstraction layer that masks what's happening from the hooks documentation
-- Makes it hard for users to understand and modify hooks
-- Caused the circular bug in `track-output-creation.js` (importing state-manager → subprocess)
-
----
-
-### 3.4 State Machine vs CC Native Capabilities
-
-**Current morph-spec state concepts:**
-
-| Morph concept | CC native equivalent | Gap |
-|---|---|---|
-| Phase system (proposal→implement) | No direct equivalent | **Unique value** — keep |
-| Phase approval gates | CC's `PreToolUse` hook + `block()` | **Unique value** — morph's approval gates are richer |
-| Trust scoring (low/medium/high/maximum) | `permissions.defaultMode` (acceptEdits/askAll/plan) | **Duplication** — trust levels could map directly to CC permission modes |
-| Task tracking (total/completed) | CC's `TaskCreate/TaskUpdate` (internal) | Partial overlap |
-| Checkpoints (save/restore) | CC's native `/rewind` + checkpointing | **Significant overlap** — morph's checkpoint commands duplicate CC's built-in checkpointing |
-| Feature session naming | CC's `/rename` + `--resume session-name` | **Duplication** — morph could use CC sessions as feature sessions |
-| LLM workflow-detector | Plan Mode + user choice | Over-engineering |
-
----
-
-### 3.5 Standards System
-
-**Current:**
-- 74 standards in `framework/standards/` organized in 11 categories
-- `STANDARDS.json` registry with `name/id/category/tags/path`
-- `morph-spec standards --list/--search/--show` CLI commands
-- Scripts: `generate-standards-registry.js`
-
-**Assessment:**
-
-Standards are **domain knowledge** — exactly what CC skills are for. The current system implements a searchable registry with a CLI, but CC provides this through:
-- Skill `description` field → automatic loading when relevant
-- `/skill-name` for direct invocation
-- Skill `user-invocable: false` for background knowledge (no slash command)
-
-A standard like `csharp-standards.md` would be better as:
-```yaml
----
-name: csharp-standards
-description: C# coding standards for this project. Loaded automatically when working on .cs or .csproj files.
-user-invocable: false
----
-```
-
-With `paths:` scoping (via the morph `rules/` system), this is nearly identical to what morph-spec is doing manually.
-
-The CLI registry (`--list/--search/--show`) is custom tooling for what `/agents` + skill descriptions already provide natively.
-
----
-
-### 3.6 What `.claude/rules/` Actually Is
-
-**Finding:** The `.claude/rules/` directory with path-scoped rule files is **not a native Claude Code feature** in the official documentation. The CC docs only describe:
-- `CLAUDE.md` at various directory levels (auto-loaded)
-- `.claude/settings.json` for permissions/hooks
-- `.claude/skills/` and `.claude/agents/` for extensions
-
-The morph-spec `rules/` system appears to be either:
-1. A **CC experimental/preview feature** not yet in stable docs
-2. A **morph-spec custom convention** that isn't actually parsed by Claude Code natively
-
-If it's the latter, the path-scoped rules (csharp-standards.md with `paths: ["**/*.cs"]`) are written to `.claude/rules/` but have no enforcement mechanism — they'd be documentation-only. The correct CC-native alternative is **skills with `user-invocable: false`** loaded when relevant files are detected.
-
-**Recommendation:** Verify whether `.claude/rules/` is a CC native feature. If not, migrate rules to skills with appropriate descriptions or `paths`-aware CLAUDE.md imports.
-
----
-
-## 4. What Morph-Spec Does Right
-
-These are **genuinely aligned or uniquely valuable**:
-
-1. **`enforce-phase-writes.js` hook** — phase-gated write enforcement is unique, irreplaceable, and correctly implemented as a `PreToolUse` hook
-2. **`track-output-creation.js`** — auto-tracking spec outputs to state.json; the direct JSON I/O approach is correct
-3. **`protect-spec-files.js`** — approval-gate-aware file protection; cannot be replaced by static `permissions.deny`
-4. **`permissions.deny` for framework readonly** — replacing the old hook with native settings; excellent alignment
-5. **CLAUDE.md with `@.morph/context/README.md` import** — using CC's `@` import syntax correctly
-6. **`.claude/CLAUDE.md` runtime reference** — project-level CLAUDE.md for quick reference; correct pattern
-7. **Skills with YAML frontmatter** — proper `name` + `description` in all skill files
-8. **Phase system itself** — the 8-phase spec-driven workflow is unique value with no CC equivalent
-9. **`statusline.py` → `settings.json` statusLine** — using CC's native statusline mechanism correctly
-10. **`update-agents` command** — keeping agents in sync is a good maintenance pattern
-
----
-
-## 5. What Should Be Simplified
-
-### 5.1 Collapse the skills level hierarchy
-
-**Current:** 5 levels (0–4), only levels 0–1 installed, installed flat
-**Should be:** Two categories, installed as proper directories with supporting files
-
-```
-framework/skills/
-  meta/          → brainstorming, code-review, verification (level-0 content)
-  workflows/     → phase-proposal, phase-design, phase-implement, etc. (level-1 content)
-```
-
-Benefits:
-- Skills installed as directories → supporting files possible → richer skills
-- `context: fork` can be added to phase-implement for isolated execution
-- `$ARGUMENTS` can be used: `/phase-design my-feature`
-- `allowed-tools` can gate what each phase can do
-- `disable-model-invocation: true` on implementation phases (don't auto-trigger)
-
-### 5.2 Convert domain skills (level-2) to proper subagents
-
-**Current:** `framework/skills/level-2-domains/` — 22 domain skill files never installed
-**Should be:** Proper `.claude/agents/` files with `memory: project`
-
-Example:
-```markdown
----
-name: blazor-builder
-description: Blazor/.NET frontend specialist. Use proactively when working on .razor files, Blazor components, or MudBlazor UI.
-tools: Read, Edit, Write, Bash, Grep, Glob
-model: sonnet
-memory: project
-skills:
-  - csharp-standards
-  - frontend-standards
----
-
-You are a senior Blazor/.NET developer...
-```
-
-This gives domain specialists:
-- Persistent project memory across sessions
-- Pre-loaded standards
-- Proper tool access control
-- CC's automatic delegation by description (no tier system needed)
-
-### 5.3 Reduce the hooks Node.js framework to targeted scripts
-
-The `shared/` modules are well-written but add unnecessary complexity. For the hooks that remain, prefer the CC-recommended pattern:
-
-**Instead of:**
-```js
-import { readStdin } from '../../shared/stdin-reader.js';
-import { block, pass } from '../../shared/hook-response.js';
-```
-
-**Use inline bash/jq:**
-```bash
-#!/bin/bash
-INPUT=$(cat)
-FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
-# ... logic ...
-echo "reason" >&2; exit 2  # block
-exit 0                      # pass
-```
-
-Or for LLM-evaluated validation, use CC's native `type: "prompt"` hook.
-
-### 5.4 Map trust scoring to CC permission modes
-
-**Current:** Internal trust levels (low/medium/high/maximum) control auto-approval behavior
-**Should be:** Map directly to CC's `permissions.defaultMode` in generated `settings.json`
-
-| Morph trust level | CC `defaultMode` |
-|---|---|
-| low | `askAll` (ask for everything) |
-| medium | `default` (standard prompting) |
-| high | `acceptEdits` (auto-accept file edits) |
-| maximum | `bypassPermissions` (skip all checks — use carefully) |
-
-This eliminates the custom trust scoring machinery and makes the user's experience consistent with how CC presents permission modes.
-
-### 5.5 Simplify workflow configs
-
-**Current:** 10 workflow configs (fast-track, standard, full-morph, design-impl, ui-refresh, express, spec-only, zero-touch, fusion, ...)
-**Should be:** 3–4 that map to clearly different phase sequences
-
-The distinction between "fast-track" and "express" or "zero-touch" is subtle enough to confuse users. More workflows = more surface area for the LLM workflow-detector to get wrong. The workflow-detector's LLM call adds latency for a decision the user could make with a simple prompt.
-
----
-
-## 6. What Should Be Removed or Deprecated
-
-| Item | Reason | Alternative |
-|---|---|---|
-| `protect-readonly-files.js` hook | Already replaced by `permissions.deny` | Already done — remove from installer |
-| Hooks `shared/` Node.js modules | Over-engineered for bash/jq use cases | Inline bash or `type: "prompt"` CC hook |
-| Skills "level" naming convention | CC has no tier concept; levels 2–4 never installed | Rename to `meta/` + `workflows/` |
-| `STANDARDS.json` registry + `generate-standards-registry.js` | CLI for what CC skill descriptions provide | Migrate standards to skills; `/` menu is the registry |
-| `morph-spec standards --list/--search/--show` commands | Replaced by CC's native skill discovery | Remove (3 CLI commands) |
-| LLM-powered `workflow-detector.js` | Latency + complexity for a user decision | Ask via `AskUserQuestion` or Plan Mode |
-| Trust scoring system | Maps to existing CC permission modes | Write directly to `settings.json` `defaultMode` |
-| `dispatch.js` (PostToolUse dispatcher) | Unclear value beyond what hooks already provide | Evaluate and likely remove |
-| `approval-reminder.js` (notification hook) | CLAUDE.md + phase workflow covers this | Remove |
-| 10 workflow configs → simplify to ≤4 | Cognitive overhead, LLM detection errors | Merge similar workflows |
-| `morph-spec checkpoint-save/restore/list` commands | CC has native `/rewind` + checkpointing | Deprecate; document CC's native commands |
-
----
-
-## 7. How to Make Morph-Spec Truly Spec-Driven
-
-The core promise of "spec-driven development" means the **spec file is the source of truth** for all phases. Currently, the spec exists at `.morph/features/{feature}/1-design/spec.md` but Claude has to be told to read it — there's no automatic loading mechanism.
-
-### 7.1 Auto-load the active feature spec into every session
-
-Use CC's `@` import syntax in `framework/CLAUDE.md` with a dynamic reference:
-
-```markdown
-## Active Feature Spec
-
-The current feature spec is loaded from state:
-
-@.morph/features/__active__/1-design/spec.md
-```
-
-Problem: CC's `@` syntax uses static paths. But the `inject-morph-context.js` hook already injects state summary. **Extend it** to also include the spec content for the active feature using `additionalContext`. This makes the spec always visible without the user needing to reference it explicitly.
-
-### 7.2 Use `context: fork` in phase skills
-
-Phase skills should run in isolated contexts so the implementation gets a clean view:
-
-```yaml
----
-name: phase-implement
-description: Execute the implementation phase for a morph-spec feature
-context: fork
-agent: general-purpose
-disable-model-invocation: true
-allowed-tools: Read, Edit, Write, Bash, Grep, Glob
----
-
-Implement feature $ARGUMENTS according to its spec.
-
-## Context loading
-1. Read: .morph/features/$ARGUMENTS/1-design/spec.md
-2. Read: .morph/features/$ARGUMENTS/3-tasks/tasks.md
-3. Read: .morph/config/config.json
-
-## Implementation rules
-- One task at a time
-- Checkpoint every 3 tasks via: morph-spec checkpoint-save $ARGUMENTS
-- Mark outputs: morph-spec mark-output $ARGUMENTS recap
-```
-
-### 7.3 Enforce spec existence before implementation
-
-Replace the complex `validate-completion.js` Stop hook with a targeted `PreToolUse` check:
-
-```json
-{
-  "hooks": {
-    "Stop": [{
-      "hooks": [{
-        "type": "prompt",
-        "prompt": "Check if the active morph-spec feature has completed required outputs for its phase. Read .morph/state.json. If required outputs are missing, respond {\"ok\": false, \"reason\": \"Missing: <output> at <path>\"}"
-      }]
-    }]
-  }
-}
-```
-
-This uses CC's native `type: "prompt"` hook instead of a custom Node.js validation chain.
-
-### 7.4 Use agent `memory: project` for standards enforcement
-
-Domain specialist agents should accumulate project-specific pattern knowledge:
-
-```markdown
----
-name: morph-csharp-specialist
-memory: project
-skills:
-  - csharp-standards
----
-
-Maintain your project memory with:
-- Naming conventions discovered in this codebase
-- Architecture patterns in use
-- Known anti-patterns to avoid
-- Decision log entries from .morph/features/*/1-design/decisions.md
-```
-
----
-
-## 8. How to Implement Native Enforcement and Validations
-
-### 8.1 Permission rules as the first enforcement layer
-
-Replace custom validation hooks where possible with `settings.json` rules:
-
-```json
-{
-  "permissions": {
-    "deny": [
-      "Write(.morph/state.json)",
-      "Edit(.morph/state.json)",
-      "Write(.morph/framework/**)",
-      "Edit(.morph/framework/**)",
-      "Bash(rm -rf .morph/**)"
-    ]
-  }
-}
-```
-
-Already implemented for state.json and framework/ — extend to cover other dangerous patterns.
-
-### 8.2 Phase enforcement as the second layer (keep `enforce-phase-writes.js`)
-
-This hook provides logic that `permissions.deny` cannot (it reads dynamic state). Keep it, but:
-- Convert from Node.js ESM to a Python or bash script (lighter startup)
-- Or use CC's `type: "agent"` hook for complex validation (CC manages the LLM call)
-
-### 8.3 Approval gates as the third layer (keep `protect-spec-files.js`)
-
-Keep as-is — this is unique domain logic. But convert to bash/jq for lighter execution.
-
-### 8.4 Completion validation as a `type: "prompt"` hook (replace `validate-completion.js`)
-
-The Stop hook that validates all required outputs are created before Claude can stop is important but currently implemented in complex Node.js. Replace with a CC native `type: "prompt"` hook that reads state.json and checks completion.
-
----
-
-## 9. Concrete Action Items (Prioritized)
-
-### High Priority — Remove dead code, align native features
-
-1. **Remove `protect-readonly-files.js` from hooks installer** — already replaced, still installed
-2. **Remove `dispatch.js` and `approval-reminder.js`** — low value hooks
-3. **Convert `validate-bash-commands.js` to `type: "prompt"` hook** — use CC native LLM evaluation
-4. **Add `$ARGUMENTS` to all phase workflow skills** — enable `/phase-design my-feature` invocation
-5. **Add `disable-model-invocation: true` to `phase-implement` and `phase-tasks`** — prevent accidental trigger
-6. **Install level-2-domains skills as subagents** (`.claude/agents/morph-blazor-builder.md`, etc.) with `memory: project`
-
-### Medium Priority — Reduce infrastructure complexity
-
-7. **Convert hooks shared modules to inline bash/jq scripts** — remove `shared/` layer
-8. **Map trust scoring directly to `settings.json` `defaultMode`** — eliminate custom trust machinery
-9. **Migrate standards from CLI registry to skills** with `user-invocable: false` descriptions
-10. **Remove `morph-spec standards` CLI commands** (3 commands, replace with skill search)
-11. **Add active feature spec to `inject-morph-context.js` payload** — truly spec-driven context
-
-### Low Priority — Architecture improvements
-
-12. **Rename skill levels to `meta/` + `workflows/`** — better reflects purpose, removes false hierarchy
-13. **Add `memory: project` to all domain specialist agents** — persistent cross-session learning
-14. **Verify `.claude/rules/` native support** — if not native, migrate to skills with `user-invocable: false`
-15. **Reduce workflow configs from 10 to ≤4** — simplify LLM detection surface
-16. **Replace `workflow-detector.js` LLM call with user question** — use `AskUserQuestion` in phase-setup skill
-
----
-
-## 10. Summary Assessment
-
-| Area | Current State | Target State |
-|---|---|---|
-| Skills | 2-level deployment, flat, missing CC features | 2-category dirs, `$ARGUMENTS`, `context: fork`, `disable-model-invocation` |
-| Agents | Tier 1+2 only, no `memory`, no `isolation` | All domain specialists as agents with `memory: project` + `skills` preload |
-| Hooks | Node.js ESM framework, 12 hooks, 4 shared modules | Bash/jq or `type: "prompt"` hooks, 7 core hooks, no shared modules |
-| Permissions | `permissions.deny` for state+framework | Extended deny rules + mapped `defaultMode` from trust levels |
-| Standards | CLI registry + 74 standards | Skills with `user-invocable: false` + path descriptions |
-| State machine | Full phase gating + trust scoring + LLM detection | Keep phase gating, simplify trust → CC modes, remove LLM detection |
-| Spec-driven | Spec exists but not auto-loaded | Spec auto-injected via SessionStart hook additionalContext |
-| Dead code | 31 agents never installed, 22 skills never deployed, 10 workflows | Remove or deploy everything that's built |
-
-The framework's **unique value** is the spec-driven phase workflow with approval gates, phase-write enforcement, and output tracking. All of this should be preserved and sharpened. The infrastructure around it should be dramatically simplified by leaning on what Claude Code provides natively.