@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/framework/hooks/shared/comment-stripper.js

@@ -1,55 +1,10 @@
-/**
- * comment-stripper.js — apagar comentários SEM apagar o que está dentro de uma
- * string, preservando comprimento e quebras de linha.
- *
- * Existe uma vez só, e serve a consumidores que fariam a MESMA coisa de
- * jeitos ligeiramente diferentes se cada um escrevesse o seu:
- *
- *   - `code-audit.js` — não pode acusar `AgentThread` que só aparece num
- *     comentário ou numa mensagem de log;
- *   - `registry-audit.js` — precisa ler **JSONC**, a forma que o exemplar
- *     canônico `model-registry.v2.json` usa e que o leitor C# do kit aceita de
- *     propósito (`JsonCommentHandling.Skip`, `AllowTrailingCommas`);
- *   - `dotnet-test-introspection.js` — lê o `global.json` por `jsoncToJson`;
- *   - `comment-scanner.js` (ao lado; lido pelo `code-budget` e pelo hook
- *     `comment-guard`) — acha as linhas de
- *     comentário de `.cs`/`.ts`/`.js`, e é o único que liga a opção `js`.
- *
- * **Por que não um regex.** O exemplar tem `"http://localhost:11434/v1"` e uma
- * `provenance` com URL. Um `replace(/\/\/.*$/gm, '')` decapitaria as duas —
- * apagando dado e chamando isso de comentário. Um varredor que atravessa as
- * strings primeiro é a única forma correta, e é o que está aqui.
- *
- * O comprimento é preservado (os removidos viram espaço, `\n` e `\r` ficam) para
- * que índices e números de linha do texto original continuem válidos no texto
- * limpo. É o que permite `code-audit.js` reportar `arquivo.cs:34` sem um segundo
- * mapeamento.
- */
+// Atravessa as strings antes: um regex apagaria o `//` de `"http://localhost"`.
+// O comprimento é preservado para índices e números de linha continuarem válidos.
 
 /**
- * @param {string} text
- * @param {object} [options]
- * @param {boolean} [options.blankStrings=false]
- *   Apaga também o CONTEÚDO das strings. **As aspas delimitadoras ficam.**
- *
- *   Apagá-las junto era um defeito com consequência: um elemento-string virava
- *   espaço puro, e o detector de vírgula sobrando de `jsoncToJson` passava a
- *   enxergar `[  ,  ,  ]` — separadores REAIS entre delimitadores que sumiram —
- *   e apagava uma vírgula que era sintaxe. Medido: `{"tags":["a","b"]}` saía
- *   `{"tags":["a","b" ]}`, JSON inválido, e o registry voltava a ser
- *   `○ não verificado`. O B1 reintroduzido pela correção do B1.
- * @param {{ unterminated?: string|null }} [options.report]
- *   Se um objeto for passado, recebe `unterminated` = `'block-comment'`,
- *   `'string'`, `'verbatim-string'`, `'raw-string'`, `'template'` ou `null`. É o canal de
- *   diagnóstico que `jsoncToJson` usa para ficar tão estrito quanto o leitor
- *   de produção, sem que este lexer precise lançar (ele também varre `.cs`,
- *   onde um comentário aberto é problema do arquivo, não da varredura).
- * @param {boolean} [options.js=false]
- *   Lê também template literal e regex literal de TS/JS. Opt-in porque só
- *   quem varre `.ts`/`.js` precisa: sem template, `https://${h}` vira
- *   comentário; sem regex, uma crase dentro de `/[`']/` abre um template que
- *   engole o resto do arquivo.
- * @returns {string} texto do MESMO comprimento
+ * `blankStrings` apaga o conteúdo das strings, mas as ASPAS FICAM: sem elas um
+ * separador real vira vírgula sobrando. `report.unterminated` recebe o literal não
+ * fechado; `js` lê template e regex literal, sem os quais `https://${h}` vira comentário.
  */
 export function stripComments(text, { blankStrings = false, report = null, js = false } = {}) {
   const out = text.split('');
@@ -95,7 +50,7 @@ export function stripComments(text, { blankStrings = false, report = null, js =
       if (end !== -1) { i = end; continue; }
     }
 
-    // Raw string literal do C#: """ ... """ — delimitadores de 3 aspas.
+    // C# raw string literal
     if (c === '"' && next === '"' && text[i + 2] === '"') {
       const end = text.indexOf('"""', i + 3);
       if (end === -1) flag('raw-string');
@@ -105,7 +60,7 @@ export function stripComments(text, { blankStrings = false, report = null, js =
       continue;
     }
 
-    // Verbatim string do C#: @"..." — aspas duplicadas escapam
+    // C# verbatim string: doubled quotes escape
     if (c === '@' && next === '"') {
       let j = i + 2;
       let closed = false;
@@ -159,7 +114,6 @@ export function stripComments(text, { blankStrings = false, report = null, js =
   return out.join('');
 }
 
-/** Índice logo após a crase que fecha o template aberto em `start`, ou -1. */
 function templateEnd(text, start) {
   let j = start + 1;
   while (j < text.length) {
@@ -176,11 +130,7 @@ const REGEX_AFTER_WORD = new Set([
   'throw', 'instanceof', 'yield', 'await',
 ]);
 
-/**
- * Uma `/` abre regex, e não divisão, quando o que vem antes não é um valor: o
- * mesmo critério de contexto dos tokenizers de JS. `out` já tem os comentários
- * apagados, então o caractere anterior é código. Sem `<`: em TSX, `</b>` é tag.
- */
+// `/` abre regex quando o que vem antes não é um valor. Sem `<`: em TSX, `</b>` é tag.
 function regexMayStart(out, i) {
   let k = i - 1;
   while (k >= 0 && /\s/.test(out[k])) k--;
@@ -192,7 +142,6 @@ function regexMayStart(out, i) {
   return REGEX_AFTER_WORD.has(out.slice(w, k + 1).join(''));
 }
 
-/** Índice logo após a `/` (e as flags) que fecha a regex aberta em `start`, ou -1 se a linha acaba antes. */
 function regexEnd(text, start) {
   let inClass = false;
   for (let j = start + 1; j < text.length; j++) {
@@ -210,7 +159,6 @@ function regexEnd(text, start) {
   return -1;
 }
 
-/** Índice logo após o `}` que fecha um `${`: o código do buraco aninha chaves, strings e templates. */
 function holeEnd(text, start) {
   let depth = 1;
   let j = start;
@@ -235,31 +183,9 @@ function holeEnd(text, start) {
   return text.length;
 }
 
-/**
- * Converte JSONC em JSON: apaga comentários e vírgulas sobrando antes de `}`/`]`.
- *
- * As duas tolerâncias são **exatamente** as que `ModelRegistry.FromJson` do
- * ai-kit declara (`CommentHandling = Skip`, `AllowTrailingCommas = true`). A
- * ferramenta que audita o registry tem de enxergar a mesma forma que o leitor
- * de produção enxerga — senão o framework passa a recomendar uma forma que a
- * sua própria auditoria não lê, e as checagens ficam inertes em silêncio.
- *
- * A vírgula sobrando é localizada num texto onde o conteúdo das strings também
- * foi apagado — **com as aspas preservadas**, senão um elemento-string vira
- * espaço puro e um separador REAL passa por vírgula sobrando (o defeito B4) —
- * e só então removida do texto real: uma vírgula dentro de `"a,}"` é dado.
- *
- * **Um comentário de bloco não fechado LANÇA**, e a razão é a mesma que fez
- * esta função existir: paridade com o leitor de produção. `JsonCommentHandling.Skip`
- * do .NET lança nesse caso, e ser mais frouxo que o kit é o defeito INVERSO do
- * B1 — auditar, e aprovar, um documento que a aplicação recusa carregar.
- * `readJsonSafe` captura e devolve `null`, que o relatório traduz em
- * "não verificado" com razão.
- *
- * @param {string} raw
- * @returns {string} JSON estrito, do mesmo comprimento do original
- * @throws {SyntaxError} comentário de bloco aberto e nunca fechado
- */
+// Paridade com `ModelRegistry.FromJson` do ai-kit, nos dois sentidos: comentário de
+// bloco não fechado LANÇA, como `JsonCommentHandling.Skip`, porque ser mais frouxo
+// que o kit é aprovar um documento que a aplicação recusa carregar.
 export function jsoncToJson(raw) {
   const report = {};
   const noComments = stripComments(raw, { report }).split('');

package/framework/hooks/shared/errata.js

@@ -0,0 +1,59 @@
+export const ERRATA_HEADING = '## Errata';
+
+/** The one normalization every reader of a frozen markdown applies. */
+export function normalizeMarkdown(text) {
+  return String(text ?? '').replace(/^/, '').replace(/\r\n?/g, '\n');
+}
+
+export function markdownLines(text) {
+  const out = [];
+  let fence = null;
+  normalizeMarkdown(text).split('\n').forEach((raw, i) => {
+    const opener = /^\s*(`{3,}|~{3,})/.exec(raw);
+    let fenced = Boolean(fence);
+    if (fence) {
+      if (opener && opener[1][0] === fence[0] && opener[1].length >= fence.length) fence = null;
+    } else if (opener) {
+      fence = opener[1];
+      fenced = true;
+    }
+    out.push({ raw, n: i + 1, fenced });
+  });
+  return out;
+}
+
+const isErrataHeading = (line) => !line.fenced
+  && /^##\s+errata\s*$/i.test(line.raw);
+
+/** Offset in the NORMALIZED text, or -1. */
+export function errataOffset(text) {
+  let offset = 0;
+  for (const line of markdownLines(text)) {
+    if (isErrataHeading(line)) return offset;
+    offset += line.raw.length + 1;
+  }
+  return -1;
+}
+
+export function frozenBody(text) {
+  const norm = normalizeMarkdown(text);
+  const at = errataOffset(norm);
+  return (at === -1 ? norm : norm.slice(0, at)).trimEnd();
+}
+
+export function errataViolation(original, proposed) {
+  if (frozenBody(proposed) !== frozenBody(original)) {
+    return { ok: false, why: 'o corpo aprovado mudou — errata só ACRESCENTA ao fim, nunca altera o texto aprovado' };
+  }
+  const next = normalizeMarkdown(proposed);
+  const nextAt = errataOffset(next);
+  if (nextAt === -1) {
+    return { ok: false, why: `o conteúdo novo precisa estar sob um bloco \`${ERRATA_HEADING}\` no fim do arquivo` };
+  }
+  const prev = normalizeMarkdown(original);
+  const prevAt = errataOffset(prev);
+  if (prevAt !== -1 && !next.slice(nextAt).startsWith(prev.slice(prevAt).trimEnd())) {
+    return { ok: false, why: 'a errata existente foi reescrita — ela é append-only, entradas anteriores não se apagam' };
+  }
+  return { ok: true };
+}

package/framework/hooks/shared/feature-locator.js

@@ -1,41 +1,11 @@
-/**
- * Locate which tree owns a feature, and which feature a gate question is about.
- *
- * `resolveMorphRoot` (payload-utils) answers this from a file path. Some hook
- * events carry no path at all — an `AskUserQuestion` gate approval is the one
- * that matters — and those were resolved by "the first in_progress feature of
- * whatever tree the session happens to sit in". That is how a Gate 2 approval
- * for one feature landed on `export-hub`, an unrelated feature that merely
- * happened to be active in the primary root.
- *
- * The honest signal for a pathless event is the question text itself: every
- * gate template in the core skills names its feature — "Gate 1 — Proposta de
- * {feature} aprovada?", "Gate 2 — Plano de {feature} aprovado?", "Gate 3 —
- * Review de {feature} aprovado?", "Gate 3 — Hotfix de {feature} pronto para
- * ship?". Rather than parse those sentences (which would break the moment a
- * template is reworded), match the question against the set of feature slugs
- * that actually exist on disk.
- *
- * When the text names no known feature, the caller must REFUSE TO GUESS.
- * Stamping a gate onto the wrong feature is close to unrecoverable — it inverts
- * gate order and invites a second stamp on the real owner; writing nothing
- * costs one `morph-spec approve`.
- *
- * Fail-open by contract: every function swallows errors and returns an empty
- * result rather than throwing.
- */
+// A pathless gate question is matched against the slugs on disk, never parsed.
+// When it names no known feature the caller must REFUSE TO GUESS: a gate on the
+// wrong feature is close to unrecoverable, writing nothing costs one `approve`.
 
 import { execSync } from 'child_process';
 import { loadState } from './state-reader.js';
 
-/**
- * Feature slugs known to `root`.
- *
- * Deliberately `loadState` and not a `readdirSync` of `.morph/features/`: state
- * lives in BOTH shapes — the thin `.morph/state.json` index and the per-feature
- * `feature.json` — and `loadState` is the one place that already merges them.
- * Listing directories alone misses every feature carried only by the index.
- */
+// `loadState`, not a directory listing: it also sees features only the index carries.
 export function featureNamesIn(root) {
   try {
     const state = loadState(root);
@@ -45,11 +15,6 @@ export function featureNamesIn(root) {
   }
 }
 
-/**
- * Every working tree of this repo — the primary root plus every registered
- * secondary worktree. Fail-open to `[sessionRoot]` when git is unavailable or
- * the directory is not a repo.
- */
 export function allWorkTrees(sessionRoot) {
   const roots = [sessionRoot];
   try {
@@ -64,26 +29,14 @@ export function allWorkTrees(sessionRoot) {
       if (path && !roots.includes(path)) roots.push(path);
     }
   } catch {
-    /* fail-open — the session root alone */
   }
   return roots;
 }
 
 const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 
-/**
- * The single feature slug named in `text`, or null.
- *
- * Slug boundaries are `[^a-z0-9-]` so a longer name never matches inside a
- * shorter one (`export` must not match the text "export-hub"). Zero matches
- * means the text named nothing; two or more means it named two features and is
- * ambiguous. Both are null — "I don't know" and "it's ambiguous" must lead to
- * the same refusal, not to a coin flip.
- *
- * @param {string} text
- * @param {string[]} names - candidate slugs
- * @returns {string|null}
- */
+// `export` must not match inside "export-hub". Zero and ambiguous matches are
+// both null: they must lead to the same refusal.
 export function featureNamedIn(text, names) {
   if (typeof text !== 'string' || !Array.isArray(names) || names.length === 0) return null;
   const haystack = text.toLowerCase();
@@ -93,28 +46,8 @@ export function featureNamedIn(text, names) {
   return hits.length === 1 ? hits[0] : null;
 }
 
-/**
- * A token in `text` shaped like a feature slug (kebab-case, at least one
- * hyphen — `morph-spec create`'s naming convention) that names none of
- * `names`. Signals "the text is talking about a specific feature I don't
- * know" as opposed to "the text names nothing in particular".
- *
- * This is what the single-feature fallback below was missing: a gate question
- * for a feature not yet registered (no `create`, no `proposal.md` written
- * yet — a fresh hotfix, say) names NO known feature either, and used to fall
- * through to "the tree's one feature must be it". That is exactly how a Gate 3
- * for `backfill-bool-filter` landed on `export-hub`, the tree's only
- * registered feature at the time.
- *
- * Deliberately narrow (requires a hyphen) to match real feature slugs
- * (`export-hub`, `backfill-bool-filter`) without flagging ordinary prose —
- * the fixed portions of every gate template ("Proposta", "aprovado", "Sinal",
- * "pronto para ship"...) are single words with no internal hyphen.
- *
- * @param {string} text
- * @param {string[]} names - every feature slug known across all trees
- * @returns {string|null}
- */
+// A slug-shaped token naming no known feature: the question is about a feature
+// not yet registered. Requires a hyphen, so template prose never matches.
 export function unrecognizedSlugLike(text, names) {
   if (typeof text !== 'string') return null;
   const known = new Set((names || []).map((n) => String(n).toLowerCase()));
@@ -122,17 +55,8 @@ export function unrecognizedSlugLike(text, names) {
   return tokens.find((t) => !known.has(t)) ?? null;
 }
 
-/**
- * Resolve a gate question to `{ name, root }`.
- *
- * The session root is consulted first so the common case costs no git call, and
- * so a feature present in BOTH trees resolves to the tree the session is
- * actually in — the same tree `morph-spec approve` would write from that cwd.
- * Only when the session root knows no such feature do we pay for enumerating
- * the worktrees.
- *
- * @returns {{name: string, root: string}|null} null ⇒ caller must not guess
- */
+// The session root wins a feature present in both trees: it is where
+// `morph-spec approve` would write from that cwd.
 export function locateFeatureForQuestion(text, sessionRoot) {
   const trees = allWorkTrees(sessionRoot);
   const localNames = featureNamesIn(sessionRoot);
@@ -146,18 +70,10 @@ export function locateFeatureForQuestion(text, sessionRoot) {
     if (found) return { name: found, root };
   }
 
-  // The text names a specific feature none of the trees know — refuse rather
-  // than guess it meant the tree's one registered feature (see
-  // `unrecognizedSlugLike` above).
   const allNames = trees.flatMap(featureNamesIn);
   if (unrecognizedSlugLike(text, allNames)) return null;
 
-  // Unambiguous fallback: the session's tree holds exactly ONE feature, so
-  // there is no other feature the answer could have been about. This is the
-  // single-feature project — the common case — and refusing there would break
-  // gate questions phrased without a name ("Gate 1 — Proposta aprovada?").
-  // With two or more features the fallback is exactly the guess that put a
-  // Gate 2 on `export-hub`, so it stops here.
+  // With exactly ONE feature in the tree there is nothing else the answer could be about.
   if (localNames.length === 1) return { name: localNames[0], root: sessionRoot };
 
   return null;

package/framework/hooks/shared/frontend-locations.js

@@ -0,0 +1,4 @@
+// `src/lib/detectors` re-exports this list, because a hook cannot import `src/`.
+export const PACKAGE_LOCATIONS = ['.', 'src/frontend', 'src/web', 'frontend', 'apps/web', 'packages/app'];
+
+export const E2E_SPEC_LOCATIONS = [...PACKAGE_LOCATIONS, 'web'];

package/framework/hooks/shared/gate-question.js

@@ -0,0 +1,12 @@
+/** Explicit gate names win over words a feature slug may also carry ("plan", "design", "review"). */
+export function gateFromQuestion(question) {
+  if (typeof question !== 'string') return null;
+  if (/gate\s+uiux/i.test(question)) return 'uiux';
+  if (/gate\s+3\b/i.test(question)) return 'review';
+  if (/gate\s+(?:[12]\b|d[oe]\s+plano|plan\b)/i.test(question)) return 'plan';
+  const lower = question.toLowerCase();
+  if (lower.includes('plano') || lower.includes('plan')) return 'plan';
+  if (lower.includes('design')) return 'uiux';
+  if (lower.includes('review') || lower.includes('ship')) return 'review';
+  return null;
+}

package/framework/hooks/shared/git-exclude.js

@@ -1,31 +1,14 @@
-/**
- * git-exclude.js — o escritor ÚNICO dos blocos que o morph-spec mantém no
- * `info/exclude` do git.
- *
- * O arquivo lido é o do COMMON dir (`git rev-parse --git-common-dir`), nunca o
- * `.git/worktrees/<id>/info/exclude`: o git não lê o deste para uma worktree
- * vinculada, e o do common dir vale para toda árvore do repositório — inclusive
- * a raiz primária. Cada chamador passa o seu marcador, e o bloco só ganha as
- * linhas que ainda faltam.
- *
- * Idempotente e fail-open: um exclude que não pôde ser escrito custa um
- * arquivo aparecendo como `??`, nunca um erro.
- */
+// O exclude do COMMON dir: o git não lê `.git/worktrees/<id>/info/exclude` para
+// uma worktree vinculada. Fail-open: falhar custa um `??`, nunca um erro.
 
 import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { resolveGitCommonDir } from './git-paths.js';
 
-/**
- * @param {string} cwd - qualquer diretório dentro do repositório
- * @param {string[]} patterns - linhas prontas (já ancoradas, ex. `/graphify-out`)
- * @param {string} marker - comentário que identifica o bloco do chamador
- */
 export function ensureCommonExclude(cwd, patterns, marker) {
   if (!patterns.length) return;
   try {
-    // Pelo disco, sem subprocesso: um `git` gerado aqui abria uma janela de
-    // console no win32 quando o chamador era um processo destacado.
+    // Pelo disco: um `git` gerado por um processo destacado abre console no win32.
     const common = resolveGitCommonDir(cwd);
     if (!common) return;
     const infoDir = join(common, 'info');

package/framework/hooks/shared/git-paths.js

@@ -1,47 +1,10 @@
-/**
- * git-paths.js — pure-filesystem git common-dir resolution (no subprocess).
- *
- * `telemetry-log.js`'s claim heartbeat used to pay `execSync('git rev-parse
- * --git-common-dir')` on every tool call to learn where `claims.json` lives —
- * a ~34ms subprocess spawn, wasted on ~99% of calls because the heartbeat
- * write itself is throttled (see `claim-registry.js`'s `shouldHeartbeat`).
- * This module answers the SAME question — mirroring `git rev-parse
- * --git-common-dir` — by reading the two on-disk shapes git itself uses,
- * without spawning `git` at all:
- *
- *   1. PRIMARY checkout: `<root>/.git` is a DIRECTORY. That directory IS the
- *      common dir. (A directory `.git` is never a linked worktree's own —
- *      git always represents a worktree's `.git` as a FILE — so this case is
- *      unambiguous.)
- *   2. LINKED WORKTREE (`git worktree add`): `<root>/.git` is a FILE
- *      containing `gitdir: <path>`, pointing at this worktree's PRIVATE
- *      gitdir (normally `<primary>/.git/worktrees/<name>`). Inside that
- *      private gitdir, a `commondir` file holds a path — relative to the
- *      private gitdir, or absolute — to the real common dir (normally
- *      `../..`, i.e. back up to `<primary>/.git`).
- *
- * Verified against a real `git worktree add` fixture: `commondir` held
- * `../..`, `.git`'s `gitdir:` line held an absolute path, and the resolved
- * result matched `git rev-parse --git-common-dir` exactly (see
- * `test/hooks/git-paths.test.js`, which asserts that parity directly rather
- * than against a hand-computed path).
- *
- * Fail-open: any missing file, unreadable path, or shape that doesn't match
- * either case above resolves to `null`. Callers must treat `null` as "not
- * resolvable right now" and skip whatever git-dependent step they were
- * guarding — never throw.
- */
+// Answers `git rev-parse` questions from the on-disk shapes git uses, without spawning git:
+// a primary checkout's `.git` is a DIRECTORY, a linked worktree's is a FILE holding `gitdir:`.
+// Every unreadable or unknown shape resolves to `null`, never a throw.
 
 import { readFileSync, statSync } from 'fs';
 import { dirname, isAbsolute, join, resolve } from 'path';
 
-/**
- * Find the nearest `.git` entry (file or directory) at or above `startDir`,
- * climbing exactly like git itself does to find the repo root.
- *
- * @param {string} startDir
- * @returns {{ path: string, isDirectory: boolean }|null}
- */
 function findDotGit(startDir) {
   let dir = resolve(startDir);
   for (;;) {
@@ -50,21 +13,13 @@ function findDotGit(startDir) {
       const st = statSync(candidate);
       return { path: candidate, isDirectory: st.isDirectory() };
     } catch {
-      // not here — keep climbing
     }
     const parent = dirname(dir);
-    if (parent === dir) return null; // reached the filesystem root
+    if (parent === dir) return null;
     dir = parent;
   }
 }
 
-/**
- * A linked worktree's `.git` FILE holds `gitdir: <path>` (absolute or relative
- * to the file) pointing at its private gitdir. `null` when the line is absent.
- *
- * @param {string} dotGitFile
- * @returns {string|null}
- */
 function privateGitDirOf(dotGitFile) {
   const match = readFileSync(dotGitFile, 'utf8').match(/^gitdir:\s*(.+?)\s*$/m);
   if (!match) return null;
@@ -73,15 +28,7 @@ function privateGitDirOf(dotGitFile) {
 
 const MORPH_BRANCH = /^ref:\s*refs\/heads\/morph\/([A-Za-z0-9._-]+)\s*$/;
 
-/**
- * The feature a checkout is bound to by its branch `morph/<feature>`, read from
- * `<root>/.git` exactly (no climbing) — the primary's `.git/HEAD` or, for a
- * linked worktree, `<gitdir>/HEAD`. `null` for any other branch (`morph-task/*`
- * included), a detached HEAD, or no `.git` at `root`.
- *
- * @param {string} root
- * @returns {string|null}
- */
+/** Reads `<root>/.git` exactly, without climbing; `null` for any branch other than `morph/<feature>`. */
 export function morphBranchFeature(root) {
   try {
     const dotGit = join(root, '.git');
@@ -94,22 +41,7 @@ export function morphBranchFeature(root) {
   }
 }
 
-/**
- * Is `startDir` inside a LINKED (secondary) worktree?
- *
- * Same on-disk fact `resolveGitCommonDir` reads: git represents a linked
- * worktree's `.git` as a FILE holding a `gitdir:` pointer, and a primary
- * checkout's `.git` as a DIRECTORY. The e2e isolation rule keys on this —
- * a compose that cannot be isolated is a hard failure only where a second
- * stack could actually collide with the primary's (see e2e-check.js
- * `decideIsolation`).
- *
- * Fail-open: outside any repo, or on an unreadable path, answers `false` —
- * the lenient direction (warn instead of fail).
- *
- * @param {string} startDir
- * @returns {boolean}
- */
+/** Outside any repo or on an unreadable path, answers `false`: the lenient direction for e2e isolation. */
 export function isSecondaryWorktree(startDir) {
   try {
     const found = findDotGit(startDir);
@@ -119,14 +51,6 @@ export function isSecondaryWorktree(startDir) {
   }
 }
 
-/**
- * Top of the working tree that contains `startDir` — the directory holding the
- * nearest `.git` (file or directory), which is what `git rev-parse
- * --show-toplevel` answers, without the subprocess. `null` outside any repo.
- *
- * @param {string} startDir
- * @returns {string|null}
- */
 export function workTreeTop(startDir) {
   try {
     const found = findDotGit(startDir);
@@ -136,16 +60,7 @@ export function workTreeTop(startDir) {
   }
 }
 
-/**
- * Resolve the git COMMON dir for `startDir` — pure filesystem, no subprocess.
- * Always returns an absolute path (unlike `git rev-parse --git-common-dir`,
- * which returns a path relative to the CALLER's cwd when run from the
- * primary checkout — callers of this function never need their own
- * `resolve(cwd, ...)` step afterward).
- *
- * @param {string} startDir
- * @returns {string|null}
- */
+/** Always absolute, unlike `git rev-parse --git-common-dir`, which is relative to the caller's cwd in the primary. */
 export function resolveGitCommonDir(startDir) {
   try {
     const found = findDotGit(startDir);
@@ -158,8 +73,6 @@ export function resolveGitCommonDir(startDir) {
     const privateGitDir = privateGitDirOf(found.path);
     if (!privateGitDir) return null;
 
-    // Inside the private gitdir, `commondir` points (relative to itself, or
-    // absolute) at the real common dir.
     const commonRaw = readFileSync(join(privateGitDir, 'commondir'), 'utf8').trim();
     if (!commonRaw) return null;
     return isAbsolute(commonRaw) ? commonRaw : resolve(privateGitDir, commonRaw);
@@ -170,15 +83,7 @@ export function resolveGitCommonDir(startDir) {
 
 const SHA = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;
 
-/**
- * The commit HEAD points at in the PRIMARY checkout `root`, read from disk —
- * `git rev-parse HEAD` without the subprocess: a detached SHA, or the branch's
- * loose ref, then `packed-refs`. `null` for every shape it does not read (a
- * linked worktree, reftable, a branch with no commit yet): the caller asks git.
- *
- * @param {string} root
- * @returns {string|null}
- */
+/** `null` for every shape it does not read (linked worktree, reftable, unborn branch): the caller asks git. */
 export function readPrimaryHead(root) {
   try {
     const gitDir = join(root, '.git');
@@ -191,7 +96,6 @@ export function readPrimaryHead(root) {
       const loose = readFileSync(join(gitDir, ref), 'utf8').trim();
       if (SHA.test(loose)) return loose;
     } catch {
-      // not loose — packed
     }
     for (const line of readFileSync(join(gitDir, 'packed-refs'), 'utf8').split(/\r?\n/)) {
       const [sha, name] = line.split(' ');