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

package/src/model-inventory.ts

@@ -0,0 +1,196 @@
+/**
+ * ⚠ FU-19 — THE PROVIDER AND MODEL INVENTORY, RESOLVED FROM DSH ITSELF.
+ *
+ * The requirement, in the user's words: *"provider and model inventory should be resolved from dsh itself, we only
+ * concern ourselves with what is configured inside dsh."* So this module does not keep a list, does not ship a
+ * table of known models, and does not guess. It asks the host what it has.
+ *
+ * ## Where the truth lives (measured, not assumed)
+ *
+ * `packages/llm/llm/src/index.ts` does `super(ctx, 'llm')`, so the service a plugin reaches is `ctx.llm`:
+ *
+ *   - `ctx.llm.listProviders()`                        → the providers DSH has
+ *   - `await ctx.llm.listModels(providerId)`           → that provider's models
+ *   - `await ctx.llm.resolveModelInfo(providerId, id)` → model detail (reasoning efforts, defaults)
+ *
+ * `api/session-controller/src/catalog.ts` builds the BROWSER model catalog from exactly that trio, so a plugin
+ * reading the same calls is reading what the UI shows. The service is resolved as an OPTIONAL seam, like every
+ * other host service this plugin uses.
+ *
+ * ## ⚠ TWO DIFFERENT THINGS ARE CALLED "PROVIDER", AND CONFLATING THEM WAS A REAL DEFECT IN THIS FEATURE
+ *
+ *   - a **SUBAGENT provider** creates the child — `spawn`, `fork` — and comes from `ctx.subagents.list()`;
+ *   - an **LLM provider** serves the model — `deepseek-official` — and comes from `ctx.llm.listProviders()`.
+ *
+ * A policy field called plain `provider` could mean either, and a user setting it would have no way to know which.
+ * So this module deals ONLY in the second kind, and the policy names it `modelProvider` for exactly that reason.
+ *
+ * ## ⚠ THE THREE-STATE VERDICT, WHICH IS THE POINT OF THE WHOLE MODULE
+ *
+ * A checker that answers only yes/no forces a lie in one direction or the other: either an unverifiable choice is
+ * reported as fine (a silent pass, which this project has fixed ten times over) or it is reported as wrong (a
+ * refusal to do something the user asked for, on the strength of a service that merely was not mounted). The
+ * verdict therefore has three states, and `unverified` is not a synonym for either:
+ *
+ *   - `available`  — the model is in the inventory; the choice is real
+ *   - `missing`    — the inventory answered and does NOT have it; the caller should say so, and must NOT swap it
+ *   - `unverified` — there was no inventory to ask; nothing is claimed, and nothing is replaced
+ */
+import type { SubagentProviderLike } from './router.ts'
+
+/**
+ * The structural view of `ctx.llm` this module needs. Structural rather than imported, like every other seam in
+ * this plugin: the harness packages are peer dependencies, and a plugin that imported their types would not load
+ * on a host that mounts a compatible service under its own class.
+ */
+export interface LlmInventoryLike {
+  listProviders(): ReadonlyArray<{ id: string }>
+  listModels(providerId: string): Promise<ReadonlyArray<{ id: string }>> | ReadonlyArray<{ id: string }>
+}
+
+/** One provider and the models it advertises. */
+export interface InventoryProvider {
+  id: string
+  models: string[]
+}
+
+/** The inventory, when there was one to read. */
+export interface InventoryAvailable {
+  available: true
+  providers: InventoryProvider[]
+  /** One sentence naming what was read, for the record. */
+  note: string
+}
+
+/** The inventory was not readable, and why — never an empty inventory pretending to be one. */
+export interface InventoryUnavailable {
+  available: false
+  reason: string
+}
+
+export type ModelInventory = InventoryAvailable | InventoryUnavailable
+
+/**
+ * Read the provider/model inventory from the host.
+ *
+ * Never throws: a provider whose model list fails is recorded with a NAME and no models rather than dropping the
+ * whole inventory, because "this provider would not answer" and "there are no providers" are different facts.
+ */
+export async function describeInventory(llm: LlmInventoryLike | null | undefined): Promise<ModelInventory> {
+  if (llm === null || llm === undefined) {
+    return {
+      available: false,
+      reason: 'no llm service is mounted, so the provider and model inventory could not be read from DSH',
+    }
+  }
+  let providerIds: string[]
+  try {
+    providerIds = llm.listProviders().map((entry) => entry.id).filter((id) => typeof id === 'string' && id !== '')
+  } catch (err) {
+    return { available: false, reason: 'llm.listProviders() failed: ' + (err instanceof Error ? err.message : String(err)) }
+  }
+
+  const providers: InventoryProvider[] = []
+  for (const id of providerIds) {
+    try {
+      const models = await llm.listModels(id)
+      providers.push({ id, models: models.map((model) => model.id).filter((modelId) => typeof modelId === 'string' && modelId !== '') })
+    } catch {
+      // Named, kept, and empty: a provider that would not answer is not the same as a provider with no models.
+      providers.push({ id, models: [] })
+    }
+  }
+  return {
+    available: true,
+    providers,
+    note: 'read from DSH: ' + providers.length + ' provider(s), '
+      + providers.reduce((sum, provider) => sum + provider.models.length, 0) + ' model(s)',
+  }
+}
+
+/** Which LLM provider advertises a model id — the lookup that makes `modelProvider` optional for the user. */
+export function findModelProvider(inventory: ModelInventory, modelId: string): string | null {
+  if (!inventory.available) return null
+  const wanted = modelId.trim()
+  if (wanted === '') return null
+  for (const provider of inventory.providers) {
+    if (provider.models.includes(wanted)) return provider.id
+  }
+  return null
+}
+
+export type ChoiceVerdict = 'available' | 'missing' | 'unverified'
+
+export interface ChoiceCheck {
+  verdict: ChoiceVerdict
+  /** One sentence, always present, always saying which of the three states this is and why. */
+  reason: string
+}
+
+/**
+ * Check a model choice against the inventory — and say `unverified` rather than guessing when there is none.
+ *
+ * ⚠ IT NEVER CHANGES THE CHOICE. A caller that receives `missing` must report it; it must not quietly substitute
+ * a model the inventory does have, because silently running a child on a different model than the user asked for
+ * is precisely the failure this whole feature exists to prevent.
+ */
+export function checkModelChoice(
+  inventory: ModelInventory,
+  modelId: string,
+  modelProvider?: string | null,
+): ChoiceCheck {
+  const model = modelId.trim()
+  if (model === '') {
+    return { verdict: 'unverified', reason: 'no model was chosen, so the child inherits the session default' }
+  }
+  if (!inventory.available) {
+    return {
+      verdict: 'unverified',
+      reason: 'model ' + model + ' is UNVERIFIED: ' + inventory.reason
+        + ' — it was neither accepted as available nor replaced with another',
+    }
+  }
+  const named = typeof modelProvider === 'string' && modelProvider.trim() !== '' ? modelProvider.trim() : null
+  if (named !== null) {
+    const provider = inventory.providers.find((entry) => entry.id === named)
+    if (provider === undefined) {
+      return { verdict: 'missing', reason: 'model provider ' + named + ' is not one DSH has: ' + providerIdsText(inventory) }
+    }
+    return provider.models.includes(model)
+      ? { verdict: 'available', reason: 'model ' + model + ' is available from ' + named }
+      : { verdict: 'missing', reason: 'provider ' + named + ' does not advertise model ' + model }
+  }
+  const owner = findModelProvider(inventory, model)
+  return owner === null
+    ? { verdict: 'missing', reason: 'no provider DSH has advertises model ' + model + ': ' + providerIdsText(inventory) }
+    : { verdict: 'available', reason: 'model ' + model + ' is available from ' + owner }
+}
+
+/** The provider ids, for a message that tells the caller what IS available instead of only what is not. */
+export function providerIdsText(inventory: ModelInventory): string {
+  if (!inventory.available) return '(inventory unavailable)'
+  if (inventory.providers.length === 0) return '(no providers)'
+  return inventory.providers.map((provider) => provider.id).join(', ')
+}
+
+/**
+ * Which subagent providers the host actually offers — the OTHER kind of provider, kept adjacent on purpose so the
+ * two are never confused in a message.
+ */
+export function subagentProviderNames(seam: { list?: () => unknown } | null | undefined): string[] {
+  if (seam === null || seam === undefined || typeof seam.list !== 'function') return []
+  try {
+    const listed = seam.list()
+    return Array.isArray(listed) ? listed.filter((entry): entry is string => typeof entry === 'string') : []
+  } catch {
+    return []
+  }
+}
+
+/** The declared capabilities of a subagent provider, or null when it is not registered. */
+export function capabilitiesOf(
+  providers: Record<string, SubagentProviderLike>,
+  name: string,
+): SubagentProviderLike['capabilities'] | null {
+  return providers[name]?.capabilities ?? null
+}

package/src/phase-graph.ts

@@ -0,0 +1,191 @@
+/**
+ * T17 — the phase dependency as a GRAPH, not a flat sequence.
+ *
+ * WHY. Three core queries in this plugin are graph operations being run over a linear array:
+ * `getStaleDownstreamPhases` is a REACHABILITY query, `getPrerequisites` is an IN-EDGE query, and
+ * `getNextLegalPhase` is a topological walk. An array can answer all three only while the dependency
+ * happens to be linear — and the moment an artifact depends on something LATER than itself (an
+ * addendum written to close an upstream gap), the array model answers *wrongly* rather than not at
+ * all. That is the case this module exists to get right.
+ *
+ * ⚠ A HAND-ROLLED GRAPH, DELIBERATELY. The item's note is explicit: Effect ships a stable,
+ * runtime-free `Graph` doing exactly this, and adopting it would trade this plugin's zero-dependency
+ * posture and its parity goldens for a few hundred lines it does not need. The queries below are
+ * small because the graph is small.
+ *
+ * ⚠ BACK-EDGES ARE FIRST-CLASS, NOT AN ERROR. An `upstream-gap` addendum legitimately points at a
+ * LATER artifact: the gap was discovered downstream and must be closed upstream. A depth-first walk
+ * with a VISITED set answers reachability over such a graph; a walk without one loops forever, and an
+ * array cannot express the edge at all.
+ */
+
+/** One node: an artifact on disk, or one being asked about before it exists. */
+export interface PhaseNode {
+  /** Artifact file name, the node's identity. */
+  id: string
+  /** Position in the canonical sequence — used for ordering, NOT as the dependency model. */
+  index: number
+  /** Whether the artifact is on disk. A queried, absent node emits no prerequisite edge. */
+  present?: boolean
+  /** Whether the artifact is locked, when the caller knows. */
+  locked?: boolean
+}
+
+/** One directed edge: `to` depends on `from`. */
+export interface PhaseEdge {
+  from: string
+  to: string
+  /** `prerequisite` — an earlier artifact that must be locked first. `addendum` — a cited dependency. */
+  kind: 'prerequisite' | 'addendum'
+}
+
+export interface PhaseGraph {
+  nodes: PhaseNode[]
+  edges: PhaseEdge[]
+}
+
+/**
+ * Build the graph for one run.
+ *
+ * `sequence` is the canonical phase order; `present` is what exists on disk, so a phase that was
+ * never created is not a node and cannot be waited on forever. `addenda` are the cited dependencies a
+ * document declares — including ones pointing FORWARD, which is what makes the graph a graph.
+ */
+export function buildPhaseGraph(input: {
+  sequence: readonly string[]
+  present: readonly string[]
+  locked?: readonly string[]
+  /** Declared dependencies: `from` must be settled before `to`. Order is irrelevant. */
+  citations?: ReadonlyArray<{ from: string; to: string }>
+  /**
+   * Artifacts to answer ABOUT, whether or not they exist yet.
+   *
+   * ⚠ THIS EXISTS BECAUSE OF A MEASURED PARITY FAILURE, and it is the item's central modelling gap:
+   * with nodes limited to what is present, a query about an artifact **that does not exist yet**
+   * found no in-edges and answered `[]` — but checking prerequisites **before creating** the artifact
+   * is the NORMAL case, so that made every pre-write check silently vacuous. A queried node is
+   * therefore a node for EDGE TARGETS ONLY: it emits no outgoing prerequisite edge, because an
+   * artifact that does not exist cannot block anything.
+   */
+  queried?: readonly string[]
+}): PhaseGraph {
+  const presentSet = new Set(input.present)
+  const lockedSet = new Set(input.locked ?? [])
+  const queriedSet = new Set(input.queried ?? [])
+  const nodes: PhaseNode[] = input.sequence
+    .map((id, index) => ({ id, index }))
+    .filter((node) => presentSet.has(node.id) || queriedSet.has(node.id))
+    .map((node) => ({
+      ...node,
+      // `present` is what makes the source rule below possible: a queried-but-absent node is a
+      // question, not a dependency.
+      present: presentSet.has(node.id),
+      locked: lockedSet.has(node.id),
+    }))
+
+  const indexOf = new Map(input.sequence.map((id, index) => [id, index]))
+  const ids = new Set(nodes.filter((node) => node.present === true).map((node) => node.id))
+  const edges: PhaseEdge[] = []
+
+  // PREREQUISITE edges: every earlier PRESENT artifact blocks this one. Restricted to what exists so a
+  // missing phase cannot hold a run hostage, and emitted only FROM present nodes so a queried one
+  // cannot appear as anybody's prerequisite.
+  for (const node of nodes) {
+    for (const other of nodes) {
+      if (other.present !== true) continue
+      if (other.index < node.index) edges.push({ from: other.id, to: node.id, kind: 'prerequisite' })
+    }
+  }
+
+  // ADDENDUM edges: the declared citations, in either direction. Deduplicated so a citation that
+  // coincides with a prerequisite is ONE edge, not two.
+  const seen = new Set(edges.map((edge) => edge.from + '\u0000' + edge.to))
+  for (const citation of input.citations ?? []) {
+    if (!ids.has(citation.from) || !ids.has(citation.to)) continue
+    const key = citation.from + '\u0000' + citation.to
+    if (seen.has(key)) continue
+    seen.add(key)
+    edges.push({ from: citation.from, to: citation.to, kind: 'addendum' })
+  }
+
+  return { nodes, edges }
+}
+
+/** The nodes that must be settled before `id` — the IN-EDGE query. */
+export function prerequisitesOf(graph: PhaseGraph, id: string): string[] {
+  return graph.edges.filter((edge) => edge.to === id).map((edge) => edge.from)
+}
+
+/** The artifacts that depend, directly, on `id` — the OUT-EDGE query. */
+export function dependentsOf(graph: PhaseGraph, id: string): string[] {
+  return graph.edges.filter((edge) => edge.from === id).map((edge) => edge.to)
+}
+
+/**
+ * Everything reachable downstream of `id` — the REACHABILITY query behind `getStaleDownstreamPhases`.
+ *
+ * ⚠ The VISITED set is load-bearing, not defensive: a back-edge makes the graph cyclic, and a walk
+ * without a visited set recurses forever on exactly the input this item exists to support.
+ */
+export function reachableFrom(graph: PhaseGraph, id: string): string[] {
+  const seen = new Set<string>()
+  const queue = [id]
+  while (queue.length > 0) {
+    const current = queue.shift() as string
+    for (const next of dependentsOf(graph, current)) {
+      if (seen.has(next)) continue
+      seen.add(next)
+      queue.push(next)
+    }
+  }
+  seen.delete(id)
+  return graph.nodes.map((node) => node.id).filter((nodeId) => seen.has(nodeId))
+}
+
+/**
+ * The next phase a run may work on.
+ *
+ * ⚠ THIS MODELS THE SHIPPED RULES EXACTLY, because `lock.ts` delegates to it and `lock.parity.spec.ts`
+ * is the proof. Three of them are easy to miss and are asserted in the spec:
+ *   1. a LOCKED node is skipped;
+ *   2. a node that is **absent and declared OPTIONAL** is skipped — an optional phase nobody created
+ *      must not stop the run;
+ *   3. if the first node that survives 1 and 2 has a prerequisite that is not LOCKED, the answer is
+ *      **`null`, NOT the next node** — the run is BLOCKED, and returning the node after it would
+ *      silently skip a dependency.
+ *
+ * ⚠ RULE 3 IS WHERE A GRAPH EARNS ITS KEEP, and it is invisible in a linear array: with a back-edge
+ * (an `upstream-gap` addendum citing a LATER artifact), an EARLY unlocked node can be blocked by a
+ * LATER one — so "continue to the next node" and "blocked, report null" give different answers, and
+ * only the second is correct.
+ *
+ * Nodes must cover the whole sequence for this query (an absent, required phase is a legitimate
+ * answer); `queried` is how the caller supplies them.
+ */
+export function nextLegalPhase(
+  graph: PhaseGraph,
+  options: { optional?: ReadonlySet<string> } = {},
+): string | null {
+  const optional = options.optional ?? new Set<string>()
+  const locked = new Set(graph.nodes.filter((node) => node.locked === true).map((node) => node.id))
+  const ordered = [...graph.nodes].sort((a, b) => a.index - b.index)
+  for (const node of ordered) {
+    if (locked.has(node.id)) continue
+    if (node.present !== true && optional.has(node.id)) continue
+    const blocked = prerequisitesOf(graph, node.id).some((from) => !locked.has(from))
+    if (blocked) return null
+    return node.id
+  }
+  return null
+}
+
+/**
+ * Whether the graph has a back-edge — an edge pointing at a LATER phase than its source.
+ *
+ * Reported rather than hidden: a back-edge is legitimate (an upstream gap), and it is exactly the
+ * shape a linear model cannot represent. A caller that wants to warn about it should be able to ask.
+ */
+export function backEdges(graph: PhaseGraph): PhaseEdge[] {
+  const indexOf = new Map(graph.nodes.map((node) => [node.id, node.index]))
+  return graph.edges.filter((edge) => (indexOf.get(edge.to) ?? 0) < (indexOf.get(edge.from) ?? 0))
+}

package/src/phase-rules.ts

@@ -6,6 +6,11 @@
  * injection. Values are byte-identical to the canonical linter (recursive-
  * mode-audit-v2).
  */
+import { join, resolve, sep } from 'node:path'
+import {
+  tddEvidenceVerdict as tddEvidenceMatch,
+  type ToolPolicy, type ToolPolicyRule, type ToolPolicyContext, type Verdict,
+} from './policy-globs.ts'
 
 export const CURRENT_WORKFLOW_PROFILE = 'recursive-mode-audit-v2'
 export const STRICT_WORKFLOW_PROFILE = 'recursive-mode-audit-v1'
@@ -303,3 +308,234 @@ export function phaseLintRulesMessage(fileName: string, workflowProfile: string
   ]
   return lines.join('\n')
 }
+
+/* -------------------------------------------------------------------------- */
+/* T16 — per-phase baseline tool policy (NARROWING ONLY)                      */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * How restrictive a verdict is, lower = stricter. `deny` < `ask` < `allow`.
+ * This ordering IS the narrowing rule: a phase baseline may replace a global
+ * verdict with a lower-ranked one, and never with a higher-ranked one. It also
+ * explains the engine's "deny wins over allow" claim in rank terms — deny is
+ * the minimum, so nothing a phase adds can soften it.
+ */
+const VERDICT_RANK: Record<Verdict, number> = { deny: 0, ask: 1, allow: 2 }
+
+export function policyVerdictRank(verdict: Verdict): number {
+  return VERDICT_RANK[verdict]
+}
+
+/**
+ * The phase number an artifact belongs to: the leading digits of its canonical
+ * filename (`03-implementation-summary.md` -> `3`). Returns `''` when the
+ * filename carries no phase number, so a caller can skip the baseline rather
+ * than guess.
+ */
+export function phaseNumberForArtifact(fileName: string): string {
+  const match = /^(\d+)/.exec(fileName)
+  if (!match) return ''
+  return String(Number(match[1]))
+}
+
+function isUnder(root: string, target: string): boolean {
+  const rootAbs = resolve(root)
+  const targetAbs = resolve(target)
+  const prefix = rootAbs.endsWith(sep) ? rootAbs : rootAbs + sep
+  return targetAbs !== rootAbs && targetAbs.startsWith(prefix)
+}
+
+/** True when the path is inside the run tree this phase is writing. */
+function insideRunTree(path: string, runDir: string | undefined): boolean {
+  if (!runDir) return false
+  return isUnder(runDir, path)
+}
+
+/**
+ * The absolute target of a call, or `'unresolvable'` when it cannot be placed.
+ * An unresolvable target FAILS CLOSED in every baseline below: "we could not
+ * tell where this write lands" is not a reason to allow it. A caller with no
+ * worktree root can still place an ABSOLUTE target; a relative one it cannot.
+ */
+function baselineTarget(args: Record<string, unknown>, ctx: ToolPolicyContext): string | 'unresolvable' {
+  const target = policyTargetPath(args)
+  if (!target) return 'unresolvable'
+  const normalized = target.replace(/\\/g, '/')
+  if (!ctx.worktreeRoot && !isAbsolutePath(normalized)) return 'unresolvable'
+  const abs = resolveFrom(ctx.worktreeRoot ?? '/', target)
+  return abs ?? 'unresolvable'
+}
+
+function isAbsolutePath(normalized: string): boolean {
+  return /^[A-Za-z]:\//.test(normalized) || normalized.startsWith('/')
+}
+
+/**
+ * PER-PHASE BASELINE (plan §4 T16). Additive, phase-scoped rules that can only
+ * NARROW the global policy. Three honest limits, stated here rather than hidden:
+ *
+ *   1. The two structures the plan names — phase 6 "writes only under
+ *      `.recursive/DECISIONS.md`" and phase 8 "only under `.recursive/memory/**`"
+ *      — as ABSOLUTE path scopes would also forbid the normal artifact edits of
+ *      those phases, so they are implemented as the narrower rules that bite
+ *      without blocking the phase's own work: no source-tree writes in phases
+ *      6-8 (by then the repo changes are done and the run documents its
+ *      decisions/state/memory), and the memory planes are read-only in phases
+ *      1-2 and 6-7. `deny` on `write` in phase 6 is also deliberately absent,
+ *      because phase 6's own artifact is `<run>/06-decisions-update.md` and a
+ *      blanket write denial would make the phase uncompletable.
+ *   2. Narrowing is enforced MECHANICALLY in withPhaseBaseline, not by trusting
+ *      this table: a phase rule whose verdict is ranked above the strictest
+ *      global verdict for the same pattern — which would widen `ask` to `allow`,
+ *      or soften a global `deny` — is DROPPED before it can be evaluated.
+ *   3. No rule below uses the bare catch-all `*`. A phase rule of that shape
+ *      would outrank every specific global rule at once (precedence is
+ *      specificity-first), including `recursive_lock*`, and would deny the phase
+ *      its own tools. The write-tool family is spelled `write*`.
+ *
+ * Phase 3's TDD-evidence rule is the one the plan states verbatim: a phase-3
+ * lock is denied until RED + GREEN evidence exists. It is reached for the phase
+ * whose artifact is the current one, i.e. the phase-3 lock itself — before that
+ * point the earlier phases are still unlocked, so the global lock-order rule
+ * already refuses.
+ */
+export function phaseBaselineRules(fileName: string): ToolPolicyRule[] {
+  const phase = phaseNumberForArtifact(fileName)
+  const rules: ToolPolicyRule[] = []
+
+  if (phase === '3') {
+    // Narrowing: the global `recursive_lock` rule denies a lock whose
+    // prerequisites are unmet. This adds a SECOND, stronger condition on the
+    // SAME tool — TDD evidence before the phase-3 lock — which the tool itself
+    // does not check.
+    rules.push({
+      pattern: 'recursive_lock*',
+      verdict: 'deny',
+      reason: 'TDD Mode: strict requires RED + GREEN evidence before locking Phase 3',
+      label: 'tdd-evidence',
+      predicate: (_id, args, ctx) => tddEvidenceMatch(String(args.artifact ?? ''), ctx.runDir),
+    })
+  }
+
+  if (phase === '6' || phase === '7' || phase === '8') {
+    // Late phases document, they do not change the implementation. Scope: the
+    // write-tool family only (`write*`), so this narrowing cannot touch a
+    // read/status/lock tool — and so it outranks a catch-all `allow` in the
+    // global policy even when that allow is listed FIRST (T16 precedence is
+    // specificity-first).
+    rules.push({
+      pattern: 'write*',
+      verdict: 'deny',
+      reason: 'phase ' + phase + ' is a documentation phase: writes outside the run tree are denied (the implementation is frozen)',
+      predicate: (_id, args, ctx) => (writesOutsideRunTree(args, ctx) ? { verdict: 'deny' } : null),
+    })
+  }
+
+  if (phase === '6' || phase === '7') {
+    // `06-decisions-update.md` / `07-state-update.md` transcribe decisions and
+    // state into their memory planes; phase 8 is where those planes are shaped.
+    rules.push({
+      pattern: 'write*',
+      verdict: 'deny',
+      reason: 'phase ' + phase + ' writes no memory plane: .recursive/DECISIONS.md|STATE.md and .recursive/memory/** are written by their own phases',
+      predicate: (_id, args, ctx) => (writesMemoryPlane(args, ctx) ? { verdict: 'deny' } : null),
+    })
+  }
+
+  if (phase === '1' || phase === '2') {
+    // Phases 1-2 characterize and plan; they do not write the memory the run
+    // only earns later. Scope: the memory planes only, so no other write
+    // (including a repo source write a plan legitimately needs) is affected.
+    rules.push({
+      pattern: 'write*',
+      verdict: 'deny',
+      reason: 'phase ' + phase + ' writes no memory plane: .recursive/memory/** and .recursive/DECISIONS.md|STATE.md are earned at phases 6-8',
+      predicate: (_id, args, ctx) => (writesMemoryPlane(args, ctx) ? { verdict: 'deny' } : null),
+    })
+  }
+
+  return rules
+}
+
+/**
+ * True when the call writes OUTSIDE the run tree. A target that cannot be
+ * resolved counts as outside: the baseline cannot prove the write lands in the
+ * run tree, and "we could not tell" is not a reason to allow it.
+ */
+function writesOutsideRunTree(args: Record<string, unknown>, ctx: ToolPolicyContext): boolean {
+  const abs = baselineTarget(args, ctx)
+  if (abs === 'unresolvable') return true
+  return !insideRunTree(abs, ctx.runDir)
+}
+
+/** True when the call writes one of the run's memory planes. */
+function writesMemoryPlane(args: Record<string, unknown>, ctx: ToolPolicyContext): boolean {
+  const abs = baselineTarget(args, ctx)
+  if (abs === 'unresolvable') return true
+  return memoryPlanePath(abs)
+}
+
+/** True when the absolute path names one of the run's memory planes. */
+function memoryPlanePath(abs: string): boolean {
+  const normalized = abs.replace(/\\/g, '/')
+  return /\/(decisions|state)\.md$/i.test(normalized) || /\/\.recursive\/memory(\/|$)/.test(normalized)
+}
+
+/**
+ * Resolve a tool-target path to an absolute path. Mirrors enforcement.ts's
+ * resolution rules: an absolute path stays as it is; a relative path resolves
+ * against the worktree root. `null` when the value cannot be a path at all.
+ */
+export function resolveFrom(worktreeRoot: string, target: string): string | null {
+  const normalized = target.replace(/\\/g, '/').trim()
+  if (!normalized) return null
+  if (/^[A-Za-z]:\//.test(normalized) || normalized.startsWith('/')) return resolve(normalized)
+  return resolve(join(worktreeRoot, normalized.replace(/^\.?\/?/, '')))
+}
+
+/** The tool-target path of a call (same key order enforcement.ts uses). */
+export function policyTargetPath(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
+}
+
+/**
+ * TDD evidence predicate for a phase-3 lock: `deny` when the artifact declares
+ * `TDD Mode: strict` without both RED and GREEN evidence, `null` otherwise
+ * (nothing to say — the global rules still apply). Lives in `policy-globs.ts`
+ * beside the built-in list, which carries the same `tdd-evidence` guard rule.
+ */
+export const tddEvidenceVerdict = tddEvidenceMatch
+
+/**
+ * Compose the effective policy for a phase: the phase baseline rules FIRST (so
+ * a narrowing rule is reached before the global rule it tightens), then the
+ * global rules.
+ *
+ * NARROWING IS MECHANICAL, not a convention this table is trusted to respect. A
+ * baseline rule whose verdict is ranked ABOVE the strictest global verdict for
+ * the same pattern is DROPPED before it can be evaluated, so no per-phase
+ * baseline can turn a global `deny` into an `allow` (or an `ask` into an
+ * `allow`). A baseline rule for a pattern the global policy does not mention is
+ * always kept: it can only add a restriction.
+ */
+export function withPhaseBaseline(policy: ToolPolicy, fileName: string, runDir?: string): ToolPolicy {
+  const baseline = phaseBaselineRules(fileName)
+  if (baseline.length === 0) return policy
+  const globalRank = new Map<string, number>()
+  for (const rule of policy.rules) {
+    const rank = VERDICT_RANK[rule.verdict]
+    const known = globalRank.get(rule.pattern)
+    if (known === undefined || rank < known) globalRank.set(rule.pattern, rank)
+  }
+  const kept = baseline.filter((rule) => {
+    const rank = VERDICT_RANK[rule.verdict]
+    const known = globalRank.get(rule.pattern)
+    return known === undefined || rank <= known
+  })
+  if (kept.length === 0) return policy
+  return { ...policy, rules: [...kept, ...policy.rules] }
+}