@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

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

@@ -1,30 +1,16 @@
 /**
- * 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 evaluator's verdict    → `evaluatorVerdictFromText` (evaluator-report.js)
- *   - path confinement           → `canonicalPath`/`isInside` (test-runner.js)
- *   - tasks.json validity        → `validateTasksJson` (tasks-json-parser.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';
 import { join, basename, isAbsolute } from 'path';
-import { derivePhaseFrom, PHASE_ARTIFACTS } from '../../../framework/hooks/shared/state-reader.js';
+import { derivePhaseFrom, diskArtifactProbe, PHASE_ARTIFACTS } from '../../../framework/hooks/shared/state-reader.js';
 import { GATE_PREREQ } from '../../core/state/gate-order.js';
-import { validateTasksJson } from '../../lib/tasks/tasks-json-parser.js';
-import { evaluatorVerdictFromText } from '../../lib/evaluator-report.js';
+import { sliceProgress, checksPath } from '../../../framework/hooks/shared/slice-progress.js';
+import {
+  reviewReportsFromDir, requiredReviewRoles, combinedVerdict, allBlockers, checksCoverage, reviewFileName, REVIEW_ROLES,
+} from '../../lib/review-reports.js';
 import { resolveFeatureTree } from '../../lib/worktree/feature-truth.js';
 import { containerDirs } from '../../../framework/hooks/shared/worktree-root.js';
 import { canonicalPath, isInside, readMorphConfig } from '../../lib/tasks/test-runner.js';
@@ -33,7 +19,6 @@ import { isFinished } from './feature-status.js';
 export const GATES = Object.keys(GATE_PREREQ);
 const FINISHED = new Set(['completed', 'abandoned']);
 const FOLDER_PHASE = Object.fromEntries(PHASE_ARTIFACTS.map(([folder, phase]) => [folder, phase]));
-const EVALUATOR_REPORT = '4-review/evaluator-report.md';
 const MAX_FILE_BYTES = 2 * 1024 * 1024;
 const MAX_DEPTH = 4;
 
@@ -47,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 || {})) {
@@ -64,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) => {
@@ -92,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'));
@@ -122,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 };
     }
   }
@@ -140,32 +110,23 @@ function resolveLocation(projectDir, name, loc, resolveTree) {
   };
 }
 
-/**
- * tasks.json as the dashboard needs it: the list even when the file breaks the
- * schema (a read-only viewer shows what is there), with the errors alongside.
- */
-export function readTasks(dir) {
-  const path = join(dir, '2-plan', 'tasks.json');
-  if (!existsSync(path)) return { list: [], errors: [], present: false };
-  const data = readJson(path);
-  if (!data) return { list: [], errors: ['tasks.json não é JSON válido'], present: true };
-  const { valid, errors } = validateTasksJson(data);
-  const list = Array.isArray(data.tasks) ? data.tasks.filter((t) => t && typeof t === 'object') : [];
-  return { list, errors: valid ? [] : errors, present: true };
+export function readSlices(dir) {
+  const progress = sliceProgress(dir);
+  if (!progress) return null;
+  const extracted = new Map((readJson(checksPath(dir))?.slices || []).filter((x) => x && x.id).map((x) => [x.id, x]));
+  const list = progress.slices.map((sl) => {
+    const x = extracted.get(sl.id) || {};
+    return {
+      ...sl,
+      persona: x.persona ?? null,
+      files: Array.isArray(x.files) ? x.files : [],
+      covers: Array.isArray(x.covers) ? x.covers : [],
+    };
+  });
+  return { counts: { total: progress.total, done: progress.done, partial: progress.partial, pending: progress.pending }, list };
 }
 
-function taskCounts(list) {
-  const counts = { total: list.length, done: 0, inProgress: 0, blocked: 0, pending: 0, skipped: 0 };
-  for (const t of list) {
-    // `completed` is the pre-schema spelling of `done` (MORPH_OS archives carry both).
-    if (t.status === 'done' || t.status === 'completed') counts.done += 1;
-    else if (t.status === 'in_progress') counts.inProgress += 1;
-    else if (t.status === 'blocked') counts.blocked += 1;
-    else if (t.status === 'skipped') counts.skipped += 1;
-    else counts.pending += 1;
-  }
-  return counts;
-}
+const NO_SLICES = { total: 0, done: 0, partial: 0, pending: 0 };
 
 function gatesOf(feature) {
   const skipped = new Set(feature.skippedPhases || []);
@@ -185,20 +146,60 @@ function gatesOf(feature) {
   });
 }
 
-function evaluatorVerdict(dir) {
-  const path = join(dir, ...EVALUATOR_REPORT.split('/'));
-  if (!existsSync(path)) return null;
-  try { return evaluatorVerdictFromText(readFileSync(path, 'utf8')); } catch { return null; }
+// Security counts only when its report exists: deciding it is required takes git.
+function reviewVerdict(dir, workType, reports = reviewReportsFromDir(dir)) {
+  const present = Object.values(reports).some((r) => r.status !== 'missing');
+  if (!present) return null;
+  const required = requiredReviewRoles({ workType, securityRequired: reports.security.status !== 'missing' });
+  return { verdict: combinedVerdict(reports, required), blockers: allBlockers(reports) };
+}
+
+export function reviewRows(reports, workType) {
+  const required = requiredReviewRoles({ workType, securityRequired: reports.security.status !== 'missing' });
+  return Object.keys(REVIEW_ROLES)
+    .filter((role) => required.includes(role) || reports[role].status !== 'missing')
+    .map((role) => {
+      const r = reports[role];
+      return {
+        role,
+        path: `4-review/${reviewFileName(role)}`,
+        status: r.status,
+        verdict: r.verdict ?? null,
+        blockers: r.blockers?.length ?? 0,
+        reviewedSha: r.reviewedSha ?? null,
+      };
+    });
+}
+
+/** `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;
+  const list = checks.filter((c) => c && c.id);
+  const rows = verifier?.checks ?? null;
+  const byId = new Map((rows ?? []).map((r) => [r.id, r]));
+  const coverage = verifier && verifier.status !== 'missing'
+    ? { total: list.length, ...checksCoverage(list.map((c) => c.id), rows) }
+    : null;
+  return {
+    coverage,
+    list: list.map((c) => ({
+      id: c.id,
+      text: c.text ?? '',
+      proof: c.proof ?? null,
+      status: byId.get(c.id)?.status ?? null,
+      evidence: byId.get(c.id)?.evidence ?? null,
+    })),
+  };
 }
 
 function summarize(name, resolved) {
   const { location, dir, ownerTree, rootStale } = resolved;
   const feature = normalizeFeature(resolved.feature);
-  const has = (rel) => existsSync(join(dir, ...rel.split('/')));
   const gates = gatesOf(feature);
   const reviewApproved = gates.find((g) => g.gate === 'review')?.approved === true;
-  const tasks = readTasks(dir);
-  const verdict = evaluatorVerdict(dir);
+  const slices = readSlices(dir);
+  const verdict = reviewVerdict(dir, feature.workType);
   const status = feature.status || (location === 'archive' ? 'completed' : 'draft');
   const finished = isFinished({ status, location });
   return {
@@ -210,29 +211,24 @@ function summarize(name, resolved) {
     dir,
     ownerTree,
     rootStale,
-    phase: derivePhaseFrom(feature, has),
-    inEvaluation: has(EVALUATOR_REPORT) && !reviewApproved,
+    phase: derivePhaseFrom(feature, diskArtifactProbe(dir)),
+    inEvaluation: verdict !== null && !reviewApproved,
     gates,
     awaiting: !finished && gates.some((g) => g.paused),
-    tasks: taskCounts(tasks.list),
-    // Titles of an active feature's tasks, for the global search. Finished
-    // features leave them out: 170 archived plans would bloat every list reply.
-    taskIndex: finished ? [] : tasks.list.map((t) => ({ id: t.id, title: t.title || '', status: t.status || 'pending' })),
+    slices: slices?.counts ?? NO_SLICES,
+    // 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, scope: feature.verification.scope ?? null, ts: feature.verification.ts ?? null }
+      ? { status: feature.verification.status ?? null, ts: feature.verification.ts ?? null }
       : null,
     verdict: verdict?.verdict ?? null,
-    blockers: verdict?.verdict ? verdict.blockers.length : null,
+    blockers: verdict ? verdict.blockers.length : null,
     createdAt: feature.createdAt || null,
     updatedAt: feature.updatedAt || feature.archivedAt || feature.createdAt || null,
     archivedAt: feature.archivedAt || null,
   };
 }
 
-/**
- * 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) => {
@@ -262,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) {
@@ -276,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 = [];
@@ -301,32 +289,28 @@ 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,
   };
 }
 
-/**
- * One feature in full: summary + tasks with their verify, the gate
- * decisions, the verify nodes and the document tree.
- */
 export function readFeatureDetail(projectDir, name, { resolveTree = resolveFeatureTree, known } = {}) {
   const resolved = resolveOne(projectDir, name, resolveTree, known);
   if (!resolved) return null;
   const summary = summarize(name, resolved);
   const feature = normalizeFeature(resolved.feature);
-  const tasks = readTasks(resolved.dir);
-  const verdict = evaluatorVerdict(resolved.dir);
+  const slices = readSlices(resolved.dir);
+  const reports = reviewReportsFromDir(resolved.dir);
+  const verdict = reviewVerdict(resolved.dir, feature.workType, reports);
+  const checks = readChecks(resolved.dir, reports.verifier);
   return {
     ...summary,
-    tasksList: tasks.list.map((t) => ({
-      ...t,
-      verification: feature.taskVerifications?.[t.id] || null,
-    })),
-    tasksErrors: tasks.errors,
+    slicesList: slices?.list ?? [],
+    checksList: checks?.list ?? [],
+    checksCoverage: checks?.coverage ?? null,
+    reviews: reviewRows(reports, feature.workType),
     gateDecisions: feature.gateDecisions || {},
     verificationNodes: feature.verification?.nodes || null,
     featureVerification: feature.verifications?.feature || null,
@@ -336,13 +320,8 @@ export function readFeatureDetail(projectDir, name, { resolveTree = resolveFeatu
   };
 }
 
-/**
- * The content of one file of a feature, confined to the feature's directory.
- * Junctions and win32 case are resolved by `canonicalPath` before the check,
- * so `..`, an absolute path or a link that leaves the folder are all refused.
- *
- * @returns {{ path: string, content: string, mtime: string } | { error: string, status: number }}
- */
+// Junctions and win32 case are resolved by `canonicalPath` before the check,
+// so `..`, an absolute path or a link that leaves the feature folder are refused.
 export function readFeatureFile(projectDir, name, relPath, { resolveTree = resolveFeatureTree, known } = {}) {
   if (typeof relPath !== 'string' || relPath === '') return { error: 'path ausente', status: 400 };
   if (isAbsolute(relPath) || /^[a-zA-Z]:/.test(relPath)) return { error: 'path fora da feature', status: 403 };

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);

package/src/dashboard/scanner/portfolio.js

@@ -1,17 +1,6 @@
 /**
- * Many projects in one dashboard. Each project keeps its own live API
- * (project-api.js: features, activity, files), created on first use; this
- * module lists the projects, routes `/p/:id/…` to the right one, and answers
- * which project a changed file belongs to.
- *
- * The list is the registry (src/lib/projects/registry.js) plus the project the
- * dashboard was launched from, which is always shown even if it cannot be
- * registered. Projects found next to the registered ones are offered, never
- * added on their own.
- *
- * A cold project can take seconds to read (a 100k-event log). The portfolio
- * never waits for one: `summary` is served only for projects already in
- * memory, and the rest are read in the background (`warmNext`).
+ * The portfolio never waits for a cold project (a 100k-event log takes seconds):
+ * `summary` is served only from memory, the rest is read by `warmNext`.
  */
 
 import { dirname, basename } from 'path';
@@ -25,18 +14,12 @@ function slug(text) {
 
 const lower = (p) => (process.platform === 'win32' ? p.toLowerCase() : p);
 
-/**
- * @param {{ launchDir: string, registry?: object, createApi?: Function }} opts
- *   `registry` and `createApi` are test seams.
- */
 export function createPortfolio({ launchDir, registry = registryModule, createApi = createProjectApi }) {
   const launchKey = registry.projectKey(launchDir);
-  const apis = new Map(); // dir key -> project api
-  // The last summary served per project: while a changed project is read
-  // again, the portfolio keeps showing it instead of going back to "reading".
-  const lastSummary = new Map(); // dir key -> summary
+  const apis = new Map();
+  // While a changed project is read again, its last summary keeps showing.
+  const lastSummary = new Map();
 
-  /** The projects shown, with stable ids derived from the folder name. */
   function list() {
     const dirs = registry.readRegistry().projects.map((p) => ({ dir: p.dir, name: p.name, source: p.source }));
     if (!dirs.some((p) => lower(p.dir) === lower(launchKey))) {
@@ -61,7 +44,6 @@ export function createPortfolio({ launchDir, registry = registryModule, createAp
     return list().find((p) => p.id === id) || null;
   }
 
-  /** The project a changed path belongs to — the deepest registered folder containing it. */
   function ownerOf(path) {
     const p = lower(String(path).replace(/\\/g, '/'));
     let best = null;
@@ -78,7 +60,6 @@ export function createPortfolio({ launchDir, registry = registryModule, createAp
     return registry.discoverProjects(roots).filter((s) => !projects.some((p) => lower(p.dir) === lower(s.dir)));
   }
 
-  /** Read the next project that is not in memory yet. @returns {object|null} the project warmed */
   function warmNext() {
     const next = list().find((p) => !apiFor(p.dir).ready());
     if (!next) return null;
@@ -106,11 +87,6 @@ export function createPortfolio({ launchDir, registry = registryModule, createAp
 
   const json = (status, body) => ({ status, body });
 
-  /**
-   * @param {string} method
-   * @param {string} url - relative to `/api/morph`
-   * @param {object|null} [body] - parsed JSON of a POST
-   */
   function handle(method, url, body = null) {
     const u = new URL(url, 'http://local');
     const parts = u.pathname.split('/').filter(Boolean);

package/src/dashboard/scanner/project-api.js

@@ -1,11 +1,6 @@
 /**
- * The live half of the dashboard: the project's features and activity, served
- * as JSON by the Vite dev server (`/api/morph/*`) and refreshed when `.morph/`
- * changes on disk. The framework knowledge stays in the static virtual module.
- *
- * Two caches with two lifetimes. A running agent appends to `events.jsonl` on
- * every tool call, so a log change drops only the event cache — rescanning the
- * features (git calls for the active ones) on each tool call would be waste.
+ * Two caches with two lifetimes: an agent appends to `events.jsonl` on every tool
+ * call, so a log change drops only the event cache, never the feature scan.
  */
 
 import { join } from 'path';
@@ -16,17 +11,9 @@ import { containerDirs } from '../../../framework/hooks/shared/worktree-root.js'
 import { isFinished } from './feature-status.js';
 import { resolveFeatureTree } from '../../lib/worktree/feature-truth.js';
 
-/** How long a remembered "which tree owns this feature" answer is trusted without a structural change. */
 const TREE_TTL_MS = 60_000;
 
-/**
- * Which cache a changed path invalidates, or null when it is none of ours.
- * `.morph/framework/` is the installed framework copy (often a junction), and
- * it never changes what this API returns.
- *
- * @param {string} path
- * @returns {'activity'|'features'|null}
- */
+/** `.morph/framework/` is the installed framework copy and never changes what this API returns. */
 export function classifyChange(path) {
   const p = String(path).replace(/\\/g, '/');
   if (!p.includes('/.morph/') && !p.endsWith('/.morph')) return null;
@@ -36,19 +23,12 @@ export function classifyChange(path) {
   return null;
 }
 
-/**
- * A full-page reload Vite would send for a file under a project's `.morph/`
- * (an agent writing a design .html). The dashboard's own code never lives
- * there, so such a reload is never needed.
- */
+/** Vite would full-reload for a `.html` under `.morph/`; the dashboard's code never lives there. */
 export function isMorphDataReload(path) {
   return typeof path === 'string' && path.replace(/\\/g, '/').includes('/.morph/');
 }
 
-/**
- * The directories worth watching: the root's and each worktree's feature,
- * archive, log and config folders — never a whole worktree (its node_modules).
- */
+/** Never a whole worktree: its node_modules. */
 export function watchTargets(projectDir) {
   const morphDirs = [join(projectDir, '.morph')];
   for (const container of containerDirs(projectDir)) {
@@ -72,12 +52,6 @@ function json(status, body) {
   return { status, body };
 }
 
-/**
- * @param {string} projectDir
- * @param {{ scanFeatures?: Function, readFeatureDetail?: Function,
- *   readFeatureFile?: Function, loadEvents?: Function, resolveTree?: Function,
- *   now?: () => number }} [deps] - test seams
- */
 export function createProjectApi(projectDir, deps = {}) {
   const scan = deps.scanFeatures || scanFeatures;
   const detail = deps.readFeatureDetail || readFeatureDetail;
@@ -87,10 +61,8 @@ export function createProjectApi(projectDir, deps = {}) {
     : {});
   const cache = { features: null };
 
-  // Which tree owns a feature costs a few git calls (~0.3 s each on Windows)
-  // and only changes when a file or folder appears or disappears — never when
-  // an agent rewrites feature.json or tasks.json, which is what happens all
-  // the time. Remembered per feature; a structural change or TTL_MS forgets it.
+  // Which tree owns a feature costs git calls (~0.3 s each on Windows) and only
+  // changes on add/remove, never on a rewrite: remembered until a structural event or TTL_MS.
   const resolveTree = deps.resolveTree || resolveFeatureTree;
   const now = deps.now || Date.now;
   const trees = new Map();
@@ -104,17 +76,9 @@ export function createProjectApi(projectDir, deps = {}) {
 
   const features = () => (cache.features ||= scan(projectDir, { resolveTree: rememberedTree }));
   const events = () => store.events();
-  // Where the list scan found each feature: opening one reuses it instead of
-  // asking git again.
   const known = (name) => features().features?.find((f) => f.name === name) || undefined;
 
-  /**
-   * @param {'features'|'activity'|'all'} scope
-   * @param {string} [path] - the file that changed; a live log is then tailed
-   *   instead of reloading every log
-   * @param {string} [event] - the watcher event; anything but 'change' (a file
-   *   or folder added or removed) may move a feature to another tree
-   */
+  /** Any `event` but 'change' may move a feature to another tree. */
   function invalidate(scope, path, event) {
     if (scope === 'features' || scope === 'all') cache.features = null;
     if (scope === 'all' || (scope === 'features' && event !== 'change')) trees.clear();
@@ -122,10 +86,6 @@ export function createProjectApi(projectDir, deps = {}) {
     else if (scope === 'activity') store.changed(path);
   }
 
-  /**
-   * @param {string} url - path + query, relative to `/api/morph`
-   * @returns {{ status: number, body: object }}
-   */
   function handle(url) {
     const u = new URL(url, 'http://local');
     const parts = u.pathname.split('/').filter(Boolean).map(decodeURIComponent);
@@ -159,20 +119,14 @@ export function createProjectApi(projectDir, deps = {}) {
     }
   }
 
-  /** Load everything once, so the first page a person opens does not pay for it. */
   function warm() {
     try { features(); events(); } catch { /* the first request will report it */ }
   }
 
-  /** Cheap to answer now: the list and the events are both in memory. */
   function ready() {
     return cache.features !== null && store.ready();
   }
 
-  /**
-   * What the portfolio shows of this project: counts, the active features with
-   * their last activity, and when anything last happened.
-   */
   function summary() {
     const scan = features();
     const last = lastActivityByFeature(events());

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

@@ -20,8 +20,7 @@ function parseFrontmatter(content) {
 
 const ROUTE_LINE = /^- \*\*([a-z0-9-]+)\*\* \(`([^`]+\.md)`\)/;
 
-// Bullet form: - **<id>** (`<path under standards/>`) — <digest>. An `@path`
-// import inside .claude/rules resolves relative to the rule file and never loads.
+// An `@path` import inside .claude/rules resolves relative to the rule file and never loads.
 export function parseStandardRoutes(content) {
   const routes = [];
   for (const line of content.split(/\r?\n/)) {