@polymorphism-tech/morph-spec 7.8.1 → 7.9.0

package/framework/evals/trace-schema.md

@@ -45,22 +45,32 @@ Um arquivo por fase. Se a fase for executada em múltiplas sessões, o mesmo arq
 }
 ```
 
-## Quando escrever
+## Como o trace é gerado (automático — não escreva à mão)
 
-| Evento | O que logar |
-|--------|-------------|
-| Task completada | Adicionar entrada em `tasks[]` com todos os campos preenchidos |
-| Eval executada (`morph-eval`) | Preencher `eval_score` e `eval_dimensions` da task correspondente |
-| Fase concluída | Preencher `completed_at` e `phase_summary` |
+O trace é **gerado pelo hook `trace-autogen`** (PostToolUse em Write|Edit) a cada
+write de `2-plan/tasks.json` — o último write da cerimônia de cada task. As skills
+(`morph-implement`, `morph-eval`, `morph-review`) **não escrevem o trace**.
 
-## Regras de escrita
+| Fonte | O que alimenta |
+|-------|----------------|
+| `tasks.json` | conjunto de tasks, `status` (done→completed, skipped→skipped, blocked→failed; pending/in_progress ficam fora), `outputs` → `files_modified` |
+| `recap.md` | `**Standard:**` → `standards_consulted`; `**Persona:**` → `agent_persona` + `sub_agent_dispatched` (`morph-{id}`/`general-purpose` = true) |
+| `feature.json → taskScores` (gravado por `morph-spec score`) | `eval_score` (lastScore) e `eval_dimensions` (camelCase → snake_case) |
 
-- O modelo escreve o trace como arquivo JSON ao final de cada task e ao final da fase.
-- Se um campo não tiver valor disponível, usar `null` — nunca omitir o campo.
-- Manter a estrutura completa para compatibilidade com análise de meta-harness.
-- `session_id` usa o formato `YYYY-MM-DD-HH-MM-SS` do início da sessão atual.
+`completed_at` e `phase_summary` são preenchidos quando nenhuma task resta
+`pending`/`in_progress`. O arquivo existente da mesma feature+fase é atualizado
+in place (`session_id`/`started_at` preservados entre sessões).
+
+**Se o trace parecer incompleto, corrija a FONTE** (um `morph-spec score`
+faltante, um recap sem o bloco `## T{N}`), nunca o trace.
+
+## Regras de geração
+
+- Se um campo não tiver valor disponível, o hook usa `null` — nunca omite o campo.
+- Estrutura completa mantida para compatibilidade com análise de meta-harness.
+- `session_id` usa o formato `YYYY-MM-DD-HH-MM-SS` da primeira geração.
 - `standards_consulted` contém os `id`s do STANDARDS.json, não os paths.
-- `files_modified` usa paths relativos à raiz do repositório.
+- `files_modified` usa paths relativos à raiz do repositório (vem de `outputs`).
 
 ## Motivação
 

package/framework/hooks/README.md

@@ -47,10 +47,12 @@ framework/hooks/
 | **PreToolUse** (Bash) | pre-bash-denylist.js | Block | Blocks `rm -rf .morph/` and direct state edits |
 | **PostToolUse** (Write\|Edit) | post-edit-typecheck.js | Advisory | Debounced `tsc --noEmit` after TS/TSX edits; silent on success |
 | **PostToolUse** (Write\|Edit) | tasks-json-guard.js | Advisory | Validates the written tasks.json schema (status/effort enums); warns so the LLM fixes it immediately |
+| **PostToolUse** (Write\|Edit) | trace-autogen.js | State sync | Auto-generates `.morph/traces/YYYY-MM-DD-{feature}-implement.json` from tasks.json + recap.md + taskScores on every tasks.json write — the skills never write traces by hand |
 | **PostToolUse** (Write\|Edit\|AskUserQuestion) | state-sync.js | State sync | Autonomous state updates (feature register, output tracking, gate approval) |
 | **PostToolUse** (Write\|Edit\|AskUserQuestion) | gate-guard.js | Advisory | Warns (never blocks) when a gate action disagrees with the persisted gateDecisions; logs one `coherent`/`divergent` line per check in `.morph/logs/activity.json` (issue #63) |
 | **PostToolUse** (all tools) | loop-detect.js | Advisory | Warns when the last 8 actions collapse to ≤2 unique signatures |
 | **Stop** | validate-completion.js | Advisory | Warns about incomplete tasks/missing outputs/recap drift; build check; session snapshot |
+| **Stop** / **SubagentStop** | subagent-report-guard.js | Block (once) | Blocks a dispatched sub-agent stopping without SendMessage (clause 1 of the dispatch protocol) and injects the exact instruction; `stop_hook_active` prevents loops; inert in the orchestrator's session |
 
 ## Design Principles
 

package/framework/hooks/claude-code/core/subagent-report-guard.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * subagent-report-guard.js — Stop / SubagentStop hook
+ *
+ * Enforces clause 1 of the morph-spec dispatch protocol: a dispatched
+ * sub-agent's FINAL act is SendMessage to the orchestrator (main). Plain text
+ * in the last message never reaches the orchestrator, and an idle agent forces
+ * the costly nag-and-wait cycle (observed 2/2 in real apply sessions —
+ * MORPH_GHLBrain 2026-07-11).
+ *
+ * Detection: the session transcript (JSONL) contains the dispatch-protocol
+ * marker ("Protocolo obrigatório") inside a USER message — that is how the
+ * dispatch prompt arrives in the sub-agent's own transcript. In the
+ * ORCHESTRATOR's transcript the marker only appears inside assistant tool_use
+ * input (the Agent call that did the dispatch), so the orchestrator is never
+ * blocked by this guard. A SendMessage tool_use anywhere in an assistant
+ * message counts as the report.
+ *
+ * Action: block the stop ONCE ({"decision":"block"}) with the exact
+ * instruction to call SendMessage — the agent continues and reports.
+ * stop_hook_active guards against blocking loops. Fail-open on any error.
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { stateExists } from '../../shared/state-reader.js';
+import { block, pass } from '../../shared/hook-response.js';
+import { logHookActivity } from '../../shared/activity-logger.js';
+
+const PROTOCOL_MARKER = 'Protocolo obrigatório';
+
+function readStdin() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf8') || '{}');
+  } catch {
+    return {};
+  }
+}
+
+function projectDir() {
+  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+/**
+ * Scan a transcript for the dispatch-protocol marker (user messages only) and
+ * for a SendMessage tool call (assistant messages).
+ *
+ * @param {string} path - JSONL transcript path
+ * @returns {{ dispatched: boolean, reported: boolean }}
+ */
+function scanTranscript(path) {
+  const raw = readFileSync(path, 'utf8');
+  let dispatched = false;
+  let reported = false;
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    let role = null;
+    try {
+      const entry = JSON.parse(line);
+      role = entry?.message?.role ?? entry?.type ?? null;
+    } catch {
+      continue;
+    }
+    if (!dispatched && role === 'user' && line.includes(PROTOCOL_MARKER)) dispatched = true;
+    if (!reported && role === 'assistant' && line.includes('"name":"SendMessage"')) reported = true;
+  }
+  return { dispatched, reported };
+}
+
+try {
+  if (!stateExists(projectDir())) pass();
+
+  const input = readStdin();
+
+  // Never loop: a previous block already forced one continuation — let this
+  // stop through even if the agent still failed to report.
+  if (input.stop_hook_active) pass();
+
+  const transcriptPath = input.transcript_path;
+  if (!transcriptPath || !existsSync(transcriptPath)) pass();
+
+  const { dispatched, reported } = scanTranscript(transcriptPath);
+  if (!dispatched || reported) pass();
+
+  logHookActivity('subagent-report-guard', input.hook_event_name || 'Stop', 'blocked', projectDir());
+  block(
+    '[morph-spec] PROTOCOLO DE RETORNO — você foi despachado com o protocolo obrigatório ' +
+    'mas ainda não chamou SendMessage. Sua última mensagem em texto NÃO chega ao orquestrador. ' +
+    'Antes de encerrar, chame a tool SendMessage com to:"main" e o relatório completo no content: ' +
+    '(1) o que foi feito em 2-3 frases, (2) arquivos modificados, (3) problemas encontrados e ' +
+    'como foram resolvidos, (4) auto-score 0-10. O SendMessage é o seu ato final.'
+  );
+} catch {
+  // Fail-open
+  process.exit(0);
+}

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

@@ -0,0 +1,183 @@
+#!/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 + feature.json taskScores 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
+ *  - feature.json    → taskScores (lastScore → eval_score, dimensions →
+ *                      eval_dimensions, camelCase → snake_case)
+ *
+ * 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.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { readStdin } from '../../shared/stdin-reader.js';
+import { stateExists } from '../../shared/state-reader.js';
+import { getFilePath } from '../../shared/payload-utils.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' };
+
+async function main() {
+  const cwd = projectDir();
+  if (!stateExists(cwd)) return;
+
+  const payload = await readStdin();
+  if (!payload) return;
+
+  const filePath = getFilePath(payload);
+  const feature = filePath ? extractFeature(filePath) : null;
+  if (!feature) 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 : [];
+
+  let recap = {};
+  const recapPath = join(featureDir, '3-implement', 'recap.md');
+  if (existsSync(recapPath)) {
+    try { recap = parseRecap(readFileSync(recapPath, 'utf8')); } catch { recap = {}; }
+  }
+
+  let taskScores = {};
+  const featureJsonPath = join(featureDir, 'feature.json');
+  if (existsSync(featureJsonPath)) {
+    try { taskScores = JSON.parse(readFileSync(featureJsonPath, 'utf8')).taskScores ?? {}; } catch { taskScores = {}; }
+  }
+
+  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 now = new Date();
+  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] ?? {};
+      const score = taskScores[t.id];
+      const dims = score?.dimensions;
+      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,
+        eval_score: score?.lastScore ?? null,
+        eval_dimensions: dims ? {
+          architecture: dims.architecture ?? null,
+          contracts: dims.contracts ?? null,
+          code_quality: dims.codeQuality ?? null,
+          test_coverage: dims.testCoverage ?? null,
+        } : null,
+        files_modified: Array.isArray(t.outputs) ? t.outputs.filter(o => typeof o === 'string') : [],
+        duration_seconds: null,
+      };
+    });
+
+  const allSettled = tasks.length > 0 &&
+    tasks.every(t => t.status !== 'pending' && t.status !== 'in_progress');
+  const scores = entries.map(e => e.eval_score).filter(s => typeof s === 'number');
+
+  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,
+      avg_eval_score: scores.length
+        ? Math.round((scores.reduce((a, b) => a + b, 0) / scores.length) * 10) / 10
+        : null,
+      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');
+}
+
+main().catch(() => { /* fail-open */ }).finally(() => process.exit(0));