@polymorphism-tech/morph-spec 9.0.0 → 9.2.0

package/framework/hooks/shared/payload-utils.js

@@ -1,32 +1,9 @@
-/**
- * Shared payload utilities for Claude Code Write/Edit hooks.
- *
- * Extracts file path and content from tool_input payloads,
- * normalizing between Write (content, file_path) and Edit (new_string, old_string, file_path).
- */
-
 import { createHash } from 'crypto';
 import { existsSync } from 'fs';
 import { dirname, join, isAbsolute } from 'path';
 
-/**
- * Resolve the project root that OWNS a given file: walk up from the file's
- * directory to the nearest ancestor containing one of `markers` (default
- * `package.json` — the tsc/build root). Falls back to `fallbackCwd` when
- * nothing matches or on any error.
- *
- * This exists so a PostToolUse hook typechecks/builds in the CORRECT root when
- * a subagent edits a file inside its own git worktree (`isolation: "worktree"`,
- * morph-apply §3b-w) instead of always assuming the main working tree. In the
- * normal (non-worktree) case it resolves to the same root as `process.cwd()`.
- *
- * Fail-open: never throws — returns `fallbackCwd` on any error.
- *
- * @param {string} filePath - edited file path (absolute or relative)
- * @param {string} fallbackCwd - root to use if resolution fails (usually process.cwd())
- * @param {string[]} [markers] - ancestor marker filenames to look for
- * @returns {string} the resolved root directory
- */
+// A sub-agent may edit inside its own worktree: the build root comes from the
+// file, not from the session's cwd.
 export function resolveRootForFile(filePath, fallbackCwd, markers = ['package.json']) {
   try {
     if (!filePath) return fallbackCwd;
@@ -48,33 +25,9 @@ export function resolveRootForFile(filePath, fallbackCwd, markers = ['package.js
   }
 }
 
-/**
- * Resolve the project root that OWNS a `.morph/features/...` path — the tree
- * whose `.morph/` the hook must read and write for that file.
- *
- * A hook process knows only where the SESSION lives (`process.cwd()` /
- * `CLAUDE_PROJECT_DIR`). That is not the same thing as where the FILE lives: a
- * session rooted in the primary repo can legitimately write to a feature that
- * lives in a secondary git worktree. Resolving state from the process instead
- * of the path is what made `enforce-phase-writes` block a legal `2-plan/` write
- * (the root still had the feature at `proposal`) while `protect-spec-files`
- * simultaneously went DARK there (the root had no approved gate to enforce) —
- * one defect, opposite directions.
- *
- * The anchor is exact, so no marker walk is needed: everything before the
- * file's own `.morph/features/` segment IS the owning root. `lastIndexOf` picks
- * the CLOSEST enclosing `.morph/` — the worktree's, not the root it nests under.
- *
- * Note this cannot be solved by locating the hook file itself: `worktree setup`
- * junctions `.morph/framework/` back to the primary root, so every worktree
- * executes the very same hook file. Only the target path identifies the tree.
- *
- * Fail-open: never throws — returns `fallbackCwd` for any non-feature path.
- *
- * @param {string} filePath - target file path (absolute or relative)
- * @param {string} fallbackCwd - root to use when the path owns no `.morph/`
- * @returns {string} the resolved project root
- */
+// State is resolved from the target PATH, never the session: a session in the
+// primary root may write a feature that lives in a worktree. `lastIndexOf` picks
+// the closest enclosing `.morph/`.
 export function resolveMorphRoot(filePath, fallbackCwd) {
   try {
     if (!filePath) return fallbackCwd;
@@ -88,111 +41,41 @@ export function resolveMorphRoot(filePath, fallbackCwd) {
   }
 }
 
-/**
- * Is this an already-absolute path, on EITHER convention?
- *
- * `path.isAbsolute` is platform-bound: `C:/x` is absolute on win32 and relative
- * on posix. That asymmetry is a real defect here, not a theoretical one — a
- * Windows-shaped path reaching a posix `join()` produces `/cwd/C:/x`, silently
- * resolving state against a directory that cannot exist. Recognizing the drive
- * letter explicitly makes the answer the same everywhere (and is a no-op on
- * win32, where `isAbsolute` already accepts it).
- */
+// `path.isAbsolute` is platform-bound: on posix `C:/x` would join into `/cwd/C:/x`.
 const isAbsolutePath = (p) => isAbsolute(p) || /^[a-zA-Z]:\//.test(p);
 
-/** Normalize to forward slashes and make absolute against `fallbackCwd`. */
 function toAbsolutePosix(filePath, fallbackCwd) {
   const p = String(filePath).replace(/\\/g, '/');
   return isAbsolutePath(p) ? p : join(fallbackCwd, p).replace(/\\/g, '/');
 }
 
-/**
- * Absolute path of a hook's target file, resolved against the root that owns
- * it. Pairs with `resolveMorphRoot` so a hook never mixes "the tree I read
- * state from" with "the file I read content from".
- *
- * @param {string} filePath
- * @param {string} fallbackCwd
- * @returns {string}
- */
 export function resolveTargetPath(filePath, fallbackCwd) {
   return toAbsolutePosix(filePath || '', fallbackCwd);
 }
 
-/**
- * Get the file path from a hook payload, normalizing backslashes.
- * @param {Object} payload - Hook payload from stdin
- * @returns {string} Normalized file path or empty string
- */
 export function getFilePath(payload) {
   const raw = payload?.tool_input?.file_path || payload?.tool_input?.path || '';
   return raw.replace(/\\/g, '/');
 }
 
-/**
- * Get the content being written or edited.
- * For Write: returns `content` (full file content).
- * For Edit: returns `new_string` (replacement text).
- * @param {Object} payload - Hook payload from stdin
- * @returns {string} Content string or empty string
- */
 export function getContentToValidate(payload) {
   const input = payload?.tool_input;
   if (!input) return '';
-  // Write tool uses 'content', Edit tool uses 'new_string'
   return input.content || input.new_string || '';
 }
 
-/**
- * Check if this is a Write operation (full file content available).
- * @param {Object} payload - Hook payload from stdin
- * @returns {boolean} True if Write (content exists), false if Edit or unknown
- */
 export function isWriteOperation(payload) {
   return typeof payload?.tool_input?.content === 'string';
 }
 
-/**
- * Get the tool name from a hook payload.
- * @param {Object} payload - Hook payload from stdin
- * @returns {string} Tool name or 'unknown'
- */
 export function getToolName(payload) {
   return payload?.tool_name || 'unknown';
 }
 
-/** Assinatura de Bash: comando normalizado, truncado. Ver getCommandSignature. */
 const BASH_SIGNATURE_MAX = 120;
 
-/**
- * Build a normalized signature for loop detection.
- * - Edit/Write: "Edit:normalized/file/path#<sha1[0:8] do conteúdo>" ("Edit:path" sem conteúdo)
- * - Bash: "Bash:<normalized command, truncated>"
- * - Every other tool WITH input: "Tool:<truncated JSON of tool_input>"
- * - No tool_input at all: just the tool name
- *
- * The general (non-Edit/Write/Bash) case matters: a burst of `Read`/`Skill`/
- * `Grep`/`Agent` calls against DIFFERENT targets (phase-context loading,
- * post-task evaluation reads, parallel subagent dispatch) is normal work, not
- * a loop. Collapsing every one of them to the bare tool name is what made
- * loop-detect fire on exactly that legitimate traffic — a real, reported
- * false positive. Folding in the actual input (rather than hand-listing a
- * target field per tool) fixes it uniformly for every tool at once.
- *
- * **Bash ficou de fora daquele fix (2026-07-22) e continuou colapsando em DUAS
- * PALAVRAS**, o que é quase sempre o nome da ferramenta e nada mais:
- * `npm test -- a`, `npm test -- b` e `npm run build` viravam `Bash:npm test` /
- * `Bash:npm run`. Um ciclo legítimo de mutação — rodar o mesmo runner sobre
- * alvos diferentes, que é exatamente como se testa se um teste morde — disparava
- * o aviso de loop três vezes seguidas. Aviso que toca à toa é aviso que se
- * aprende a ignorar, e aí ele não serve nem quando está certo.
- *
- * O discriminador agora é o comando inteiro (normalizado e truncado), mesma
- * forma dos demais tools. Repetir o comando IDÊNTICO continua sendo loop.
- *
- * @param {Object} payload - Hook payload from stdin
- * @returns {string} Signature string
- */
+// The input is part of the signature: the same tool on DIFFERENT targets is
+// work, not a loop. Only an identical call repeats the signature.
 export function getCommandSignature(payload) {
   const tool = getToolName(payload);
   if (tool === 'unknown') return 'unknown';
@@ -203,11 +86,8 @@ export function getCommandSignature(payload) {
   if (tool === 'Edit' || tool === 'Write') {
     const path = (input.file_path || input.path || '').replace(/\\/g, '/');
     if (!path) return tool;
-    // O caminho sozinho confundia TRABALHO com LOOP: editar regiões diferentes
-    // de dois arquivos (a forma normal de uma correção que cruza teste e
-    // fonte) dava só duas assinaturas e disparava o aviso. O conteúdo da
-    // edição entra na assinatura; repetir a MESMA edição continua casando, e o
-    // ping-pong A→B / B→A continua dando duas assinaturas — loop de verdade.
+    // O caminho sozinho confundia editar regiões diferentes com loop; o
+    // ping-pong A→B / B→A continua dando duas assinaturas.
     const body = tool === 'Write'
       ? input.content
       : (input.old_string !== undefined || input.new_string !== undefined)
@@ -218,8 +98,6 @@ export function getCommandSignature(payload) {
   }
 
   if (tool === 'Bash') {
-    // Espaços colapsados para que a mesma invocação escrita com espaçamento
-    // diferente continue casando — o alvo é o comando, não a digitação.
     const cmd = (input.command || '').replace(/\s+/g, ' ').trim();
     return cmd ? `Bash:${cmd.slice(0, BASH_SIGNATURE_MAX)}` : 'Bash';
   }

package/framework/hooks/shared/phase-utils.js

@@ -1,25 +1,16 @@
 // GENERATED by scripts/generate-refs.js — DO NOT EDIT manually
 // Source of truth: src/core/paths/output-schema.js
 // Regenerate with: node scripts/generate-refs.js
-/**
- * Shared phase utilities for Claude Code hooks.
- *
- * Maps phases to directories and output types.
- */
 
-/** Phase order */
-export const PHASE_ORDER = ["plan","uiux","implement","review","sync"];
+export const PHASE_ORDER = ["plan","uiux","implement","review"];
 
-/** Map phase → allowed output subdirectory */
 export const PHASE_DIRS = {
   plan: '2-plan',
   uiux: '1-design',
   implement: '3-implement',
   review: '4-review',
-  sync: '3-implement',
 };
 
-/** Map output type (camelCase) → phase that produces it */
 export const OUTPUT_PHASE_MAP = {
   plan: 'plan',
   checks: 'plan',
@@ -33,7 +24,6 @@ export const OUTPUT_PHASE_MAP = {
   securityReport: 'review',
 };
 
-/** Map filename → output type (camelCase) */
 export const FILENAME_TO_OUTPUT = {
   'plan.md': 'plan',
   'checks.json': 'checks',
@@ -46,7 +36,6 @@ export const FILENAME_TO_OUTPUT = {
   'security.md': 'securityReport',
 };
 
-/** Protected spec files and the approval gate that locks them */
 export const PROTECTED_SPEC_FILES = {
   'plan.md': 'plan',
   'checks.json': 'plan',
@@ -57,63 +46,33 @@ export const PROTECTED_SPEC_FILES = {
 };
 
 
-/**
- * Extract feature name from a .morph/features/{feature}/... path
- * @param {string} filePath - File path to analyze
- * @returns {string|null} Feature name or null
- */
 export function extractFeatureName(filePath) {
   const normalized = filePath.replace(/\\/g, '/');
   const match = normalized.match(/\.morph\/features\/([^/]+)\//);
   return match ? match[1] : null;
 }
 
-/**
- * Extract phase subdirectory from a .morph/features/{feature}/{phaseDir}/... path
- * @param {string} filePath - File path to analyze
- * @returns {string|null} Phase directory (e.g., '2-plan', '1-design') or null
- */
 export function extractPhaseDir(filePath) {
   const normalized = filePath.replace(/\\/g, '/');
   const match = normalized.match(/\.morph\/features\/[^/]+\/(\d+-[^/]+)\//);
   return match ? match[1] : null;
 }
 
-/**
- * Check if a file path is inside .morph/features/
- * @param {string} filePath
- * @returns {boolean}
- */
 export function isFeaturePath(filePath) {
   const normalized = filePath.replace(/\\/g, '/');
   return normalized.includes('.morph/features/');
 }
 
-/**
- * Check if a file path is inside .morph/framework/ (readonly)
- * @param {string} filePath
- * @returns {boolean}
- */
 export function isFrameworkPath(filePath) {
   const normalized = filePath.replace(/\\/g, '/');
   return normalized.includes('.morph/framework/');
 }
 
-/**
- * Check if a file path is state.json
- * @param {string} filePath
- * @returns {boolean}
- */
 export function isStatePath(filePath) {
   const normalized = filePath.replace(/\\/g, '/');
   return normalized.endsWith('.morph/state.json');
 }
 
-/**
- * Get the basename of a file path
- * @param {string} filePath
- * @returns {string}
- */
 export function getBasename(filePath) {
   const normalized = filePath.replace(/\\/g, '/');
   return normalized.split('/').pop();

package/framework/hooks/shared/redact-secrets.js

@@ -1,14 +1,6 @@
-/**
- * Redaction of obvious secrets in free text that telemetry persists (Bash
- * commands, dispatch prompts). events.jsonl is copied into finish backups
- * under `.git/`, so whatever lands there outlives the session.
- *
- * Pattern-based by design: it catches a secret written NEXT TO its name
- * (`KEY=…`, `Authorization: …`, `user:pass@`) or in a well-known token shape.
- * A bare value with no name beside it is invisible to any pattern — which is
- * why tool OUTPUT (stdout/stderr, a failure's `error` body) is never persisted
- * at all instead of being redacted.
- */
+// Catches a secret written next to its name or in a known token shape; a bare
+// value is invisible to any pattern, which is why tool OUTPUT is never
+// persisted at all instead of being redacted.
 
 export const REDACTED = '[REDACTED]';
 
@@ -43,10 +35,7 @@ const RULES = [
   [/\beyJ[A-Za-z0-9_-]{5,}\.eyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]+/g, REDACTED],
 ];
 
-/**
- * @param {*} text
- * @returns {*} the text with secrets replaced by `[REDACTED]`; non-strings unchanged
- */
+/** Non-strings pass through unchanged. */
 export function redactSecrets(text) {
   if (typeof text !== 'string' || text === '') return text;
   let out = text;

package/framework/hooks/shared/reparse-scan.js

@@ -1,63 +1,16 @@
-/**
- * reparse-scan.js — exhaustive, fail-closed reparse-point (symlink/junction)
- * scan of a directory tree.
- *
- * This lives in `framework/hooks/shared/` rather than `src/` because BOTH sides
- * need it and the dependency direction in this repo only runs one way: `src/`
- * imports from `framework/hooks/shared/` (see `finish.js`'s `claim-registry`
- * and `e2e-check` imports), never the reverse — a hook shipped into a target
- * project has the package, not this repo's `src/` layout.
- *
- * Two callers, one question:
- *   - `teardownWorktree` (src/commands/project/worktree.js) — may this worktree
- *     be handed to `git worktree remove`?
- *   - the `block-destructive-worktree-removal` PreToolUse hook — is the command
- *     about to run going to traverse a link out of the worktree?
- *
- * WHY IT MUST BE EXHAUSTIVE — both `git worktree remove` and its `--force`
- * fallback FOLLOW reparse points out of the worktree and delete the PRIMARY
- * ROOT's real files. The plain removal is not the safe one: it refuses only
- * when it sees modified/untracked *tracked-scope* content, so a GITIGNORED
- * junction (`node_modules`, `.claude`) leaves `git status` empty, the removal
- * proceeds, exits 0 — and the target is gone.
- *
- * So the check cannot live in the `catch` of the plain removal (unreachable on
- * exactly the destructive path), and it cannot be a fixed list of the links
- * `setup` creates: a nested link inside a real `node_modules` (npm link, npm
- * workspaces) is invisible to any top-level inventory. We scan the whole tree
- * and NEVER recurse INTO a reparse point — descending one would walk the target
- * we are trying to protect (and could not terminate on a cycle).
- *
- * FAIL-CLOSED, deliberately: an empty result is NOT the same as a safe one. A
- * directory we could not read or an entry we could not lstat might BE (or
- * contain) a reparse point. Those answer `unprovable`, and every caller must
- * treat that exactly like a found link — decline. "I saw nothing" and "I proved
- * there is nothing" are different claims, and only the second may authorize a
- * removal. This is the one module in the shared/ directory that must NOT be
- * fail-open; the whole point is that uncertainty blocks.
- *
- * `lstat` reports a POSIX symlink and a Windows junction alike as a symbolic
- * link, so the scan behaves identically on both platforms — as does the
- * destruction it prevents.
- */
+// `git worktree remove` (plain or --force) follows reparse points and deletes the
+// primary root's files, nested links included. FAIL-CLOSED: an entry that cannot
+// be read is `unprovable` and blocks exactly like a found link.
 
 import { readdirSync, lstatSync } from 'fs';
 import { join, relative } from 'path';
 
-/**
- * Every reparse point anywhere under `dir`, as relative paths.
- *
- * @param {string} dir
- * @param {string} [base] - root of the scan, for relative reporting
- * @param {{points: string[], unprovable: string[]}} [acc]
- * @returns {{points: string[], unprovable: string[]}} both empty = provably clean
- */
+/** @returns {{points: string[], unprovable: string[]}} both empty = provably clean */
 export function findReparsePoints(dir, base = dir, acc = { points: [], unprovable: [] }) {
   let entries;
   try {
     entries = readdirSync(dir, { withFileTypes: true });
   } catch {
-    // Unreadable (ACL, lock, EMFILE): we cannot prove what is in here.
     acc.unprovable.push((relative(base, dir) || '.').replace(/\\/g, '/'));
     return acc;
   }
@@ -71,28 +24,15 @@ export function findReparsePoints(dir, base = dir, acc = { points: [], unprovabl
       continue;
     }
     if (st.isSymbolicLink()) {
-      // Forward slashes: every other path this command reports is normalized,
-      // and these end up in JSON the caller may compare or display.
       acc.points.push(relative(base, p).replace(/\\/g, '/'));
-      continue; // do NOT descend — that is the target, not the worktree
+      continue; // descending would walk the target, not the worktree
     }
     if (st.isDirectory() && entry.name !== '.git') findReparsePoints(p, base, acc);
   }
   return acc;
 }
 
-/**
- * The single question both callers actually ask: may this tree be handed to a
- * command that follows links?
- *
- * Collapses `points` and `unprovable` into one list precisely because callers
- * must not weigh them differently — `teardownWorktree` already concatenated
- * them, and a hook that treated `unprovable` as "probably fine" would reopen
- * the hole this module exists to close.
- *
- * @param {string} dir
- * @returns {{ safe: boolean, blockers: string[] }}
- */
+// One list on purpose: callers must not weigh `unprovable` lighter than a link.
 export function scanForBlockers(dir) {
   const { points, unprovable } = findReparsePoints(dir);
   const blockers = [...points, ...unprovable];

package/framework/hooks/shared/slice-progress.js

@@ -14,21 +14,13 @@ export function sliceReportPath(featureDir, sliceId) {
   return join(featureDir, '3-implement', 'reports', `${sliceId}.md`);
 }
 
-/** Status of a slice from its report text: no report = pendente, PARCIAL first line = parcial, else feito. */
 export function sliceStatusFromReport(text) {
   if (text == null) return 'pendente';
   const first = String(text).split(/\r?\n/).find((l) => l.trim() !== '') ?? '';
   return PARTIAL_MARKER.test(first) ? 'parcial' : 'feito';
 }
 
-/**
- * Progress of a feature's slices.
- *
- * @param {string|null} checksText - the raw extracted checks file of the plan
- * @param {(sliceId: string) => string|null} readReport - report text, null when absent
- * @returns {{ total: number, done: number, partial: number, pending: number,
- *   slices: { id: string, title: string, depends: string[], covers: string[], status: string }[] } | null} null when that file is unreadable
- */
+/** @returns {{ total, done, partial, pending, slices } | null} null when the checks text is unreadable */
 export function sliceProgressFrom(checksText, readReport) {
   let slices;
   try {
@@ -58,23 +50,18 @@ function readOrNull(path) {
   }
 }
 
-/** Slice progress of the feature directory on disk. */
 export function sliceProgress(featureDir) {
   return sliceProgressFrom(readOrNull(checksPath(featureDir)), (id) => readOrNull(sliceReportPath(featureDir, id)));
 }
 
-/** Unfinished slices whose dependencies are all done: what the next dispatch can take. */
 export function readySlices(progress) {
   if (!progress) return [];
   const done = new Set(progress.slices.filter((s) => s.status === 'feito').map((s) => s.id));
   return progress.slices.filter((s) => s.status !== 'feito' && s.depends.every((d) => done.has(d)));
 }
 
-/**
- * What a slice report must carry, besides prose and its covered scenarios.
- * Loose on purpose: a false "complete" costs a read, a false "incomplete"
- * re-dispatches finished work.
- */
+// Loose on purpose: a false "complete" costs a read, a false "incomplete"
+// re-dispatches finished work.
 export const REPORT_MARKERS = [
   { id: 'files', re: /^\s*(?:[-*]\s*)?(?:\*\*|#+\s*)?arquivos\s*:?\**\s*:?/mi },
 ];
@@ -83,13 +70,7 @@ const MIN_PROSE_CHARS = 80;
 
 const scenarioRe = (id) => new RegExp(`(?<![\\w-])${id}(?![\\w-])`);
 
-/**
- * Inspect one report file: does it exist, which mandatory items it lacks,
- * and whether it is partial.
- *
- * @param {string} path
- * @param {{ covers?: string[] }} [slice] - every scenario the slice covers must be named
- */
+/** Every scenario in `covers` must be named in the report. */
 export function inspectReport(path, { covers = [] } = {}) {
   const missingAll = ['what', 'files', ...covers];
   if (!existsSync(path)) return { exists: false, complete: false, missing: missingAll };

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

@@ -1,34 +1,21 @@
-/**
- * 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
- */
+// One reading of "hand-written project source" for the `reuse` and
+// `code-budget` validators and the `comment-guard` hook.
 
 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`.
+// `.morph/` holds archived contracts that would duplicate real types.
 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
- */
+/** 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 || ''));
 }