@polymorphism-tech/morph-spec 4.8.1 → 4.8.4

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

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

@@ -1,337 +0,0 @@
-# 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)