@polymorphism-tech/morph-spec 8.20.0 → 8.21.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:** 8.20.0  
+**Version:** 8.21.0  
 **Requires:** Node.js 22+, Claude Code
 
 ---
@@ -368,4 +368,4 @@ Code generated by morph-spec (contracts, templates, implementation output) belon
 
 ---
 
-*morph-spec v8.20.0 by [Polymorphism Tech](https://polymorphism.tech)*
+*morph-spec v8.21.0 by [Polymorphism Tech](https://polymorphism.tech)*

package/bin/morph-spec.js

@@ -428,7 +428,8 @@ program
 program
   .command('cost [feature]')
   .description('Cost-facing view over .morph/logs/events.jsonl: task duration, bytes re-ingested by kind (proxy, not tokens), dispatch counts')
-  .option('--by <mode>', 'Group by: task|phase (default: feature-wide summary)')
+  .option('--by <mode>', 'Group by: task|phase (default: feature-wide summary; with --all-trees, applies to the combined aggregate)')
+  .option('--all-trees', 'Aggregate .morph/logs/events.jsonl across every git worktree that has one, not just the current tree — per-tree breakdown + combined total')
   .option('--json', 'Output the aggregate as JSON')
   .action((feature, options) => costCommand(feature, options));
 

package/claude-plugin.json

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

@@ -185,4 +185,4 @@ Never edited directly — go through CLI commands or `morph-spec update` instead
 
 ---
 
-*morph-spec v8.20.0 by Polymorphism Tech*
+*morph-spec v8.21.0 by Polymorphism Tech*

package/docs/QUICKSTART.md

@@ -249,4 +249,4 @@ morph-spec doctor
 
 ---
 
-*morph-spec v8.20.0 by Polymorphism Tech*
+*morph-spec v8.21.0 by Polymorphism Tech*

package/framework/agents.json

@@ -102,7 +102,7 @@
         "design", "ui", "ux", "design system", "tokens", "wcag",
         "accessibility", "mockup", "flow", "shadcn", "tailwind"
       ],
-      "stack": ["nextjs"],
+      "stack": ["*"],
       "standards": [
         "frontend-design-system-naming",
         "frontend-design-system-animations",

package/framework/docs/CLI.md

@@ -9,7 +9,7 @@
 - **`morph-spec approve <feature> <gate> --mode auto`** — aprova um gate (`proposal`/`uiux`/`plan`/`review`) em `trust: auto`. **`uiux`** é o único gate cujo `AskUserQuestion` o hook `state-sync.js` não reconhece por texto (só casa "Gate 1/2/3") — aprove-o sempre explicitamente por este comando ou por `advance`, nunca contando com o hook. **O Gate 3 exige `4-review/evaluator-report.md`**: sem o relatório do avaliador independente o comando recusa (exit 1). Se o dispatch do avaliador for impossível nesta sessão, aprove com `--self-assessed` — a degradação é gravada em `approvalGates.review.selfAssessed` e aparece marcada no `morph-spec list`. `--force` **não** dispensa esta regra (é só para ordem de gate). **Exceção `hotfix`:** esse tipo nunca despacha o avaliador (`morph-hotfix` §7); o Gate 3 exige `4-review/review-report.md` no lugar do `evaluator-report.md`, e a assinatura humana continua obrigatória via `--approver` (o backstop de `--mode auto` acima permanece recusando).
 - **`morph-spec advance <feature>`** — aprova o gate da fase corrente **e** cria a pasta da próxima fase num passo só (`--design` toma o ramo opcional de uiux a partir da proposta).
 - **`morph-spec score <feature> <task> <score> [--dims a,c,q,t]`** — grava `taskScores` no feature.json com timestamp server-side; **nunca edite taskScores à mão**. Em PowerShell, cite o valor de `--dims` entre aspas (`--dims "9.5,9,9,9"`) — sem aspas, a lista pode chegar como tokens separados; o parser aceita ambas as formas, mas citar evita qualquer ambiguidade.
-- **`morph-spec gate-check <feature> <gate> [--signals <json>] [--trust <mode>] [--json]`** — o caminho **default**: coleta do disco os sinais que `shouldPauseGate` (risk-detector.js) já sabe avaliar (`workType`, `taskCount`, verificação, sha/diffstat), decide a pausa e persiste `gateDecisions.{gate}`. `--signals` aceita só as chaves que o disco genuinamente não expõe sozinho — `designSystemDivergence`, `standardsViolations`, `evalScore` — qualquer outra chave é ignorada com aviso. No **review**, o `evalScore` real vem do token `**Composite-Score:** {n.n}` do `evaluator-report.md` (o avaliador o grava por contrato); sem o token, cai no proxy (média das `taskScores`); `--signals` vence ambos. Um stamp de `verification` com status `fail` (último `morph-spec verify` vermelho) **força pausa** em qualquer gate.
+- **`morph-spec gate-check <feature> <gate> [--signals <json>] [--trust <mode>] [--json]`** — o caminho **default**: coleta do disco os sinais que `shouldPauseGate` (risk-detector.js) já sabe avaliar (`workType`, `taskCount`, verificação, sha/diffstat), decide a pausa e persiste `gateDecisions.{gate}`. `--signals` aceita só as chaves que o disco genuinamente não expõe sozinho — `designSystemDivergence`, `standardsViolations`, `evalScore` — qualquer outra chave é ignorada com aviso. No **review**, o `evalScore` real vem do token `**Composite-Score:** {n.n}` do `evaluator-report.md` (o avaliador o grava por contrato); sem o token, cai no proxy (média das `taskScores`); `--signals` vence ambos. Um stamp de `verification` com status `fail` (último `morph-spec verify` vermelho) **força pausa** em qualquer gate. Um stamp `pass` mas **stale** (sha diferente do HEAD atual — código mudou depois do último verify) força pausa **só no ship** (`review`); em `plan`/`uiux`/`proposal` a staleness é computada e reportada em `signals`, mas não pausa nada — é regra de ship, não de gate genérico. Stamp **ausente** nunca pausa por isso (features legadas sem stamp).
 - **`morph-spec gate-decision <feature> <gate> --pause <bool> [--reason <txt>] [--signals <json>]`** — o **escape manual**: registra uma decisão já tomada pela sessão (ex.: `discoveryMode: "interview"`, sinal que `shouldPauseGate` nem representa). Mesmo write path do `gate-check` — grava `gateDecisions` no feature.json com timestamp server-side (shape em `framework/schemas/feature.schema.json`); **nunca edite gateDecisions à mão** — o Edit manual colide com o hook state-sync.
 
 ## Features
@@ -38,4 +38,4 @@
 ## Observabilidade
 
 - **`morph-spec telemetry [--json] [--feature <f>] [--limit <n>]`** — reconstrói o caminho de execução da sessão a partir de `.morph/logs/events.jsonl` (skills invocadas, personas despachadas + prompts, standards/base de conhecimento lidos, mix de tools, prompts do usuário). Capturado silenciosamente pelo hook `telemetry-log` em todo tool call e todo UserPromptSubmit.
-- **`morph-spec cost [feature] [--by task|phase] [--json]`** — custo da execução a partir do mesmo `events.jsonl`: duração por task (TaskStart→TaskEnd), bytes de contexto re-ingerido por tipo (`rubric`/`standard`/`skill`/`agents`/`plan-artifact`/`code`), dispatches + tamanho de prompt e mix de tools. Bytes re-ingeridos são **proxy determinística** de custo de token (tokens reais não são observáveis por hook). Use antes/depois de mudar skill ou fluxo para medir o efeito.
+- **`morph-spec cost [feature] [--by task|phase] [--all-trees] [--json]`** — custo da execução a partir do mesmo `events.jsonl`: duração por task (TaskStart→TaskEnd), bytes de contexto re-ingerido por tipo (`rubric`/`standard`/`skill`/`agents`/`plan-artifact`/`code`), dispatches + tamanho de prompt e mix de tools. Bytes re-ingeridos são **proxy determinística** de custo de token (tokens reais não eram observáveis por hook até o evento `SessionUsage` — quando presente no stream, `inputTokens`/`outputTokens`/`cacheReadTokens`/`cacheCreationTokens` são somados e exibidos à parte como "tokens reais", nunca misturados com a proxy de bytes). `--all-trees` agrega `.morph/logs/events.jsonl` de **toda árvore git** que tiver um (não só a corrente) — reusa a mesma enumeração de worktree do `doctor --worktrees`/`fleet`; mostra um resumo por árvore + o total combinado (`--by` aplica ao agregado combinado). Use antes/depois de mudar skill ou fluxo para medir o efeito.

package/framework/hooks/claude-code/core/enforce-phase-writes.js

@@ -102,8 +102,29 @@ export async function run(payload) {
       // advances once that file exists) — the deadlock this hook used to create.
       const entryGate = PHASE_DIR_ENTRY_GATE[targetDir];
       if (entryGate && isGateApproved(featureName, entryGate, root)) {
-        logHookActivity('enforce-phase-writes', 'PreToolUse', 'ok');
-        return null;
+        // uiux is OPTIONAL — proposal approval alone is enough to enter
+        // 2-plan/ for a feature that never took the design branch (no
+        // 1-design/ dir), exactly as before this check. But once a feature
+        // HAS opted into uiux (1-design/ exists), that gate is not
+        // decorative: 2-plan/ must wait for it too, or a feature can skip
+        // straight from an approved proposal into planning with its design
+        // gate silently left pending.
+        const tookDesignBranch = targetDir === '2-plan'
+          && existsSync(resolveTargetPath(`.morph/features/${featureName}/1-design`, root));
+
+        if (!tookDesignBranch || isGateApproved(featureName, 'uiux', root)) {
+          logHookActivity('enforce-phase-writes', 'PreToolUse', 'ok');
+          return null;
+        }
+
+        logHookActivity('enforce-phase-writes', 'PreToolUse', 'blocked');
+        return blockResult(
+          `MORPH-SPEC: Writing to '2-plan/' is not allowed yet.\n` +
+          `This feature entered the uiux branch (1-design/ exists) and the 'uiux' gate is still pending.\n\n` +
+          `Approve the design gate first, then re-enter plan:\n` +
+          `  morph-spec approve ${featureName} uiux\n` +
+          `  morph-spec advance ${featureName}`
+        );
       }
 
       const phaseLabel = phase.toUpperCase();

package/framework/hooks/claude-code/core/state-sync.js

@@ -94,6 +94,11 @@ function isApprovalAnswer(answer) {
 
 function gateFromQuestion(question) {
   if (typeof question !== 'string') return null;
+  // Checked BEFORE the generic patterns below: the pinned uiux template is
+  // "Gate uiux — Design de {feature} aprovado?" (morph-uiux/SKILL.md) — it
+  // must never fall through to 'plan' via a stray "plan"/"plano" substring in
+  // the feature name. `/gate\s+uiux/i` alone is unambiguous either way.
+  if (/gate\s+uiux/i.test(question)) return 'uiux';
   const lower = question.toLowerCase();
   if (lower.includes('gate 1') || lower.includes('proposta')) return 'proposal';
   if (lower.includes('gate 2') || lower.includes('plano') || lower.includes('plan')) return 'plan';

package/framework/hooks/claude-code/core/telemetry-log.js

@@ -41,6 +41,32 @@ function normalize(p) {
   return (p || '').replace(/\\/g, '/');
 }
 
+// events.jsonl grows forever across a project's lifetime (R2 rotation caps
+// the FILE, not any single line) — a multi-KB sub-agent prompt or a long
+// Bash command written verbatim on every dispatch/call is the dominant per-
+// line cost. Capped AT THE WRITE SITE (not in the shared logger, so every
+// OTHER event type stays exactly as-is) to `MAX_FIELD_CHARS`, with the
+// ORIGINAL length preserved in a sibling `<field>Chars` key — `morph-spec
+// cost` sums prompt chars for its dispatch-cost view, and must prefer that
+// field over `prompt.length` once it's present (a truncated string's own
+// length would silently undercount every dispatch over the cap). This shape
+// is a CONTRACT with the telemetry reader — do not rename either half.
+const MAX_FIELD_CHARS = 2000;
+const TRUNCATE_SUFFIX = '…[truncado]';
+
+/**
+ * Cap a free-text field (prompt/command) at MAX_FIELD_CHARS, always
+ * reporting the field's true original length alongside it.
+ *
+ * @param {string} value
+ * @returns {{ value: string, chars: number }}
+ */
+function capField(value) {
+  const str = typeof value === 'string' ? value : '';
+  if (str.length <= MAX_FIELD_CHARS) return { value: str, chars: str.length };
+  return { value: str.slice(0, MAX_FIELD_CHARS) + TRUNCATE_SUFFIX, chars: str.length };
+}
+
 /**
  * Classify a Read target into the telemetry `kind` taxonomy — a contract with
  * the observability side (src/lib/telemetry/telemetry-reader.js), so these
@@ -144,7 +170,8 @@ export async function run(payload) {
 
     // UserPromptSubmit carries the user's prompt and no tool_name.
     if (payload.hook_event_name === 'UserPromptSubmit' || (!payload.tool_name && typeof payload.prompt === 'string')) {
-      event = { event: 'UserPromptSubmit', tool: 'UserPrompt', prompt: payload.prompt || '' };
+      const userPrompt = capField(payload.prompt || '');
+      event = { event: 'UserPromptSubmit', tool: 'UserPrompt', prompt: userPrompt.value, promptChars: userPrompt.chars };
     } else {
       const tool = payload.tool_name;
       if (!tool) return null;
@@ -156,7 +183,9 @@ export async function run(payload) {
       } else if (tool === 'Agent' || tool === 'Task') {
         event.persona = input.subagent_type || '';
         if (input.description) event.desc = input.description;
-        event.prompt = input.prompt || '';
+        const dispatchPrompt = capField(input.prompt || '');
+        event.prompt = dispatchPrompt.value;
+        event.promptChars = dispatchPrompt.chars;
       } else if (tool === 'Read') {
         event.target = targetFilePath || normalize(input.file_path || input.path);
         event.kind = classifyReadKind(event.target);
@@ -169,7 +198,9 @@ export async function run(payload) {
           // omit bytes
         }
       } else if (tool === 'Bash') {
-        event.command = input.command || '';
+        const bashCommand = capField(input.command || '');
+        event.command = bashCommand.value;
+        event.commandChars = bashCommand.chars;
       } else if (tool === 'Write' || tool === 'Edit') {
         event.target = normalize(input.file_path || input.path);
       } else {

package/framework/hooks/claude-code/core/validate-completion.js

@@ -21,7 +21,7 @@
  * Fail-open: exits 0 on any error.
  */
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from 'fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync, statSync } from 'fs';
 import { join } from 'path';
 import { createHash } from 'crypto';
 import { runBuildCheck } from '../../shared/build-check.js';
@@ -30,6 +30,7 @@ import {
 } from '../../shared/state-reader.js';
 import { contextResult, runStandalone } from '../../shared/hook-response.js';
 import { logHookActivity, logEvent } from '../../shared/activity-logger.js';
+import { appendTelemetryEvent } from '../../shared/telemetry-logger.js';
 
 /**
  * Audit recap.md against tasks.json + standard-citation rule.
@@ -121,6 +122,80 @@ function auditRecapAndTasks(featurePath) {
   return warnings;
 }
 
+// Safety valve for a pathological outlier transcript — NOT needed for the
+// normal case: a real 45 MB / ~16k-line transcript (inspected directly while
+// building this) parses+sums in ~350ms locally, well inside a Stop hook's
+// budget. Above this, skip rather than risk an unbounded read.
+const MAX_TRANSCRIPT_BYTES = 50 * 1024 * 1024; // 50 MB
+
+/**
+ * Sum real token usage from a Claude Code session transcript (JSONL, the
+ * `transcript_path` the Stop payload carries).
+ *
+ * Each assistant TURN is written to the transcript as MULTIPLE JSONL lines —
+ * one per content block (thinking/text/tool_use) — every one of them
+ * repeating the exact SAME turn-level `message.usage` object under the same
+ * `message.id`. Verified against a real transcript: 5982 assistant lines but
+ * only 3315 unique message ids, with byte-identical usage across duplicates
+ * of the same id — summing every line naively double/triple-counts (measured
+ * ~2x on output_tokens on that file). This is why a per-line sum is wrong and
+ * a dedup-by-id sum is required; there is no running/cumulative total field
+ * to lean on instead — each turn's `usage` is that turn's own cost.
+ *
+ * Tolerant to shape: any missing usage field reads as 0. A corrupt/truncated
+ * line is skipped, not fatal — same discipline as telemetry-logger's reader.
+ *
+ * @param {string} [transcriptPath]
+ * @returns {{inputTokens:number,outputTokens:number,cacheReadTokens:number,cacheCreationTokens:number}|null}
+ *   null when there is nothing to report (no path, missing/oversized/
+ *   unreadable file, or zero assistant messages carrying usage).
+ */
+function computeSessionUsage(transcriptPath) {
+  if (!transcriptPath || typeof transcriptPath !== 'string') return null;
+  try {
+    if (!existsSync(transcriptPath)) return null;
+    if (statSync(transcriptPath).size > MAX_TRANSCRIPT_BYTES) return null;
+
+    const raw = readFileSync(transcriptPath, 'utf-8');
+    let inputTokens = 0, outputTokens = 0, cacheReadTokens = 0, cacheCreationTokens = 0;
+    const seenMessageIds = new Set();
+    let sawAny = false;
+
+    for (const line of raw.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      let entry;
+      try {
+        entry = JSON.parse(trimmed);
+      } catch {
+        continue; // one corrupt/truncated line must not lose the whole transcript
+      }
+      if (entry?.type !== 'assistant') continue;
+      const usage = entry?.message?.usage;
+      if (!usage || typeof usage !== 'object') continue;
+
+      // Dedup by message.id (fallback to the line's own uuid when a message
+      // carries none) — first occurrence wins, duplicates carry identical
+      // values so which one wins never matters.
+      const dedupKey = entry?.message?.id || entry?.uuid;
+      if (dedupKey) {
+        if (seenMessageIds.has(dedupKey)) continue;
+        seenMessageIds.add(dedupKey);
+      }
+
+      sawAny = true;
+      inputTokens += Number(usage.input_tokens) || 0;
+      outputTokens += Number(usage.output_tokens) || 0;
+      cacheReadTokens += Number(usage.cache_read_input_tokens) || 0;
+      cacheCreationTokens += Number(usage.cache_creation_input_tokens) || 0;
+    }
+
+    return sawAny ? { inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens } : null;
+  } catch {
+    return null; // fail-open
+  }
+}
+
 // Phases where compaction is strongly recommended before starting
 const COMPACT_TRIGGER_PHASES = new Set(['implement']);
 
@@ -128,12 +203,15 @@ const COMPACT_TRIGGER_PHASES = new Set(['implement']);
 const HEAVY_SOURCE_PHASES = new Set(['plan', 'uiux']);
 
 /**
- * @param {object} _payload - parsed Stop stdin payload (unused — this hook
- *   reads its own state from disk, not from the tool payload)
+ * @param {object} payload - parsed Stop stdin payload. Most of this hook's
+ *   logic reads its own state from disk rather than the payload, EXCEPT the
+ *   session-usage capture below, which needs `payload.transcript_path` (and
+ *   `payload.session_id` for the throttle key) — the one thing only the
+ *   payload carries.
  * @returns {Promise<object|null>} a hookSpecificOutput advisory (phase
  *   transition / build failure / recap drift), or null (pass/silent).
  */
-export async function run(_payload) {
+export async function run(payload) {
   try {
     // Prevent infinite loop
     if (process.env.MORPH_STOP_HOOK_ACTIVE === '1') return null;
@@ -264,6 +342,40 @@ export async function run(_payload) {
     }
     // ────────────────────────────────────────────────────────────────────────
 
+    // ── Session usage (real tokens, from the transcript) ──────────────────────
+    // Silent side effect — never contributes to `warnings`/additionalContext,
+    // same as telemetry-log.js's capture. Throttled: only re-emitted when the
+    // computed totals actually changed since the last SessionUsage recorded
+    // for this session_id, so an unchanged transcript across consecutive
+    // Stops (no new assistant turn) does not re-append an identical event.
+    try {
+      const usage = computeSessionUsage(payload?.transcript_path);
+      if (usage) {
+        const usagePath = join(memDir, 'session-usage.json');
+        let stored = {};
+        try {
+          if (existsSync(usagePath)) stored = JSON.parse(readFileSync(usagePath, 'utf-8'));
+        } catch { /* corrupt file — start fresh */ }
+
+        const sessionKey = payload?.session_id || 'default';
+        const last = stored[sessionKey];
+        const unchanged = last
+          && last.inputTokens === usage.inputTokens
+          && last.outputTokens === usage.outputTokens
+          && last.cacheReadTokens === usage.cacheReadTokens
+          && last.cacheCreationTokens === usage.cacheCreationTokens;
+
+        if (!unchanged) {
+          appendTelemetryEvent({ event: 'SessionUsage', ...usage }, cwd);
+          stored[sessionKey] = usage;
+          try { writeFileSync(usagePath, JSON.stringify(stored, null, 2), 'utf-8'); } catch { /* non-blocking */ }
+        }
+      }
+    } catch {
+      // Fail-open — usage capture must never block Stop
+    }
+    // ────────────────────────────────────────────────────────────────────────
+
     if (warnings.length === 0) return null;
 
     const message = [

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

@@ -27,7 +27,10 @@
  * Also the real call site for activity-log rotation (R1.2 of the performance
  * plan): SessionStart is the only reliable "between sessions" checkpoint the
  * harness gets, so this is where `.morph/logs/activity.jsonl` gets archived
- * to `.morph/logs/sessions/` once it crosses the size threshold.
+ * to `.morph/logs/sessions/` once it crosses the size threshold. The same
+ * checkpoint now also rotates `.morph/logs/events.jsonl` (telemetry-logger.js)
+ * once IT crosses its own threshold — events.jsonl grew unbounded even after
+ * R1.2, since that rotation only ever covered activity.jsonl.
  *
  * Fail-open: any error, or nothing to report, → pass() silently. This hook
  * never blocks a session from starting.
@@ -46,6 +49,7 @@ import {
 import { contextResult, runStandalone } from '../../shared/hook-response.js';
 import { acquireClaim, foreignClaim, claimAge } from '../../shared/claim-registry.js';
 import { rotateActivityLogIfLarge } from '../../shared/activity-logger.js';
+import { rotateEventsLogIfLarge } from '../../shared/telemetry-logger.js';
 
 function projectDir() {
   return process.env.CLAUDE_PROJECT_DIR || process.cwd();
@@ -223,10 +227,11 @@ export async function run(payload) {
       return null;
     }
 
-    // Rotate the activity log before anything else touches it this session.
-    // Best-effort, never fatal to session start — rotateActivityLogIfLarge()
-    // is itself fail-open (returns false on any error).
+    // Rotate the activity + events logs before anything else touches them
+    // this session. Best-effort, never fatal to session start — both rotate*
+    // helpers are themselves fail-open (return false on any error).
     try { rotateActivityLogIfLarge(dir); } catch { /* non-blocking */ }
+    try { rotateEventsLogIfLarge(dir); } catch { /* non-blocking */ }
 
     if (isSecondaryWorktree(dir)) {
       const feature = featureFromBranch(dir) || featureFromSingleDir(dir);

package/framework/hooks/shared/telemetry-logger.js

@@ -16,12 +16,22 @@
  * - Windows-safe paths via path.join
  */
 
-import { appendFileSync, readFileSync, mkdirSync, existsSync } from 'fs';
+import {
+  appendFileSync, readFileSync, mkdirSync, existsSync, statSync, renameSync,
+} from 'fs';
 import { join, dirname } from 'path';
 
 const LOGS_DIR = '.morph/logs';
 export const EVENTS_FILE = join(LOGS_DIR, 'events.jsonl');
 
+// SessionStart (worktree-context.js) rotates events.jsonl once it crosses
+// this size, alongside the pre-existing activity.jsonl rotation — same
+// call site, same "between sessions" checkpoint. events.jsonl has no natural
+// per-turn cap (prompts/commands are truncated at the write site, but the
+// LINE COUNT itself grows unbounded across a long-lived project), so without
+// this it grows forever the way activity.jsonl used to before R1.2.
+export const ROTATE_THRESHOLD_BYTES = 5 * 1024 * 1024; // 5 MB
+
 function getEventsPath(projectPath) {
   return join(projectPath || process.cwd(), EVENTS_FILE);
 }
@@ -73,3 +83,56 @@ export function readTelemetryEvents(projectPath) {
     return [];
   }
 }
+
+/**
+ * Archive the current events.jsonl to `.morph/logs/sessions/`, mirroring
+ * activity-logger.js's `archiveSession()` — same directory, same rename-not-
+ * rewrite mechanics (O(1) even at multi-MB sizes). Named with an `events-`
+ * prefix (activity-logger's archives carry no prefix) so the two streams
+ * never collide inside the shared `sessions/` directory and stay
+ * distinguishable at a glance.
+ *
+ * Fail-silent — called only from `rotateEventsLogIfLarge` below, which has
+ * already confirmed the file exists.
+ *
+ * @param {string} [projectPath]
+ */
+function archiveEvents(projectPath) {
+  try {
+    const eventsPath = getEventsPath(projectPath);
+    if (!existsSync(eventsPath)) return;
+
+    const sessionsDir = join(projectPath || process.cwd(), LOGS_DIR, 'sessions');
+    mkdirSync(sessionsDir, { recursive: true });
+
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const archivePath = join(sessionsDir, `events-${stamp}.jsonl`);
+    renameSync(eventsPath, archivePath);
+  } catch {
+    // Fail-silent
+  }
+}
+
+/**
+ * Rotate events.jsonl when it crosses `thresholdBytes`. Called from
+ * worktree-context.js on SessionStart, right next to the existing
+ * `rotateActivityLogIfLarge()` call — the only reliable "between sessions"
+ * checkpoint the harness gets. `thresholdBytes` is injectable so a test can
+ * force rotation without writing multiple megabytes.
+ *
+ * @param {string} [projectPath] - Project root (defaults to cwd)
+ * @param {number} [thresholdBytes] - Rotate once the log is at least this large
+ * @returns {boolean} true if a rotation was performed
+ */
+export function rotateEventsLogIfLarge(projectPath, thresholdBytes = ROTATE_THRESHOLD_BYTES) {
+  try {
+    const eventsPath = getEventsPath(projectPath);
+    if (!existsSync(eventsPath)) return false;
+    const { size } = statSync(eventsPath);
+    if (size < thresholdBytes) return false;
+    archiveEvents(projectPath);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/framework/schemas/tasks.schema.json

@@ -39,7 +39,7 @@
           "standards": {
             "type": "array",
             "items": { "type": "string", "minLength": 1 },
-            "description": "Standards pinned by morph-plan for this task, as paths relative to the framework root (e.g. \"standards/backend/dotnet/vsa-handler-patterns.md\"). Optional. Part of the plan contract: frozen after Gate 2."
+            "description": "Standards pinned by morph-plan for this task, as PATHS relative to the framework root (e.g. \"standards/backend/dotnet/vsa-handler-patterns.md\"). Optional. Part of the plan contract: frozen after Gate 2. NOT the same vocabulary as agents.json's top-level `standards` field, which lists IDs (e.g. \"backend-dotnet-vsa-handler-patterns\", no slashes/extension) — same field name, different shape; do not treat one as the other."
           }
         },
         "additionalProperties": false

package/framework/skills/core/create-umbraco-lp/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a criação de uma landing page nova ponta-a-ponta a partir do
 version: core
 when-to-invoke: ao iniciar um novo projeto de LP com o template Umbraco genérico
 user-invokable: true
-cliVersion: "8.20.0"
+cliVersion: "8.21.0"
 stacks:
   - umbraco
 ---

package/framework/skills/core/migrate-lp-to-umbraco/SKILL.md

@@ -4,7 +4,7 @@ description: Migra uma landing page existente (React/Vite, Next.js estático ou
 version: core
 when-to-invoke: ao receber instrução "use /migrate-lp-to-umbraco {projeto}" do usuário, ou quando o usuário descrever necessidade de migrar uma LP para Umbraco
 user-invokable: true
-cliVersion: "8.20.0"
+cliVersion: "8.21.0"
 stacks:
   - umbraco
 ---

package/framework/skills/core/morph-apply/SKILL.md

@@ -4,7 +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: "8.20.0"
+cliVersion: "8.21.0"
 ---
 
 # morph-apply
@@ -208,21 +208,12 @@ Quando `getPendingTasks(data).length === 0`:
 - Invocar `Skill(morph-review)` para gerar `.morph/features/{feature}/4-review/review-report.md`.
 - A skill morph-review chama `morph-eval` em escopo de feature inteira.
 
-### 5. Gate 3 (trust-aware)
+### 5. Gate 3
 
-Rode `morph-spec gate-check {feature} review [--json]` — lê `trust`, decide via `shouldPauseGate` e persiste `gateDecisions.review` com timestamp server-side (shape canônico em `.morph/framework/schemas/feature.schema.json`), imprimindo `pause`/`reason`/`signals`. É o default — não recompute a tabela do MORPH.md §5 em linguagem natural.
-
-**`evalScore` sem override é uma PROXY** (média das `taskScores`, não o score composto real). Passe o composto do `review-report.md` (avaliador independente) e qualquer violação que ele tenha encontrado via `--signals` — as únicas chaves que este comando aceita sobrescrever:
-```
-morph-spec gate-check {feature} review --signals '{"evalScore":9.2,"standardsViolations":[]}'
-```
-
-Risco que nenhuma dessas chaves representa (julgamento do avaliador que não vira `standardsViolations`): use `gate-decision` direto em vez de `gate-check`.
-
-**Nunca edite `feature.json` à mão** (colide com o hook state-sync — erro "file modified since read"). Os caminhos acima gravam no mesmo lugar; o hook `gate-guard.js` confere depois se a ação bateu com a decisão persistida.
-
-- Pause: `AskUserQuestion` com options `["aprovado, fechar feature", "preciso ajustar", "rollback"]`.
-- Auto: exibir summary do review-report, aprovar via `morph-spec approve {feature} review --mode auto`, e prosseguir.
+Apresentado e persistido por `morph-review` §8 (invocada no passo 4 acima) — gate-check, template
+fixo nomeando a feature, aprovação registrada pós-resposta. Ao retomar o controle dela, **NÃO
+re-apresente o gate**: siga direto para o encerramento (§6) conforme a decisão já persistida em
+`gateDecisions.review`.
 
 ### 6. Pós Gate 3 — encerramento
 

package/framework/skills/core/morph-brainstorming/SKILL.md

@@ -4,7 +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: "8.20.0"
+cliVersion: "8.21.0"
 ---
 
 # morph-brainstorming
@@ -147,6 +147,6 @@ options:
 
 ## Referências
 - `.morph/framework/MORPH.md` — seções 1 (Papéis), 2 (Fases), 5 (Gates), Trust Mode
-- `.morph/framework/standards/STANDARDS.json` — para referência de standards relevantes à stack
+- `morph-spec standards --find "<query>"` — para referência de standards relevantes à stack (ver `morph-standards`)
 - `framework/skills/core/morph-stack-scan/SKILL.md` — invocada na Parte 0 (varredura), antes de qualquer pergunta
 - `.morph/framework/MORPH.md` §5 — regras de pausa do Gate 1 (trust mode)

package/framework/skills/core/morph-eval/SKILL.md

@@ -4,7 +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: "8.20.0"
+cliVersion: "8.21.0"
 ---
 
 # morph-eval

package/framework/skills/core/morph-hotfix/SKILL.md

@@ -4,7 +4,7 @@ description: ADW cirúrgico de hotfix — resolve uma queda/bug crítico de prod
 version: core
 when-to-invoke: ao receber "/morph-hotfix {feature}", quando a morph-proposal classifica o pedido como workType hotfix (Passo 0), ou o usuário diz "produção caiu / hotfix / urgente"
 user-invokable: true
-cliVersion: "8.20.0"
+cliVersion: "8.21.0"
 ---
 
 # morph-hotfix

package/framework/skills/core/morph-implement/SKILL.md

@@ -4,7 +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: "8.20.0"
+cliVersion: "8.21.0"
 ---
 
 # morph-implement

package/framework/skills/core/morph-plan/SKILL.md

@@ -4,7 +4,7 @@ description: Guia a produção dos artefatos de planejamento de uma feature (use
 version: core
 when-to-invoke: ao iniciar a fase plan de uma feature, após o Gate 1 (proposal aprovado)
 user-invokable: true
-cliVersion: "8.20.0"
+cliVersion: "8.21.0"
 ---
 
 # morph-plan
@@ -84,10 +84,10 @@ Ao iniciar a fase plan — após o `proposal.md` ser aprovado e antes de qualque
 
 4. Produza `mandate.md` em `.morph/features/{feature}/2-plan/`:
    - Stack exata do projeto (leia de `.morph/config/config.json` → `project.stack` ou do CLAUDE.md).
-   - Standards obrigatórios: liste os IDs relevantes de `.morph/framework/standards/STANDARDS.json`.
+   - Standards obrigatórios: descubra-os com `morph-spec standards --find "<domínio/tecnologia>"` (top 3 `id · path · digest` — o digest decide) por domínio tocado; liste os IDs escolhidos.
    - Patterns proibidos — **copie por extenso no mandate.md** a lista canônica de `MORPH.md` § "Stack baked-in" (`Guid.NewGuid()`→`Guid.CreateVersion7()`, classes não-sealed sem justificativa, exceptions como fluxo de controle, camada de Service/Manager entre handler e dados, repository genérico `IRepository<T>`/`IUnitOfWork`, SQL cru sem justificativa) mais qualquer proibição específica da feature. Copie o texto completo — o mandate.md é lido por implementadores em contexto fresco, sem `MORPH.md` carregado, então um ponteiro sozinho não basta aqui.
    - Política de acesso a dados (registre no mandate): `ApplicationDbContext` injetado direto no slice — para CRUD e para queries específicas (joins, projeção, paginação). Para concorrência ou SQL específico, store dedicado hand-written com justificativa em `decisions.md`.
-   - **Features com agentes de IA (MAF):** se a feature envolve um agente (Microsoft Agent Framework), **use a tool Read** nos standards relevantes de `framework/standards/ai-agents/*.md` (ex.: `setup`, `agent-session`, `middleware-patterns`, `mcp-server`, `mcp-tools`, `multi-agent-patterns`, `production`) — filtre pelo que a feature exige via STANDARDS.json. Esses standards carregam as **convenções de projeto** (single-agent por padrão — Workflows só para fan-in/out real; provider, caching, observability, A2A) que uma fonte externa de docs (ex.: context7) não conhece. Padrão de divisão: **superfície da API** pode vir de docs ao vivo/context7 (mais frescas para um SDK em evolução), mas **as convenções vêm dos standards** — registre ambas no mandate. Não pule os `ai-agents/*.md` só porque o STANDARDS.json index lista que eles existem.
+   - **Features com agentes de IA (MAF):** se a feature envolve um agente (Microsoft Agent Framework), **use a tool Read** nos standards relevantes de `framework/standards/ai-agents/*.md` (ex.: `setup`, `agent-session`, `middleware-patterns`, `mcp-server`, `mcp-tools`, `multi-agent-patterns`, `production`) — filtre pelo que a feature exige via `morph-spec standards --find "<tema>" --category ai-agents`. Esses standards carregam as **convenções de projeto** (single-agent por padrão — Workflows só para fan-in/out real; provider, caching, observability, A2A) que uma fonte externa de docs (ex.: context7) não conhece. Padrão de divisão: **superfície da API** pode vir de docs ao vivo/context7 (mais frescas para um SDK em evolução), mas **as convenções vêm dos standards** — registre ambas no mandate. Não pule os `ai-agents/*.md` só porque o STANDARDS.json index lista que eles existem.
    - Checklist de done com critérios verificáveis por tarefa.
 
 5. Produza `tasks.json` em `.morph/features/{feature}/2-plan/` seguindo o schema em `.morph/framework/schemas/tasks.schema.json`.
@@ -199,7 +199,7 @@ Ao registrar a aprovação do Gate 2, atualize o frontmatter de cada use case de
 ## Referências
 
 - `.morph/framework/MORPH.md` — seções 2 (Fases), 3 (Contratos de Output), 5 (Gates), Trust Mode
-- `.morph/framework/standards/STANDARDS.json` — para identificar standards relevantes ao mandate
+- `morph-spec standards --find "<query>"` — para identificar standards relevantes ao mandate (o índice inteiro só como navegação exploratória; ver `morph-standards`)
 - `.morph/framework/agents.json` — personas por domínio; lido UMA VEZ no passo 5a para carimbar `agent`/`standards` por task
 - `.morph/framework/schemas/tasks.schema.json` — schema obrigatório de tasks.json
 - `.morph/specs/usecases/` — acervo permanente de use cases do projeto (leia antes de numerar; em `bug`, é onde mora o UC a corrigir)

package/framework/skills/core/morph-proposal/SKILL.md

@@ -4,7 +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: "8.20.0"
+cliVersion: "8.21.0"
 ---
 
 # morph-proposal