@try-works/dsh-recursive-mode 0.3.1 → 0.4.0

package/src/enforcement.ts

@@ -5,48 +5,153 @@
  * Layer 2 (tool guards) and Layer 8 (tamper) are the remaining enforcement
  * layers. Configurable strict|advisory per gate (default advisory).
  */
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync, readdirSync } from 'node:fs'
 import { join, isAbsolute, resolve, sep } from 'node:path'
-import { getLockStatus, getPrerequisiteBlockers } from './lock.ts'
-import { getMdFieldValue } from './status.ts'
+import { getLockStatus } from './lock.ts'
+import { validateTransition, type GateCheckResult } from './lifecycle.ts'
+import {
+  evaluateToolPolicy, loadToolPolicyFile,
+  builtInToolPolicyDefault, LOCK_TOOL_NAMES, WRITE_TOOL_NAMES,
+  type ToolPolicy, type ToolPolicyContext, type Decision as PolicyDecision,
+} from './policy-globs.ts'
+import { withPhaseBaseline, phaseNumberForArtifact, resolveFrom } from './phase-rules.ts'
+
+/**
+ * The BUILT-IN default rule list (T16) is defined in `src/policy-globs.ts`,
+ * beside the evaluator and the loader that use it as the ABSENT-file fallback,
+ * and re-exported here because it is part of the guard's documented behaviour.
+ * (It cannot live in a module of its own: the list needs the loader's predicate
+ * contract and the loader needs the list, which as two modules is a value-level
+ * import cycle — the very thing that made a top-level wiring call throw.)
+ */
+export const builtInToolPolicy = builtInToolPolicyDefault
 
 export type EnforcementMode = 'strict' | 'advisory'
 
+/**
+ * T28 — the budgets. Every unbounded loop and every unbounded result gets a named,
+ * configurable cap, because a bound that is not named cannot be reviewed and a bound
+ * that is not configurable gets hardcoded per call site (which is exactly what
+ * happened to `maxDepth`).
+ */
+export interface BudgetConfig {
+  /** Rounds ONE phase's audit loop may run, even when every round makes progress. */
+  maxAuditRounds: number
+  /**
+   * How many times a phase may be sent back for repair. Distinct from T20's
+   * no-progress bound: that one stops a loop REPEATING a finding, this one bounds a
+   * loop that keeps finding genuinely NEW things — the case the no-progress bound
+   * deliberately lets run.
+   */
+  maxRepairAttempts: number
+  /** The ceiling for the WHOLE recursion, not a fresh allowance at each level. */
+  maxDelegationDepth: number
+  /** Delegated children one phase may start. */
+  maxChildrenPerPhase: number
+  /** Byte ceiling for one tool result. T24's caps bound the COUNT of findings; a few enormous findings need this. */
+  maxResultBytes: number
+}
+
+export const DEFAULT_BUDGETS: BudgetConfig = {
+  // Matches the historical `maxRounds ?? 3`, so adding the config changes no default.
+  maxAuditRounds: 3,
+  maxRepairAttempts: 3,
+  // Matches the hardcoded `maxDepth ?? 2` this replaces, for the same reason.
+  maxDelegationDepth: 2,
+  maxChildrenPerPhase: 4,
+  maxResultBytes: 65_536,
+}
+
 export interface EnforcementConfig {
   preStep: EnforcementMode
   toolGuards: EnforcementMode
   tamper: EnforcementMode
+  /** T28: the caps. Always present, so a caller never has to guess a default. */
+  budgets: BudgetConfig
 }
 
-/** Validate the enforcement config shape (unknown keys fail at plugin load). */
+const CONFIG_KEYS = ['preStep', 'toolGuards', 'tamper', 'budgets']
+const BUDGET_KEYS: ReadonlyArray<keyof BudgetConfig> = [
+  'maxAuditRounds', 'maxRepairAttempts', 'maxDelegationDepth', 'maxChildrenPerPhase', 'maxResultBytes',
+]
+
+/**
+ * Validate the enforcement config shape (unknown keys fail at plugin load).
+ *
+ * A budget must be a POSITIVE INTEGER. Zero and negatives are rejected rather than
+ * coerced: `0` would mean "never allowed", which bricks the phase it was meant to
+ * bound, and a negative would read as already-exceeded everywhere it is compared.
+ * A config error is loud at load, not mysterious later.
+ */
 export function resolveEnforcementConfig(config: unknown): EnforcementConfig {
   const raw = (config ?? {}) as Record<string, unknown>
-  const unknown = Object.keys(raw).filter((k) => !['preStep', 'toolGuards', 'tamper'].includes(k))
+  const unknown = Object.keys(raw).filter((k) => !CONFIG_KEYS.includes(k))
   if (unknown.length > 0) {
-    throw new Error('EnforcementConfig has unknown key(s) ' + unknown.join(', ') + ' - config is { preStep, toolGuards, tamper }')
+    throw new Error('EnforcementConfig has unknown key(s) ' + unknown.join(', ') + ' - config is { preStep, toolGuards, tamper, budgets }')
   }
   const mode = (value: unknown): EnforcementMode => (value === 'strict' ? 'strict' : 'advisory')
+
+  const rawBudgets = (raw.budgets ?? {}) as Record<string, unknown>
+  if (typeof raw.budgets !== 'undefined' && (raw.budgets === null || typeof raw.budgets !== 'object')) {
+    throw new Error('EnforcementConfig budgets must be an object of caps')
+  }
+  const unknownBudget = Object.keys(rawBudgets).filter((k) => !BUDGET_KEYS.includes(k as keyof BudgetConfig))
+  if (unknownBudget.length > 0) {
+    throw new Error('EnforcementConfig budgets has unknown key(s) ' + unknownBudget.join(', ') + ' - budgets are { ' + BUDGET_KEYS.join(', ') + ' }')
+  }
+  const budgets = { ...DEFAULT_BUDGETS }
+  for (const key of BUDGET_KEYS) {
+    const value = rawBudgets[key]
+    if (value === undefined) continue
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) {
+      throw new Error('EnforcementConfig budgets.' + key + ' must be a positive integer (got ' + JSON.stringify(value) + ')')
+    }
+    budgets[key] = value
+  }
+
   return {
     preStep: mode(raw.preStep),
     toolGuards: mode(raw.toolGuards),
     tamper: mode(raw.tamper),
+    budgets,
   }
 }
 
-export const DEFAULT_ENFORCEMENT: EnforcementConfig = { preStep: 'advisory', toolGuards: 'advisory', tamper: 'advisory' }
+export const DEFAULT_ENFORCEMENT: EnforcementConfig = {
+  preStep: 'advisory',
+  toolGuards: 'advisory',
+  tamper: 'advisory',
+  budgets: DEFAULT_BUDGETS,
+}
 
-/** Tool names the locked-artifact write guard treats as write operations. */
-const WRITE_TOOL_NAMES = new Set(['write', 'edit', 'fs_write', 'fs-write', 'pwsh', 'shell', 'bash', 'run_code'])
+/**
+ * T15: the rule that produced a guard decision (a machine-readable reason for
+ * every allow/deny/ask the guard hands back). `'none'` means no guard predicate
+ * fired; `'transition'` marks a decision whose only dissenting gate was the
+ * advisory transition gate (see consultTransitionGate).
+ */
+export type GuardRule = 'lock-order' | 'tdd-evidence' | 'locked-write' | 'transition' | 'none'
 
-/** Tool names the monotonic lock-order guard treats as lock operations. */
-const LOCK_TOOL_NAMES = new Set(['recursive_lock', 'recursive_lock_phase'])
+/** T15: the transition gate's verdict as attached to a decision (advisory only). */
+export interface GuardTransition {
+  passed: boolean
+  failures: string[]
+}
 
 /**
  * Layer 2 - tools/pre-execute guard decision.
  * Pure predicate: inspects the pending tool execution (name + args) against
  * the run tree under the given worktree root.
+ *
+ * T15: `rule` and `transition` are OPTIONAL and additive. They must stay
+ * optional — `coerceAskToDecision` is asserted with `toEqual({ kind: ... })`
+ * (an EXACT match) in tests/enforcement.spec.ts, so the coercion path may never
+ * grow extra keys. `evaluateToolGuard` itself always sets `rule`.
  */
-export type ToolGuardDecision = { kind: 'allow'; warn?: string } | { kind: 'deny'; reason: string } | { kind: 'ask'; reason?: string }
+export type ToolGuardDecision =
+  | { kind: 'allow'; warn?: string; rule?: GuardRule; transition?: GuardTransition }
+  | { kind: 'deny'; reason: string; rule?: GuardRule; transition?: GuardTransition }
+  | { kind: 'ask'; reason?: string; rule?: GuardRule; transition?: GuardTransition }
 
 export interface ToolExecLike {
   name: string
@@ -54,6 +159,61 @@ export interface ToolExecLike {
   agent?: unknown
 }
 
+/* -------------------------------------------------------------------------- */
+/* T16 — the policy the guard evaluates                                       */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * The BUILT-IN default rule list (T16) is defined in `src/policy-globs.ts`,
+ * beside the evaluator and the loader that use it as the ABSENT-file fallback,
+ * and re-exported here because it is part of the guard's documented behaviour.
+ * (It cannot live in a module of its own: the list needs the loader's predicate
+ * contract and the loader needs the list, which as two modules is a value-level
+ * import cycle — the very thing that made a top-level wiring call throw.)
+ */
+
+/**
+ * The policy in force for one guard call: the worktree's policy file when
+ * present (a broken file fails closed), the built-in list when absent, plus the
+ * current phase's narrowing baseline. Exported so a reviewer — and
+ * `recursive:policy` later — can read the effective rules instead of inferring
+ * them from a code path.
+ */
+export function resolveToolPolicyForGuard(worktreeRoot: string, runId: string): ToolPolicy {
+  const loaded = loadToolPolicyFile(worktreeRoot)
+  return withPhaseBaseline(loaded.policy, currentPhaseArtifact(worktreeRoot, runId))
+}
+
+/**
+ * The artifact whose phase baseline applies: the HIGHEST-numbered phase artifact
+ * present in the run (a run at phase 3 has `00`-`03` on disk). Read from the
+ * filesystem on every call — the same no-cache discipline the active run id
+ * needs, because a cached phase would apply yesterday's baseline to today's lock.
+ */
+export function currentPhaseArtifact(worktreeRoot: string, runId: string): string {
+  if (!worktreeRoot || !runId) return ''
+  const runDir = join(worktreeRoot, '.recursive', 'run', runId)
+  let names: string[]
+  try {
+    names = readdirSync(runDir)
+  } catch {
+    return ''
+  }
+  let best = ''
+  let bestPhase = -1
+  for (const name of names) {
+    if (!name.endsWith('.md')) continue
+    const phase = phaseNumberForArtifact(name)
+    if (!phase) continue
+    const value = Number(phase)
+    if (value > bestPhase) {
+      bestPhase = value
+      best = name
+    }
+  }
+  return best
+}
+
 export function evaluateToolGuard(
   exec: ToolExecLike,
   worktreeRoot: string,
@@ -62,50 +222,86 @@ export function evaluateToolGuard(
 ): ToolGuardDecision {
   const name = exec.name
   const args = (exec.arguments ?? {}) as Record<string, unknown>
-  const runDir = join(worktreeRoot, '.recursive', 'run', activeRunId)
-
-  // Monotonic lock-order denial (recursive_lock out of order).
-  if (LOCK_TOOL_NAMES.has(name)) {
-    const artifact = String(args.artifact ?? '')
-    if (artifact) {
-      const blockers = getPrerequisiteBlockers(runDir, artifact)
-      if (blockers.length > 0) {
-        const reason = 'monotonic lock-order: ' + blockers.map((b) => b.artifact + ' (' + b.status + ')').join(', ')
-        return mode === 'strict' ? { kind: 'deny', reason } : { kind: 'ask', reason }
-      }
-      // TDD evidence gating on Phase 3 lock.
-      if (artifact === '03-implementation-summary.md') {
-        const artifactPath = join(runDir, artifact)
-        const content = existsSync(artifactPath) ? readFileSync(artifactPath, 'utf8') : ''
-        const tddMode = getMdFieldValue(content, 'TDD Mode') ?? ''
-        if (tddMode === 'strict') {
-          const hasRed = /RED|red evidence/i.test(content)
-          const hasGreen = /GREEN|green evidence/i.test(content)
-          if (!hasRed || !hasGreen) {
-            const reason = 'TDD Mode: strict requires RED + GREEN evidence before locking Phase 3'
-            return mode === 'strict' ? { kind: 'deny', reason } : { kind: 'ask', reason }
-          }
-        }
-      }
-    }
-  }
+  const runId = typeof activeRunId === 'string' ? activeRunId.trim() : ''
+  const runDir = join(worktreeRoot, '.recursive', 'run', runId)
 
-  // Locked-artifact write denial.
-  if (WRITE_TOOL_NAMES.has(name)) {
-    const target = firstTargetPath(args)
-    if (target) {
-      const normalized = target.replace(/\\/g, '/')
-      if (normalized.endsWith('.md') && normalized.includes('/.recursive/run/')) {
-        const abs = resolveTargetPath(normalized, worktreeRoot)
-        if (abs && getLockStatus(abs) === 'LOCKED') {
-          const reason = 'locked-artifact write denial: ' + normalized + ' carries Status: LOCKED (reopen explicitly to edit)'
-          return mode === 'strict' ? { kind: 'deny', reason } : { kind: 'ask', reason }
-        }
-      }
-    }
+  // T15: the transition gate is consulted BEFORE the verdict so its result can
+  // ride along on every lock-tool decision — including a refusal.
+  const transition = consultTransitionGate(name, args, worktreeRoot, runId)
+
+  // T16: the verdict comes from the ordered policy, not from branches here. The
+  // policy file is re-read per call on purpose: a policy a human just edited
+  // must take effect on the next tool call, not after a restart.
+  const policy = resolveToolPolicyForGuard(worktreeRoot, runId)
+  const context: ToolPolicyContext = { args, runDir, runId, worktreeRoot }
+  const decision = evaluateToolPolicy(policy, name, args, context)
+  return advisory(verdictFor(mode, decision), transition)
+}
+
+/**
+ * Map the policy's verdict onto the guard's decision kind: `strict` denies,
+ * `advisory` asks (the pre-T16 wording, unchanged), `allow` stays an allow. The
+ * decision's `rule` is the label of the rule that decided it, so a policy
+ * verdict is traceable to an auditable line in the policy file.
+ */
+function verdictFor(mode: EnforcementMode, decision: PolicyDecision): ToolGuardDecision {
+  const rule = (decision.rule ?? 'none') as GuardRule
+  if (decision.kind === 'allow') return { kind: 'allow', rule }
+  const reason = decision.reason ?? 'tool policy denied this call'
+  return mode === 'strict' ? { kind: 'deny', reason, rule } : { kind: 'ask', reason, rule }
+}
+
+/**
+ * T15 — consult the transition gate (`validateTransition`) from the guard,
+ * ADVISORY-FIRST.
+ *
+ * The gate's result is ATTACHED to the decision as `transition` and NEVER
+ * changes the verdict (allow/deny/ask), which continues to come from the
+ * guard's own predicates. Rationale: `validateTransition` enforces a SUPERSET
+ * of the guard's checks — it additionally requires `Audit: PASS`, a
+ * `Requirement Completion Status` section, a delegation-basis marker,
+ * `## Effective Inputs Re-read`, and (for phase 3) that the RED/GREEN evidence
+ * FILES exist. Promoting those to blocking would deny locks the lock tool
+ * itself allows, and would take the parity fixtures red — they carry none of
+ * those markers. So: the gate reports, the guard decides, and a gate failure
+ * under an otherwise-allowed call surfaces as an advisory `warn` (never a
+ * silent allow).
+ *
+ * Only lock-tool calls with a REAL run id and a non-empty artifact are
+ * consulted; a missing run id means the caller has no run context (the gate
+ * would resolve prerequisites against the run ROOT and be meaningless).
+ */
+function consultTransitionGate(
+  name: string,
+  args: Record<string, unknown>,
+  worktreeRoot: string,
+  runId: string,
+): GateCheckResult | undefined {
+  if (!LOCK_TOOL_NAMES.has(name)) return undefined
+  if (!worktreeRoot || !runId) return undefined
+  const artifact = String(args.artifact ?? '')
+  if (!artifact) return undefined
+  try {
+    return validateTransition({ runId, worktreeRoot, targetArtifact: artifact, kind: 'lock' })
+  } catch {
+    // Best-effort evidence: a transition read must never fail the guard call.
+    return undefined
   }
+}
 
-  return { kind: 'allow' }
+/** Attach the transition verdict, and warn when the guard allows against it. */
+function advisory(decision: ToolGuardDecision, transition: GateCheckResult | undefined): ToolGuardDecision {
+  if (!transition) return decision
+  if (decision.kind !== 'allow') return { ...decision, transition }
+  if (transition.passed) return { ...decision, transition }
+  // The verdict stays `allow`; the gate only names itself as the dissenting
+  // voice, so an advisory pass is never silent.
+  return {
+    ...decision,
+    rule: 'transition',
+    warn: 'transition gate (advisory) failed: ' + transition.failures.join('; '),
+    transition,
+  }
 }
 
 /**
@@ -123,26 +319,20 @@ export function coerceAskToDecision(decision: ToolGuardDecision, mode: Enforceme
   return { kind: 'allow', warn: decision.reason ?? 'ask under advisory enforcement allows' }
 }
 
-/** Resolve a tool-target path to an absolute path under the worktree root. */
+/**
+ * Resolve a tool-target path to an absolute path under the worktree root.
+ * T16: the path arithmetic moved to `phase-rules.ts` (shared with the phase
+ * baselines, so the guard and a baseline can never disagree about which path a
+ * call names); what stays here is this module's containment rule.
+ */
 function resolveTargetPath(target: string, worktreeRoot: string): string | null {
-  const normalized = target.replace(/\\/g, '/')
-  if (isAbsolute(normalized)) {
-    const abs = resolve(normalized)
-    const rootAbs = resolve(worktreeRoot)
-    const rootPrefix = rootAbs.endsWith(sep) ? rootAbs : rootAbs + sep
-    if (abs !== rootAbs && !abs.startsWith(rootPrefix)) return null
-    return abs
-  }
-  return resolve(worktreeRoot, normalized.replace(/^\.?\/?/, ''))
-}
-
-/** Extract the first candidate target path from a tool's arguments. */
-function firstTargetPath(args: Record<string, unknown>): string | null {
-  for (const key of ['file_path', 'path', 'command', 'target', 'filePath']) {
-    const value = args[key]
-    if (typeof value === 'string' && value.trim() !== '') return value.trim()
-  }
-  return null
+  const abs = resolveFrom(worktreeRoot, target)
+  if (!abs) return null
+  if (!isAbsolute(target.replace(/\\/g, '/'))) return abs
+  const rootAbs = resolve(worktreeRoot)
+  const rootPrefix = rootAbs.endsWith(sep) ? rootAbs : rootAbs + sep
+  if (abs !== rootAbs && !abs.startsWith(rootPrefix)) return null
+  return abs
 }
 
 /**

package/src/errors.ts

@@ -0,0 +1,197 @@
+/**
+ * T24 — stable, greppable, self-sufficient tool errors.
+ *
+ * WHY PROSE AND NOT A JSON ENVELOPE. A structured error envelope reaches the
+ * model double-escaped and is materially harder to read than a sentence, and a
+ * model that cannot read a refusal cannot correct it. So every error here
+ * renders as ONE sentence:
+ *
+ *     <code> <class>: <problem>[ - <detail>]. Next: <the exact call that resolves it>.
+ *
+ * The leading `<code> <class>` pair is STABLE and greppable, so a consumer that
+ * is not an LLM — a test, a board badge, a log grep — can branch on it without
+ * parsing prose. The `Next:` clause names a real tool call, because "invalid
+ * input" without a route is a refusal the caller can only guess at.
+ *
+ * Codes are `RM<group><serial>` where the THIRD character is the class group:
+ * 1 input, 2 value, 3 workspace, 4 state, 5 runtime, 6 capability. Because the
+ * group is embedded in the code, a log grep for `RM1` finds every input-shaped
+ * failure without knowing this registry — and `tests/errors.spec.ts` asserts the
+ * third character matches the entry's own class, so the grouping cannot drift.
+ */
+
+/** What kind of thing went wrong. Stable vocabulary — consumers branch on it. */
+export type ToolErrorClass = 'input' | 'value' | 'workspace' | 'state' | 'runtime' | 'capability'
+
+export interface ToolErrorSpec {
+  /** Stable `RM<group><serial>` code. Never reuse one for a different problem. */
+  code: string
+  klass: ToolErrorClass
+  /** The fixed problem statement, no trailing punctuation. */
+  problem: string
+  /** What resolves it, naming the exact call. No trailing punctuation. */
+  next: string
+}
+
+/**
+ * The registry. Every `recursive_*` tool error must come from here: a tool that
+ * invents its own sentence is a tool whose refusals cannot be grepped, and
+ * `tests/errors.spec.ts` asserts the codes are unique and well formed so the
+ * registry cannot rot into duplicates.
+ */
+export const TOOL_ERRORS = {
+  /* 1xxx — input the caller must supply. */
+  BAD_PROBE_ARGUMENTS: {
+    code: 'RM1144',
+    klass: 'input',
+    problem: 'probeArguments is not a JSON object',
+    next: 'pass a JSON object such as {"artifact":"01-as-is.md"} so the preview can evaluate the guard against real arguments',
+  },
+  BAD_ASK_GATE: {
+    code: 'RM1141',
+    klass: 'input',
+    problem: 'the requested human gate is not one of tdd-mode, qa-signoff or gate-block',
+    next: 'call recursive_ask with gate: tdd-mode | qa-signoff | gate-block',
+  },
+  BAD_ASK_ANSWER: {
+    code: 'RM1142',
+    klass: 'input',
+    problem: 'the answer is not one of the labels the gate offered',
+    next: 'use one of the labels the ask returned; an unoffered answer reads as a decision while being a transcription error',
+  },
+  MISSING_ASK_ARTIFACT: {
+    code: 'RM1143',
+    klass: 'input',
+    problem: 'this gate has no default artifact, so one must be named',
+    next: 'pass artifact: <file> so the answer has somewhere durable to land',
+  },
+  MISSING_RUN_ID: {
+    code: 'RM1101',
+    klass: 'input',
+    problem: 'runId is required',
+    next: 'call recursive_status with no runId to see the latest run id in this workspace',
+  },
+  MISSING_ARTIFACT: {
+    code: 'RM1102',
+    klass: 'input',
+    problem: 'artifact is required',
+    next: 'call recursive_phase to see which artifact the run is currently on',
+  },
+  MISSING_PHASE_AND_RUN: {
+    code: 'RM1103',
+    klass: 'input',
+    problem: 'phase and runId are required',
+    next: 'call recursive_status to read the run id, then pass phase as 04|05|06|07|08',
+  },
+  MISSING_SCRATCH_ARGS: {
+    code: 'RM1104',
+    klass: 'input',
+    problem: 'action, runId and target are all required',
+    next: 'call recursive_scratch with action=read|write|append, a runId, and target=md|ts',
+  },
+  MISSING_CREATE_RUN_ID: {
+    code: 'RM1105',
+    klass: 'input',
+    problem: 'runId is required for create',
+    next: 'call recursive_init with a runId to scaffold the run first',
+  },
+  MISSING_PROMOTE_BRANCHES: {
+    code: 'RM1106',
+    klass: 'input',
+    problem: 'fromBranch and toBranch are required for promote',
+    next: 'call recursive_worktree with action=promote plus fromBranch and toBranch',
+  },
+
+  /* 2xxx — a supplied value is outside its allowed set. */
+  BAD_TARGET: {
+    code: 'RM2201',
+    klass: 'value',
+    problem: 'target must be md or ts',
+    next: 'pass target=md for /.recursive/run/<id>/scratch/scratch.md or target=ts for scratch.ts',
+  },
+  BAD_ACTION: {
+    code: 'RM2202',
+    klass: 'value',
+    problem: 'action must be create | promote | status',
+    next: 'pass action=create, action=promote or action=status',
+  },
+
+  /* 3xxx — the session is not attached to a control plane. */
+  NO_WORKSPACE: {
+    code: 'RM3301',
+    klass: 'workspace',
+    problem: 'this session is not attached to a registered workspace',
+    next: 'open the session inside a workspace directory; the control-plane root is resolved from the session cwd',
+  },
+
+  /* 4xxx — the workspace exists but the state the call needs does not. */
+  NO_RUN: {
+    code: 'RM4401',
+    klass: 'state',
+    problem: 'no recursive run exists in this workspace',
+    next: 'call recursive_init with a runId to scaffold the first run',
+  },
+  NO_PHASE: {
+    code: 'RM4402',
+    klass: 'state',
+    problem: 'no current recursive phase could be determined',
+    next: 'call recursive_init to scaffold the run, or recursive_status to inspect why every phase is locked',
+  },
+
+  PENDING_WORK: {
+    code: 'RM4403',
+    klass: 'state',
+    problem: 'the run has unresolved delegated work, so this phase cannot lock yet',
+    next: 'call recursive_status to see the pending delegation, have the child write its reply.md, then lock again',
+  },
+
+  /* 5xxx — the runtime refused an operation it understands. */
+
+  RUNTIME_REFUSED: {
+    code: 'RM5501',
+    klass: 'runtime',
+    problem: 'the recursive runtime refused the operation',
+    next: 'fix the cause named in the detail and retry; a gate refusal names the artifact and its status',
+  },
+
+  /* 6xxx — an optional host service is absent (the plugin degrades, never crashes). */
+  TEAM_SERVICE_UNAVAILABLE: {
+    code: 'RM6601',
+    klass: 'capability',
+    problem: 'the agent-teams service is not available in this composition',
+    next: 'use recursive_lock and recursive_lint directly, or mount a composition that provides ctx.agentTeams',
+  },
+} as const satisfies Record<string, ToolErrorSpec>
+
+export type ToolErrorName = keyof typeof TOOL_ERRORS
+
+/**
+ * Render one registry entry as the single sentence a tool returns.
+ * `detail` carries the run-specific part (a run id, an artifact, a gate).
+ */
+export function toolError(name: ToolErrorName, detail?: string): string {
+  const spec: ToolErrorSpec = TOOL_ERRORS[name]
+  const head = spec.code + ' ' + spec.klass + ': ' + spec.problem
+  const withDetail = detail && detail.trim() !== '' ? head + ' - ' + detail.trim() : head
+  return withDetail + '. Next: ' + spec.next + '.'
+}
+
+/** True when a string already carries a registry code — used to avoid double-wrapping. */
+export function hasToolErrorCode(message: string): boolean {
+  return /^RM\d{4}\b/.test(message.trim())
+}
+
+/**
+ * Give a thrown runtime message a stable code WITHOUT nesting one that is
+ * already there.
+ *
+ * A refusal the runtime already expressed in this registry's vocabulary (for
+ * example `RM4403` pending work) is passed through untouched: wrapping it would
+ * bury the real code inside `RM5501`'s detail and make the greppable handle
+ * useless, which is the whole reason the registry exists. A bare thrown message
+ * has no code to branch on, so it is wrapped and its sentence survives as the
+ * detail.
+ */
+export function codeRuntimeRefusal(message: string): string {
+  return hasToolErrorCode(message) ? message : toolError('RUNTIME_REFUSED', message)
+}

package/src/git-context.ts

@@ -49,8 +49,7 @@ export function gitRun(repoRoot: string, ...args: string[]): string | null {
 }
 
 /** True when a non-equal git-dir vs git-common-dir marks a linked worktree. */
-export function isLinkedWorktree(gitDir: string | null, commonDir: string | null): boolean {
-  if (!gitDir || !commonDir) return false
+export function isLinkedWorktree(gitDir: string | null, commonDir: string | null): boolean {  if (!gitDir || !commonDir) return false
   return gitDir !== commonDir
 }
 
@@ -130,3 +129,35 @@ export function verifyWorktreeBranch(repoRoot: string, recordedBranch: string |
   if (live !== recordedBranch) return { ok: false, reason: `checkout is on branch '${live}' but 00-worktree.md records '${recordedBranch}'` }
   return { ok: true, reason: null }
 }
+
+/**
+ * FU-4 — the paths this checkout has actually changed, for the memory loader's path weighting.
+ *
+ * WHY IT EXISTS. T29's selection weights a shard that names a path the run has changed **above** one that
+ * merely shares wording with the query — but nothing computed those paths, so the weighting was exercised
+ * by tests and never by a run. A weighting that is never fed is a rule that does not exist in production.
+ *
+ * ⚠ IT REUSES `gitRun` AND THE SAME TWO QUERIES `ts-lint.ts` ALREADY USES (`diff --name-only` for tracked
+ * changes, `ls-files --others` for new files). A second way of asking git the same question is a second
+ * thing to get subtly wrong — and the lint path is the one with a parity golden behind it.
+ *
+ * ⚠ IT IS CAPPED, AND IT IS BEST-EFFORT. Uncapped, a large checkout would let path matches swamp the
+ * query score entirely, so the list is capped; and a repo where git fails returns `[]` rather than
+ * throwing, because a memory hint must never be the reason a phase call fails.
+ */
+export const MAX_CHANGED_PATHS = 50
+
+export function changedPaths(repoRoot: string, limit: number = MAX_CHANGED_PATHS): string[] {
+  const tracked = gitRun(repoRoot, 'diff', '--name-only', 'HEAD')
+  const untracked = gitRun(repoRoot, 'ls-files', '--others', '--exclude-standard')
+  const paths: string[] = []
+  for (const blob of [tracked, untracked]) {
+    if (blob === null) continue
+    for (const line of blob.split('\n')) {
+      const path = line.trim().replace(/\\/g, '/')
+      if (path !== '' && !paths.includes(path)) paths.push(path)
+      if (paths.length >= limit) return paths
+    }
+  }
+  return paths
+}