@polymorphism-tech/morph-spec 7.1.1 → 7.2.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.2.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.2.0 by [Polymorphism Tech](https://polymorphism.tech)*

package/claude-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "morph-spec",
-  "version": "7.1.1",
+  "version": "7.2.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.2.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.2.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.

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/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);
+}

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/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/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.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.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.2.0"
 ---
 
 # morph-standards

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polymorphism-tech/morph-spec",
-  "version": "7.1.1",
+  "version": "7.2.0",
   "description": "MORPH-SPEC: NLH (Natural Language Harness) for spec-driven development with Claude Code",
   "keywords": [
     "claude-code",

package/src/core/paths/output-schema.js

@@ -20,6 +20,11 @@ import { join } from 'path';
  *   phase        - The morph-spec phase that produces this output
  *   protected    - Whether the file requires an approval gate before editing
  *   approvalGate - (optional) Which gate protects this file
+ *   mutableFields- (optional) For protected JSON files: top-level array-item
+ *                  field names that MAY still change after the gate is approved.
+ *                  Lets the implement phase update task progress without
+ *                  unfreezing the plan contract. When present, the protect
+ *                  hook does a semantic diff instead of a blanket block.
  */
 export const OUTPUT_SCHEMA = {
   // 0-proposal/
@@ -36,7 +41,7 @@ export const OUTPUT_SCHEMA = {
   // 2-plan/
   spec:           { filename: 'spec.md',               phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan' },
   mandate:        { filename: 'mandate.md',            phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan' },
-  tasks:          { filename: 'tasks.json',            phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan' },
+  tasks:          { filename: 'tasks.json',            phaseDir: '2-plan',      phase: 'plan',      protected: true,  approvalGate: 'plan', mutableFields: ['status', 'outputs', 'notes'] },
   decisions:      { filename: 'decisions.md',          phaseDir: '2-plan',      phase: 'plan',      protected: false },
 
   // 3-implement/
@@ -119,6 +124,18 @@ export const PROTECTED_SPEC_FILES = Object.fromEntries(
     .map(([, entry]) => [entry.filename, entry.approvalGate])
 );
 
+/**
+ * For protected files that carry mutable progress fields: filename → the
+ * top-level array-item fields that may change after the gate is approved.
+ * The protect-spec-files hook uses this to allow progress updates (e.g.
+ * task status) while still freezing the plan contract.
+ */
+export const MUTABLE_SPEC_FIELDS = Object.fromEntries(
+  Object.entries(OUTPUT_SCHEMA)
+    .filter(([, entry]) => entry.protected && entry.approvalGate && entry.mutableFields)
+    .map(([, entry]) => [entry.filename, entry.mutableFields])
+);
+
 // ============================================================================
 // Backwards-compat shim (will be removed in v5.1)
 // ============================================================================