@polymorphism-tech/morph-spec 7.1.1 → 7.3.0

package/README.md

@@ -3,7 +3,7 @@
 > Spec-driven development framework for multi-stack projects. Turns feature requests into implementation-ready code through structured, AI-orchestrated phases.
 
 **Package:** `@polymorphism-tech/morph-spec`
-**Version:** 7.1.1  
+**Version:** 7.3.0  
 **Requires:** Node.js 22+, Claude Code
 
 ---
@@ -365,4 +365,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v7.1.1 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v7.3.0 by [Polymorphism Tech](https://polymorphism.tech)*

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "7.1.1",
+  "version": "7.3.0",
   "displayName": "MORPH-SPEC Framework",
   "description": "Spec-driven development with 38 agents and 8-phase workflow for .NET/Blazor/Next.js/Azure",
   "publisher": "polymorphism-tech",

package/docs/CHEATSHEET.md

@@ -196,4 +196,4 @@ These files are never edited directly. Use CLI commands or `morph-spec update` i
 
 ---
 
-*morph-spec v7.1.1 by Polymorphism Tech*
+*morph-spec v7.3.0 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -197,4 +197,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v7.1.1 by Polymorphism Tech*
+*morph-spec v7.3.0 by Polymorphism Tech*

package/framework/CLAUDE.md

@@ -14,12 +14,14 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 
 **NUNCA:**
 - Pular para código sem proposal aprovado (Gate 1) e plano aprovado (Gate 2).
-- Modificar `spec.md`, `mandate.md`, `tasks.md` depois do Gate 2 — eles estão congelados.
+- Modificar o contrato do plano depois do Gate 2: `spec.md`, `mandate.md`, e os campos de plano de `tasks.json` (`title`, `description`, `dependencies`, `effort`, `doneCriteria`, `group`) estão congelados.
+- Usar `Edit` em `tasks.json` após o Gate 2 — o arquivo é gravado inteiro via `writeTasksJson` (Write). O hook `protect-spec-files` bloqueia `Edit`.
 - Listar perguntas em texto simples — sempre use a tool `AskUserQuestion` (1-4 perguntas por chamada).
 - Usar `Guid.NewGuid()`, classes não-sealed sem justificativa, exceptions como fluxo de controle, camada de Service/Manager entre handler e dados, ou SQL cru sem justificativa.
 
 **SEMPRE:**
 - Auto-advance entre tarefas durante a fase implement — não pause sem ambiguidade bloqueante.
+- Atualizar o progresso em `tasks.json` via `writeTasksJson` ao concluir cada task — apenas os campos `status`, `outputs` e `notes` mudam; o contrato do plano permanece congelado.
 - Apresentar gates com o template fixo definido em MORPH.md / morph-plan.
 - Registrar decisões não triviais em `decisions.md`.
 - Aplicar `morph-eval` após cada tarefa; silêncio em score ≥ 8 é o sinal correto.
@@ -41,7 +43,7 @@ Se não houver feature ativa, pergunte ao usuário qual feature trabalhar.
 |-------|-------------|
 | `morph-brainstorming` | Entender negócio, escanear stack, produzir proposal.md |
 | `morph-stack-scan` | Detectar desvios de stack em projeto brownfield |
-| `morph-plan` | Produzir spec.md + mandate.md + tasks.md |
+| `morph-plan` | Produzir spec.md + mandate.md + tasks.json |
 | `morph-implement` | Executar uma tarefa com auto-advance entre tasks |
 | `morph-eval` | Aplicar rubricas e produzir score 0-10 |
 | `morph-review` | Produzir review-report.md (Gate 3) |

package/framework/MORPH.md

@@ -64,8 +64,8 @@ Responsabilidades: ler o mandato, entender o escopo, propor o plano de ataque, i
 Anti-padrão: o Orchestrator não escreve código. Se você está no papel de Orchestrator e percebe que começou a implementar algo, pare — você transitou de papel sem intenção, e o plano provavelmente ainda não está fechado.
 
 **Specialist** — ativo durante a fase de implementação.
-Responsabilidades: executar tarefas do tasks.md em ordem, consultar standards relevantes antes de cada tarefa, registrar decisões e desvios no decisions.md, manter o recap.md atualizado ao final de cada tarefa.
-Anti-padrão: o Specialist não cria novas tarefas. Descobertas de escopo durante a implementação vão para o decisions.md com flag "escopo expandido" — o Orchestrator avalia se o tasks.md precisa ser atualizado.
+Responsabilidades: executar tarefas do tasks.json em ordem, consultar standards relevantes antes de cada tarefa, registrar decisões e desvios no decisions.md, manter o recap.md atualizado ao final de cada tarefa.
+Anti-padrão: o Specialist não cria novas tarefas. Descobertas de escopo durante a implementação vão para o decisions.md com flag "escopo expandido" — o Orchestrator avalia se o tasks.json precisa ser atualizado.
 
 **Evaluator** — ativo após uma tarefa ou fase ser concluída.
 Responsabilidades: aplicar as rubricas em `framework/evals/rubrics/`, produzir score 0-10, emitir feedback priorizado quando score < 8, escalar para revisão humana quando score < 6.
@@ -201,7 +201,7 @@ Despache um sub-agent quando a tarefa atende a pelo menos um dos critérios abai
 - Risco de "contaminar" o contexto principal com detalhes de baixo nível irrelevantes para o fluxo
 
 **O que passar ao sub-agent:**
-- Especificação da tarefa (do tasks.md)
+- Especificação da tarefa (do tasks.json)
 - Path do standard relevante (apenas um)
 - Lista de arquivos que ele precisa ler ou modificar
 - Critério de done claro e verificável

package/framework/commands/morph-apply.md

@@ -25,7 +25,7 @@ Se algum estiver faltando, abortar e pedir ao usuário para rodar `/morph-propos
 
 ## Anti-padrões
 
-- Não pausar entre tarefas para confirmação — o tasks.md já foi aprovado no Gate 2.
+- Não pausar entre tarefas para confirmação — o tasks.json já foi aprovado no Gate 2.
 - Não escrever código fora de `3-implement/` ou da source tree do projeto.
 - Não modificar `spec.md` ou `mandate.md` durante a implementação — esses arquivos foram congelados pelo Gate 2.
 

package/framework/commands/morph-proposal.md

@@ -32,7 +32,7 @@ Conduz a feature do request inicial até o Gate 2 (plano aprovado), sem interven
 
 4. **Após Gate 1, invocar `morph-plan`** (skill em `framework/skills/core/morph-plan/`):
    - Lê `proposal.md`.
-   - Produz `spec.md`, `mandate.md`, `tasks.md` em `.morph/features/{feature-name}/2-plan/`.
+   - Produz `spec.md`, `mandate.md`, `tasks.json` em `.morph/features/{feature-name}/2-plan/`.
    - Apresenta o **Gate 2** com template fixo (ver SKILL.md passo 5).
 
 5. **Aguardar aprovação do Gate 2.**

package/framework/hooks/README.md

@@ -128,7 +128,7 @@ Claude Code sends JSON to stdin: { tool_input: { file_path: "..." } }
 protect-spec-files.js
     ├── Is in .morph/features/{feature}/?
     │   ├── Is spec.md and design gate approved? → BLOCK
-    │   ├── Is tasks.md and tasks gate approved? → BLOCK
+    │   ├── Is tasks.json and tasks gate approved? → BLOCK
     │   └── Gate not approved → pass
     └── Not a feature file → pass
     ↓

package/framework/hooks/claude-code/core/protect-spec-files.js

@@ -1,72 +1,193 @@
-#!/usr/bin/env node
-
-/**
- * PreToolUse Hook: Protect Approved Spec Files
- *
- * Event: PreToolUse | Matcher: Write|Edit
- *
- * Blocks Write/Edit to spec artifacts after their approval gate has passed:
- *   - 2-plan/spec.md, contracts.cs, tasks.md, etc. → blocked if 'plan' gate approved
- *   - 1-design/design-system.md, etc. → blocked if 'uiux' gate approved
- *
- * Fail-open: exits 0 on any error.
- */
-
-import { readStdin } from '../../shared/stdin-reader.js';
-import { stateExists, isGateApproved } from '../../shared/state-reader.js';
-import {
-  isFeaturePath,
-  extractFeatureName,
-  getBasename,
-  PROTECTED_SPEC_FILES
-} from '../../shared/phase-utils.js';
-import { block, pass } from '../../shared/hook-response.js';
-import { logHookActivity } from '../../shared/activity-logger.js';
-import { getFilePath } from '../../shared/payload-utils.js';
-
-try {
-  // Amend mode: bypass spec protection for legitimate in-implementation corrections
-  if (process.env.MORPH_AMEND_PHASE) {
-    console.error(`[morph-spec] AMEND MODE: bypassing spec protection for phase '${process.env.MORPH_AMEND_PHASE}'`);
-    pass();
-  }
-
-  if (!stateExists()) pass();
-
-  const payload = await readStdin();
-  if (!payload) pass();
-
-  const filePath = getFilePath(payload);
-  if (!filePath) pass();
-
-  // Only check files inside .morph/features/
-  if (!isFeaturePath(filePath)) pass();
-
-  const featureName = extractFeatureName(filePath);
-  if (!featureName) pass();
-
-  const filename = getBasename(filePath);
-  const requiredGate = PROTECTED_SPEC_FILES[filename];
-
-  // Not a protected file
-  if (!requiredGate) pass();
-
-  // Check if the gate has been approved
-  if (isGateApproved(featureName, requiredGate)) {
-    logHookActivity('protect-spec-files', 'PreToolUse', 'blocked');
-    block(
-      `MORPH-SPEC: '${filename}' is locked — the '${requiredGate}' gate has been approved.\n` +
-      `Editing approved specs breaks the spec contract.\n\n` +
-      `If changes are truly needed, ask the user to revoke the gate approval\n` +
-      `in .morph/state.json (set approvals.${requiredGate} to false), make\n` +
-      `your edits, then re-present the gate for approval.`
-    );
-  }
-
-  // Gate not yet approved — allow editing
-  logHookActivity('protect-spec-files', 'PreToolUse', 'ok');
-  pass();
-} catch {
-  // Fail-open
-  process.exit(0);
-}
+#!/usr/bin/env node
+
+/**
+ * PreToolUse Hook: Protect Approved Spec Files
+ *
+ * Event: PreToolUse | Matcher: Write|Edit
+ *
+ * Blocks Write/Edit to spec artifacts after their approval gate has passed:
+ *   - 2-plan/spec.md, mandate.md, etc. → blocked if 'plan' gate approved
+ *   - 1-design/design-system.md, etc. → blocked if 'uiux' gate approved
+ *
+ * Semantic exception for files in MUTABLE_SPEC_FIELDS (e.g. tasks.json):
+ * the plan contract is frozen, but per-task progress fields (status, outputs,
+ * notes) may still change during the implement phase. For those files a Write
+ * is allowed only when the semantic diff touches solely the mutable fields;
+ * Edit is always blocked because the legitimate progress path is a full Write
+ * via writeTasksJson(). This lets the implement phase record task status
+ * without unfreezing the plan.
+ *
+ * Fail-open: exits 0 on any error.
+ */
+
+import { readFileSync } from 'fs';
+import { isAbsolute, join } from 'path';
+import { readStdin } from '../../shared/stdin-reader.js';
+import { stateExists, isGateApproved } from '../../shared/state-reader.js';
+import {
+  isFeaturePath,
+  extractFeatureName,
+  getBasename,
+  PROTECTED_SPEC_FILES,
+  MUTABLE_SPEC_FIELDS
+} from '../../shared/phase-utils.js';
+import { block, pass } from '../../shared/hook-response.js';
+import { logHookActivity } from '../../shared/activity-logger.js';
+import { getFilePath, getToolName } from '../../shared/payload-utils.js';
+
+/**
+ * Compare two tasks.json structures and return the list of plan-contract
+ * violations — changes that touch anything other than the mutable fields.
+ *
+ * @param {object} oldDoc - parsed previous file content
+ * @param {object} newDoc - parsed proposed file content
+ * @param {string[]} mutableFields - field names allowed to change
+ * @returns {string[]} human-readable violation messages (empty = OK)
+ */
+function diffPlanContract(oldDoc, newDoc, mutableFields) {
+  const violations = [];
+  const mutable = new Set(mutableFields);
+
+  if (oldDoc.version !== newDoc.version) {
+    violations.push(`'version' changed (${oldDoc.version} → ${newDoc.version})`);
+  }
+  if (oldDoc.feature !== newDoc.feature) {
+    violations.push(`'feature' changed (${oldDoc.feature} → ${newDoc.feature})`);
+  }
+
+  const oldTasks = Array.isArray(oldDoc.tasks) ? oldDoc.tasks : [];
+  const newTasks = Array.isArray(newDoc.tasks) ? newDoc.tasks : [];
+
+  if (oldTasks.length !== newTasks.length) {
+    violations.push(`task count changed (${oldTasks.length} → ${newTasks.length}) — tasks cannot be added or removed`);
+  }
+
+  const oldById = new Map(oldTasks.map(t => [t.id, t]));
+  const newById = new Map(newTasks.map(t => [t.id, t]));
+
+  // A task present before must still exist (no removals / id renames).
+  for (const id of oldById.keys()) {
+    if (!newById.has(id)) violations.push(`task '${id}' was removed`);
+  }
+  for (const id of newById.keys()) {
+    if (!oldById.has(id)) violations.push(`task '${id}' was added`);
+  }
+
+  // For tasks present on both sides, only mutable fields may differ.
+  for (const [id, newTask] of newById) {
+    const oldTask = oldById.get(id);
+    if (!oldTask) continue;
+    const keys = new Set([...Object.keys(oldTask), ...Object.keys(newTask)]);
+    for (const key of keys) {
+      if (mutable.has(key)) continue;
+      if (JSON.stringify(oldTask[key]) !== JSON.stringify(newTask[key])) {
+        violations.push(`task '${id}': immutable field '${key}' changed`);
+      }
+    }
+  }
+
+  return violations;
+}
+
+try {
+  // Amend mode: bypass spec protection for legitimate in-implementation corrections
+  if (process.env.MORPH_AMEND_PHASE) {
+    console.error(`[morph-spec] AMEND MODE: bypassing spec protection for phase '${process.env.MORPH_AMEND_PHASE}'`);
+    pass();
+  }
+
+  if (!stateExists()) pass();
+
+  const payload = await readStdin();
+  if (!payload) pass();
+
+  const filePath = getFilePath(payload);
+  if (!filePath) pass();
+
+  // Only check files inside .morph/features/
+  if (!isFeaturePath(filePath)) pass();
+
+  const featureName = extractFeatureName(filePath);
+  if (!featureName) pass();
+
+  const filename = getBasename(filePath);
+  const requiredGate = PROTECTED_SPEC_FILES[filename];
+
+  // Not a protected file
+  if (!requiredGate) pass();
+
+  // Gate not yet approved — allow editing
+  if (!isGateApproved(featureName, requiredGate)) {
+    logHookActivity('protect-spec-files', 'PreToolUse', 'ok');
+    pass();
+  }
+
+  // ── Gate approved — file is locked ──────────────────────────────────────
+  const mutableFields = MUTABLE_SPEC_FIELDS[filename];
+
+  // Files with mutable progress fields (e.g. tasks.json): allow a full Write
+  // that touches only those fields. Anything else stays blocked.
+  if (mutableFields) {
+    const toolName = getToolName(payload);
+    const newContent = payload?.tool_input?.content;
+
+    // Edit is never the legitimate progress path — progress is written as a
+    // full file via writeTasksJson(). Block Edit; fall through to the message.
+    if (toolName !== 'Write' || typeof newContent !== 'string') {
+      logHookActivity('protect-spec-files', 'PreToolUse', 'blocked');
+      block(
+        `MORPH-SPEC: '${filename}' is locked — the '${requiredGate}' gate has been approved.\n` +
+        `Progress updates (${mutableFields.join(', ')}) must be written as a full-file\n` +
+        `Write, not an Edit. The plan contract (titles, dependencies, doneCriteria…)\n` +
+        `is frozen. To change the plan itself, ask the user to revoke the\n` +
+        `'${requiredGate}' gate in .morph/state.json, then re-present it for approval.`
+      );
+    }
+
+    // Semantic diff: old = current file on disk, new = proposed content.
+    // Any failure to read/parse → fail-open (pass), never a false block.
+    let oldDoc, newDoc;
+    try {
+      // filePath may already be absolute (Claude Code usually sends absolute
+      // paths); only join against cwd when it is relative.
+      const absPath = isAbsolute(filePath) ? filePath : join(process.cwd(), filePath);
+      oldDoc = JSON.parse(readFileSync(absPath, 'utf-8'));
+      newDoc = JSON.parse(newContent);
+    } catch {
+      // Cannot compare — fail-open rather than block a possibly-valid write.
+      logHookActivity('protect-spec-files', 'PreToolUse', 'ok');
+      pass();
+    }
+
+    const violations = diffPlanContract(oldDoc, newDoc, mutableFields);
+    if (violations.length === 0) {
+      // Only mutable progress fields changed — this is a legitimate
+      // implement-phase update.
+      logHookActivity('protect-spec-files', 'PreToolUse', 'ok');
+      pass();
+    }
+
+    logHookActivity('protect-spec-files', 'PreToolUse', 'blocked');
+    block(
+      `MORPH-SPEC: '${filename}' is locked — the '${requiredGate}' gate has been approved.\n` +
+      `This Write changes the frozen plan contract:\n` +
+      violations.map(v => `  • ${v}`).join('\n') + '\n\n' +
+      `During the implement phase only these fields may change: ${mutableFields.join(', ')}.\n` +
+      `To change the plan itself, ask the user to revoke the '${requiredGate}' gate\n` +
+      `in .morph/state.json, then re-present it for approval.`
+    );
+  }
+
+  // Fully-locked file (spec.md, mandate.md, design files): blanket block.
+  logHookActivity('protect-spec-files', 'PreToolUse', 'blocked');
+  block(
+    `MORPH-SPEC: '${filename}' is locked — the '${requiredGate}' gate has been approved.\n` +
+    `Editing approved specs breaks the spec contract.\n\n` +
+    `If changes are truly needed, ask the user to revoke the gate approval\n` +
+    `in .morph/state.json (set approvals.${requiredGate} to false), make\n` +
+    `your edits, then re-present the gate for approval.`
+  );
+} catch {
+  // Fail-open
+  process.exit(0);
+}