@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/framework/hooks/claude-code/core/trace-autogen.js

@@ -1,277 +0,0 @@
-#!/usr/bin/env node
-/**
- * trace-autogen.js — PostToolUse hook (Write|Edit)
- *
- * Auto-generates the execution trace
- * `.morph/traces/YYYY-MM-DD-{feature}-implement.json` from tasks.json +
- * recap.md whenever tasks.json is written during
- * the implement phase.
- *
- * This removes the manual trace-writing step from the skills (friction item
- * observed in MORPH_GHLBrain 2026-07-11: 5 writes per task). The tasks.json
- * status flip — the last write of every task's ceremony — now produces the
- * trace for free: deterministic, idempotent, always in sync with the real
- * on-disk state. The skills must NOT write traces by hand anymore.
- *
- * Sources:
- *  - tasks.json      → task set, status (done→completed, skipped→skipped,
- *                      blocked→failed; pending/in_progress stay out), outputs
- *  - recap.md        → per-task `**Standard:**` id and `**Persona:**` line
- *
- * The most recent existing `*-{feature}-implement.json` is updated in place
- * (session_id/started_at preserved); a new dated file is created otherwise.
- * `completed_at` + phase_summary are stamped when no task is left
- * pending/in_progress. Fail-open: any error exits 0 silently.
- *
- * This is also the vantage point for TaskStart/TaskEnd telemetry: a
- * pending→in_progress flip and a flip to done/skipped are the only two task
- * transitions the harness can observe (tasks.json is the single place task
- * status is written), so this hook diffs each task's previous status against
- * `.morph/logs/task-times.json` and appends the matching event via the shared
- * telemetry logger (see `updateTaskTimes` below). The same start/end pair
- * feeds `duration_seconds` in the trace entry.
- */
-
-import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'fs';
-import { join } from 'path';
-import { runStandalone } from '../../shared/hook-response.js';
-import { stateExists } from '../../shared/state-reader.js';
-import { getFilePath, resolveMorphRoot } from '../../shared/payload-utils.js';
-import { appendTelemetryEvent } from '../../shared/telemetry-logger.js';
-
-function projectDir() {
-  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
-}
-
-function extractFeature(filePath) {
-  const normalized = String(filePath).replace(/\\/g, '/');
-  const match = normalized.match(/\.morph\/features\/([^/]+)\/2-plan\/tasks\.json$/);
-  return match ? match[1] : null;
-}
-
-/**
- * Parse recap.md task blocks (`## T{N} — ...`) into
- * { [id]: { standard, persona } }. Best-effort: missing fields stay null.
- */
-function parseRecap(raw) {
-  const map = {};
-  const blocks = String(raw).split(/^## (?=T\d+)/m).slice(1);
-  for (const block of blocks) {
-    const id = (block.match(/^(T\d+)/) ?? [])[1];
-    if (!id) continue;
-    const standard = (block.match(/\*\*Standard:\*\*\s*([^\s(]+)/) ?? [])[1] ?? null;
-    const persona = (block.match(/\*\*Persona:\*\*\s*(.+)$/m) ?? [])[1]?.trim() ?? null;
-    map[id] = { standard, persona };
-  }
-  return map;
-}
-
-/** session_id in the trace-schema format YYYY-MM-DD-HH-MM-SS. */
-function sessionId(d) {
-  const p = (n) => String(n).padStart(2, '0');
-  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}-${p(d.getHours())}-${p(d.getMinutes())}-${p(d.getSeconds())}`;
-}
-
-/** tasks.json status → trace-schema status. Unsettled statuses are omitted. */
-const STATUS_MAP = { done: 'completed', skipped: 'skipped', blocked: 'failed' };
-
-const TASK_TIMES_PATH = join('.morph', 'logs', 'task-times.json');
-
-/**
- * Read `.morph/logs/task-times.json`: `{ [feature]: { [taskId]: { status,
- * start?, end? } } }`. Nested by feature — not flat by task id, as a literal
- * reading of "keyed by taskId" might suggest — because task ids (T1, T2…)
- * are only unique WITHIN a feature; a flat map would let two sibling
- * features in the same tree (see worktree-state-resolution.test.js for that
- * shape) clobber each other's start/end timestamps.
- * Fail-open: a missing/corrupt file reads as {}.
- */
-function readTaskTimes(root) {
-  const p = join(root, TASK_TIMES_PATH);
-  if (!existsSync(p)) return {};
-  try {
-    return JSON.parse(readFileSync(p, 'utf8'));
-  } catch {
-    return {};
-  }
-}
-
-function writeTaskTimes(root, allTimes) {
-  mkdirSync(join(root, '.morph', 'logs'), { recursive: true });
-  writeFileSync(join(root, TASK_TIMES_PATH), JSON.stringify(allTimes, null, 2), 'utf8');
-}
-
-/**
- * Diff each task's PREVIOUS status (from `times`, this feature's slice of
- * task-times.json) against its status in the tasks.json that was just
- * written, and append the matching telemetry event via the shared logger —
- * same shape/mechanism as every other event in events.jsonl, just a
- * different `event` value.
- *
- *  - pending → in_progress   ⇒ TaskStart, stamp `start`
- *  - anything → done/skipped ⇒ TaskEnd (carries the new status), stamp `end`
- *  - first sight of a task id (no prior entry) only seeds the baseline,
- *    silently — there is no prior status to diff, and emitting an event here
- *    would fabricate a transition that never happened (e.g. a task whose
- *    first-ever tasks.json write already shows it `done`, from historical
- *    data predating this file).
- *
- * Mutates `times` in place and returns whether anything changed, so the
- * caller only rewrites task-times.json when needed and the entries built
- * right after this call see the freshly-stamped start/end for
- * `duration_seconds`.
- */
-function updateTaskTimes(times, tasks, feature, root, nowIso) {
-  let changed = false;
-  for (const t of tasks) {
-    const prev = times[t.id];
-    if (!prev) {
-      times[t.id] = { status: t.status };
-      changed = true;
-      continue;
-    }
-    if (prev.status === t.status) continue;
-
-    if (prev.status === 'pending' && t.status === 'in_progress') {
-      appendTelemetryEvent({ event: 'TaskStart', feature, task: t.id, phase: 'implement' }, root);
-      times[t.id] = { ...prev, status: t.status, start: nowIso };
-    } else if (t.status === 'done' || t.status === 'skipped') {
-      appendTelemetryEvent({ event: 'TaskEnd', feature, task: t.id, status: t.status, phase: 'implement' }, root);
-      times[t.id] = { ...prev, status: t.status, end: nowIso };
-    } else {
-      times[t.id] = { ...prev, status: t.status };
-    }
-    changed = true;
-  }
-  return changed;
-}
-
-/** Seconds between recorded start/end for a task, or null when either is missing. */
-function taskDuration(times, taskId) {
-  const rec = times[taskId];
-  if (!rec?.start || !rec?.end) return null;
-  const secs = (new Date(rec.end).getTime() - new Date(rec.start).getTime()) / 1000;
-  return Number.isFinite(secs) ? Math.round(secs * 10) / 10 : null;
-}
-
-/**
- * @param {object} payload - parsed PostToolUse stdin payload (Write|Edit)
- * @returns {Promise<null>} always null — this hook is pure side-effect (trace
- *   file + task-times.json), never prints/injects context.
- */
-export async function run(payload) {
-  try {
-    await generateTrace(payload);
-  } catch {
-    // Fail-open
-  }
-  return null;
-}
-
-async function generateTrace(payload) {
-  if (!payload) return;
-
-  const filePath = getFilePath(payload);
-  const feature = filePath ? extractFeature(filePath) : null;
-  if (!feature) return;
-
-  // Read the sources — and write the trace — in the tree that owns the written
-  // tasks.json. Resolving from the session instead made this hook INERT for
-  // every worktree feature: the root's copy of the feature has no
-  // `2-plan/tasks.json`, so the `existsSync` guard below returned silently and
-  // no trace was ever produced for work done in a worktree.
-  const cwd = resolveMorphRoot(filePath, projectDir());
-  if (!stateExists(cwd)) return;
-
-  const featureDir = join(cwd, '.morph', 'features', feature);
-  const tasksPath = join(featureDir, '2-plan', 'tasks.json');
-  if (!existsSync(tasksPath)) return;
-  const tasksDoc = JSON.parse(readFileSync(tasksPath, 'utf8'));
-  const tasks = Array.isArray(tasksDoc.tasks) ? tasksDoc.tasks : [];
-
-  const now = new Date();
-
-  // TaskStart/TaskEnd telemetry + duration_seconds source: diff each task's
-  // previous status (persisted below) against the status just written.
-  const allTimes = readTaskTimes(cwd);
-  const times = allTimes[feature] ?? (allTimes[feature] = {});
-  if (updateTaskTimes(times, tasks, feature, cwd, now.toISOString())) {
-    writeTaskTimes(cwd, allTimes);
-  }
-
-  let recap = {};
-  const recapPath = join(featureDir, '3-implement', 'recap.md');
-  if (existsSync(recapPath)) {
-    try { recap = parseRecap(readFileSync(recapPath, 'utf8')); } catch { recap = {}; }
-  }
-
-  const tracesDir = join(cwd, '.morph', 'traces');
-  mkdirSync(tracesDir, { recursive: true });
-
-  // Multi-session phases update the same file incrementally (trace-schema):
-  // reuse the most recent trace for this feature+phase if one exists.
-  const suffix = `-${feature}-implement.json`;
-  const existing = readdirSync(tracesDir)
-    .filter(f => /^\d{4}-\d{2}-\d{2}-/.test(f) && f.endsWith(suffix))
-    .sort()
-    .pop();
-
-  let previous = null;
-  if (existing) {
-    try { previous = JSON.parse(readFileSync(join(tracesDir, existing), 'utf8')); } catch { previous = null; }
-  }
-
-  const fileName = existing ?? `${now.toISOString().slice(0, 10)}${suffix}`;
-
-  const entries = tasks
-    .filter(t => STATUS_MAP[t.status])
-    .map(t => {
-      const recapEntry = recap[t.id] ?? {};
-      return {
-        id: t.id,
-        title: t.title ?? null,
-        status: STATUS_MAP[t.status],
-        standards_consulted: recapEntry.standard ? [recapEntry.standard] : [],
-        agent_persona: recapEntry.persona ?? null,
-        sub_agent_dispatched: recapEntry.persona
-          ? /^morph-|general-purpose/.test(recapEntry.persona)
-          : false,
-        files_modified: Array.isArray(t.outputs) ? t.outputs.filter(o => typeof o === 'string') : [],
-        duration_seconds: taskDuration(times, t.id),
-      };
-    });
-
-  const allSettled = tasks.length > 0 &&
-    tasks.every(t => t.status !== 'pending' && t.status !== 'in_progress');
-
-  const standardCounts = {};
-  for (const entry of entries) {
-    for (const std of entry.standards_consulted) {
-      standardCounts[std] = (standardCounts[std] ?? 0) + 1;
-    }
-  }
-  const mostUsed = Object.entries(standardCounts)
-    .sort((a, b) => b[1] - a[1])
-    .slice(0, 3)
-    .map(([std]) => std);
-
-  const trace = {
-    schema_version: '1.0',
-    session_id: previous?.session_id ?? sessionId(now),
-    feature,
-    phase: 'implement',
-    started_at: previous?.started_at ?? now.toISOString(),
-    completed_at: allSettled ? (previous?.completed_at ?? now.toISOString()) : null,
-    tasks: entries,
-    phase_summary: {
-      tasks_completed: entries.filter(e => e.status === 'completed').length,
-      tasks_failed: entries.filter(e => e.status === 'failed').length,
-      standards_most_used: mostUsed,
-      sub_agents_dispatched: entries.filter(e => e.sub_agent_dispatched).length,
-    },
-  };
-
-  writeFileSync(join(tracesDir, fileName), JSON.stringify(trace, null, 2), 'utf8');
-}
-
-await runStandalone(run);

package/framework/hooks/git/pre-commit/specs.sh

@@ -1,50 +0,0 @@
-#!/bin/bash
-# Scope: universal | Validates spec.md required sections
-# MORPH-SPEC Pre-Commit Hook: Spec Validation
-# Validates that spec.md files have required sections
-
-echo "🔍 Validating spec files..."
-
-# Find modified spec.md files
-SPEC_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep 'spec\.md$')
-
-if [ -z "$SPEC_FILES" ]; then
-  echo "✓ No spec files modified"
-  exit 0
-fi
-
-HAS_ERRORS=false
-
-for spec_file in $SPEC_FILES; do
-  echo "Checking: $spec_file"
-
-  # Required sections
-  REQUIRED_SECTIONS=(
-    "## 📋 Metadata"
-    "## 🎯 Overview"
-    "## 🏗️ Technical Design"
-    "## ✅ Acceptance Criteria"
-  )
-
-  for section in "${REQUIRED_SECTIONS[@]}"; do
-    if ! grep -q "$section" "$spec_file"; then
-      echo "  ❌ Missing section: $section"
-      HAS_ERRORS=true
-    fi
-  done
-
-  # Check if has at least one user story or requirement
-  if ! grep -qi "user story\|requirement\|acceptance criteria" "$spec_file"; then
-    echo "  ⚠️  Warning: No user stories or requirements found"
-  fi
-done
-
-if [ "$HAS_ERRORS" = true ]; then
-  echo ""
-  echo "❌ COMMIT BLOCKED: spec.md files are incomplete"
-  echo "   Add missing sections before committing"
-  exit 1
-fi
-
-echo "✓ All spec files are valid"
-exit 0

package/framework/hooks/shared/tasks-validator.js

@@ -1,111 +0,0 @@
-/**
- * tasks-validator.js — minimal hook-side schema validation for tasks.json.
- *
- * Mirrors VALID_STATUS / VALID_EFFORT from src/lib/tasks/tasks-json-parser.js.
- * Hooks are installed standalone into target projects (.morph/framework/hooks/),
- * so they cannot import from src/ — the enum lives here, duplicated on purpose
- * and covered by tests on both sides.
- */
-
-export const VALID_TASK_STATUS = ['pending', 'in_progress', 'done', 'skipped', 'blocked'];
-export const VALID_TASK_EFFORT = ['S', 'M', 'L', 'XL'];
-
-/**
- * Validate the parts of a tasks.json document that hooks care about:
- * a tasks[] array whose entries carry a valid status (and effort, when set).
- * The production failure this guards: a leaf agent writing status "completed"
- * (not in the enum) without any validation.
- *
- * @param {object} doc - parsed tasks.json
- * @returns {{ valid: boolean, errors: string[] }}
- */
-/** Human-readable type name for error messages ('array', not 'object'). */
-function typeName(value) {
-  return Array.isArray(value) ? 'array' : typeof value;
-}
-
-export function validateTasksDoc(doc) {
-  if (!doc || typeof doc !== 'object' || !Array.isArray(doc.tasks)) {
-    return { valid: false, errors: ['tasks.json must be an object with a tasks[] array'] };
-  }
-
-  const errors = [];
-  for (const task of doc.tasks) {
-    const id = task?.id ?? '?';
-    if (!VALID_TASK_STATUS.includes(task?.status)) {
-      errors.push(`task '${id}': invalid status '${task?.status}' (valid: ${VALID_TASK_STATUS.join(', ')})`);
-    }
-    if (task?.effort !== undefined && !VALID_TASK_EFFORT.includes(task.effort)) {
-      errors.push(`task '${id}': invalid effort '${task.effort}' (valid: ${VALID_TASK_EFFORT.join(', ')})`);
-    }
-    // Mutable-field type checks with the exact field/value in the message —
-    // a malformed notes/outputs used to surface as the misleading generic
-    // "notes is empty" downstream (MORPH_GHLBrain 2026-07-11).
-    if (task?.notes !== undefined && typeof task.notes !== 'string') {
-      errors.push(`task '${id}': 'notes' must be a string (got ${typeName(task.notes)})`);
-    }
-    if (task?.outputs !== undefined) {
-      if (!Array.isArray(task.outputs)) {
-        errors.push(`task '${id}': 'outputs' must be an array of path strings (got ${typeName(task.outputs)})`);
-      } else {
-        task.outputs.forEach((entry, i) => {
-          if (typeof entry !== 'string') {
-            errors.push(`task '${id}': outputs[${i}] must be a string path (got ${typeName(entry)})`);
-          }
-        });
-      }
-    }
-  }
-  return { valid: errors.length === 0, errors };
-}
-
-/**
- * Planned-vs-real outputs divergence: tasks whose `outputs` changed relative
- * to the previous document but whose `notes` is still empty. The divergence
- * itself is legitimate (outputs is a mutable progress field) — shipping it
- * without an explanatory note is what gets flagged.
- *
- * @param {object} oldDoc - parsed previous tasks.json
- * @param {object} newDoc - parsed proposed tasks.json
- * @returns {string[]} human-readable violation messages (empty = OK)
- */
-/** Compact outputs rendering for messages, capped so huge arrays stay readable. */
-function fmtOutputs(outputs) {
-  const s = JSON.stringify(outputs ?? []);
-  return s.length > 120 ? s.slice(0, 117) + '...' : s;
-}
-
-export function outputsDivergenceViolations(oldDoc, newDoc) {
-  const violations = [];
-  const oldById = new Map((oldDoc?.tasks ?? []).map(t => [t.id, t]));
-
-  for (const task of newDoc?.tasks ?? []) {
-    const old = oldById.get(task.id);
-    if (!old) continue;
-    const outputsChanged =
-      JSON.stringify(old.outputs ?? []) !== JSON.stringify(task.outputs ?? []);
-    if (!outputsChanged) continue;
-
-    // A filled string note explains the divergence — done.
-    if (typeof task.notes === 'string' && task.notes.trim().length > 0) continue;
-
-    // Root-cause specific messages: a malformed notes value is a DIFFERENT
-    // failure than a missing one — claiming "notes is empty" when the agent
-    // just wrote an array reads as a false positive and burns a retry cycle.
-    if (task.notes !== undefined && typeof task.notes !== 'string') {
-      violations.push(
-        `task '${task.id}': outputs diverged from the plan and 'notes' is not a string ` +
-        `(got ${typeName(task.notes)}) — write the explanation as a single string in 'notes'`
-      );
-      continue;
-    }
-
-    violations.push(
-      `task '${task.id}': outputs diverged from the plan ` +
-      `(${fmtOutputs(old.outputs)} → ${fmtOutputs(task.outputs)}) but 'notes' is empty — ` +
-      `record why in 'notes' in the same edit. ` +
-      `Deletions and annotations belong in 'notes', not in 'outputs' (outputs = produced paths only).`
-    );
-  }
-  return violations;
-}

package/framework/rules/morph-task-tracking.md

@@ -1,54 +0,0 @@
----
-stacks:
-  - "*"
----
-
-# MORPH-SPEC Task Tracking
-
-> Progress lives in `tasks.json` — nowhere else. There is no CLI command to mark a task done and
-> no session-level checklist to keep in sync: this file IS the record of what happened.
-
-## Persisting Progress to `tasks.json`
-
-To record task progress for the feature, write `.morph/features/{feature}/2-plan/tasks.json`,
-touching ONLY the mutable fields:
-
-- `status` — `pending` → `in_progress` → `done` (também: `skipped`, `blocked`)
-- `outputs` — the files the task produced
-- `notes` — free-text record (deviations, context, resolved blockers)
-
-> **O status terminal é `done`.** `completed` **não existe** no enum de
-> `.morph/framework/schemas/tasks.schema.json` — é vocabulário de outro sistema, e o hook
-> `protect-spec-files` rejeita a gravação.
-
-The plan contract — `title`, `description`, `dependencies`, `effort`, `doneCriteria`,
-`group`, `agent`, `standards` — is frozen after Gate 2. Any attempt to change it is
-blocked by the `protect-spec-files` hook. `agent` (persona id, no `morph-` prefix)
-and `standards` (paths pinned by morph-plan) are optional — legacy plans without
-them remain valid.
-
-Use the `Write` tool (whole-file rewrite) OR the `Edit` tool — `Edit` is allowed
-as long as it touches only `status`, `outputs`, and `notes`. State is then synced
-automatically by the `state-sync` PostToolUse hook; you do not call a CLI to mark
-output.
-
-Update each task as you go — `in_progress` when you pick it up, `done` when it is finished —
-rather than batching every write to the end of the phase. `morph-spec status`, `dag`, `verify`
-and the dashboard all read this file, so a stale `tasks.json` is a blind orchestrator.
-
-## Deviation Tracking
-
-When completing a task differently than originally planned, record the reason in the
-task's `notes` field. `notes` is **uma única string** (o schema declara
-`"notes": { "type": "string" }`) — para registrar mais de um desvio, separe-os com
-`;` ou `\n` dentro da mesma string. Um array é **rejeitado** pelo validador, com a
-mensagem `'notes' must be a string`.
-
-```json
-{
-  "id": "T3",
-  "status": "done",
-  "outputs": ["Features/User/Update/Handler.cs"],
-  "notes": "deviation: split validation into a separate validator for testability; blocker-resolved: EF migration conflict fixed by regenerating the snapshot"
-}
-```