@try-works/dsh-recursive-mode 0.1.0

package/src/status.ts

@@ -0,0 +1,194 @@
+import { createHash } from 'node:crypto'
+import { readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import type { ArtifactState, PhaseDef, PhaseState, RecursiveStatusResult } from './types.ts'
+
+export const RUN_ARTIFACT_SEQUENCE = [
+  '00-requirements.md',
+  '00-worktree.md',
+  '01-as-is.md',
+  '01.5-root-cause.md',
+  '02-to-be-plan.md',
+  '03-implementation-summary.md',
+  '03.5-code-review.md',
+  '04-test-summary.md',
+  '05-manual-qa.md',
+  '06-decisions-update.md',
+  '07-state-update.md',
+  '08-memory-impact.md',
+]
+
+export const PHASES: PhaseDef[] = [
+  { key: '00R', label: 'Phase 0 (Requirements)', file: '00-requirements.md', optional: false, phaseName: '0 (Requirements)' },
+  { key: '00W', label: 'Phase 0 (Worktree)', file: '00-worktree.md', optional: false, phaseName: '0 (Worktree)' },
+  { key: '01', label: 'Phase 1 (AS-IS)', file: '01-as-is.md', optional: false, phaseName: '1 (AS-IS)' },
+  { key: '01.5', label: 'Phase 1.5 (Root Cause)', file: '01.5-root-cause.md', optional: true, phaseName: '1.5 (Root Cause)' },
+  { key: '02', label: 'Phase 2 (TO-BE Plan)', file: '02-to-be-plan.md', optional: false, phaseName: '2 (TO-BE Plan)' },
+  { key: '03', label: 'Phase 3 (Implementation)', file: '03-implementation-summary.md', optional: false, phaseName: '3 (Implementation)' },
+  { key: '03.5', label: 'Phase 3.5 (Code Review)', file: '03.5-code-review.md', optional: true, phaseName: '3.5 (Code Review)' },
+  { key: '04', label: 'Phase 4 (Test Summary)', file: '04-test-summary.md', optional: false, phaseName: '4 (Test Summary)' },
+  { key: '05', label: 'Phase 5 (Manual QA)', file: '05-manual-qa.md', optional: false, phaseName: '5 (Manual QA)' },
+  { key: '06', label: 'Phase 6 (Decisions)', file: '06-decisions-update.md', optional: false, phaseName: '6 (Decisions Update)' },
+  { key: '07', label: 'Phase 7 (State)', file: '07-state-update.md', optional: false, phaseName: '7 (State Update)' },
+  { key: '08', label: 'Phase 8 (Memory)', file: '08-memory-impact.md', optional: false, phaseName: '8 (Memory Impact)' },
+]
+
+const LOCK_HASH_LINE_RE = /^[ \t]*LockHash:.*(?:\n|$)/gm
+const STRICT_WORKFLOW_PROFILES = new Set(['recursive-mode-audit-v1', 'recursive-mode-audit-v2'])
+const AUDITED_PHASE_FILES = new Set([
+  '01-as-is.md', '01.5-root-cause.md', '02-to-be-plan.md', '03-implementation-summary.md',
+  '03.5-code-review.md', '04-test-summary.md', '06-decisions-update.md', '07-state-update.md', '08-memory-impact.md',
+])
+const CURRENT_WORKFLOW_PROFILE = 'recursive-mode-audit-v2'
+const STRICT_WORKFLOW_PROFILE = 'recursive-mode-audit-v1'
+const COMPAT_WORKFLOW_PROFILE = 'memory-phase8'
+const LATE_PHASE_FILES = ['06-decisions-update.md', '07-state-update.md', '08-memory-impact.md']
+const LATE_PHASE_KEYS = new Set(['06', '07', '08'])
+
+export function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+export function trimMdValue(value: string): string {
+  let trimmed = value.trim()
+  for (const quote of ['`', '"', "'"]) {
+    if (trimmed.startsWith(quote) && trimmed.endsWith(quote) && trimmed.length >= 2) {
+      const inner = trimmed.slice(1, -1)
+      if (!inner.includes(quote)) return inner.trim()
+    }
+  }
+  return trimmed
+}
+
+export function getMdFieldValue(content: string, fieldName: string): string | null {
+  const pattern = new RegExp(`^[ \\t]*(?:[-*][ \\t]+)?${escapeRegExp(fieldName)}:[ \\t]*(.+?)\\s*$`, 'm')
+  const match = pattern.exec(content)
+  if (!match) return null
+  return trimMdValue(match[1])
+}
+
+export function getGateStatus(content: string, gateName: string): string {
+  const pattern = new RegExp(`^[ \\t]*${escapeRegExp(gateName)}:\\s*(PASS|FAIL)\\s*$`, 'm')
+  const match = pattern.exec(content)
+  return match ? match[1].toUpperCase() : 'MISSING'
+}
+
+export function getTodoStats(content: string): { hasTodo: boolean; total: number; checked: number; unchecked: number } {
+  const lines = content.split(/\r?\n/)
+  let inTodo = false
+  let hasTodo = false
+  let checked = 0
+  let unchecked = 0
+  let total = 0
+  for (const line of lines) {
+    if (!inTodo) {
+      if (/^\s*##\s+TODO\s*$/.test(line)) { inTodo = true; hasTodo = true }
+      continue
+    }
+    if (/^\s*##\s+/.test(line) || /^\s*#\s+/.test(line)) break
+    const item = /^\s*[-*]\s+\[([ xX])\]\s+/.exec(line)
+    if (item) {
+      total += 1
+      if (item[1].toLowerCase() === 'x') checked += 1
+      else unchecked += 1
+    }
+  }
+  return { hasTodo, total, checked, unchecked }
+}
+
+export function lockHashFromContent(content: string): string {
+  const normalized = content.replace(/\r\n/g, '\n').replace(/\r/g, '\n')
+  const stripped = normalized.replace(LOCK_HASH_LINE_RE, '')
+  return createHash('sha256').update(stripped, 'utf8').digest('hex')
+}
+
+export function getWorkflowProfile(runDir: string): string {
+  const requirementsPath = join(runDir, '00-requirements.md')
+  try {
+    const content = readFileSync(requirementsPath, 'utf8')
+    const workflowVersion = getMdFieldValue(content, 'Workflow version')
+    if (workflowVersion === CURRENT_WORKFLOW_PROFILE) return CURRENT_WORKFLOW_PROFILE
+    if (workflowVersion === STRICT_WORKFLOW_PROFILE) return STRICT_WORKFLOW_PROFILE
+    if (workflowVersion === COMPAT_WORKFLOW_PROFILE) return COMPAT_WORKFLOW_PROFILE
+  } catch { /* fall through */ }
+  if (LATE_PHASE_FILES.some(file => { try { statSync(join(runDir, file)); return true } catch { return false } })) return COMPAT_WORKFLOW_PROFILE
+  return 'legacy'
+}
+
+export { getLatestRunDirectory, discoverRuns, resolveRunDir } from './run.ts'
+export type { RunDiscoveryResult } from './run.ts'
+
+export function getArtifactState(artifactPath: string, workflowProfile: string): ArtifactState {
+  let content: string | null = null
+  try { content = readFileSync(artifactPath, 'utf8') } catch { /* missing */ }
+  if (content === null) {
+    return { exists: false, status: 'PENDING', lockValid: false, lockProblems: ['File missing'], blockers: ['File missing'], lockedAt: null, storedHash: null, actualHash: null, coverage: 'MISSING', approval: 'MISSING', audit: 'MISSING', todoHasSection: false, todoUnchecked: 0 }
+  }
+  const status = getMdFieldValue(content, 'Status') ?? 'UNKNOWN'
+  const todo = getTodoStats(content)
+  const coverage = getGateStatus(content, 'Coverage')
+  const approval = getGateStatus(content, 'Approval')
+  const audit = getGateStatus(content, 'Audit')
+  const tddCompliance = getGateStatus(content, 'TDD Compliance')
+  const lockedAt = getMdFieldValue(content, 'LockedAt')
+  const storedHash = getMdFieldValue(content, 'LockHash')
+  let actualHash: string | null = null
+  const lockProblems: string[] = []
+  const blockers: string[] = []
+  let lockValid = false
+  const fileName = artifactPath.split(/[\\/]/).pop() ?? ''
+
+  if (status !== 'LOCKED') {
+    lockProblems.push(`Status is '${status}' (expected LOCKED for lock-valid)`)
+  } else {
+    if (!lockedAt) lockProblems.push('Missing LockedAt')
+    if (!storedHash) lockProblems.push('Missing LockHash')
+    if (storedHash) {
+      actualHash = lockHashFromContent(content)
+      if (storedHash.toLowerCase() !== actualHash.toLowerCase()) lockProblems.push('LockHash mismatch')
+    }
+    if (coverage !== 'PASS') lockProblems.push(`Coverage gate is ${coverage}`)
+    if (approval !== 'PASS') lockProblems.push(`Approval gate is ${approval}`)
+    if (STRICT_WORKFLOW_PROFILES.has(workflowProfile) && AUDITED_PHASE_FILES.has(fileName) && audit !== 'PASS') lockProblems.push(`Audit gate is ${audit}`)
+    if (fileName === '03-implementation-summary.md' && tddCompliance !== 'PASS') lockProblems.push(`TDD Compliance gate is ${tddCompliance}`)
+    if (!todo.hasTodo) lockProblems.push('Missing ## TODO section')
+    else if (todo.unchecked > 0) lockProblems.push(`Unchecked TODO items: ${todo.unchecked}`)
+    if (lockProblems.length === 0) lockValid = true
+  }
+
+  if (!todo.hasTodo) blockers.push('Missing ## TODO section')
+  else if (todo.unchecked > 0) blockers.push(`Unchecked TODO items: ${todo.unchecked}`)
+  if (coverage !== 'PASS') blockers.push(`Coverage gate is ${coverage}`)
+  if (approval !== 'PASS') blockers.push(`Approval gate is ${approval}`)
+  if (fileName === '03-implementation-summary.md' && tddCompliance !== 'PASS') blockers.push(`TDD Compliance gate is ${tddCompliance}`)
+
+  const dedupedBlockers: string[] = []
+  for (const blocker of blockers) if (!dedupedBlockers.includes(blocker)) dedupedBlockers.push(blocker)
+
+  return { exists: true, status, lockValid, lockProblems, blockers: dedupedBlockers, lockedAt, storedHash, actualHash, coverage, approval, audit, todoHasSection: todo.hasTodo, todoUnchecked: todo.unchecked }
+}
+
+export function foldRun(runDir: string, runId: string): RecursiveStatusResult {
+  const workflowProfile = getWorkflowProfile(runDir)
+  const states = new Map<string, ArtifactState>()
+  for (const phase of PHASES) {
+    const state = getArtifactState(join(runDir, phase.file), workflowProfile)
+    if (phase.optional && !state.exists) state.status = 'SKIPPED'
+    else if (workflowProfile === 'legacy' && LATE_PHASE_KEYS.has(phase.key) && !state.exists) state.status = 'SKIPPED'
+    states.set(phase.key, state)
+  }
+  let currentPhase: RecursiveStatusResult['currentPhase'] = null
+  for (const phase of PHASES) {
+    const state = states.get(phase.key)!
+    if (state.status === 'SKIPPED') continue
+    if (!state.exists || !state.lockValid) {
+      currentPhase = { key: phase.key, label: phase.label, phaseName: phase.phaseName, status: state.status }
+      break
+    }
+  }
+  const phases: PhaseState[] = PHASES.map(phase => {
+    const state = states.get(phase.key)!
+    return { key: phase.key, label: phase.label, file: phase.file, optional: phase.optional, exists: state.exists, status: state.status, lockValid: state.lockValid, lockProblems: state.lockProblems, blockers: state.blockers }
+  })
+  return { runId, currentPhase, phases, workflowProfile }
+}

package/src/types.ts

@@ -0,0 +1,112 @@
+export interface PhaseDef {
+  key: string
+  label: string
+  file: string
+  optional: boolean
+  phaseName: string
+}
+
+export interface ArtifactState {
+  exists: boolean
+  status: string
+  lockValid: boolean
+  lockProblems: string[]
+  blockers: string[]
+  lockedAt: string | null
+  storedHash: string | null
+  actualHash: string | null
+  coverage: string
+  approval: string
+  audit: string
+  todoHasSection: boolean
+  todoUnchecked: number
+}
+
+export interface PhaseState {
+  key: string
+  label: string
+  file: string
+  optional: boolean
+  exists: boolean
+  status: string
+  lockValid: boolean
+  lockProblems: string[]
+  blockers: string[]
+}
+
+export interface RecursiveStatusResult {
+  runId: string
+  currentPhase: { key: string; label: string; phaseName: string; status: string } | null
+  phases: PhaseState[]
+  workflowProfile: string
+}
+
+/* ================= Phase D wire vocabulary (run 06 R3, PROPOSAL 11.4-11.7) === */
+
+/** Run-level durable state (mirrors lifecycle.ts RUN_STATES; single pure-type home for the wire). */
+export type RecursiveRunState = 'new' | 'active' | 'paused' | 'blocked' | 'complete'
+
+/** One locked-phase fact carried by a recursive/phase-locked event. */
+export interface RecursivePhaseLock {
+  lockedAt: string
+  lockHash: string
+}
+
+/** One gate failure fact carried by a recursive/gate-blocked event. */
+export interface RecursiveGateBlock {
+  failures: string[]
+  kind: string
+}
+
+/** One tamper fact carried by a recursive/tamper event. */
+export interface RecursiveTamper {
+  path: string
+  reason: string
+}
+
+/** One subagent activity fact (start or end). */
+export interface RecursiveSubagent {
+  childId: string
+  role: string
+  provider: string
+  status?: 'running' | 'done' | 'failed'
+}
+
+/** One phase row in a run card's folded phase chain. */
+export interface RecursivePhaseRow {
+  phase: string
+  status: string
+  lockedAt?: string
+  lockHash?: string
+}
+
+/**
+ * The per-run wire card the recursive projection folds: the board, inspector,
+ * node, and strip all render from this whole value — never from the file tree.
+ */
+export interface RecursiveRunCard {
+  runId: string
+  worktreeRoot: string
+  repo?: string
+  template?: string
+  /** Folded phase chain: last-wins per phase key. */
+  phases: Record<string, RecursivePhaseRow>
+  /** Folded run-level state: last recursive/run-state wins (default 'active'). */
+  state: RecursiveRunState
+  stateReason?: string
+  /** Latest gate block (last-wins); absent when no block is in force. */
+  gateBlocked?: RecursiveGateBlock
+  /** Tamper facts (accumulated, latest wins per path). */
+  tampers: Record<string, RecursiveTamper>
+  /** Subagent activity (latest status wins per childId). */
+  subagents: Record<string, RecursiveSubagent>
+  /** Set on recursive/run-merged; the run re-keys to this root. */
+  mergedToRepoRoot?: string
+}
+
+/**
+ * The recursive projection whole value: runs grouped by worktree root first,
+ * then by runId. The board renders one lane per run; the client enumerates by
+ * worktree root so it never crosses the workspace boundary.
+ */
+export type RecursiveProjection = Record<string, Record<string, RecursiveRunCard>>

package/src/workspace.ts

@@ -0,0 +1,67 @@
+/**
+ * Workspace-scoped control-plane root resolution (R1, binding invariant).
+ *
+ * The plugin NEVER scans `workspaceRegistry.list()` to find "the" workspace and
+ * NEVER reads another open workspace's `.recursive/` tree. The ONLY root-resolution
+ * path is: session canonical cwd (`agent.session.header.cwd`) -> 
+ * `workspaceRegistry.resolveByPath(cwd)` -> the owning workspace's canonical `path`,
+ * which IS the control-plane root.
+ */
+
+export interface WorkspaceLike {
+  readonly path: string
+  readonly id: string
+}
+
+export interface WorkspaceRegistryLike {
+  /** Resolve by canonical directory path without creating or mutating. */
+  resolveByPath(path: string): Promise<WorkspaceLike | undefined> | WorkspaceLike | undefined
+  /** MUST NOT be used by this plugin (workspace-scoping invariant). */
+  list?(): unknown
+}
+
+export interface WorkspaceResolver {
+  (cwd: string): Promise<string | null>
+}
+
+/**
+ * Build a resolver bound to a workspace registry. Returns the canonical workspace
+ * path for the given cwd, or `null` when the cwd is not a registered workspace
+ * (no repo -> defer, never fail hard).
+ */
+export function makeWorkspaceResolver(registry: WorkspaceRegistryLike): WorkspaceResolver {
+  return async (cwd: string): Promise<string | null> => {
+    if (!cwd) return null
+    const workspace = await registry.resolveByPath(cwd)
+    return workspace?.path ?? null
+  }
+}
+
+/**
+ * Resolve the control-plane root for an agent-like object with a session header
+ * carrying a canonical `cwd`. Degrades to `null` when the registry or cwd is
+ * unavailable (callers defer, never fail hard).
+ */
+export async function resolveControlPlaneRoot(
+  agent: { session?: { header?: { cwd?: string } } } | null | undefined,
+  registry?: WorkspaceRegistryLike | null,
+  cwdFallback?: string,
+): Promise<string | null> {
+  const cwd = agent?.session?.header?.cwd ?? cwdFallback ?? null
+  if (!cwd) return null
+  // B4: the session header cwd IS the workspace/control-plane root when the
+  // registry is absent (headless/code-mode assemblies do not compose the
+  // workspace service). Registry, when present, canonicalizes; otherwise the
+  // session cwd is authoritative — never null just because the registry is
+  // missing, or scratch/closeout (and every other per-call read) would be
+  // permanently dead in headless hosts.
+  if (!registry) return cwd
+  return makeWorkspaceResolver(registry)(cwd)
+}
+
+/**
+ * Extract the canonical session cwd (for callers that pass it explicitly).
+ */
+export function sessionCwd(agent: { session?: { header?: { cwd?: string } } } | null | undefined): string | null {
+  return agent?.session?.header?.cwd ?? null
+}