@polymorphism-tech/morph-spec 9.0.0 → 9.1.0

package/src/lib/installers/templates-reconcile.js

@@ -1,67 +1,13 @@
-/**
- * templates-reconcile.js — reconcile a pre-existing `.morph/framework/templates/`
- * copy against the project's prior recorded morph-spec version.
- *
- * Shared by BOTH install paths that can encounter this directory:
- *   - `morph-spec update` (src/commands/project/update.js) — always knows the
- *     project's prior version (`checkProjectOutdated().current`, read from
- *     `.morph/.morphversion` BEFORE this run overwrites it).
- *   - `morph-spec init`/`setup-infra` (src/scripts/setup-infra.js) — the SAME
- *     source (`getProjectMorphVersion()`, the function `checkProjectOutdated`
- *     itself calls), read at the same point in the run (before its own write
- *     of `.morph/.morphversion`), when it's available — e.g. a repair run
- *     over an already-initialized project. Falls back to a plain warning when
- *     it isn't (a project with no recorded version has nothing here for this
- *     function to reconcile against safely).
- */
-
 import { existsSync } from 'fs';
 import { compareVersions } from '../../utils/version-checker.js';
 import { realEffects } from './effects.js';
 
-/**
- * Last CLI version whose `update`/`setup-infra` still wrote
- * `.morph/framework/templates/` unconditionally, before Task 2 of the R3
- * perf plan removed that copy. Used as the decision boundary in
- * `reconcileLegacyTemplatesCopy` below — see its doc comment for why a
- * version check is used instead of diffing file content.
- */
+// Last CLI version whose install still copied `.morph/framework/templates/` unconditionally.
 export const LAST_VERSION_THAT_COPIED_TEMPLATES = '8.17.0';
 
-/**
- * Reconcile a pre-existing `.morph/framework/templates/` copy now that
- * neither install path unconditionally writes it anymore (Task 2, R3 perf
- * plan — resolution falls back to the npm package's own framework/templates/,
- * see template-registry.js / architecture-scanner.js's layered resolver).
- *
- * Decided from the project's PRIOR recorded CLI version (before THIS run
- * writes a new one), not by diffing content against the package. A content
- * diff can't tell "stale copy from an older CLI version" apart from
- * "deliberate user override" — and staleness is the dominant case for
- * anyone who actually runs `update`/`setup-infra` again, since template
- * content does change between releases. The version boundary is unambiguous
- * instead:
- *
- *   - No local copy → nothing to do.
- *   - Prior version is unrecorded, OR <= LAST_VERSION_THAT_COPIED_TEMPLATES
- *     → the copy could ONLY have been put there by the OLD installer:
- *     `.morph/framework/**` is Edit-denied to the agent (MORPH_DENY in
- *     hooks-installer.js — "installer-managed, immutable at runtime"),
- *     the directory is gitignored, and every install/update before this fix
- *     unconditionally wiped + recopied it. There is no path by which a
- *     project on an old version could have a genuine override sitting
- *     here. Safe to delete unconditionally — it is dead weight, not data.
- *   - Prior version > LAST_VERSION_THAT_COPIED_TEMPLATES → this install path
- *     has never written this directory for this project. Anything found
- *     here was placed deliberately (by the user or other tooling) — this is
- *     the forward-looking override use case the layered resolver exists
- *     for. Preserve untouched, unconditionally, with no diffing.
- *
- * @param {string} templatesDest - .morph/framework/templates (may not exist)
- * @param {string|null} priorProjectVersion - project's recorded morph-spec
- *   version BEFORE this run (e.g. `checkProjectOutdated().current`)
- * @returns {'absent'|'removed-legacy'|'preserved-override'}
- */
+// Decided by the PRIOR recorded version, not by diffing: a diff can't tell a stale copy from an override.
+// Unrecorded or <= the boundary → only the old installer could have written it, delete.
+// Newer → placed deliberately, preserve.
 export function reconcileLegacyTemplatesCopy(templatesDest, priorProjectVersion, fx = realEffects()) {
   if (!existsSync(templatesDest)) return 'absent';
 
@@ -74,8 +20,7 @@ export function reconcileLegacyTemplatesCopy(templatesDest, priorProjectVersion,
     fx.remove(templatesDest);
     return 'removed-legacy';
   } catch {
-    // Couldn't remove — don't risk a half-broken state; leave it and let
-    // the layered resolver's override-first check pick it up as before.
+    // Couldn't remove: leave it; the resolver's override-first check picks it up.
     return 'preserved-override';
   }
 }

package/src/lib/mutation/dotnet-introspection.js

@@ -1,10 +1,3 @@
-/**
- * .NET introspection the targeted mutation (`morph-spec mutate`) needs: which
- * project owns a file, which test mode the SDK picks, and which types a C# file
- * declares — read FAIL-SAFE (see csharpClasses).
- *
- * Pure: reads files, never spawns a process.
- */
 import { existsSync, readFileSync, readdirSync } from 'fs';
 import { dirname, join, resolve } from 'path';
 
@@ -13,54 +6,21 @@ import { jsoncToJson } from '../../../framework/hooks/shared/comment-stripper.js
 
 const MTP_RUNNER = 'Microsoft.Testing.Platform';
 const TYPE_HEADER = /\b(?:class|struct|record|interface)\b/;
-/** A C# identifier's first character: a letter, an Nl letter (`Ⅱ`), `_`, `@` (verbatim) or `\` (a unicode escape). */
+// `@` = verbatim identifier, `\` = unicode escape.
 const NAME_START = '[\\p{L}\\p{Nl}_@\\\\]';
-/**
- * TRIPWIRE: every type-declaration keyword wherever it sits — applied to the RAW
- * text (nothing blanked) and to the blanked code alike, with NO context rule:
- * round 5 showed that any exclusion decided by what precedes the keyword (the
- * `:` of a generic constraint, a `where T :` shape) can be forged by a comment in
- * the raw text or by string content a cut exposes in the code. `record class`/
- * `record struct` count once. What follows the keyword, after optional whitespace,
- * is a name start (NAME_START), a comment or preprocessor line standing between
- * the keyword and its name (`class/**\/BTests` is legal), OR a quote — a quote is
- * what the RAW text shows where the blanked code shows the spaces of a string the
- * keyword is followed by (`"; class " : " Fake"` exposed as code): every keyword
- * the code counts is a keyword the raw text counts, by offset.
- * A constraint keyword is therefore counted too whenever a name-shaped token
- * follows it (`where T : class where U : …`, `: class // note`): it is not named,
- * so the file is unscannable. `class,` / `class\n{` / `class?` are not counted at all.
- */
+// TRIPWIRE with NO context rule: any exclusion based on what precedes the keyword can be
+// forged by a comment or exposed string. The quote in the lookahead makes every keyword
+// the blanked code counts also counted in the raw text, at the same offset.
 const TYPE_KEYWORD = new RegExp(`\\b(?:record\\s+(?:class|struct)|class|record|struct|interface)\\b(?=\\s*(?:${NAME_START}|["']|\\/[/*]|#))`, 'gu');
-/** A type declaration the scanner can NAME: after `; { } ]`, a newline or the file start; attributes; modifiers; a NAME_START name. */
 const TYPE_DECL = new RegExp(`(?:^|[;{}\\]\\n])[ \\t]*(?:\\[[^\\]\\n]*\\][ \\t]*)*(?:(?:public|internal|private|protected|sealed|static|partial|abstract|unsafe|file|new|readonly|ref)\\s+)*(record\\s+(?:class|struct)|class|record|struct|interface)\\s+(${NAME_START}[^\\s:<({;,=]*)`, 'gu');
 const IDENT = '[\\p{L}_][\\p{L}\\p{N}_]*';
 const QUALIFIER = `(?:${IDENT}\\s*(?:\\.|::)\\s*)*`;
-/** An attribute's optional arguments: one nested level of parentheses, no `]`. */
 const ATTRIBUTE_ARGS = '(?:\\((?:[^()\\]]|\\([^()\\]]*\\))*\\))?';
-/** Any other attribute of the same section: a name, optionally with arguments. */
 const OTHER_ATTRIBUTE = `${QUALIFIER}${IDENT}\\s*${ATTRIBUTE_ARGS}`;
 const TEST_ATTRIBUTE_NAME = '(?:Fact|Theory|Test|TestMethod|DataTestMethod|TestCase|TestCaseSource)(?:Attribute)?';
-/**
- * A test attribute, read on the BLANKED code of a test-project file (hasTestAttribute):
- * a WHOLE name — `Fact`, `Theory`, `Test`, `TestMethod`, `DataTestMethod`, `TestCase`,
- * `TestCaseSource`, optionally `…Attribute` and qualified (`Xunit.Fact`) — inside an
- * attribute section that CLOSES as one: `[` where a declaration may start (line start,
- * after `;` `{` `}` `]` or a `*\/`), an optional target, other attributes before it
- * separated by `,`, the test name with its optional arguments, any further attributes,
- * then the `]` — followed by a declaration start (`[`, a name, a comment, a directive)
- * or the end of the input.
- *
- * A false POSITIVE is the unsafe direction here: a helper taken for a test file
- * narrows the subset to its own name, and the tests that USE the helper never run. The final review of branch B found
- * exactly that with the old prefix match (`, TestContext` / `, Factory` / `, TheoryData`
- * after any `,`), and its re-review (N1) with a test name merely FOLLOWED by `(` or `,`:
- * a C# 12 collection laid out with `[` alone on its line (`[\n    Env.Dev,\n    Env.Test,\n];`,
- * a row `[Env.Test, Env.Dev],`, `[\n    Test("a"),\n];`). Requiring the section to close
- * rejects all three; what still matches is stated in csharpClasses. A false NEGATIVE
- * only leaves a test file out of a selection (a custom attribute such as `[SkippableFact]`, a test
- * attribute after an argument holding `]`).
- */
+// A false POSITIVE is the unsafe side (a helper taken for a test file hides the tests that
+// use it), so the whole name must sit in an attribute section that CLOSES: a C# 12
+// collection such as `[\n Env.Test,\n];` must not match. Residual cases: csharpClasses.
 export const CS_TEST_ATTRIBUTE = new RegExp(
   '(?:^|[;{}\\]]|\\*\\/)[ \\t]*\\['
   + `\\s*(?:${IDENT}\\s*:(?!:)\\s*)?`
@@ -71,22 +31,12 @@ export const CS_TEST_ATTRIBUTE = new RegExp(
   'mu',
 );
 
-/**
- * File text with a leading UTF-8 BOM stripped (VS and `charset=utf-8-bom` write
- * one) and every C# new-line character mapped 1:1 to `\n` — CR, NEL (U+0085),
- * LS (U+2028), PS (U+2029): JS `\s` excludes NEL, so `class<NEL>Name` was
- * invisible to both regexes (compiled and discovered by xunit); a CR-only file had
- * no line ends at all. U+001A (Ctrl-Z) is mapped 1:1 to a space: Roslyn reads it
- * as whitespace and JS `\s` does not, so `class<SUB>Name` hid a declaration the
- * same way (B3 carry-over: compiled, green while skipping the class). Length is kept (CRLF becomes `\n\n`). null when unreadable.
- */
+// Roslyn reads CR/NEL/LS/PS as new-lines and U+001A as whitespace; JS `\s` misses NEL
+// and U+001A, which hid `class<NEL>Name`. Mapped 1:1 so offsets stay aligned with the code.
 const readText = (path) => {
   try { return readFileSync(path, 'utf8').replace(/\x1A/g, ' ').replace(/^\uFEFF/, '').replace(/[\r\u0085\u2028\u2029]/g, '\n'); } catch { return null; }
 };
 
-/** Which test framework a csproj references, by package (or MSBuild SDK) name. */
-
-/** Nearest file matching `projectName` walking up from a file's directory, inside the root; null when none. */
 function nearestProjectFile(fileAbs, rootAbs, projectName) {
   for (let dir = dirname(fileAbs); isInside(dir, rootAbs); dir = dirname(dir)) {
     let names = [];
@@ -97,32 +47,20 @@ function nearestProjectFile(fileAbs, rootAbs, projectName) {
   return null;
 }
 
-/**
- * The project — `.csproj`, `.fsproj` or `.vbproj` — nearest to ANY file walking
- * up, or null inside the root. Asked about the .NET sources the C# scan cannot
- * read (a bUnit `.razor`, an F# `.fs`).
- */
 export function nearestProjectOf(fileAbs, rootAbs) {
   return nearestProjectFile(fileAbs, rootAbs, /\.(?:cs|fs|vb)proj$/i);
 }
 
-/** .NET sources the C# scan cannot read: Razor (`.razor`, `.cshtml`), F# (`.fs`, `.fsi`, `.fsx`), VB (`.vb`). */
 const NON_CSHARP_SOURCE = /\.(?:razor|cshtml|fs|fsi|fsx|vb)$/i;
 
-/** A .NET source other than C#: no type scan, hence no class selector, for it. */
+/** No type scan, hence no class selector, for these. */
 export const isNonCSharpSource = (path) => NON_CSHARP_SOURCE.test(String(path));
 
-/** Any .NET source a project compiles — C# or one of the others. */
 export const isDotnetSource = (path) => /\.cs$/i.test(String(path)) || isNonCSharpSource(path);
 
 /**
- * `.NET` test mode for a cwd: nearest `global.json` walking UP (as the SDK
- * resolves it — from the CWD, never from the `.sln` argument), read as JSONC.
- *
- * @param {string} absCwd
- * @returns {'mtp'|'vstest'|null} `mtp` when `test.runner` is Microsoft.Testing.Platform;
- *   `vstest` when readable without it (or absent: the SDK default); null when a
- *   global.json exists but cannot be read — never a guess.
+ * Nearest global.json walking up from the CWD, as the SDK resolves it (never from the
+ * `.sln` argument). null when one exists but cannot be read — never a guess.
  */
 export function dotnetTestMode(absCwd) {
   for (let dir = resolve(absCwd); ; dir = dirname(dir)) {
@@ -141,7 +79,6 @@ export function dotnetTestMode(absCwd) {
 
 const lineEnd = (text, i) => { const e = text.indexOf('\n', i); return e < 0 ? text.length : e; };
 
-/** End (exclusive) of a regular string or char literal opened at `start`; -1 if the line ends first. */
 function closeOnLine(text, start, quote) {
   for (let j = start + 1; j < text.length && text[j] !== '\n'; j++) {
     if (text[j] === '\\') j++;
@@ -150,11 +87,8 @@ function closeOnLine(text, start, quote) {
   return -1;
 }
 
-/**
- * Does an interpolated literal's content end inside a hole? A `"` inside a hole
- * (`$"{d["k"]}"`) ends the literal as the scanner reads it, so what it took for
- * the literal stops with the hole still open. `{{`/`}}` outside a hole are escapes.
- */
+// A `"` inside a hole (`$"{d["k"]}"`) ends the literal as the scanner reads it,
+// leaving the hole open. `{{`/`}}` outside a hole are escapes.
 function holeLeftOpen(content) {
   let depth = 0;
   for (let k = 0; k < content.length; k++) {
@@ -167,26 +101,9 @@ function holeLeftOpen(content) {
 }
 
 /**
- * C# source with every comment, preprocessor line and string/char literal
- * blanked — newlines and length kept — or null when the file cannot be read this way:
- * - a literal or comment never ends;
- * - an interpolated `$"…"`/`$@"…"`/`@$"…"` literal is cut by a quote inside a hole
- *   (its content ends with the hole open). Blanking the part before the cut would
- *   leave the rest of the hole as "code", with braces that can cancel out.
- *
- * Raw strings (`"""…"""`, 3+ quotes, with or without `$`/`$$`) end at the same run
- * of quotes; a quote inside a raw interpolation hole is NOT checked. Verbatim `@"…"`
- * ends at a lone `"`. Regular and char literals cannot cross a line.
- *
- * This is a heuristic lexer and it CAN misread (known: `holeLeftOpen` counts the
- * braces of a char literal such as `'}'`, so `$"{(c == '}' ? "a" : "/*")}"` is cut
- * at the inner quote and `"/*"` becomes code). Nothing relies on the
- * blanking being right: csharpClasses compares the declarations it names against
- * the type keywords of the RAW text, and any declaration a misread hides makes the
- * file unscannable.
- *
- * @param {string} text
- * @returns {string|null}
+ * Comments, preprocessor lines and literals blanked, length and newlines kept; null when
+ * a literal never ends or an interpolation hole is cut. A heuristic lexer that CAN misread:
+ * csharpClasses never trusts it alone (it checks against the raw text).
  */
 export function blankCSharpLiterals(text) {
   const out = text.split('');
@@ -232,7 +149,6 @@ export function blankCSharpLiterals(text) {
   return out.join('');
 }
 
-/** Type-keyword tokens in a text (raw or blanked) — every one; no context rule (see TYPE_KEYWORD). */
 const typeKeywordCount = (text) => [...text.matchAll(TYPE_KEYWORD)].length;
 
 /**
@@ -285,7 +201,7 @@ const typeKeywordCount = (text) => [...text.matchAll(TYPE_KEYWORD)].length;
  *   or a custom one (`[SkippableFact]`) is not seen: the file counts as a helper and
  *   it is left out of a selection;
  * - `hasTestAttribute` is still a heuristic, and ITS false positive is the unsafe
- *   side. Since the re-review (N1) the section must close; what still matches in a
+ *   side. The section must close; what still matches in a
  *   helper — probed — is a LIST PATTERN opening a line (or after `;` `{` `}` `]`)
  *   whose element is named exactly `Test`/`Fact`/… (qualified or not) and whose `]`
  *   is followed by a combinator: `[Env.Test] or [Env.Dev] => true`. Such a helper is
@@ -317,10 +233,8 @@ export function csharpClasses(csFileAbs) {
   // length, so the raw text at the same offsets shows the directive.
   const split = decls.find((d) => /(^|\n)[ \t]*#/.test(text.slice(d.at - d.gap, d.at)));
   if (split) return unscannable(`a preprocessor directive stands between a type keyword and the name "${split.name}"`);
-  // THE NET (R2, tightened in round 5): the raw text is the lexer-independent
-  // truth about how many type keywords the file carries. Compare it — and the
-  // blanked code — against what was actually named (see the JSDoc for why
-  // equality of counts is equality of sets).
+  // The raw text is the lexer-independent truth about how many type keywords the file
+  // carries (the JSDoc explains why equal counts mean equal sets).
   const rawKeywords = typeKeywordCount(text);
   if (rawKeywords !== decls.length) {
     return unscannable(`${rawKeywords} type keyword(s) in the file but ${decls.length} declaration(s) recognised`);

package/src/lib/mutation/subset.js

@@ -51,10 +51,7 @@ export function testFilesCiting({ root, testProjectDirs, types, exclude = [] })
   return found.sort();
 }
 
-/**
- * The tests to run FIRST, chosen by the tool: files the feature changed, and files naming a
- * type the mutated files declare. A mutant the subset does not kill goes to the whole suite.
- */
+/** Chosen by the tool, never the verifier: test files the feature changed or that name a mutated type. */
 export function dotnetSubset({ root, testProjectDirs, mutatedFiles, changed = [] }) {
   const changedSet = new Set(changed.map(posix));
   const mention = mentionOf(mutatedTypesOf(root, mutatedFiles));

package/src/lib/plan/artifact-vocabulary.js

@@ -1,33 +1,18 @@
 /** The inline justification that lets a criterion talk about an artifact on purpose. */
 export const ARTIFACT_MARKER_RE = /por\s+que\s+artefato\s*:/i;
 
-/**
- * Case-insensitive spelling of `word` inside a regex that must stay
- * case-SENSITIVE elsewhere — Node 18 has no inline `(?i:…)` modifier.
- */
+// Node 18 has no inline `(?i:…)` modifier, and the rest of the regex must stay case-sensitive.
 const anyCase = (word) => [...word].map((c) => {
   const lo = c.toLowerCase();
   const up = c.toUpperCase();
   return lo === up ? c : `[${lo}${up}]`;
 }).join('');
 
-/**
- * What follows "arquivo em" in a behavioural export criterion ("exporta o
- * arquivo em CSV", "salva o arquivo em formato aberto"): an uppercase file
- * format acronym or the word `formato`. Case-sensitive on purpose — `src`,
- * `docs` or `lib` after "arquivo em" are places, and places are artifacts.
- */
+// Case-sensitive on purpose: `src`, `docs` or `lib` after "arquivo em" are places, and places are artifacts.
 const FORMAT_TOKEN = String.raw`\s+(?:[A-Z]{2,5}(?![\p{L}\d_])|${anyCase('formato')}(?![\p{L}]))`;
 
-/**
- * Vocabulary of artifact-shaped phrasing. `term` is the label surfaced in
- * warnings and cited by the `morph-plan` skill prose — keep it stable, a
- * parity test imports it verbatim.
- *
- * Unicode lookarounds, never `\b`: in JS, `\b` does not treat accented
- * letters (é, á, ó…) as word characters, so it would false-boundary inside
- * "não" or "binário".
- */
+// `term` is cited verbatim by the `morph-plan` skill (a parity test imports it): keep it stable.
+// Unicode lookarounds, never `\b`: JS `\b` false-boundaries inside "não" or "binário".
 export const ARTIFACT_VOCABULARY = [
   { term: 'grep',                        re: /(?<![\p{L}\d_])grep(?![\p{L}\d_])/iu },
   { term: 'contém a string',             re: /cont[ée]m\s+as?\s+strings?/iu },
@@ -44,12 +29,7 @@ export const ARTIFACT_VOCABULARY = [
   { term: 'glob **/',                    re: /\*\*\/|\/\*\*/ },
 ];
 
-/**
- * Vocabulary terms matched in `text`, in vocabulary order, each at most once.
- *
- * @param {string} text
- * @returns {string[]}
- */
+/** Each term at most once, in vocabulary order. */
 export function findArtifactTerms(text) {
   const s = String(text ?? '');
   const found = [];

package/src/lib/plan/checks.js

@@ -11,17 +11,12 @@ export const MAX_SLICE_FILES = 8;
 export const MAX_SLICES = 12;
 export const MAX_PARALLEL = 4;
 
-/** sha256 of the plan without its errata: appending a correction never invalidates checks.json. */
+/** sha256 of the plan without its errata: appending a correction never invalidates the extracted checks. */
 export function planHash(text) {
   return createHash('sha256').update(frozenBody(text), 'utf8').digest('hex');
 }
 
-/**
- * Persona ids the project can dispatch: the installed agents.json, else the package's.
- *
- * @param {string} cwd
- * @returns {string[]|null} null when no agents.json is readable — personas then go unchecked
- */
+/** The installed agents.json, else the package's; null when unreadable (personas then go unchecked). */
 export function knownPersonas(cwd) {
   const agents = readAgentsJson(cwd)?.agents;
   return agents && typeof agents === 'object' ? Object.keys(agents) : null;
@@ -54,14 +49,8 @@ export function dependencyCycle(slices) {
 
 const fileKey = (f) => f.replace(/\\/g, '/').replace(/^\.\//, '').toLowerCase();
 
-/**
- * Waves of slices that may run at the same time: a slice joins a wave only
- * after every slice it depends on ran in an earlier one, and never with a
- * slice that touches one of its files. At most MAX_PARALLEL per wave.
- *
- * @param {{ id: string, depends?: string[], files?: string[] }[]} slices
- * @returns {string[][]} empty when the dependencies have a cycle
- */
+// A slice joins a wave only after its dependencies ran, never with one touching its files, and at most
+// MAX_PARALLEL per wave. Empty on a dependency cycle.
 export function parallelGroups(slices) {
   if (dependencyCycle(slices)) return [];
   const ids = new Set(slices.map((s) => s.id));
@@ -94,13 +83,6 @@ export function parallelGroups(slices) {
   return groups;
 }
 
-/**
- * Judge a parsed plan.
- *
- * @param {ReturnType<import('./plan-parser.js').parsePlan>} plan
- * @param {{ personas?: string[]|null, surfaces?: string[]|null }} [known]
- * @returns {{ errors: string[], warnings: string[] }}
- */
 export function validatePlan(plan, { personas = null, surfaces = null } = {}) {
   const errors = [];
   const warnings = [];
@@ -184,7 +166,6 @@ export function validatePlan(plan, { personas = null, surfaces = null } = {}) {
   return { errors, warnings };
 }
 
-/** The checks.json document for a parsed plan. */
 export function buildChecks(feature, text, plan) {
   return {
     version: CHECKS_VERSION,
@@ -202,14 +183,7 @@ export function buildChecks(feature, text, plan) {
   };
 }
 
-/**
- * The feature's extracted checks and whether they still describe the plan on
- * disk. plan-check writes them only with zero errors, so `fresh` also means
- * the plan passed every plan-check rule (no slice over MAX_SLICE_FILES, every
- * scenario covered).
- *
- * @returns {{ status: 'fresh'|'no-plan'|'no-checks'|'unreadable'|'stale', checks: object|null }}
- */
+/** plan-check writes the checks only with zero errors, so `fresh` also means the plan passed every rule. */
 export function readPlanChecks(cwd, featureName) {
   const planPath = getAbsoluteOutputPath(cwd, featureName, 'plan');
   const checksPath = getAbsoluteOutputPath(cwd, featureName, 'checks');

package/src/lib/plan/plan-parser.js

@@ -175,12 +175,7 @@ function parseSlices(lines) {
   return slices;
 }
 
-/**
- * Parse `2-plan/plan.md` into its structure. Pure: no validation, no I/O —
- * `checks.js` judges what this returns.
- *
- * @param {string} text
- */
+/** Pure: no validation, no I/O; `checks.js` judges what this returns. */
 export function parsePlan(text) {
   const lines = markdownLines(text);
   const sections = splitSections(lines);

package/src/lib/projects/registry.js

@@ -1,19 +1,5 @@
-/**
- * Where the morph-spec projects on this machine are — the list the dashboard's
- * portfolio reads. Nothing else records it: each project only knows its own
- * `.morph/`.
- *
- * Three writers register a project as a side note of what they already do —
- * `init`, `update` (never under `--dry-run`) and `dashboard` — and the
- * dashboard adds and removes on request. Registering is fail-open: a registry
- * that cannot be read or written never fails the command that tried.
- *
- * The file lives in the user's home (`~/.morph-spec/projects.json`, or
- * `MORPH_PROJECTS_REGISTRY`), read through `os.homedir()` at call time so a
- * suite that isolates the home also isolates this file. Paths under the
- * system temp dir are never registered: the test suites run `init`/`update`
- * there by the hundred, including through spawned CLIs that keep the real home.
- */
+// Paths under the system temp dir are never registered: test suites run `init`/`update` there by the
+// hundred, through spawned CLIs that keep the real home. The home is read at call time so isolating it works.
 
 import { existsSync, readFileSync, readdirSync } from 'fs';
 import { homedir, tmpdir } from 'os';
@@ -35,7 +21,6 @@ export function projectKey(dir) {
 
 const sameDir = (a, b) => (process.platform === 'win32' ? a.toLowerCase() === b.toLowerCase() : a === b);
 
-/** A folder is a morph-spec project when morph-spec installed its config there. */
 export function isMorphProject(dir) {
   return existsSync(join(dir, '.morph', 'config', 'config.json'));
 }
@@ -61,18 +46,13 @@ function projectName(dir) {
   }
 }
 
-/**
- * The registered projects that still exist. A folder that was deleted or lost
- * its `.morph/` drops out on read — the file is rewritten on the next write.
- *
- * @returns {{ version: number, projects: Array<{ dir: string, name: string, addedAt: string, lastSeenAt: string, source: string }> }}
- */
+/** Folders that were deleted or lost `.morph/` drop out on read. */
 export function readRegistry() {
   let data = null;
   try {
     const path = registryPath();
     if (existsSync(path)) data = JSON.parse(readFileSync(path, 'utf8'));
-  } catch { /* unreadable registry reads as empty */ }
+  } catch {}
   const projects = Array.isArray(data?.projects) ? data.projects : [];
   return {
     version: REGISTRY_VERSION,
@@ -84,16 +64,7 @@ function write(projects) {
   atomicWriteJson(registryPath(), { version: REGISTRY_VERSION, projects });
 }
 
-/**
- * Note that `dir` is a morph-spec project. Idempotent; refreshes `lastSeenAt`.
- * Never throws.
- *
- * @param {string} dir
- * @param {'init'|'update'|'dashboard'|'manual'} source
- * @param {{ tempRoot?: string }} [opts] - test seam: the folder whose
- *   projects are never registered (the system temp dir)
- * @returns {boolean} true when the project is in the registry afterwards
- */
+/** Idempotent, never throws; `tempRoot` is the test seam for the never-registered folder. */
 export function registerProject(dir, source, { tempRoot = tmpdir() } = {}) {
   try {
     const key = projectKey(dir);
@@ -115,7 +86,7 @@ export function registerProject(dir, source, { tempRoot = tmpdir() } = {}) {
   }
 }
 
-/** Take a project off the list. Its files are not touched. Never throws. */
+/** Never throws; the project's files are not touched. */
 export function unregisterProject(dir) {
   try {
     const key = projectKey(dir);
@@ -128,15 +99,7 @@ export function unregisterProject(dir) {
   }
 }
 
-/**
- * morph-spec projects directly under each root that are not registered yet —
- * the portfolio offers them, the person decides. One level deep: a repos
- * folder is the expected root, and a deeper walk would enter node_modules and
- * worktrees for nothing.
- *
- * @param {string[]} roots
- * @returns {Array<{ dir: string, name: string }>}
- */
+/** Unregistered projects one level under each root: deeper would walk node_modules and worktrees. */
 export function discoverProjects(roots) {
   const registered = readRegistry().projects.map((p) => p.dir);
   const out = [];

package/src/lib/review-reports.js

@@ -60,7 +60,7 @@ function tableRows(body) {
   return rows;
 }
 
-/** `| id | tipo | onde | evidência |`; `untyped` = tipo fora de {@link BLOCKER_TYPES}. */
+// `| id | tipo | onde | evidência |`; `untyped` = tipo fora de BLOCKER_TYPES.
 function parseBlockers(body) {
   const blockers = [];
   const untyped = [];
@@ -74,10 +74,7 @@ function parseBlockers(body) {
 
 const STATUS_BY_KEY = Object.fromEntries(CHECK_STATUSES.map((s) => [normalize(s), s]));
 
-/**
- * `| Cn | PROVADO|NÃO PROVADO|FALHA | evidência |` de TODAS as seções: uma confirmação
- * traz só os Cn que mudou, então vale a última linha de cada Cn. Status por igualdade exata.
- */
+// Vale a última linha de cada Cn em todas as seções: uma confirmação traz só os Cn que mudou.
 function parseChecks(bodies) {
   const byId = new Map();
   for (const cells of bodies.flatMap(tableRows)) {
@@ -110,10 +107,7 @@ export function parseReviewReport(text) {
   };
 }
 
-/**
- * `missing`: sem arquivo. `partial`: `PARCIAL` na 1ª linha, com ou sem veredito.
- * `unverdicted`: sem `**Verdict:** SHIP|FIX`. `ok`: legível — quem decide é o risk-detector.
- */
+// `partial`: `PARCIAL` na 1ª linha, com ou sem veredito. `ok` só diz legível: quem decide é o risk-detector.
 function stateOf(path, text) {
   if (text === null) return { status: 'missing', path };
   const parsed = parseReviewReport(text);
@@ -148,13 +142,7 @@ export function reviewReports(cwd, featureName) {
   return reviewReportsFromDir(join(cwd, '.morph', 'features', featureName));
 }
 
-/**
- * Todo Cn precisa de uma linha, e só `PROVADO` cobre.
- *
- * @param {string[]} checkIds
- * @param {{id: string, status: string}[]|null} rows - `parseReviewReport(...).checks`
- * @returns {{ missing: string[], notProven: {id: string, status: string}[] }}
- */
+/** Todo Cn precisa de uma linha, e só `PROVADO` cobre. */
 export function checksCoverage(checkIds, rows) {
   const byId = new Map((rows ?? []).map((r) => [r.id, r]));
   const missing = [];
@@ -167,12 +155,7 @@ export function checksCoverage(checkIds, rows) {
   return { missing, notProven };
 }
 
-/**
- * O sinal que `reviewPause` (risk-detector) lê; `checkIds: null` = cobertura não conferível.
- *
- * @param {ReturnType<typeof reviewReportsFromDir>} reports
- * @param {{ required: string[], checkIds: string[]|null }} opts
- */
+/** O sinal que `reviewPause` lê; `checkIds: null` = cobertura não conferível. */
 export function reviewSignal(reports, { required, checkIds }) {
   const out = { required, reports: {} };
   for (const role of ROLE_ORDER) {
@@ -205,7 +188,6 @@ export function combinedVerdict(reports, required) {
   return required.every((r) => reports[r].status === 'ok' && reports[r].verdict === 'SHIP') ? 'SHIP' : null;
 }
 
-/** Todos os bloqueadores tipados dos relatórios presentes, com o papel que os abriu. */
 export function allBlockers(reports) {
   return ROLE_ORDER.flatMap((role) => (reports[role].blockers ?? []).map((b) => ({ ...b, role })));
 }