@try-works/dsh-recursive-mode 0.1.0

package/src/runtime.ts

@@ -0,0 +1,564 @@
+import { Service, type Context } from '@deepseek-ai/cordis'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { foldRun, resolveRunDir } from './status.ts'
+import {
+  getLockStatus,
+  getNextLegalPhase,
+  getPrerequisiteBlockers,
+  getStaleDownstreamPhases,
+  invalidateReceipt,
+  lockHashFromContent,
+  writeReceipt,
+} from './lock.ts'
+import type { RecursiveStatusResult } from './types.ts'
+import { resolveControlPlaneRoot, type WorkspaceRegistryLike } from './workspace.ts'
+import { closeoutPhase } from './closeout.ts'
+import { readScratch, writeScratch, appendScratch, type ScratchTarget } from './scratch.ts'
+import { buildReviewBundle, type ReviewBundleInput } from './review.ts'
+import { createHandoff, createChildBrief, replyPath, childScratchPath, buildDelegationPrompt, type HandoffInput, type ChildBriefInput } from './handoff.ts'
+import { loadRouterPolicy, routerPolicyPath, resolveRole, capabilityProbe, delegationDecisionBasis, type RouterPolicy, type SubagentProviderLike, type RouteDecision, type CapabilityProbe } from './router.ts'
+import { delegate, validateReferences, writeActionRecord, evaluateDelegationResult, reviewOutputSchema, defaultReviewToolFilter, type SubagentsRuntimeLike, type SubagentStartRequestLike, type SubagentResultLike, type Reference, type ActionRecordInput } from './delegation.ts'
+import { foldRecursivePhase, validateTransition, detectTransitionIntent, LifecycleDriver, coupleGateBlockToGoal, type PhaseTransitionIntent, type SessionEventLike, type RecursivePhaseState, type GateCheckResult } from './lifecycle.ts'
+import { resolveEnforcementConfig, DEFAULT_ENFORCEMENT, evaluatePreStepGate, evaluateToolGuard, detectTamper, type EnforcementConfig, type PreStepGateDecision, type ToolGuardDecision, type ToolExecLike } from './enforcement.ts'
+import type { Session } from '@deepseek-ai/dsh-session'
+import { runCreated as runCreatedEvent, phase as phaseEvent, phaseLocked as phaseLockedEvent, runState as runStateEvent } from './events.ts'
+import { renderRecursivePolicy, type PolicyContext } from './policy.ts'
+import { foldRecursiveProjection as foldProjectionEvent, emptyRecursiveFoldState, recursiveProjectionUnit, isInsideWorkspace, type RecursiveEventLike, type RecursiveFoldState } from './projection.ts'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    recursive: RecursiveRuntime
+  }
+}
+
+export interface LockArtifactResult {
+  artifact: string
+  runId: string
+  status: string
+  lockedAt: string | null
+  lockHash: string | null
+  receipt?: unknown
+  blockers: string[]
+}
+
+export interface LintArtifactResult {
+  artifact: string
+  runId: string
+  errors: string[]
+  warnings: string[]
+  passed: boolean
+}
+
+const ARTIFACT_STUB = {
+  '00-requirements.md': ['Run: ', 'Phase: 0', 'Status: DRAFT', 'Workflow version: recursive-mode-audit-v2', 'Inputs: none', 'Outputs: none', 'Scope note: '],
+  '00-worktree.md': ['Run: ', 'Phase: 0 (Worktree)', 'Status: DRAFT', 'Workflow version: recursive-mode-audit-v2', 'Inputs: none', 'Outputs: none', 'Scope note: '],
+  '01-as-is.md': ['Run: ', 'Phase: 1 (AS-IS)', 'Status: DRAFT', 'Workflow version: recursive-mode-audit-v2', 'Inputs: none', 'Outputs: none', 'Scope note: '],
+  '02-to-be-plan.md': ['Run: ', 'Phase: 2 (TO-BE Plan)', 'Status: DRAFT', 'Workflow version: recursive-mode-audit-v2', 'Inputs: none', 'Outputs: none', 'Scope note: '],
+  '03-implementation-summary.md': ['Run: ', 'Phase: 3 (Implementation)', 'Status: DRAFT', 'Workflow version: recursive-mode-audit-v2', 'Inputs: none', 'Outputs: none', 'Scope note: '],
+  '04-test-summary.md': ['Run: ', 'Phase: 4 (Test Summary)', 'Status: DRAFT', 'Workflow version: recursive-mode-audit-v2', 'Inputs: none', 'Outputs: none', 'Scope note: '],
+  '05-manual-qa.md': ['Run: ', 'Phase: 5 (Manual QA)', 'Status: DRAFT', 'Workflow version: recursive-mode-audit-v2', 'Inputs: none', 'Outputs: none', 'Scope note: '],
+  '06-decisions-update.md': ['Run: ', 'Phase: 6 (Decisions Update)', 'Status: DRAFT', 'Workflow version: recursive-mode-audit-v2', 'Inputs: none', 'Outputs: none', 'Scope note: '],
+  '07-state-update.md': ['Run: ', 'Phase: 7 (State Update)', 'Status: DRAFT', 'Workflow version: recursive-mode-audit-v2', 'Inputs: none', 'Outputs: none', 'Scope note: '],
+  '08-memory-impact.md': ['Run: ', 'Phase: 8 (Memory Impact)', 'Status: DRAFT', 'Workflow version: recursive-mode-audit-v2', 'Inputs: none', 'Outputs: none', 'Scope note: '],
+}
+
+export class RecursiveRuntime extends Service {
+  /** Recursive-mode runtime service. Owns run-state reads + lock/init/lint operations. */
+
+  constructor(ctx: Context, config: { repoRoot?: string; workspaceRegistry?: WorkspaceRegistryLike } = {}) {
+    super(ctx, 'recursive')
+    this.repoRoot = config.repoRoot ?? process.cwd()
+    this.workspaceRegistry = config.workspaceRegistry ?? null
+  }
+
+  private readonly repoRoot: string
+  private readonly workspaceRegistry: WorkspaceRegistryLike | null
+  private _enforcementConfig: EnforcementConfig | null = null
+
+  /**
+   * Workspace-scoped control-plane root (R1 binding invariant).
+   * Resolves the session agent's canonical cwd -> workspace path via the
+   * registry; NEVER scans list(). Returns null when unavailable (defer).
+   */
+  async resolveWorkspaceRoot(agent?: { session?: { header?: { cwd?: string } } } | null): Promise<string | null> {
+    return resolveControlPlaneRoot(agent, this.workspaceRegistry)
+  }
+
+  /**
+   * Run-scoped closeout receipt scaffold (R2), rooted under the given
+   * workspace root. Refuses runIds outside the root (never crosses workspaces).
+   */
+  closeoutRun(root: string, runId: string, phase: string) {
+    const runDir = join(root, '.recursive', 'run', runId)
+    const runRoot = join(root, '.recursive', 'run')
+    // workspace-scoping guard: the run must be under this root
+    if (!runDir.startsWith(runRoot) || !existsSync(runDir)) {
+      return { error: 'Run not found in current workspace: ' + runId }
+    }
+    try {
+      const result = closeoutPhase(runDir, phase)
+      return { closeoutPhase: phase, runId, ...result }
+    } catch (err) {
+      return { error: (err as Error).message }
+    }
+  }
+
+  /**
+   * Run-scoped scratchpad access (R5), rooted under the given workspace root.
+   */
+  scratchRun(root: string, runId: string, action: string, target: ScratchTarget, content?: string) {
+    const runDir = join(root, '.recursive', 'run', runId)
+    const runRoot = join(root, '.recursive', 'run')
+    if (!runDir.startsWith(runRoot) || !existsSync(runDir)) {
+      return { error: 'Run not found in current workspace: ' + runId }
+    }
+    try {
+      if (action === 'read') {
+        return { runId, target, action, content: readScratch(runDir, target), path: join(runDir, 'scratch', 'scratch.' + target) }
+      }
+      if (action === 'write') {
+        const path = writeScratch(runDir, target, content ?? '')
+        return { runId, target, action, path }
+      }
+      if (action === 'append') {
+        const path = appendScratch(runDir, target, content ?? '')
+        return { runId, target, action, path }
+      }
+      return { error: 'Unsupported scratch action: ' + action + ' (expected read|write|append)' }
+    } catch (err) {
+      return { error: (err as Error).message }
+    }
+  }
+
+  /**
+   * Phase B (native delegation): build a review bundle (R1) + file-backed
+   * handoff docs (R2), resolve the role via the router policy (R3), and call
+   * ctx.subagents.start() with the full request (R4). Workspace-scoped: every
+   * path resolves under the session's control-plane root.
+   */
+  async delegateReview(input: {
+    root: string
+    runId: string
+    phase: string
+    role: string
+    delegationId: string
+    childId: string
+    artifactPath: string
+    upstreamArtifacts: string[]
+    auditQuestions: string[]
+    requiredOutput: string
+    codeRefs?: string[]
+    changedFiles?: string[]
+    diffBasis?: ReviewBundleInput['diffBasis']
+    policyPath?: string
+    providers?: Record<string, SubagentProviderLike>
+    subagents?: SubagentsRuntimeLike
+    maxDepth?: number
+    toolFilter?: unknown
+  }) {
+    const policy = loadRouterPolicy(input.policyPath ?? routerPolicyPath(input.root))
+    const providers = input.providers ?? {}
+    const decision = resolveRole(input.role, policy, providers)
+    const probe = capabilityProbe({ providers, role: input.role, policy })
+
+    // R1 bundle + R2 handoff/brief/prompt (file-backed context-in contract).
+    const bundle = buildReviewBundle({
+      root: input.root,
+      runId: input.runId,
+      phase: input.phase,
+      role: input.role,
+      artifactPath: input.artifactPath,
+      upstreamArtifacts: input.upstreamArtifacts,
+      auditQuestions: input.auditQuestions,
+      requiredOutput: input.requiredOutput,
+      codeRefs: input.codeRefs,
+      changedFiles: input.changedFiles,
+      diffBasis: input.diffBasis,
+    })
+    const handoffPath = createHandoff({
+      root: input.root,
+      runId: input.runId,
+      delegationId: input.delegationId,
+      role: input.role,
+      objective: input.requiredOutput,
+      runDocRefs: input.upstreamArtifacts,
+      codeRefs: input.codeRefs ?? [],
+      auditQuestions: input.auditQuestions,
+      requiredOutput: input.requiredOutput,
+      decisionBasis: decision.reason,
+      constraints: [
+        'Workspace-scoped: never read another workspace\'s .recursive/ tree.',
+        'Optionality: if the probe fails, fall back to self-audit — never weaken the audit.',
+        'Fail loud: capability mismatches reject; do not silently degrade.',
+      ],
+    })
+    const briefPath = createChildBrief({
+      root: input.root,
+      runId: input.runId,
+      delegationId: input.delegationId,
+      childId: input.childId,
+      slice: 'Perform the delegated ' + input.role + ' for run ' + input.runId + ' (' + input.phase + ') and write your submission to reply.md.',
+    })
+    const prompt = buildDelegationPrompt({
+      root: input.root,
+      runId: input.runId,
+      delegationId: input.delegationId,
+      childId: input.childId,
+      handoffPath,
+      briefPath,
+    })
+
+    // R4: plugin-driven delegation with the full request shape.
+    const request: SubagentStartRequestLike = {
+      prompt: [{ type: 'text', text: prompt }],
+      label: input.delegationId + '/' + input.childId,
+      outputSchema: reviewOutputSchema(),
+      toolFilter: input.toolFilter ?? defaultReviewToolFilter(),
+      maxDepth: input.maxDepth ?? 2,
+    }
+
+    let result: SubagentResultLike | null = null
+    let error: string | null = null
+    if (decision.tier === 'native' || decision.tier === 'external-cli') {
+      if (!input.subagents) {
+        error = 'no ctx.subagents runtime available (self-audit fallback)'
+      } else {
+        try {
+          result = await delegate({
+            subagents: input.subagents,
+            provider: decision.provider as string,
+            request,
+          })
+        } catch (err) {
+          error = (err as Error).message
+        }
+      }
+    } else {
+      error = 'delegation resolved to ' + decision.tier + ' (' + decision.reason + ')'
+    }
+
+    const evaluation = result ? evaluateDelegationResult(result) : { accepted: false, reason: error ?? 'no result' }
+
+    // R6: record the attempt as an action record (accepted only if evaluation passes).
+    const actionRecordPath = writeActionRecord({
+      root: input.root,
+      runId: input.runId,
+      subagentId: input.childId,
+      phase: input.phase,
+      purpose: input.role + ' for run ' + input.runId,
+      executionMode: decision.tier,
+      artifactPath: input.artifactPath,
+      upstreamArtifacts: input.upstreamArtifacts,
+      reviewBundle: bundle.repoRelativePath,
+      diffBasis: input.diffBasis?.normalizedDiffCommand,
+      codeRefs: input.codeRefs,
+      auditQuestions: input.auditQuestions,
+      findings: evaluation.accepted && result?.structured ? [(result.structured as { verdict?: string })?.verdict ?? 'accepted'] : undefined,
+      success: evaluation.accepted,
+      stopReason: result?.stopReason,
+    })
+
+    return {
+      decision,
+      probe,
+      bundle,
+      handoffPath,
+      briefPath,
+      replyPath: replyPath({ root: input.root, runId: input.runId, delegationId: input.delegationId, childId: input.childId }),
+      childScratchPath: childScratchPath({ root: input.root, runId: input.runId, childId: input.childId }),
+      prompt,
+      request,
+      result,
+      evaluation,
+      actionRecordPath,
+      error,
+    }
+  }
+
+  /** R6: validate a child's claimed references against actual files. */
+  validateReferences(root: string, references: Reference[]) {
+    return validateReferences(root, references)
+  }
+
+  /** R7: probe availability for a role and render the decision basis prose. */
+  probeDelegation(root: string, role: string, providers: Record<string, SubagentProviderLike> = {}) {
+    const policy = loadRouterPolicy(routerPolicyPath(root))
+    const decision = resolveRole(role, policy, providers)
+    const probe = capabilityProbe({ providers, role, policy })
+    return {
+      decision,
+      probe,
+      basis: delegationDecisionBasis({ role, available: probe.available, provider: probe.provider, fallback: 'self-audit' }),
+    }
+  }
+
+  /**
+   * B3: per-call workspace root resolution. The control-plane root is the
+   * session's cwd (or registry-canonicalized), NEVER process.cwd() — the host
+   * checkout is not the run's workspace. Reads resolve under that root only.
+   */
+  async resolveRootFor(agent?: { session?: { header?: { cwd?: string } } } | null): Promise<string | null> {
+    return resolveControlPlaneRoot(agent, this.workspaceRegistry, this.repoRoot)
+  }
+
+  /**
+   * Emit a recursive/* event into the session whose control-plane root matches
+   * `root` (additive log-only; the projection drives from these). Falls back to
+   * the agent's session when passed, else the session store list.
+   */
+  private emitToSession(root: string, type: string, data: unknown, agent?: { session?: { header?: { cwd?: string } } | null } | null) {
+    const sessions = this.ctx.get('sessions') as { list?: () => Session[] } | undefined
+    const candidates: Session[] = []
+    if (agent?.session) candidates.push(agent.session as unknown as Session)
+    const listed = sessions?.list?.() ?? []
+    for (const s of listed) candidates.push(s)
+    const norm = (x: string) => x.split(String.fromCharCode(92)).join("/")
+    const target = candidates.find((s) => {
+      const cwd = norm(s.header?.cwd ?? "")
+      return cwd === "" || cwd === norm(root) || cwd.startsWith(norm(root) + "/")
+    })
+    if (!target) return
+    try { (target.append as unknown as (t: string, d: unknown) => void)(type, data) } catch { /* log-only */ }
+  }
+
+  async status(runId?: string, agent?: { session?: { header?: { cwd?: string } } } | null): Promise<RecursiveStatusResult | null> {
+    const root = await this.resolveRootFor(agent)
+    if (!root) return null
+    const resolved = resolveRunDir(root, runId)
+    if (!resolved) return null
+    return foldRun(resolved.runDir, resolved.runId)
+  }
+
+  /**
+   * Scaffold a run directory with stub artifact headers (no-op if exists).
+   * Returns the run dir + created artifacts.
+   */
+  async initRun(runId: string, agent?: { session?: { header?: { cwd?: string } } } | null): Promise<{ runDir: string; runId: string; created: string[]; existing: string[] }> {
+    const root = await this.resolveRootFor(agent)
+    if (!root) throw new Error('cannot resolve workspace control-plane root for this session')
+    const runDir = join(root, '.recursive', 'run', runId)
+    mkdirSync(runDir, { recursive: true })
+    const created: string[] = []
+    const existing: string[] = []
+    for (const [file, fields] of Object.entries(ARTIFACT_STUB)) {
+      const path = join(runDir, file)
+      if (existsSync(path)) {
+        existing.push(file)
+        continue
+      }
+      const header = fields.map((f, i) => (i === 0 ? f + runId : f)).join('\n')
+      writeFileSync(path, '# ' + file.replace(/\.md$/, '') + ' — ' + file + '\n\n' + header + '\n', 'utf8')
+      created.push(file)
+    }
+    // B2: a run's files first exist here — the run-created event feeds the
+    // projection's worktree-grouped card. Emit only when the scaffold is fresh
+    // (created.length > 0) so resume/ensure does not double-log.
+    if (created.length > 0) {
+      this.emitToSession(root, 'recursive/run-created', runCreatedEvent({ runId, worktreeRoot: root }), agent)
+      this.emitToSession(root, 'recursive/run-state', runStateEvent({ runId, worktreeRoot: root, state: 'new' }), agent)
+    }
+    return { runDir, runId, created, existing }
+  }
+
+  /**
+   * Lock a DRAFT artifact (or reopen a LOCKED one). Validates prerequisites;
+   * writes Status/LockedAt/LockHash + receipt. Returns the lock result.
+   */
+  async lockArtifact(runId: string, artifact: string, reopen = false, agent?: { session?: { header?: { cwd?: string } } } | null): Promise<LockArtifactResult> {
+    const root = await this.resolveRootFor(agent)
+    if (!root) throw new Error('cannot resolve workspace control-plane root for this session')
+    const runDir = join(root, '.recursive', 'run', runId)
+    const artifactPath = join(runDir, artifact)
+    if (reopen) {
+      return this.reopenArtifact(root, runDir, runId, artifact, artifactPath, agent)
+    }
+    if (!existsSync(artifactPath)) throw new Error('Artifact not found: ' + artifact)
+    const status = getLockStatus(artifactPath)
+    if (status === 'LOCKED') throw new Error('Artifact already LOCKED: ' + artifact)
+    // B2: log the phase-intent BEFORE validation so the pre-step gate reads it
+    // (the caller of the transition set). Never a projection event.
+    this.emitToSession(root, 'recursive/phase-intent', { runId, worktreeRoot: root, targetArtifact: artifact, kind: 'lock' }, agent)
+    const blockers = getPrerequisiteBlockers(runDir, artifact)
+    if (blockers.length > 0) {
+      throw new Error('Prerequisite blockers: ' + blockers.map(b => b.artifact + ' (' + b.status + ')').join(', '))
+    }
+    let content = readFileSync(artifactPath, 'utf8')
+    const lockedAt = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z')
+    content = setOrInsertField(content, 'Status', 'LOCKED', ['Phase'])
+    content = setOrInsertField(content, 'LockedAt', lockedAt, ['Status'])
+    const provisional = setOrInsertField(content, 'LockHash', '0'.repeat(64), ['LockedAt', 'Status'])
+    const lockHash = lockHashFromContent(provisional)
+    content = setOrInsertField(content, 'LockHash', lockHash, ['LockedAt', 'Status'])
+    writeFileSync(artifactPath, content, 'utf8')
+    const receipt = writeReceipt(runDir, artifact, artifactPath)
+    // B2: the commit is durable — emit phase + phase-locked (the projection's
+    // last-wins phase chain + lock badge + truncated hash).
+    this.emitToSession(root, 'recursive/phase', phaseEvent({ runId, worktreeRoot: root, phase: artifact, status: 'LOCKED' }), agent)
+    this.emitToSession(root, 'recursive/phase-locked', phaseLockedEvent({ runId, worktreeRoot: root, phase: artifact, lockedAt, lockHash }), agent)
+    this.emitToSession(root, 'recursive/run-state', runStateEvent({ runId, worktreeRoot: root, state: 'active' }), agent)
+    return {
+      artifact,
+      runId,
+      status: 'LOCKED',
+      lockedAt,
+      lockHash,
+      receipt,
+      blockers: [],
+    }
+  }
+
+  /** Reopen a LOCKED artifact to DRAFT (delete LockedAt/LockHash, invalidate downstream receipts). */
+  private reopenArtifact(root: string, runDir: string, runId: string, artifact: string, artifactPath: string, agent?: { session?: { header?: { cwd?: string } } } | null): LockArtifactResult {
+    if (!existsSync(artifactPath)) throw new Error('Artifact not found: ' + artifact)
+    let content = readFileSync(artifactPath, 'utf8')
+    content = content.replace(/^[ \t]*Status:.*$/m, 'Status: `DRAFT`')
+    content = content.replace(/^[ \t]*LockedAt:.*\n?/m, '')
+    content = content.replace(/^[ \t]*LockHash:.*\n?/m, '')
+    writeFileSync(artifactPath, content, 'utf8')
+    const hadReceipt = invalidateReceipt(runDir, artifact)
+    const stale = getStaleDownstreamPhases(runDir, artifact)
+    for (const entry of stale) invalidateReceipt(runDir, entry.artifact)
+    // B2: reopen reverts to DRAFT — log phase-intent + emit the transition so
+    // the pre-step gate and projection both see the reverted state.
+    this.emitToSession(root, 'recursive/phase-intent', { runId, worktreeRoot: root, targetArtifact: artifact, kind: 'reopen' }, agent)
+    this.emitToSession(root, 'recursive/phase', phaseEvent({ runId, worktreeRoot: root, phase: artifact, status: 'DRAFT' }), agent)
+    this.emitToSession(root, 'recursive/run-state', runStateEvent({ runId, worktreeRoot: root, state: 'active', reason: 'reopened ' + artifact }), agent)
+    return {
+      artifact,
+      runId,
+      status: 'DRAFT',
+      lockedAt: null,
+      lockHash: null,
+      blockers: hadReceipt || stale.length > 0 ? ['Downstream receipts invalidated'] : [],
+    }
+  }
+
+  /**
+   * Lint an artifact for phase-specific issues. Minimal structural checks:
+   * gates present, TODO section, Status field, LockHash consistency.
+   */
+  async lintArtifact(runId: string, artifact?: string, agent?: { session?: { header?: { cwd?: string } } } | null): Promise<LintArtifactResult> {
+    const root = await this.resolveRootFor(agent)
+    if (!root) throw new Error('cannot resolve workspace control-plane root for this session')
+    const runDir = join(root, '.recursive', 'run', runId)
+    const target = artifact ?? getNextLegalPhase(runDir) ?? '00-requirements.md'
+    const artifactPath = join(runDir, target)
+    if (!existsSync(artifactPath)) {
+      return { artifact: target, runId, errors: ['Artifact not found'], warnings: [], passed: false }
+    }
+    const content = readFileSync(artifactPath, 'utf8')
+    const errors: string[] = []
+    const warnings: string[] = []
+    const status = getLockStatus(artifactPath)
+    if (status === 'MISSING') errors.push('File missing')
+    else if (status === 'DRAFT') warnings.push('Artifact is DRAFT (not locked)')
+    else if (status === 'STALE_LOCK') errors.push('LockHash mismatch or missing lock fields')
+    if (!/^[ \t]*## TODO[ \t]*$/m.test(content)) errors.push('Missing ## TODO section')
+    for (const gate of ['Coverage', 'Approval']) {
+      if (!new RegExp('^[ \\t]*' + gate + ':\\s*(PASS|FAIL)\\s*$', 'm').test(content)) warnings.push('Missing ' + gate + ' gate')
+    }
+    if (target === '03-implementation-summary.md' && !new RegExp('^[ \\t]*TDD Compliance:\\s*(PASS|FAIL)\\s*$', 'm').test(content)) {
+      warnings.push('Missing TDD Compliance gate')
+    }
+    return { artifact: target, runId, errors, warnings, passed: errors.length === 0 }
+  }
+
+  /** Phase C R1/R2: fold the log into phase state; validate a transition intent. */
+  foldPhase(events: readonly SessionEventLike[]): RecursivePhaseState | null {
+    return foldRecursivePhase(events)
+  }
+
+  validateTransition(intent: PhaseTransitionIntent): GateCheckResult {
+    return validateTransition(intent)
+  }
+
+  detectTransitionIntent(events: readonly SessionEventLike[]): PhaseTransitionIntent | null {
+    return detectTransitionIntent(events)
+  }
+
+  /** Phase C R3: Layer 1 pre-step gate decision (caller of the transition set). */
+  gatePreStep(events: readonly SessionEventLike[], config?: EnforcementConfig): PreStepGateDecision {
+    const mode = (config ?? this.enforcementConfig).preStep
+    return evaluatePreStepGate(events, mode)
+  }
+
+  /** Phase C R4: Layer 2 tool guard decision (caller of the transition set). */
+  guardTool(exec: ToolExecLike, root: string, runId: string, config?: EnforcementConfig): ToolGuardDecision {
+    const mode = (config ?? this.enforcementConfig).toolGuards
+    return evaluateToolGuard(exec, root, runId, mode)
+  }
+
+  /** Phase C R8: fs/observed tamper detection. */
+  detectTamper(targetPath: string, root: string, runId: string) {
+    return detectTamper(targetPath, root, runId)
+  }
+
+  /** Phase C R5: render the current-phase policy contract. */
+  renderPolicy(root: string, runId: string, folded: RecursivePhaseState | null): string {
+    return renderRecursivePolicy({ worktreeRoot: root, runId, folded, config: this.enforcementConfig } as PolicyContext)
+  }
+
+  /** Phase C R6: couple a gate-block to the goal service (graceful no-op). */
+  coupleGateBlockToGoal(goalService: unknown, agent: unknown, ref: unknown, reason: { code: string; message: string }): boolean {
+    return coupleGateBlockToGoal(goalService as never, agent, ref, reason)
+  }
+
+  /** Phase D R1: append a recursive/* event through the host session adapter (worktree-keyed). */
+  emitRecursiveEvent(session: unknown, type: string, data: Record<string, unknown>): void {
+    const s = session as { append?: (type: string, data: unknown) => void } | null | undefined
+    if (s && typeof s.append === 'function') {
+      s.append(type, data)
+    }
+  }
+
+  /** Phase D R2/R9: fold a session log into the worktree-grouped projection. */
+  foldRecursiveProjection(events: readonly RecursiveEventLike[], workspaceRoot = ''): RecursiveFoldState {
+    let state = emptyRecursiveFoldState(workspaceRoot)
+    for (const event of events) state = foldProjectionEvent(state, event)
+    return state
+  }
+
+  /** Phase D R2: the registered projection unit (key 'recursive'). */
+  get projectionUnit() {
+    return recursiveProjectionUnit
+  }
+
+  /** Phase D R9: whether a worktreeRoot is inside the workspace control-plane root. */
+  isInsideWorkspace(worktreeRoot: string, workspaceRoot: string): boolean {
+    return isInsideWorkspace(worktreeRoot, workspaceRoot)
+  }
+
+  /** Phase C R7: resolve the enforcement config (strict|advisory, default advisory). */
+  get enforcementConfig(): EnforcementConfig {
+    return this._enforcementConfig ?? DEFAULT_ENFORCEMENT
+  }
+
+  setEnforcementConfig(config: unknown): EnforcementConfig {
+    this._enforcementConfig = resolveEnforcementConfig(config)
+    return this._enforcementConfig
+  }
+}
+
+/** set_or_insert_field: replace first field occurrence, else insert after the last listed after-field. */
+function setOrInsertField(content: string, fieldName: string, value: string, afterFields: string[]): string {
+  const line = fieldName + ': `' + value + '`'
+  const fieldRe = new RegExp('^[ \\t]*(?:[-*][ \\t]+)?' + escapeRegExp(fieldName) + ':\\s*.*$', 'm')
+  if (fieldRe.test(content)) {
+    return content.replace(fieldRe, line)
+  }
+  const lines = content.replace(/\r\n/g, '\n').replace(/\r/g, '\n').split('\n')
+  let insertAt = 0
+  for (const afterField of afterFields) {
+    const afterRe = new RegExp('^[ \\t]*(?:[-*][ \\t]+)?' + escapeRegExp(afterField) + ':\\s*.*$', 'm')
+    for (let i = 0; i < lines.length; i++) {
+      if (afterRe.test(lines[i])) insertAt = Math.max(insertAt, i + 1)
+    }
+  }
+  lines.splice(insertAt, 0, line)
+  return lines.join('\n')
+}
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}

package/src/scratch.ts

@@ -0,0 +1,85 @@
+/**
+ * Run-scoped disposable scratchpad (R5). Lives at <run-dir>/scratch/scratch.md
+ * and <run-dir>/scratch/scratch.ts, is git-ignored, and is NEVER citable as an
+ * Input in phase docs (enforced by the recursive:policy + lint, Phase C).
+ * The plugin never creates a run implicitly: writing scratch requires an
+ * existing run directory.
+ *
+ * Phase B R5 adds child-scoped scratch (PROPOSAL 10.7): each delegated child
+ * gets its OWN disposable scratch under <run-dir>/scratch/<child-id>.md, while
+ * the parent's scratch.md stays the main agent's working memory. A child MAY
+ * read the parent scratch when the prompt includes it, but writes go only to
+ * the child's own file.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from 'node:fs'
+import { join, resolve, sep } from 'node:path'
+
+export type ScratchTarget = 'md' | 'ts'
+
+export function scratchPathFor(runDir: string, target: ScratchTarget): string {
+  if (target !== 'md' && target !== 'ts') {
+    throw new Error('Unsupported scratch target: ' + String(target) + ' (expected md or ts)')
+  }
+  return join(runDir, 'scratch', 'scratch.' + target)
+}
+
+function assertRunExists(runDir: string): void {
+  if (!existsSync(runDir)) {
+    throw new Error('Run directory does not exist: ' + runDir + ' (scratch never creates runs)')
+  }
+}
+
+export function readScratch(runDir: string, target: ScratchTarget): string {
+  assertRunExists(runDir)
+  const path = scratchPathFor(runDir, target)
+  if (!existsSync(path)) return ''
+  return readFileSync(path, 'utf8')
+}
+
+export function writeScratch(runDir: string, target: ScratchTarget, content: string): string {
+  assertRunExists(runDir)
+  const path = scratchPathFor(runDir, target)
+  mkdirSync(join(runDir, 'scratch'), { recursive: true })
+  writeFileSync(path, content, 'utf8')
+  return path
+}
+
+export function appendScratch(runDir: string, target: ScratchTarget, content: string): string {
+  assertRunExists(runDir)
+  const path = scratchPathFor(runDir, target)
+  mkdirSync(join(runDir, 'scratch'), { recursive: true })
+  appendFileSync(path, content + '\n', 'utf8')
+  return path
+}
+
+/**
+ * Child-scoped scratch path (Phase B R5): <run-dir>/scratch/<child-id>.md.
+ * Resolved under the run dir; a child id escaping the scratch dir is rejected.
+ */
+export function childScratchPath(runDir: string, childId: string): string {
+  assertRunExists(runDir)
+  const scratchDir = resolve(runDir, 'scratch')
+  const candidate = resolve(scratchDir, childId + '.md')
+  const prefix = scratchDir.endsWith(sep) ? scratchDir : scratchDir + sep
+  if (!candidate.startsWith(prefix)) {
+    throw new Error('Child scratch escapes the run scratch dir: ' + childId)
+  }
+  return candidate
+}
+
+/** Read-only access to the PARENT's scratch (the main agent's working memory). */
+export function readParentScratch(runDir: string, target: ScratchTarget = 'md'): string {
+  return readScratch(runDir, target)
+}
+
+/**
+ * Write ONLY the child's own scratch file. Refuses any target outside
+ * <run-dir>/scratch/<child-id>.md (a child cannot overwrite the parent's
+ * scratch.md through this writer).
+ */
+export function writeChildScratch(runDir: string, childId: string, content: string): string {
+  const path = childScratchPath(runDir, childId)
+  mkdirSync(join(runDir, 'scratch'), { recursive: true })
+  writeFileSync(path, content, 'utf8')
+  return path
+}