@polymorphism-tech/morph-spec 9.8.0 → 10.0.0

package/framework/hooks/claude-code/core/worktree-create.js

@@ -1,9 +1,8 @@
 #!/usr/bin/env node
 
-import { existsSync, mkdirSync, readFileSync } from 'fs';
+import { existsSync, mkdirSync } from 'fs';
 import { execFileSync } from 'child_process';
 import { dirname, join, resolve } from 'path';
-import { homedir } from 'os';
 import { stateExists } from '../../shared/state-reader.js';
 import { resolveGitCommonDir } from '../../shared/git-paths.js';
 import { runMorphSpec } from '../../shared/morph-cli.js';
@@ -34,43 +33,6 @@ export function slugify(name) {
   return slug || `wt-${Date.now().toString(36)}`;
 }
 
-function readJsonSafe(path) {
-  try { return JSON.parse(readFileSync(path, 'utf8').replace(/^/, '')); } catch { return null; }
-}
-
-// `null` when unset, distinct from an explicit `'fresh'`, which overrides the feature-branch default.
-export function readBaseRefSetting(root, home = homedir()) {
-  let value = null;
-  for (const p of [
-    join(home, '.claude', 'settings.json'),
-    join(root, '.claude', 'settings.json'),
-    join(root, '.claude', 'settings.local.json'),
-  ]) {
-    const s = readJsonSafe(p);
-    const v = s?.worktree?.baseRef;
-    if (typeof v === 'string' && v) value = v;
-  }
-  return value;
-}
-
-function headRef(cwd) {
-  try {
-    const name = git(['rev-parse', '--abbrev-ref', 'HEAD'], cwd);
-    if (name && name !== 'HEAD') return name;
-    return git(['rev-parse', 'HEAD'], cwd) || null;
-  } catch {
-    return null;
-  }
-}
-
-// Unset → the `morph/<f>` branch `cwd` is on: a sub-agent tree born from the default branch lacks the feature's work.
-export function resolveBase(setting, cwd) {
-  if (setting === 'head') return headRef(cwd);
-  if (setting) return null;
-  const current = headRef(cwd);
-  return current && /^morph\/.+/.test(current) ? current : null;
-}
-
 function isKnownFeature(root, name) {
   if (existsSync(join(root, '.morph', 'features', name, 'feature.json'))) return true;
   try {
@@ -92,14 +54,14 @@ function defaultBranch(root) {
   return null;
 }
 
-function gitFallback(root, name, base) {
+function gitFallback(root, name) {
   const branch = `morph-task/${name}`;
   const container = newWorktreesDir(root);
   const path = `${container}/${name}`;
   if (existsSync(path)) return { path };
   try { git(['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], root); }
   catch {
-    const from = base || defaultBranch(root);
+    const from = defaultBranch(root);
     git(from ? ['branch', branch, from] : ['branch', branch], root);
   }
   mkdirSync(container, { recursive: true });
@@ -113,21 +75,20 @@ export async function run(payload) {
   if (!root) return { error: `worktree-create: "${start}" is not inside a git repository` };
 
   const name = slugify(payload?.name);
-  const base = resolveBase(readBaseRefSetting(root), start);
 
   if (!stateExists(root)) {
-    try { return gitFallback(root, name, base); }
+    try { return gitFallback(root, name); }
     catch (err) { return { error: `worktree-create: ${err?.message || err}` }; }
   }
 
   const args = isKnownFeature(root, name)
     ? ['worktree', 'setup', name, '--json']
-    : ['worktree', 'provision', name, '--json', ...(base ? ['--base', base] : [])];
+    : ['worktree', 'provision', name, '--json'];
 
   const r = runMorphSpec(args, { cwd: root });
   if (r.unavailable) {
     process.stderr.write('worktree-create: morph-spec CLI not found — creating the tree with plain git under worktrees/ (no infra links, no port block). Run `morph-spec worktree link --all` inside it.\n');
-    try { return gitFallback(root, name, base); }
+    try { return gitFallback(root, name); }
     catch (err) { return { error: `worktree-create: ${err?.message || err}` }; }
   }
   if (r.stderr?.trim()) process.stderr.write(r.stderr);

package/framework/hooks/claude-code/core/worktree-env-inject.js

@@ -49,11 +49,7 @@ export async function run(payload) {
     // CLAUDE_PROJECT_DIR first: it is what the project hooks resolve `.morph/framework` against.
     const anchored = anchorSessionCommand(command, process.env.CLAUDE_PROJECT_DIR || payload?.cwd || '');
     if (anchored) {
-      return updatedInputResult(
-        { ...payload.tool_input, command: anchored.command },
-        'PreToolUse',
-        `⚓ âncora da sessão exportada para o CLI: ${ANCHOR_KEY}=${anchored.anchor} — o finish/worktree remove adia o desmonte do worktree em que esta sessão está ancorada`,
-      );
+      return updatedInputResult({ ...payload.tool_input, command: anchored.command }, 'PreToolUse');
     }
 
     const dir = payload?.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
@@ -63,11 +59,7 @@ export async function run(payload) {
     const rewritten = rewriteCommand(command, loadEnvFile(manifest));
     if (!rewritten) return null;
 
-    return updatedInputResult(
-      { ...payload.tool_input, command: rewritten.command },
-      'PreToolUse',
-      `🔌 worktree env injetado (.morph/worktree.env): ${rewritten.injected.join(' ')}`,
-    );
+    return updatedInputResult({ ...payload.tool_input, command: rewritten.command }, 'PreToolUse');
   } catch {
     return null;
   }

package/framework/hooks/shared/gate-event.js

@@ -9,10 +9,10 @@ export const GATE_STEPS = ['decision', 'approve', 'unapprove'];
  * The trail `cost --metrics` turns into "what did the human do with each pause":
  * `gateDecisions` keeps only the latest decision, so the history lives here.
  */
-export function recordGateEvent(projectPath, { feature, gate, step, pause, signal, source, approvedBy }) {
+export function recordGateEvent(projectPath, { feature, gate, step, pause, signal, source, resolver, approvedBy }) {
   if (!existsSync(join(projectPath || process.cwd(), '.morph'))) return;
   const event = { event: GATE_EVENT, feature, gate, step };
-  if (step === 'decision') Object.assign(event, { pause: pause === true, signal: signal ?? null, source: source ?? null });
+  if (step === 'decision') Object.assign(event, { pause: pause === true, signal: signal ?? null, source: source ?? null, ...(pause === true ? { resolver: resolver ?? 'human' } : {}) });
   else event.approvedBy = approvedBy ?? null;
   appendTelemetryEvent(event, projectPath);
 }

package/framework/hooks/shared/graph-refresh.js

@@ -8,6 +8,7 @@ import {
   readFileSync, renameSync, statSync, unlinkSync, writeFileSync, writeSync,
 } from 'fs';
 import { dirname, join, resolve } from 'path';
+import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 import { readPrimaryHead, resolveGitCommonDir, workTreeTop } from './git-paths.js';
 import { findFirstOnPath, quoteForCmd } from './morph-cli.js';
@@ -20,6 +21,8 @@ import {
 
 export { primaryTree };
 
+export const GRAPHIFY_PACKAGE = 'graphifyy';
+
 // Ficam fora de propósito: `.graphify_root` guarda o caminho absoluto da raiz, `cache/`
 // é indexado pelo mtime da origem, e excluir `.graphifyignore` esconderia o da raiz.
 const SEED_FILES = ['manifest.json', '.graphify_analysis.json', '.graphify_labels.json', 'graph.json'];
@@ -131,12 +134,26 @@ function appendRefreshLog(dir, entry) {
   } catch { /* log é diagnóstico, nunca bloqueia */ }
 }
 
+// The tool venv's own executable, for when the shim on PATH is missing: `uv tool install` writes the shim
+// under $HOME, so an install run with another HOME leaves the venv in place and the shim elsewhere.
+function venvGraphify(env, platform) {
+  const win = platform === 'win32';
+  const home = (win ? env.USERPROFILE : env.HOME) || homedir();
+  const venvs = [
+    join(env.UV_TOOL_DIR || (win ? join(env.APPDATA || join(home, 'AppData', 'Roaming'), 'uv', 'tools')
+      : join(env.XDG_DATA_HOME || join(home, '.local', 'share'), 'uv', 'tools')), GRAPHIFY_PACKAGE),
+    join(env.PIPX_HOME || (win ? join(home, 'pipx') : join(home, '.local', 'pipx')), 'venvs', GRAPHIFY_PACKAGE),
+  ];
+  const file = win ? join('Scripts', 'graphify.exe') : join('bin', 'graphify');
+  return venvs.map((v) => join(v, file)).find((f) => existsSync(f)) ?? null;
+}
+
 // No win32 o libuv só acha `.exe` sem shell; `.cmd`/`.bat` passa pelo shell.
-export function resolveGraphify(env = process.env) {
-  const names = process.platform === 'win32'
+export function resolveGraphify(env = process.env, platform = process.platform) {
+  const names = platform === 'win32'
     ? ['graphify.exe', 'graphify.cmd', 'graphify.bat']
     : ['graphify'];
-  const file = findFirstOnPath(names, env);
+  const file = findFirstOnPath(names, env) ?? venvGraphify(env, platform);
   return file ? { file, shell: /\.(cmd|bat)$/i.test(file) } : null;
 }
 

package/framework/hooks/shared/heavy-command.js

@@ -45,6 +45,8 @@ function skipWrappers(tokens) {
   }
 }
 
+// The package managers' "run in that directory" flags: `npm --prefix <dir> test` is still `npm test`.
+const PM_DIR_FLAGS = new Set(['--prefix', '--cwd', '-C', '--dir']);
 const DOCKER_VALUE_FLAGS = new Set(['-f', '--file', '-p', '--project-name', '--profile', '--env-file', '--project-directory', '-H', '--host', '--context']);
 
 function firstArg(args, valueFlags = new Set()) {
@@ -59,7 +61,8 @@ function kindOfTokens(tokens) {
   const [head, ...args] = tokens;
   if (!head || args.some((a) => INFO_FLAGS.has(a))) return null;
   const exe = executable(head);
-  const sub = firstArg(args, exe === 'docker' || exe === 'docker-compose' ? DOCKER_VALUE_FLAGS : undefined);
+  const sub = firstArg(args, exe === 'docker' || exe === 'docker-compose' ? DOCKER_VALUE_FLAGS
+    : PACKAGE_MANAGERS.has(exe) ? PM_DIR_FLAGS : undefined);
 
   if (exe === 'dotnet') return DOTNET_HEAVY.has(sub) ? `dotnet ${sub}` : null;
   if (exe === 'msbuild') return 'msbuild';
@@ -148,6 +151,34 @@ function testKindOfTokens(tokens) {
   return kind && TEST_LABEL.test(kind) ? kind : null;
 }
 
+const DOTNET_FILTERS = /^(--filter|--tests|--treenode-filter|\/testcasefilter:)/i;
+const NAME_FILTERS = /^(-t|-g|--grep|--testNamePattern|--test-name-pattern|--testPathPattern|--filter)(=|$)/;
+// A bare word may be a flag's value (`--reporter dot`); only a path-shaped argument selects files.
+const TEST_PATH = /[\\/]|\.(spec|test)\b|\.[cm]?[jt]sx?$/;
+const PATH_VALUE_FLAGS = new Set(['-c', '--config', '--project', '--root', '--workspace', '--outputFile', '--reporter', ...PM_DIR_FLAGS]);
+
+function isFilteredRun(kind, tokens) {
+  const runnerAt = executable(tokens[0]) === 'node'
+    ? tokens.findIndex((t, i) => i > 0 && executable(t).replace(/\.[cm]?js$/, '') === kind)
+    : 0;
+  const args = tokens.slice(runnerAt + 1);
+  if (kind.startsWith('dotnet')) return args.some((a) => DOTNET_FILTERS.test(a));
+  for (let i = 0; i < args.length; i++) {
+    if (PATH_VALUE_FLAGS.has(args[i])) { i++; continue; }
+    if (NAME_FILTERS.test(args[i]) || (!args[i].startsWith('-') && TEST_PATH.test(args[i]))) return true;
+  }
+  return false;
+}
+
+/** `{ kind, filtered }` for the first test run in `command`, `null` when there is none. */
+export function testRunCall(command) {
+  for (const tokens of commandTokens(command)) {
+    const kind = testKindOfTokens(tokens);
+    if (kind) return { kind, filtered: isFilteredRun(kind, tokens) };
+  }
+  return null;
+}
+
 export function testRunKind(command) {
   for (const tokens of commandTokens(command)) {
     const kind = testKindOfTokens(tokens);

package/framework/hooks/shared/heavy-config.js

@@ -12,7 +12,7 @@ export const HEAVY_DEFAULTS = Object.freeze({
   maxHoldMinutes: 90,
   shutdownBuildServer: true,
   disableNodeReuse: false,
-  gateBash: false,
+  gateBash: true,
 });
 
 export const HEAVY_KINDS = Object.freeze(['unit', 'build', 'e2e']);

package/framework/hooks/shared/next-step.js

@@ -4,26 +4,71 @@
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { derivePhaseForFeature } from './state-reader.js';
-import { sliceProgress, readySlices } from './slice-progress.js';
+import { implementProgress } from './report-progress.js';
 
 export const FIX_ATTEMPTS = 3;
 
 const step = (action, command, reason, extra = {}) => ({ action, command, reason, ...extra });
 
+const HOW = {
+  plan: (f) => [
+    `Rode \`/morph-plan ${f}\`: escreva 2-plan/plan.md e rode \`morph-spec plan-check ${f}\` até zero erro.`,
+  ],
+  gate: (f) => [
+    `Rode \`morph-spec gate-check ${f} plan\`; se pausar, AskUserQuestion "Gate do plano — Plano de ${f} aprovado?".`,
+  ],
+  design: (f) => [
+    `Rode \`/morph-uiux ${f}\` (opções em 1-design/opcoes/, protótipo e prints); depois \`morph-spec gate-check ${f} uiux\`.`,
+    `Se pausar, AskUserQuestion "Gate uiux — Design de ${f} aprovado?".`,
+  ],
+  implement: (f) => [
+    'Implemente os Cn pendentes em sequência; ao fechar cada um, marque `feito` + evidência (teste ou arquivo:linha) '
+    + `em 3-implement/report.md e commite \`wip(${f}): Cn …\`.`,
+  ],
+  decide: () => [
+    'Leia a pergunta do Cn bloqueado em 3-implement/report.md ## Notas; decida pelo plano/ADR ou faça AskUserQuestion com ela.',
+    'Registre a resposta em ## Notas, volte o Cn para `pendente` e siga implementando.',
+  ],
+  verify: (f) => [
+    `\`morph-spec verify ${f} --json\` sem filtro; passou de 10 min, run_in_background.`,
+  ],
+  fix: (f) => [
+    `Leia o \`feedback\` do último verify, corrija a causa e rode \`morph-spec verify ${f} --json\` de novo, sem filtro.`,
+  ],
+  escalate: () => [
+    'AskUserQuestion com o texto do reason (aceitar/continuar/parar) e siga a resposta; não rode outro verify antes dela.',
+  ],
+  review: () => [
+    'Siga .claude/skills/morph-apply/references/review.md.',
+  ],
+  finish: (f) => [
+    `AskUserQuestion header "Integração" (PR ou merge); depois \`morph-spec finish ${f} --pr\` ou \`--merge\`.`,
+  ],
+  status: (f) => [
+    `Rode \`morph-spec status ${f}\` e confira a fase em .morph/features/${f}/feature.json.`,
+  ],
+};
+
 /**
- * @param {{ feature: string, phase: string, slices: object|null, gates: object,
+ * @param {{ feature: string, phase: string, progress: object|null, gates: object,
  *   verification: { status?: string }|null, verificationStale?: boolean, failStreak?: number }} s
  * `verificationStale` undefined = unknown (the hook has no git): read as fresh.
  */
 export function decideNext(s) {
+  const n = decide(s);
+  const how = (HOW[n.action] ?? HOW.status)(s.feature);
+  const hotfix = s.workType === 'hotfix' && n.command.startsWith('/morph-hotfix');
+  return { ...n, how: hotfix ? ['Fluxo de hotfix: siga .claude/skills/morph-apply/references/hotfix.md.', ...how] : how };
+}
+
+function decide(s) {
   const f = s.feature;
   const approved = (g) => s.gates?.[g]?.approved === true;
-  // The hotfix pipeline (scout, human approval, ship) lives in its own skill, end to end.
   const skill = (name) => (s.workType === 'hotfix' ? `/morph-hotfix ${f}` : `/${name} ${f}`);
 
   switch (s.phase) {
     case 'plan':
-      return s.slices
+      return s.progress
         ? step('gate', `morph-spec gate-check ${f} plan`, 'plano extraído: o gate do plano decide a pausa')
         : step('plan', `/morph-plan ${f}`, 'sem checks.json: escreva o plan.md e rode plan-check até zero erro');
 
@@ -31,26 +76,20 @@ export function decideNext(s) {
       return step('design', `morph-spec gate-check ${f} uiux`, 'complete 1-design/ (morph-uiux) e passe o gate de uiux');
 
     case 'implement': {
-      if (!s.slices) return step('plan', skill('morph-plan'), 'sem checks.json: plan.md curto (uma fatia) e plan-check até zero erro');
-      if (s.slices.done < s.slices.total) {
-        const ready = readySlices(s.slices);
-        if (!ready.length) {
-          const waiting = s.slices.slices.filter((sl) => sl.status === 'bloqueado').map((sl) => sl.id);
-          if (waiting.length) {
-            return step('decide', 'AskUserQuestion (decisão da fatia)',
-              'relatório BLOQUEADO: decida pelo plano/ADR ou pergunte, e retome o MESMO agente com a resposta — nunca re-despache',
-              { slices: waiting });
-          }
-          return step('blocked', `morph-spec report-check ${f}`, 'fatias pendentes sem dependência satisfeita');
-        }
-        const partial = ready.filter((sl) => sl.status === 'parcial').map((sl) => sl.id);
-        return step('dispatch', skill('morph-apply'),
-          partial.length ? `retome ${partial.join(', ')} (PARCIAL) e despache as prontas` : 'despache as fatias prontas',
-          { slices: ready.map((sl) => sl.id) });
+      const p = s.progress;
+      if (!p) return step('plan', skill('morph-plan'), 'sem checks.json: plan.md curto e plan-check até zero erro');
+      const blocked = p.checks.filter((c) => c.status === 'bloqueado').map((c) => c.id);
+      if (blocked.length) {
+        return step('decide', 'AskUserQuestion (decisão do cenário)',
+          'Cn bloqueado no report.md: decida pelo plano/ADR ou pergunte, e siga implementando', { checks: blocked });
+      }
+      const pending = p.checks.filter((c) => c.status === 'pendente').map((c) => c.id);
+      if (pending.length) {
+        return step('implement', skill('morph-apply'), 'implemente nesta sessão e marque cada Cn feito no report.md', { checks: pending });
       }
       const v = s.verification;
       if (!v?.status || s.verificationStale === true) {
-        return step('verify', `morph-spec verify ${f}`, v?.status ? 'a árvore andou desde o último verify' : 'todas as fatias relatadas, sem verify');
+        return step('verify', `morph-spec verify ${f}`, v?.status ? 'a árvore andou desde o último verify' : 'todo Cn feito, sem verify');
       }
       if (v.status === 'fail') {
         const streak = s.failStreak ?? 0;
@@ -77,8 +116,8 @@ export function decideNext(s) {
 }
 
 export function formatNext(n) {
-  const slices = n.slices?.length ? ` [${n.slices.join(', ')}]` : '';
-  return `próximo: ${n.action}${slices} → ${n.command} — ${n.reason}`;
+  const ids = n.checks?.length ? ` [${n.checks.join(', ')}]` : '';
+  return `próximo: ${n.action}${ids} → ${n.command} — ${n.reason}`;
 }
 
 /** Facts readable from `hooks/shared`; the CLI adds `verificationStale` (git) on top. Null without feature.json. */
@@ -99,7 +138,7 @@ export function collectNextSignals(featureName, cwd) {
     workType: feature.workType ?? 'feature',
     worktreePath: feature.worktree?.path ?? null,
     phase,
-    slices: sliceProgress(featureDir),
+    progress: implementProgress(featureDir),
     gates: feature.approvals || feature.approvalGates || {},
     verification: feature.verification ?? null,
     failStreak: feature.verifications?.feature?.failStreak ?? 0,

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

@@ -12,10 +12,10 @@ export const PHASE_DIRS = {
 export const OUTPUT_PHASE_MAP = {
   plan: 'plan',
   checks: 'plan',
-  uiDesignSystem: 'uiux',
+  planCritique: 'plan',
+  planView: 'plan',
   uiMockups: 'uiux',
-  uiComponents: 'uiux',
-  uiFlows: 'uiux',
+  implementReport: 'implement',
   evidencias: 'implement',
   verifierReport: 'review',
   reviewerReport: 'review',
@@ -25,10 +25,10 @@ export const OUTPUT_PHASE_MAP = {
 export const FILENAME_TO_OUTPUT = {
   'plan.md': 'plan',
   'checks.json': 'checks',
-  'design-system.md': 'uiDesignSystem',
+  'critica.md': 'planCritique',
+  'plan.html': 'planView',
   'mockups.md': 'uiMockups',
-  'components.md': 'uiComponents',
-  'flows.md': 'uiFlows',
+  'report.md': 'implementReport',
   'verifier.md': 'verifierReport',
   'reviewer.md': 'reviewerReport',
   'security.md': 'securityReport',
@@ -37,10 +37,7 @@ export const FILENAME_TO_OUTPUT = {
 export const PROTECTED_SPEC_FILES = {
   'plan.md': 'plan',
   'checks.json': 'plan',
-  'design-system.md': 'uiux',
   'mockups.md': 'uiux',
-  'components.md': 'uiux',
-  'flows.md': 'uiux',
 };
 
 

package/framework/hooks/shared/report-progress.js

@@ -0,0 +1,86 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+/** `PARCIAL` on the report's first non-blank line, tolerating heading/bold/quote typography. */
+export const PARTIAL_MARKER = /^[\s#>*_]*PARCIAL\b/;
+
+export const STATUSES = ['pendente', 'feito', 'bloqueado'];
+
+export function checksPath(featureDir) {
+  return join(featureDir, '2-plan', 'checks.json');
+}
+
+export function reportPath(featureDir) {
+  return join(featureDir, '3-implement', 'report.md');
+}
+
+const ROW = /^\|\s*(C\d+)\s*\|\s*([^|]*?)\s*\|\s*(.*?)\s*\|?\s*$/;
+
+/** Status per Cn from the report's table; an unknown status reads as `pendente`. */
+export function parseReport(text) {
+  const rows = new Map();
+  for (const line of String(text ?? '').split(/\r?\n/)) {
+    const m = ROW.exec(line);
+    if (!m) continue;
+    const status = m[2].toLowerCase();
+    rows.set(m[1], { status: STATUSES.includes(status) ? status : 'pendente', evidence: m[3] });
+  }
+  return rows;
+}
+
+// Features started before 10.0 have per-slice reports and no report.md: a Cn counts as done when a
+// slice that covers it has a final report, so an in-flight feature keeps moving after the upgrade.
+function legacyRows(checks, readSliceReport) {
+  const rows = new Map();
+  for (const slice of Array.isArray(checks.slices) ? checks.slices : []) {
+    const first = String(readSliceReport(slice.id) ?? '').split(/\r?\n/).find((l) => l.trim() !== '');
+    if (first === undefined) continue;
+    const status = /^[\s#>*_]*BLOQUEADO\b/.test(first) ? 'bloqueado' : PARTIAL_MARKER.test(first) ? null : 'feito';
+    if (!status) continue;
+    for (const id of slice.covers ?? []) {
+      if (rows.get(id)?.status !== 'bloqueado') rows.set(id, { status, evidence: `${slice.id}.md` });
+    }
+  }
+  return rows;
+}
+
+/** @returns {{ total, done, blocked, pending, checks: Array<{id, status, evidence}>, legacy: boolean } | null} */
+export function implementProgressFrom(checksText, reportText, readSliceReport = () => null) {
+  let checks;
+  try {
+    checks = JSON.parse(checksText ?? '');
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(checks?.checks)) return null;
+  const legacy = reportText == null && Array.isArray(checks.slices);
+  const rows = legacy ? legacyRows(checks, readSliceReport) : parseReport(reportText);
+  const out = checks.checks
+    .filter((c) => c && typeof c.id === 'string')
+    .map((c) => ({ id: c.id, status: rows.get(c.id)?.status ?? 'pendente', evidence: rows.get(c.id)?.evidence ?? '' }));
+  const count = (status) => out.filter((c) => c.status === status).length;
+  return { total: out.length, done: count('feito'), blocked: count('bloqueado'), pending: count('pendente'), checks: out, legacy };
+}
+
+function readOrNull(path) {
+  try {
+    return existsSync(path) ? readFileSync(path, 'utf8') : null;
+  } catch {
+    return null;
+  }
+}
+
+export function implementProgress(featureDir) {
+  const sliceDir = join(featureDir, '3-implement', 'reports');
+  return implementProgressFrom(
+    readOrNull(checksPath(featureDir)),
+    readOrNull(reportPath(featureDir)),
+    (id) => (existsSync(sliceDir) ? readOrNull(join(sliceDir, `${id}.md`)) : null),
+  );
+}
+
+/** The report template body for a feature's checks: every Cn starts `pendente`. */
+export function reportSkeleton(featureName, checkIds) {
+  const rows = checkIds.map((id) => `| ${id} | pendente | |`).join('\n');
+  return `# ${featureName}\n\n| Cn | status | evidência |\n|----|--------|-----------|\n${rows}\n\n## Notas\n\n`;
+}

package/framework/hooks/shared/state-reader.js

@@ -131,8 +131,9 @@ export const PHASE_INDEX = { plan: 0, uiux: 1, implement: 2, review: 3 };
 // not advance the phase.
 export const PHASE_ARTIFACTS = [
   ['4-review',    'review',    'verifier.md'],
+  ['3-implement', 'implement', 'report.md'],
   ['3-implement', 'implement', 'reports/'],
-  ['1-design',    'uiux',      'design-system.md'],
+  ['1-design',    'uiux',      'mockups.md'],
   ['2-plan',      'plan',      'plan.md'],
 ];
 
@@ -180,7 +181,7 @@ export function derivePhaseFrom(feature, hasArtifact) {
 
   // An approved gate advances the phase before the next artifact exists, or
   // that artifact could never be written.
-  const designStarted = hasArtifact(DESIGN_DIR) || hasArtifact(`${DESIGN_DIR}/design-system.md`);
+  const designStarted = hasArtifact(DESIGN_DIR) || hasArtifact(`${DESIGN_DIR}/mockups.md`);
   const implied = gateImpliedPhaseFrom(feature, designStarted);
   return PHASE_INDEX[implied] > PHASE_INDEX[artifactPhase] ? implied : artifactPhase;
 }