@polymorphism-tech/morph-spec 9.0.0 → 9.1.0

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 a slice report, 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/)) {

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

@@ -1,7 +1,7 @@
 import { readFileSync, readdirSync, existsSync } from 'fs';
 import { join } from 'path';
 
-/** One-line `key: value` frontmatter. CRLF-safe: a checkout with autocrlf is still read. */
+/** CRLF-safe: a checkout with autocrlf is still read. */
 export function parseFrontmatter(content) {
   const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(content);
   if (!match) return {};
@@ -21,19 +21,9 @@ export function parseFrontmatter(content) {
 const FENCE = /^(\s*)```/;
 const DISPATCH_HINT = /dispatch|despach|subagent_type|Template do prompt/i;
 const PERSONA_REF = /morph-(\{id\}|\{task\.agent\}|[a-z][a-z-]*[a-z])/g;
-/** Words after `morph-` that are skills or CLI verbs, never personas. */
-/** Claude Code's own sub-agents: dispatched by skills, but not personas of agents.json. */
 const BUILTIN_AGENT = /`(Explore|general-purpose|Plan)`/g;
 const NOT_PERSONA = /^(spec|proposal|brainstorming|stack-scan|uiux|plan|implement|apply|review|eval|hotfix|standards|media|task)$/;
 
-/**
- * The prompts a skill tells the orchestrator to send to a sub-agent: fenced
- * blocks that are either written as a dispatch (`dispatch Agent (…)`) or sit
- * right under a line about dispatching. Each carries the personas it names —
- * `generic` when the template is `morph-{id}` (any implementer).
- *
- * @returns {Array<{ index: number, personas: string[], generic: boolean, builtin: string[], context: string, text: string }>}
- */
 export function extractDispatchPrompts(content) {
   const lines = content.split(/\r?\n/);
   const out = [];
@@ -45,7 +35,7 @@ export function extractDispatchPrompts(content) {
     const body = lines.slice(i + 1, j);
     const text = body.map((l) => l.slice(Math.min(open[1].length, l.length - l.trimStart().length))).join('\n');
     // Only the sentence that introduces the block counts: a paragraph further up
-    // that mentions a dispatch (morph-apply's DAG example) is not this block's.
+    // that mentions a dispatch is not this block's.
     let k = i - 1;
     while (k >= 0 && lines[k].trim() === '') k--;
     const before = k >= 0 && i - k <= 2 ? lines[k] : '';

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

@@ -10,12 +10,8 @@ export function scanStandards(frameworkDir, agents) {
   const refMap = {};
   for (const agent of agents) {
     for (const std of personaStandardIds(agent)) {
-      // agents.json stores standards as plain id STRINGS. Reading `std.id` off
-      // a string yields undefined, so every reference piled into refMap
-      // [undefined] and the lookup below missed all 60 — the Standards graph
-      // drew standards with no agent edge at all. The object form is the v4
-      // shape (`{ id, scope, priority }`); still accepted so a mixed or
-      // restored agents.json does not silently lose edges again.
+      // agents.json stores standards as id strings; the `{ id }` object form is
+      // still accepted so a mixed agents.json does not lose edges.
       const id = typeof std === 'string' ? std : std?.id;
       if (!id) continue;
       if (!refMap[id]) refMap[id] = [];

package/src/dashboard/vite-plugin-morph-data.js

@@ -21,14 +21,6 @@ function readBody(req) {
   });
 }
 
-/**
- * Two data paths:
- *   - `virtual:morph-data` — the framework's knowledge (agents, phases, skills,
- *     standards, rules, hooks, docs). Static for the life of the server.
- *   - `/api/morph/*` — the portfolio (`/projects`) and each project's features
- *     and activity (`/p/:id/…`), read on demand and pushed as `morph:changed`
- *     over the HMR socket when a project's `.morph/` changes.
- */
 export default function morphDataPlugin(frameworkDir, projectDir) {
   return {
     name: 'vite-plugin-morph-data',
@@ -43,11 +35,8 @@ export default function morphDataPlugin(frameworkDir, projectDir) {
       const portfolio = createPortfolio({ launchDir: projectDir });
       const push = (data) => server.ws.send({ type: 'custom', event: 'morph:changed', data });
 
-      // Vite reloads the whole page for any changed .html it watches, even when
-      // handleHotUpdate returns [] (vite 6: no module matched + .html = full
-      // reload). A project's .morph/ carries .html design sources, and an agent
-      // writing one reloaded the dashboard under the person reading it. The
-      // dashboard's own code never lives under .morph/.
+      // Vite 6 full-reloads any changed .html it watches even when handleHotUpdate
+      // returns [], and a project's .morph/ carries .html design sources.
       const clientHot = server.environments?.client?.hot;
       if (clientHot?.send) {
         const send = clientHot.send.bind(clientHot);
@@ -64,10 +53,8 @@ export default function morphDataPlugin(frameworkDir, projectDir) {
         if (fresh.length) server.watcher.add(fresh);
       }
 
-      // Read the projects in the background, one at a time, so neither the first
-      // page nor the portfolio waits for a large project. Reading one blocks the
-      // event loop for seconds, so each step waits WARM_GAP_MS first: the reads
-      // a push (or an add) just caused are served before the next block.
+      // One project at a time, WARM_GAP_MS apart: a read blocks the event loop for
+      // seconds, and the reads a push just caused are served first.
       let warming = false;
       function warmSoon() {
         if (warming) return;
@@ -88,7 +75,6 @@ export default function morphDataPlugin(frameworkDir, projectDir) {
         res.setHeader('Content-Type', 'application/json; charset=utf-8');
         res.setHeader('Cache-Control', 'no-store');
         res.end(JSON.stringify(out));
-        // The portfolio's list changed: watch and read any project just added.
         if (req.method !== 'GET' && status === 200) { watchNew(); push({ scope: 'projects' }); warmSoon(); }
       });
 
@@ -98,7 +84,7 @@ export default function morphDataPlugin(frameworkDir, projectDir) {
       rescan.unref?.();
 
       const timers = new Map();
-      const changed = new Map(); // `${project}:${scope}` -> path -> watcher event, in the debounce window
+      const changed = new Map();
       const onFsEvent = (event, path) => {
         const scope = classifyChange(path);
         if (!scope) return;

package/src/lib/ai/ai-checks.js

@@ -1,26 +1,5 @@
-/**
- * ai-checks.js — o coletor das cinco checagens de `morph-spec doctor --ai`.
- *
- * Contrato de uma checagem:
- *
- *     { id, name, status: 'ok'|'warn'|'error'|'skip', reason?, findings: [], unverified?: [] }
- *
- * Duas regras que este módulo existe para tornar mecânicas:
- *
- * 1. **`status: 'skip'` sai com `reason` obrigatória.** "Não verificado" sem
- *    motivo é ruído — quem lê não consegue decidir se falta insumo ou se falta
- *    checagem. Um `skip` sem razão é bug deste arquivo, e há canário.
- * 2. **`null` de uma função de checagem é DESCONHECIDO, nunca "não achei
- *    nada".** `[]` é "perguntei e não achei" e vira `ok`. É a doutrina de
- *    `pr-index.js`, já viva no `doctor`.
- *
- * E uma proibição: **nada alcançável daqui escreve.** Os candidatos óbvios ao
- * erro — `scripts/generate-ai-pin-props.js` e
- * `scripts/generate-standards-registry.js` — escrevem por padrão e NÃO entram
- * no grafo de imports deste módulo. É a lição do T10 da #90, onde a auditoria
- * ia ALOCAR um bloco de porta ao auditar, inventando o estado que reportava.
- * O canário assere a lista de chamadas feitas, não só o retorno.
- */
+// `skip` sai com `reason` obrigatória, e `null` de uma checagem é DESCONHECIDO, nunca "não achei".
+// Nada alcançável daqui escreve: os geradores de `scripts/` ficam fora do grafo de imports.
 
 import { scanAiPackageRefs } from './ai-project-scan.js';
 import { resolveAiPin, auditPinDrift } from './pin-drift.js';
@@ -30,7 +9,6 @@ import { auditRenamedApi, auditPromptSource, renamedApiGate } from './code-audit
 /** Os cinco ids, na ordem em que o relatório os imprime. */
 export const AI_CHECK_IDS = ['pin-drift', 'removed-api', 'pricing-missing', 'api-per-alias', 'prompt-source'];
 
-/** Nome legível de cada checagem. */
 export const AI_CHECK_NAMES = {
   'pin-drift': 'pin × projeto (versões de pacote de IA)',
   'removed-api': 'API renomeada antes do 1.0 GA',
@@ -42,7 +20,6 @@ export const AI_CHECK_NAMES = {
 /** O pacote cuja versão gateia a checagem de API renomeada. */
 export const MAF_PACKAGE = 'Microsoft.Agents.AI';
 
-/** As dependências reais. Substituíveis inteiras ou em parte, por canário. */
 export function defaultAiDeps() {
   return {
     scanAiPackageRefs,
@@ -75,19 +52,8 @@ function skipAll(reason) {
   return AI_CHECK_IDS.map((id) => skip(id, reason));
 }
 
-/**
- * Roda as cinco checagens sobre um projeto.
- *
- * As três condições de silêncio total acontecem ANTES de qualquer leitura do
- * pin — e é essa ordem, não o retorno, que o canário assere: sem `.csproj`
- * alcançável, `resolveAiPin` não é sequer chamada.
- *
- * @param {string} targetPath - raiz do projeto
- * @param {object} [options]
- * @param {object|null} [options.config] - `.morph/config/config.json` já lido
- * @param {object} [options.deps] - substituição parcial de `defaultAiDeps()`
- * @returns {Array<{id: string, name: string, status: string, reason?: string, findings: Array}>}
- */
+// As condições de silêncio total acontecem ANTES de ler o pin: sem `.csproj` alcançável,
+// `resolveAiPin` nem é chamada.
 export function collectAiChecks(targetPath, { config = null, deps = {} } = {}) {
   const d = { ...defaultAiDeps(), ...deps };
 
@@ -114,8 +80,7 @@ export function collectAiChecks(targetPath, { config = null, deps = {} } = {}) {
   const unverified = scan.unreadable.slice();
   const checks = [];
 
-  // ── pin-drift ────────────────────────────────────────────────────────────
-  // Condição 2: sem pin resolvível, a checagem que depende dele sai skip.
+  // Sem pin resolvível, a checagem que depende dele sai skip.
   const pin = d.resolveAiPin(targetPath);
   if (!pin) {
     checks.push(skip('pin-drift', 'nenhum `ai-pin.json` resolvível (nem em `.morph/framework/`, nem '
@@ -127,7 +92,6 @@ export function collectAiChecks(targetPath, { config = null, deps = {} } = {}) {
       : resolved('pin-drift', findings, { unverified }));
   }
 
-  // ── removed-api ──────────────────────────────────────────────────────────
   const maf = scan.packages.find((p) => p.name === MAF_PACKAGE) ?? null;
   const gate = d.renamedApiGate(maf);
   if (gate !== null) {
@@ -139,7 +103,6 @@ export function collectAiChecks(targetPath, { config = null, deps = {} } = {}) {
       : resolved('removed-api', findings));
   }
 
-  // ── pricing-missing e api-per-alias ──────────────────────────────────────
   const registry = d.locateAiRegistry(targetPath, config);
   const noRegistry = 'nenhum registry de modelos encontrado — nem `project.ai.modelRegistry` no '
     + 'config, nem um `.json` com `defaultAlias` + mapa de aliases, nem uma seção `Pricing` num '
@@ -155,7 +118,6 @@ export function collectAiChecks(targetPath, { config = null, deps = {} } = {}) {
       : noRegistry)
     : resolved('api-per-alias', perAlias));
 
-  // ── prompt-source ────────────────────────────────────────────────────────
   const prompts = d.auditPromptSource(targetPath);
   checks.push(prompts === null
     ? skip('prompt-source', 'nenhum `.cs` alcançável a partir desta raiz')
@@ -164,19 +126,12 @@ export function collectAiChecks(targetPath, { config = null, deps = {} } = {}) {
   return checks;
 }
 
-/**
- * Código de saída do `doctor --ai`: 1 quando há ao menos um `error`, 0 caso
- * contrário. `warn` e `skip` NUNCA mudam o código de saída — só `pin-drift`
- * produz `error`, e só na faixa flutuante, a única classe com prejuízo medido.
- *
- * @param {Array<{status: string}>} checks
- * @returns {0|1}
- */
+/** `warn` e `skip` nunca mudam o código de saída: só `pin-drift` produz `error`, na faixa flutuante. */
 export function aiExitCode(checks) {
   return checks.some((c) => c.status === 'error') ? 1 : 0;
 }
 
-/** true quando NENHUMA checagem teve insumo — o relatório sai em uma linha. */
+/** true quando nenhuma checagem teve insumo: o relatório sai em uma linha. */
 export function allSkipped(checks) {
   return checks.length > 0 && checks.every((c) => c.status === 'skip');
 }