@polymorphism-tech/morph-spec 8.15.1 → 8.17.0

package/src/commands/observability/cost.js

@@ -0,0 +1,137 @@
+/**
+ * `morph-spec cost [feature] [--by task|phase] [--json]`
+ *
+ * A cost-facing view over the same harness event stream `telemetry` reads
+ * (.morph/logs/events.jsonl): how much wall-clock time was spent inside
+ * measured tasks (TaskStart→TaskEnd), how many context bytes were
+ * re-ingested (grouped by kind: rubric/standard/skill/agents/plan-artifact/
+ * code), and how many sub-agent dispatches happened (with total prompt
+ * chars).
+ *
+ * IMPORTANT: bytes re-ingested is a DETERMINISTIC PROXY for cost, not a
+ * token count. Hooks only see what tools read off disk — never the model's
+ * actual token usage — so this measures re-ingestion pressure, not spend.
+ *
+ * Read-only, always exits 0 on a normal (even empty) run — fail-open, an
+ * empty stream is an answer, not an error. Only `--by` with an unknown value
+ * is a usage error (exit 1).
+ */
+
+import chalk from 'chalk';
+import { loadTelemetry, aggregateCost } from '../../lib/telemetry/telemetry-reader.js';
+
+const BYTES_CAVEAT =
+  'Bytes re-ingeridos são um PROXY determinístico de custo (o que as ferramentas leram do disco) — NÃO são tokens reais. Hooks não enxergam o uso real de tokens do modelo.';
+
+const BY_MODES = ['task', 'phase'];
+
+function fmtBytes(n) {
+  if (!n) return '0 B';
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / 1024 / 1024).toFixed(1)} MB`;
+}
+
+function fmtDuration(s) {
+  if (s === null || s === undefined) return '-';
+  if (s < 60) return `${s.toFixed(1)}s`;
+  const m = Math.floor(s / 60);
+  const rem = Math.round(s % 60);
+  return `${m}m${rem}s`;
+}
+
+function printBytesByKind(bytesByKind) {
+  const entries = Object.entries(bytesByKind);
+  if (!entries.length) {
+    console.log(chalk.gray('    (0 bytes re-ingeridos — nenhum Read com bytes/kind neste escopo)'));
+    return;
+  }
+  for (const [kind, bytes] of entries.sort((a, b) => b[1] - a[1])) {
+    console.log(`    ${chalk.yellow(kind.padEnd(14))} ${fmtBytes(bytes)}`);
+  }
+}
+
+function printTasks(tasks) {
+  if (!tasks.length) {
+    console.log(chalk.gray('\nNenhuma task com TaskStart/TaskEnd capturada.'));
+    return;
+  }
+  for (const t of tasks) {
+    const status = t.open ? chalk.yellow('[em aberto]') : (t.status || '-');
+    console.log('\n' + chalk.white.bold(`Task ${t.task}`) + chalk.gray(` · ${t.feature ?? '(sem feature)'}`) + ` · ${status}`);
+    console.log(`  duração: ${fmtDuration(t.durationSeconds)}`);
+    console.log(`  dispatches: ${t.dispatches.count} (${t.dispatches.promptChars} chars de prompt)`);
+    console.log('  bytes re-ingeridos por kind:');
+    printBytesByKind(t.bytesByKind);
+  }
+}
+
+function printPhases(phases) {
+  if (!phases.length) {
+    console.log(chalk.gray('\nNenhum byte de Read com phase capturado.'));
+    return;
+  }
+  for (const p of phases) {
+    console.log('\n' + chalk.white.bold(`Fase ${p.phase}`) + chalk.gray(` · ${fmtBytes(p.bytesTotal)} total`));
+    printBytesByKind(p.bytesByKind);
+  }
+}
+
+function printSummary(summary) {
+  console.log(`\n  duração dentro de tasks medidas: ${fmtDuration(summary.taskDurationSeconds)}`);
+  console.log(`  dispatches: ${summary.dispatches.count} (${summary.dispatches.promptChars} chars de prompt)`);
+
+  console.log('\n' + chalk.white.bold('Bytes re-ingeridos por kind') + ` (${fmtBytes(summary.bytesTotal)} total)`);
+  printBytesByKind(summary.bytesByKind);
+
+  if (summary.tools.length) {
+    console.log('\n' + chalk.white.bold('Mix de tools'));
+    for (const t of summary.tools) console.log(`  ${t.name.padEnd(16)} ${t.count}`);
+  }
+}
+
+/**
+ * @param {string} [feature] - narrow to a single feature
+ * @param {{ json?: boolean, by?: 'task'|'phase', cwd?: string }} [options]
+ */
+export function costCommand(feature, options = {}) {
+  if (options.by && !BY_MODES.includes(options.by)) {
+    console.error(chalk.red(`\n❌ Invalid --by: "${options.by}"`));
+    console.error(chalk.gray(`Valid modes: ${BY_MODES.join(', ')}\n`));
+    process.exitCode = 1;
+    return;
+  }
+
+  const events = loadTelemetry(options.cwd || process.cwd());
+  const summary = aggregateCost(events, { feature });
+
+  if (options.json) {
+    // No forced process.exit() here: on Windows a piped stdout write is
+    // async, and exit()ing right after a large console.log can race the
+    // flush and truncate output. Letting the event loop drain naturally
+    // (nothing else keeps it alive in this command) exits 0 without risk.
+    console.log(JSON.stringify(summary));
+    return;
+  }
+
+  if (summary.total === 0) {
+    const scope = feature ? ` para a feature "${feature}"` : '';
+    console.log(chalk.gray(`Telemetria vazia${scope} — nenhum evento capturado ainda em .morph/logs/events.jsonl.`));
+    return;
+  }
+
+  const scope = feature ? chalk.cyan(` · feature ${feature}`) : '';
+  console.log(chalk.white.bold(`Custo do harness (proxy determinística) — ${summary.total} eventos${scope}`));
+  console.log(chalk.gray(`⚠ ${BYTES_CAVEAT}`));
+  if (summary.features.length) {
+    console.log(chalk.gray(`Features: ${summary.features.join(', ')}`));
+  }
+
+  if (options.by === 'task') {
+    printTasks(summary.tasks);
+  } else if (options.by === 'phase') {
+    printPhases(summary.phases);
+  } else {
+    printSummary(summary);
+  }
+}

package/src/commands/project/standards.js

@@ -0,0 +1,220 @@
+/**
+ * `morph-spec standards --find "<query>" [--category <c>] [--tags <a,b>] [--json]`
+ *
+ * Server-side replacement for "read the whole STANDARDS.json to pick 1-3
+ * standards" (R2 of the performance plan — token cut per task). Today
+ * morph-implement loads the full 65 KB / 60-entry registry (with a `digest`
+ * per entry) just to choose a couple of relevant standards: ~16k tokens per
+ * task. This command searches server-side and returns only the TOP 3 hits —
+ * `id · path · digest` — where the digest is the FULL text: it is what
+ * substitutes for actually reading the standard's .md file.
+ *
+ * Without `--find` (a bare call): lists categories + counts — a cheap
+ * orientation view, no scoring.
+ *
+ * A query with no hit exits 0 (this is advisory tooling, not a gate) with a
+ * human-readable warning + category suggestions on stderr, and — under
+ * `--json` — a stable `{ query, results: [], suggestion }` shape on stdout so
+ * a JSON consumer never has to special-case "no results" as a parse error.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+
+/**
+ * Resolve STANDARDS.json the same way doctor.js resolves the standards root:
+ * an installed project first (`.morph/framework/standards/`), falling back
+ * to this package's own bundled copy (`framework/standards/`) — the framework
+ * repo in dev, or the npm package's own copy before `setup-infra` has run.
+ *
+ * @param {string} targetPath - project root to look for `.morph/` under
+ * @returns {string|null} absolute path to STANDARDS.json, or null if neither exists
+ */
+export function resolveStandardsJsonPath(targetPath) {
+  const installed = join(targetPath, '.morph', 'framework', 'standards', 'STANDARDS.json');
+  if (existsSync(installed)) return installed;
+
+  const packageFallback = join(import.meta.dirname, '..', '..', '..', 'framework', 'standards', 'STANDARDS.json');
+  if (existsSync(packageFallback)) return packageFallback;
+
+  return null;
+}
+
+/** Load + parse STANDARDS.json. Throws on missing/invalid file — caller decides how to report it. */
+function loadRegistry(standardsJsonPath) {
+  const raw = readFileSync(standardsJsonPath, 'utf8');
+  return JSON.parse(raw);
+}
+
+/**
+ * category → count, sorted by count desc then name asc.
+ * @param {object[]} standards
+ * @returns {{ category: string, count: number }[]}
+ */
+export function categoryCounts(standards) {
+  const counts = {};
+  for (const std of standards) {
+    const cat = std.category || 'uncategorized';
+    counts[cat] = (counts[cat] || 0) + 1;
+  }
+  return Object.entries(counts)
+    .map(([category, count]) => ({ category, count }))
+    .sort((a, b) => b.count - a.count || a.category.localeCompare(b.category));
+}
+
+/**
+ * Simple weighted relevance score for one standard against a query.
+ * Tiers, as specified: name/id > tags(+aliases) > digest. category/subcategory
+ * ride alongside the tags tier (lighter). A token-level fallback keeps
+ * multi-word queries findable even without a verbatim phrase match anywhere.
+ *
+ * @param {object} std - one STANDARDS.json entry
+ * @param {string} query - raw user query (already trimmed, non-empty)
+ * @returns {number} score, 0 = no match
+ */
+export function scoreStandard(std, query) {
+  const q = query.toLowerCase();
+  const tokens = q.split(/\s+/).filter((t) => t.length >= 3);
+
+  const name = String(std.name || '').toLowerCase();
+  const id = String(std.id || '').toLowerCase();
+  const category = String(std.category || '').toLowerCase();
+  const subcategory = String(std.subcategory || '').toLowerCase();
+  const tags = (std.tags || []).map((t) => String(t).toLowerCase());
+  const aliases = (std.aliases || []).map((a) => String(a).toLowerCase());
+  const digest = String(std.digest || '').toLowerCase();
+
+  let score = 0;
+
+  // Tier 1: name / id — the strongest signal.
+  if (id === q || name === q) score += 20;
+  else if (id.includes(q) || name.includes(q)) score += 12;
+
+  // Tier 2: tags / aliases (curated search terms) + category/subcategory.
+  if (tags.includes(q) || aliases.includes(q)) score += 8;
+  else if (tags.some((t) => t.includes(q)) || aliases.some((a) => a.includes(q))) score += 5;
+  if (category === q || subcategory === q) score += 4;
+
+  // Tier 3: digest — weakest signal, full-phrase substring only.
+  if (digest.includes(q)) score += 2;
+
+  // Token-level fallback for multi-word queries with no verbatim match above.
+  for (const tok of tokens) {
+    if (name.includes(tok) || id.includes(tok)) score += 2;
+    if (tags.some((t) => t.includes(tok)) || aliases.some((a) => a.includes(tok))) score += 1;
+    if (digest.includes(tok)) score += 0.5;
+  }
+
+  return score;
+}
+
+/**
+ * Rank standards against a query, applying optional category/tags filters
+ * first. Returns the TOP 3 with score > 0, sorted desc (ties broken by id).
+ *
+ * @param {object[]} standards
+ * @param {string} query
+ * @param {{ category?: string, tags?: string[] }} [filters]
+ * @returns {Array<object & { score: number }>}
+ */
+export function findStandards(standards, query, filters = {}) {
+  const category = filters.category?.toLowerCase();
+  const tags = (filters.tags || []).map((t) => t.toLowerCase());
+
+  let candidates = standards;
+  if (category) {
+    candidates = candidates.filter((s) => String(s.category || '').toLowerCase() === category);
+  }
+  if (tags.length) {
+    candidates = candidates.filter((s) =>
+      (s.tags || []).some((t) => tags.includes(String(t).toLowerCase())));
+  }
+
+  return candidates
+    .map((s) => ({ ...s, score: scoreStandard(s, query) }))
+    .filter((s) => s.score > 0)
+    .sort((a, b) => b.score - a.score || String(a.id).localeCompare(String(b.id)))
+    .slice(0, 3);
+}
+
+/** Parse `--tags a,b,c` into a trimmed, non-empty array. */
+function parseTagsOption(raw) {
+  if (!raw) return [];
+  return String(raw).split(',').map((t) => t.trim()).filter(Boolean);
+}
+
+/**
+ * @param {{ find?: string, category?: string, tags?: string, json?: boolean, cwd?: string }} [options]
+ */
+export function standardsCommand(options = {}) {
+  const cwd = options.cwd || process.cwd();
+  const standardsJsonPath = resolveStandardsJsonPath(cwd);
+
+  if (!standardsJsonPath) {
+    console.error(chalk.red('\n❌ STANDARDS.json não encontrado — nem em .morph/framework/standards/ nem no pacote.'));
+    console.error(chalk.gray('   Rode `morph-spec setup-infra` (projeto instalado) ou verifique framework/standards/ (repo do framework).\n'));
+    process.exit(1);
+  }
+
+  let registry;
+  try {
+    registry = loadRegistry(standardsJsonPath);
+  } catch (err) {
+    console.error(chalk.red(`\n❌ STANDARDS.json inválido em ${standardsJsonPath}: ${err.message}\n`));
+    process.exit(1);
+  }
+
+  const standards = Array.isArray(registry.standards) ? registry.standards : [];
+  const query = (options.find || '').trim();
+
+  // ── Bare call (no --find): categories + counts, cheap orientation ────────
+  if (!query) {
+    const counts = categoryCounts(standards);
+    if (options.json) {
+      console.log(JSON.stringify({ total: standards.length, categories: counts }));
+      process.exit(0);
+    }
+    console.log(chalk.bold(`\nSTANDARDS.json — ${standards.length} standards, ${counts.length} categorias\n`));
+    const col = (s, w) => String(s).padEnd(w);
+    for (const { category, count } of counts) {
+      console.log(`  ${col(category, 20)}${count}`);
+    }
+    console.log(chalk.gray('\nUse --find "<query>" para buscar (top 3, com digest completo).\n'));
+    process.exit(0);
+  }
+
+  // ── --find: score + filter ────────────────────────────────────────────
+  const filters = { category: options.category, tags: parseTagsOption(options.tags) };
+  const results = findStandards(standards, query, filters);
+
+  if (!results.length) {
+    const counts = categoryCounts(standards);
+    if (options.json) {
+      console.log(JSON.stringify({ query, results: [], suggestion: { categories: counts } }));
+      process.exit(0);
+    }
+    console.error(chalk.yellow(`\n⚠️  Nenhum standard encontrado para "${query}".`));
+    console.error(chalk.gray('   Categorias disponíveis: ' +
+      counts.map((c) => `${c.category} (${c.count})`).join(', ') + '\n'));
+    process.exit(0);
+  }
+
+  const shaped = results.map((r) => ({
+    id: r.id, name: r.name, path: r.path, category: r.category, digest: r.digest, score: r.score,
+  }));
+
+  if (options.json) {
+    console.log(JSON.stringify({ query, results: shaped }));
+    process.exit(0);
+  }
+
+  console.log(chalk.bold(`\nTOP ${shaped.length} para "${query}"\n`));
+  shaped.forEach((r, i) => {
+    console.log(chalk.cyan(`${i + 1}. ${r.id}`) + chalk.gray(`  (${r.category})`));
+    console.log(`   ${r.path}`);
+    console.log(chalk.gray(`   ${r.digest}`));
+    console.log('');
+  });
+  process.exit(0);
+}

package/src/commands/state/approve.js

@@ -283,17 +283,38 @@ export async function approveCommand(featureName, gateName, options = {}) {
 
     let selfAssessed = false;
     if (gateName === 'review') {
-      const evaluatorReport = join(process.cwd(), '.morph', 'features', featureName, '4-review', 'evaluator-report.md');
-      if (!existsSync(evaluatorReport)) {
-        if (!options.selfAssessed) {
-          console.error(chalk.red('\n❌ Gate 3 exige o avaliador independente — `4-review/evaluator-report.md` não existe.'));
-          console.error(chalk.gray('   O score composto da feature vem do avaliador (persona `evaluator`, contexto fresco)'));
-          console.error(chalk.gray('   despachado pela morph-review, nunca de auto-avaliação de quem implementou.'));
-          console.error(chalk.gray('   Se o dispatch for impossível nesta sessão, aprove com --self-assessed —'));
-          console.error(chalk.gray('   a degradação fica registrada no feature.json e aparece no `list`/`fleet`.\n'));
+      if (feature.workType === 'hotfix') {
+        // Hotfix Gate 3 does NOT require the independent evaluator: `morph-hotfix`
+        // (SKILL.md §7) never dispatches `morph-evaluator` — speed over ceremony
+        // is the point of a hotfix — and instead writes `4-review/review-report.md`
+        // (diff + real test evidence) before asking the human to approve. Requiring
+        // evaluator-report.md here made the skill's own documented flow unable to
+        // clear its own Gate 3 (the only escape was --self-assessed, which stamps
+        // a degradation for a report that was never supposed to exist). The human
+        // signature is already enforced above (line ~215) — this only checks the
+        // artifact the skill actually produces.
+        const reviewReport = join(process.cwd(), '.morph', 'features', featureName, '4-review', 'review-report.md');
+        if (!existsSync(reviewReport)) {
+          console.error(chalk.red('\n❌ Gate 3 de hotfix exige `4-review/review-report.md` — não existe.'));
+          console.error(chalk.gray('   É o artefato que a `morph-hotfix` produz (diff do fix + evidência real de'));
+          console.error(chalk.gray('   teste do `morph-spec verify`), não o `evaluator-report.md` do avaliador'));
+          console.error(chalk.gray('   independente — hotfix nunca despacha o avaliador. Escreva o relatório antes'));
+          console.error(chalk.gray('   de aprovar; a assinatura humana já é exigida pelo backstop acima.\n'));
           process.exit(1);
         }
-        selfAssessed = true;
+      } else {
+        const evaluatorReport = join(process.cwd(), '.morph', 'features', featureName, '4-review', 'evaluator-report.md');
+        if (!existsSync(evaluatorReport)) {
+          if (!options.selfAssessed) {
+            console.error(chalk.red('\n❌ Gate 3 exige o avaliador independente — `4-review/evaluator-report.md` não existe.'));
+            console.error(chalk.gray('   O score composto da feature vem do avaliador (persona `evaluator`, contexto fresco)'));
+            console.error(chalk.gray('   despachado pela morph-review, nunca de auto-avaliação de quem implementou.'));
+            console.error(chalk.gray('   Se o dispatch for impossível nesta sessão, aprove com --self-assessed —'));
+            console.error(chalk.gray('   a degradação fica registrada no feature.json e aparece no `list`/`fleet`.\n'));
+            process.exit(1);
+          }
+          selfAssessed = true;
+        }
       }
     }
 

package/src/dashboard/scanner/hooks-scanner.js

@@ -63,8 +63,17 @@ export function hookRegistrations(definitions = getHookDefinitions()) {
     for (const h of def.hooks || []) {
       const file = basename(String(h.command || '').trim());
       if (!file.endsWith('.js')) continue;
-      if (!byFile.has(file)) byFile.set(file, []);
-      byFile.get(file).push({ event: key, rawEvent: def.event, matcher: def.matcher || null });
+      // Grupos consolidados apontam para chain.js com os hooks reais em
+      // `args` (base names, na ordem de execução) — registre cada elo, não o
+      // runner: é o elo que o Inspector precisa mostrar. chain.js em si não é
+      // um hook de domínio e ficaria como nó fantasma em todo evento.
+      const files = file === 'chain.js' && Array.isArray(h.args) && h.args.length
+        ? h.args.map(a => `${a}.js`)
+        : [file];
+      for (const f of files) {
+        if (!byFile.has(f)) byFile.set(f, []);
+        byFile.get(f).push({ event: key, rawEvent: def.event, matcher: def.matcher || null });
+      }
     }
   }
   return byFile;

package/src/lib/installers/memory-installer.js

@@ -87,7 +87,7 @@ metadata:
 - \`.morph/framework/schemas/tasks.schema.json\` — tasks.json schema reference
 - \`.morph/framework/phases.json\` — phase folder mapping and skill associations
 - \`.morph/framework/agents.json\` — domain persona definitions (dotnet-senior, ef-modeler, etc.)
-- \`.morph/framework/rubrics/\` — eval rubrics for morph-eval scoring
+- \`.morph/framework/evals/rubrics/\` — eval rubrics for morph-eval scoring (architecture/contracts/code-quality/test-coverage)
 `;
 
 /**

package/src/lib/tasks/tasks-json-parser.js

@@ -87,6 +87,32 @@ export function validateTasksJson(data) {
     if (task.usecase !== undefined && (typeof task.usecase !== 'string' || !USECASE_RE.test(task.usecase))) {
       errors.push(`${ctx}.usecase must match /^UC-\\d+$/ (the ID alone, e.g. "UC-07")`);
     }
+
+    // Optional: morph-plan may stamp a persona + standards per task (R2 token
+    // cut — `morph-spec standards --find` replaces reading the whole
+    // STANDARDS.json). Both are part of the plan contract and frozen after
+    // Gate 2 by protect-spec-files (any key outside MUTABLE_SPEC_FIELDS is
+    // blocked by construction — see that hook's top comment). Type-check
+    // only here: no cross-check against agents.json, since stack-filtered
+    // installs carry fewer personas than the full set and would false-fail.
+    if (task.agent !== undefined) {
+      if (typeof task.agent !== 'string' || !task.agent.trim()) {
+        errors.push(`${ctx}.agent must be a non-empty string (persona id, e.g. "dotnet-senior")`);
+      } else if (task.agent.startsWith('morph-')) {
+        errors.push(`${ctx}.agent must be the bare persona id — no "morph-" prefix (got "${task.agent}")`);
+      }
+    }
+    if (task.standards !== undefined) {
+      if (!Array.isArray(task.standards)) {
+        errors.push(`${ctx}.standards must be an array of paths`);
+      } else {
+        task.standards.forEach((s, i) => {
+          if (typeof s !== 'string' || !s.trim()) {
+            errors.push(`${ctx}.standards[${i}] must be a non-empty string path`);
+          }
+        });
+      }
+    }
   }
 
   return { valid: errors.length === 0, errors };