@polymorphism-tech/morph-spec 9.0.0 → 9.1.0

package/src/lib/specs/screen-checklist.js

@@ -1,30 +1,10 @@
-/**
- * O checklist de tela do `1-design/mockups.md` — as decisões que uma tela de
- * dados precisa (volume, paginação, ordenação, filtro, os três estados,
- * mobile, abas) escritas por tela, na fase uiux.
- *
- * Existe porque o que o design não pergunta não vira cenário, e o que
- * não é cenário ninguém entrega: telas de admin saíam listando tudo, sem
- * paginar nem ordenar, com o design aprovado. Os leitores do MESMO parser:
- *
- *   - `gate-check uiux` pausa com os problemas nomeados;
- *   - `approve`/`advance` com assinatura `auto` recusam a mesma pausa sem uma
- *     decisão gravada (`uiuxAutoApprovalBlock`) — a regra é a do risk-detector;
- *   - `gate-check review` exige que o verificador registre a conferência de cada
- *     item decidido contra a tela entregue (`checklistCoverage`).
- *
- * Mockup no formato ANTERIOR ao checklist (telas `## S001: …`, sem nenhuma
- * `## Tela:`) é legado e isento, com a isenção gravada no sinal.
- *
- * O formato é o que a `morph-uiux` ensina: cada tela é um `## Tela: <nome>`, e
- * dentro dela um `### Checklist de tela` com uma linha por item — tabela
- * (`| Paginação | servidor, 25/página |`) ou lista (`- **Paginação:** …`).
- * "Não se aplica" é resposta válida; vazio, "?" ou "a definir" não são.
- */
+// Cada tela é `## Tela: <nome>` com um `### Checklist de tela`, uma linha por item (tabela ou lista).
+// "Não se aplica" é resposta válida; vazio, "?" ou "a definir" não são. Telas `## S001: …` sem
+// nenhuma `## Tela:` são o formato legado, isento.
 
 import { createHash } from 'crypto';
 import { existsSync, readFileSync } from 'fs';
-import { join } from 'path';
+import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { getAbsoluteOutputPath } from '../../core/paths/output-schema.js';
 import { verifierScreenChecklist } from '../review-reports.js';
@@ -32,12 +12,7 @@ import { LEGACY_MOCKUP_EXEMPTION, uiuxChecklistPause } from '../risk-detector.js
 
 const PACKAGE_AGENTS = fileURLToPath(new URL('../../../framework/agents.json', import.meta.url));
 
-/**
- * Os itens, na ordem do template. `match` roda sobre o rótulo NORMALIZADO
- * (minúsculas, sem acento): "Estado de erro", "Erro" e "**Erro:**" são o mesmo
- * item. Um rótulo que casa com vários ("Estados (vazio/carregando/erro)")
- * responde a todos eles.
- */
+/** `match` roda sobre o rótulo normalizado; um rótulo que casa com vários itens responde a todos. */
 export const SCREEN_CHECKLIST_ITEMS = [
   { id: 'superficie', label: 'Superfície', match: /\bsuperficie\b/ },
   { id: 'volume', label: 'Volume esperado', match: /\bvolume\b/ },
@@ -51,26 +26,24 @@ export const SCREEN_CHECKLIST_ITEMS = [
   { id: 'abas', label: 'Abas', match: /\babas\b/ },
 ];
 
-/**
- * Itens que o verificador não confere contra a tela: a superfície decide QUAIS
- * standards a tela lê, não um comportamento que a tela entregue exiba.
- */
+// A superfície decide quais standards a tela lê, não um comportamento que a tela entregue exiba.
 const NOT_VERIFIED_AT_REVIEW = new Set(['superficie']);
 
-/**
- * Respostas que ocupam a célula sem decidir nada: as exatas, e as que COMEÇAM
- * adiando a decisão ("a definir depois", "TBD.", "? talvez").
- */
+// As exatas, e as que começam adiando a decisão ("a definir depois", "TBD.").
 const PLACEHOLDERS = new Set(['', '-', '--', '—', '–', '...', 'x', 'todo', 'definir', 'pendente']);
 const PLACEHOLDER_PREFIX_RE = /^(a definir|tbd|\?|…)/;
 
-/** O formato de mockup anterior ao checklist: telas `## S001: <nome>`. */
 const LEGACY_SCREEN_HEADING_RE = /^##\s+S\d+\s*:/i;
 
 const NOT_APPLICABLE_RE = /^(nao se aplica|n\/a)\b/;
 
 const SCREEN_HEADING_RE = /^##\s+tela\s*[:—–-]\s*(.+?)\s*#*\s*$/i;
 const CHECKLIST_HEADING_RE = /^(#{3,6})\s+checklist\b/i;
+const PROTOTYPE_LINE_RE = /prot[oó]tipo/i;
+const PROTOTYPE_PATH_RE = /(?:1-design\/)?(prototipos\/[^\s`|)\]]+\.html)/i;
+
+/** As larguras dos prints que o laço de autocrítica deixa ao lado do protótipo. */
+export const PROTOTYPE_WIDTHS = [1280, 390];
 
 /** Minúsculas, sem acento, sem marcação inline, espaços colapsados. */
 export function normalizeLabel(text) {
@@ -83,21 +56,15 @@ export function normalizeLabel(text) {
     .trim();
 }
 
-/** Nome de tela comparável entre o mockup e o relatório do avaliador. */
 function screenKey(name) {
   return normalizeLabel(name).replace(/^tela\s*[:—–-]\s*/, '').replace(/[.:;,]+$/, '');
 }
 
-/** Os itens que um rótulo responde. */
 function itemsOf(label) {
   const norm = normalizeLabel(label);
   return SCREEN_CHECKLIST_ITEMS.filter((item) => item.match.test(norm)).map((item) => item.id);
 }
 
-/**
- * Uma linha de checklist como `[rótulo, resposta]`, ou null: linha de tabela
- * (separador `|---|` fora) ou item de lista `- Rótulo: resposta`.
- */
 function checklistRow(line) {
   const trimmed = line.trim();
   if (trimmed.startsWith('|')) {
@@ -112,13 +79,12 @@ function checklistRow(line) {
   return [bullet[1].slice(0, colon), bullet[1].slice(colon + 1).trim()];
 }
 
-/** As células de uma linha de tabela markdown, sem as bordas. */
 export function tableCells(line) {
   const inner = line.trim().replace(/^\|/, '').replace(/\|$/, '');
   return inner.split(/(?<!\\)\|/).map((cell) => cell.trim());
 }
 
-/** Linhas fora de blocos cercados: um exemplo dentro de ``` não é uma tela. */
+// Um exemplo dentro de ``` não é uma tela.
 function proseLines(markdown) {
   const out = [];
   let fenced = false;
@@ -129,12 +95,6 @@ function proseLines(markdown) {
   return out;
 }
 
-/**
- * As telas do mockup e o que o checklist de cada uma responde.
- *
- * @param {string} markdown - conteúdo do `1-design/mockups.md`
- * @returns {Array<{ name: string, hasChecklist: boolean, answers: Map<string, string> }>}
- */
 export function parseScreens(markdown) {
   const screens = [];
   let screen = null;
@@ -146,7 +106,7 @@ export function parseScreens(markdown) {
       const level = heading[1].length;
       const named = SCREEN_HEADING_RE.exec(line);
       if (level <= 2) {
-        screen = named && named[1].trim() ? { name: named[1].trim(), hasChecklist: false, answers: new Map() } : null;
+        screen = named && named[1].trim() ? { name: named[1].trim(), hasChecklist: false, answers: new Map(), prototype: null } : null;
         if (screen) screens.push(screen);
         checklistLevel = 0;
         continue;
@@ -160,6 +120,9 @@ export function parseScreens(markdown) {
       }
       continue;
     }
+    if (screen && !screen.prototype && PROTOTYPE_LINE_RE.test(line)) {
+      screen.prototype = PROTOTYPE_PATH_RE.exec(line)?.[1] ?? null;
+    }
     if (!screen || !checklistLevel) continue;
     const row = checklistRow(line);
     if (!row) continue;
@@ -178,16 +141,8 @@ const isNotApplicable = (answer) => NOT_APPLICABLE_RE.test(normalizeLabel(answer
 
 const labelOf = (id) => SCREEN_CHECKLIST_ITEMS.find((item) => item.id === id)?.label ?? id;
 
-/**
- * As superfícies que a persona `ui-designer` declara no `agents.json` — o
- * vocabulário válido do item `Superfície`, que o `morph-plan` usa para
- * somar os standards da tela no `standards:` da fatia. Lê a cópia instalada do
- * projeto; sem ela (este repositório), a do pacote. Persona sem `surfaces`
- * (instalação anterior ao campo) devolve null: o valor não é validado.
- *
- * @param {string} cwd
- * @returns {string[]|null}
- */
+// O vocabulário válido de `Superfície`: as `surfaces` da `ui-designer`, da cópia instalada ou do pacote.
+// null quando a persona não declara o campo, e então o valor não é validado.
 export function knownSurfaces(cwd) {
   const surfaces = readAgentsJson(cwd)?.agents?.['ui-designer']?.surfaces;
   return surfaces && typeof surfaces === 'object' && !Array.isArray(surfaces) ? Object.keys(surfaces) : null;
@@ -202,24 +157,13 @@ export function readAgentsJson(cwd) {
   return null;
 }
 
-/** A resposta de `Superfície` nomeia uma das superfícies conhecidas? */
 function namesSurface(answer, surfaces) {
   const norm = normalizeLabel(answer);
   return surfaces.some((key) => new RegExp(`(^|[^a-z0-9-])${key}([^a-z0-9-]|$)`).test(norm));
 }
 
-/**
- * Audita o checklist do mockup: toda tela tem o bloco, e todo item tem uma
- * resposta escrita — e, quando `surfaces` é dado, a `Superfície` é uma delas.
- *
- * Sem nenhuma `## Tela:`, o mockup é `legacy` (isento) só quando declara telas
- * no formato antigo; qualquer outro formato é o problema "nenhuma tela
- * declarada" — senão trocar o heading seria o atalho para pular o checklist.
- *
- * @param {string} markdown
- * @returns {{ legacy: boolean, screens: Array<{ name: string, hasChecklist: boolean, missing: string[], unanswered: string[] }>,
- *   problems: string[] }} `problems` vazio ⇔ checklist completo (ou isento)
- */
+// Sem nenhuma `## Tela:`, só o formato antigo é legado; qualquer outro heading é "nenhuma tela
+// declarada", senão trocar o heading pularia o checklist.
 export function auditScreenChecklist(markdown, { surfaces = null } = {}) {
   const parsed = parseScreens(markdown);
   const problems = [];
@@ -247,31 +191,38 @@ export function auditScreenChecklist(markdown, { surfaces = null } = {}) {
         problems.push(`tela "${screen.name}": Superfície "${surface}" não é uma das superfícies da ui-designer (${surfaces.join(', ')})`);
       }
     }
-    return { name: screen.name, hasChecklist: screen.hasChecklist, missing, unanswered };
+    return { name: screen.name, hasChecklist: screen.hasChecklist, missing, unanswered, prototype: screen.prototype };
   });
   return { legacy: false, screens, problems };
 }
 
-/**
- * O sinal `screenChecklist` de um gate, lido do disco. COLETA, nunca decide:
- * quem pausa é o risk-detector.
- *
- * `mockups: false` é "a feature não tem mockup" — nada a cobrar. No review, o
- * que se cobra é a conferência (`uncovered`: itens decididos sem linha na
- * seção do verificador), não o design, que já passou pelo Gate uiux.
- *
- * @param {string} cwd
- * @param {string} featureName
- * @param {string} gateName
- * @returns {{ mockups: boolean, legacy: boolean, screens: string[], problems: string[],
- *   exempt?: string, section?: boolean, uncovered?: string[] }}
- */
+// Linha **Protótipo:** da tela + o HTML + os prints do laço de autocrítica ao lado dele.
+export function auditPrototypes(screens, designDir) {
+  const problems = [];
+  for (const screen of screens) {
+    if (!screen.prototype) {
+      problems.push(`tela "${screen.name}" sem a linha \`**Protótipo:** 1-design/prototipos/<tela>.html\``);
+      continue;
+    }
+    const base = screen.prototype.replace(/\.html$/i, '');
+    const expected = [screen.prototype, ...PROTOTYPE_WIDTHS.map((width) => `${base}-${width}.png`)];
+    const missing = expected.filter((rel) => !existsSync(join(designDir, rel)));
+    if (missing.length) problems.push(`tela "${screen.name}": falta ${missing.map((rel) => `1-design/${rel}`).join(', ')}`);
+  }
+  return problems;
+}
+
+// Coleta, nunca decide: quem pausa é o risk-detector. No review cobra-se a conferência (`uncovered`), não o design.
 export function collectScreenChecklist(cwd, featureName, gateName) {
   const mockups = readMockups(cwd, featureName);
   if (mockups === null) return { mockups: false, legacy: false, screens: [], problems: [] };
   const audit = auditScreenChecklist(mockups, { surfaces: knownSurfaces(cwd) });
   const signal = { mockups: true, legacy: audit.legacy, screens: audit.screens.map((s) => s.name), problems: audit.problems };
   if (audit.legacy) signal.exempt = LEGACY_MOCKUP_EXEMPTION;
+  if (gateName === 'uiux' && !audit.legacy) {
+    const designDir = dirname(getAbsoluteOutputPath(cwd, featureName, 'uiMockups'));
+    signal.prototypes = auditPrototypes(audit.screens, designDir);
+  }
   if (gateName === 'review') {
     const report = verifierScreenChecklist(cwd, featureName);
     signal.section = report.section;
@@ -280,36 +231,15 @@ export function collectScreenChecklist(cwd, featureName, gateName) {
   return signal;
 }
 
-/**
- * Por que o Gate uiux NÃO pode ser aprovado com assinatura `auto` — a pausa
- * que o `gate-check uiux` daria pelo checklist —, ou null. Lido por `approve`
- * e `advance`, para que uma aprovação automática nunca passe onde o gate-check
- * pausaria. Uma decisão gravada com `pause: false` (o `gate-decision` manual,
- * ou um gate-check que não pausou) é a resposta a essa pausa e destrava — só
- * para o mockup que ela viu: a decisão guarda `mockupsHash`, e um mockup
- * escrito ou mudado depois dela volta a ser conferido.
- *
- * @param {string} cwd
- * @param {string} featureName
- * @param {object} feature - o feature.json (lê `gateDecisions.uiux`)
- * @returns {string|null}
- */
+// Lido por approve e advance para que o `auto` nunca passe onde o gate-check pausaria. Uma decisão com
+// `pause: false` destrava só o design que ela viu: guarda `mockupsHash`, e mudar o arquivo volta a conferir.
 export function uiuxAutoApprovalBlock(cwd, featureName, feature) {
   const decision = feature?.gateDecisions?.uiux;
   if (decision?.pause === false && decision.mockupsHash === mockupsHash(cwd, featureName)) return null;
   return uiuxChecklistPause(collectScreenChecklist(cwd, featureName, 'uiux'));
 }
 
-/**
- * O que o verificador deixou de conferir: por tela do mockup, os itens com
- * decisão (nem "não se aplica", nem a superfície) sem linha na seção
- * `## Checklist de tela` do relatório. Uma linha que o avaliador marca como
- * não verificável conta como conferida — o que pausa é a AUSÊNCIA da linha.
- *
- * @param {string} designMarkdown - o `1-design/mockups.md`
- * @param {string} reportSection - o corpo da seção do `verifier.md`
- * @returns {string[]} `"<tela>: <item>, <item>"` por tela com lacuna
- */
+// Linha marcada como não verificável conta como conferida: o que pausa é a ausência da linha.
 export function checklistCoverage(designMarkdown, reportSection) {
   const covered = new Map();
   for (const line of proseLines(reportSection)) {
@@ -333,14 +263,7 @@ export function checklistCoverage(designMarkdown, reportSection) {
   return gaps;
 }
 
-/**
- * O `1-design/mockups.md` por conteúdo: BOM e CRLF não contam, para que o
- * checkout de outra máquina seja o mesmo mockup.
- *
- * @param {string} cwd
- * @param {string} featureName
- * @returns {string|null} null sem mockup
- */
+// BOM e CRLF não contam: o checkout de outra máquina é o mesmo arquivo.
 export function mockupsHash(cwd, featureName) {
   const text = readMockups(cwd, featureName);
   if (text === null) return null;

package/src/lib/stack/dotnet-build-ignores.js

@@ -27,17 +27,13 @@ function planHasDotnetSlice(tree, featureName) {
   return (checks?.slices || []).some((slice) => DOTNET_IMPLEMENTERS.includes(String(slice.persona || '').replace(/^morph-/, '')));
 }
 
-/**
- * "Is this a .NET project?" from what is known before the first code commit:
- * the declared `project.stack`, a .NET implementer in the plan's slices, or a
- * .csproj/.sln/.slnx already in the tree. Greenfield has only the second.
- */
+// The plan's slices are checked because a greenfield tree has no stack or .csproj yet.
 export function isDotnetProject(tree, { featureName, configRoot = tree } = {}) {
   if (getProjectTags(readMorphConfig(configRoot)).includes('dotnet')) return true;
   return planHasDotnetSlice(tree, featureName) || hasDotnetProjectFile(tree);
 }
 
-/** @returns {string[]} the `.gitignore` entries added to `tree`; `[]` when not .NET or on any error */
+/** Returns the `.gitignore` entries added; `[]` when not .NET or on any error. */
 export function seedDotnetBuildIgnores(tree, options = {}) {
   try {
     return isDotnetProject(tree, options) ? ensureDotnetBuildIgnores(tree) : [];

package/src/lib/stack/stack-profile.js

@@ -1,17 +1,6 @@
 import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 
-/** @typedef {'nextjs'|'dotnet'|'nodejs-cli'|'unknown'} StackName */
-
-/**
- * @typedef {Object} StackProfile
- * @property {StackName} stack
- * @property {boolean} isDotnet
- * @property {boolean} isNextjs
- * @property {string[]} defaultValidators
- * @property {string|null} buildCommand
- */
-
 const DOTNET_STACKS = new Set(['dotnet', 'aspnet']);
 const NEXTJS_STACKS = new Set(['nextjs', 'next', 'next.js']);
 const NO_VALIDATOR_STACKS = new Set(['nodejs-cli', 'node-cli', 'cli']);
@@ -34,9 +23,6 @@ const PROFILES = {
   },
 };
 
-/**
- * Read project stack from .morph/config/config.json.
- */
 function readStack(cwd) {
   const configPath = join(cwd, '.morph', 'config', 'config.json');
   if (!existsSync(configPath)) return null;
@@ -47,7 +33,6 @@ function readStack(cwd) {
   }
 }
 
-/** Merge two or more profiles' validator lists (deduped) and boolean flags. */
 function mergeProfiles(profiles) {
   return {
     isDotnet: profiles.some((p) => p.isDotnet),
@@ -57,16 +42,7 @@ function mergeProfiles(profiles) {
   };
 }
 
-/**
- * Get the StackProfile for the current project.
- *
- * `stack` may be a compound value (e.g. "dotnet-nextjs", "dotnet+nextjs") —
- * the framework's own convention for monorepos (see stack-filter.js's
- * getProjectTags, which splits project.stack the same way). Each segment is
- * resolved independently and matching profiles are merged, instead of the
- * whole compound string failing every exact-match check and silently
- * collapsing to the empty profile (0 default validators).
- */
+/** A compound stack ("dotnet-nextjs", "dotnet+nextjs") merges the profile of each segment. */
 export function getStackProfile(cwd, stackOverride) {
   const root = cwd ?? process.cwd();
   const raw = stackOverride ?? readStack(root);
@@ -74,8 +50,6 @@ export function getStackProfile(cwd, stackOverride) {
 
   const segments = stack.split(/[-+]/).filter(Boolean);
 
-  // Single-segment stack (the overwhelming common case): resolve exactly as
-  // before, byte-for-byte, including the 'unknown' → dotnet fallback.
   if (segments.length <= 1) {
     let profile;
     if (NEXTJS_STACKS.has(stack)) {
@@ -90,7 +64,6 @@ export function getStackProfile(cwd, stackOverride) {
     return { stack, ...profile };
   }
 
-  // Compound stack: resolve each recognized segment and merge.
   const matched = [];
   if (segments.some((s) => DOTNET_STACKS.has(s))) matched.push(PROFILES.dotnet);
   if (segments.some((s) => NEXTJS_STACKS.has(s))) matched.push(PROFILES.nextjs);

package/src/lib/stack/stack-scan.js

@@ -175,13 +175,7 @@ function auditNextjs(root, read) {
 
 const AUDITS = { dotnet: auditDotnet, nextjs: auditNextjs };
 
-/**
- * Deterministic stack audit of the tree at `root`, driven by `config.project.stack`:
- * only the configured stacks are judged; no configured stack means no rule runs.
- *
- * @param {string} root
- * @param {object|null} config the parsed `.morph/config/config.json`
- */
+/** Only the stacks in `config.project.stack` are judged; none configured means no rule runs. */
 export function scanStack(root, config) {
   const stack = typeof config?.project?.stack === 'string' ? config.project.stack : null;
   const tags = getProjectTags(config);
@@ -230,7 +224,6 @@ export function notAuditedReason(result) {
     : 'não auditado: project.stack ausente em .morph/config/config.json';
 }
 
-/** The scan as the markdown report the morph-plan skill reads. */
 export function renderStackScan(result, title) {
   const out = [`# Stack Scan — ${title}`, ''];
   out.push(`**Stack configurado:** ${result.stack ? `\`${result.stack}\`` : 'ausente em `project.stack` — nenhuma regra aplicada'}`);

package/src/lib/stack-filter.js

@@ -1,14 +1,4 @@
-/**
- * Parse `stacks:` from YAML frontmatter content.
- * Returns ['*'] if no stacks field found (backwards compatible — always install).
- *
- * Supports:
- *   stacks:\n  - dotnet\n  - blazor   (YAML list)
- *   stacks: [dotnet, blazor]           (inline array)
- *
- * @param {string} content - Raw file content with YAML frontmatter
- * @returns {string[]}
- */
+/** `['*']` without a `stacks:` field (always install); accepts a YAML list or an inline array. */
 export function parseStacks(content) {
   const normalized = content.replace(/\r\n/g, '\n');
   const fmMatch = normalized.match(/^---\n([\s\S]*?)\n---/);
@@ -16,9 +6,7 @@ export function parseStacks(content) {
 
   const fm = fmMatch[1];
 
-  // Try inline format: stacks: [dotnet, blazor] — quotes stripped like the
-  // list branch below; `["umbraco"]` sem isso parseava como a string literal
-  // `"umbraco"` (com aspas) e nunca casava tag nenhuma.
+  // Quotes stripped like the list branch: `["umbraco"]` would otherwise never match a tag.
   const inlineMatch = fm.match(/^stacks:\s*\[([^\]]*)\]/m);
   if (inlineMatch) {
     const items = inlineMatch[1]
@@ -28,7 +16,6 @@ export function parseStacks(content) {
     return items.length > 0 ? items : ['*'];
   }
 
-  // Try YAML list format: stacks:\n  - dotnet\n  - blazor
   const listMatch = fm.match(/^stacks:\s*\n((?:\s+-\s+.+\n?)*)/m);
   if (listMatch) {
     const items = listMatch[1]
@@ -41,12 +28,7 @@ export function parseStacks(content) {
   return ['*'];
 }
 
-/**
- * Extract project tags from config object.
- * Combines stack tags (from `project.stack` split by '-' or '+')
- * with integration tags (from `project.integrations` array).
- * Deduplicates the result.
- */
+/** Stack tags (`project.stack` split by '-' or '+') plus `project.integrations`, deduplicated. */
 export function getProjectTags(config) {
   const stack = config?.project?.stack;
   const stackTags = (stack && typeof stack === 'string')
@@ -58,12 +40,7 @@ export function getProjectTags(config) {
   return [...new Set([...stackTags, ...integrations])];
 }
 
-/**
- * Determine if an asset should be installed for the given project tags.
- * - stacks includes '*' → always install
- * - stacks is empty → treat as '*' (backwards compatible)
- * - Otherwise → install if intersection with projectTags is non-empty
- */
+/** Empty or '*' stacks always install; otherwise any intersection with the project tags. */
 export function shouldInstall(assetStacks, projectTags) {
   if (assetStacks.length === 0 || assetStacks.includes('*')) return true;
   return assetStacks.some(s => projectTags.includes(s));

package/src/lib/standards/registry.js

@@ -22,13 +22,7 @@ function readMeta(standardsJsonPath) {
   }
 }
 
-/**
- * The registry as every reader sees it: runtime entries with their sidecar
- * fields merged back by id. A missing or unreadable sidecar degrades to "no
- * aliases"; a missing or unreadable STANDARDS.json throws.
- * @param {string} standardsJsonPath
- * @returns {{ version: string|null, standards: object[], sharedAliases: Record<string, string[]> }}
- */
+/** Sidecar merged by id. Missing/unreadable sidecar = no aliases; missing STANDARDS.json throws. */
 export function loadStandardsRegistry(standardsJsonPath) {
   const runtime = JSON.parse(readFileSync(standardsJsonPath, 'utf8'));
   const meta = readMeta(standardsJsonPath);

package/src/lib/standards/sections.js

@@ -5,12 +5,7 @@ export function ghSlug(heading) {
   return heading.trim().toLowerCase().replace(SLUG_STRIP, '').replace(/ /g, '-');
 }
 
-/**
- * Every heading outside code fences, with the slug GitHub gives it (`-1`, `-2`
- * for repeats) and the line it sits on.
- * @param {string} text
- * @returns {Array<{ level: number, title: string, slug: string, line: number }>}
- */
+/** Headings outside code fences, repeated slugs suffixed `-1`, `-2` as GitHub does. */
 export function markdownHeadings(text) {
   const out = [];
   const seen = new Map();
@@ -39,13 +34,7 @@ export function headingSlugs(text) {
   return new Set(markdownHeadings(text).map((h) => h.slug));
 }
 
-/**
- * The section a slug opens: its heading through the line before the next
- * heading of the same or a higher level. `null` when no heading has the slug.
- * @param {string} text
- * @param {string} slug - with or without the leading `#`
- * @returns {string|null}
- */
+/** Heading through the line before the next heading of same or higher level; slug may carry `#`. */
 export function sectionBySlug(text, slug) {
   const want = String(slug).replace(/^#/, '');
   const all = markdownHeadings(text);