@polymorphism-tech/morph-spec 4.3.6 → 4.5.0

package/docs/claude-alignment-report.md

@@ -0,0 +1,137 @@
+# Claude Code Native Alignment Report — Round 2
+
+> **Date:** 2026-02-22
+> **Status:** Implemented
+> **Scope:** Memory/rules layer — building on Round 1 (commit 8c806c2)
+
+---
+
+## Summary
+
+Round 2 of Claude Code native alignment identifies and adopts two native patterns from the official Claude Code memory documentation that were missed in Round 1:
+
+1. **`.claude/rules/*.md`** — Path-scoped, auto-loading instruction files
+2. **`@import` in CLAUDE.md** — Auto-import external files into session context
+
+---
+
+## Native Patterns Now Adopted
+
+### 1. Path-Scoped Rules (`.claude/rules/`)
+
+**What it is:** Claude Code natively supports modular instruction files placed in `.claude/rules/`. Files without `paths:` frontmatter apply globally; files with `paths:` frontmatter auto-load only when Claude is working with matching files.
+
+**What we implemented:**
+
+| File | Scope | Paths |
+|------|-------|-------|
+| `morph-workflow.md` | Always active | (none — global) |
+| `csharp-standards.md` | C# files | `**/*.cs`, `**/*.csproj` |
+| `frontend-standards.md` | Blazor/TS/CSS | `**/*.razor`, `**/*.tsx`, `**/*.ts`, `**/*.css` |
+| `testing-standards.md` | Test files | `tests/**`, `**/*.test.*`, `**/*.spec.*`, `**/*Tests.cs` |
+| `infrastructure-standards.md` | Infra files | `**/*.bicep`, `**/Dockerfile`, `**/pipelines/**` |
+
+**Source material:** Distilled from `framework/standards/` (core/coding.md, backend/dotnet/core.md, core/testing.md, frontend/blazor/pitfalls.md, infrastructure/azure/azure.md, frontend/nextjs/nextjs-patterns.md).
+
+**Why it matters:** Previously, standards were buried in `.morph/framework/standards/` — Claude had to navigate deep paths to access them, and they were never automatically loaded. Path-scoped rules ensure Claude sees the right standards *automatically* when working on the right files, without any manual intervention.
+
+**Installation:** `morph-spec init` copies `framework/rules/` → `.claude/rules/` (step 9a in `initCommand()`).
+
+### 2. `@import` in CLAUDE.md
+
+**What it is:** Claude Code supports `@path/to/file` syntax inside CLAUDE.md to auto-import external files into the session context at startup.
+
+**What we implemented:** Added `@.morph/context/README.md` to `framework/CLAUDE.md`:
+
+```markdown
+## PROJECT CONTEXT
+
+@.morph/context/README.md
+```
+
+**Why it matters:** Previously, `framework/CLAUDE.md` referenced `.morph/context/README.md` only in text (e.g., "run `morph-spec detect` to see your stack"). The file was never actually loaded. Now, every Claude Code session in a user project automatically starts with the project context (stack, architecture, technologies) pre-loaded — no manual reading required.
+
+---
+
+## What Remains Over-Engineered
+
+### Partially Redundant: Session Context Injection vs Auto Memory
+
+The `UserPromptSubmit` hook injects context into every session. This overlaps with:
+- Auto memory (`~/.claude/projects/.../memory/`) — Claude Code's native persistent context layer
+- The new `@import` in CLAUDE.md — project context auto-loaded at startup
+
+**Verdict:** Keep the hook for now. It handles dynamic state (current feature, active phase) that auto memory doesn't cover. Revisit in Round 3 — the hook may be reducible to only inject feature-specific state, not static project context.
+
+### Level 3–4 Skills Rarely Used
+
+`framework/skills/level-3-technologies/` and `level-4-patterns/` contain 30+ files that are rarely invoked. They're installed to `.claude/skills/` via symlinks/copies during init.
+
+**Verdict:** Keep for now — they're passive (loaded on-demand via `/skill-name`). Consider documenting them as "on-demand only" in the `morph-workflow.md` rule. Long-term, Level 3–4 could be removed from auto-install and accessed directly from `framework/skills/` when needed.
+
+### 37 Agents in `agents.json`
+
+The agent system has 37 agents across 4 tiers. For most projects, only 5–8 agents are active at any given time.
+
+**Verdict:** Acceptable complexity. Agents drive spawn prompts and workflow orchestration — they can't be replaced by documentation. The activation-by-keyword system (Tier 3) already limits unnecessary activation.
+
+---
+
+## What Was Intentionally Kept (Justified)
+
+| Feature | Justification |
+|---------|--------------|
+| `state.json` + state machine | Claude Code has no native feature-tracking equivalent; phase enforcement requires runtime state |
+| `protect-spec-files.js` hook | Dynamically checks approval gate state before allowing spec file edits — cannot be replaced by static `permissions.deny` |
+| All 12 Claude Code hooks | Context injection (dynamic), output tracking (direct JSON I/O), tool failure logging all provide value beyond native capabilities |
+| `.morph/framework/standards/` | Deep reference library for agents; the rules layer distills it but doesn't replace it |
+| `permissions.deny` for state.json + framework | Already replaced `protect-readonly-files.js` hook in Round 1 — this is the right native approach |
+| Skills hierarchy (Level 0–2) | Level 0 (meta), Level 1 (phase workflows), Level 2 (domains) are actively invoked via `/skill-name` syntax |
+
+---
+
+## Roadmap: Round 3 Candidates
+
+In priority order:
+
+1. **Session context hook reduction** — Trim `UserPromptSubmit` hook to inject only feature-specific dynamic state, relying on `@import` + rules for static context. Reduces hook complexity.
+
+2. **Level 3–4 skill audit** — Measure actual usage frequency. If consistently low, move these to a "pull-on-demand" model (reference from framework, not installed to `.claude/skills/`).
+
+3. **`morph-workflow.md` rule enhancement** — Add current workflow/phase detection so the always-active rule provides live feature status context (currently requires `morph-spec status` command).
+
+4. **User-level rules layer (`~/.claude/rules/`)** — A potential personal workflow preferences file for Polymorphism Tech developers (e.g., preferred stack defaults, commit message style). Not currently used.
+
+5. **Rules auto-update on `morph-spec update`** — Currently rules are only installed during `init`. The `update` command should sync `.claude/rules/` when framework rules change.
+
+---
+
+## Files Changed in Round 2
+
+| Action | File |
+|--------|------|
+| Created | `framework/rules/morph-workflow.md` |
+| Created | `framework/rules/csharp-standards.md` |
+| Created | `framework/rules/frontend-standards.md` |
+| Created | `framework/rules/testing-standards.md` |
+| Created | `framework/rules/infrastructure-standards.md` |
+| Updated | `framework/CLAUDE.md` — added `@.morph/context/README.md` import |
+| Updated | `src/commands/project/init.js` — added step 9a: rules copy to `.claude/rules/` |
+| Created | `docs/claude-alignment-report.md` (this file) |
+
+---
+
+## Round 1 Reference (commit 8c806c2)
+
+Round 1 implemented 7 tasks:
+1. Fixed circular hook bug in `track-output-creation.js`
+2. Native `permissions.deny` replaced `protect-readonly-files.js`
+3. Skills installed to `.claude/skills/` (flat, with symlinks on non-Windows)
+4. Global statusline installed to `~/.claude/`
+5. `PostToolUseFailure` hook: `handle-tool-failure.js`
+6. Standards registry: `framework/standards/STANDARDS.json` (74 entries)
+7. `framework/phases.json` — canonical phase definitions
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

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

@@ -0,0 +1,512 @@
+# 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.