@polymorphism-tech/morph-spec 8.40.0 → 8.42.0

package/framework/hooks/claude-code/core/comment-guard.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+
+/**
+ * PostToolUse Hook: comments the edit added in a shape the
+ * `architecture-code-comments` standard never allows.
+ *
+ * Event: PostToolUse | Matcher: Write|Edit
+ *
+ * `decision: block` makes the agent fix it in the same turn; the edit itself
+ * already landed. Only comments absent from `tool_response.originalFile`
+ * count, so editing a legacy file never reports its old comments.
+ *
+ * Fail-open: any error passes silently.
+ */
+
+import { readFileSync } from 'fs';
+import { isAbsolute, relative, resolve } from 'path';
+
+import { blockResult, runStandalone } from '../../shared/hook-response.js';
+import { commentFindings, docCommentsForbidden, MAX_BLOCK_LINES } from '../../shared/comment-rules.js';
+import { isGenerated, isProjectSource } from '../../shared/source-files.js';
+
+const MAX_LISTED = 10;
+
+const RULE_LABEL = {
+  process: 'história de processo (UC/ADR/task/gate)',
+  banner: 'banner ou #region',
+  'doc-comment': '///·JSDoc em código que não é pacote publicado',
+  'long-block': `bloco com mais de ${MAX_BLOCK_LINES} linhas`,
+};
+
+function spliceEdit(original, oldString, newString, replaceAll) {
+  if (replaceAll) return original.split(oldString).join(newString);
+  const at = original.indexOf(oldString);
+  if (at < 0) return null;
+  return original.slice(0, at) + newString + original.slice(at + oldString.length);
+}
+
+function readOrNull(file) {
+  try {
+    return readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function contentsOf(payload, absolute) {
+  const input = payload.tool_input ?? {};
+  const response = payload.tool_response ?? {};
+  const before = response.originalFile ?? '';
+  if (payload.tool_name === 'Write') {
+    if (response.originalFile === undefined) return null;
+    return { before, after: readOrNull(absolute) ?? input.content ?? '' };
+  }
+  if (typeof response.originalFile !== 'string') return null;
+  const after = readOrNull(absolute)
+    ?? spliceEdit(response.originalFile, input.old_string ?? '', input.new_string ?? '', input.replace_all === true);
+  return after === null ? null : { before, after };
+}
+
+// NOT_SOURCE matches `build/`, `out/` anywhere: judged on an absolute path,
+// a project checked out under such a folder would be skipped whole.
+function projectRelative(absolute, projectDir) {
+  const rel = relative(projectDir, absolute);
+  return rel && !rel.startsWith('..') && !isAbsolute(rel) ? rel : absolute;
+}
+
+function describe(file, findings) {
+  const listed = findings.slice(0, MAX_LISTED)
+    .map((f) => `- ${file}:${f.line} — ${RULE_LABEL[f.rule]} — ${f.text}`);
+  if (findings.length > MAX_LISTED) listed.push(`- (+${findings.length - MAX_LISTED})`);
+  return [
+    'Comentários que o padrão do projeto não aceita (architecture-code-comments: o padrão é nenhum comentário):',
+    ...listed,
+    '',
+    'Remova-os agora. O que o nome, o tipo ou o teste podem dizer vai para eles; o elo com a pós-condição vai no NOME do teste.',
+    `Só fica o porquê que o código não mostra (invariante, ordem que importa, quirk externo com link), em até ${MAX_BLOCK_LINES} linhas.`,
+  ].join('\n');
+}
+
+/**
+ * @param {object} payload - PostToolUse stdin payload
+ * @returns {Promise<object|null>}
+ */
+export async function run(payload) {
+  try {
+    if (!['Write', 'Edit'].includes(payload?.tool_name)) return null;
+    const file = payload.tool_input?.file_path ?? '';
+    const projectDir = process.env.CLAUDE_PROJECT_DIR || payload.cwd || process.cwd();
+    const absolute = isAbsolute(file) ? file : resolve(projectDir, file);
+    const judged = projectRelative(absolute, projectDir);
+    if (!isProjectSource(judged) || isGenerated(judged)) return null;
+
+    const contents = contentsOf(payload, absolute);
+    if (!contents) return null;
+
+    let docForbidden = false;
+    try { docForbidden = docCommentsForbidden(absolute); } catch { /* unreadable project file: stay quiet */ }
+
+    const findings = commentFindings({ file, ...contents, docCommentsForbidden: docForbidden });
+    return findings.length ? blockResult(describe(file, findings)) : null;
+  } catch {
+    return null;
+  }
+}
+
+await runStandalone(run);

package/framework/hooks/claude-code/core/telemetry-log.js

@@ -24,9 +24,13 @@
  * output, where a secret value can appear with no name beside it.
  *
  * SINK RESOLUTION: the event is appended to the `.morph/` tree that OWNS the
- * tool's target file (`resolveMorphRoot`); tools with no file path sink on the
- * nearest morph tree above the payload's `cwd`, so a sub-agent working in a
- * worktree logs its Bash calls next to its Reads and Writes.
+ * tool's target file — the tree of its `.morph/features/` segment
+ * (`resolveMorphRoot`), else the nearest morph tree above the file; tools with
+ * no file path sink on the nearest morph tree above the payload's `cwd`, so a
+ * sub-agent working in a worktree logs its Bash calls next to its Reads and
+ * Writes. The feature is the tree's BINDING (`morph/<f>` branch, then
+ * `MORPH_FEATURE` in `.morph/worktree.env`) before its most recent active
+ * feature; a bound feature with no `feature.json` in that tree keeps phase null.
  *
  * SILENT: never blocks, never injects context — only appends. Fail-open on any
  * error (exit 0). Only active inside a morph project (stateExists gate).
@@ -40,6 +44,7 @@ import { runStandalone } from '../../shared/hook-response.js';
 import { getFilePath, resolveMorphRoot, resolveTargetPath } from '../../shared/payload-utils.js';
 import { redactSecrets } from '../../shared/redact-secrets.js';
 import { exitCodeMasked } from '../../shared/command-tokens.js';
+import { morphBranchFeature } from '../../shared/git-paths.js';
 import { readTranscriptUsage, usageDelta } from '../../shared/transcript-usage.js';
 
 function normalize(p) {
@@ -115,6 +120,24 @@ function morphRootAbove(dir, fallback) {
   return fallback;
 }
 
+const FEATURE_NAME = /^[A-Za-z0-9._-]+$/;
+
+/**
+ * The feature the TREE is bound to, before any guess from its state: the
+ * branch `morph/<f>` checked out there, then `MORPH_FEATURE` in its
+ * `.morph/worktree.env` (a task worktree sits on `morph-task/<n>`). Without
+ * it, a sub-agent's worktree reported the root's most recent active feature.
+ */
+async function boundFeature(root) {
+  const fromBranch = morphBranchFeature(root);
+  if (fromBranch) return fromBranch;
+  const manifest = join(root, '.morph', 'worktree.env');
+  if (!existsSync(manifest)) return null;
+  const { loadEnvFile } = await import('../../shared/e2e-check.js');
+  const name = loadEnvFile(manifest)?.MORPH_FEATURE;
+  return name && FEATURE_NAME.test(name) && name !== '.' && name !== '..' ? name : null;
+}
+
 function featureFromPath(target) {
   const m = /\/\.morph\/features\/([^/]+)\//.exec(`/${normalize(target)}`);
   return m ? m[1] : null;
@@ -192,8 +215,9 @@ export async function run(payload) {
 
     const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
     const targetFilePath = getFilePath(payload);
-    const cwd = targetFilePath
-      ? resolveMorphRoot(targetFilePath, projectDir)
+    const targetAbs = targetFilePath ? resolveTargetPath(targetFilePath, projectDir) : '';
+    const cwd = targetAbs
+      ? resolveMorphRoot(targetAbs, null) ?? morphRootAbove(dirname(targetAbs), projectDir)
       : morphRootAbove(payload.cwd, projectDir);
 
     if (!stateExists(cwd)) return null;
@@ -204,8 +228,15 @@ export async function run(payload) {
     let phase = null;
     try {
       const active = getActiveFeature(cwd);
-      feature = active?.name ?? featureFromPath(targetFilePath);
-      if (feature) phase = active?.feature?.phase || derivePhaseForFeature(feature, cwd);
+      const bound = await boundFeature(cwd);
+      if (bound) {
+        feature = bound;
+        if (bound === active?.name && active.feature?.phase) phase = active.feature.phase;
+        else if (existsSync(join(cwd, '.morph', 'features', bound, 'feature.json'))) phase = derivePhaseForFeature(bound, cwd);
+      } else {
+        feature = active?.name ?? featureFromPath(targetFilePath);
+        if (feature) phase = active?.feature?.phase || derivePhaseForFeature(feature, cwd);
+      }
     } catch {
       // enrichment is best-effort — a missing feature never blocks capture
     }
@@ -263,7 +294,7 @@ export async function run(payload) {
         // between the Read and this hook omits the numbers rather than fail.
         if (hookEvent !== 'PostToolUseFailure') {
           try {
-            const abs = resolveTargetPath(event.target, cwd);
+            const abs = targetAbs || resolveTargetPath(event.target, projectDir);
             event.bytes = statSync(abs).size;
             const read = readSliceBytes(abs, input, event.bytes);
             if (read !== undefined) event.bytesRead = read;

package/framework/hooks/claude-code/core/worktree-create.js

@@ -22,8 +22,9 @@
  *      `morph-spec worktree provision <n> [--base <ref>]`.
  *   4. `worktree.baseRef` from the merged settings (`~/.claude/settings.json`
  *      < `<root>/.claude/settings.json` < `<root>/.claude/settings.local.json`):
- *      `"head"` → the current branch (or sha) of `payload.cwd`; anything else
- *      → the repo's default branch (the CLI's own default).
+ *      `"head"` → the current branch (or sha) of `payload.cwd`; unset and
+ *      `payload.cwd` on `morph/<f>` → that feature branch; `"fresh"` or
+ *      anything else → the repo's default branch (the CLI's own default).
  *   5. CLI exit 0 or 2 (already exists) → its `path`. Exit 1/3 → error.
  *      CLI unavailable → in-hook git fallback that still lands the tree under
  *      `<root>/worktrees/<n>` on `morph-task/<n>` (degraded: no junctions, no
@@ -81,10 +82,11 @@ function readJsonSafe(path) {
 
 /**
  * `worktree.baseRef` across the three settings layers, last one wins.
- * Fail-open per file. Returns `'fresh'` (the documented default) when unset.
+ * Fail-open per file. `null` when unset — distinct from an explicit `'fresh'`,
+ * which overrides the feature-branch default (see `resolveBase`).
  */
 export function readBaseRefSetting(root, home = homedir()) {
-  let value = 'fresh';
+  let value = null;
   for (const p of [
     join(home, '.claude', 'settings.json'),
     join(root, '.claude', 'settings.json'),
@@ -108,6 +110,21 @@ function headRef(cwd) {
   }
 }
 
+/**
+ * The base of a task tree. `"head"` → whatever `cwd` has checked out;
+ * `"fresh"` (or any other explicit value) → the default branch; unset → the
+ * `morph/<f>` branch `cwd` is on, when it is one. A sub-agent dispatched by
+ * the apply needs the feature's work, and a tree born from the default branch
+ * made every dispatch open with `git merge --ff-only morph/<f>`.
+ * `morph-task/*` does not match: a tree of a tree tips at the default.
+ */
+export function resolveBase(setting, cwd) {
+  if (setting === 'head') return headRef(cwd);
+  if (setting) return null;
+  const current = headRef(cwd);
+  return current && /^morph\/.+/.test(current) ? current : null;
+}
+
 function isKnownFeature(root, name) {
   if (existsSync(join(root, '.morph', 'features', name, 'feature.json'))) return true;
   try {
@@ -158,8 +175,7 @@ export async function run(payload) {
   if (!root) return { error: `worktree-create: "${start}" is not inside a git repository` };
 
   const name = slugify(payload?.name);
-  const baseSetting = readBaseRefSetting(root);
-  const base = baseSetting === 'head' ? headRef(start) : null;
+  const base = resolveBase(readBaseRefSetting(root), start);
 
   // Outside a morph project there is nothing to govern beyond WHERE the tree
   // lands — plain git, under <root>/worktrees/.

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

@@ -0,0 +1,171 @@
+/**
+ * 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 evaluator and the `code-budget` density.
+ *
+ * @module comment-rules
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'fs';
+import { dirname, join } from 'path';
+
+import { citesProcess, commentLines } from './comment-scanner.js';
+
+export const MAX_BLOCK_LINES = 3;
+
+const ALLOWED = [
+  /READS STANDARDS?:/,
+  /\bVERIFY:/,
+  /eslint-(?:disable|enable)/,
+  /@ts-(?:ignore|expect-error|nocheck|check)/,
+  /<auto-generated/i,
+  /prettier-ignore/,
+  /ReSharper\s+(?:disable|restore)/,
+  /@(?:vitest|jest)-environment/,
+  /^\/\/\/\s*<reference\b/,
+  /^#!/,
+  /istanbul ignore|c8 ignore|v8 ignore/,
+];
+
+const DECORATION = /[-=*#~_+]{3,}/;
+const REGION = /^\s*#\s*(?:end)?region\b/;
+
+function bodyOf(text) {
+  return text.replace(/^(?:\/\/+|\/\*+|\*+)/, '').replace(/\*+\/$/, '').trim();
+}
+
+function isBanner(text) {
+  const body = bodyOf(text);
+  if (REGION.test(body)) return true;
+  if (!DECORATION.test(body)) return false;
+  const words = body.replace(/[-=*#~_+|]/g, '').trim();
+  return words === '' || /^[-=*#~_+]{3,}.*[-=*#~_+]{3,}$/.test(body);
+}
+
+function isDocComment(text, isCs) {
+  return isCs ? /^\/\/\/(?!\/)/.test(text) : /^\/\*\*(?!\*)/.test(text);
+}
+
+function nearest(startDir, test) {
+  let dir = startDir;
+  for (;;) {
+    const hit = test(dir);
+    if (hit) return hit;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * 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}
+ */
+export function docCommentsForbidden(file) {
+  const dir = dirname(file);
+  if (/\.cs$/i.test(file)) {
+    const proj = nearest(dir, (d) => {
+      try {
+        const name = readdirSync(d).find((n) => /\.csproj$/i.test(n));
+        return name ? join(d, name) : null;
+      } catch {
+        return null;
+      }
+    });
+    if (!proj) return false;
+    const xml = readFileSync(proj, 'utf8');
+    return !/<(?:IsPackable|GeneratePackageOnBuild)>\s*true\s*</i.test(xml) && !/<PackageId>/i.test(xml);
+  }
+  const pkg = nearest(dir, (d) => (existsSync(join(d, 'package.json')) ? join(d, 'package.json') : null));
+  if (!pkg) return false;
+  return JSON.parse(readFileSync(pkg, 'utf8')).private === true;
+}
+
+/** Lines of `after` whose comment is not one `before` already had (moved comments do not count). */
+function addedCommentLines(before, after, file) {
+  const remaining = new Map();
+  for (const text of commentLines(before, file).values()) {
+    remaining.set(text, (remaining.get(text) ?? 0) + 1);
+  }
+  const added = new Map();
+  for (const [line, text] of commentLines(after, file)) {
+    const left = remaining.get(text) ?? 0;
+    if (left > 0) remaining.set(text, left - 1);
+    else added.set(line, text);
+  }
+  return added;
+}
+
+function addedRegionLines(before, after) {
+  const old = new Map();
+  for (const row of before.split('\n')) {
+    if (REGION.test(row)) old.set(row.trim(), (old.get(row.trim()) ?? 0) + 1);
+  }
+  const out = [];
+  after.split('\n').forEach((row, i) => {
+    if (!REGION.test(row)) return;
+    const left = old.get(row.trim()) ?? 0;
+    if (left > 0) old.set(row.trim(), left - 1);
+    else out.push({ line: i + 1, text: row.trim() });
+  });
+  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 }>}
+ */
+export function commentFindings({ file, before, after, docCommentsForbidden: docForbidden = false }) {
+  const isCs = /\.cs$/i.test(file);
+  const all = commentLines(after, file);
+  const added = addedCommentLines(before, after, file);
+  const findings = [];
+  const flagged = new Set();
+  const flag = (line, rule, text) => {
+    if (flagged.has(line)) return;
+    flagged.add(line);
+    findings.push({ line, rule, text });
+  };
+
+  for (const [line, text] of added) {
+    if (ALLOWED.some((re) => re.test(text))) continue;
+    if (citesProcess(text)) flag(line, 'process', text);
+    else if (isBanner(text)) flag(line, 'banner', text);
+  }
+  for (const { line, text } of addedRegionLines(before, after)) flag(line, 'banner', text);
+
+  if (docForbidden) {
+    for (const [line, text] of added) {
+      const opensBlock = !isCs || !isDocComment(all.get(line - 1) ?? '', isCs);
+      if (isDocComment(text, isCs) && opensBlock) flag(line, 'doc-comment', text);
+    }
+  }
+
+  const rows = after.split('\n');
+  const lines = [...all.keys()]
+    .filter((line) => (rows[line - 1] ?? '').trim() === all.get(line))
+    .sort((a, b) => a - b);
+  let run = [];
+  const closeRun = () => {
+    if (run.length && isDocComment(all.get(run[0]), isCs)) {
+      run = [];
+      return;
+    }
+    const addedInRun = run.filter((l) => added.has(l) && !ALLOWED.some((re) => re.test(all.get(l))));
+    if (addedInRun.length > MAX_BLOCK_LINES) {
+      flag(run[0], 'long-block', `${run.length} linhas: ${all.get(run[0])}`);
+    }
+    run = [];
+  };
+  for (const line of lines) {
+    if (run.length && line !== run[run.length - 1] + 1) closeRun();
+    run.push(line);
+  }
+  closeRun();
+
+  return findings.sort((a, b) => a.line - b.line);
+}

package/{src/lib/validators/code-budget → framework/hooks/shared}/comment-scanner.js

@@ -5,10 +5,10 @@
  * 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 code-budget-comment-scanner
+ * @module comment-scanner
  */
 
-import { stripComments } from '../../ai/comment-stripper.js';
+import { stripComments } from './comment-stripper.js';
 
 /** Vocabulário de processo do morph-spec, fora o id de task (abaixo). */
 const PROCESS_CITATION = [

package/{src/lib/ai → framework/hooks/shared}/comment-stripper.js

@@ -11,7 +11,8 @@
  *     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`;
- *   - `validators/code-budget/comment-scanner.js` — acha as linhas de
+ *   - `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

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

@@ -58,6 +58,42 @@ function findDotGit(startDir) {
   }
 }
 
+/**
+ * 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;
+  return isAbsolute(match[1]) ? match[1] : resolve(dirname(dotGitFile), match[1]);
+}
+
+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}
+ */
+export function morphBranchFeature(root) {
+  try {
+    const dotGit = join(root, '.git');
+    const gitDir = statSync(dotGit).isDirectory() ? dotGit : privateGitDirOf(dotGit);
+    if (!gitDir) return null;
+    const name = MORPH_BRANCH.exec(readFileSync(join(gitDir, 'HEAD'), 'utf8').trim())?.[1];
+    return name && name !== '.' && name !== '..' ? name : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Is `startDir` inside a LINKED (secondary) worktree?
  *
@@ -119,11 +155,8 @@ export function resolveGitCommonDir(startDir) {
       return found.path;
     }
 
-    // `.git` is a FILE: `gitdir: <path>` → this worktree's private gitdir.
-    const content = readFileSync(found.path, 'utf8');
-    const match = content.match(/^gitdir:\s*(.+?)\s*$/m);
-    if (!match) return null;
-    const privateGitDir = isAbsolute(match[1]) ? match[1] : resolve(dirname(found.path), match[1]);
+    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.

package/framework/hooks/shared/source-files.js

@@ -0,0 +1,34 @@
+/**
+ * Which files count as the project's hand-written source. One reading for the
+ * `reuse` and `code-budget` validators and the `comment-guard` hook, so the
+ * three never disagree about the same file.
+ *
+ * @module source-files
+ */
+
+const SCANNABLE = /\.(cs|ts|tsx|js|jsx|mjs|cjs)$/i;
+
+// `.morph/` is real: an archived feature's `contracts.cs` entered ProspectPRO's
+// graph as a second `RoulettePriority`.
+const NOT_SOURCE = /(^|\/)(?:\.morph|node_modules|dist|build|out|\.next|bin|obj|coverage)\//;
+
+const DECLARATION_FILE = /\.d\.ts$/i;
+
+const GENERATED = /(?:\.Designer|\.g|\.g\.i)\.cs$|ModelSnapshot\.cs$/i;
+
+/**
+ * @param {string} sourceFile
+ * @returns {boolean} project code in a scanned extension, tests included
+ */
+export function isProjectSource(sourceFile) {
+  const f = String(sourceFile || '').replace(/\\/g, '/');
+  return SCANNABLE.test(f) && !DECLARATION_FILE.test(f) && !NOT_SOURCE.test(f);
+}
+
+/**
+ * @param {string} sourceFile
+ * @returns {boolean} generated C# nobody writes by hand
+ */
+export function isGenerated(sourceFile) {
+  return GENERATED.test(String(sourceFile || ''));
+}