@polymorphism-tech/morph-spec 4.3.6 → 4.5.0

package/docs/plans/2026-02-22-morph-spec-next.md

@@ -0,0 +1,478 @@
+# morph-spec-next Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Close the remaining gaps left after Claude Code Native Alignment Rounds 1 & 2 — specifically: make `morph-spec update` sync all Claude-native artifacts introduced in recent rounds, add `.claude/rules/` and `.claude/agents/` health checks to `doctor`, and bump the version to 4.4.0 to signal the alignment work to users.
+
+**Architecture:** Four focused changes to existing files. No new files created. All changes are additive within the existing command/utility patterns. Tests follow the established pattern of testing utility functions directly (not interactive CLI commands).
+
+**Tech Stack:** Node.js ESM, `fs-extra`, existing `installSkills` / `installAgents` utilities, `node:test`
+
+---
+
+## Background: What update.js is missing
+
+`morph-spec update` currently:
+- Cleans the entire `.claude/` directory (`cleanFrameworkDirs` line 62)
+- Rebuilds: commands, skills (manual junction-linking), hooks, CLAUDE.md (via `copyDirectory` — bug)
+- **Missing:** flat skills (`installSkills`), agents (`installAgents`), rules copy, `CLAUDE_runtime.md` copy
+
+Also: line 311 calls `copyDirectory(claudeMdSrc, claudeMdDest)` on a single FILE — should be `copyFile`.
+
+---
+
+## Task 1: Fix update.js — imports + copyFile bug
+
+**Files:**
+- Modify: `src/commands/project/update.js`
+
+**Step 1: Add missing imports**
+
+At the top of `update.js`, after the existing `import { installClaudeHooks }` line (line 29), add:
+
+```javascript
+import { installSkills } from '../../utils/skills-installer.js';
+import { installAgents } from '../../utils/agents-installer.js';
+```
+
+**Step 2: Fix the copyDirectory → copyFile bug on CLAUDE.md**
+
+Find this block (around line 307–311):
+```javascript
+// Update CLAUDE.md
+updateSpinner.text = 'Updating CLAUDE.md...';
+const claudeMdSrc = join(contentDir, 'CLAUDE.md');
+const claudeMdDest = join(targetPath, 'CLAUDE.md');
+await copyDirectory(claudeMdSrc, claudeMdDest);
+```
+
+Replace `copyDirectory` with `copyFile`:
+```javascript
+// Update CLAUDE.md
+updateSpinner.text = 'Updating CLAUDE.md...';
+const claudeMdSrc = join(contentDir, 'framework', 'CLAUDE.md');
+const claudeMdDest = join(targetPath, 'CLAUDE.md');
+await copyFile(claudeMdSrc, claudeMdDest);
+```
+
+Note: `contentDir` is the framework root (returned by `getContentDir()`), so `CLAUDE.md` is at `join(contentDir, 'framework', 'CLAUDE.md')`.
+
+**Step 3: Run the existing update-related tests to confirm nothing broke**
+
+```bash
+npm test -- test/commands/init.test.js
+```
+
+Expected: 16 pass, 0 fail.
+
+**Step 4: Commit**
+
+```bash
+git add src/commands/project/update.js
+git commit -m "fix(update): import installSkills/installAgents and fix copyFile bug on CLAUDE.md"
+```
+
+---
+
+## Task 2: Add new artifact sync steps to update.js
+
+**Files:**
+- Modify: `src/commands/project/update.js`
+
+After the existing skills symlinking block (the closing `}` of the `{ const skillsSrc = ...}` block, around line 301) and BEFORE the hooks update line (`// Update Claude Code hooks`), insert these four steps:
+
+**Step 1: Add flat skills sync (installSkills)**
+
+```javascript
+// Sync morph skills to .claude/skills/ for native Claude Code discovery
+updateSpinner.text = 'Syncing morph skills to .claude/skills/...';
+await installSkills(targetPath);
+```
+
+**Step 2: Add agents sync (installAgents)**
+
+```javascript
+// Sync native subagents to .claude/agents/
+updateSpinner.text = 'Syncing agents to .claude/agents/...';
+await installAgents(targetPath, frameworkDir);
+```
+
+**Step 3: Add rules sync**
+
+```javascript
+// Sync path-scoped rules to .claude/rules/
+updateSpinner.text = 'Syncing rules to .claude/rules/...';
+const rulesSrc = join(frameworkDir, 'rules');
+const rulesDest = join(claudeDest, 'rules');
+if (await pathExists(rulesSrc)) {
+  await copyDirectory(rulesSrc, rulesDest);
+}
+```
+
+**Step 4: Add CLAUDE_runtime.md sync**
+
+```javascript
+// Sync runtime CLAUDE.md to .claude/CLAUDE.md
+updateSpinner.text = 'Syncing .claude/CLAUDE.md...';
+const runtimeSrc = join(frameworkDir, 'CLAUDE_runtime.md');
+const runtimeDest = join(claudeDest, 'CLAUDE.md');
+if (await pathExists(runtimeSrc)) {
+  await copyFile(runtimeSrc, runtimeDest);
+}
+```
+
+**Step 5: Update the success output block**
+
+Find the "Updated files:" logger section (around line 336–350) and add these lines after the existing hooks line:
+
+```javascript
+logger.dim('  ✓ .claude/skills/ (flat .md for /skill-name discovery)');
+logger.dim('  ✓ .claude/agents/ (native subagents refreshed)');
+logger.dim('  ✓ .claude/rules/ (path-scoped rules synced)');
+logger.dim('  ✓ .claude/CLAUDE.md (runtime quick reference)');
+```
+
+**Step 6: Run syntax check**
+
+```bash
+node --check src/commands/project/update.js && echo "Syntax OK"
+```
+
+Expected: `Syntax OK`
+
+**Step 7: Commit**
+
+```bash
+git add src/commands/project/update.js
+git commit -m "feat(update): sync rules, agents, flat skills, and .claude/CLAUDE.md on update"
+```
+
+---
+
+## Task 3: Write tests for update artifact sync
+
+**Files:**
+- Create: `test/commands/update.test.js`
+
+The update command is interactive, so test the underlying utility functions directly — the same pattern used in `test/commands/init.test.js`.
+
+**Step 1: Write the test file**
+
+```javascript
+/**
+ * Tests for update command artifact sync.
+ * Tests utility functions directly to avoid interactive prompts.
+ */
+
+import { test, describe, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import { createTempDir, cleanupTempDir } from '../helpers/test-utils.js';
+import { installSkills } from '../../src/utils/skills-installer.js';
+import { installAgents } from '../../src/utils/agents-installer.js';
+import { copyDirectory, copyFile, pathExists } from '../../src/utils/file-copier.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const FRAMEWORK_DIR = join(__dirname, '..', '..', 'framework');
+
+describe('update — artifact sync', () => {
+  let tempDir;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+  });
+
+  afterEach(() => {
+    cleanupTempDir(tempDir);
+  });
+
+  test('installSkills produces flat .claude/skills/ .md files', async () => {
+    await installSkills(tempDir);
+    const skillsDir = join(tempDir, '.claude', 'skills');
+    assert.ok(existsSync(skillsDir), '.claude/skills/ must exist');
+    const files = readdirSync(skillsDir).filter(f => f.endsWith('.md'));
+    assert.ok(files.length >= 4, `must have at least 4 flat skill files, got ${files.length}`);
+  });
+
+  test('installAgents produces .claude/agents/ with morph- prefixed files', async () => {
+    await installAgents(tempDir, FRAMEWORK_DIR);
+    const agentsDir = join(tempDir, '.claude', 'agents');
+    assert.ok(existsSync(agentsDir), '.claude/agents/ must exist');
+    const files = readdirSync(agentsDir);
+    assert.ok(files.every(f => f.startsWith('morph-')), 'all agent files must have morph- prefix');
+    assert.ok(files.length >= 6, `must have at least 6 agents, got ${files.length}`);
+  });
+
+  test('rules copy produces .claude/rules/ with 5 files', async () => {
+    const rulesSrc = join(FRAMEWORK_DIR, 'rules');
+    const rulesDest = join(tempDir, '.claude', 'rules');
+    const exists = await pathExists(rulesSrc);
+    assert.ok(exists, 'framework/rules/ source must exist');
+    await copyDirectory(rulesSrc, rulesDest);
+    const files = readdirSync(rulesDest).filter(f => f.endsWith('.md'));
+    assert.equal(files.length, 5, `must install 5 rule files, got ${files.length}`);
+  });
+
+  test('CLAUDE_runtime.md copy produces .claude/CLAUDE.md', async () => {
+    const src = join(FRAMEWORK_DIR, 'CLAUDE_runtime.md');
+    const dest = join(tempDir, '.claude', 'CLAUDE.md');
+    const claudeDir = join(tempDir, '.claude');
+    // ensure parent exists
+    await (await import('node:fs/promises')).mkdir(claudeDir, { recursive: true });
+    await copyFile(src, dest);
+    assert.ok(existsSync(dest), '.claude/CLAUDE.md must exist after copy');
+    const content = (await import('node:fs/promises')).readFile(dest, 'utf-8');
+    assert.ok(content instanceof Promise, 'content must be readable');
+  });
+
+  test('clean-recreate is idempotent — second run replaces without error', async () => {
+    // First run
+    await installSkills(tempDir);
+    await installAgents(tempDir, FRAMEWORK_DIR);
+    const rulesSrc = join(FRAMEWORK_DIR, 'rules');
+    const rulesDest = join(tempDir, '.claude', 'rules');
+    await copyDirectory(rulesSrc, rulesDest);
+
+    // Second run (simulates update running again)
+    await installSkills(tempDir);
+    await installAgents(tempDir, FRAMEWORK_DIR);
+    await copyDirectory(rulesSrc, rulesDest);
+
+    const ruleFiles = readdirSync(rulesDest).filter(f => f.endsWith('.md'));
+    assert.equal(ruleFiles.length, 5, 'idempotent: must still have 5 rule files after second run');
+  });
+});
+```
+
+**Step 2: Run the new tests**
+
+```bash
+npm test -- test/commands/update.test.js
+```
+
+Expected: 5 pass, 0 fail.
+
+**Step 3: Commit**
+
+```bash
+git add test/commands/update.test.js
+git commit -m "test(update): add artifact sync tests for update command"
+```
+
+---
+
+## Task 4: Version bump to 4.4.0
+
+**Files:**
+- Modify: `package.json`
+
+**Step 1: Update version**
+
+Find: `"version": "4.3.7"`
+Replace with: `"version": "4.4.0"`
+
+**Step 2: Update version reference in framework/CLAUDE.md and framework/CLAUDE_runtime.md**
+
+In `framework/CLAUDE.md`, find: `*MORPH-SPEC v4.3.7 by Polymorphism Tech*`
+Replace with: `*MORPH-SPEC v4.4.0 by Polymorphism Tech*`
+
+In `framework/CLAUDE_runtime.md`, find: `*MORPH-SPEC v4.3.7 by Polymorphism Tech*`
+Replace with: `*MORPH-SPEC v4.4.0 by Polymorphism Tech*`
+
+**Step 3: Verify version is consistent**
+
+```bash
+node -e "import('./package.json', {assert:{type:'json'}}).then(m=>console.log(m.default.version))" 2>/dev/null || grep '"version"' package.json
+```
+
+Expected: `4.4.0`
+
+**Step 4: Commit**
+
+```bash
+git add package.json framework/CLAUDE.md framework/CLAUDE_runtime.md
+git commit -m "chore: bump version to 4.4.0 — Claude Code native alignment rounds 1 & 2"
+```
+
+---
+
+## Task 5: Doctor — add .claude/rules/ and .claude/agents/ checks
+
+**Files:**
+- Modify: `src/commands/project/doctor.js`
+
+The `.claude/` check block (line ~454–494) checks commands and skills. Add rules and agents checks inside the `if (hasCommands && hasSkills)` block, after the skills link status check ends (after the closing `}` of the `if (skillDirs.length > 0)` block).
+
+**Step 1: Add the rules check**
+
+After the skills link block ends (around line 487), and still inside `if (hasCommands && hasSkills) {`, add:
+
+```javascript
+    // Check .claude/rules/
+    const rulesPath = join(claudePath, 'rules');
+    if (await pathExists(rulesPath)) {
+      const ruleFiles = await fs.readdir(rulesPath);
+      const mdRules = ruleFiles.filter(f => f.endsWith('.md'));
+      checks.push({ name: '.claude/rules/', status: 'ok', msg: `${mdRules.length} rules` });
+    } else {
+      checks.push({ name: '.claude/rules/', status: 'warn', msg: 'missing — run morph-spec update' });
+      hasWarnings = true;
+    }
+
+    // Check .claude/agents/
+    const agentsPath = join(claudePath, 'agents');
+    if (await pathExists(agentsPath)) {
+      const agentFiles = await fs.readdir(agentsPath);
+      const morphAgents = agentFiles.filter(f => f.startsWith('morph-') && f.endsWith('.md'));
+      checks.push({ name: '.claude/agents/', status: 'ok', msg: `${morphAgents.length} agents` });
+    } else {
+      checks.push({ name: '.claude/agents/', status: 'warn', msg: 'missing — run morph-spec update' });
+      hasWarnings = true;
+    }
+```
+
+**Step 2: Verify syntax**
+
+```bash
+node --check src/commands/project/doctor.js && echo "Syntax OK"
+```
+
+Expected: `Syntax OK`
+
+**Step 3: Commit**
+
+```bash
+git add src/commands/project/doctor.js
+git commit -m "feat(doctor): add .claude/rules/ and .claude/agents/ health checks"
+```
+
+---
+
+## Task 6: Write tests for doctor enhancements
+
+**Files:**
+- Create: `test/commands/doctor.test.js`
+
+**Step 1: Write tests that directly exercise the check logic**
+
+```javascript
+/**
+ * Tests for doctor command health check additions.
+ * Tests the check logic by setting up temp dirs with/without the expected artifacts.
+ */
+
+import { test, describe, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { createTempDir, cleanupTempDir } from '../helpers/test-utils.js';
+import { pathExists } from '../../src/utils/file-copier.js';
+import { installSkills } from '../../src/utils/skills-installer.js';
+import { installAgents } from '../../src/utils/agents-installer.js';
+import { copyDirectory } from '../../src/utils/file-copier.js';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const FRAMEWORK_DIR = join(__dirname, '..', '..', 'framework');
+
+describe('doctor — .claude artifact checks', () => {
+  let tempDir;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+  });
+
+  afterEach(() => {
+    cleanupTempDir(tempDir);
+  });
+
+  test('.claude/rules/ missing → would produce warn', async () => {
+    const rulesPath = join(tempDir, '.claude', 'rules');
+    const exists = await pathExists(rulesPath);
+    assert.equal(exists, false, '.claude/rules/ should not exist in fresh temp dir');
+    // Confirms doctor would add a warning
+  });
+
+  test('.claude/rules/ present with 5 files → would produce ok', async () => {
+    const rulesSrc = join(FRAMEWORK_DIR, 'rules');
+    const rulesDest = join(tempDir, '.claude', 'rules');
+    await copyDirectory(rulesSrc, rulesDest);
+    const exists = await pathExists(rulesDest);
+    assert.ok(exists, '.claude/rules/ must exist after copy');
+    const { readdirSync } = await import('fs');
+    const files = readdirSync(rulesDest).filter(f => f.endsWith('.md'));
+    assert.equal(files.length, 5, 'must have 5 rule files for an ok check');
+  });
+
+  test('.claude/agents/ missing → would produce warn', async () => {
+    const agentsPath = join(tempDir, '.claude', 'agents');
+    const exists = await pathExists(agentsPath);
+    assert.equal(exists, false, '.claude/agents/ should not exist in fresh temp dir');
+  });
+
+  test('.claude/agents/ present with morph- agents → would produce ok', async () => {
+    await installAgents(tempDir, FRAMEWORK_DIR);
+    const agentsPath = join(tempDir, '.claude', 'agents');
+    const exists = await pathExists(agentsPath);
+    assert.ok(exists, '.claude/agents/ must exist after installAgents');
+    const { readdirSync } = await import('fs');
+    const files = readdirSync(agentsPath).filter(f => f.startsWith('morph-'));
+    assert.ok(files.length >= 6, `must have at least 6 morph- agents, got ${files.length}`);
+  });
+});
+```
+
+**Step 2: Run the tests**
+
+```bash
+npm test -- test/commands/doctor.test.js
+```
+
+Expected: 4 pass, 0 fail.
+
+**Step 3: Commit**
+
+```bash
+git add test/commands/doctor.test.js
+git commit -m "test(doctor): add tests for .claude/rules/ and .claude/agents/ check logic"
+```
+
+---
+
+## Task 7: Full test suite + final commit
+
+**Step 1: Run full test suite**
+
+```bash
+npm test 2>&1 | tail -10
+```
+
+Expected: `pass` count ≥ 596, `fail` 0, `skipped` 1. (Previous baseline: 587 pass.)
+
+**Step 2: If any failures, fix them before proceeding**
+
+Failing tests mean the plan has a bug. Stop, diagnose, fix — do NOT skip tests.
+
+**Step 3: Update memory**
+
+Update `MEMORY.md` to reflect the new test count and version.
+
+**Step 4: Final commit if anything was missed**
+
+```bash
+git status
+# If clean: nothing to do
+# If not: git add <files> && git commit -m "chore: final cleanup for morph-spec-next"
+```
+
+---
+
+## What this plan does NOT include (intentionally)
+
+- `.wiki/prompts/` — only one prompt file, still useful for future alignment rounds; no cleanup needed
+- Level 3–4 skill audit — both directories contain only `README.md`; nothing to audit
+- `morph-workflow.md` live injection — rules are static files; the `enrich-prompt.js` hook already handles dynamic state injection and is already focused (no trim needed)

package/docs/plans/2026-02-22-native-alignment-design.md

@@ -0,0 +1,199 @@
+# Design: MORPH-SPEC Native Alignment + State.json Simplification
+
+**Date:** 2026-02-22
+**Version target:** 4.5.0
+**Branch:** single branch, all changes together
+
+---
+
+## Summary
+
+Six focused changes that align MORPH-SPEC closer to Claude Code's native platform patterns and reduce architectural complexity without breaking existing functionality.
+
+---
+
+## Section 1 — Skills File Format Fix
+
+**Problem:** `skills-installer.js` installs skills as flat files (`.claude/skills/brainstorming.md`). Native Claude Code format is subdirectory + `SKILL.md` (`.claude/skills/brainstorming/SKILL.md`). Flat format prevents frontmatter features from working (allowed-tools, argument-hint, context:fork).
+
+**Design:**
+- `installSkillsFromDir()` creates `<destDir>/<skillName>/SKILL.md` instead of `<destDir>/<skillName>.md`
+- Skill name derived from filename without extension (same as today)
+- All level-0-meta, level-1-workflows, level-2-domains affected
+
+**Files:**
+- `src/utils/skills-installer.js` — change flat copy to mkdir + write SKILL.md
+- `test/utils/skills-installer.test.js` — update assertions to check subdirectory format
+- `src/commands/project/update.js` — no change needed (calls installSkills which is updated)
+
+---
+
+## Section 2 — Rules as Dynamic @-imports
+
+**Problem:** `framework/rules/*.md` contain static copies of standards content. When standards change, rules become stale until next `morph-spec update`.
+
+**Design:** Replace static body content with `@-import` directives pointing to `.morph/framework/standards/` paths in the user project. The `morph-workflow.md` rule keeps its own content (not a standards file).
+
+**Files changed:**
+- `framework/rules/csharp-standards.md` — body → @-imports to core/coding.md + backend/dotnet.md
+- `framework/rules/frontend-standards.md` — body → @-imports to frontend/ standards
+- `framework/rules/testing-standards.md` — body → @-imports to core/testing.md
+- `framework/rules/infrastructure-standards.md` — body → @-imports to infrastructure/ standards
+- `framework/rules/morph-workflow.md` — gets new "Test File Policy" section (see Section 4), no @-imports
+
+**@-import paths** use `.morph/framework/standards/` because rules are installed into user projects where that path is valid.
+
+---
+
+## Section 3 — CLAUDE.md Consolidation
+
+**Problem:** Two separate user-facing CLAUDE.md files (`framework/CLAUDE.md` and `framework/CLAUDE_runtime.md`) with duplicated content and no @-imports for dynamic context.
+
+**Design:** Single `framework/CLAUDE.md` that merges both files. Installed to `.claude/CLAUDE.md` in user projects. Uses `@.morph/context/README.md` import for dynamic project context. `framework/CLAUDE_runtime.md` deleted.
+
+**New `framework/CLAUDE.md` structure:**
+1. Header + project context @-import
+2. Critical Rules (from current CLAUDE.md)
+3. Quick Reference commands table (from CLAUDE_runtime.md)
+4. State & Outputs table (from CLAUDE_runtime.md)
+5. Phase Sequence (from CLAUDE_runtime.md)
+6. Agents section (from CLAUDE_runtime.md)
+7. MCP CLI deferred mode note (new)
+8. Footer
+
+**Files:**
+- `framework/CLAUDE.md` — merged content
+- `framework/CLAUDE_runtime.md` — **deleted**
+- `src/commands/project/init.js` — change source from `CLAUDE_runtime.md` to `CLAUDE.md` for `.claude/CLAUDE.md` install
+- `src/commands/project/update.js` — same change
+- `test/commands/init.test.js` — update source file reference
+- `test/commands/update.test.js` — update source file reference
+
+---
+
+## Section 4 — Test File Policy in morph-workflow Rule
+
+**Problem:** Claude modifies test files to make failing tests pass instead of fixing the implementation. A blocking hook is not appropriate because Claude also needs to legitimately fix incorrect test specs.
+
+**Design:** Behavioral rule in `framework/rules/morph-workflow.md` (always-active, no paths filter):
+
+```markdown
+## Test File Policy
+
+When a test fails, always follow this order:
+1. Analyze whether the IMPLEMENTATION is wrong or the TEST SPEC is wrong
+2. Fix the implementation first
+3. Only modify a test file if the test expectation itself is incorrect
+4. Before modifying a test file, explain WHY the test spec is wrong
+```
+
+No new hook. Declarative behavioral guidance over imperative blocking.
+
+**Files:**
+- `framework/rules/morph-workflow.md` — add Test File Policy section
+
+---
+
+## Section 5 — Standards and Templates Additions
+
+**5a. TypeScript Strict Mode**
+
+Add explicit strict mode section to `framework/rules/frontend-standards.md`:
+- `"strict": true` in tsconfig.json is required
+- Explains why: agents rely on compiler errors to self-correct at compile time
+
+**5b. MCP CLI Deferred Mode**
+
+Add note to merged `framework/CLAUDE.md`:
+- With 3+ MCPs, add `"experimental": { "mcpCliMode": true }` to settings.json
+- Keeps context window clean; MCP tools load on-demand
+
+**5c. User Stories Template**
+
+New file `framework/templates/docs/user-stories.md` with format:
+- Story header (feature, priority)
+- Optimal path steps
+- Edge cases
+- Acceptance criteria checklist
+
+**Files:**
+- `framework/rules/frontend-standards.md` — add TypeScript strict section (also in @-import content)
+- `framework/CLAUDE.md` — add MCP deferred mode note
+- `framework/templates/docs/user-stories.md` — new template file
+
+---
+
+## Section 6 — State.json Simplification
+
+**Problem:** `state.json` tracks `outputs.{type}.created` and `phase` — both derivable from the filesystem. The `track-output-creation.js` hook exists solely to maintain these two fields and has been the source of synchronization bugs.
+
+**Design:**
+
+Remove from state.json schema (per feature):
+- `outputs` object (all 12 output types with `created` booleans and `path` strings)
+- `phase` string field
+
+Keep in state.json (unchanged):
+- `workflow` — which workflow was auto-selected
+- `approvalGates` — approval status per gate
+- `tasks` — total/completed counts
+- `createdAt` — timestamp
+- `activeAgents` — for display/analytics
+
+Derive at runtime:
+```javascript
+// Phase: highest-numbered folder present
+function derivePhase(featurePath) {
+  const folders = ['4-implement', '3-tasks', '2-ui', '1-design', '0-proposal'];
+  return folders.find(f => fs.existsSync(path.join(featurePath, f))) ?? 'setup';
+}
+
+// Output existence: file exists check
+function deriveOutputs(feature, outputDefs) {
+  return Object.fromEntries(
+    Object.entries(outputDefs).map(([type, relPath]) => [
+      type, { created: fs.existsSync(path.join(featureBase, relPath)), path: relPath }
+    ])
+  );
+}
+```
+
+**Migration:** `state-manager.js` migration from v4.x → v5.0 removes `outputs` and `phase` fields on first load if present. Backwards compatible read.
+
+**Files:**
+- `src/core/state/state-manager.js` — remove `outputs` + `phase` from `ensureFeature()`, add migration, add `derivePhase()` + `deriveOutputs()` helpers
+- `framework/hooks/claude-code/post-tool-use/track-output-creation.js` — **deleted**
+- `src/utils/hooks-installer.js` — remove `track-output-creation.js` from PostToolUse hook list
+- `src/commands/project/status.js` — update to call `derivePhase()` + `deriveOutputs()`
+- `test/core/state/state-manager.test.js` — remove `outputs`/`phase` tests, add derive helper tests
+
+---
+
+## What Does NOT Change
+
+- `approvalGates` in state.json — kept, protected by permissions.deny
+- `protect-spec-files.js` hook — kept, still reads approvalGates from state.json
+- All 37 agents in agents.json — unchanged
+- All validators — unchanged
+- All workflow configs — unchanged
+- All Handlebars templates (except new user-stories.md addition)
+- Git hooks — unchanged
+- Agent Teams hooks — unchanged
+
+---
+
+## Test Strategy
+
+All 614 existing tests must pass after changes. New tests added for:
+- `skills-installer.test.js` — verify subdirectory format
+- `state-manager.test.js` — verify `derivePhase()`, `deriveOutputs()`, migration from v4
+- `hooks-installer.test.js` — verify track-output-creation no longer registered
+
+No integration tests needed — all changes are unit-testable.
+
+---
+
+## Version Bump
+
+`package.json`: `4.4.0` → `4.5.0`
+`framework/CLAUDE.md`: update version in footer