@polymorphism-tech/morph-spec 4.7.2 → 4.8.1

package/docs/plans/2026-02-24-framework-failure-points.md

@@ -0,0 +1,125 @@
+# Framework Failure Points — Implementation Plan
+
+**Status:** COMPLETE
+
+> Created: 2026-02-24
+> Status: In progress (detect-agents fix already merged)
+
+---
+
+## Already Done
+
+- **#1 detect-agents ghost command** — Fixed in commit `9a90f31`. All 5 skill files updated to use `Read agents.json + morph-spec state add-agent` flow.
+- **#2 validate-css in morph-replicate** — Fixed in same commit.
+
+---
+
+## Remaining Issues — Prioritized
+
+### Task 1 — Fix ARCHITECTURE.md hooks table (documentation, low risk)
+
+The hooks table in `docs/ARCHITECTURE.md` has wrong hook names. Verified against actual files in `framework/hooks/claude-code/`:
+
+| What doc says | What actually exists |
+|---|---|
+| UserPromptSubmit: `protect-spec-files.js` | UserPromptSubmit: `enrich-prompt.js` |
+| PreToolUse: `validate-feature-phase.js` | PreToolUse: `enforce-phase-writes.js` + `protect-readonly-files.js` + `protect-spec-files.js` (3 hooks) |
+
+**Fix:** Rewrite hooks table in `ARCHITECTURE.md` with correct names and descriptions. Also fix COMMAND-FLOWS.md Section 9 hook chain (same error — hook names partially wrong).
+
+Files: `docs/ARCHITECTURE.md`, `docs/COMMAND-FLOWS.md`
+
+---
+
+### Task 2 — Add `morph-spec unapprove` command (gate revocation)
+
+`approve` was kept in the CLI, but `reject` was removed in the simplification. Users who approve a gate and then realize the spec needs rework are blocked — no supported path to undo an approval.
+
+**Fix:** Add `unapprove` command that sets `approvals[gate] = false` and removes the approval from history.
+
+Files:
+- `src/commands/state/approve.js` — add `unapproveCommand()`
+- `bin/morph-spec.js` — register `morph-spec unapprove <feature> <gate>`
+- `test/commands/approve.test.js` — add tests
+
+---
+
+### Task 3 — Make spec injection limit configurable
+
+`inject-morph-context.js` hardcodes `3000` chars. Real specs exceed this; Claude starts sessions with truncated context and makes decisions based on partial information.
+
+**Fix:** Read limit from `.morph/config/config.json` → `hooks.specInjectionLimit` (default: 3000). Add `specInjectionLimit` to the config schema.
+
+Files:
+- `framework/hooks/claude-code/session-start/inject-morph-context.js`
+- `src/lib/config/config-schema.js` (or wherever defaults live)
+- `test/hooks/hooks-e2e.test.js` — add test for custom limit
+
+---
+
+### Task 4 — Add hook health summary to `morph-spec doctor`
+
+`doctor` checks for the existence of `.claude/skills/`, `.claude/agents/`, `.claude/rules/` but doesn't validate hook configuration. A broken hook (wrong path, deleted file) passes doctor with no warning.
+
+**Fix:** Add a `hooks` health check section to `doctorCommand()`:
+1. Read `.claude/settings.local.json`
+2. For each configured hook, verify the hook script file exists at the referenced path
+3. Report any missing or misconfigured hooks
+
+Files:
+- `src/commands/project/doctor.js`
+- `test/commands/doctor.test.js`
+
+---
+
+### Task 5 — Skills-CLI compatibility: add `cliVersion` to SKILL.md frontmatter + doctor check
+
+After the radical simplification, skill files drifted from the CLI. There's no mechanism to detect this drift.
+
+**Fix:**
+1. Add `cliVersion: "4.7.2"` to the frontmatter of all workflow skill files (`level-1-workflows/**`)
+2. `morph-spec doctor` reads each installed `.claude/skills/*/SKILL.md`, extracts `cliVersion`, and warns if it doesn't match the running CLI version
+
+This gives future maintainers a clear signal when a skill update is needed.
+
+Files:
+- `framework/skills/level-1-workflows/*/SKILL.md` (8 files) — add `cliVersion: "4.7.2"` to frontmatter
+- `src/commands/project/doctor.js` — add skills version check
+- `test/commands/doctor.test.js` — add tests
+
+---
+
+### Task 6 — Atomic state.json writes (prevent corruption on concurrent hook + CLI)
+
+`state-manager.js` does direct `writeFileSync`. If `track-output-creation.js` hook fires while a CLI command is mid-write, the state file can be corrupted or half-written.
+
+**Fix:** Use write-then-rename pattern in `saveState()`:
+1. Write to `state.json.tmp`
+2. `fs.renameSync('state.json.tmp', 'state.json')`
+
+`renameSync` is atomic on the same filesystem (POSIX guarantee; on Windows, Node ≥ 14 uses `MoveFileExW` which is also atomic for same-volume).
+
+Files:
+- `src/core/state/state-manager.js` — update `saveState()`
+- `test/core/state-manager.test.js` — add concurrent write test
+
+---
+
+## Intentionally Deferred
+
+**Phase numbering refactor** (issue #11): Renaming phase IDs and output directories (0-proposal → proposal/, 1-design → design/, etc.) is a breaking change that affects state.json migration, all skill files, all hook paths, and user documentation simultaneously. High value, high risk — scope for a dedicated major version bump.
+
+---
+
+## Execution Order
+
+```
+Task 1 (docs fix)   → low risk, do first, no tests needed
+Task 2 (unapprove)  → small new command, fully testable
+Task 3 (spec limit) → single hook + config schema
+Task 4 (doctor)     → extends existing doctor checks
+Task 5 (cliVersion) → frontmatter + doctor extension
+Task 6 (atomic)     → state-manager internals
+```
+
+Tasks 1–3 are independent and can be done in any order. Tasks 4–5 both extend doctor.js; do sequentially. Task 6 is self-contained.

package/docs/plans/2026-02-24-morph-init-design.md

@@ -0,0 +1,337 @@
+# morph-init: LLM-Powered Project Initialization
+
+**Status:** COMPLETE (see implementation plan)
+
+**Date:** 2026-02-24
+**Replaces:** `morph-spec init` as user-facing entry point
+
+---
+
+## Problem
+
+`morph-spec init` relies on deterministic file-based detection that fails in three common scenarios:
+
+1. **Monorepos** — Next.js in `src/frontend/`, .NET in `src/backend/`; patterns look for config at project root only
+2. **Empty/new projects** — no files yet to detect
+3. **Non-standard layouts** — any structure outside expected conventions
+
+When detection fails, it writes `architecture: "unknown"`, `stack: "dotnet"` (false positive), and a placeholder `context/README.md` with `(To be detected)`. MCP recommendations are also wrong because they depend on the detected stack.
+
+Additionally, skills throughout the framework reference `superpowers:brainstorming`, `superpowers:writing-plans`, etc. — but nothing in init ensures those plugins are installed.
+
+---
+
+## Decision
+
+Split init into two layers with clear responsibilities:
+
+| Layer | Entry Point | Mechanism | Responsibility |
+|-------|-------------|-----------|----------------|
+| Infrastructure | `morph-spec setup-infra` (internal) | CLI, deterministic | Dirs, framework files, hooks, agents, rules, skills |
+| Context + Config | `/morph-init` (skill) | LLM-powered | Stack detection, README.md, config.json, MCPs, plugins |
+
+**User-facing flow:**
+```
+npm install -g @polymorphism-tech/morph-spec
+        ↓ (postinstall copies morph-init.md → ~/.claude/skills/)
+
+Open project in Claude Code
+/morph-init    ← single entry point for all users
+```
+
+`morph-spec init` CLI remains for CI/CD and non-Claude-Code environments but is no longer the documented primary path.
+
+---
+
+## Architecture
+
+```
+npm package (@polymorphism-tech/morph-spec)
+  ├── bin/morph-spec.js              CLI — retains: status, update, doctor, mcp, etc.
+  │                                       init kept for headless/CI use only
+  ├── src/scripts/
+  │   ├── setup-infra.js             NEW — headless infrastructure setup (no prompts)
+  │   ├── install-plugin.js          NEW — auto-installs Claude Code plugins
+  │   └── global-install.js          NEW — postinstall: copies morph-init.md globally
+  └── framework/skills/
+      └── level-0-meta/morph-init/
+          └── SKILL.md               NEW — primary user entry point
+```
+
+---
+
+## Skill Design: `/morph-init`
+
+### Frontmatter
+
+```yaml
+---
+name: morph-init
+description: >
+  LLM-powered project initialization. Installs morph-spec infrastructure,
+  analyzes any project structure intelligently, generates rich context/README.md
+  and config.json, and configures MCPs. Use once per project after installing
+  @polymorphism-tech/morph-spec. Re-run with /morph-init refresh to update
+  context as project evolves.
+argument-hint: "[refresh]"
+user-invocable: true
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+```
+
+---
+
+### Step 0 — Plugin Prerequisites
+
+Check and auto-install `superpowers` and `context7` Claude Code plugins.
+
+**Detection:**
+```bash
+# Read ~/.claude/plugins/installed_plugins.json
+# Check for keys: "superpowers@claude-plugins-official", "context7@claude-plugins-official"
+```
+
+**Auto-install flow (for each missing plugin):**
+```
+[Bash] node {morphSpecRoot}/scripts/install-plugin.js {plugin}
+  1. GET github.com/anthropics/claude-plugins-official — resolve latest SHA/version
+  2. Download plugin files recursively to:
+     ~/.claude/plugins/cache/claude-plugins-official/{plugin}/{version}/
+  3. Register in installed_plugins.json:
+     { scope: "user", installPath: "...", version: "...",
+       installedAt: now, lastUpdated: now, gitCommitSha: "..." }
+  4. SUCCESS → "✓ {plugin} installed."
+  5. FAIL    → show manual guide (see below) → STOP
+```
+
+**Manual fallback (on auto-install failure):**
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Plugin {plugin} requires manual installation:              │
+│                                                             │
+│  1. Claude Code → Settings (Cmd/Ctrl+,) → Extensions        │
+│  2. Browse → search "{plugin}" → Install                    │
+│  3. Restart Claude Code                                     │
+│  4. Re-run /morph-init                                      │
+└─────────────────────────────────────────────────────────────┘
+→ STOP — do not continue without required plugins
+```
+
+Both `superpowers` and `context7` are required. Execution halts if either cannot be installed.
+
+---
+
+### Step 1 — Infrastructure
+
+```
+Check if .morph/ exists:
+
+  MISSING → [Bash] npx morph-spec setup-infra
+              Creates: .morph/{config,framework,context,features,checkpoints,memory,archive}
+              Copies:  framework files (templates, standards, rules, agents, skills, hooks)
+              Installs: .claude/agents/, .claude/rules/, .claude/skills/
+              Creates: config.json (minimal), context/README.md (placeholder)
+              Updates: .gitignore
+            → "✓ Infrastructure installed"
+
+  EXISTS + argument "refresh" → continue (will overwrite context/config)
+
+  EXISTS + no argument →
+    "MORPH already initialized. Refresh context and config? (y/n)"
+    n → STOP
+```
+
+---
+
+### Step 2 — LLM Project Analysis
+
+Run in parallel to build an evidence map:
+
+| Tool | Pattern | Signal |
+|------|---------|--------|
+| Glob | `**/package.json` | All package.json — detect next, supabase, clerk, stripe, etc. |
+| Glob | `**/*.csproj` | .NET projects (any depth) |
+| Glob | `**/next.config.{js,ts,mjs}` | Next.js in any subdirectory |
+| Glob | `**/components.json` | shadcn/ui |
+| Glob | `**/docker-compose*.yml` | Services in use |
+| Glob | `database/migrations/**` | Supabase local dev |
+| Glob | `supabase/**` | Supabase project config |
+| Glob | `**/*.razor` | Blazor |
+| Read | `.env.example` | Env vars reveal integrations |
+| Read | `README.md` | Existing developer context |
+| Grep | `@supabase/supabase-js` | Supabase dep in any package.json |
+| Grep | `clerk\|auth0\|nextauth` | Authentication provider |
+| Grep | `stripe\|asaas` | Payment provider |
+
+**Output: evidence map**
+```json
+{
+  "stack": ["nextjs", "dotnet"],
+  "integrations": ["supabase", "docker", "clerk"],
+  "uiLibrary": "shadcn",
+  "monorepo": true,
+  "frontendPath": "src/frontend",
+  "backendPath": "src/backend",
+  "confidence": { "stack": 0.98, "integrations": 0.91 }
+}
+```
+
+---
+
+### Step 3 — Targeted Questions (max 3)
+
+**Rule: only ask what cannot be inferred with ≥90% confidence.**
+
+| Question | Condition | Purpose |
+|----------|-----------|---------|
+| "Em uma frase: qual é o objetivo principal do [ProjectName]?" | Always | Generate Overview in README.md |
+| "Confirmo: frontend em `{frontendPath}`, backend em `{backendPath}`. Correto?" | Monorepo detected | Validate before persisting paths |
+| "Supabase Cloud (managed) ou self-hosted?" | Supabase detected | Determines MCP URL configuration |
+
+Do not ask about technology already confirmed by file evidence.
+
+---
+
+### Step 4 — Generate `context/README.md`
+
+```markdown
+# [ProjectName] — Project Context
+
+## Overview
+[Answer from question 1]
+
+## Tech Stack
+| Layer      | Technology              | Location         |
+|------------|-------------------------|------------------|
+| Frontend   | Next.js 14 (App Router) | src/frontend/    |
+| Backend    | .NET 8 (Clean Arch.)    | src/backend/     |
+| Database   | Supabase (PostgreSQL)   | database/        |
+| UI Library | shadcn/ui + Tailwind    | components.json  |
+| Auth       | Clerk                   | —                |
+
+## Architecture
+[Inferred + confirmed: monorepo / single-stack / etc.]
+[Description of layers and responsibilities]
+
+## Key Integrations
+[Per integration: service → purpose → detection evidence]
+
+## Agent Notes
+[Conventions detected from eslint/tsconfig/.editorconfig,
+ important paths, project-specific patterns for MORPH agents]
+```
+
+---
+
+### Step 5 — Update `config.json`
+
+```json
+{
+  "framework": "global",
+  "frameworkVersion": "4.x.x",
+  "project": {
+    "name": "ProspectPRO",
+    "description": "One-sentence objective from question 1",
+    "stack": "nextjs+dotnet",
+    "architecture": "monorepo",
+    "uiLibrary": "shadcn",
+    "integrations": ["supabase", "docker", "clerk"],
+    "frontendPath": "src/frontend",
+    "backendPath": "src/backend"
+  }
+}
+```
+
+---
+
+### Step 6 — Configure MCPs
+
+For each detected integration with an available MCP:
+
+```
+supabase detected:
+  "Configure Supabase MCP now? (needs SUPABASE_URL + SERVICE_ROLE_KEY)"
+  YES → collect credentials → Write .claude/settings.local.json
+  NO  → show config snippet + "morph-spec mcp setup supabase"
+
+github:
+  "Configure GitHub MCP? (needs GITHUB_PERSONAL_ACCESS_TOKEN)"
+  YES/NO → same pattern
+
+Others (Figma, Docker, Azure): only if explicitly detected in .env.example or mentioned
+```
+
+---
+
+### Step 7 — Final Output
+
+```
+✓ Plugins: superpowers v4.3.1 ✓   context7 ✓
+✓ Infrastructure: .morph/ structure, hooks, agents, rules, skills
+✓ context/README.md generated
+✓ config.json updated
+  Stack: nextjs+dotnet  |  Architecture: monorepo
+  Integrations: supabase, docker, clerk
+✓ MCPs: supabase configured
+○ Restart Claude Code to activate newly installed plugins
+
+Next: /morph-proposal [feature-name]
+```
+
+---
+
+## CLI Changes
+
+### `morph-spec setup-infra` (new command)
+
+Headless infrastructure-only setup. Called internally by the skill.
+Same logic as current `morph-spec init` but:
+- No interactive prompts
+- No stack detection (that's the skill's job)
+- No MCP setup (that's the skill's job)
+- Writes minimal `config.json` (name + version only)
+- Writes placeholder `context/README.md`
+
+### `morph-spec init` (modified)
+
+Remains for CI/CD and non-Claude-Code environments.
+Internally delegates to `setup-infra.js` for infrastructure,
+then runs a best-effort detection pass.
+No longer documented as primary user path.
+
+### `morph-spec doctor` (modified)
+
+Add plugin checks:
+```
+✓ superpowers@claude-plugins-official installed?
+✓ context7@claude-plugins-official installed?
+```
+
+---
+
+## New Files
+
+| File | Description |
+|------|-------------|
+| `framework/skills/level-0-meta/morph-init/SKILL.md` | Primary skill |
+| `src/scripts/setup-infra.js` | Headless infrastructure setup |
+| `src/scripts/install-plugin.js` | Auto-install CC plugins from GitHub |
+| `src/scripts/global-install.js` | postinstall: copy skill to ~/.claude/skills/ |
+
+## Modified Files
+
+| File | Change |
+|------|--------|
+| `package.json` | Add `"postinstall": "node scripts/global-install.js"` |
+| `src/commands/project/init.js` | Delegate to setup-infra.js; remove context/MCP logic |
+| `src/commands/project/doctor.js` | Add plugin presence checks |
+| `src/lib/detectors/structure-detector.js` | Fix nextjs patterns for subdirectories (best-effort) |
+
+---
+
+## Out of Scope
+
+- Removing `morph-spec init` entirely (kept for CI/CD)
+- Plugin auto-update (only install if missing)
+- Interactive stack selector fallback in CLI (skill handles this)
+- shadcn MCP (no official MCP available)