@try-works/dsh-recursive-mode 0.1.3 → 0.1.5

package/src/index.ts

@@ -1,5 +1,7 @@
 import { type Context } from '@deepseek-ai/cordis'
-import type { Session } from '@deepseek-ai/dsh-session'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
 import { RecursiveRuntime } from './runtime.ts'
 import { createRecursiveStatusTool } from './recursive_status.tool.ts'
 import { createRecursiveInitTool } from './recursive_init.tool.ts'
@@ -8,23 +10,14 @@ import { createRecursiveLintTool } from './recursive_lint.tool.ts'
 import { createRecursiveCloseoutTool } from './recursive_closeout.tool.ts'
 import { createRecursiveScratchTool } from './recursive_scratch.tool.ts'
 import { registerRecursiveCommand } from './commands.ts'
-import { stageBWorkflowInit } from './bootstrap.ts'
-import { evaluatePreStepGate, evaluateToolGuard, detectTamper, resolveEnforcementConfig, DEFAULT_ENFORCEMENT, type EnforcementConfig } from './enforcement.ts'
-import { detectTransitionIntent } from './lifecycle.ts'
+import { evaluateToolGuard } from './enforcement.ts'
 import { renderRecursivePolicy } from './policy.ts'
-import {
-  gateBlocked as gateBlockedEvent,
-  tamper as tamperEvent,
-  phaseIntent as phaseIntentEvent,
-  runCreated as runCreatedEvent,
-  phase as phaseEvent,
-  phaseLocked as phaseLockedEvent,
-  runState as runStateEvent,
-  runMerged as runMergedEvent,
-  subagentStart as subagentStartEvent,
-  subagentEnd as subagentEndEvent,
-} from './events.ts'
-import { recursiveProjectionUnit } from './projection.ts'
+import { fsPolicyIntent } from './fs-intent.ts'
+import { snapshotWorkspace } from './snapshot.ts'
+import { mountRecursiveRoutesOnce, makeRecursiveRoutes, type RecursiveRouteHost } from './live-route.ts'
+import { enumerateRuns } from './bootstrap.ts'
+import { getNextLegalPhase, getLockStatus } from './lock.ts'
+import { phaseLintRulesMessage } from './phase-rules.ts'
 
 export const name = '@try-works/dsh-recursive-mode'
 
@@ -71,8 +64,8 @@ export * from './delegation.ts'
 export * from './lifecycle.ts'
 export * from './enforcement.ts'
 export * from './policy.ts'
-export * from './events.ts'
-export * from './projection.ts'
+export * from './snapshot.ts'
+export * from './live-route.ts'
 
 /**
  * Bundle plugin entry. The Loader activates this row once `tools` is available
@@ -83,44 +76,29 @@ export * from './projection.ts'
 export const inject = ['tools']
 
 /**
- * Two-stage init (PROPOSAL §5.10):
- *  - Stage A (mount-time, this apply): register the isolated ctx.recursive
- *    service + the recursive_* tools + the /recursive command + the
- *    recursive:policy prompt section. No repo/run work here.
- *  - Stage B (agent/session-start): resolve the session's workspace root (R1),
- *    bootstrap the scaffold if missing, enumerate runs as dir names only, and
- *    inject a workspace-scoped notice. See stageBWorkflowInit + the
- *    agent/session-start listener below.
+ * Plugin entry (SP2 R1). Stage A (mount-time, this apply): register the
+ * isolated ctx.recursive service + the recursive_* tools + the /recursive
+ * command + the recursive:policy prompt section + the LIVE board/strip route
+ * (HTTP state + SSE), served per-workspace from the filesystem fold. No
+ * repo/run work and NO session-event emission here: zero recursive/* events
+ * are ever appended (resume-crash fix), and the board reads the live fs route.
  */
-export function apply(ctx: Context) {
+export function apply(ctx: Context, config?: { shellOnly?: boolean; repoRoot?: string }) {
+  // R4 shell split (02-to-be-plan.addendum-r4-r2-mount-resolution.md): the
+  // global bare-name row in cordis.patch.yml mounts with config.shellOnly=true
+  // to expose ONLY the client bundle for client discovery. It must register
+  // NOTHING on the server root — no tools, no /recursive command, no
+  // recursive:policy, no projection (BUG 4 always-on leak). The full server
+  // surface is mounted ONLY by the recursive preset's isolated recursive-realm,
+  // whose rows carry no config (shellOnly undefined).
+  if (config?.shellOnly) return
   ctx.effect(function* () {
     // Workspace registry: optional host service (durable). Access via ctx.get —
     // property access requires inject and would fail boot when undeclared.
     // Resolve the control-plane root strictly from the session agent's cwd.
     const workspaceRegistry = ctx.get('workspaceRegistry') as never
-    const recursive = new RecursiveRuntime(ctx, { repoRoot: process.cwd(), workspaceRegistry })
+    const recursive = new RecursiveRuntime(ctx, { repoRoot: config?.repoRoot ?? process.cwd(), workspaceRegistry })
 
-    /** Typed agent payload shape (session is a full Session). */
-    type AgentLike = { session?: Session | null }
-
-    /** Extract the session from a listener payload. */
-    const sessionOf = (p: unknown): Session | null => {
-      const a = (p as { agent?: AgentLike | null } | null)?.agent
-      return a?.session ?? null
-    }
-
-    /** Resolve the session's control-plane root (registry first, cwd fallback). */
-    const rootOf = async (p: unknown): Promise<string> => {
-      const a = (p as { agent?: AgentLike | null } | null)?.agent
-      const root = await recursive.resolveRootFor(a as { session?: { header?: { cwd?: string } } } | null)
-      return root ?? a?.session?.header.cwd ?? process.cwd()
-    }
-
-    /** Emit one recursive/* event into the session log (log-only). */
-    const emit = (session: Session | null, type: string, data: unknown) => {
-      if (!session) return
-      try { (session.append as unknown as (t: string, d: unknown) => void)(type, data) } catch { /* log-only; never fail the gate on an emit error */ }
-    }
     const disposers = [
       ctx.tools.register(createRecursiveStatusTool(recursive)),
       ctx.tools.register(createRecursiveInitTool(recursive)),
@@ -144,42 +122,28 @@ export function apply(ctx: Context) {
         name: 'recursive:policy',
         order: 55,
         text: (context: unknown) => {
-          const agent = (context as { agent?: { session?: { header?: { cwd?: string }; events?: { type: string; data?: Record<string, unknown> }[] } } } | undefined)?.agent
+          const agent = (context as { agent?: { session?: { header?: { cwd?: string } } } } | undefined)?.agent
           if (!agent) return ''
-          const cwd = agent.session?.header?.cwd ?? ''
-          if (!cwd) return ''
-          const events = agent.session?.events ?? []
-          const intent = detectTransitionIntent(events as never)
-          if (!intent || intent.worktreeRoot === '') return ''
-          return renderRecursivePolicy({ worktreeRoot: intent.worktreeRoot, runId: intent.runId, folded: recursive.foldPhase(events as never), config: recursive.enforcementConfig })
+          // SP3 R5 policy-render fix: derive intent from the FILESYSTEM, not the
+          // retired recursive/phase-intent session event (zero-emission removed
+          // the emitter, so detectTransitionIntent was ALWAYS null and this
+          // section rendered ''). Pure read-only fs folding; no recursive/*
+          // events are appended.
+          const intent = fsPolicyIntent(agent, workspaceRegistry as never)
+          if (!intent) return ''
+          return renderRecursivePolicy({ worktreeRoot: intent.worktreeRoot, runId: intent.runId, config: recursive.enforcementConfig })
         },
       }))
     }
 
-    // Phase C R3: agent/pre-step phase-transition gate (Layer 1, caller of the
-    // lifecycle transition set). Reads on transition intent only; rejects (strict)
-    // or warns (advisory) when the target gates fail.
-    const agentEvents = ctx as unknown as { on?: (event: string, listener: (payload: unknown, next?: unknown) => unknown) => () => void }
-    if (agentEvents.on) {
-      disposers.push(agentEvents.on('agent/pre-step', (payload, next) => {
-        const p = payload as { agent?: { session?: { events?: { type: string; data?: Record<string, unknown> }[] } } } | null
-        const events = p?.agent?.session?.events ?? []
-        const session = sessionOf(p)
-        const intent = recursive.detectTransitionIntent(events as never)
-        const decision = evaluatePreStepGate(events as never, recursive.enforcementConfig.preStep)
-        void (async () => {
-          // Emit a committed run-state (blocked) when a gate rejects the intent —
-          // the board then shows the run blocked, not merely a log message.
-          if (decision.gateBlocked && intent?.runId) {
-            const worktreeRoot = intent?.worktreeRoot ?? (await rootOf(p))
-            emit(session, 'recursive/gate-blocked', gateBlockedEvent({ runId: intent.runId, worktreeRoot, phase: intent?.targetArtifact ?? '', failures: decision.failures, kind: 'pre-step' }))
-            emit(session, 'recursive/run-state', runStateEvent({ runId: intent.runId, worktreeRoot, state: 'blocked', reason: 'gate-blocked: ' + decision.failures.join('; ') }))
-          }
-        })()
-        if (decision.kind === 'reject') return { kind: 'reject' }
-        return typeof next === 'function' ? next() : { kind: 'enter', messages: [] }
-      }))
-    }
+    // Phase C R3 (Layer 1, agent/pre-step proactive intent gate) is RETIRED
+    // under zero-emission (SP2 R1): its only signal was the recursive/phase-intent
+    // session event, whose emitter is now deleted, and it was ADVISORY by default
+    // (it never rejected; its sole side effect was the now-removed emission).
+    // Enforcement is preserved where it actually bites: Layer 2 (tools/pre-execute
+    // inspects the REAL tool call args below) plus the recursive_lock tool's own
+    // prerequisite validation in lockArtifact — strictly more reliable than the
+    // heuristic intent scan. See 03-implementation-summary.addendum-r1-*.md.
 
     // Phase C R4: tools/pre-execute surgical guards (Layer 2, caller of the
     // transition set). Scope-filtered to the active run's worktree.
@@ -195,87 +159,68 @@ export function apply(ctx: Context) {
         if (decision.kind === 'allow') return typeof next === 'function' ? next() : { kind: 'allow' }
         if (decision.kind === 'deny') return decision
         // ask -> in advisory we let it through with a warn (the approval seam is Phase D)
-        return typeof next === 'function' ? next() : { kind: 'allow' }
       }))
     }
 
-    // Phase C R8 + Phase D R1: fs/observed lock-tamper warnings -> recursive/tamper event.
-    const fsRuntime = ctx as unknown as { on?: (event: string, listener: (payload: unknown) => void) => () => void }
-    if (fsRuntime.on) {
-      disposers.push(fsRuntime.on('fs/observed', (payload) => {
-        const p = payload as { target?: { displayPath?: string }; agent?: AgentLike | null } | null
-        const path = p?.target?.displayPath ?? ''
-        if (!path) return
-        // B3: tamper detection is scoped to the SESSION's control-plane root,
-        // not the host checkout.
-        const sessionCwd = p?.agent?.session?.header.cwd ?? ''
-        const tamper = detectTamper(path, sessionCwd, '')
-        if (!tamper) return
-        // Resolve the worktree root from the tampered path (strip /.recursive/run/<id>/).
-        const normalized = path.replace(/\\/g, '/')
-        const marker = '/.recursive/run/'
-        const idx = normalized.indexOf(marker)
-        const worktreeRoot = idx >= 0 ? normalized.slice(0, idx) : sessionCwd
-        // Prefer the observing session's own log (additive); fall back to the
-        // session store list only when the payload carries no session.
-        const session = sessionOf(p) ?? null
-        if (session) {
-          emit(session, 'recursive/tamper', tamperEvent({ runId: tamper.runId, worktreeRoot, path: tamper.path, reason: tamper.reason }))
-          return
-        }
-        const sessions = ctx.get('sessions') as { list?: () => Session[] } | undefined
-        const match = sessions?.list?.().find((s) => {
-          const cwd = (s.header?.cwd ?? '').replace(/\\/g, '/')
-          return cwd === '' || cwd === worktreeRoot || cwd.startsWith(worktreeRoot + '/')
-        })
-        if (match) emit(match, 'recursive/tamper', tamperEvent({ runId: tamper.runId, worktreeRoot, path: tamper.path, reason: tamper.reason }))
+    // SP3 R5: agent/pre-step lint-rules injection (pre-step contract verified: the
+    // listener returns { kind: 'enter', messages: [...messages, injected] } and the
+    // returned array REPLACES the default [...claimed, context]). When the session's
+    // control-plane root has an active recursive run whose current phase doc is
+    // DRAFT, prepend a compact system-reminder with THAT phase's required sections +
+    // gates. Pure fs read (zero-emission): never appends recursive/* events.
+    const agentRuntime = ctx as unknown as { on?: (event: string, listener: (payload: unknown, next?: unknown) => unknown) => () => void }
+    if (agentRuntime.on) {
+      disposers.push(agentRuntime.on('agent/pre-step', async (payload, next) => {
+        const p = payload as {
+          messages?: Array<{ content: Array<{ type: string; text?: string }> }>,
+          agent?: { session?: { header?: { cwd?: string } } } | null,
+        } | null
+        const messages = p?.messages ?? []
+        const agent = p?.agent ?? null
+        const cwd = agent?.session?.header?.cwd ?? ''
+        // delegate first so later listeners keep veto power, then fold ours on
+        if (typeof next === 'function') await next()
+        if (!cwd) return { kind: 'enter', messages } as const
+        const root = await recursive.resolveRootForRoute(undefined, cwd, undefined)
+        if (!root) return { kind: 'enter', messages } as const
+        const runs = enumerateRuns(root)
+        if (runs.length === 0) return { kind: 'enter', messages } as const
+        const runId = runs[runs.length - 1]
+        const runDir = join(root, '.recursive', 'run', runId)
+        if (!existsSync(runDir)) return { kind: 'enter', messages } as const
+        const phase = getNextLegalPhase(runDir)
+        if (!phase) return { kind: 'enter', messages } as const
+        // only inject when the phase doc is DRAFT (not locked/missing).
+        const phasePath = join(runDir, phase)
+        const status = existsSync(phasePath) ? getLockStatus(phasePath) : null
+        if (status !== 'DRAFT') return { kind: 'enter', messages } as const
+        const reminder = phaseLintRulesMessage(phase)
+        return {
+          kind: 'enter',
+          messages: [...messages, createUserMessage({ content: [{ type: 'text', text: reminder }], source: { kind: 'plugin', plugin: '@try-works/dsh-recursive-mode' } })],
+        } as const
       }))
     }
 
-    // Phase D R2: register the recursive projection unit (activates only when a
-    // projection registry is composed — headless assemblies stay unaffected).
-    // The unit's cell is per-session: a session's own log is its workspace, so
-    // an accept-all init is scoped by the session boundary (see projection.ts
-    // emptyRecursiveFoldState). The registry (if present) is cached here so the
-    // session-start boundary can re-read run state after the projection drove.
-    let sessionProjections: { snapshot?: (session: Session) => { values: Partial<Record<string, unknown>> } } | null = null
-    ctx.inject(['sessionProjections'], (projectionCtx) => {
-      const registry = (projectionCtx as { sessionProjections?: { register: (def: unknown) => () => void; snapshot?: (session: Session) => unknown } }).sessionProjections
-      if (registry?.register) {
-        disposers.push(registry.register(recursiveProjectionUnit))
-        sessionProjections = registry as { snapshot?: (session: Session) => { values: Partial<Record<string, unknown>> } }
+    // Phase C R8: fs/observed lock-tamper WARNINGS are served to the board via the
+    // mountOnce-global: apply() runs per-session, but the route must register
+    // exactly once (WebServer.register throws on duplicate kind+path) and serve
+    // PER-WORKSPACE state. No-op when the host composes no webServer (headless).
+    const webServer = ctx.get('webServer') as
+      | { register: (route: { kind: string; path: string; handler: unknown }) => () => void }
+      | undefined
+    const sessionsStore = ctx.get('sessions') as
+      | { get?: (id: string) => { header?: { cwd?: string } } | undefined }
+      | undefined
+    if (webServer) {
+      const host: RecursiveRouteHost = {
+        // sessionId PRIMARY: the host resolves cwd from the attached session header;
+        // the client-passed cwd is a fallback hint (hydration / headless).
+        resolveRoot: async (sessionId: string | undefined, cwd: string) => recursive.resolveRootForRoute(sessionId, cwd, sessionsStore),
+        snapshot: async (root: string) => snapshotWorkspace(root),
+        revision: () => 1,
       }
-    })
-
-    // Stage B (R6): agent/session-start workflow init, workspace-scoped.
-    // NEW sessions emit recursive/run-state('active') after init; resumed
-    // sessions replay the projection (already folded from the persisted log) —
-    // no duplicate run-created. run-created is emitted by the lifecycle at the
-    // init/lock boundary (the only place a run's files first exist).
-    const events = ctx as unknown as { on?: (event: string, listener: (payload: unknown) => void) => () => void }
-    if (events.on) {
-      disposers.push(events.on('agent/session-start', (payload) => {
-        const p = payload as { agent?: AgentLike | null; source?: 'new' | 'resume' }
-        const session = sessionOf(p)
-        const cwd = p?.agent?.session?.header?.cwd
-        if (!cwd) return
-        void (async () => {
-          const root = await recursive.resolveRootFor(p?.agent as { session?: { header?: { cwd?: string } } } | null)
-          if (!root) return
-          const result = stageBWorkflowInit({ root, source: p.source === 'resume' ? 'resume' : 'new' })
-          // Emit run-state for the active run (from the projected wire value, the
-          // one same-source view) when the projection registry is present.
-          if (session) {
-            const runId = result.activeRunId ?? result.runs[result.runs.length - 1] ?? ''
-            if (runId) {
-              const snap = sessionProjections?.snapshot?.(session)
-              const proj = (snap?.values as { recursive?: Record<string, Record<string, { state?: string }>> } | undefined)?.recursive
-              const state = proj?.[root]?.[runId]?.state ?? 'active'
-              emit(session, 'recursive/run-state', runStateEvent({ runId, worktreeRoot: root, state: state as 'new' | 'active' | 'paused' | 'blocked' | 'complete' }))
-            }
-          }
-        })()
-      }))
+      disposers.push(mountRecursiveRoutesOnce('@try-works/dsh-recursive-mode', () => makeRecursiveRoutes(host), webServer))
     }
 
     yield () => { for (const d of disposers) d() }

package/src/init-templates.ts

@@ -0,0 +1,276 @@
+/**
+ * Init templates (R5): canonical-parity port of recursive-init.py's
+ * requirements_content / worktree_content / detect_git_context, plus full
+ * per-phase templates derived from the canonical artifact-template sections
+ * (get_artifact_required_sections) + TODO + Coverage/Approval FAIL gates.
+ *
+ * 00-requirements.md + 00-worktree.md are byte-identical to canonical
+ * recursive-init.py output (LF, no BOM). Later phases are structural: every
+ * required section heading + the two FAIL gates, so lint fails honestly until
+ * the phase is actually worked.
+ */
+import { execFileSync } from 'node:child_process'
+import { join } from 'node:path'
+import { getArtifactRequiredSections } from './phase-rules.ts'
+
+export interface GitContext {
+  baselineType: string
+  baselineReference: string
+  comparisonReference: string
+  normalizedBaseline: string
+  normalizedComparison: string
+  normalizedDiffCommand: string
+  baseBranch: string
+  worktreeBranch: string
+  baseCommit: string
+  notes: string
+}
+
+/**
+ * detect_git_context(): canonical parity. Returns {context, error} — never
+ * throws on missing git; error is surfaced in the worktree template note.
+ */
+export function detectGitContext(repoRoot: string): { context: Partial<GitContext>; error: string | null } {
+  const run = (args: string[]): string | null => {
+    try {
+      return execFileSync('git', args, { cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+    } catch {
+      return null
+    }
+  }
+  const headSha = run(['rev-parse', '--verify', 'HEAD^{commit}'])
+  if (!headSha) {
+    return { context: {}, error: 'Unable to resolve HEAD commit for Phase 0 diff basis prefill: git rev-parse returned no output' }
+  }
+  const branch = run(['symbolic-ref', '--quiet', '--short', 'HEAD']) || '(detached HEAD)'
+  const diffCommand = 'git diff --name-only ' + headSha
+  return {
+    context: {
+      baselineType: 'local commit',
+      baselineReference: headSha,
+      comparisonReference: 'working-tree',
+      normalizedBaseline: headSha,
+      normalizedComparison: 'working-tree',
+      normalizedDiffCommand: diffCommand,
+      baseBranch: branch,
+      worktreeBranch: branch,
+      baseCommit: headSha,
+      notes: 'recursive-init prefilled this executable diff basis from the current HEAD commit. If Phase 0 later changes the chosen baseline, update every diff-basis field and rerun lint before locking.',
+    },
+    error: null,
+  }
+}
+
+/**
+ * requirements_content(run_id, template, from_issue): byte-identical to the
+ * canonical recursive-init.py function (LF, template flavor in Scope note).
+ */
+export function requirementsContent(runId: string, template = 'feature', fromIssue = ''): string {
+  const inputs = ['- [chat summary or source notes if captured in repo]']
+  if (fromIssue.trim()) inputs.push('- Source: ' + fromIssue.trim())
+  const inputsBlock = inputs.join('\n')
+  return [
+    'Run: `/.recursive/run/' + runId + '/`',
+    'Phase: `00 Requirements`',
+    'Status: `DRAFT`',
+    'Workflow version: `recursive-mode-audit-v2`',
+    'Inputs:',
+    inputsBlock,
+    'Outputs:',
+    '- `/.recursive/run/' + runId + '/00-requirements.md`',
+    'Scope note: This document defines stable requirement identifiers and acceptance criteria. (Template: ' + template + ')',
+    '',
+    '## TODO',
+    '',
+    '- [ ] Elicit requirements from user/context',
+    '- [ ] Define requirement identifiers (R1, R2, ...)',
+    '- [ ] Write acceptance criteria for each requirement',
+    '- [ ] Document out of scope items (OOS1, OOS2, ...)',
+    '- [ ] List constraints and assumptions',
+    '- [ ] Complete Coverage Gate checklist',
+    '- [ ] Complete Approval Gate checklist',
+    '',
+    '## Requirements',
+    '',
+    '### `R1` <short title>',
+    '',
+    'Description:',
+    'Acceptance criteria:',
+    '- [observable condition 1]',
+    '- [observable condition 2]',
+    '',
+    '## Out of Scope',
+    '',
+    '- `OOS1`: ...',
+    '',
+    '## Constraints',
+    '',
+    '- ...',
+    '',
+    '## Coverage Gate',
+    '...',
+    'Coverage: FAIL',
+    '',
+    '## Approval Gate',
+    '...',
+    'Approval: FAIL',
+  ].join('\n') + '\n'
+}
+
+/**
+ * worktree_content(run_id, repo_root, git_context, prefill_error): byte-identical
+ * to the canonical recursive-init.py function.
+ */
+export function worktreeContent(runId: string, repoRoot: string, git: Partial<GitContext>, prefillError: string | null): string {
+  const baseBranch = git.baseBranch ?? '(resolve during Phase 0)'
+  const worktreeBranch = git.worktreeBranch ?? '(resolve during Phase 0)'
+  const baseCommit = git.baseCommit ?? '<resolve-before-locking>'
+  const baselineType = git.baselineType ?? 'local commit'
+  const baselineReference = git.baselineReference ?? '<resolve-before-locking>'
+  const comparisonReference = git.comparisonReference ?? 'working-tree'
+  const normalizedBaseline = git.normalizedBaseline ?? '<resolve-before-locking>'
+  const normalizedComparison = git.normalizedComparison ?? 'working-tree'
+  const normalizedDiffCommand = git.normalizedDiffCommand ?? 'git diff --name-only <resolve-before-locking>'
+  const notes = git.notes ?? 'Populate an executable diff basis before locking Phase 0. Lint and lock will fail until the normalized basis matches live git state.'
+  const setupNote = prefillError
+    ? 'recursive-init could not prefill the Phase 0 diff basis automatically: ' + prefillError
+    : 'recursive-init detected the current repository context and prefilled the Phase 0 diff basis.'
+  return [
+    'Run: `/.recursive/run/' + runId + '/`',
+    'Phase: `00 Worktree`',
+    'Status: `DRAFT`',
+    'Inputs:',
+    '- `/.recursive/run/' + runId + '/00-requirements.md`',
+    '- Current git repository state',
+    'Outputs:',
+    '- `/.recursive/run/' + runId + '/00-worktree.md`',
+    'Scope note: This document records the Phase 0 worktree context and the executable diff basis that all later audited phases must reuse.',
+    '',
+    '## TODO',
+    '',
+    '- [ ] Confirm the selected worktree location and isolation approach',
+    '- [ ] Confirm the base branch and worktree branch values',
+    '- [ ] Run setup and verify the clean test baseline',
+    '- [ ] Confirm the diff basis fields still match live git state',
+    '- [ ] Complete Coverage Gate checklist',
+    '- [ ] Complete Approval Gate checklist',
+    '',
+    '## Directory Selection',
+    '',
+    '- Repository root: `' + repoRoot + '`',
+    '- Preferred worktree location: `.worktrees/' + runId + '/`',
+    '- Update this section with the actual selected location before locking Phase 0.',
+    '',
+    '## Safety Verification',
+    '',
+    '- Original branch / repo state observed at init time: `' + baseBranch + '`',
+    '- Isolation still must be confirmed after the actual worktree is created.',
+    '',
+    '## Worktree Creation',
+    '',
+    '- Intended worktree branch: `' + worktreeBranch + '`',
+    '- Record the actual worktree creation command and output before locking.',
+    '',
+    '## Main Branch Protection',
+    '',
+    '- Base branch source of truth at init time: `' + baseBranch + '`',
+    '- Explicitly document any deviation from isolated worktree execution before locking.',
+    '',
+    '## Project Setup',
+    '',
+    '- Init-time note: ' + setupNote,
+    '- Replace this section with the actual setup commands and results during Phase 0.',
+    '',
+    '## Test Baseline Verification',
+    '',
+    '- Record the baseline commands and results after setup completes.',
+    '',
+    '## Worktree Context',
+    '',
+    '- Base branch: `' + baseBranch + '`',
+    '- Worktree branch: `' + worktreeBranch + '`',
+    '- Base commit: `' + baseCommit + '`',
+    '',
+    '## Diff Basis For Later Audits',
+    '',
+    '- Baseline type: `' + baselineType + '`',
+    '- Baseline reference: `' + baselineReference + '`',
+    '- Comparison reference: `' + comparisonReference + '`',
+    '- Normalized baseline: `' + normalizedBaseline + '`',
+    '- Normalized comparison: `' + normalizedComparison + '`',
+    '- Normalized diff command: `' + normalizedDiffCommand + '`',
+    '- Base branch: `' + baseBranch + '`',
+    '- Worktree branch: `' + worktreeBranch + '`',
+    '- Diff basis notes: `' + notes + '`',
+    '',
+    '## Traceability',
+    '',
+    '- Recursive workflow safety -> Phase 0 records a reusable executable diff basis before audited phases begin.',
+    '',
+    '## Coverage Gate',
+    '',
+    '- [ ] Worktree location and branch context are recorded',
+    '- [ ] Setup and clean baseline verification are recorded',
+    '- [ ] Diff basis fields are executable against live git state',
+    '',
+    'Coverage: FAIL',
+    '',
+    '## Approval Gate',
+    '',
+    '- [ ] Phase 0 context is ready for downstream audited phases',
+    '- [ ] No unresolved setup or diff-basis inconsistencies remain',
+    '',
+    'Approval: FAIL',
+  ].join('\n') + '\n'
+}
+
+/**
+ * Later-phase template: required sections (canonical get_artifact_required_
+ * sections) as ## headings + TODO + FAIL gates. Structural scaffold: the phase
+ * author fills each section; lint stays FAIL until Coverage/Approval are set.
+ */
+export function laterPhaseContent(runId: string, fileName: string, workflowProfile = 'recursive-mode-audit-v2'): string {
+  const sections = getArtifactRequiredSections(fileName, workflowProfile)
+  const lines = [
+    'Run: `/.recursive/run/' + runId + '/`',
+    'Phase: `' + fileName.replace(/\.md$/, '').replace(/^0?/, '') + '`',
+    'Status: `DRAFT`',
+    'Workflow version: `' + workflowProfile + '`',
+    'Inputs:',
+    '- (list upstream artifacts re-read for this phase)',
+    'Outputs:',
+    '- `/.recursive/run/' + runId + '/' + fileName + '`',
+    'Scope note: Scaffold generated by the recursive-mode plugin (R5). Fill every required section before lint.',
+    '',
+    '## TODO',
+    '',
+    '- [ ] Work through every required section below',
+    '- [ ] Record evidence and traceability',
+    '- [ ] Complete Coverage Gate checklist',
+    '- [ ] Complete Approval Gate checklist',
+  ];
+  for (const section of sections) {
+    if (section === 'TODO') continue
+    lines.push('', '## ' + section, '', '- (fill)')
+  }
+  lines.push('', '## Coverage Gate', '', 'Coverage: FAIL', '', '## Approval Gate', '', 'Approval: FAIL', '')
+  return lines.join('\n')
+}
+
+/**
+ * Scaffold dirs under a run (addenda/subagents/router-prompts/evidence + subs).
+ * Mirrors canonical recursive-init.py's ensure_directory sequence.
+ */
+export const RUN_SCAFFOLD_DIRS = [
+  'addenda',
+  'subagents',
+  'router-prompts',
+  'evidence',
+  'evidence/screenshots',
+  'evidence/logs',
+  'evidence/perf',
+  'evidence/traces',
+  'evidence/review-bundles',
+  'evidence/router',
+  'evidence/other',
+]