@polymorphism-tech/morph-spec 9.0.0 → 9.1.0

package/framework/hooks/shared/command-tokens.js

@@ -1,19 +1,6 @@
-/**
- * command-tokens.js — shell-ish tokenizer shared by the PreToolUse Bash guards.
- *
- * Lives in shared/ (not inside a hook) on purpose: every core hook ends in a
- * standalone tail that reads stdin and exits, so a hook importing a sibling
- * hook for a helper would fire THAT tail in its own process — consuming the
- * payload and exiting before the importer ever ran. block-raw-worktree-add
- * and block-destructive-worktree-removal both read paths off these tokens,
- * so they agree on what a quoted path is.
- */
+// Lives in shared/: a hook importing a sibling hook would fire that hook's
+// stdin-reading tail in its own process.
 
-/**
- * Split a shell-ish command into tokens, honoring single and double quotes.
- * @param {string} command
- * @returns {string[]}
- */
 export function tokenize(command) {
   const tokens = [];
   const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
@@ -22,7 +9,6 @@ export function tokenize(command) {
   return tokens;
 }
 
-/** Index of the first pipe (`|`, not `||` nor `>|`) outside quotes, or -1. */
 function firstUnquotedPipe(command) {
   const s = String(command || '');
   let quote = null;
@@ -43,24 +29,11 @@ function firstUnquotedPipe(command) {
   return -1;
 }
 
-/**
- * Does the command pipe one process into another outside quotes? Without
- * `pipefail` the shell reports the LAST command's status, so the exit code of
- * `dotnet test … | grep …` is grep's, not the test run's.
- * @param {string} command
- * @returns {boolean}
- */
 export function hasUnquotedPipe(command) {
   return firstUnquotedPipe(command) >= 0;
 }
 
-/**
- * The work a command does, without the filter that shapes its output:
- * `dotnet test 2>&1 | tail -25` and `dotnet test | tail -20` run the same
- * tests. Whitespace collapsed, stderr redirections dropped.
- * @param {string} command
- * @returns {string}
- */
+/** The command without the pipe filter and stderr redirections that shape its output. */
 export function producerOf(command) {
   const s = String(command || '');
   const pipe = firstUnquotedPipe(s);
@@ -70,11 +43,6 @@ export function producerOf(command) {
     .trim();
 }
 
-/**
- * The command split at `;`, newline and background `&` outside quotes, plus
- * whether a background `&` was seen. `&&`, `||` and `>&`/`&>` redirections
- * stay inside their segment.
- */
 function topLevelSegments(command) {
   const s = String(command || '');
   const segments = [];
@@ -102,14 +70,7 @@ function topLevelSegments(command) {
 
 const REPORTER = /^(?:echo|printf|true|:|exit\s+0)\b/;
 
-/**
- * Is the exit code of this command the exit code of the work it ran? The
- * shell reports the last segment of a `;` sequence: `dotnet test > log;
- * echo "exit=$?"` always exits 0, and so does `dotnet test || true`. A pipe
- * without `pipefail` reports the filter, and a background `&` reports 0.
- * @param {string} command
- * @returns {boolean}
- */
+/** True when the shell reports something other than the work's exit code (`; echo`, `|| true`, pipe, `&`). */
 export function exitCodeMasked(command) {
   const { segments, background } = topLevelSegments(command);
   if (background) return true;
@@ -253,14 +214,8 @@ function commandWriteTargets(head, body) {
   return targets;
 }
 
-/**
- * Files a command writes: stdout redirection (`>`, `>>`, `1>`, `&>`), `tee`, `sed -i`,
- * `perl -i`, the `cp`/`mv` destination, and a python/node `-c`/`-e`/heredoc script's writes.
- * The redirect scan stops at the line that opens a heredoc: the body is data, and an
- * apostrophe in it would derail the quote-aware split. Quoted operators are text.
- * @param {string} command
- * @returns {string[]}
- */
+// The redirect scan stops at the heredoc line: the body is data, and an
+// apostrophe in it would derail the quote-aware split.
 export function writeTargets(command) {
   const lines = String(command || '').split('\n');
   const heredocAt = lines.findIndex((line) => line.includes('<<'));

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

@@ -1,11 +1,5 @@
-/**
- * The comment shapes the `architecture-code-comments` standard forbids in
- * every case, judged only on the comments an edit ADDED. Whether a short
- * comment restates the code is not decidable here; that stays with the
- * Gate 3 reviewer and the `code-budget` density.
- *
- * @module comment-rules
- */
+// Judges only the comments an edit ADDED, and only their shape: whether a
+// comment restates the code is not decidable here.
 
 import { existsSync, readdirSync, readFileSync } from 'fs';
 import { dirname, join } from 'path';
@@ -58,13 +52,7 @@ function nearest(startDir, test) {
   }
 }
 
-/**
- * Doc-comments are allowed only on a package consumed outside the repo. When
- * that cannot be read from the nearest project file, the rule stays quiet.
- *
- * @param {string} file - absolute path of the edited file
- * @returns {boolean}
- */
+/** Doc-comments are allowed only on a package consumed outside the repo; unreadable = quiet. */
 export function docCommentsForbidden(file) {
   const dir = dirname(file);
   if (/\.cs$/i.test(file)) {
@@ -85,7 +73,7 @@ export function docCommentsForbidden(file) {
   return JSON.parse(readFileSync(pkg, 'utf8')).private === true;
 }
 
-/** Lines of `after` whose comment is not one `before` already had (moved comments do not count). */
+// Moved comments do not count as added.
 function addedCommentLines(before, after, file) {
   const remaining = new Map();
   for (const text of commentLines(before, file).values()) {
@@ -115,10 +103,7 @@ function addedRegionLines(before, after) {
   return out;
 }
 
-/**
- * @param {{ file: string, before: string, after: string, docCommentsForbidden?: boolean }} input
- * @returns {Array<{ line: number, rule: 'process'|'banner'|'doc-comment'|'long-block', text: string }>}
- */
+/** @returns {Array<{ line: number, rule: 'process'|'banner'|'doc-comment'|'long-block', text: string }>} */
 export function commentFindings({ file, before, after, docCommentsForbidden: docForbidden = false }) {
   const isCs = /\.cs$/i.test(file);
   const all = commentLines(after, file);

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

@@ -1,20 +1,10 @@
-/**
- * Linhas de comentário de um arquivo e se elas contam história de processo.
- *
- * O comentário é o que `stripComments` apaga: o mesmo varredor que já separa
- * comentário de string para o `doctor --ai`, com a sintaxe de TS/JS ligada
- * fora do C#. Um regex por linha confundiria `https://` com comentário.
- *
- * @module comment-scanner
- */
+// Comentário é o que `stripComments` apaga: um regex por linha confundiria
+// `https://` com comentário.
 
 import { stripComments } from './comment-stripper.js';
 
-/**
- * Id de cenário (`C{n}`) e de fatia (`F{n}`) do plano. A mesma grafia também é
- * tecla de função, métrica, célula de planilha ou o modelo C-quatro: esses
- * vizinhos não contam (casos em comment-scanner.test.js).
- */
+// A mesma grafia de `C{n}`/`F{n}` é tecla, métrica, célula ou o modelo C-quatro:
+// esses vizinhos não contam.
 const PLAN_ID = new RegExp(String.raw`(?<!\b(?:key|tecla|press|aperte|cell|c[eé]lula|column|coluna)\s+)(?<![\w.#$/-])[CF]\d{1,2}(?![\w.(-]|\s+(?:key|tecla|score|model|modelo|diagram|diagrama)\b)`, 'i');
 
 const PROCESS_CITATION = [
@@ -27,19 +17,11 @@ const PROCESS_CITATION = [
   /\bmockups?\b/i,
 ];
 
-/**
- * @param {string} commentText
- * @returns {boolean} o comentário usa o vocabulário de processo acima
- */
 export function citesProcess(commentText) {
   return PROCESS_CITATION.some((re) => re.test(commentText)) || PLAN_ID.test(commentText);
 }
 
-/**
- * @param {string} content - conteúdo do arquivo
- * @param {string} file - path, só para escolher a sintaxe
- * @returns {Map<number, string>} nº da linha (1-based) → texto do comentário nela
- */
+/** @returns {Map<number, string>} linha 1-based → texto do comentário; `file` só escolhe a sintaxe */
 export function commentLines(content, file) {
   const text = String(content || '');
   const stripped = stripComments(text, { js: !/\.cs$/i.test(file) });
@@ -53,8 +35,7 @@ export function commentLines(content, file) {
       if (first < 0) first = k;
       last = k;
     }
-    // O espaço dentro do comentário não muda ao ser apagado; o trecho vai do
-    // primeiro ao último caractere apagado.
+    // Espaço dentro do comentário não muda ao ser apagado.
     if (first >= 0) out.set(index + 1, row.slice(first, last + 1).trim());
     start += row.length + 1;
   });

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`);
- *   - `mutation/dotnet-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

@@ -1,15 +1,10 @@
 export const ERRATA_HEADING = '## Errata';
 
-/** Strip BOM and CRLF — the one normalization every reader of a frozen markdown applies. */
+/** The one normalization every reader of a frozen markdown applies. */
 export function normalizeMarkdown(text) {
   return String(text ?? '').replace(/^/, '').replace(/\r\n?/g, '\n');
 }
 
-/**
- * Lines with fenced blocks marked, so no heading is read inside ``` or ~~~.
- *
- * @returns {{ raw: string, n: number, fenced: boolean }[]}
- */
 export function markdownLines(text) {
   const out = [];
   let fence = null;
@@ -30,7 +25,7 @@ export function markdownLines(text) {
 const isErrataHeading = (line) => !line.fenced
   && /^##\s+errata\s*$/i.test(line.raw);
 
-/** Offset of the `## Errata` heading in the NORMALIZED text, or -1. */
+/** Offset in the NORMALIZED text, or -1. */
 export function errataOffset(text) {
   let offset = 0;
   for (const line of markdownLines(text)) {
@@ -40,20 +35,12 @@ export function errataOffset(text) {
   return -1;
 }
 
-/** Everything before the errata block, normalized, without trailing blank. */
 export function frozenBody(text) {
   const norm = normalizeMarkdown(text);
   const at = errataOffset(norm);
   return (at === -1 ? norm : norm.slice(0, at)).trimEnd();
 }
 
-/**
- * Is `proposed` the approved text plus an append-only errata? The body stays
- * byte-identical, the result carries an errata block, and what the errata
- * already said is never rewritten.
- *
- * @returns {{ok: true} | {ok: false, why: string}}
- */
 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' };

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 `plan.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

@@ -1,6 +1,4 @@
-// The single list of frontend package locations: `src/lib/detectors` re-exports it,
-// because a hook cannot import `src/`.
+// `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'];
 
-// Where `verify`/`e2e` look for a Playwright setup when `project.frontendPath` is absent.
 export const E2E_SPEC_LOCATIONS = [...PACKAGE_LOCATIONS, 'web'];

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

@@ -1,10 +1,4 @@
-/**
- * The gate a gate question asks about, or null. Explicit gate names win over
- * words that may also appear in a feature slug ("plan", "design", "review").
- *
- * @param {string} question
- * @returns {'plan'|'uiux'|'review'|null}
- */
+/** 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';

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