@try-works/dsh-recursive-mode 0.1.0

package/src/bootstrap.ts

@@ -0,0 +1,118 @@
+/**
+ * Idempotent scaffold installer + Stage B workflow init (R6). TS port of
+ * install-recursive-mode.py's core: bootstrap the /.recursive/ control plane
+ * when missing (no-op when present), enumerate runs as directory names only,
+ * and drive the agent/session-start Stage B (new vs resume) workspace-scoped
+ * to the session's control-plane root (R1).
+ */
+import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export interface BootstrapResult {
+  root: string
+  bootstrapped: boolean
+  created: string[]
+  existing: string[]
+}
+
+export interface StageBResult {
+  root: string
+  source: 'new' | 'resume'
+  bootstrapped: boolean
+  runs: string[]
+  activeRunId?: string
+}
+
+const CONTROL_PLANE_FILES: Record<string, string> = {
+  'RECURSIVE.md': '# recursive-mode\\n\\nrecursive-mode workflow. The canonical spec is maintained by the installed skill; this scaffold is the repo-local control plane.\\n',
+  'STATE.md': '# STATE\\n\\nRepository state ledger.\\n',
+  'DECISIONS.md': '# DECISIONS\\n\\nDecision ledger.\\n',
+}
+
+const MEMORY_FILES: Record<string, string> = {
+  'memory/MEMORY.md': '# MEMORY\\n\\nDurable memory router.\\n',
+  'memory/skills/SKILLS.md': '# SKILLS\\n\\nSkill memory router.\\n',
+}
+
+/**
+ * Idempotent scaffold install: creates the /.recursive/ control plane when
+ * missing. Never overwrites existing files; preserves unrelated content.
+ */
+export function bootstrapScaffold(root: string): BootstrapResult {
+  const recursiveRoot = join(root, '.recursive')
+  const created: string[] = []
+  const existing: string[] = []
+
+  const writeIfMissing = (rel: string, content: string) => {
+    const path = join(recursiveRoot, rel)
+    if (existsSync(path)) {
+      existing.push(rel)
+      return
+    }
+    mkdirSync(join(path, '..'), { recursive: true })
+    writeFileSync(path, content, 'utf8')
+    created.push(rel)
+  }
+
+  for (const [rel, content] of Object.entries(CONTROL_PLANE_FILES)) writeIfMissing(rel, content)
+  for (const [rel, content] of Object.entries(MEMORY_FILES)) writeIfMissing(rel, content)
+  // run/ + config/ + memory/ dirs (empty dirs for the scaffold)
+  for (const dir of ['run', 'config', 'memory/training']) {
+    const path = join(recursiveRoot, dir)
+    if (!existsSync(path)) {
+      mkdirSync(path, { recursive: true })
+      created.push(dir + '/')
+    } else {
+      existing.push(dir + '/')
+    }
+  }
+
+  return {
+    root,
+    bootstrapped: created.length > 0,
+    created,
+    existing,
+  }
+}
+
+/**
+ * Enumerate runs as directory names only (bounded O(#dirs)). Never reads
+ * run docs; never returns file paths.
+ */
+export function enumerateRuns(root: string): string[] {
+  const runRoot = join(root, '.recursive', 'run')
+  if (!existsSync(runRoot)) return []
+  return 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)
+    .sort()
+}
+
+export interface StageBInput {
+  root: string
+  source: 'new' | 'resume'
+  activeRunId?: string
+}
+
+/**
+ * Stage B workflow init at agent/session-start. New: bootstrap if missing +
+ * enumerate runs. Resume: never re-bootstrap; enumerate + note the active run
+ * (the caller re-reads only that run's current phase doc). Always scoped to
+ * the given control-plane root.
+ */
+export function stageBWorkflowInit(input: StageBInput): StageBResult {
+  const { root, source, activeRunId } = input
+  const bootstrap = bootstrapScaffold(root)
+  const runs = enumerateRuns(root)
+  return {
+    root,
+    source,
+    bootstrapped: source === 'new' ? bootstrap.bootstrapped : false,
+    runs,
+    activeRunId,
+  }
+}

package/src/client/board.tsx

@@ -0,0 +1,61 @@
+/**
+ * Board overlay (Phase D R5, §11.8): the kanban view over the 'recursive'
+ * projection. Pure read-only renderer — no filesystem, no run-file scraping.
+ * Cards are grouped by worktree root (the projection's outer key) and mapped
+ * to their current-phase lane via derive.columnForRun.
+ */
+import { createElement } from 'react'
+import type { RecursiveProjection, RecursiveRunCard } from '../types.ts'
+import type { RecursiveProjectionReader } from './contract.ts'
+import { cardFacts, columnForRun, KANBAN_LANES } from './derive.ts'
+
+
+/** Flatten the worktree-grouped projection into a stable run list. */
+export function listRuns(projection: RecursiveProjection | undefined): RecursiveRunCard[] {
+  if (projection === undefined) return []
+  const runs: RecursiveRunCard[] = []
+  for (const worktreeRoot of Object.keys(projection)) {
+    for (const runId of Object.keys(projection[worktreeRoot])) {
+      runs.push(projection[worktreeRoot][runId])
+    }
+  }
+  return runs
+}
+
+export interface BoardProps {
+  useProjection: RecursiveProjectionReader
+}
+
+export function Board({ useProjection }: BoardProps) {
+  const projection = useProjection('recursive') as RecursiveProjection | undefined
+  const runs = listRuns(projection)
+  if (runs.length === 0) {
+    return createElement('div', { className: 'rec-board', 'data-empty': true },
+      createElement('p', { className: 'rec-board-empty' }, 'No recursive runs in this workspace yet.'),
+    )
+  }
+  return createElement('div', { className: 'rec-board' },
+    KANBAN_LANES.map((lane) => {
+      const laneRuns = runs.filter((r) => columnForRun(r) === lane.id)
+      return createElement('section', { key: lane.id, className: 'rec-lane' },
+        createElement('h2', { className: 'rec-lane-title' }, lane.label),
+        laneRuns.map((run) => {
+          const facts = cardFacts(run)
+          return createElement('article', { key: run.worktreeRoot + '\u0000' + run.runId, className: 'rec-card' },
+            createElement('div', { className: 'rec-card-head' },
+              createElement('strong', {}, run.runId),
+              facts.tampered && createElement('span', { className: 'rec-badge rec-badge-tamper', title: 'tampered' }, '!'),
+            ),
+            createElement('div', { className: 'rec-card-progress' },
+              createElement('div', { className: 'rec-card-progress-fill', style: { width: Math.round(facts.progress * 100) + '%' } }),
+            ),
+            createElement('div', { className: 'rec-card-meta' },
+              createElement('span', {}, facts.currentPhase ?? 'no phases'),
+              createElement('span', { className: 'rec-badge' }, facts.state),
+            ),
+          )
+        }),
+      )
+    }),
+  )
+}

package/src/client/contract.ts

@@ -0,0 +1,58 @@
+/**
+ * Structural client seams (self-contained). The real @deepseek-ai/dsh-client-*
+ * packages are HOST-INJECTED at bundle time via dsh.client.inject (never
+ * installed in this package's dependency tree — they depend on workspace:^
+ * peers that resolve only inside the DSH workspace). We declare the minimal
+ * shapes we consume so the pure client modules type-check and bundle in
+ * isolation; the DSH loader links them to the real runtime identities at
+ * compose time.
+ *
+ * One deliberate narrowing: the client only READS (R9 read-only). It never
+ * calls back into the host; every host fact arrives through the projection.
+ */
+
+/** SessionEvent-like carrier (the projection/node fold reads events by shape). */
+export interface ClientSessionEvent {
+  type: string
+  seq?: number
+  time?: number
+  data?: Record<string, unknown>
+}
+
+/** A session header (cwd is the control-plane root). */
+export interface ClientSessionHeader {
+  cwd?: string
+}
+
+/** Minimal appendable session (log-only write seam). */
+export interface ClientSession {
+  header: ClientSessionHeader
+  append(type: string, data: unknown): unknown
+}
+
+/** The client root context the bundle receives from the module loader. */
+export interface ClientContext {
+  slots: ClientSlots
+  get(name: string): unknown
+}
+
+/** A registered slot's options (list/keyed entries carry id/order/label). */
+export interface SlotOptions {
+  name: string
+  id?: string
+  order?: number
+  label?: string
+  children?: unknown
+  store?: unknown
+  locale?: unknown
+  registrant?: unknown
+}
+
+/** The slot registry surface the client injects into. */
+export interface ClientSlots {
+  inject(seat: string, factory: (ctx: unknown) => () => void): () => void
+  register(options: SlotOptions, component: unknown): () => void
+}
+
+/** useProjection('recursive') reader — undefined = capability absent. */
+export type RecursiveProjectionReader = (key: 'recursive') => unknown

package/src/client/derive.ts

@@ -0,0 +1,241 @@
+/**
+ * Pure derivation over the projected RecursiveRunCard (Phase D R5/R6/R7):
+ * kanban lane mapping, card facts, conversation-node keying, and inspector
+ * phase-row expansion. EVERYTHING here is a pure function over the wire card
+ * — no React, no fs, no session window, no /.recursive/run/ scraping (the
+ * read-only-client + projection-over-files invariant, 00-requirements R9).
+ *
+ * The card arrives from the 'recursive' session projection (whole value,
+ * host-computed); this module only derives presentation from it.
+ */
+import type { RecursiveRunCard, RecursivePhaseRow, RecursiveRunState } from '../types.ts'
+
+/** The ordered kanban lanes (§11.4): one lane per phase group. */
+export interface RecursiveLane {
+  /** Stable lane id. */
+  id: string
+  /** Human label. */
+  label: string
+  /** Phase-group keys folded into this lane. */
+  groups: readonly string[]
+}
+
+export const KANBAN_LANES: readonly RecursiveLane[] = [
+  { id: '0', label: 'Worktree & Requirements', groups: ['00'] },
+  { id: '1/1.5', label: 'Analysis', groups: ['01', '01.5'] },
+  { id: '2', label: 'TO-BE Plan', groups: ['02'] },
+  { id: '3/3.5', label: 'Implementation + Code Review', groups: ['03', '03.5'] },
+  { id: '4', label: 'Tests', groups: ['04'] },
+  { id: '5', label: 'Manual QA', groups: ['05'] },
+  { id: '6-8', label: 'Closeout', groups: ['06', '07', '08'] },
+]
+
+const GROUP_ORDER: readonly string[] = ['00', '01', '01.5', '02', '03', '03.5', '04', '05', '06', '07', '08']
+
+/** Mandatory phase groups: a run is only 'locked'-valid when every one of these is present and LOCKED (01.5 is optional). */
+const MANDATORY_GROUPS: readonly string[] = ['00', '01', '02', '03', '03.5', '04', '05', '06', '07', '08']
+
+/** Map a group id to its ordinal for stable ordering. */
+const GROUP_INDEX = new Map(GROUP_ORDER.map((g, i) => [g, i]))
+
+/** Group id for a phase filename (e.g. '03.5-code-review.md' -> '03.5'); null for non-phase names. */
+export function phaseGroupOf(phase: string): string | null {
+  const m = /^(\d{2}(?:\.\d)?)(?:-|$)/.exec(phase)
+  if (m === null) return null
+  const g = m[1]
+  return GROUP_INDEX.has(g) ? g : null
+}
+
+/** Kanban lane id for a phase filename. */
+export function laneOf(phase: string): string | null {
+  const g = phaseGroupOf(phase)
+  if (g === null) return null
+  for (const lane of KANBAN_LANES) {
+    if ((lane.groups as readonly string[]).includes(g)) return lane.id
+  }
+  return null
+}
+
+/**
+ * The run's current-phase lane: the highest-ordered phase group present in the
+ * card wins (a run is "at" its furthest phase). No phases -> lane 0.
+ */
+export function columnForRun(card: RecursiveRunCard): string {
+  let best: string | null = null
+  let bestIndex = -1
+  for (const key of Object.keys(card.phases)) {
+    const g = phaseGroupOf(key)
+    if (g === null) continue
+    const idx = GROUP_INDEX.get(g) ?? -1
+    if (idx > bestIndex) {
+      bestIndex = idx
+      best = g
+    }
+  }
+  if (best === null) return '0'
+  return laneOf(best + '-x') ?? '0'
+}
+
+/** Subagent chip (one per childId, latest status). */
+export interface RecursiveSubagentChip {
+  childId: string
+  role: string
+  provider: string
+  status: 'running' | 'done' | 'failed'
+}
+
+/** Presentation facts derived from one card (§11.4). */
+export interface RecursiveCardFacts {
+  runId: string
+  worktreeRoot: string
+  repo?: string
+  template?: string
+  state: RecursiveRunState
+  stateReason?: string
+  /** Phases locked so far. */
+  lockedCount: number
+  /** Distinct phase groups present (progress denominator). */
+  totalPhases: number
+  /** lockedCount / totalPhases (0 when totalPhases is 0). */
+  progress: number
+  /** Any tamper fact present. */
+  tampered: boolean
+  /** Latest gate block present. */
+  gateBlocked: boolean
+  gateKind?: string
+  /** Run was merged to a repo root. */
+  merged: boolean
+  mergedToRepoRoot?: string
+  /** Lock validity: tampered | locked | in-progress. */
+  lockValidity: 'tampered' | 'locked' | 'in-progress'
+  /** Latest current-phase label (or null). */
+  currentPhase: string | null
+  /** Subagent chips, latest status per child. */
+  subagents: RecursiveSubagentChip[]
+}
+
+/** Derive §11.4 presentation facts from one card (no fs, no session). */
+export function cardFacts(card: RecursiveRunCard): RecursiveCardFacts {
+  const groups = new Set<string>()
+  for (const key of Object.keys(card.phases)) {
+    const g = phaseGroupOf(key)
+    if (g !== null) groups.add(g)
+  }
+  const lockedGroups = new Set<string>()
+  for (const key of Object.keys(card.phases)) {
+    const g = phaseGroupOf(key)
+    if (g !== null && card.phases[key].status === 'LOCKED') lockedGroups.add(g)
+  }
+  const lockedCount = lockedGroups.size
+  const totalPhases = groups.size
+
+  const subagents: RecursiveSubagentChip[] = Object.values(card.subagents).map(s => ({
+    childId: s.childId,
+    role: s.role,
+    provider: s.provider,
+    status: s.status ?? 'done',
+  }))
+
+  let currentPhase: string | null = null
+  let currentIdx = -1
+  for (const key of Object.keys(card.phases)) {
+    const g = phaseGroupOf(key)
+    if (g === null) continue
+    const idx = GROUP_INDEX.get(g) ?? -1
+    if (idx > currentIdx) {
+      currentIdx = idx
+      currentPhase = key
+    }
+  }
+
+  const tampered = Object.keys(card.tampers).length > 0
+  // Lock validity: tampered beats everything; else every MANDATORY phase present
+  // and LOCKED -> locked; else still in-progress (01.5 stays optional).
+  const allMandatoryLocked = MANDATORY_GROUPS.every((g) => {
+    const row = Object.entries(card.phases).find(([key]) => phaseGroupOf(key) === g)
+    return row !== undefined && row[1].status === 'LOCKED'
+  })
+  const lockValidity: RecursiveCardFacts['lockValidity'] = tampered
+    ? 'tampered'
+    : allMandatoryLocked
+      ? 'locked'
+      : 'in-progress'
+
+  return {
+    runId: card.runId,
+    worktreeRoot: card.worktreeRoot,
+    repo: card.repo,
+    template: card.template,
+    state: card.state,
+    stateReason: card.stateReason,
+    lockedCount,
+    totalPhases,
+    progress: totalPhases === 0 ? 0 : lockedCount / totalPhases,
+    tampered,
+    gateBlocked: card.gateBlocked !== undefined,
+    gateKind: card.gateBlocked?.kind,
+    merged: card.mergedToRepoRoot !== undefined,
+    mergedToRepoRoot: card.mergedToRepoRoot,
+    lockValidity,
+    currentPhase,
+    subagents,
+  }
+}
+
+/**
+ * Stable conversation-node business id: runId + worktreeRoot (§11.6). The
+ * worktree root is part of the id so two runs with the same runId in
+ * different worktrees never collide — never "latest unfinished".
+ */
+export function nodeKeyOf(runId: string, worktreeRoot: string): string {
+  return worktreeRoot + '\u0000' + runId
+}
+
+/** One expanded inspector phase row (§11.5). */
+export interface RecursivePhaseInspectorRow {
+  /** Normalized phase key (group only, e.g. '03.5'). */
+  phase: string
+  /** Full filename if present, else null (a mandatory-empty row). */
+  fileName: string | null
+  status: string
+  lockedAt?: string
+  lockHash?: string
+  /** Whether the row is present in the card (vs a mandatory-empty slot). */
+  present: boolean
+}
+
+/**
+ * Expand a card's phase chain into full inspector rows: the always-shown
+ * '03.5' slot (§11.10 mandatory deviation) plus 01.5 when present, and
+ * 06/07/08 as three distinct rows (never one merged lane).
+ */
+export function expandPhaseRows(card: RecursiveRunCard): RecursivePhaseInspectorRow[] {
+  const byGroup = new Map<string, RecursivePhaseRow>()
+  for (const [fileName, row] of Object.entries(card.phases)) {
+    const g = phaseGroupOf(fileName)
+    if (g !== null) byGroup.set(g, row)
+  }
+
+  const rows: RecursivePhaseInspectorRow[] = []
+  for (const g of GROUP_ORDER) {
+    // 01.5 is optional: only emit when present.
+    if (g === '01.5' && !byGroup.has(g)) continue
+    // 03.5 is always shown (§11.10).
+    const row = byGroup.get(g)
+    if (row === undefined) {
+      if (g === '03.5') {
+        rows.push({ phase: g, fileName: null, status: '—', present: false })
+      }
+      continue
+    }
+    rows.push({
+      phase: g,
+      fileName: row.phase,
+      status: row.status,
+      lockedAt: row.lockedAt,
+      lockHash: row.lockHash,
+      present: true,
+    })
+  }
+  return rows
+}

package/src/client/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Client entry (Phase D R4): the browser half of dsh-recursive-mode. Receives
+ * the client root context from the DSH loader and registers the board,
+ * inspector, conversation node, status strip, and settings page (§11.8).
+ * READ-ONLY (R9): every host fact arrives through the recursive projection;
+ * this module never touches the filesystem.
+ *
+ * The apply(ctx) surface mirrors the shipped dsh-client-ui-* packages; the
+ * dsh.client.inject list in package.json names the host packages the loader
+ * must provide (they are injected at compose time, never installed here).
+ */
+import type { ClientContext } from './contract.ts'
+import { registerSlots } from './slots.ts'
+
+export { recursiveNodeDefinition, RECURSIVE_NODE_KIND, matchRecursiveNode, foldRecursiveNode } from './node.ts'
+export type { RecursiveNodeData, RecursiveNodeState } from './node.ts'
+export { Board, listRuns } from './board.tsx'
+export { Inspector } from './inspector.tsx'
+export { StatusStrip } from './strip.tsx'
+export { RecursiveSettings } from './settings.tsx'
+export type { RecursiveProjectionReader } from './contract.ts'
+
+/** Browser-half plugin entry (R4). */
+export function apply(ctx: ClientContext): void {
+  // The conversation node is registered through the node-inject seam; the
+  // other surfaces through the slot registry.
+  registerSlots(ctx)
+}

package/src/client/inspector.tsx

@@ -0,0 +1,49 @@
+/**
+ * Drill-down inspector (Phase D R6, §11.5): the details-seat swap rendering
+ * one run's phase chain (with the always-shown 3.5 row + full 6/7/8 rows),
+ * lock badges, and tamper/gate facts — all from the projection, never disk.
+ */
+import { createElement } from 'react'
+import type { RecursiveProjection } from '../types.ts'
+import { cardFacts, expandPhaseRows } from './derive.ts'
+import type { RecursiveProjectionReader } from './contract.ts'
+
+export interface InspectorProps {
+  runId: string
+  worktreeRoot: string
+  useProjection: RecursiveProjectionReader
+  onBackToToolDetails: () => void
+}
+
+export function Inspector({ runId, worktreeRoot, useProjection, onBackToToolDetails }: InspectorProps) {
+  const projection = useProjection('recursive') as RecursiveProjection | undefined
+  const card = projection?.[worktreeRoot]?.[runId]
+  if (card === undefined) {
+    return createElement('div', { className: 'rec-inspector' },
+      createElement('p', {}, 'Run not found: ' + runId),
+    )
+  }
+  const facts = cardFacts(card)
+  const rows = expandPhaseRows(card)
+  return createElement('div', { className: 'rec-inspector' },
+    createElement('div', { className: 'rec-inspector-head' },
+      createElement('button', { onClick: onBackToToolDetails, className: 'rec-back' }, '← back to tool details'),
+      createElement('h2', {}, runId),
+      createElement('span', { className: 'rec-badge' }, facts.state),
+      facts.tampered && createElement('span', { className: 'rec-badge rec-badge-tamper' }, 'tampered'),
+    ),
+    createElement('section', { className: 'rec-inspector-section' },
+      createElement('h3', {}, 'Phases'),
+      rows.map((row) => createElement('div', { key: row.phase, className: 'rec-phase-row' },
+        createElement('span', { className: 'rec-phase-id' }, row.phase),
+        createElement('span', { className: 'rec-phase-name' }, row.fileName ?? '—'),
+        createElement('span', { className: 'rec-badge' }, row.status),
+        row.lockHash !== undefined && createElement('code', { className: 'rec-lockhash' }, '#' + row.lockHash.slice(0, 8)),
+      )),
+    ),
+    facts.gateBlocked && createElement('section', { className: 'rec-inspector-section' },
+      createElement('h3', {}, 'Gate'),
+      createElement('p', {}, 'Blocked (' + (facts.gateKind ?? '') + ')'),
+    ),
+  )
+}