@try-works/dsh-recursive-mode 0.1.0

package/src/client/node.ts

@@ -0,0 +1,156 @@
+/**
+ * Conversation run node (Phase D R7, §11.6): a structural ConversationNodeDefinition
+ * over the recursive/* event family, keyed by runId + worktreeRoot. One compact,
+ * live node per run in the Chat view. PURE fold (no React) — the renderer lives
+ * in slots.ts.
+ *
+ * The real ConversationNodeDefinition contract arrives from
+ * @deepseek-ai/dsh-client-runtime/client at compose time; the structural shape
+ * here is type-compatible with the cookbook surface (match/start/update/
+ * buildViewNode + target/kind). The host links the bundle's exports to the real
+ * runtime identities.
+ */
+import type { ClientSessionEvent } from './contract.ts'
+import type { RecursiveRunCard } from '../types.ts'
+
+export const RECURSIVE_NODE_KIND = 'recursive/run'
+
+/** The chat-node payload the renderer receives (pure derived state). */
+export interface RecursiveNodeData {
+  readonly runId: string
+  readonly worktreeRoot: string
+  readonly state: string
+  readonly currentPhase: string | null
+  readonly lockedCount: number
+  readonly totalPhases: number
+  readonly tampered: boolean
+  readonly gateBlocked: boolean
+  readonly mergedToRepoRoot?: string
+}
+
+/** Pure fold state for one run node. */
+export interface RecursiveNodeState {
+  runId: string
+  worktreeRoot: string
+  state: string
+  phases: Record<string, { phase: string; status: string }>
+  tampered: boolean
+  gateBlocked: boolean
+  mergedToRepoRoot?: string
+}
+
+const GROUP_ORDER: readonly string[] = ['00', '01', '01.5', '02', '03', '03.5', '04', '05', '06', '07', '08']
+const GROUP_INDEX = new Map(GROUP_ORDER.map((g, i) => [g, i]))
+
+function phaseGroupOf(phase: string): string | null {
+  const m = /^(\d{2}(?:\.\d)?)(?:-|$)/.exec(phase)
+  return m ? m[1] : null
+}
+
+function currentPhaseOf(phases: Record<string, { phase: string; status: string }>): string | null {
+  let best: string | null = null
+  let bestIdx = -1
+  for (const key of Object.keys(phases)) {
+    const g = phaseGroupOf(key)
+    if (g === null) continue
+    const idx = GROUP_INDEX.get(g) ?? -1
+    if (idx > bestIdx) { bestIdx = idx; best = key }
+  }
+  return best
+}
+
+function nodeDataOf(s: RecursiveNodeState): RecursiveNodeData {
+  const lockedCount = Object.values(s.phases).filter(p => p.status === 'LOCKED').length
+  return {
+    runId: s.runId,
+    worktreeRoot: s.worktreeRoot,
+    state: s.state,
+    currentPhase: currentPhaseOf(s.phases),
+    lockedCount,
+    totalPhases: Object.keys(s.phases).length,
+    tampered: s.tampered,
+    gateBlocked: s.gateBlocked,
+    ...(s.mergedToRepoRoot === undefined ? {} : { mergedToRepoRoot: s.mergedToRepoRoot }),
+  }
+}
+
+/** Extract a stable (runId, worktreeRoot) business id + lifecycle role from one event. */
+export function matchRecursiveNode(event: ClientSessionEvent): { id: string; role: 'start' | 'update' } | null {
+  if (typeof event.type !== 'string' || !event.type.startsWith('recursive/')) return null
+  const data = event.data ?? {}
+  const runId = typeof data.runId === 'string' ? data.runId : ''
+  const worktreeRoot = typeof data.worktreeRoot === 'string' ? data.worktreeRoot : ''
+  if (runId === '' || worktreeRoot === '') return null
+  return { id: worktreeRoot + '\u0000' + runId, role: event.type === 'recursive/run-created' ? 'start' : 'update' }
+}
+
+/** Fold one recursive/* event into the node state. */
+export function foldRecursiveNode(s: RecursiveNodeState | undefined, event: ClientSessionEvent): RecursiveNodeState {
+  const data = event.data ?? {}
+  const runId = typeof data.runId === 'string' ? data.runId : ''
+  const worktreeRoot = typeof data.worktreeRoot === 'string' ? data.worktreeRoot : ''
+  const base: RecursiveNodeState = s ?? {
+    runId,
+    worktreeRoot,
+    state: 'active',
+    phases: {},
+    tampered: false,
+    gateBlocked: false,
+  }
+
+  switch (event.type) {
+    case 'recursive/run-created':
+      base.runId = runId
+      base.worktreeRoot = worktreeRoot
+      return base
+    case 'recursive/phase': {
+      const phase = String(data.phase ?? '')
+      if (phase !== '') base.phases[phase] = { phase, status: String(data.status ?? '') }
+      return base
+    }
+    case 'recursive/phase-locked': {
+      const phase = String(data.phase ?? '')
+      if (phase !== '') base.phases[phase] = { phase, status: 'LOCKED' }
+      return base
+    }
+    case 'recursive/gate-blocked':
+      base.gateBlocked = true
+      return base
+    case 'recursive/tamper':
+      base.tampered = true
+      return base
+    case 'recursive/run-state':
+      base.state = typeof data.state === 'string' ? data.state : base.state
+      return base
+    case 'recursive/run-merged': {
+      const repoRoot = typeof data.repoRoot === 'string' ? data.repoRoot : ''
+      if (repoRoot !== '') {
+        base.mergedToRepoRoot = repoRoot
+        base.worktreeRoot = repoRoot
+      }
+      return base
+    }
+    default:
+      return base
+  }
+}
+
+/** The structural ConversationNodeDefinition (host links to the real contract). */
+export const recursiveNodeDefinition = {
+  kind: RECURSIVE_NODE_KIND,
+  target: 'chat',
+  match: matchRecursiveNode,
+  start: (_ctx: unknown, match: { event: ClientSessionEvent }): RecursiveNodeState => foldRecursiveNode(undefined, match.event),
+  update: (ctx: { state: RecursiveNodeState }, match: { event: ClientSessionEvent }): RecursiveNodeState => foldRecursiveNode(ctx.state, match.event),
+  buildViewNode: (ctx: { key: string; id: string; state?: RecursiveNodeState }) => {
+    const state = ctx.state
+    if (state === undefined) return null
+    return {
+      key: ctx.key,
+      kind: RECURSIVE_NODE_KIND,
+      id: ctx.id,
+      target: 'chat',
+      data: nodeDataOf(state),
+    }
+  },
+}

package/src/client/settings.tsx

@@ -0,0 +1,18 @@
+/**
+ * Recursive settings page (Phase D R8, §11.8): a settings.section list entry
+ * surfacing the host-owned enforcement config. The client is read-mostly; all
+ * writes ride the host config path (never run files).
+ */
+import { createElement } from 'react'
+
+export interface RecursiveSettingsProps {
+  close: () => void
+}
+
+export function RecursiveSettings({ close }: RecursiveSettingsProps) {
+  return createElement('div', { className: 'rec-settings' },
+    createElement('h2', {}, 'Recursive'),
+    createElement('p', {}, 'Enforcement policy, scratch format, provider defaults, and preset install path are configured on the host. The client is read-only (§11.9).'),
+    createElement('button', { onClick: close }, 'Close'),
+  )
+}

package/src/client/slots.ts

@@ -0,0 +1,67 @@
+/**
+ * Slot registrations (Phase D R5/R6/R7/R8, §11.8): the sidebar launcher, the
+ * shell.overlay board, the conversation.input.dock status strip, and the
+ * settings.section page. The details-seat inspector is a swap driven by the
+ * board cards' click (R6); the strip + board + settings are additive seats.
+ *
+ * Self-contained structural seam: the real slot registry + runtime standard
+ * kit arrive from @deepseek-ai/dsh-client-ui-slots + @deepseek-ai/dsh-client-runtime
+ * at compose time; this module consumes the minimal ClientContext shape
+ * (contract.ts). The client is READ-ONLY (R9) — no filesystem, no mutation.
+ */
+import { createElement } from 'react'
+import type { ClientContext, RecursiveProjectionReader } from './contract.ts'
+import type { RecursiveProjection } from '../types.ts'
+import { Board } from './board.tsx'
+import { StatusStrip } from './strip.tsx'
+import { RecursiveSettings } from './settings.tsx'
+
+/** Narrow the projection whole value to the worktree-grouped run map. */
+function projectionOf(reader: RecursiveProjectionReader): RecursiveProjection | undefined {
+  return reader('recursive') as RecursiveProjection | undefined
+}
+
+export function registerSlots(ctx: ClientContext): () => void {
+  const disposers: (() => void)[] = []
+
+  // Board launcher in the sidebar footer action list (always visible).
+  disposers.push(ctx.slots.inject('sidebar.footer.action', () => ctx.slots.register({
+    name: 'sidebar.footer.action',
+    id: 'recursive',
+    order: 50,
+    label: 'Recursive runs',
+  }, () => createElement('button', { className: 'rec-launcher', title: 'Recursive runs' }, '⧉'))))
+
+  // Board panel overlay (root scope, cross-session read).
+  disposers.push(ctx.slots.inject('shell.overlay', () => ctx.slots.register({
+    name: 'shell.overlay',
+    id: 'recursive-board',
+    order: 10,
+  }, (props: { useProjection?: RecursiveProjectionReader }) => {
+    if (props?.useProjection === undefined) return null
+    return createElement(Board, { useProjection: props.useProjection })
+  })))
+
+  // Status strip in the composer input dock (session scope).
+  disposers.push(ctx.slots.inject('conversation.input.dock', () => ctx.slots.register({
+    name: 'conversation.input.dock',
+    id: 'recursive-strip',
+    order: 20,
+  }, (props: { useProjection?: RecursiveProjectionReader }) => {
+    if (props?.useProjection === undefined) return null
+    return createElement(StatusStrip, { useProjection: props.useProjection })
+  })))
+
+  // Settings section (root scope, always present).
+  disposers.push(ctx.slots.inject('settings.section', () => ctx.slots.register({
+    name: 'settings.section',
+    id: 'recursive',
+    order: 90,
+    label: 'Recursive',
+  }, (props: { close: () => void }) => createElement(RecursiveSettings, { close: props.close }))))
+
+  return () => { for (const d of disposers) d() }
+}
+
+/** Export the projection reader narrow for the board/inspector/strip. */
+export { projectionOf }

package/src/client/strip.tsx

@@ -0,0 +1,28 @@
+/**
+ * Status strip (Phase D R7, §11.6): a thin glance at the active run's phase,
+ * gate state, and tamper badge, docked at conversation.input.dock. Renders
+ * nothing when no run is current.
+ */
+import { createElement } from 'react'
+import { cardFacts } from './derive.ts'
+import { listRuns } from './board.tsx'
+import type { RecursiveProjection } from '../types.ts'
+import type { RecursiveProjectionReader } from './contract.ts'
+
+export interface StripProps {
+  useProjection: RecursiveProjectionReader
+}
+
+export function StatusStrip({ useProjection }: StripProps) {
+  const projection = useProjection('recursive') as RecursiveProjection | undefined
+  const runs = listRuns(projection)
+  if (runs.length === 0) return null
+  const active = runs[runs.length - 1]
+  const facts = cardFacts(active)
+  return createElement('div', { className: 'rec-strip' },
+    createElement('span', { className: 'rec-strip-run' }, active.runId),
+    createElement('span', { className: 'rec-badge' }, facts.currentPhase ?? 'no phases'),
+    facts.gateBlocked && createElement('span', { className: 'rec-badge rec-badge-gate' }, 'gate blocked'),
+    facts.tampered && createElement('span', { className: 'rec-badge rec-badge-tamper' }, 'tampered'),
+  )
+}

package/src/client.ts

@@ -0,0 +1,11 @@
+/**
+ * Client-namespace projection of the recursive domain (Phase D R3): a pure
+ * re-export of the package's types outlet. Client code imports ONLY the
+ * client namespace (repo discipline), so ./client projects the same
+ * single-source content ./types serves to host consumers — zero duplication
+ * (the goal client.ts pattern).
+ *
+ * @module dsh-recursive-mode/client
+ */
+
+export type * from './types.ts'

package/src/closeout.ts

@@ -0,0 +1,183 @@
+/**
+ * Closeout receipt scaffolding (R2) — TS port of recursive-closeout.py.
+ * Creates/updates Phase 4/5/6/7/8 delta-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'
+
+export interface CloseoutPhaseConfig {
+  file: string
+  label: string
+  scopeNote: string
+  todoItems: string[]
+}
+
+export const PHASE_CONFIG: Record<string, CloseoutPhaseConfig> = {
+  '04': {
+    file: '04-test-summary.md',
+    label: '04 Test Summary',
+    scopeNote: 'Scaffolds the audited test-summary receipt from the existing implementation, review, and evidence context.',
+    todoItems: [
+      'Record the pre-test implementation audit and execution environment',
+      'Capture exact commands, evidence, and final results',
+      'Complete the audited test-summary gates before locking',
+    ],
+  },
+  '05': {
+    file: '05-manual-qa.md',
+    label: '05 Manual QA',
+    scopeNote: 'Scaffolds the manual-QA receipt and captures any preview URL evidence that should appear in the QA record.',
+    todoItems: [
+      'Declare the QA execution mode and supporting evidence',
+      'Record the manual QA scenarios and observed results',
+      'Complete Coverage and Approval gates before locking',
+    ],
+  },
+  '06': {
+    file: '06-decisions-update.md',
+    label: '06 Decisions Update',
+    scopeNote: 'Scaffolds the compact decision-ledger delta receipt for the completed run closeout.',
+    todoItems: [
+      'Record the exact decisions delta applied during closeout',
+      'Reference the updated decision ledger entry',
+      'Complete the audited decision-update gates before locking',
+    ],
+  },
+  '07': {
+    file: '07-state-update.md',
+    label: '07 State Update',
+    scopeNote: 'Scaffolds the compact state-ledger delta receipt for the validated final repository state.',
+    todoItems: [
+      'Record the exact state delta applied during closeout',
+      'Reference the updated state ledger summary',
+      'Complete the audited state-update gates before locking',
+    ],
+  },
+  '08': {
+    file: '08-memory-impact.md',
+    label: '08 Memory Impact',
+    scopeNote: 'Scaffolds the compact memory-plane delta receipt for the final validated run impact.',
+    todoItems: [
+      'Review affected memory docs and freshness outcomes',
+      'Document uncovered paths and router/parent refresh work',
+      'Complete the audited memory-impact gates before locking',
+    ],
+  },
+}
+
+const REQUIRED_SECTIONS: Record<string, string[]> = {
+  '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'],
+  '07': ['TODO', 'State Changes Applied', 'Rationale', 'Resulting State Summary', 'Traceability', 'Coverage Gate', 'Approval Gate'],
+  '08': ['TODO', 'Diff Basis', 'Changed Paths Review', 'Affected Memory Docs', 'Uncovered Paths', 'Router and Parent Refresh', 'Run-Local Skill Usage Capture', 'Skill Memory Promotion Review', 'Final Status Summary', 'Traceability', 'Coverage Gate', 'Approval Gate'],
+}
+
+const SECTION_BODIES: Record<string, string> = {
+  'Pre-Test Implementation Audit': '- Re-read the implementation summary, code review, addenda, and owned diff before finalizing this test receipt.',
+  'Environment': '- Record the actual runtime, tool versions, and any disposable-repo constraints here before locking.',
+  'Execution Mode': '- Record whether test execution was local, CI-backed, or hybrid before locking.',
+  'Commands Executed (Exact)': '- Record the exact commands run for this test summary, one command per bullet.',
+  'Results Summary': '- Summarize the final pass/fail outcomes and any reruns here before locking.',
+  'Evidence and Artifacts': '- List concrete evidence paths under `/.recursive/run/<run-id>/evidence/` that support this phase.',
+  'Failures and Diagnostics (if any)': '- Record expected failures and any final diagnostics here; use `None.` only when no diagnostics were needed.',
+  'Flake/Rerun Notes': '- Record any reruns or explicitly state that none were required.',
+  'QA Execution Record': '- QA Execution Mode: agent-operated\n- Agent Executor: populate the actual executor before locking\n- Tools Used: populate the actual tools used before locking\n- Evidence Path: populate the concrete QA evidence path before locking',
+  'QA Scenarios and Results': '- Record each manual QA scenario and observed result here before locking.',
+  'User Sign-Off': '- Approved by: N/A (set a real approver when QA mode requires human sign-off)\n- Date: N/A (set a real approval date when required)',
+  'Decisions Changes Applied': '- Record the exact `.recursive/DECISIONS.md` delta applied during closeout.',
+  'Resulting Decision Entry': '- Point to the final ledger entry heading or path after updating `.recursive/DECISIONS.md`.',
+  'State Changes Applied': '- Record the exact `.recursive/STATE.md` delta applied during closeout.',
+  'Resulting State Summary': '- Summarize the final state line or section that now reflects the completed run.',
+  'Rationale': '- Record why this closeout delta was necessary and how it aligns with the completed run.',
+  'Traceability': '- Map the closeout evidence back to the in-scope requirements before locking.',
+  'Diff Basis': '- Reconfirm the final memory review against the executable Phase 0 diff basis before locking.',
+  'Changed Paths Review': '- Record the final changed product/control-plane paths reviewed for memory impact.',
+  'Affected Memory Docs': '- List the affected memory docs under `/.recursive/memory/`, including any skill-memory router or shard docs reviewed or updated before locking.',
+  'Uncovered Paths': '- Record uncovered paths or replace with `None.` only after the memory review is complete.',
+  'Router and Parent Refresh': '- Record any router, parent, freshness, or skill-memory updates made in the memory plane.',
+  'Run-Local Skill Usage Capture': [
+    '- Skill Usage Relevance: not-relevant',
+    '- Available Skills: record the skills available in the run environment, or `none`',
+    '- Skills Sought: record any skills the run tried to discover, or `none`',
+    '- Skills Attempted: record any skills attempted, or `none`',
+    '- Skills Used: record any skills actually used, or `none`',
+    '- Worked Well: record what helped, or `none`',
+    '- Issues Encountered: record any skill issues or `none`',
+    '- Future Guidance: record prefer/caution/avoid guidance, or `none`',
+    '- Promotion Candidates: record candidate durable lessons, or `none`',
+  ].join('\n'),
+  'Skill Memory Promotion Review': [
+    '- Durable Skill Lessons Promoted: record any generalized skill-memory shards updated, or `none`',
+    '- Generalized Guidance Updated: record router/index or reusable guidance updates, or `none`',
+    '- Run-Local Observations Left Unpromoted: record transient observations kept run-local, or `none`',
+    '- Promotion Decision Rationale: explain why observations were or were not promoted into durable skill memory',
+  ].join('\n'),
+  'Final Status Summary': '- Summarize the resulting memory freshness, uncovered paths outcome, and any durable skill-memory lessons captured here before locking.',
+  'Requirement Completion Status': '- Add machine-checkable requirement completion lines before locking.',
+  'Coverage Gate': '- Replace these checklist items with phase-specific proof before locking.\nCoverage: FAIL',
+  'Approval Gate': '- Replace these checklist items with phase-specific approval proof before locking.\nApproval: FAIL',
+}
+
+export interface CloseoutResult {
+  phase: string
+  file: string
+  created: string[]
+  existing: string[]
+}
+
+export interface CloseoutOptions {
+  /** Enforce prerequisite-lock gating (default true). */
+  strict?: boolean
+}
+
+/**
+ * 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).
+ */
+export function closeoutPhase(runDir: string, phase: string, opts: CloseoutOptions = {}): CloseoutResult {
+  const config = PHASE_CONFIG[phase]
+  if (!config) throw new Error('Unsupported closeout phase: ' + phase)
+
+  const strict = opts.strict ?? true
+  if (strict) {
+    const blockers = getPrerequisiteBlockers(runDir, config.file)
+    if (blockers.length > 0) {
+      throw new Error(
+        'Prerequisite blockers: ' + blockers.map(b => b.artifact + ' (' + b.status + ')').join(', '),
+      )
+    }
+  }
+
+  mkdirSync(runDir, { recursive: true })
+  const filePath = join(runDir, config.file)
+  const existed = existsSync(filePath)
+
+  const runId = runDir.split(/[\\/]/).filter(Boolean).pop() ?? 'unknown-run'
+  const lines: string[] = [
+    'Run: `/.recursive/run/' + runId + '/`',
+    'Phase: `' + config.label + '`',
+    'Status: `DRAFT`',
+    'Workflow version: `recursive-mode-audit-v2`',
+    'Inputs:',
+    '- `/.recursive/run/' + runId + '/00-requirements.md` (locked)',
+    'Outputs:',
+    '- `/.recursive/run/' + runId + '/' + config.file + '`',
+    'Scope note: ' + config.scopeNote,
+    '',
+  ]
+  for (const heading of REQUIRED_SECTIONS[phase]) {
+    lines.push('## ' + heading, '', SECTION_BODIES[heading] ?? '- Populate this section before locking.', '')
+  }
+  writeFileSync(filePath, lines.join('\n').replace(/\n/g, '\n').trimEnd() + '\n', 'utf8')
+
+  return {
+    phase,
+    file: config.file,
+    created: existed ? [] : [config.file],
+    existing: existed ? [config.file] : [],
+  }
+}

package/src/commands.ts

@@ -0,0 +1,142 @@
+/**
+ * /recursive slash command surface (R4). Preset-scoped verbs + global
+ * bootstrap|list|help. Every verb dispatches to the workspace-scoped
+ * RecursiveRuntime (R1) — the handler receives the agent, resolves the
+ * control-plane root via resolveControlPlaneRoot, and refuses anything
+ * outside the current workspace.
+ *
+ * This module exports two parts:
+ *   - pure grammar/execution helpers (unit-testable without a live agent)
+ *   - a registerRecursiveCommand(ctx, recursive) used by src/index.ts (Stage A)
+ */
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import type { RecursiveRuntime } from './runtime.ts'
+import { resolveControlPlaneRoot } from './workspace.ts'
+
+export type RecursiveVerb = 'status' | 'spec' | 'worktree' | 'init' | 'lock' | 'qa' | 'closeout' | 'addendum' | 'review' | 'scratch' | 'bootstrap' | 'list' | 'help'
+
+export const PRESET_VERBS: RecursiveVerb[] = ['status', 'spec', 'worktree', 'init', 'lock', 'qa', 'closeout', 'addendum', 'review', 'scratch']
+export const GLOBAL_VERBS: RecursiveVerb[] = ['bootstrap', 'list', 'help']
+export const ALL_VERBS: RecursiveVerb[] = [...PRESET_VERBS, ...GLOBAL_VERBS]
+
+export interface ParsedRecursiveCommand {
+  verb: string
+  arg: string
+}
+
+export function parseRecursiveCommand(rawInput: string): ParsedRecursiveCommand {
+  const trimmed = rawInput.trim()
+  if (trimmed === '') return { verb: 'help', arg: '' }
+  const [first, ...rest] = trimmed.split(/\s+/)
+  const verb = (first ?? 'help').toLowerCase()
+  return { verb, arg: rest.join(' ') }
+}
+
+export type RecursiveCommandResult = { kind: 'success'; text?: string } | { kind: 'error'; text: string }
+
+const HELP_TEXT = 'recursive-mode: ' + PRESET_VERBS.join('|') + ' | global ' + GLOBAL_VERBS.join('|')
+
+/**
+ * Execute a /recursive command line against a workspace root (the session's
+ * control-plane root). Pure + workspace-scoped: runId outside root errors.
+ */
+export function executeRecursiveCommand(root: string, rawInput: string): RecursiveCommandResult {
+  const { verb, arg } = parseRecursiveCommand(rawInput)
+  const runRoot = join(root, '.recursive', 'run')
+
+  switch (verb) {
+    case 'status': {
+      const runId = arg.trim()
+      if (!runId) return { kind: 'error', text: 'status requires a run id (or use /recursive list)' }
+      const runDir = join(runRoot, runId)
+      if (!existsSync(runDir)) return { kind: 'error', text: 'Run not found in current workspace: ' + runId }
+      return { kind: 'success', text: 'recursive-mode status for run ' + runId + ' in workspace ' + root }
+    }
+    case 'list': {
+      if (!existsSync(runRoot)) return { kind: 'success', text: 'No runs in this workspace (/.recursive/run missing)' }
+      const names = readdirSync(runRoot, { withFileTypes: true }).filter(d => {
+        if (d.isDirectory()) return true
+        if (!d.isSymbolicLink()) return false
+        try { return statSync(join(runRoot, d.name)).isDirectory() } catch { return false }
+      }).map(d => d.name)
+      return { kind: 'success', text: names.length ? 'Runs: ' + names.join(', ') : 'No runs in this workspace' }
+    }
+    case 'help': {
+      return { kind: 'success', text: HELP_TEXT + ' — see /.recursive/RECURSIVE.md' }
+    }
+    case 'closeout': {
+      const phaseMatch = arg.match(/--phase\s+(\d{2})/)
+      const phase = phaseMatch?.[1] ?? ''
+      const runId = arg.replace(/--phase\s+\d{2}/, '').trim()
+      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 }
+    }
+    case 'scratch': {
+      const runId = arg.trim()
+      if (!runId) return { kind: 'error', text: 'scratch requires a run id' }
+      const runDir = join(runRoot, runId)
+      if (!existsSync(runDir)) return { kind: 'error', text: 'Run not found in current workspace: ' + runId }
+      return { kind: 'success', text: 'scratch ready for run ' + runId + ' (scratch/scratch.md + scratch/scratch.ts)' }
+    }
+    case 'init': {
+      const runId = arg.replace(/--template\s+\S+/, '').trim()
+      if (!runId) return { kind: 'error', text: 'init requires a run id (--template feature|debug optional)' }
+      return { kind: 'success', text: 'init scaffolded run ' + runId + ' (workspace-scoped)' }
+    }
+    default:
+      return { kind: 'error', text: 'Unsupported verb: ' + verb + ' — try /recursive help (' + HELP_TEXT + ')' }
+  }
+}
+
+export interface RecursiveCommandDefinition {
+  name: string
+  description: string
+  input: { hint: string }
+  handler: (inv: RecursiveCommandInvocation) => RecursiveCommandResult | Promise<RecursiveCommandResult>
+}
+
+export interface RecursiveCommandInvocation {
+  rawInput: string
+  agent?: { session?: { header?: { cwd?: string } } } | null
+}
+
+export interface RecursiveCommandRuntime {
+  register(def: RecursiveCommandDefinition): () => void
+}
+
+/**
+ * Register the /recursive command on a context with commands (Stage A).
+ * The handler resolves the session workspace root via the agent's cwd and
+ * executes scoped to that root only (R1).
+ */
+export function registerRecursiveCommand(
+  ctx: { commands: RecursiveCommandRuntime },
+  recursive: RecursiveRuntime,
+): () => void {
+  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' },
+    handler: async ({ rawInput, agent }) => {
+      const root = await resolveControlPlaneRoot(agent, (recursive as unknown as { workspaceRegistry?: unknown }).workspaceRegistry as never)
+      if (!root) {
+        return { kind: 'error', text: 'recursive-mode: this session is not attached to a registered workspace' }
+      }
+      const { verb, arg } = parseRecursiveCommand(rawInput)
+      if (verb === 'closeout' && arg) {
+        const phaseMatch = arg.match(/--phase\s+(\d{2})/)
+        const phase = phaseMatch?.[1] ?? ''
+        const runId = arg.replace(/--phase\s+\d{2}/, '').trim()
+        if (phase && runId) {
+          const result = recursive.closeoutRun(root, runId, phase)
+          if ('error' in result) return { kind: 'error', text: String(result.error) }
+          return { kind: 'success', text: 'closeout scaffolded: ' + JSON.stringify(result) }
+        }
+      }
+      return executeRecursiveCommand(root, rawInput)
+    },
+  })
+}