@polymorphism-tech/morph-spec 9.0.0 → 9.2.0

package/src/dashboard/app/pages/Standards.jsx

@@ -8,9 +8,6 @@ import SearchFilter from '../components/SearchFilter.jsx';
 import Markdown from '../components/Markdown.jsx';
 import EntityLink, { useSelection, standardKey } from '../components/EntityLink.jsx';
 
-// ─── Colors ───────────────────────────────────────────────────────────────────
-
-/** Token palette the categories draw from, in order; the categories come from the data. */
 const PALETTE = [
   'var(--color-phase-implement)',
   'var(--color-phase-uiux)',
@@ -24,20 +21,17 @@ const PALETTE = [
 
 const tint = (color, pct = 14) => `color-mix(in srgb, ${color} ${pct}%, var(--color-core))`;
 
-/** category → color, stable by category name so a color never jumps between renders. */
+/** Stable by category name, so a color never jumps between renders. */
 function categoryColors(standards) {
   const cats = [...new Set(standards.map((s) => s.category || 'outros'))].sort();
   return Object.fromEntries(cats.map((c, i) => [c, PALETTE[i % PALETTE.length]]));
 }
 
-// Resolve `?sel=` to a standard: by id first, then by the path a plan cites.
 export function findStandard(list, sel) {
   if (!sel) return null;
   return list.find((s) => s.id === sel) || list.find((s) => s.path === standardKey(sel)) || null;
 }
 
-// ─── Nodes ────────────────────────────────────────────────────────────────────
-
 const HANDLE = { width: 7, height: 7, border: 0 };
 const NODE_W = 230;
 const NODE_H = 52;
@@ -97,8 +91,6 @@ function CategoryNode({ data }) {
 
 const nodeTypes = { standardNode: StandardNode, agentNode: AgentNode, categoryNode: CategoryNode };
 
-// ─── Layout ───────────────────────────────────────────────────────────────────
-
 const CELL_W = NODE_W + 14;
 const CELL_H = NODE_H + 12;
 const PAD = 16;
@@ -106,7 +98,6 @@ const HEADER = 40;
 const BLOCK_GAP = 36;
 const MAX_ROW_W = 1700;
 
-/** How many columns a category block gets: tall categories spread sideways. */
 function colsFor(n) {
   if (n > 12) return 3;
   if (n > 5) return 2;
@@ -127,7 +118,6 @@ function buildGraph({ standards, agents, colors, isMatch, hasFilter, persona, se
     .map(([cat, list]) => [cat, [...list].sort((a, b) => (a.subcategory || '').localeCompare(b.subcategory || '') || a.name.localeCompare(b.name))])
     .sort((a, b) => b[1].length - a[1].length || a[0].localeCompare(b[0]));
 
-  // Pack the category blocks into rows no wider than MAX_ROW_W.
   const blocks = cats.map(([cat, list]) => {
     const cols = colsFor(list.length);
     const rows = Math.ceil(list.length / cols);
@@ -141,7 +131,7 @@ function buildGraph({ standards, agents, colors, isMatch, hasFilter, persona, se
   }
   const totalW = Math.max(...rows.map((r) => r.w), 0);
 
-  const std = new Set(); // node ids present
+  const std = new Set();
   let y = 180;
   for (const row of rows) {
     let x = (totalW - row.w) / 2;
@@ -170,7 +160,6 @@ function buildGraph({ standards, agents, colors, isMatch, hasFilter, persona, se
     y += row.h + BLOCK_GAP;
   }
 
-  // The personas on top, each with an edge to every standard it consults.
   const withStandards = agents.filter((a) => (a.standards || []).some((id) => std.has(id)));
   const agentX0 = (totalW - withStandards.length * (NODE_W + 24)) / 2;
   const byId = new Map(standards.map((s) => [s.id, s]));
@@ -194,8 +183,6 @@ function buildGraph({ standards, agents, colors, isMatch, hasFilter, persona, se
   return { nodes, edges, categories: cats.map(([c, l]) => [c, l.length]) };
 }
 
-// ─── Detail ───────────────────────────────────────────────────────────────────
-
 function Section({ title, children }) {
   return (
     <section className="space-y-2">
@@ -307,8 +294,6 @@ export function StandardDetail({ std, color = 'var(--color-dim)' }) {
   );
 }
 
-// ─── Page ─────────────────────────────────────────────────────────────────────
-
 export default function Standards() {
   const standards = morphData.standards?.list || [];
   const version = morphData.standards?.version;

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

@@ -1,12 +1,6 @@
 /**
- * The harness event stream (`.morph/logs/events.jsonl`, schema v2 of
- * framework/hooks/shared/telemetry-logger.js) told as a feed a person can read.
- *
- * Reading and summing are NOT done here: `loadTelemetryAllTrees` gathers every
- * tree's log plus the finish backups, and `aggregateCost` is the one place
- * tokens are added up (only `delta` can be summed; a v1 stream yields `null`,
- * which the UI shows as unknown — never 0). This module only decides what each
- * event means in words, and which ones are worth a line.
+ * `loadTelemetryAllTrees` reads and `aggregateCost` is the one place tokens are
+ * summed: a v1 stream yields `null`, shown as unknown, never 0.
  */
 
 import { statSync, openSync, readSync, closeSync } from 'fs';
@@ -14,7 +8,6 @@ import { join, resolve } from 'path';
 import { loadTelemetryAllTrees, aggregateCost, dedupeEvents } from '../../lib/telemetry/telemetry-reader.js';
 import { isFailedToolCall } from '../../../framework/hooks/shared/telemetry-logger.js';
 
-/** Kinds a person follows by default; the rest are one click away. */
 export const DEFAULT_KINDS = ['prompt', 'question', 'skill', 'dispatch', 'handback', 'verify', 'gate', 'failure'];
 export const ALL_KINDS = [...DEFAULT_KINDS, 'write', 'read', 'command', 'tool'];
 
@@ -44,16 +37,6 @@ function nodesSummary(nodes) {
   return Object.entries(nodes).map(([name, n]) => ({ name, status: typeof n === 'string' ? n : n?.status ?? null }));
 }
 
-/**
- * One event → one feed line, or null when the event is bookkeeping.
- *
- * @returns {null | {
- *   id: string, ts: string, feature: string|null, phase: string|null,
- *   kind: string, title: string, detail: string|null, status: 'ok'|'fail'|null,
- *   refs: { persona?: string, skill?: string, path?: string },
- *   nodes?: Array<{name: string, status: string|null}>
- * }}
- */
 export function describeEvent(e) {
   if (!e || typeof e !== 'object' || SILENT_EVENTS.has(e.event)) return null;
   const base = {
@@ -69,9 +52,8 @@ export function describeEvent(e) {
   const line = (kind, title, extra = {}) => ({ ...base, kind, title, ...extra, refs: { ...base.refs, ...(extra.refs || {}) } });
 
   if (e.event === 'UserPromptSubmit') {
-    // Hand-backs, task notifications and reminders arrive through the same door
-    // as a person's prompt, wrapped in a tag. A slash command is the one tagged
-    // prompt a person typed.
+    // Hand-backs, notifications and reminders arrive as a prompt wrapped in a tag;
+    // a slash command is the one tagged prompt a person typed.
     const text = typeof e.prompt === 'string' ? e.prompt.trim() : '';
     const command = /^<command-name>\/?([^<]+)<\/command-name>/.exec(text);
     if (command) return line('prompt', `Você rodou /${command[1].trim()}`);
@@ -119,8 +101,7 @@ export function describeEvent(e) {
   return line('tool', tool || e.event);
 }
 
-// The same event array is fed again on every request until the log changes:
-// describing ~100k events once, not per page, is the difference that matters.
+// Memoized per events array: describing ~100k events once, not per page.
 const described = new WeakMap();
 
 function describeAll(events) {
@@ -137,12 +118,6 @@ function describeAll(events) {
   return described.get(events);
 }
 
-/**
- * The feed, newest first, filtered and paginated by a `before` timestamp cursor.
- *
- * @param {Object[]} events - raw events, any order
- * @param {{ feature?: string, kinds?: string[], before?: string, limit?: number }} [opts]
- */
 export function buildFeed(events, { feature, kinds = DEFAULT_KINDS, before, limit = 100 } = {}) {
   const wanted = new Set(kinds);
   const lines = describeAll(events).filter((l) => wanted.has(l.kind) && (!feature || l.feature === feature));
@@ -152,15 +127,6 @@ export function buildFeed(events, { feature, kinds = DEFAULT_KINDS, before, limi
   return { items: page, next: page.length === limit && last ? last.ts : null, total: lines.length };
 }
 
-/**
- * What the feature list shows as "the last thing that happened" in each
- * feature: the newest line a person follows by default (a dispatch, a verify, a
- * task — not a Read or a shell command), plus `ts`, the newest event of ANY kind,
- * which is what says an agent is working right now.
- *
- * @param {Object[]} events
- * @returns {Record<string, {ts: string, title: string|null, kind: string|null, status: string|null, titleTs: string|null}>}
- */
 const lastByLines = new WeakMap();
 
 export function lastActivityByFeature(events) {
@@ -179,7 +145,6 @@ export function lastActivityByFeature(events) {
   return out;
 }
 
-/** Every event of the project across its trees and finish backups. */
 export function loadProjectEvents(projectDir) {
   return dedupeEvents(loadTelemetryAllTrees(projectDir).flatMap((t) => t.events));
 }
@@ -195,27 +160,14 @@ function fileSize(path) {
 }
 
 /**
- * The project's events kept in memory and followed as they are appended.
- *
- * A running agent appends one line to its tree's `events.jsonl` per tool call.
- * Re-reading every log (≈100k events, seconds) on each append would block the
- * dev server for the whole run, so the store remembers how far it read each
- * live log and parses only the bytes after that. Anything it cannot follow
- * that way — a log that shrank (SessionStart rotated it), a log it has never
- * seen (a new worktree), an archive or backup — falls back to a full reload
- * through `loadTelemetryAllTrees`, the same reader as always. Copies of one
- * event are still dropped by `eventId`.
- *
- * Every update yields a NEW events array, so everything memoized per array
- * (described lines, per-feature cost) follows the change.
- *
- * @param {string} projectDir
- * @param {{ loadTrees?: Function }} [deps] - test seam, defaults to loadTelemetryAllTrees
+ * Tails each live log from the last byte read; a shrunk (rotated) or unseen log,
+ * an archive or a backup falls back to a full reload. Every update yields a NEW
+ * events array, so everything memoized per array follows the change.
  */
 export function createEventStore(projectDir, { loadTrees = loadTelemetryAllTrees } = {}) {
   let events = null;
   let seen = new Set();
-  let offsets = new Map(); // live log path -> bytes consumed (up to the last newline)
+  let offsets = new Map();
   let pending = new Set();
   let fullReload = true;
   const costs = new Map();
@@ -238,7 +190,6 @@ export function createEventStore(projectDir, { loadTrees = loadTelemetryAllTrees
     costs.clear();
   }
 
-  /** Parse the bytes appended to `path` since the last read; false when it cannot follow. */
   function tail(path) {
     const from = offsets.get(path);
     const size = fileSize(path);
@@ -273,7 +224,6 @@ export function createEventStore(projectDir, { loadTrees = loadTelemetryAllTrees
       const prevLines = described.get(events);
       const merged = events.concat(fresh);
       events = fresh.every((e) => (e.ts || '') >= last) ? merged : dedupeEvents(merged);
-      // Carry the described lines over instead of describing 100k events again.
       if (prevLines) {
         const byTsDesc = (a, b) => (b.ts || '').localeCompare(a.ts || '');
         const added = fresh.map(describeEvent).filter(Boolean).sort(byTsDesc);
@@ -302,19 +252,13 @@ export function createEventStore(projectDir, { loadTrees = loadTelemetryAllTrees
 
   return {
     events: current,
-    /**
-     * Something under `.morph/logs` changed. A known live log is tailed on the
-     * next read; anything else (rotation archive, new tree, backup) reloads.
-     */
     changed(path) {
       const known = path && [...offsets.keys()].find((p) => resolve(p) === resolve(path));
       if (known) pending.add(known);
       else fullReload = true;
     },
     reset() { fullReload = true; },
-    /** Loaded and not waiting for a full reload: reading it now is cheap. */
     ready() { return events !== null && !fullReload; },
-    /** `featureCost`, memoized until the events change. */
     cost(feature) {
       const all = current();
       if (!costs.has(feature)) costs.set(feature, featureCost(all, feature));
@@ -323,10 +267,7 @@ export function createEventStore(projectDir, { loadTrees = loadTelemetryAllTrees
   };
 }
 
-/**
- * What the feature cost, straight from `aggregateCost`. `sessionUsage` and
- * `agentUsage` stay `null` when the stream has no summable sample.
- */
+/** `sessionUsage` and `agentUsage` stay `null` when the stream has no summable sample. */
 export function featureCost(events, feature) {
   const c = aggregateCost(events, { feature });
   return {

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

@@ -2,27 +2,13 @@ import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import { personaStandardIds, isImplementer, renderAgentMd, loadKnownMcpIds } from '../../utils/agents-installer.js';
 
-/** A line of a phase skill that dispatches a sub-agent. */
 const DISPATCH_LINE = /despach|dispatch|subagent_type/i;
 
-/** The generic dispatch token: "the implementer of the task's domain". */
 const GENERIC_DISPATCH = 'morph-{id}';
 
 /**
- * Which phases each persona works in, read from the phase skills themselves.
- *
- * v5 has no phase list on the persona: a phase dispatches a persona when its
- * skill (`phases.json → skill`) names `morph-{personaId}` on a dispatch line
- * (morph-uiux → ui-designer, morph-plan → scout, morph-review → verifier, reviewer, security).
- * A skill that dispatches the generic `morph-{id}` runs every implementer —
- * the same `isImplementer` the validator and the installer use.
- *
  * Only dispatch lines count: morph-plan cites `morph-dotnet-senior` as a
  * spelling example of the `agent` field, which dispatches nobody.
- *
- * @param {string} frameworkDir
- * @param {Record<string, object>} agents - agents.json `agents` map
- * @returns {Map<string, string[]>} personaId → phase ids, in phase order
  */
 export function personaPhases(frameworkDir, agents) {
   const result = new Map(Object.keys(agents).map((id) => [id, []]));
@@ -46,10 +32,6 @@ export function personaPhases(frameworkDir, agents) {
   return result;
 }
 
-/**
- * Scan agents.json (v5) — flat domain personas, no tiers.
- * Returns the list shaped for the dashboard inspector.
- */
 export function scanAgents(frameworkDir) {
   const agentsJsonPath = join(frameworkDir, 'agents.json');
   if (!existsSync(agentsJsonPath)) {
@@ -58,9 +40,7 @@ export function scanAgents(frameworkDir) {
   const agentsJson = JSON.parse(readFileSync(agentsJsonPath, 'utf8'));
   const phasesOf = personaPhases(frameworkDir, agentsJson.agents);
   const knownMcpIds = loadKnownMcpIds(frameworkDir);
-  // The exact `.claude/agents/morph-{id}.md` the installer writes: the system
-  // prompt the sub-agent actually runs with. A persona whose data the renderer
-  // refuses shows the refusal instead of hiding the persona.
+  // A persona whose data the renderer refuses shows the refusal instead of hiding the persona.
   const promptOf = (id, agent) => {
     try { return renderAgentMd({ id, ...agent }, knownMcpIds); } catch (err) { return `<!-- não renderizou: ${err.message} -->`; }
   };
@@ -71,8 +51,6 @@ export function scanAgents(frameworkDir) {
     color: agent.color || null,
     domains: agent.domains || [],
     keywords: agent.keywords || [],
-    // Every standard the persona can cite, surfaces included — the same
-    // reading the installer and the validator use.
     standards: personaStandardIds(agent),
     surfaces: agent.surfaces || null,
     stack: agent.stack || ['*'],

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

@@ -1,8 +1,3 @@
-/**
- * The reading material of the framework — the charter, the runtime
- * instructions, the CLI reference and the Gate 3 review checklist — for the
- * dashboard's Guide page.
- */
 import { readFileSync } from 'fs';
 import { join } from 'path';
 
@@ -10,7 +5,6 @@ function read(path) {
   try { return readFileSync(path, 'utf8'); } catch { return null; }
 }
 
-/** `## Heading` lines, the table of contents a long document is read by. */
 export function headingsOf(content) {
   const out = [];
   let inFence = false;

package/src/dashboard/scanner/feature-status.js

@@ -1,9 +1,6 @@
 /**
- * When a feature counts as finished — the one rule the portfolio (server) and
- * the feature list (client) share. Pure, no node imports: the client bundles it.
- *
- * A feature in `.morph/archive/` is closed whatever its status says: legacy
- * archives keep `draft` or `in_progress` from before `finish` set the status.
+ * Pure, no node imports: the client bundles it. An archived feature is closed
+ * whatever its legacy status says.
  */
 export function isFinished(f) {
   return f?.status === 'completed' || f?.status === 'abandoned' || f?.location === 'archive';

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

@@ -1,22 +1,6 @@
 /**
- * The dashboard's view of the target project's features — the ONLY scanner
- * that reads the project rather than the framework package.
- *
- * Every rule here is borrowed, never re-encoded:
- *   - which tree owns a feature  → `resolveFeatureTree` (feature-truth.js)
- *   - the current phase          → `derivePhaseFrom` (state-reader.js)
- *   - gate order                 → `GATE_PREREQ` (gate-order.js)
- *   - the review verdict         → `reviewReportsFromDir` (review-reports.js)
- *   - path confinement           → `canonicalPath`/`isInside` (test-runner.js)
- *   - slice progress             → `sliceProgress` (slice-progress.js)
- *
- * Three places a feature can live: the root `.morph/features/{f}`, a worktree
- * `{worktrees}/{wt}/.morph/features/{f}`, and `.morph/archive/{f}` once
- * `finish` ran. The root copy of a feature built in a worktree is its
- * birth-instant skeleton and never changes again, so for an active feature the
- * owner tree wins. Only active features pay for that question — it spawns git.
- *
- * Read-only and fail-open: a corrupt file degrades one feature, never the scan.
+ * The root copy of a feature built in a worktree is its birth skeleton, so for an
+ * active feature the owner tree wins. Only active features ask: it spawns git.
  */
 
 import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
@@ -48,10 +32,7 @@ function subdirs(dir) {
   } catch { return []; }
 }
 
-/**
- * Old feature.json files stamped a gate as a bare `true` (MORPH_OS). Lifting it
- * to `{approved: true}` is what lets the shared rules read them unchanged.
- */
+/** Old feature.json files stamped a gate as a bare `true`. */
 export function normalizeGates(gates) {
   const out = {};
   for (const [name, value] of Object.entries(gates || {})) {
@@ -65,10 +46,6 @@ function normalizeFeature(fj) {
   return { ...f, approvalGates: normalizeGates(f.approvalGates || f.approvals) };
 }
 
-/**
- * Every place a feature lives, before deciding which one tells the truth.
- * @returns {Map<string, {root?: string, worktrees: string[], archive?: string}>}
- */
 function collectLocations(projectDir) {
   const found = new Map();
   const slot = (name) => {
@@ -93,17 +70,10 @@ function collectLocations(projectDir) {
   return found;
 }
 
-/**
- * Decide which directory is this feature's truth.
- *
- * @returns {{ location: 'root'|'worktree'|'archive', dir: string, feature: object,
- *   ownerTree: string|null, rootStale: boolean }}
- */
 function resolveLocation(projectDir, name, loc, resolveTree) {
   const rootFj = loc.root ? readJson(join(loc.root, 'feature.json')) : null;
 
-  // Archived: `finish` moved the artifacts. An old root copy may linger (MORPH_OS
-  // keeps a feature.json per finished feature) — the archive holds the files.
+  // An old root copy may linger; the archive holds the files.
   const rootFinished = rootFj && (FINISHED.has(rootFj.status) || rootFj.archivedAt);
   if (loc.archive && (!rootFj || rootFinished)) {
     const archFj = readJson(join(loc.archive, 'feature.json'));
@@ -123,8 +93,7 @@ function resolveLocation(projectDir, name, loc, resolveTree) {
       const wtDir = join(tree, '.morph', 'features', name);
       const wtFj = readJson(join(wtDir, 'feature.json'));
       if (wtFj) return { location: 'worktree', dir: wtDir, feature: wtFj, ownerTree: tree, rootStale: false };
-      // The owner tree exists but carries no copy of the feature: all we have is
-      // the root skeleton, and the UI has to say so.
+      // The owner tree has no copy of the feature: only the root skeleton is left.
       return { location: 'root', dir: loc.root, feature: rootFj, ownerTree: tree, rootStale: true };
     }
   }
@@ -141,10 +110,6 @@ function resolveLocation(projectDir, name, loc, resolveTree) {
   };
 }
 
-/**
- * The plan's slices with the status their reports give, plus the fields the
- * extraction carries for the card. `null` when the plan has not been checked yet.
- */
 export function readSlices(dir) {
   const progress = sliceProgress(dir);
   if (!progress) return null;
@@ -189,10 +154,6 @@ function reviewVerdict(dir, workType, reports = reviewReportsFromDir(dir)) {
   return { verdict: combinedVerdict(reports, required), blockers: allBlockers(reports) };
 }
 
-/**
- * One row per review report the feature asks for or already has: status,
- * verdict, blockers and the SHA it reviewed.
- */
 export function reviewRows(reports, workType) {
   const required = requiredReviewRoles({ workType, securityRequired: reports.security.status !== 'missing' });
   return Object.keys(REVIEW_ROLES)
@@ -210,10 +171,7 @@ export function reviewRows(reports, workType) {
     });
 }
 
-/**
- * The plan's scenarios, each with the verifier's row for it. `coverage` is
- * `null` until a verifier report exists; only PROVADO covers.
- */
+/** `coverage` is `null` until a verifier report exists; only PROVADO covers. */
 export function readChecks(dir, verifier) {
   const checks = readJson(checksPath(dir))?.checks;
   if (!Array.isArray(checks)) return null;
@@ -258,8 +216,7 @@ function summarize(name, resolved) {
     gates,
     awaiting: !finished && gates.some((g) => g.paused),
     slices: slices?.counts ?? NO_SLICES,
-    // Titles of an active feature's slices, for the global search. Finished
-    // features leave them out: 170 archived plans would bloat every list reply.
+    // Finished features leave slice titles out: archived plans would bloat every list reply.
     sliceIndex: finished || !slices ? [] : slices.list.map((sl) => ({ id: sl.id, title: sl.title, status: sl.status })),
     verification: feature.verification
       ? { status: feature.verification.status ?? null, ts: feature.verification.ts ?? null }
@@ -272,10 +229,6 @@ function summarize(name, resolved) {
   };
 }
 
-/**
- * Files of a feature, grouped by the phase their top folder belongs to.
- * @returns {Array<{path: string, phase: string|null, size: number, mtime: string}>}
- */
 export function listDocuments(dir) {
   const out = [];
   const walk = (abs, rel, depth) => {
@@ -305,9 +258,8 @@ export function listDocuments(dir) {
 }
 
 /**
- * Resolve one feature. `known` is where a previous scan already found it: the
- * list scan paid for the git calls, and opening a feature or one of its files
- * must not pay again. It is only trusted while its feature.json still reads.
+ * `known` is where a previous scan found the feature, so opening it does not pay
+ * for git again. It is only trusted while its feature.json still reads.
  */
 function resolveOne(projectDir, name, resolveTree, known) {
   if (known?.dir) {
@@ -319,13 +271,6 @@ function resolveOne(projectDir, name, resolveTree, known) {
   return resolveLocation(projectDir, name, loc, resolveTree);
 }
 
-/**
- * The feature list of a project.
- *
- * @param {string} projectDir
- * @param {{ resolveTree?: Function }} [opts] - seam for tests; defaults to
- *   `resolveFeatureTree`
- */
 export function scanFeatures(projectDir, { resolveTree = resolveFeatureTree } = {}) {
   const config = readMorphConfig(projectDir);
   const features = [];
@@ -344,8 +289,7 @@ export function scanFeatures(projectDir, { resolveTree = resolveFeatureTree } =
       trust: config?.trust || null,
       dir: projectDir,
       initialized: existsSync(join(projectDir, '.morph')),
-      // A project that has state.json but no feature.json anywhere predates the
-      // per-feature state model — the dashboard says so instead of showing "empty".
+      // state.json with no feature.json anywhere predates the per-feature state model.
       legacyStateOnly: hasState && features.length === 0,
     },
     features,

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

@@ -26,13 +26,7 @@ function extractImports(source) {
   return imports;
 }
 
-/**
- * Claude Code event name → the kebab-case key the Hook Inspector groups by.
- * `pre-compact` and `teammate-idle` have no MORPH hooks — those nodes render
- * empty on purpose. `worktree-create`/`worktree-remove` are the worktree
- * lifecycle events (v3.8.0) — outside the tool-call flow, drawn as their own
- * pair in HookInspector.jsx.
- */
+/** `pre-compact` and `teammate-idle` have no MORPH hooks: those nodes render empty on purpose. */
 const EVENT_KEYS = {
   SessionStart: 'session-start',
   UserPromptSubmit: 'user-prompt',
@@ -47,20 +41,7 @@ const EVENT_KEYS = {
   WorktreeRemove: 'worktree-remove',
 };
 
-/**
- * Build filename → [{ event, matcher }] from the installer's MORPH_HOOKS.
- *
- * The event is NOT derivable from the path. Before the v4→v5 migration the
- * hooks sat in per-event folders, so `basename(dirname(file))` produced the
- * event key; the migration flattened everything into `core/`, and from then on
- * every hook reported `event: 'core'`. Nothing crashed — the Inspector groups
- * by event, found no key it knew, and rendered every node empty. Twelve hooks,
- * zero shown.
- *
- * `getHookDefinitions()` is the single source of truth (the same array the
- * installer writes into settings.local.json), so the registration and the
- * drawing can no longer disagree.
- */
+/** The event is not derivable from the path: every hook sits in `core/`. */
 export function hookRegistrations(definitions = getHookDefinitions()) {
   const byFile = new Map();
   for (const def of definitions) {
@@ -69,10 +50,8 @@ export function hookRegistrations(definitions = getHookDefinitions()) {
     for (const h of def.hooks || []) {
       const file = basename(String(h.command || '').trim());
       if (!file.endsWith('.js')) continue;
-      // 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.
+      // Grupos consolidados apontam para chain.js com os elos em `args`: registre
+      // cada elo, senão chain.js vira nó fantasma em todo evento.
       const files = file === 'chain.js' && Array.isArray(h.args) && h.args.length
         ? h.args.map(a => `${a}.js`)
         : [file];
@@ -80,8 +59,7 @@ export function hookRegistrations(definitions = getHookDefinitions()) {
         if (!byFile.has(f)) byFile.set(f, []);
         const entries = byFile.get(f);
         const matcher = def.matcher || null;
-        // Several raw events share one Inspector column (PostToolUse and its
-        // Failure/Batch siblings): one node per column, not one per event.
+        // PostToolUse and its Failure/Batch siblings share one Inspector column.
         if (entries.some((e) => e.event === key && e.matcher === matcher)) continue;
         entries.push({ event: key, rawEvent: def.event, matcher });
       }
@@ -111,7 +89,6 @@ export function scanHooks(frameworkDir) {
     // PostToolUse and UserPromptSubmit, and must show under both.
     const regs = registrations.get(filename);
     if (!regs || regs.length === 0) {
-      // On disk but never registered — real dead weight, and worth seeing.
       return [{ ...base, event: 'unregistered', matcher: null }];
     }
     return regs.map(r => ({ ...base, event: r.event, rawEvent: r.rawEvent, matcher: r.matcher }));

package/src/dashboard/scanner/index.js

@@ -6,10 +6,6 @@ import { scanStandards } from './standards-scanner.js';
 import { scanRules } from './rules-scanner.js';
 import { scanDocs } from './docs-scanner.js';
 
-/**
- * The framework's knowledge, for the static virtual module. The project's
- * state (features, activity) is served live by project-api.js instead.
- */
 export function scanAll(frameworkDir) {
   const agents = scanAgents(frameworkDir);
   const phases = scanPhases(frameworkDir);