@try-works/dsh-recursive-mode 0.3.0 → 0.4.0

package/src/types.ts

@@ -22,6 +22,27 @@ export interface ArtifactState {
   todoUnchecked: number
 }
 
+/**
+ * T21 — ONE named position per phase, derived from the fields every consumer
+ * currently recombines for itself (`status`, `lockValid`, `lockProblems`,
+ * `blockers`). Two consumers recombining those independently is exactly how two
+ * consumers come to disagree about a phase's state; a single derived value gives
+ * them nothing to disagree about.
+ *
+ * Closed vocabulary, total and disjoint (see `phasePosition`):
+ *   `absent`       the artifact does not exist
+ *   `skipped`      an optional (or legacy-profile late) phase that is not present
+ *   `draft`        present and unlocked, with no blockers
+ *   `blocked`      present and unlocked, with at least one blocker
+ *   `invalid-lock` LOCKED but failing a condition other than its hash
+ *   `locked`       LOCKED and lock-valid
+ *   `tampered`     LOCKED with a hash mismatch — the more serious fact, so it wins
+ *                  over any other lock problem
+ */
+export type PhasePosition = 'absent' | 'skipped' | 'draft' | 'blocked' | 'invalid-lock' | 'locked' | 'tampered'
+
+export const PHASE_POSITIONS: readonly PhasePosition[] = ['absent', 'skipped', 'draft', 'blocked', 'locked', 'invalid-lock', 'tampered']
+
 export interface PhaseState {
   key: string
   label: string
@@ -32,6 +53,8 @@ export interface PhaseState {
   lockValid: boolean
   lockProblems: string[]
   blockers: string[]
+  /** T21: the single derived state of this phase. */
+  position: PhasePosition
 }
 
 export interface RecursiveStatusResult {
@@ -64,6 +87,22 @@ export interface RecursiveTamper {
   reason: string
 }
 
+/**
+ * T18 — one piece of unresolved in-flight work, DERIVED from the run directory
+ * (there is no ledger). `unanswered-delegation` is a `handoff.md` with no reply
+ * yet; `empty-reply` is a reply file that exists but carries nothing, which is
+ * not a submission.
+ */
+export interface PendingWorkItem {
+  kind: 'unanswered-delegation' | 'empty-reply'
+  /** The delegation directory name, so a refusal can name what is blocking. */
+  delegationId: string
+  /** Repo-relative path of the file that would settle it, or of the handoff. */
+  path: string
+  /** One sentence for a human, naming the delegation and what is missing. */
+  detail: string
+}
+
 /** One subagent activity fact (start or end). */
 export interface RecursiveSubagent {
   childId: string
@@ -78,6 +117,12 @@ export interface RecursivePhaseRow {
   status: string
   lockedAt?: string
   lockHash?: string
+  /**
+   * T21: the same single derived position `foldRun` publishes, carried onto the
+   * wire so the board and the tooling cannot disagree about a phase's state.
+   * Optional so a row produced before this field existed stays readable.
+   */
+  position?: PhasePosition
 }
 
 /**
@@ -100,6 +145,12 @@ export interface RecursiveRunCard {
   tampers: Record<string, RecursiveTamper>
   /** Subagent activity (latest status wins per childId). */
   subagents: Record<string, RecursiveSubagent>
+  /**
+   * T18: unresolved in-flight work, DERIVED from the run directory on every fold
+   * (never stored). Optional so an older producer's card stays readable; the
+   * folder always sets it. A non-empty array explains why a lock will be refused.
+   */
+  pendingWork?: PendingWorkItem[]
   /** Set on recursive/run-merged; the run re-keys to this root. */
   mergedToRepoRoot?: string
 }

package/src/workflow-audit.ts

@@ -0,0 +1,288 @@
+/**
+ * T2 — fan the audit out through the native workflow engine's contract.
+ *
+ * WHY. A phase-3.5 audit over several reviewers is a natural fan-out, and the plugin reimplements
+ * that loop by hand. The engine already owns the shape: `phase(title)` to group work, `agent(prompt,
+ * opts)` to run one child, and `parallel(thunks)` to fan out and await all of them. Adopting it means
+ * one orchestration model instead of two that drift.
+ *
+ * ⚠ THE HOOK SHAPE IS A STRUCTURAL SEAM, not an import, because the engine runs against a live host
+ * context (the item calls it integration-grade). Modelling the three hooks this adapter uses keeps
+ * the CONTRACT testable without a host — and the contract is where the risk lives, not the plumbing.
+ *
+ * ⚠⚠ THE PROPERTY THIS ITEM'S OWN RESCOPE NAMED, and the reason the mapping is pure: **no
+ * cross-item null-dropping.** The engine's `agent()` and `parallel()` resolve `null` for a child
+ * that FAILED, and the obvious implementation — `results.filter(Boolean)` — silently turns a
+ * failed reviewer into a fan-out that simply looks smaller. An audit that dropped its dissenting
+ * reviewer would report a clean pass, which is the worst outcome this plugin can produce. So the
+ * result carries an entry for EVERY planned item, with `ok: false` where a child produced nothing,
+ * and `describeAuditFanOut` says how many failed.
+ */
+
+/** One reviewer's assignment inside the fan-out. */
+export interface AuditFanOutItem {
+  /** Stable label: what the board and the engine's progress show. */
+  label: string
+  /** The reviewer role, for traceability back to the router. */
+  role: string
+  prompt: string
+}
+
+/** One phase of the fan-out: a titled group of items run in parallel. */
+export interface AuditFanOutPhase {
+  title: string
+  items: AuditFanOutItem[]
+}
+
+export interface AuditFanOutPlan {
+  runId: string
+  phases: AuditFanOutPhase[]
+}
+
+/** One item's outcome, PRESENT whether or not the child produced anything. */
+export interface AuditFanOutEntry {
+  label: string
+  role: string
+  /** False when the child failed or returned nothing — never inferred from a missing entry. */
+  ok: boolean
+  value?: unknown
+  /** Why it failed, when it did. */
+  reason?: string
+}
+
+export interface AuditFanOutResult {
+  entries: AuditFanOutEntry[]
+  /** How many planned items produced nothing. Stated, so a partial audit cannot read as complete. */
+  failed: number
+}
+
+/**
+ * The three hooks this adapter uses.
+ *
+ * `agent` and `parallel` resolve `null` rather than rejecting when a child fails — that is the
+ * engine's documented behaviour and the reason this module handles null explicitly instead of
+ * treating a resolved promise as success.
+ */
+export interface WorkflowHooksLike {
+  phase(title: string): void
+  agent(prompt: string, options?: { label?: string; phase?: string }): Promise<unknown>
+  parallel(thunks: ReadonlyArray<() => Promise<unknown>>): Promise<unknown[]>
+  log?(message: string): void
+}
+
+/** The reviewers a plan is built from — the plugin's own audit inputs, not an engine concept. */
+export interface AuditReviewerSpec {
+  role: string
+  /** Extra instructions for this reviewer; the plan adds the contract around it. */
+  focus?: string
+}
+
+export interface AuditPlanInput {
+  runId: string
+  artifact: string
+  phase: string
+  reviewers: readonly AuditReviewerSpec[]
+  /** Questions every reviewer must answer, so the plan carries them rather than each caller. */
+  auditQuestions?: readonly string[]
+}
+
+/**
+ * Build the fan-out plan. PURE: same inputs, same plan — which is what makes the orchestration
+ * testable without a host and comparable between runs.
+ *
+ * One phase per ROLE, with one item per reviewer of that role, so the engine's progress reads as
+ * "audit phase X, reviewer Y" rather than a flat list of anonymous children.
+ */
+export function buildAuditFanOutPlan(input: AuditPlanInput): AuditFanOutPlan {
+  const phases: AuditFanOutPhase[] = []
+  for (const reviewer of input.reviewers) {
+    const role = reviewer.role.trim()
+    if (role === '') continue
+    const title = input.phase + ' audit: ' + role
+    let phase = phases.find((candidate) => candidate.title === title)
+    if (phase === undefined) {
+      phase = { title, items: [] }
+      phases.push(phase)
+    }
+    phase.items.push({
+      label: input.runId + '/' + role + '/' + (phase.items.length + 1),
+      role,
+      prompt: [
+        'Review ' + input.artifact + ' as the ' + role + '.',
+        ...(reviewer.focus === undefined || reviewer.focus.trim() === '' ? [] : [reviewer.focus.trim()]),
+        ...(input.auditQuestions === undefined || input.auditQuestions.length === 0
+          ? []
+          : ['Answer explicitly: ' + input.auditQuestions.join(' | ')]),
+      ].join('\n'),
+    })
+  }
+  return { runId: input.runId, phases }
+}
+
+/**
+ * Run a plan through the engine's hooks.
+ *
+ * ⚠ EVERY planned item yields an entry, whether or not its child produced a value. A missing entry
+ * and a failed child are different facts, and conflating them is how an audit reports a pass it did
+ * not earn: this returns `ok: false` with a reason instead of dropping the row.
+ */
+export async function orchestrateAudit(hooks: WorkflowHooksLike, plan: AuditFanOutPlan): Promise<AuditFanOutResult> {
+  const entries: AuditFanOutEntry[] = []
+  for (const phase of plan.phases) {
+    hooks.phase(phase.title)
+    const values = await hooks.parallel(phase.items.map((item) => () =>
+      hooks.agent(item.prompt, { label: item.label, phase: phase.title })))
+    for (const [index, item] of phase.items.entries()) {
+      const value = values[index]
+      if (value === null || value === undefined) {
+        entries.push({ label: item.label, role: item.role, ok: false, reason: 'the reviewer child produced no result' })
+        continue
+      }
+      entries.push({ label: item.label, role: item.role, ok: true, value })
+    }
+  }
+  const failed = entries.filter((entry) => !entry.ok).length
+  return { entries, failed }
+}
+
+/**
+ * A board-facing summary that STATES the failures.
+ *
+ * The count is explicit because an audit with three of five reviewers failed is not a smaller
+ * audit — it is an incomplete one, and a summary that only reported the successes would be the
+ * silent-drop defect wearing a friendlier face.
+ */
+export function describeAuditFanOut(result: AuditFanOutResult): string {
+  const total = result.entries.length
+  if (total === 0) return 'audit fan-out planned no reviewers'
+  if (result.failed === 0) return 'audit fan-out: ' + total + ' reviewer(s), all produced a result'
+  const names = result.entries.filter((entry) => !entry.ok).map((entry) => entry.label)
+  return 'audit fan-out: ' + total + ' reviewer(s), ' + result.failed + ' FAILED ('
+    + names.join(', ') + ') — the audit is INCOMPLETE, not smaller'
+}
+
+/**
+ * T2 — the canonical script the ENGINE runs, and the request that starts it.
+ *
+ * ⚠⚠ MEASURED, AND IT CHANGES WHERE THE HOOKS LIVE. The engine is a service —
+ * `WorkflowEngine.start(request): WorkflowRun`, *"Parse and execute a workflow script"*, with the
+ * request carrying **the script, its `args`, the parent agent and an optional cancel signal** — and
+ * its `workflow/*` lifecycle events are documented as **"observe-only … never expose run control"**.
+ * So `phase()` / `agent()` / `parallel()` are hooks available to a SCRIPT, not functions the plugin
+ * may call directly: the plugin's job is to hand the engine a script plus the plan, and to read the
+ * frames afterwards. {@link orchestrateAudit} is therefore the shape a script (or a test double)
+ * drives, and this is the shape the plugin submits.
+ *
+ * ⚠ THE PLUGIN DOES NOT SHIP A GENERATED SCRIPT. A script built by string concatenation from a plan
+ * would put reviewer prompts into a program's source, where a stray quote becomes a syntax error in
+ * the orchestration layer — the worst place for one. The script is a CONSTANT that reads the plan
+ * from `args`, which also keeps the orchestration auditable: one script, reviewed once.
+ */
+export const AUDIT_FANOUT_SCRIPT = [
+  'const plan = args.plan',
+  'for (const phase of plan.phases) {',
+  '  phase(phase.title)',
+  '  await parallel(phase.items.map((item) => () => agent(item.prompt, { label: item.label, phase: phase.title })))',
+  '}',
+  'return args.plan.runId',
+].join('\n')
+
+/**
+ * What the engine needs to start an audit fan-out. Mirrors `WorkflowStartRequest` structurally.
+ *
+ * ⚠ `meta` IS REQUIRED BY THE ENGINE, and this type originally omitted it — a defect found by READING the
+ * engine's declarations rather than by any test (T2's acceptance ran against a scripted engine that
+ * validated nothing). `packages/workflow/workflow/lib/types/runtime-types.d.ts` states the field is
+ * non-optional and its README lists *"a malformed meta block"* among the rejections, so a live engine
+ * would have refused this fan-out outright. `subagentProvider` and `maxTotalAgents` are carried too, since
+ * they are the engine's own child controls and a fan-out that ignores them cannot honour a host's limits.
+ */
+export interface AuditWorkflowRequest {
+  script: string
+  /** The engine-validated identity block: name, description, and one phase per reviewer role. */
+  meta: {
+    name: string
+    description: string
+    whenToUse?: string
+    phases?: Array<{ title: string; detail?: string; provider?: string; model?: string }>
+  }
+  args: { plan: AuditFanOutPlan }
+  parent: unknown
+  signal?: unknown
+  /** Optional engine-wide child-provider override for this run. */
+  subagentProvider?: string
+  /** Optional per-run total-child ceiling, so a host's cap is respected rather than exceeded. */
+  maxTotalAgents?: number
+}
+
+/**
+ * Build the engine request for a plan.
+ *
+ * `parent` is the exact live Agent, as the engine requires for child authority; it passes through
+ * untouched rather than reshaped, because the engine authenticates by object identity.
+ *
+ * ⚠ THE META IS DERIVED FROM THE PLAN, not hand-written: the engine's `phases` are `{title, detail?,
+ * provider?, model?}` and the plan already holds exactly that per reviewer role, so deriving it means the
+ * two can never disagree about what the run will do.
+ */
+export function auditWorkflowRequest(
+  plan: AuditFanOutPlan,
+  options: {
+    parent: unknown
+    signal?: unknown
+    /** Overrides the derived identity block; the phases still come from the plan unless given. */
+    meta?: { name?: string; description?: string; whenToUse?: string }
+    subagentProvider?: string
+    maxTotalAgents?: number
+  },
+): AuditWorkflowRequest {
+  const reviewers = plan.phases.reduce((total, phase) => total + phase.items.length, 0)
+  return {
+    script: AUDIT_FANOUT_SCRIPT,
+    meta: {
+      name: options.meta?.name ?? 'recursive-audit-fan-out',
+      description: options.meta?.description
+        ?? 'Fan an audit out to ' + reviewers + ' reviewer(s) across ' + plan.phases.length + ' role phase(s) and aggregate ONE verdict.',
+      ...(options.meta?.whenToUse === undefined ? {} : { whenToUse: options.meta.whenToUse }),
+      phases: plan.phases.map((phase) => ({ title: phase.title, detail: phase.items.map((item) => item.label).join(', ') })),
+    },
+    args: { plan },
+    parent: options.parent,
+    ...(options.signal === undefined ? {} : { signal: options.signal }),
+    ...(options.subagentProvider === undefined ? {} : { subagentProvider: options.subagentProvider }),
+    ...(options.maxTotalAgents === undefined ? {} : { maxTotalAgents: options.maxTotalAgents }),
+  }
+}
+
+/**
+ * T2 — the engine, as a structural seam.
+ *
+ * ⚠ START AND AWAIT ONLY. The engine's `workflow/*` lifecycle events are documented as
+ * **"observe-only … never expose run control"**, so a caller starts a run and awaits the script's
+ * `result`; it must not try to steer the run through the event stream.
+ */
+export interface WorkflowEngineLike {
+  start(request: AuditWorkflowRequest): { result: Promise<unknown> }
+}
+
+/**
+ * Start an audit fan-out and await the script's result.
+ *
+ * ⚠ NO ENGINE IS A STATED OUTCOME, not a silent empty audit: a fan-out that could not be
+ * orchestrated must never read as a fan-out that found nothing wrong. The caller gets
+ * `orchestrated: false` and a reason, in the same spirit as every other optional seam here.
+ */
+export async function startAuditFanOut(
+  workflow: WorkflowEngineLike | null | undefined,
+  plan: AuditFanOutPlan,
+  options: { parent: unknown; signal?: unknown },
+): Promise<{ orchestrated: boolean; reason?: string; result?: unknown }> {
+  if (workflow === null || workflow === undefined || typeof workflow.start !== 'function') {
+    return {
+      orchestrated: false,
+      reason: 'no workflow engine is mounted, so the ' + plan.phases.length + '-phase audit fan-out was NOT orchestrated',
+    }
+  }
+  const run = workflow.start(auditWorkflowRequest(plan, options))
+  return { orchestrated: true, result: await run.result }
+}

package/scripts/install-preset.cmd

@@ -1,7 +0,0 @@
-@echo off
-rem install-preset.cmd — thin launcher for scripts\install-preset.js
-rem Materializes the `recursive` agent preset into %DSH_HOME%\.agent-presets\recursive\
-rem with an absolute file-URL row into the profile-installed package.
-setlocal
-node "%~dp0install-preset.js" %*
-exit /b %ERRORLEVEL%

package/scripts/install-preset.js

@@ -1,101 +0,0 @@
-#!/usr/bin/env node
-/**
- * install-preset.js — materialize the `recursive` agent preset into the user's
- * DSH home so `agentPreset.list` returns `recursive` and selecting it mounts the
- * full per-session recursive-mode surface.
- *
- * R2 resolution (02-to-be-plan.addendum-r4-r2-mount-resolution.md), option (B):
- * the preset's server-surface row is written as an ABSOLUTE file URL into the
- * PROFILE-installed package (lib/index.js), NOT a vendored copy. This keeps the
- * nested @deepseek-ai/cordis + @deepseek-ai/dsh-tools imports resolving through
- * the profile's flat-fallback junctions (same cordis symbols => Service identity
- * preserved), and `ctx.recursive` resolves correctly inside the isolate realm.
- *
- * Idempotent + atomic: writes to a temp file in the same directory, then renames.
- *
- * Usage: node install-preset.js [--profile <name>] [--dsh-home <dir>] [--force]
- */
-import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from 'node:fs'
-import { dirname, join, resolve } from 'node:path'
-import { homedir } from 'node:os'
-import { fileURLToPath, pathToFileURL } from 'node:url'
-
-const __dirname = dirname(fileURLToPath(import.meta.url))
-const PACKAGE_ROOT = resolve(__dirname, '..')
-const PRESET_SOURCE_DIR = join(PACKAGE_ROOT, 'preset', 'recursive')
-const PRESET_SOURCE = join(PRESET_SOURCE_DIR, 'agent.cordis.yml')
-const PRESET_METADATA_SOURCE = join(PRESET_SOURCE_DIR, 'preset.yml')
-const PLACEHOLDER = '@@RECURSIVE_SERVER_ENTRY@@'
-const PKG_NAME = '@try-works/dsh-recursive-mode'
-
-function parseArgs(argv) {
-  const out = { profile: 'web', dshHome: '', force: false }
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i]
-    if (a === '--profile' && argv[i + 1]) { out.profile = argv[++i]; continue }
-    if (a === '--dsh-home' && argv[i + 1]) { out.dshHome = argv[++i]; continue }
-    if (a === '--force') { out.force = true; continue }
-  }
-  return out
-}
-
-function fail(msg) {
-  console.error('[install-preset] FAIL: ' + msg)
-  process.exitCode = 1
-}
-
-const args = parseArgs(process.argv.slice(2))
-const dshHome = args.dshHome || process.env.DSH_HOME || join(homedir(), '.dsh')
-
-// Locate the profile install dir and its lib/index.js.
-const profilePkgDir = join(dshHome, 'profiles', args.profile, 'node_modules', ...PKG_NAME.split('/'))
-const serverEntry = join(profilePkgDir, 'lib', 'index.js')
-
-if (!existsSync(serverEntry)) {
-  fail(
-    'Profile-installed package entry not found: ' + serverEntry + "\n" +
-    '  Install the package into the profile first: pnpm dsh plugin --profile ' + args.profile + ' add ' + PKG_NAME,
-  )
-  process.exit(1)
-}
-
-const serverUrl = pathToFileURL(serverEntry).href
-
-// Read the preset template and materialize the placeholder.
-const template = readFileSync(PRESET_SOURCE, 'utf8')
-if (!template.includes(PLACEHOLDER)) {
-  fail('Preset template missing placeholder ' + PLACEHOLDER + ' in ' + PRESET_SOURCE)
-  process.exit(1)
-}
-const materialized = template.replaceAll(PLACEHOLDER, serverUrl)
-
-// Destination: ~/.dsh/.agent-presets/recursive/agent.cordis.yml
-const presetDir = join(dshHome, '.agent-presets', 'recursive')
-const presetFile = join(presetDir, 'agent.cordis.yml')
-
-if (existsSync(presetFile) && !args.force) {
-  const existing = readFileSync(presetFile, 'utf8')
-  if (existing === materialized) {
-    console.log('[install-preset] OK (already up to date): ' + presetFile)
-    console.log('  server entry: ' + serverUrl)
-    process.exit(0)
-  }
-}
-
-mkdirSync(presetDir, { recursive: true })
-const tmp = join(presetDir, '.agent.cordis.yml.tmp')
-writeFileSync(tmp, materialized, 'utf8')
-renameSync(tmp, presetFile)
-
-// Copy the optional display metadata (preset.yml) beside the composition so the
-// picker shows the human-facing name instead of the id. Absent source is fine.
-const metadataFile = join(presetDir, 'preset.yml')
-if (existsSync(PRESET_METADATA_SOURCE)) {
-  const metadataTmp = join(presetDir, '.preset.yml.tmp')
-  writeFileSync(metadataTmp, readFileSync(PRESET_METADATA_SOURCE, 'utf8'), 'utf8')
-  renameSync(metadataTmp, metadataFile)
-}
-
-console.log('[install-preset] OK: ' + presetFile)
-console.log('  server entry: ' + serverUrl)
-console.log('  (re-run is idempotent; add --force to overwrite an existing file)')