@polymorphism-tech/morph-spec 7.1.1 → 7.3.0

package/framework/hooks/claude-code/core/validate-completion.js

@@ -1,136 +1,136 @@
-#!/usr/bin/env node
-
-/**
- * Stop Hook: Phase Transition Alert + Build Check + Session Snapshot
- *
- * Event: Stop
- *
- * 1. Detects transitions into the `implement` phase and recommends /compact.
- * 2. Runs stack-aware build check — warns only on failure (silent on pass).
- * 3. Saves session snapshot for next-session orientation.
- *
- * Phase transition tracking: stores last-seen phase per feature in
- * .morph/memory/phase-watch.json so the alert fires exactly once.
- *
- * Fail-open: exits 0 on any error.
- */
-
-import { readFileSync, writeFileSync, existsSync } from 'fs';
-import { join } from 'path';
-import { runBuildCheck } from '../../shared/build-check.js';
-import { saveSessionSnapshot } from '../../shared/session-snapshot.js';
-import {
-  stateExists, getActiveFeature, getMostRecentFeature, derivePhaseForFeature,
-} from '../../shared/state-reader.js';
-import { injectContext, pass } from '../../shared/hook-response.js';
-import { logHookActivity, logEvent } from '../../shared/activity-logger.js';
-
-// Phases where compaction is strongly recommended before starting
-const COMPACT_TRIGGER_PHASES = new Set(['implement']);
-
-// Phases where compaction is suggested when arriving (heavy spec phases)
-const HEAVY_SOURCE_PHASES = new Set(['plan', 'uiux']);
-
-try {
-  // Prevent infinite loop
-  if (process.env.MORPH_STOP_HOOK_ACTIVE === '1') pass();
-
-  if (!stateExists()) pass();
-
-  // getActiveFeature() only returns in_progress/draft features.
-  // Fall back to the most recently updated feature when all features are 'done'.
-  let active = getActiveFeature() || getMostRecentFeature();
-  if (!active) pass();
-
-  const { name, feature } = active;
-  const cwd  = process.cwd();
-  const warnings = [];
-
-  // ── Phase transition detection ────────────────────────────────────────────
-  const currentPhase = feature.phase || derivePhaseForFeature(name, cwd);
-
-  const watchPath = join(cwd, '.morph', 'memory', 'phase-watch.json');
-  let phaseWatch  = {};
-  try {
-    if (existsSync(watchPath)) phaseWatch = JSON.parse(readFileSync(watchPath, 'utf-8'));
-  } catch { /* corrupt file — start fresh */ }
-
-  const lastPhase = phaseWatch[name];
-
-  // Update stored phase (always, so the alert only fires once per transition)
-  try {
-    phaseWatch[name] = currentPhase;
-    writeFileSync(watchPath, JSON.stringify(phaseWatch, null, 2), 'utf-8');
-  } catch { /* non-blocking */ }
-
-  // Alert when entering implement from a heavy spec phase
-  const isPhaseTransition = lastPhase && lastPhase !== currentPhase;
-  const enteringImplement = COMPACT_TRIGGER_PHASES.has(currentPhase);
-  const comingFromHeavyPhase = HEAVY_SOURCE_PHASES.has(lastPhase);
-
-  if (isPhaseTransition && enteringImplement && comingFromHeavyPhase) {
-    warnings.push(
-      `⚡ Phase advanced: ${lastPhase} → implement`,
-      ``,
-      `💡 Recommended before starting implementation:`,
-      `   Run /compact to free up context — spec.md, mandate.md and tasks.md`,
-      `   loaded during planning take significant space. A compact now gives`,
-      `   Claude a clean slate focused on writing code.`,
-      ``,
-      `   After /compact, resume with: /morph-apply ${name}`,
-    );
-  }
-
-  // ── Build/typecheck verification ──────────────────────────────────────────
-  // Stack-aware build check — advisory warning if build fails.
-  // Success is silent (no output on pass).
-  try {
-    const configPath = join(cwd, '.morph', 'config', 'config.json');
-    if (existsSync(configPath)) {
-      const config = JSON.parse(readFileSync(configPath, 'utf-8'));
-      const stack = config?.project?.stack;
-      if (stack && currentPhase === 'implement') {
-        const buildResult = runBuildCheck(cwd, stack);
-        if (buildResult.status === 'fail') {
-          warnings.push('⚠ Build/typecheck failed:');
-          warnings.push(buildResult.output);
-          warnings.push('Fix build errors before ending session.');
-        }
-        // pass and skip → silent (success is silent)
-      }
-    }
-  } catch {
-    // Fail-open — build check must never block Stop
-  }
-  // ────────────────────────────────────────────────────────────────────────
-
-  // ── Session snapshot ──────────────────────────────────────────────────────
-  // Save session state for next session's "getting up to speed" routine.
-  try {
-    if (active) {
-      const { name } = active;
-      saveSessionSnapshot({
-        feature: name,
-        phase: currentPhase,
-        buildStatus: 'skip',
-        lastEditedFiles: [],
-      }, cwd);
-    }
-  } catch {
-    // Fail-open — snapshot save must never block Stop
-  }
-  // ────────────────────────────────────────────────────────────────────────
-
-  if (warnings.length === 0) pass();
-
-  const message = [
-    'MORPH-SPEC:',
-    ...warnings.map(w => `  ${w}`),
-  ].join('\n');
-
-  logHookActivity('validate-completion', 'Stop', `warnings(${warnings.length})`);
-  logEvent('session_end', { feature: name, phase: currentPhase, warnings: warnings.length });
-  injectContext(message);
-} catch {
-  process.exit(0);
-}
+#!/usr/bin/env node
+
+/**
+ * Stop Hook: Phase Transition Alert + Build Check + Session Snapshot
+ *
+ * Event: Stop
+ *
+ * 1. Detects transitions into the `implement` phase and recommends /compact.
+ * 2. Runs stack-aware build check — warns only on failure (silent on pass).
+ * 3. Saves session snapshot for next-session orientation.
+ *
+ * Phase transition tracking: stores last-seen phase per feature in
+ * .morph/memory/phase-watch.json so the alert fires exactly once.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { runBuildCheck } from '../../shared/build-check.js';
+import { saveSessionSnapshot } from '../../shared/session-snapshot.js';
+import {
+  stateExists, getActiveFeature, getMostRecentFeature, derivePhaseForFeature,
+} from '../../shared/state-reader.js';
+import { injectContext, pass } from '../../shared/hook-response.js';
+import { logHookActivity, logEvent } from '../../shared/activity-logger.js';
+
+// Phases where compaction is strongly recommended before starting
+const COMPACT_TRIGGER_PHASES = new Set(['implement']);
+
+// Phases where compaction is suggested when arriving (heavy spec phases)
+const HEAVY_SOURCE_PHASES = new Set(['plan', 'uiux']);
+
+try {
+  // Prevent infinite loop
+  if (process.env.MORPH_STOP_HOOK_ACTIVE === '1') pass();
+
+  if (!stateExists()) pass();
+
+  // getActiveFeature() only returns in_progress/draft features.
+  // Fall back to the most recently updated feature when all features are 'done'.
+  let active = getActiveFeature() || getMostRecentFeature();
+  if (!active) pass();
+
+  const { name, feature } = active;
+  const cwd  = process.cwd();
+  const warnings = [];
+
+  // ── Phase transition detection ────────────────────────────────────────────
+  const currentPhase = feature.phase || derivePhaseForFeature(name, cwd);
+
+  const watchPath = join(cwd, '.morph', 'memory', 'phase-watch.json');
+  let phaseWatch  = {};
+  try {
+    if (existsSync(watchPath)) phaseWatch = JSON.parse(readFileSync(watchPath, 'utf-8'));
+  } catch { /* corrupt file — start fresh */ }
+
+  const lastPhase = phaseWatch[name];
+
+  // Update stored phase (always, so the alert only fires once per transition)
+  try {
+    phaseWatch[name] = currentPhase;
+    writeFileSync(watchPath, JSON.stringify(phaseWatch, null, 2), 'utf-8');
+  } catch { /* non-blocking */ }
+
+  // Alert when entering implement from a heavy spec phase
+  const isPhaseTransition = lastPhase && lastPhase !== currentPhase;
+  const enteringImplement = COMPACT_TRIGGER_PHASES.has(currentPhase);
+  const comingFromHeavyPhase = HEAVY_SOURCE_PHASES.has(lastPhase);
+
+  if (isPhaseTransition && enteringImplement && comingFromHeavyPhase) {
+    warnings.push(
+      `⚡ Phase advanced: ${lastPhase} → implement`,
+      ``,
+      `💡 Recommended before starting implementation:`,
+      `   Run /compact to free up context — spec.md, mandate.md and tasks.json`,
+      `   loaded during planning take significant space. A compact now gives`,
+      `   Claude a clean slate focused on writing code.`,
+      ``,
+      `   After /compact, resume with: /morph-apply ${name}`,
+    );
+  }
+
+  // ── Build/typecheck verification ──────────────────────────────────────────
+  // Stack-aware build check — advisory warning if build fails.
+  // Success is silent (no output on pass).
+  try {
+    const configPath = join(cwd, '.morph', 'config', 'config.json');
+    if (existsSync(configPath)) {
+      const config = JSON.parse(readFileSync(configPath, 'utf-8'));
+      const stack = config?.project?.stack;
+      if (stack && currentPhase === 'implement') {
+        const buildResult = runBuildCheck(cwd, stack);
+        if (buildResult.status === 'fail') {
+          warnings.push('⚠ Build/typecheck failed:');
+          warnings.push(buildResult.output);
+          warnings.push('Fix build errors before ending session.');
+        }
+        // pass and skip → silent (success is silent)
+      }
+    }
+  } catch {
+    // Fail-open — build check must never block Stop
+  }
+  // ────────────────────────────────────────────────────────────────────────
+
+  // ── Session snapshot ──────────────────────────────────────────────────────
+  // Save session state for next session's "getting up to speed" routine.
+  try {
+    if (active) {
+      const { name } = active;
+      saveSessionSnapshot({
+        feature: name,
+        phase: currentPhase,
+        buildStatus: 'skip',
+        lastEditedFiles: [],
+      }, cwd);
+    }
+  } catch {
+    // Fail-open — snapshot save must never block Stop
+  }
+  // ────────────────────────────────────────────────────────────────────────
+
+  if (warnings.length === 0) pass();
+
+  const message = [
+    'MORPH-SPEC:',
+    ...warnings.map(w => `  ${w}`),
+  ].join('\n');
+
+  logHookActivity('validate-completion', 'Stop', `warnings(${warnings.length})`);
+  logEvent('session_end', { feature: name, phase: currentPhase, warnings: warnings.length });
+  injectContext(message);
+} catch {
+  process.exit(0);
+}

package/framework/hooks/shared/phase-utils.js

@@ -65,6 +65,16 @@ export const PROTECTED_SPEC_FILES = {
   'tasks.json': 'plan',
 };
 
+/**
+ * For protected files that carry mutable progress fields: filename → the
+ * top-level array-item fields that may change after the gate is approved.
+ * When a protected file is listed here, the protect-spec-files hook does a
+ * semantic diff (allowing only these fields to change) instead of a blanket block.
+ */
+export const MUTABLE_SPEC_FIELDS = {
+  'tasks.json': ['status', 'outputs', 'notes'],
+};
+
 /**
  * Extract feature name from a .morph/features/{feature}/... path
  * @param {string} filePath - File path to analyze

package/framework/phases.json

@@ -43,7 +43,7 @@
       "goals": [
         "Write spec.md (technical spec)",
         "Write mandate.md (implementation contract with stack defaults + forbidden patterns)",
-        "Write tasks.md (ordered task breakdown)"
+        "Write tasks.json (ordered task breakdown)"
       ],
       "requiredOutputs": ["spec", "mandate", "tasks"],
       "optionalOutputs": ["decisions"],

package/framework/rules/morph-workflow.md

@@ -125,19 +125,26 @@ After making structural changes (new packages, dependencies, project config chan
 
 BEFORE implementing ANY task during the implement phase:
 
-1. **Read tasks.md** → identify the FR references for the current task (e.g., `[FR001, FR003]`)
-2. **Read spec.md** → the sections for those specific FRs
-3. **Read contracts.cs/.ts** → the DTOs/interfaces referenced by those FRs
+1. **Read tasks.json** → identify the current task object (`id`, `description`, `doneCriteria`, `dependencies`)
+2. **Read spec.md** → the FR sections that the task `description` references
+3. **Read the contracts** → the DTOs/interfaces are defined inside `spec.md` (v5 keeps contracts in the spec, not separate files)
 4. Only then begin implementation
 
 This is **NON-NEGOTIABLE**. The spec is the source of truth. Code that doesn't match the spec is a bug.
 
-Every task in `tasks.md` MUST have FR cross-references in this format:
-```
-### T001: Create user endpoint [FR001, FR003]
-- **Spec refs:** FR001 (user CRUD), FR003 (input validation)
-- **Contracts:** CreateUserRequest, CreateUserResponse, UserErrors
-- **Files:** Features/UserFeature/Create/Handler.cs, Validator.cs, Endpoint.cs
+Every task in `tasks.json` MUST reference its FR(s) in the `description` field so the link to the spec is explicit:
+```json
+{
+  "id": "T1",
+  "title": "Create user endpoint",
+  "description": "Implement user CRUD (FR001) and input validation (FR003). Contracts: CreateUserRequest, CreateUserResponse, UserErrors.",
+  "dependencies": [],
+  "effort": "M",
+  "doneCriteria": "POST /users creates a user and rejects invalid input",
+  "status": "pending",
+  "outputs": ["Features/UserFeature/Create/Handler.cs", "Validator.cs", "Endpoint.cs"],
+  "group": "backend"
+}
 ```
 
 ---

package/framework/skills/README.md

@@ -14,7 +14,7 @@ These are the only skills the harness needs. MORPH.md references them by path.
 |----------------------|----------------------------------------------------------------------|----------------|
 | `morph-brainstorming` | Business understanding + brownfield scan → proposal.md (Gate 1)     | yes            |
 | `morph-stack-scan`    | Detect stack drift in existing projects, generate migration-plan.md  | yes            |
-| `morph-plan`          | Produce spec.md + mandate.md + tasks.md (Gate 2)                     | yes            |
+| `morph-plan`          | Produce spec.md + mandate.md + tasks.json (Gate 2)                   | yes            |
 | `morph-implement`     | Execute each task with standard + persona, auto-advance between tasks| no             |
 | `morph-eval`          | Score work 0-10 across 4 dimensions, silence on score >= 8           | no             |
 | `morph-review`        | Final review report with scores + recommendation (Gate 3)            | yes            |

package/framework/skills/core/morph-apply/SKILL.md

@@ -4,6 +4,7 @@ description: Orquestra a execução autônoma de tasks de uma feature morph-spec
 version: core
 when-to-invoke: após Gate 2 aprovado, ao receber instrução "use /morph-apply" ou "implementar feature"
 user-invokable: true
+cliVersion: "7.3.0"
 ---
 
 # morph-apply

package/framework/skills/core/morph-brainstorming/SKILL.md

@@ -4,6 +4,7 @@ description: Entende o negócio, os usuários e a arquitetura antes de qualquer
 version: core
 when-to-invoke: ao receber um novo request de feature, antes de morph-plan
 user-invokable: true
+cliVersion: "7.3.0"
 ---
 
 # morph-brainstorming

package/framework/skills/core/morph-eval/SKILL.md

@@ -4,6 +4,7 @@ description: Avalia a qualidade de uma tarefa ou fase com rubricas graduadas 0-1
 version: core
 when-to-invoke: ao completar uma tarefa ou ao finalizar uma fase de implementação
 user-invokable: false
+cliVersion: "7.3.0"
 ---
 
 # morph-eval

package/framework/skills/core/morph-implement/SKILL.md

@@ -4,6 +4,7 @@ description: Guia a execução de cada tarefa de implementação com standard e
 version: core
 when-to-invoke: ao iniciar cada task de implementação listada em tasks.json
 user-invokable: false
+cliVersion: "7.3.0"
 ---
 
 # morph-implement
@@ -78,6 +79,12 @@ Ao iniciar cada task de `tasks.json` — antes de escrever qualquer código. Nor
    await writeTasksJson(tasksPath, data);
    ```
 
+   `tasks.json` é protegido após o Gate 2, mas os campos de progresso (`status`,
+   `outputs`, `notes`) continuam graváveis durante a fase implement. `writeTasksJson`
+   grava o arquivo **inteiro** (Write) — esse é o caminho permitido. Nunca use a
+   tool `Edit` em `tasks.json` após o Gate 2: o hook `protect-spec-files` bloqueia
+   Edit e qualquer mudança em campos de plano (`title`, `dependencies`, `doneCriteria`…).
+
 9. Quando invocada por `morph-apply`, retornar o controle à skill orquestradora — ela decide qual task vem em seguida via `getReadyTasks(data)`. Quando invocada manualmente, verificar se há próxima task ready e iniciá-la imediatamente aplicando esta skill desde o passo 1 (auto-advance). Pause apenas se encontrar ambiguidade bloqueante não coberta pelo mandate.
 
 ## Output esperado

package/framework/skills/core/morph-plan/SKILL.md

@@ -4,6 +4,7 @@ description: Guia a produção dos três artefatos de planejamento de uma featur
 version: core
 when-to-invoke: ao iniciar a fase plan de uma feature, após o Gate 1 (proposal aprovado)
 user-invokable: true
+cliVersion: "7.3.0"
 ---
 
 # morph-plan

package/framework/skills/core/morph-proposal/SKILL.md

@@ -4,6 +4,7 @@ description: Orquestra a fase de proposta+plano de uma feature morph-spec. Encad
 version: core
 when-to-invoke: ao receber instrução "use /morph-proposal" do usuário, ou ao iniciar uma nova feature
 user-invokable: true
+cliVersion: "7.3.0"
 ---
 
 # morph-proposal

package/framework/skills/core/morph-review/SKILL.md

@@ -4,6 +4,7 @@ description: Conduz a fase de revisão e produz o review-report.md para o Gate 3
 version: core
 when-to-invoke: ao iniciar a fase review, após todas as tasks de tasks.json estarem com status `done`
 user-invokable: true
+cliVersion: "7.3.0"
 ---
 
 # morph-review

package/framework/skills/core/morph-stack-scan/SKILL.md

@@ -4,6 +4,7 @@ description: Varre o codebase existente, detecta stack atual, compara com o stac
 version: core
 when-to-invoke: ao iniciar uma feature em projeto brownfield (codebase já existente)
 user-invokable: true
+cliVersion: "7.3.0"
 ---
 
 # morph-stack-scan

package/framework/skills/core/morph-standards/SKILL.md

@@ -4,6 +4,7 @@ description: Localiza e carrega um standard específico do STANDARDS.json sob de
 version: core
 when-to-invoke: quando precisar consultar um standard específico durante a implementação
 user-invokable: true
+cliVersion: "7.3.0"
 ---
 
 # morph-standards