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

package/src/live-route.ts

@@ -0,0 +1,163 @@
+/**
+ * Live recursive board/strip route (SP2 R1): host HTTP + SSE serving the
+ * filesystem fold, keyed per-WORKSPACE. The board/strip read this instead of
+ * useProjection('recursive'); cold resume and every GET are a fresh fs read.
+ *
+ * Keying (creator steer): the client passes its session cwd verbatim; the HOST
+ * resolves the recursive control-plane root server-side (cwd == workspace root,
+ * cwd == subdir, cwd == repo root). Multiple sessions in one workspace collapse
+ * to one fold; a workspace switch shows the new root.
+ *
+ * R9 read-only: GET state + GET events only. No POST/action route; the client
+ * never mutates the host.
+ *
+ * Registration is mountOnce-global because apply() runs PER-SESSION while
+ * WebServer.register throws on a duplicate (kind, path). The first mount wins;
+ * later mounts no-op (the state is per-workspace, so per-session registration
+ * would be both wrong and a crash).
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { RecursiveProjection } from './types.ts'
+
+/** API prefix the board/strip fetch. */
+export const RECURSIVE_API_PREFIX = '/.recursive/api'
+
+/** The host seam the route builder needs: root resolution + the fs fold + a revision. */
+export interface RecursiveRouteHost {
+  /**
+   * Resolve the recursive control-plane root. sessionId is PRIMARY (the host
+   * prefers the attached session header cwd — never trusts a client path); cwd
+   * is a fallback hint only while the session is hydrating / for headless callers.
+   */
+  resolveRoot(sessionId: string | undefined, cwd: string): Promise<string | null>
+  /** Fresh filesystem fold for one workspace root (per-workspace state). */
+  snapshot(root: string): Promise<RecursiveProjection> | RecursiveProjection
+  /** Monotone revision; bump whenever the fs fold changes (SSE frame + state). */
+  revision(root: string): number
+}
+
+/** The state payload the board/strip read. */
+export interface RecursiveStatePayload {
+  root: string | null
+  projection: RecursiveProjection
+  revision: number
+}
+
+const HEARTBEAT_MS = 15_000
+
+function json(res: ServerResponse, status: number, body: unknown): void {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
+  res.end(JSON.stringify(body))
+}
+
+/** Same-origin browser tripwire (NOT an authority check; the loopback socket is the real boundary). */
+function browserMarker(req: IncomingMessage): boolean {
+  const headers = req.headers ?? {}
+  const site = headers['sec-fetch-site']
+  return site === 'same-origin' || typeof headers.origin === 'string'
+}
+
+/** Read a query param (URLSearchParams tolerates a missing/duplicate value). */
+function queryOf(req: IncomingMessage, name: string): string {
+  const url = req.url ?? ''
+  const q = url.indexOf('?')
+  if (q < 0) return ''
+  return new URLSearchParams(url.slice(q + 1)).get(name) ?? ''
+}
+
+/**
+ * Build the two read-only routes. Returns [state, events] in registration order.
+ * @param host - the resolved-root + fs-fold seam (the RecursiveRuntime adapter).
+ */
+export function makeRecursiveRoutes(host: RecursiveRouteHost): readonly { kind: 'exact'; path: string; handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void> }[] {
+  const state: { kind: 'exact'; path: string; handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void> } = {
+    kind: 'exact',
+    path: RECURSIVE_API_PREFIX + '/state',
+    handler: async (req, res) => {
+      if (req.method !== 'GET') { res.writeHead(405); res.end(); return }
+      if (!browserMarker(req)) { res.writeHead(403); res.end(); return }
+      const sessionId = queryOf(req, 'sessionId') || undefined
+      const cwd = queryOf(req, 'cwd')
+      const root = sessionId === undefined && cwd === '' ? null : await host.resolveRoot(sessionId, cwd)
+      if (root === null) {
+        json(res, 200, { root: null, projection: {}, revision: 0 } as RecursiveStatePayload)
+        return
+      }
+      json(res, 200, { root, projection: await host.snapshot(root), revision: host.revision(root) } as RecursiveStatePayload)
+    },
+  }
+  const events: { kind: 'exact'; path: string; handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void> } = {
+    kind: 'exact',
+    path: RECURSIVE_API_PREFIX + '/events',
+    handler: async (req, res) => {
+      if (req.method !== 'GET') { res.writeHead(405); res.end(); return }
+      if (!browserMarker(req)) { res.writeHead(403); res.end(); return }
+      const sessionId = queryOf(req, 'sessionId') || undefined
+      const cwd = queryOf(req, 'cwd')
+      const root = sessionId === undefined && cwd === '' ? null : await host.resolveRoot(sessionId, cwd)
+      if (root === null) { res.writeHead(200, { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-cache', connection: 'keep-alive' }); res.write('data: {"root":null,"projection":{},"revision":0}\n\n'); res.end(); return }
+      res.writeHead(200, { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-cache', connection: 'keep-alive' })
+      const push = (): void => {
+        const payload = { root, projection: host.snapshot(root), revision: host.revision(root) }
+        res.write('data: ' + JSON.stringify(payload) + '\n\n')
+      }
+      const heartbeat = setInterval(() => { res.write(': ping\n\n') }, HEARTBEAT_MS)
+      const close = (): void => { clearInterval(heartbeat) }
+      req.once('close', close)
+      res.once('close', close)
+      await push()
+    },
+  }
+  return [state, events]
+}
+
+/**
+ * Register the routes at most ONCE per process. WebServer.register throws on a
+ * duplicate (kind, path), and apply() runs per-session, so later mounts MUST
+ * no-op. The registry rides a global symbol so two module instances of the same
+ * package share one verdict; the unmarker rides ctx.effect (cordis runs the
+ * effect callback immediately and treats its return as the disposer).
+ */
+const MOUNTED = Symbol.for('dsh-recursive-mode.mounted')
+
+interface MountRegistry {
+  [MOUNTED]?: Set<string>
+}
+
+function mountedSet(): Set<string> {
+  const registry = globalThis as MountRegistry
+  return (registry[MOUNTED] ??= new Set())
+}
+
+export interface WebServerLike {
+  register(route: { kind: string; path: string; handler: unknown }): () => void
+}
+
+/**
+ * mountOnce wrapper for the route registration. Returns the disposer of the
+ * registration (or a no-op for a later mount).
+ * @param packageName - npm package identity (every install source shares it).
+ * @param makeRoutes - builds the routes (called once, on the first mount).
+ * @param webServer - the host webserver service (or a structural fake).
+ */
+export function mountRecursiveRoutesOnce(
+  packageName: string,
+  makeRoutes: () => readonly { kind: string; path: string; handler: unknown }[],
+  webServer: WebServerLike,
+): () => void {
+  const mounted = mountedSet()
+  if (mounted.has(packageName)) return () => {}
+  mounted.add(packageName)
+  const disposers: Array<() => void> = []
+  try {
+    for (const route of makeRoutes()) disposers.push(webServer.register(route))
+  } catch (error) {
+    mounted.delete(packageName)
+    for (const dispose of disposers) dispose()
+    throw error
+  }
+  return () => {
+    for (const dispose of disposers) dispose()
+    mounted.delete(packageName)
+  }
+}

package/src/phase-rules.ts

@@ -0,0 +1,262 @@
+/**
+ * Phase rules (R5): canonical parity port of lint-recursive-run.py's
+ * get_artifact_required_sections + workflow/audit constants. Single source of
+ * truth for per-phase required section headings and audit extras; consumed by
+ * initRun templates, renderRecursivePolicy, and the pre-step lint-rules
+ * injection. Values are byte-identical to the canonical linter (recursive-
+ * mode-audit-v2).
+ */
+
+export const CURRENT_WORKFLOW_PROFILE = 'recursive-mode-audit-v2'
+export const STRICT_WORKFLOW_PROFILE = 'recursive-mode-audit-v1'
+export const COMPAT_WORKFLOW_PROFILE = 'memory-phase8'
+export const STRICT_WORKFLOW_PROFILES = new Set([CURRENT_WORKFLOW_PROFILE, STRICT_WORKFLOW_PROFILE])
+
+export const LATE_PHASE_ARTIFACTS = ['06-decisions-update.md', '07-state-update.md', '08-memory-impact.md']
+
+export 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',
+])
+
+export const PRIOR_RECURSIVE_EVIDENCE_FILES = new Set([
+  '01-as-is.md',
+  '02-to-be-plan.md',
+  '04-test-summary.md',
+  '07-state-update.md',
+  '08-memory-impact.md',
+])
+
+export const DIFF_AUDITED_FILES = new Set([
+  '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',
+])
+
+export const TRACEABILITY_REQUIRED_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',
+  '05-manual-qa.md',
+  '06-decisions-update.md',
+  '07-state-update.md',
+  '08-memory-impact.md',
+])
+
+export const AUDIT_REQUIRED_HEADINGS = [
+  'Audit Context',
+  'Effective Inputs Re-read',
+  'Earlier Phase Reconciliation',
+  'Subagent Contribution Verification',
+  'Worktree Diff Audit',
+  'Gaps Found',
+  'Repair Work Performed',
+  'Requirement Completion Status',
+  'Audit Verdict',
+]
+
+export const DIFF_BASIS_FIELDS = [
+  'Baseline type',
+  'Baseline reference',
+  'Comparison reference',
+  'Normalized baseline',
+  'Normalized comparison',
+  'Normalized diff command',
+]
+
+const SECTION_MAP: Record<string, string[]> = {
+  '00-worktree.md': [
+    'TODO',
+    'Directory Selection',
+    'Safety Verification',
+    'Worktree Creation',
+    'Main Branch Protection',
+    'Project Setup',
+    'Test Baseline Verification',
+    'Worktree Context',
+    'Diff Basis For Later Audits',
+    'Traceability',
+    'Coverage Gate',
+    'Approval Gate',
+  ],
+  '00-requirements.md': [
+    'TODO',
+    'Requirements',
+    'Out of Scope',
+    'Constraints',
+    'Coverage Gate',
+    'Approval Gate',
+  ],
+  '01-as-is.md': [
+    'TODO',
+    'Reproduction Steps (Novice-Runnable)',
+    'Current Behavior by Requirement',
+    'Source Requirement Inventory',
+    'Relevant Code Pointers',
+    'Known Unknowns',
+    'Evidence',
+    'Traceability',
+    'Coverage Gate',
+    'Approval Gate',
+  ],
+  '01.5-root-cause.md': [
+    'TODO',
+    'Error Analysis',
+    'Reproduction Verification',
+    'Recent Changes Analysis',
+    'Evidence Gathering (Multi-Layer if applicable)',
+    'Data Flow Trace',
+    'Pattern Analysis',
+    'Hypothesis Testing',
+    'Root Cause Summary',
+    'Traceability',
+    'Coverage Gate',
+    'Approval Gate',
+  ],
+  '02-to-be-plan.md': [
+    'TODO',
+    'Planned Changes by File',
+    'Requirement Mapping',
+    'Implementation Steps',
+    'Testing Strategy',
+    'Playwright Plan (if applicable)',
+    'Manual QA Scenarios',
+    'Idempotence and Recovery',
+    'Implementation Sub-phases',
+    'Plan Drift Check',
+    'Traceability',
+    'Coverage Gate',
+    'Approval Gate',
+  ],
+  '03-implementation-summary.md': [
+    'TODO',
+    'Changes Applied',
+    'TDD Compliance Log',
+    'Plan Deviations',
+    'Implementation Evidence',
+    'Traceability',
+    'Coverage Gate',
+    'Approval Gate',
+  ],
+  '03.5-code-review.md': [
+    'TODO',
+    'Review Scope',
+    'Plan Alignment Assessment',
+    'Code Quality Assessment',
+    'Issues Found',
+    'Verdict',
+    'Review Metadata',
+    'Traceability',
+    'Coverage Gate',
+    'Approval Gate',
+  ],
+  '04-test-summary.md': [
+    'TODO',
+    'Pre-Test Implementation Audit',
+    'Environment',
+    'Execution Mode',
+    'Commands Executed (Exact)',
+    'Results Summary',
+    'Evidence and Artifacts',
+    'Failures and Diagnostics (if any)',
+    'Flake/Rerun Notes',
+    'Traceability',
+    'Coverage Gate',
+    'Approval Gate',
+  ],
+  '05-manual-qa.md': [
+    'TODO',
+    'QA Execution Record',
+    'QA Scenarios and Results',
+    'Evidence and Artifacts',
+    'User Sign-Off',
+    'Traceability',
+    'Coverage Gate',
+    'Approval Gate',
+  ],
+  '06-decisions-update.md': [
+    'TODO',
+    'Decisions Changes Applied',
+    'Rationale',
+    'Resulting Decision Entry',
+    'Traceability',
+    'Coverage Gate',
+    'Approval Gate',
+  ],
+  '07-state-update.md': [
+    'TODO',
+    'State Changes Applied',
+    'Rationale',
+    'Resulting State Summary',
+    'Traceability',
+    'Coverage Gate',
+    'Approval Gate',
+  ],
+  '08-memory-impact.md': [
+    'TODO',
+    'Diff Basis',
+    'Changed Paths Review',
+    'Affected Memory Docs',
+    'Run-Local Skill Usage Capture',
+    'Skill Memory Promotion Review',
+    'Uncovered Paths',
+    'Router and Parent Refresh',
+    'Final Status Summary',
+    'Traceability',
+    'Coverage Gate',
+    'Approval Gate',
+  ],
+}
+
+/**
+ * get_artifact_required_sections(file_name, workflow_profile): canonical-parity
+ * required section headings for a phase artifact. Defaults to TODO + Coverage
+ * Gate + Approval Gate for unknown files. Audited phases in strict profiles get
+ * the audit headings appended (plus Prior Recursive Evidence Reviewed for the
+ * prior-evidence file set).
+ */
+export function getArtifactRequiredSections(fileName: string, workflowProfile: string = CURRENT_WORKFLOW_PROFILE): string[] {
+  const headings = [...(SECTION_MAP[fileName] ?? ['TODO', 'Coverage Gate', 'Approval Gate'])]
+  if (STRICT_WORKFLOW_PROFILES.has(workflowProfile) && AUDITED_PHASE_FILES.has(fileName)) {
+    headings.push(...AUDIT_REQUIRED_HEADINGS)
+    if (PRIOR_RECURSIVE_EVIDENCE_FILES.has(fileName)) {
+      headings.push('Prior Recursive Evidence Reviewed')
+    }
+  }
+  return headings
+}
+
+/**
+ * Compact lint-rules message for the pre-step injection (R5): this phase's
+ * required sections + phase-specific gate notes, derived from the canonical
+ * artifact-template sections. Kept short enough to prepend as a system-style
+ * reminder without bloating the step context.
+ */
+export function phaseLintRulesMessage(fileName: string, workflowProfile: string = CURRENT_WORKFLOW_PROFILE): string {
+  const sections = getArtifactRequiredSections(fileName, workflowProfile)
+  const lines = [
+    '<system-reminder>',
+    'Recursive-mode phase lint rules for THIS phase (' + fileName + '):',
+    'Required sections: ' + sections.join(' | '),
+    'Gates: Coverage: FAIL until all checkboxes pass; Approval: FAIL until user sign-off; lock only via recursive_lock (monotonic).',
+    'Audited phases: end with Audit: PASS before setting Coverage/Approval PASS; record Audit Context and Audit Verdict.',
+    'TDD (phase 3): declare TDD Mode: strict|pragmatic; strict requires RED + GREEN evidence paths.',
+    'QA (phase 5): declare QA Execution Mode: human|agent-operated|hybrid; human/hybrid need user sign-off.',
+    '</system-reminder>',
+  ]
+  return lines.join('\n')
+}

package/src/policy.ts

@@ -2,8 +2,9 @@
  * recursive:policy prompt-section renderer (Phase C R5, PROPOSAL 8.4 Layer 3).
  * Renders the CURRENT phase's contract from folded state + enforcement config:
  * what must exist before advancing, which tools are denied/asked this phase,
- * the strict/pragmatic TDD mode, the QA mode, and the lock chain - the same
- * rules the machine gates enforce (no prompt/gate contradiction).
+ * the strict/pragmatic TDD mode, the QA mode, the lock chain, and (R5) the
+ * current phase's required sections + gate checklist — the same rules the
+ * machine gates enforce (no prompt/gate contradiction).
  */
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
@@ -12,11 +13,12 @@ import { foldRun } from './status.ts'
 import type { RecursivePhaseState } from './lifecycle.ts'
 import type { EnforcementConfig } from './enforcement.ts'
 import { DEFAULT_ENFORCEMENT } from './enforcement.ts'
+import { getArtifactRequiredSections, AUDITED_PHASE_FILES, CURRENT_WORKFLOW_PROFILE } from './phase-rules.ts'
 
 export interface PolicyContext {
   worktreeRoot: string
   runId: string
-  folded: RecursivePhaseState | null
+  folded?: RecursivePhaseState | null
   config?: EnforcementConfig
 }
 
@@ -32,10 +34,12 @@ export function renderRecursivePolicy(context: PolicyContext | null): string {
   // Derive the current phase from files (never trust an unchecked fold).
   let currentPhase = folded?.phase ?? ''
   let nextRequired = ''
+  let currentFile = ''
   const status = existsSync(runDir) ? foldRun(runDir, context.runId) : null
   if (status?.currentPhase) {
     currentPhase = status.currentPhase.label + ' (' + status.currentPhase.status + ')'
     nextRequired = status.currentPhase.phaseName + ' (' + status.currentPhase.key + ')'
+    currentFile = status.currentPhase.phaseName
   }
 
   const strictness = (gate: EnforcementConfig[keyof EnforcementConfig]) => gate
@@ -51,6 +55,26 @@ export function renderRecursivePolicy(context: PolicyContext | null): string {
     '- The control-plane root is resolved STRICTLY from this session workspace (never scan other workspaces).',
     '- Scratch is disposable, git-ignored, and never citable as an Input.',
     '- The workflow spec lives at /.recursive/RECURSIVE.md; bootstrap it when missing.',
-  ]
+  ];
+
+  // R5: surface the current phase's required sections + gate checklist.
+  if (currentFile) {
+    const sections = getArtifactRequiredSections(currentFile, CURRENT_WORKFLOW_PROFILE)
+    lines.push('');
+    lines.push('## This phase (' + currentFile + ') required sections (canonical lint):');
+    lines.push('- ' + sections.join(' | '));
+    lines.push('## This phase gate checklist:');
+    lines.push('- Coverage: FAIL until every checklist item is done; Approval: FAIL until sign-off; lock only via recursive_lock (monotonic).');
+    if (AUDITED_PHASE_FILES.has(currentFile)) {
+      lines.push('- Audited phase: end with Audit: PASS before setting Coverage/Approval PASS; record Audit Context + Audit Verdict.');
+    }
+    if (currentFile === '03-implementation-summary.md') {
+      lines.push('- TDD Mode: strict|pragmatic; strict requires RED + GREEN evidence paths.');
+    }
+    if (currentFile === '05-manual-qa.md') {
+      lines.push('- QA Execution Mode: human|agent-operated|hybrid; human/hybrid require user sign-off.');
+    }
+  }
+
   return lines.join('\n')
-}
+}