@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/src/commands/state/gate-check.js

@@ -1,117 +1,45 @@
 import chalk from 'chalk';
-import { existsSync, readFileSync } from 'fs';
 import { getFeature } from '../../core/state/state-manager.js';
-import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
-import { shouldPauseGate, getRiskSignals, classifyE2eSkip } from '../../lib/risk-detector.js';
-import { evaluatorReportState, evaluatorMediaSection, verdictSignal } from '../../lib/evaluator-report.js';
+import { shouldPauseGate, getRiskSignals, classifyE2eSkip, planChecksPause, securityReviewFor } from '../../lib/risk-detector.js';
+import { reviewReports, reviewSignal, requiredReviewRoles, verifierMediaSection } from '../../lib/review-reports.js';
 import { collectScreenChecklist } from '../../lib/specs/screen-checklist.js';
 import { persistGateDecision, VALID_GATES, readTrustFromConfig } from './gate-decision.js';
 import { minimatch } from 'minimatch';
 import { detectDefaultBranch, getHeadSha, getDiffStat, changedPathsAgainst } from '../../lib/git/default-branch.js';
 import { treeMovedSince } from '../../lib/git/evidence-staleness.js';
 import { readMorphConfig } from '../../lib/tasks/test-runner.js';
-import { oversizedTasks } from '../../lib/tasks/tasks-json-parser.js';
+import { readPlanChecks } from '../../lib/plan/checks.js';
 import { assertOwnerTree, ownerTreeRefusalLines } from '../../lib/worktree/feature-truth.js';
 
-/**
- * `--signals` on `gate-check` is NOT a general override like `gate-decision`'s
- * — everything else here is read straight off disk (workType, taskCount, sha,
- * diffstat, verification), and letting a caller override those would let a
- * careless/hostile `--signals` silently defeat the policy this command exists
- * to make deterministic (e.g. overriding `workType` away from "hotfix" would
- * suppress risk-detector's forced Gate-3 pause). Only the signals that are
- * genuinely NOT derivable from disk today are accepted here:
- *   - standardsViolations / designSystemDivergence: still an LLM's
- *     natural-language read (see the R4 report — no deterministic detector
- *     exists in JS yet).
- */
+// Only signals NOT derivable from disk may be overridden: overriding a disk fact (e.g. `workType`
+// away from hotfix) would silently defeat the policy this command makes deterministic.
 const OVERRIDABLE_SIGNAL_KEYS = ['standardsViolations', 'designSystemDivergence'];
 
-/**
- * Os paths de standard que fazem uma feature ser "de midia".
- *
- * Escritos aqui, uma vez, e lidos do campo `standards[]` das tasks — que o Gate
- * 2 congelou. Nao ha julgamento envolvido: ou a task pinou o standard, ou nao
- * pinou. Um sinal derivado de opiniao seria sobrescrivivel na pratica ainda que
- * nao estivesse em OVERRIDABLE_SIGNAL_KEYS.
- *
- * A forma dos valores e a de `tasks.json` (`standards/...`), nao a do disco
- * (`framework/standards/...`): e o vocabulario que o plano usa.
- */
-export const MEDIA_STANDARD_PATHS = [
-  'standards/ai-agents/modalities-image-gen.md',
-  'standards/ai-agents/media-video.md',
-  'standards/ai-agents/media-pipeline.md',
+export const MEDIA_STANDARD_IDS = [
+  'ai-agents-modalities-image-gen',
+  'ai-agents-media-video',
+  'ai-agents-media-pipeline',
 ];
 
-/**
- * Uma feature "gera midia" quando ALGUMA task pinou um dos tres standards de
- * midia no seu array `standards[]`.
- *
- * Isto e uma FUNCAO EXPORTADA, e nao uma expressao dentro de `collectSignals`,
- * porque um predicado que decide se um guardrail arma tem de ser testavel
- * sozinho — o irmao `productionCode` tem quatro casos, e este nao tinha nenhum.
- * Um predicado que sempre devolve `false` desarma a clausula em silencio, e
- * silencio e o defeito que esta epic catalogou sete vezes.
- *
- * **O prefixo `framework/` e normalizado, e essa e a razao de existir da
- * funcao.** O vocabulario do plano e `standards/...` (o exemplo do
- * `tasks.schema.json`, e a unica forma medida hoje nos `standards[]` desta
- * arvore), mas o disco e `framework/standards/...` — e a mesma prosa das skills
- * cita as duas formas. Um plano que escrevesse a forma do disco desarmaria o
- * guardrail sem erro nenhum: `standards --find`, `validate` e o proprio Gate 3
- * continuariam verdes. Aceitar as duas grafias custa uma linha; recusar uma
- * delas em silencio custa o gate.
- *
- * Fail-open por AUSENCIA (nao por opiniao): lista vazia, `standards` ausente ou
- * de tipo errado ⇒ `false` ⇒ nao pausa. Sem plano legivel nao ha como AFIRMAR
- * que a feature gera midia, e uma regra nova nao trava feature legada.
- *
- * @param {Array<object>} tasks - `tasks.json` → `tasks[]` (qualquer coisa nao-array vira []).
- * @returns {boolean} true se ao menos uma task pinou um standard de midia.
- */
-export function featureGeneratesMedia(tasks) {
-  if (!Array.isArray(tasks)) return false;
-
-  return tasks.some((t) =>
-    Array.isArray(t?.standards) &&
-    t.standards.some((s) =>
-      typeof s === 'string' &&
-      MEDIA_STANDARD_PATHS.includes(s.replace(/^framework\//, ''))));
+// O plano escreve o standard pelo id ou pelo caminho (com ou sem `framework/`/`standards/`).
+export function standardIdOf(value) {
+  return String(value ?? '').trim().replace(/\\/g, '/')
+    .replace(/^(\.morph\/)?(framework\/)?(standards\/)?/, '')
+    .replace(/\.md$/, '')
+    .replace(/\//g, '-');
 }
 
-/** Read tasks.json's task list for a feature; [] if missing/corrupt. Mirrors verify.js's readTasks(). */
-function readTasks(featureName) {
-  try {
-    const tasksPath = getAbsoluteOutputPath(process.cwd(), featureName, 'tasks');
-    if (!existsSync(tasksPath)) return [];
-    return JSON.parse(readFileSync(tasksPath, 'utf8')).tasks || [];
-  } catch {
-    return [];
-  }
+// Decide se um guardrail arma: um predicado que sempre devolve `false` desarma em silêncio a
+// pausa de mídia da review e a rota opus.
+export function featureGeneratesMedia(slices) {
+  if (!Array.isArray(slices)) return false;
+  return slices.some((s) => Array.isArray(s?.standards)
+    && s.standards.some((id) => MEDIA_STANDARD_IDS.includes(standardIdOf(id))));
 }
 
-/**
- * "Esta feature mexeu em prompt ou em modelo?" — em duas metades, porque uma só
- * não distingue as duas situações que pedem ações diferentes.
- *
- * `declared: false` é "o projeto não declara caminho algum de prompt/modelo" —
- * a regra é inerte por construção e a razão registrada diz isso. `declared:
- * true` com `touched: []` é "declara, e nada foi tocado" — a regra rodou e não
- * viu nada. Colapsar os dois num array vazio faria um projeto que nunca
- * configurou `watch[]` parecer um projeto que foi verificado.
- *
- * O predicado NÃO é invenção deste framework: o repositório de referência já
- * roda exatamente ele em produção, disparando publicação por `paths:` sobre os
- * mesmos globs e decidindo o escopo com `git diff --name-only`.
- *
- * COLETA, NUNCA DECIDE. Nada aqui julga se o que foi tocado deveria pausar um
- * gate — política escrita no coletor cria duas fontes para o mesmo fato.
- *
- * @param {string} cwd
- * @param {string|null} defaultBranch
- * @returns {{declared: boolean, watch: string[], touched: string[]}}
- */
+// `declared: false` (nenhum caminho declarado: regra inerte) e `touched: []` (declarou, nada
+// tocado) não podem colapsar num array vazio. COLETA, NUNCA DECIDE: política no coletor cria
+// duas fontes para o mesmo fato.
 function collectPromptModel(cwd, defaultBranch) {
   const watch = readMorphConfig(cwd)?.project?.evals?.watch;
   const globs = Array.isArray(watch) ? watch.filter((g) => typeof g === 'string' && g.trim()) : [];
@@ -126,103 +54,73 @@ function collectPromptModel(cwd, defaultBranch) {
   };
 }
 
-/**
- * Collect every signal `shouldPauseGate()` (risk-detector.js) is documented
- * to consume, straight off disk — the deterministic call site risk-detector
- * never had (it shipped fully tested with zero callers; see the R4 report).
- *
- * `verificationStatus` feeds a real pause rule (verify vermelho pausa —
- * política adicionada em risk-detector.js no fecho do R4, qualquer gate).
- * `verificationStale` também alimenta uma regra própria, mas só no ship
- * (`gate === 'review'`) — sha do stamp divergindo do HEAD atual. `gate` em si
- * é o que permite risk-detector.js diferenciar as duas. `e2eStatus`/`e2eReason`
- * alimentam a regra da dispensa de e2e (também só no ship): um nó e2e que
- * PULOU não reprova o rollup, logo `verificationStatus` sai 'pass' e a razão
- * literal é o único fato que distingue dispensa legítima de ausência de prova.
- * `verificationScope` é o quarto sinal da mesma regra: um `verify {f} {task}`
- * carimba `scope: 'task:{id}'` e o e2e dele pula com a razão do GRUPO daquela
- * task, que risk-detector.js recusa como dispensa da feature.
- * `verification` completo, `e2eSkipClass`, diffstat e sha seguem como contexto
- * de auditoria persistido, sem regra própria.
- *
- * @param {string} featureName
- * @param {object} feature
- * @param {string} cwd
- * @param {string} gateName
- * @returns {object}
- */
+/** A regra única de quais relatórios o ship exige, lida por gate-check, approve e report-check. */
+export function collectReviewRequirement(cwd, feature) {
+  let changed = [];
+  try { changed = changedPathsAgainst(detectDefaultBranch(cwd), cwd); } catch { changed = []; }
+  const security = securityReviewFor(changed);
+  return { required: requiredReviewRoles({ workType: feature?.workType, securityRequired: security.required }), security };
+}
+
+export function collectReviewSignal(cwd, featureName, feature, planChecks = readPlanChecks(cwd, featureName)) {
+  const { required } = collectReviewRequirement(cwd, feature);
+  const checkIds = Array.isArray(planChecks.checks?.checks) ? planChecks.checks.checks.map((c) => c.id) : null;
+  return reviewSignal(reviewReports(cwd, featureName), { required, checkIds });
+}
+
+/** Why an automatic signature may not close the plan gate: the rule that makes gate-check pause it. */
+export function planAutoApprovalBlock(cwd, featureName) {
+  const reason = planChecksPause(readPlanChecks(cwd, featureName).status);
+  return reason ? reason.replace('{feature}', featureName) : null;
+}
+
+// Collects only; risk-detector.js decides. `e2eStatus`/`e2eReason` exist because a skipped e2e
+// node does not fail the rollup: the literal reason is the only fact separating a legitimate
+// waiver from missing proof.
 export function collectSignals(featureName, feature, cwd, gateName) {
-  const tasks = readTasks(featureName);
+  const planChecks = readPlanChecks(cwd, featureName);
+  const slices = planChecks.checks?.slices ?? null;
   const defaultBranch = detectDefaultBranch(cwd);
   const sha = getHeadSha(cwd);
   const verification = feature.verification || null;
 
   const signals = {
-    // Furo 2: disk-derived, never in OVERRIDABLE_SIGNAL_KEYS — a caller
-    // cannot spoof which gate risk-detector.js thinks it is deciding, same
-    // anti-spoof rationale as workType (hotfix's forced pause).
+    // Disk-derived, never overridable: a caller cannot spoof which gate is being decided.
     gate: gateName,
     workType: feature.workType || 'feature',
-    taskCount: tasks.length,
+    sliceCount: slices ? slices.length : null,
     standardsViolations: [],
     designSystemDivergence: false,
   };
 
-  // Fato de disco, fora de OVERRIDABLE_SIGNAL_KEYS: task que não cabe num
-  // dispatch se fatia no plano, não depois de um sub-agent bater no teto.
-  if (gateName === 'plan') signals.oversizedTasks = oversizedTasks({ tasks });
+  if (gateName === 'plan') signals.planChecks = planChecks.status;
 
-  // Só onde o checklist decide algo: no fecho do design e no ship. Fato de
-  // disco, fora de OVERRIDABLE_SIGNAL_KEYS.
+  // Só onde o checklist decide algo: no fecho do design e no ship.
   if (gateName === 'uiux' || gateName === 'review') {
     signals.screenChecklist = collectScreenChecklist(cwd, featureName, gateName);
   }
 
   if (gateName === 'review') {
-    signals.evaluatorVerdict = verdictSignal(evaluatorReportState(cwd, featureName));
+    signals.reviewReports = collectReviewSignal(cwd, featureName, feature, planChecks);
     signals.mediaClaims = {
-      section: evaluatorMediaSection(cwd, featureName),
-      featureGeneratesMedia: featureGeneratesMedia(tasks),
+      section: verifierMediaSection(cwd, featureName),
+      featureGeneratesMedia: featureGeneratesMedia(slices),
     };
   }
 
-  // verificationStatus alimenta a regra "verify vermelho pausa"; o resto do
-  // stamp é auditoria. verificationStale é fail-open na direção "not stale":
-  // stamp com sha null (checkout sem git) ou stamp ausente lê como NOT stale.
+  // verificationStale é fail-open: stamp sem sha (checkout sem git) ou ausente lê como NOT stale.
   signals.verification = verification;
   if (verification?.status) signals.verificationStatus = verification.status;
   signals.verificationStale = treeMovedSince(cwd, verification?.sha, sha);
 
-  // O nó e2e, separado do rollup de propósito: um `skip` NÃO reprova
-  // `verification.status`, então sem estas duas chaves o gate lê 'pass' tanto
-  // quando o e2e rodou e passou quanto quando ele nunca rodou. `null` aqui é
-  // DESCONHECIDO (stamp ausente, ou anterior ao nó e2e), nunca 'skip'.
-  // `e2eSkipClass` é DERIVADO pela fonte única (classifyE2eSkip, em
-  // risk-detector.js) e persistido só como auditoria — quem decide continua
-  // sendo shouldPauseGate, aqui não há política.
-  //
-  // Nenhuma das três entra em OVERRIDABLE_SIGNAL_KEYS: descrevem O QUE
-  // ACONTECEU no disco, como `gate`/`workType`, não uma opinião que o chamador
-  // possa afirmar. Um `--signals '{"e2eStatus":"pass"}'` compraria o Gate 3.
+  // Separado do rollup: um `skip` NÃO reprova `verification.status`. `null` é DESCONHECIDO, nunca
+  // 'skip'. Fora de OVERRIDABLE_SIGNAL_KEYS: um `--signals '{"e2eStatus":"pass"}'` compraria o ship.
   signals.e2eStatus = verification?.nodes?.e2e ?? null;
   signals.e2eReason = verification?.e2eReason ?? null;
   signals.e2eSkipClass = signals.e2eStatus === 'skip' ? classifyE2eSkip(signals.e2eReason) : null;
-  // De QUEM é o carimbo. `verify {f} {task}` grava 'task:{id}'; só 'feature'
-  // responde pela app inteira, e é por isso que este sinal existe: a razão
-  // 'task group "docs" does not touch runtime' é dispensa legítima do que
-  // AQUELA task verificou, e sem o escopo ela dispensaria o Gate 3 da feature.
-  // Fato de disco como os outros três — jamais sobrescrevível por --signals.
-  signals.verificationScope = verification?.scope ?? null;
 
-  // O nó de eval, separado do rollup pela mesma razão que o e2e: um eval que
-  // PULOU (escopo de task) não avermelha `verification.status`, então o gate
-  // leria 'pass' tanto para "o eval rodou e passou" quanto para "o eval nunca
-  // rodou". `null` aqui é "este projeto não declara nó de eval" — DISTINTO de
-  // 'skip', que é "declara, e esta corrida não o executou".
+  // Mesma razão do e2e. `null` = o projeto não declara nó de eval, DISTINTO de 'skip'.
   signals.evalsStatus = verification?.nodes?.evals ?? null;
-  // O que a feature TOCOU, contra os globs que o projeto declarou como
-  // prompt/modelo. Fato de disco: `declared` vem do config commitado, `touched`
-  // do git. Nenhuma política mora aqui — quem decide é shouldPauseGate.
   signals.promptModel = collectPromptModel(cwd, defaultBranch);
 
   signals.diffstat = getDiffStat(defaultBranch, cwd);
@@ -231,20 +129,8 @@ export function collectSignals(featureName, feature, cwd, gateName) {
   return signals;
 }
 
-/**
- * `morph-spec gate-check <feature> <gate> [--signals <json>] [--trust <mode>]
- * [--json]` — the deterministic, disk-derived counterpart to `gate-decision`:
- * collects the signals `shouldPauseGate()` (risk-detector.js) already knows
- * how to score, calls it, and persists the result through the SAME write path
- * as `gate-decision` ({@link persistGateDecision}) so the two commands can
- * never produce a differently-shaped `gateDecisions.{gate}` entry.
- *
- * Golden rule: this command does NOT change gate policy. It is a faithful
- * caller of risk-detector.js's existing, already-tested rules — nothing here
- * adds a new pause condition. Where the skills' natural-language risk tables
- * (morph-brainstorming/morph-plan/morph-review/morph-apply) diverge from
- * risk-detector.js, risk-detector.js wins (see the R4 report for the full list).
- */
+// Never changes gate policy: a faithful caller of risk-detector.js, which wins wherever the
+// skills' risk tables diverge. Persists through the same path as `gate-decision`.
 export async function gateCheckCommand(featureName, gateName, options = {}) {
   try {
     if (!VALID_GATES.includes(gateName)) {
@@ -259,10 +145,7 @@ export async function gateCheckCommand(featureName, gateName, options = {}) {
       process.exit(1);
     }
 
-    // Owner-tree guard: gate-check reads workType/tasks/verdict/git off cwd
-    // AND writes the resulting decision through persistGateDecision — both
-    // halves are wrong from a tree that isn't this feature's own, so refuse
-    // rather than compute a decision from stale reads and then fail to save it.
+    // Both the reads and the persisted decision are wrong from a tree that doesn't own the feature.
     const owner = assertOwnerTree(featureName, process.cwd());
     if (owner.blocked) {
       for (const { tone, text } of ownerTreeRefusalLines(featureName, owner.tree, owner.branch, `morph-spec gate-check ${featureName} ${gateName}`)) {
@@ -289,7 +172,7 @@ export async function gateCheckCommand(featureName, gateName, options = {}) {
       if (rejected.length > 0) {
         console.error(chalk.yellow(
           `\n⚠️  --signals ignored for keys not derived from disk-facts you may safely override: ${rejected.join(', ')}\n` +
-          `   Only ${OVERRIDABLE_SIGNAL_KEYS.join(', ')} may be overridden here — everything else is read from feature.json/tasks.json/git.\n` +
+          `   Only ${OVERRIDABLE_SIGNAL_KEYS.join(', ')} may be overridden here — everything else is read from feature.json/checks.json/git.\n` +
           `   Use \`morph-spec gate-decision\` directly for a fully manual decision.\n`
         ));
       }
@@ -303,9 +186,14 @@ export async function gateCheckCommand(featureName, gateName, options = {}) {
     const signals = { ...collectSignals(featureName, feature, cwd, gateName), ...overrides };
 
     const trust = options.trust || readTrustFromConfig();
-    const { pause, reason } = shouldPauseGate({ trust }, signals);
+    const computed = shouldPauseGate({ trust }, signals);
+    const manual = feature.gateDecisions?.[gateName];
+    const manualPause = manual?.source === 'manual' && manual.pause === true;
+    const { pause, reason } = manualPause ? { pause: true, reason: manual.reason } : computed;
 
-    const entry = await persistGateDecision(featureName, gateName, { pause, reason, signals, trust, cwd });
+    const entry = await persistGateDecision(featureName, gateName, {
+      pause, reason, signals, trust, cwd, source: manualPause ? 'manual' : 'gate-check',
+    });
 
     if (options.json) {
       console.log(JSON.stringify({ feature: featureName, gate: gateName, ...entry }, null, 2));
@@ -317,6 +205,9 @@ export async function gateCheckCommand(featureName, gateName, options = {}) {
       ? chalk.yellow(`\n⏸️  Gate "${gateName}" — PAUSE (${featureName})`)
       : chalk.green(`\n▶️  Gate "${gateName}" — auto-pass (${featureName})`));
     console.log(chalk.gray(`   reason: ${entry.reason} | trust: ${entry.trust} | decidedAt: ${entry.decidedAt}`));
+    if (manualPause) {
+      console.log(chalk.gray(`   pausa manual mantida (sinais calculados: ${computed.reason}); só \`morph-spec gate-decision ${featureName} ${gateName} --pause false\` a libera`));
+    }
     if (allSignals.length > 0) {
       console.log(chalk.gray(`   risk signals present: ${allSignals.join('; ')}`));
     }

package/src/commands/state/gate-decision.js

@@ -5,7 +5,7 @@ import { getFeature, updateFeature } from '../../core/state/state-manager.js';
 import { assertOwnerTree, ownerTreeRefusalLines } from '../../lib/worktree/feature-truth.js';
 import { mockupsHash } from '../../lib/specs/screen-checklist.js';
 
-export const VALID_GATES = ['proposal', 'uiux', 'plan', 'review'];
+export const VALID_GATES = ['plan', 'uiux', 'review'];
 
 function parsePauseValue(raw) {
   const v = String(raw).toLowerCase();
@@ -15,11 +15,7 @@ function parsePauseValue(raw) {
   process.exit(1);
 }
 
-/**
- * trust from the committed config (BOM-tolerant), defaulting to "auto".
- * Shared by `gate-decision` (recorded as metadata) and `gate-check`
- * (drives shouldPauseGate's decision directly).
- */
+/** `trust` from the committed config (BOM-tolerant), defaulting to "auto". */
 export function readTrustFromConfig() {
   try {
     const path = join(process.cwd(), '.morph', 'config', 'config.json');
@@ -32,24 +28,10 @@ export function readTrustFromConfig() {
 }
 
 /**
- * Write the canonical `gateDecisions.{gate}` entry to a feature's
- * authoritative feature.json — the ONE write path both `gate-decision` (a
- * caller-supplied pause/reason/signals, e.g. an LLM's natural-language risk
- * read, or a manual override) and `gate-check` (a `shouldPauseGate()`-derived
- * pause/reason/signals) feed into, so the two commands can never drift into
- * two different persisted shapes for the same field. Does NOT validate
- * `gateName` — callers that need a friendly CLI error check `VALID_GATES`
- * themselves before calling this.
- *
- * @param {string} featureName
- * @param {string} gateName
- * @param {{ pause: boolean, reason?: string, signals?: object, trust?: string, cwd?: string }} decision
- * @returns {Promise<{ pause: boolean, reason: string, signals: object, trust: string, decidedAt: string, mockupsHash?: string|null }>}
- *   the exact entry written (decidedAt is server-side, generated here). A uiux
- *   decision also carries the hash of the mockup it saw: it answers that
- *   mockup's pause, not the next one's.
+ * The ONE write path of `gateDecisions.{gate}`, shared by `gate-decision` and `gate-check`.
+ * Does not validate `gateName`. A uiux decision records the `mockupsHash` it saw.
  */
-export async function persistGateDecision(featureName, gateName, { pause, reason, signals = {}, trust, cwd = process.cwd() } = {}) {
+export async function persistGateDecision(featureName, gateName, { pause, reason, signals = {}, trust, cwd = process.cwd(), source } = {}) {
   const entry = {
     pause,
     reason: reason || (pause ? 'risco detectado' : 'nenhum sinal de risco'),
@@ -57,30 +39,13 @@ export async function persistGateDecision(featureName, gateName, { pause, reason
     trust: trust || readTrustFromConfig(),
     decidedAt: new Date().toISOString(),
     ...(gateName === 'uiux' ? { mockupsHash: mockupsHash(cwd, featureName) } : {}),
+    source,
   };
 
   await updateFeature(featureName, `gateDecisions.${gateName}`, entry);
   return entry;
 }
 
-/**
- * `morph-spec gate-decision <feature> <gate> --pause <bool> [--reason <txt>]
- * [--signals <json>] [--trust <mode>]` — record the trust decision for a gate
- * under `gateDecisions` in the authoritative feature.json.
- *
- * The timestamp (`decidedAt`) is
- * stamped server-side and the write is atomic (state-manager). This replaces
- * the manual Edit of feature.json from the skills — which collided with the
- * state-sync hook rewriting the file between the agent's Read and Edit
- * ("file modified since read"). The canonical shape is documented in
- * framework/schemas/feature.schema.json and consumed by gate-guard.js.
- *
- * The manual escape hatch: `gate-check` (src/commands/state/gate-check.js) is
- * the default, disk-derived path via `shouldPauseGate()`; this command stays
- * for a caller that already knows the decision (an LLM's natural-language
- * risk read a script can't see, or a deliberate override) — both write
- * through {@link persistGateDecision}, so the persisted shape never diverges.
- */
 export async function gateDecisionCommand(featureName, gateName, options = {}) {
   try {
     if (!VALID_GATES.includes(gateName)) {
@@ -118,7 +83,7 @@ export async function gateDecisionCommand(featureName, gateName, options = {}) {
         process.exit(1);
       }
       if (!signals || typeof signals !== 'object' || Array.isArray(signals)) {
-        console.error(chalk.red('\n❌ Invalid --signals: expected a JSON object, e.g. \'{"taskCount":12}\'\n'));
+        console.error(chalk.red('\n❌ Invalid --signals: expected a JSON object, e.g. \'{"standardsViolations":[]}\'\n'));
         process.exit(1);
       }
     }
@@ -128,6 +93,7 @@ export async function gateDecisionCommand(featureName, gateName, options = {}) {
       reason: options.reason,
       signals,
       trust: options.trust,
+      source: 'manual',
     });
 
     if (options.json) {

package/src/commands/state/handoff.js

@@ -1,34 +1,9 @@
-/**
- * `morph-spec handoff <feature>` — generate the compressed session-handoff
- * document (`.morph/features/{f}/handoff.md`).
- *
- * The fleet workflow hands a feature between Claude Code instances (a new
- * worktree session, a resumed session after a phase transition). The handoff
- * is the sanctioned way to carry context across: derived, regenerable, and
- * pointer-based (see handoff-generator.js). This command is also called
- * in-process by `worktree setup`, `create --worktree`, `advance` and
- * `approve` — the CLI surface exists for the LLM/user to refresh the
- * document on demand.
- *
- * WORKTREE-AWARE: `create --worktree` writes a COMPLETE feature.json into the
- * primary root and the branch-committed copy (`morph/{f}`) becomes the truth
- * from then on. Building the handoff from `process.cwd()` unconditionally
- * used to mean: run this from the root while the worktree is alive, and you
- * either got "Feature not found" (root's copy was already sheded) or a
- * document silently built from the stale birth skeleton, written INTO the
- * root (a second, always-defasada copy of a document that's supposed to be
- * regenerated, not duplicated). This resolves the owning tree first
- * (`resolveFeatureTree`) and writes THERE, unless `--here` forces the cwd.
- */
-
 import chalk from 'chalk';
 import { buildHandoff, writeHandoff } from '../../lib/generators/handoff-generator.js';
 import { resolveFeatureTree } from '../../lib/worktree/feature-truth.js';
 
-/**
- * @param {string} featureName
- * @param {{ json?: boolean, here?: boolean }} [options]
- */
+// With a live worktree the root copy is a stale birth skeleton: build and write in the
+// owning tree (`resolveFeatureTree`) unless `--here` forces the cwd.
 export function handoffCommand(featureName, options = {}) {
   const cwd = process.cwd();
 
@@ -44,9 +19,7 @@ export function handoffCommand(featureName, options = {}) {
   }
 
   if (owner.source === 'branch-only') {
-    // The truth exists, committed on morph/{feature}, but is not materialized
-    // into ANY tree right now. A handoff points at files on disk — pointing
-    // at files that exist nowhere is worse than recusing outright.
+    // The handoff points at files on disk; a truth materialized in no tree is refused.
     const hint = `morph-spec worktree setup ${featureName}  (ou: git checkout ${owner.branch})`;
     if (options.json) {
       console.log(JSON.stringify({ error: 'feature-not-in-tree', feature: featureName, branch: owner.branch, hint }));
@@ -87,6 +60,6 @@ export function handoffCommand(featureName, options = {}) {
   if (tree !== cwd) {
     console.log(chalk.yellow(`   resolvido para ${tree} — a cópia da raiz é esqueleto de nascimento, não a verdade.`));
   }
-  console.log(chalk.gray(`   fase ${result.meta.phase} · tasks ${result.meta.tasksDone}/${result.meta.tasksTotal} · ${result.meta.generatedAt}`));
+  console.log(chalk.gray(`   fase ${result.meta.phase} · fatias ${result.meta.slicesDone}/${result.meta.slicesTotal} · ${result.meta.generatedAt}`));
   console.log(chalk.gray('   A próxima sessão lê este documento antes de continuar (ponteiros, não cópias).\n'));
 }