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

package/src/closeout-standards.ts

@@ -0,0 +1,102 @@
+/**
+ * Closeout standards check (FU-12b) — does every artifact in a run fit the required standard?
+ *
+ * ⚠ WHAT THIS IS FOR, in the user's words: *"phase 6 7 8 writes the state decisions memory artifacts, and
+ * closeout just makes sure that all the artifacts fit the required standards."* The closeout does not author
+ * the ledgers. It holds the run to the standard and reports what is missing.
+ *
+ * ⚠ WHY IT READS `phase-rules` INSTEAD OF KEEPING ITS OWN LIST: the required sections already have exactly
+ * one home. `phase-rules.ts` owns them and is PROFILE-AWARE — it appends `AUDIT_REQUIRED_HEADINGS` for
+ * audited artifacts under a strict workflow profile, and `Prior Recursive Evidence Reviewed` for the files
+ * that need it. A private copy cannot match that, and this session has already produced three separate
+ * defects from exactly that duplication (the closeout's own `REQUIRED_SECTIONS`, the 00–03 stubs, and the
+ * `meta` block). So this module invents nothing: it asks the rules and reports the difference.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { getLockStatus } from './lock.ts'
+import { CURRENT_WORKFLOW_PROFILE, getArtifactRequiredSections } from './phase-rules.ts'
+import { RUN_ARTIFACT_SEQUENCE, getGateStatus, hasHeading } from './ts-lint.ts'
+
+/** Gate lines every phase document carries, as `Coverage: PASS|FAIL` / `Approval: PASS|FAIL`. */
+const UNIVERSAL_GATES = ['Coverage', 'Approval'] as const
+
+export interface StandardViolation {
+  /** Run-relative artifact name, or the sequence entry that was absent. */
+  artifact: string
+  kind: 'missing-artifact' | 'missing-section' | 'gate-not-passing' | 'not-locked'
+  /** What is wrong, spelled so a caller can print it without re-deriving anything. */
+  detail: string
+}
+
+export interface StandardsReport {
+  /** How many artifacts from the sequence were present and examined. */
+  checked: number
+  /** Artifacts in the sequence that do not exist yet — informational, not necessarily a failure. */
+  absent: string[]
+  violations: StandardViolation[]
+}
+
+export interface StandardsOptions {
+  /** Workflow profile whose rules apply; defaults to the current one, as every caller does. */
+  workflowProfile?: string
+  /**
+   * Report artifacts that are present but not LOCKED. **OFF by default**: a closeout runs mid-run and a DRAFT
+   * artifact is the normal state, so treating it as a violation would make the check useless exactly when it
+   * is most wanted. Callers that need an all-locked assertion ask for it.
+   */
+  requireLocked?: boolean
+}
+
+/**
+ * Examine every artifact in the run against the phase rules.
+ *
+ * Reports, per present artifact: required headings that are missing, gate lines that are missing or FAIL, and
+ * (only when `requireLocked`) a status that is not LOCKED. Absent artifacts are listed separately — during a
+ * closeout most of the sequence legitimately does not exist yet, and conflating "not written yet" with
+ * "written wrong" would bury the findings that matter.
+ */
+export function verifyRunStandards(runDir: string, options: StandardsOptions = {}): StandardsReport {
+  const profile = options.workflowProfile ?? CURRENT_WORKFLOW_PROFILE
+  const violations: StandardViolation[] = []
+  const absent: string[] = []
+  let checked = 0
+
+  for (const artifact of RUN_ARTIFACT_SEQUENCE) {
+    const path = join(runDir, artifact)
+    if (!existsSync(path)) { absent.push(artifact); continue }
+    checked += 1
+    let content = ''
+    try { content = readFileSync(path, 'utf8') } catch { continue }
+
+    for (const heading of getArtifactRequiredSections(artifact, profile)) {
+      if (!hasHeading(content, heading)) {
+        violations.push({ artifact, kind: 'missing-section', detail: 'missing required section: ## ' + heading })
+      }
+    }
+    for (const gate of UNIVERSAL_GATES) {
+      const status = getGateStatus(content, gate)
+      if (status !== 'PASS') {
+        violations.push({ artifact, kind: 'gate-not-passing', detail: gate + ': ' + status })
+      }
+    }
+    if (options.requireLocked === true) {
+      const status = getLockStatus(path)
+      if (status !== 'LOCKED') {
+        violations.push({ artifact, kind: 'not-locked', detail: 'status is ' + status })
+      }
+    }
+  }
+
+  return { checked, absent, violations }
+}
+
+/** One line per violation, for a tool result or a CLI print. Empty when the run fits the standard. */
+export function formatStandardsReport(report: StandardsReport): string[] {
+  const lines = report.violations.map((v) => v.artifact + ': ' + v.detail)
+  if (lines.length === 0) {
+    return ['All ' + report.checked + ' present artifact(s) fit the required standards'
+      + (report.absent.length > 0 ? ' (' + report.absent.length + ' not written yet)' : '') + '.']
+  }
+  return lines
+}

package/src/closeout.ts

@@ -1,11 +1,12 @@
 /**
  * Closeout receipt scaffolding (R2) — TS port of recursive-closeout.py.
- * Creates/updates Phase 4/5/6/7/8 delta-receipt stubs with canonical headers
+ * Creates/updates Phase 0-8 receipt stubs with canonical headers
  * and required sections, gated on prerequisite phases being LOCKED.
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
-import { getPrerequisiteBlockers } from './lock.ts'
+import { getLockStatus, getPrerequisiteBlockers } from './lock.ts'
+import { getRunTreeAddenda } from './ts-lint.ts'
 
 export interface CloseoutPhaseConfig {
   file: string
@@ -68,6 +69,7 @@ export const PHASE_CONFIG: Record<string, CloseoutPhaseConfig> = {
 }
 
 const REQUIRED_SECTIONS: Record<string, string[]> = {
+  // `recursive_lint` both know; these are the stub's minimum, not a replacement for them.
   '04': ['TODO', 'Pre-Test Implementation Audit', 'Environment', 'Execution Mode', 'Commands Executed (Exact)', 'Results Summary', 'Evidence and Artifacts', 'Failures and Diagnostics (if any)', 'Flake/Rerun Notes', 'Requirement Completion Status', 'Traceability', 'Coverage Gate', 'Approval Gate'],
   '05': ['TODO', 'Execution Mode', 'QA Execution Record', 'QA Scenarios and Results', 'User Sign-Off', 'Requirement Completion Status', 'Traceability', 'Coverage Gate', 'Approval Gate'],
   '06': ['TODO', 'Decisions Changes Applied', 'Rationale', 'Resulting Decision Entry', 'Traceability', 'Coverage Gate', 'Approval Gate'],
@@ -126,6 +128,12 @@ export interface CloseoutResult {
   file: string
   created: string[]
   existing: string[]
+  /**
+   * Every addendum found anywhere in the run tree, as run-relative paths — and cited in the scaffolded
+   * receipt. Optional on the TYPE so a caller that builds its own result literal still compiles; the
+   * closeout itself always populates it.
+   */
+  addenda?: string[]
 }
 
 export interface CloseoutOptions {
@@ -137,6 +145,12 @@ export interface CloseoutOptions {
  * Create or update a closeout receipt stub for the given phase.
  * Returns the file + created/existing lists. When strict, refuses phases whose
  * prerequisite artifacts are not all LOCKED (reuses lock.ts chain validation).
+ *
+ * ⚠ ADDENDA ARE PART OF THE CLOSEOUT WORK, and they are CITED, never written. An addendum closes a gap in
+ * an artifact that is already locked, which is precisely the kind of thing a receipt must account for — and
+ * they are not always in `addenda/`: the real ones sit beside the artifact they close, in the run ROOT. So
+ * the receipt lists every addendum in the run tree (see {@link getRunTreeAddenda}), and says so explicitly
+ * when there are none, because "we looked and found none" and "we never looked" must not read alike.
  */
 export function closeoutPhase(runDir: string, phase: string, opts: CloseoutOptions = {}): CloseoutResult {
   const config = PHASE_CONFIG[phase]
@@ -156,7 +170,25 @@ export function closeoutPhase(runDir: string, phase: string, opts: CloseoutOptio
   const filePath = join(runDir, config.file)
   const existed = existsSync(filePath)
 
+  // ⚠ FU-8 — A CLOSEOUT MUST NOT SILENTLY UNLOCK ITS OWN ARTIFACT. Found by the FU-1 harness: a
+  // closeout run after the phase had locked rewrote the file to `Status: \`DRAFT\`` while its RECEIPT
+  // still said LOCKED, leaving a run whose file and receipt disagree. The plugin publishes the rule this
+  // breaks, in the policy section a model reads every turn: *"Writes to a Status: LOCKED phase doc are
+  // denied/asked; reopen explicitly to edit."* The prerequisite check above guards EARLIER phases; this
+  // guards the artifact the closeout actually writes.
+  //
+  // ⚠ IT REFUSES RATHER THAN SKIPPING QUIETLY, and it names the remedy, because the caller's next move
+  // differs: a refusal means "reopen it first if you really mean to", while a silent skip would look
+  // like a successful closeout that changed nothing.
+  if (getLockStatus(filePath) === 'LOCKED') {
+    throw new Error(
+      'Artifact is LOCKED: ' + config.file + ' — the contract denies a write to a LOCKED phase doc; '
+      + 'reopen it explicitly (recursive_lock with reopen) before scaffolding its receipt',
+    )
+  }
+
   const runId = runDir.split(/[\\/]/).filter(Boolean).pop() ?? 'unknown-run'
+  const addenda = getRunTreeAddenda(runDir)
   const lines: string[] = [
     'Run: `/.recursive/run/' + runId + '/`',
     'Phase: `' + config.label + '`',
@@ -167,6 +199,10 @@ export function closeoutPhase(runDir: string, phase: string, opts: CloseoutOptio
     'Outputs:',
     '- `/.recursive/run/' + runId + '/' + config.file + '`',
     'Scope note: ' + config.scopeNote,
+    'Addenda:',
+    ...(addenda.length > 0
+      ? addenda.map(a => '- `/.recursive/run/' + runId + '/' + a + '`')
+      : ['- none found in the run tree']),
     '',
   ]
   for (const heading of REQUIRED_SECTIONS[phase]) {
@@ -179,5 +215,6 @@ export function closeoutPhase(runDir: string, phase: string, opts: CloseoutOptio
     file: config.file,
     created: existed ? [] : [config.file],
     existing: existed ? [config.file] : [],
+    addenda,
   }
 }

package/src/commands.ts

@@ -14,10 +14,17 @@ import { join } from 'node:path'
 import type { RecursiveRuntime } from './runtime.ts'
 import { resolveControlPlaneRoot } from './workspace.ts'
 import { bootstrapScaffold } from './bootstrap.ts'
+import { loadMemoryIndex } from './memory.ts'
+import { explainMemorySelection } from './memory-select.ts'
+import { readFeedback } from './memory-feedback.ts'
+import { closeoutReport } from './closeout-report.ts'
+import { loadRouterPolicy, routerPolicyPath } from './router.ts'
+import { resolveSubagentTarget } from './role-route.ts'
+import { writePolicySelection, type SelectionScope } from './policy-write.ts'
 
-export type RecursiveVerb = 'status' | 'spec' | 'worktree' | 'init' | 'lock' | 'qa' | 'closeout' | 'addendum' | 'review' | 'scratch' | 'bootstrap' | 'list' | 'help'
+export type RecursiveVerb = 'status' | 'spec' | 'worktree' | 'init' | 'lock' | 'qa' | 'closeout' | 'addendum' | 'review' | 'scratch' | 'memory' | 'model' | 'bootstrap' | 'list' | 'help'
 
-export const PRESET_VERBS: RecursiveVerb[] = ['status', 'spec', 'worktree', 'init', 'lock', 'qa', 'closeout', 'addendum', 'review', 'scratch']
+export const PRESET_VERBS: RecursiveVerb[] = ['status', 'spec', 'worktree', 'init', 'lock', 'qa', 'closeout', 'addendum', 'review', 'scratch', 'memory', 'model']
 export const GLOBAL_VERBS: RecursiveVerb[] = ['bootstrap', 'list', 'help']
 export const ALL_VERBS: RecursiveVerb[] = [...PRESET_VERBS, ...GLOBAL_VERBS]
 
@@ -76,6 +83,33 @@ export function executeRecursiveCommand(root: string, rawInput: string): Recursi
         : 'created ' + result.created.length + ' item(s), ' + result.existing.length + ' existing'
       return { kind: 'success', text: 'recursive-mode scaffold repair: ' + summary + ' — root ' + root }
     }
+    case 'memory': {
+      // P4 — THE SELECTOR WITH NO AGENT LOOP, printing its score COMPONENTS. The reference's loader is a
+      // script an agent runs; this is the same job on the surface the plugin already has, and it explains
+      // itself, so "why did the agent get this?" is answerable from a shell rather than only from a test.
+      const phaseMatch = arg.match(/--phase\s+([\d.]+)/)
+      const phase = phaseMatch?.[1]
+      const query = arg.replace(/--phase\s+[\d.]+/, '').trim()
+      if (query === '') {
+        return { kind: 'error', text: 'memory requires a query: /recursive memory <query> [--phase 04]' }
+      }
+      const entries = loadMemoryIndex(root)
+      if (entries.length === 0) {
+        return { kind: 'success', text: 'the memory plane is empty, so nothing is injected rather than fabricating memory' }
+      }
+      const explanation = explainMemorySelection(entries, {
+        query,
+        ...(phase === undefined ? {} : { phase }),
+        // The counters live in the sidecar; the caller reads them, exactly as the runtime does.
+        feedback: readFeedback(root),
+      })
+      const lines = [explanation.rendered]
+      if (explanation.excluded.length > 0) {
+        lines.push('', 'Excluded ' + explanation.excluded.length + ' entry(s):')
+        for (const item of explanation.excluded.slice(0, 5)) lines.push('- ' + item.title + ': ' + item.reason)
+      }
+      return { kind: 'success', text: lines.join('\n') }
+    }
     case 'closeout': {
       const phaseMatch = arg.match(/--phase\s+(\d{2})/)
       const phase = phaseMatch?.[1] ?? ''
@@ -83,7 +117,85 @@ export function executeRecursiveCommand(root: string, rawInput: string): Recursi
       if (!phase || !runId) return { kind: 'error', text: 'closeout requires <run-id> --phase 04|05|06|07|08' }
       const runDir = join(runRoot, runId)
       if (!existsSync(runDir)) return { kind: 'error', text: 'Run not found in current workspace: ' + runId }
-      return { kind: 'success', text: 'closeout scaffolded for ' + runId + ' phase ' + phase }
+      // ⚠ THIS BRANCH USED TO LIE. It returned "closeout scaffolded for <run> phase <n>" having read nothing,
+      // written nothing and checked nothing — a command that reported success for work it never did. It now
+      // runs the LINTER the closeout actually is: it reads the phase artifact and reports what is missing,
+      // and WRITES NOTHING, which is the design the user specified ("like a linter checking if the agent
+      // missed anything; it is not supposed to edit files by itself").
+      try {
+        const report = closeoutReport(runDir, phase)
+        const lines = [
+          report.artifact + ' — ' + (report.exists ? report.status : 'ABSENT'),
+          report.findings.length === 0
+            ? 'fits the required standard.'
+            : report.findings.length + ' finding(s) before it can lock:',
+        ]
+        for (const finding of report.findings.slice(0, 12)) lines.push('- ' + finding.detail)
+        if (report.prerequisites.length > 0) {
+          lines.push('Advisory — earlier phases not yet LOCKED: '
+            + report.prerequisites.map((p) => p.artifact + ' (' + p.status + ')').join(', '))
+        }
+        if (report.addenda.length > 0) lines.push('Addenda cited: ' + report.addenda.length)
+        return { kind: 'success', text: lines.join('\n') }
+      } catch (err) {
+        return { kind: 'error', text: err instanceof Error ? err.message : String(err) }
+      }
+    }
+    case 'model': {
+      // ⚠ FU-19 — THE EFFECTIVE PROVIDER AND MODEL FOR A PHASE, WITH ITS PROVENANCE, and no agent loop. The same
+      // shape as `/recursive memory`: the workflow's own resolution, printed, so "why did this child run on that
+      // model" is answerable without reading the code or starting anything.
+      const phaseMatch = arg.match(/--phase\s+(\S+)/)
+      const roleMatch = arg.match(/--role\s+(\S+)/)
+      // ⚠ QUOTES ARE STRIPPED, because a shell-typed selector often arrives quoted and `--role ""` must be
+      // understood as "no role given" rather than as a role literally named two quote characters. That mistake was
+      // caught by this verb's own spec, which is the point of writing the spec before believing the code.
+      const unquote = (value: string | undefined): string => (value ?? '').replace(/^["']|["']$/g, '').trim()
+      const phase = unquote(phaseMatch?.[1])
+      const role = unquote(roleMatch?.[1])
+      // ⚠ FU-19 — SET OR CLEAR, when the user supplied something to set. A bare `/recursive model` still READS.
+      // The scope is inferred from which selectors were given, so `/recursive model --model cheap` sets the GENERAL
+      // default, `--phase 03 --model cheap` sets that phase's override, and `--role X --provider fork` sets the
+      // role route. `--clear` removes the named fields, or the whole level when none are named.
+      const providerMatch = arg.match(/--provider\s+(\S+)/)
+      const modelMatch = arg.match(/--model\s+(\S+)/)
+      const modelProviderMatch = arg.match(/--model-provider\s+(\S+)/)
+      const clear = /--clear\b/.test(arg)
+      if (providerMatch !== null || modelMatch !== null || modelProviderMatch !== null || clear) {
+        const scope: SelectionScope = phase !== '' ? 'phase' : role !== '' ? 'role' : 'general'
+        const written = writePolicySelection(root, {
+          scope,
+          ...(phase === '' ? {} : { phase }),
+          ...(role === '' ? {} : { role }),
+          ...(providerMatch === null ? {} : { provider: providerMatch[1]! }),
+          ...(modelMatch === null ? {} : { model: modelMatch[1]! }),
+          ...(modelProviderMatch === null ? {} : { modelProvider: modelProviderMatch[1]! }),
+          ...(clear ? { clear: true } : {}),
+        })
+        if ('refused' in written) return { kind: 'error', text: written.refused }
+        return { kind: 'success', text: written.message }
+      }
+      const policy = loadRouterPolicy(routerPolicyPath(root))
+      // `ladderProvider: null` on purpose: this verb reports what is CONFIGURED, and the provider ladder needs a
+      // live host's registered providers to answer. A caller wanting the full answer gets it from a delegation's
+      // routing notes, which is where the resolved ladder actually appears.
+      const target = resolveSubagentTarget({ role, phase, policy, ladderProvider: null })
+      const general = policy.defaults.subagent
+      return {
+        kind: 'success',
+        text: [
+          'effective selection for role ' + (role === '' ? '(none given)' : role) + (phase === '' ? '' : ' in phase ' + phase) + ':',
+          '- subagent provider, who creates the child: ' + (target.provider ?? 'none configured') + '  [from ' + target.chosen.provider + ']',
+          '- model, what the child runs on: ' + (target.model ?? 'inherited — no model is sent') + '  [from ' + target.chosen.model + ']',
+          target.reason,
+          'configured: general ' + (general === undefined ? 'unset' : JSON.stringify(general))
+            + ', phase routes ' + Object.keys(policy.phase_routes ?? {}).length
+            + ', role routes ' + Object.keys(policy.role_routes ?? {}).length,
+          'a model chosen here is checked against what DSH has when a delegation runs: available is applied, missing'
+            + ' is reported and NOT substituted, and unverified means there was no inventory to ask.',
+          '⚠ changing a default applies to FUTURE delegations only — it never rewrites a run\'s recorded history.',
+        ].join('\n'),
+      }
     }
     case 'worktree': {
       // /recursive worktree create <runId> [--base <branch>]
@@ -152,7 +264,7 @@ export function registerRecursiveCommand(
   return ctx.commands.register({
     name: 'recursive',
     description: 'recursive-mode workflow commands (workspace-scoped)',
-    input: { hint: 'status|spec|worktree|init|lock|qa|closeout|addendum|review|scratch|bootstrap|list|help' },
+    input: { hint: 'status|spec|worktree|init|lock|qa|closeout|addendum|review|scratch|memory|bootstrap|list|help' },
     handler: async ({ rawInput, agent }) => {
       const root = await resolveControlPlaneRoot(agent, (recursive as unknown as { workspaceRegistry?: unknown }).workspaceRegistry as never)
       if (!root) {

package/src/config.ts

@@ -0,0 +1,113 @@
+/**
+ * T7 — the plugin's Config: the `recursive` settings namespace.
+ *
+ * HOW THE SETTINGS SERVICE ACTUALLY SEES THIS, measured against
+ * `@deepseek-ai/dsh-settings`'s own types rather than assumed: `describe()` "read[s]
+ * active plugin schemas and their live values", and `update(ns, patch, expectedRevision)`
+ * "merge[s] editable fields into an entry's config". There is **no `register(...)` call
+ * for a plugin to make** — the item's `registerEnforcementSettings(settings)` wording
+ * describes a seam that does not exist. **Declaring this schema IS the registration:**
+ * the Loader owns the profile entry, the service projects the schema into a form, and an
+ * edit re-applies the plugin with the new config. That re-application IS the hot reload,
+ * which is why there is no watcher here to keep in sync.
+ *
+ * VALIDATION IS NOT DUPLICATED. The schema is what the UI reads and what gives the form
+ * its shape; `resolveEnforcementConfig` remains the STRICT validator (unknown keys
+ * rejected, budgets required to be positive integers, fail-loud at load). A schema that
+ * silently coerced a bad value would be a second, weaker contract beside the real one.
+ */
+import z from '@deepseek-ai/schemastery'
+import { DEFAULT_BUDGETS } from './enforcement.ts'
+
+/** One enforcement mode, as the settings form presents it. */
+const enforcementMode = z.union([z.const('strict'), z.const('advisory')])
+
+export interface RecursiveModeBudgets {
+  maxAuditRounds?: number
+  maxRepairAttempts?: number
+  maxDelegationDepth?: number
+  maxChildrenPerPhase?: number
+  maxResultBytes?: number
+}
+
+export interface RecursiveModeEnforcement {
+  preStep?: 'strict' | 'advisory'
+  toolGuards?: 'strict' | 'advisory'
+  tamper?: 'strict' | 'advisory'
+  budgets?: RecursiveModeBudgets
+}
+
+export interface RecursiveModeConfig {
+  /** R4 shell split: expose ONLY the client bundle, registering nothing server-side. */
+  shellOnly?: boolean
+  repoRoot?: string
+  /** T7/T28: the enforcement modes and the budgets, editable live. */
+  enforcement?: RecursiveModeEnforcement
+  /** T7: overrides for the workspace router file — see the schema comment on defaults. */
+  router?: { defaults?: Record<string, string | number | boolean | undefined> }
+}
+
+/**
+ * The schema the settings service discovers. Field descriptions are the form's help
+ * text, so they are written for the person toggling them, not for the reader of this file.
+ */
+export const Config = z.object({
+  shellOnly: z.boolean().default(false).description(
+    'Client-shell only: registers nothing on the server (no tools, no command, no projection).',
+  ),
+  repoRoot: z.string().description(
+    'Control-plane root. Defaults to the process working directory when unset.',
+  ),
+  enforcement: z.object({
+    preStep: enforcementMode.default('advisory').description(
+      'Phase pre-step enforcement: strict refuses an out-of-order transition, advisory warns and proceeds.',
+    ),
+    toolGuards: enforcementMode.default('advisory').description(
+      'Tool guard mode: strict DENIES an out-of-order tool call, advisory allows it and carries the warning.',
+    ),
+    tamper: enforcementMode.default('advisory').description(
+      'Tamper detection: strict refuses an artifact whose LockHash no longer matches its body.',
+    ),
+    budgets: z.object({
+      maxAuditRounds: z.natural().default(DEFAULT_BUDGETS.maxAuditRounds).description(
+        'Rounds one phase audit loop may run, even while every round makes progress.',
+      ),
+      maxRepairAttempts: z.natural().default(DEFAULT_BUDGETS.maxRepairAttempts).description(
+        'How many times a phase may be sent back for repair before the loop stops.',
+      ),
+      maxDelegationDepth: z.natural().default(DEFAULT_BUDGETS.maxDelegationDepth).description(
+        'Ceiling for the WHOLE recursion. A child narrows it; it is never re-granted per level.',
+      ),
+      maxChildrenPerPhase: z.natural().default(DEFAULT_BUDGETS.maxChildrenPerPhase).description(
+        'Delegated children one phase may start, counted by distinct operation.',
+      ),
+      maxResultBytes: z.natural().default(DEFAULT_BUDGETS.maxResultBytes).description(
+        'Byte ceiling for one tool result, applied after the finding-count cap.',
+      ),
+    }).description('T28 budgets.'),
+  }).description('The enforcement modes plus the T28 budgets.'),
+  /**
+   * T7 — the ROUTER overrides. Deliberately NO defaults on these fields: `.default()`
+   * would make every field present, and a present field overrides the workspace's
+   * `recursive-router.json` — so defaulting them would silently shadow the declarative
+   * file forever. Absent means "defer to the file"; present means "override it".
+   */
+  router: z.object({
+    defaults: z.object({
+      when_role_unconfigured: z.union([z.const('ask'), z.const('fallback-local')]).description(
+        'What to do when a role has no configured route. Leave unset to use the workspace router file.',
+      ),
+      when_cli_unavailable: z.union([z.const('ask'), z.const('fallback-local')]).description(
+        'What to do when the routed CLI is unavailable. Leave unset to use the workspace router file.',
+      ),
+      when_model_unknown: z.union([z.const('ask'), z.const('fallback-local')]).description(
+        'What to do when a routed model is not a known provider. Leave unset to use the workspace router file.',
+      ),
+      allow_auto_assign_if_single_cli: z.boolean().description(
+        'Assign a role automatically when exactly one CLI is configured. Unset defers to the file.',
+      ),
+      probe_timeout_ms: z.natural().description('CLI capability probe timeout in ms. Unset defers to the file.'),
+      invoke_timeout_ms: z.natural().description('Routed CLI invocation timeout in ms. Unset defers to the file.'),
+    }).description('Router default policy fields this namespace overrides.'),
+  }).description('Overrides for .recursive/config/recursive-router.json — one path, not two.'),
+})