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

package/src/settlement.ts

@@ -0,0 +1,355 @@
+/**
+ * T36 — observe a delegated child's settlement WITHOUT reading session history.
+ *
+ * THE CONSTRAINT, VERIFIED IN THE CHECKOUT RATHER THAN ASSUMED. DSH prohibits new
+ * production calls to `Session.snapshotEvents()`, `Session.eventAt()` and
+ * `Session.ownEvents()`: *"existing logic may remain unmigrated for now, but new
+ * calls are prohibited"*, the rule is enforced by an executable lint check, and
+ * *"copying a waiver to a new production call violates this policy"*. The obvious
+ * implementation of an observer — scan the parent's log for the `subagent-settled`
+ * notice — is therefore exactly the thing that is forbidden, and it would also be
+ * the wrong shape: history reads make ordinary logic depend on storage.
+ *
+ * THE PRESCRIBED REPLACEMENT is to *"process the delivered current event"* or read
+ * maintained projection state. So this module never looks back. It recognises the
+ * settlement **at delivery time** (the `session/event` listener passes it as it is
+ * committed) and records it in the run's own file state, which is precisely the
+ * plugin's zero-emission, file-derived architecture: nothing is appended to the
+ * session, and the durable fact lands where every other plugin fact lands.
+ *
+ * WHY THE NOTICE ARRIVES AT ALL. A continuable child that finishes produces a
+ * durable user message in the parent whose source is `{ kind: 'subagent-settled' }`
+ * — the parent-side settlement seam. There is no promise to await, which is why
+ * `delegateContinuable` takes an injected observer instead of awaiting one.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import type { SubagentResultLike, ContinuableChildId, ContinuableMessageId } from './delegation.ts'
+
+/** A settlement notice, as the plugin records it. */
+export interface SettlementNotice {
+  /** The durable child this settles. */
+  childId: string
+  /** One line saying the child is finished and why, in the parent's vocabulary. */
+  summary: string
+  /** The child's own closing text, if it left any. */
+  closingText: string
+  /** The message id the notice arrived as, when the event carried one. */
+  messageId?: string
+}
+
+/** Minimal structural view of a delivered session event (no harness import). */
+export interface SessionEventLike {
+  type?: string
+  data?: unknown
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === 'object' && value !== null ? value as Record<string, unknown> : null
+}
+
+function textOf(block: unknown): string {
+  const record = asRecord(block)
+  return record !== null && record.type === 'text' && typeof record.text === 'string' ? record.text : ''
+}
+
+/**
+ * Recognise a settlement notice from a DELIVERED session event, or null when the
+ * event is not one. Pure: no I/O, no history read, safe on any event.
+ *
+ * The notice's shape is the harness's: a `user/message` whose `source.kind` is
+ * `subagent-settled` and whose `source.senderSessionId` names the child. The
+ * content is a summary line, then optionally `Its closing message:` followed by
+ * the child's own text — so the closing text is everything after that marker, and
+ * a child that left nothing yields the harness's own "It left no closing message."
+ */
+export function settlementFromEvent(event: SessionEventLike): SettlementNotice | null {
+  if (event?.type !== 'user/message') return null
+  const message = asRecord(event.data)
+  if (message === null) return null
+  const source = asRecord(message.source)
+  if (source === null || source.kind !== 'subagent-settled') return null
+  const childId = typeof source.senderSessionId === 'string' ? source.senderSessionId : ''
+  if (childId === '') return null
+
+  const content = Array.isArray(message.content) ? message.content : []
+  const texts = content.map(textOf).filter((t) => t !== '')
+  const markerIndex = texts.findIndex((t) => t === 'Its closing message:')
+  const summary = typeof source.summary === 'string' && source.summary !== ''
+    ? source.summary
+    : (texts[0] ?? '')
+  const closingText = markerIndex >= 0 ? texts.slice(markerIndex + 1).join('\n\n') : ''
+
+  const notice: SettlementNotice = { childId, summary, closingText }
+  if (typeof message.id === 'string' && message.id !== '') notice.messageId = message.id
+  return notice
+}
+
+/** The run-scoped append-only settlement log. */
+export function settlementLogPath(runDir: string): string {
+  return join(runDir, 'subagents', 'settlements.jsonl')
+}
+
+/**
+ * Which run owns this child, resolved from the FILESYSTEM alone.
+ *
+ * The delivered event names the child (`source.senderSessionId`) but not the run,
+ * and the plugin's whole design is to derive placement from what is on disk rather
+ * than to keep a registry that could go stale. A delegation writes its child
+ * directories as `subagents/<delegationId>/child-<childId>/`, so the run holding
+ * that child is the run the settlement belongs to.
+ *
+ * AMBIGUITY RETURNS NULL rather than guessing. Two runs claiming the same child
+ * would mean a copied tree, and filing a settlement into the wrong run is worse
+ * than not filing it: it would attach one run's evidence to another run's chain.
+ * A miss costs a settlement the loop will report as "no settlement yet", which is
+ * recoverable; mis-filing is not.
+ */
+export function runDirForChild(root: string, childId: string): string | null {  if (childId === '' || root === '') return null
+  const runsRoot = join(root, '.recursive', 'run')
+  let runs: string[]
+  try {
+    runs = readdirSync(runsRoot, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort()
+  } catch {
+    return null
+  }
+
+  const matches: string[] = []
+  for (const runName of runs) {
+    const runDir = join(runsRoot, runName)
+    let delegations: string[]
+    try {
+      delegations = readdirSync(join(runDir, 'subagents'), { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+    } catch {
+      continue
+    }
+    for (const delegationId of delegations) {
+      if (existsSync(join(runDir, 'subagents', delegationId, 'child-' + childId))) {
+        matches.push(runDir)
+        break
+      }
+    }
+  }
+  return matches.length === 1 ? matches[0]! : null
+}
+
+/**
+ * Record one notice in the run's file state. APPEND-ONLY, matching the run's own
+ * evidence posture: a settlement that already happened is a fact, and rewriting
+ * the log would let a later write erase the record of an earlier round.
+ */
+export function recordSettlement(runDir: string, notice: SettlementNotice): string {
+  const path = settlementLogPath(runDir)
+  mkdirSync(dirname(path), { recursive: true })
+  appendFileSync(path, JSON.stringify(notice) + '\n', 'utf8')
+  return path
+}
+
+/** Every recorded notice for a run, in arrival order. Never throws. */
+/**
+ * ⚠ FU-17 — THE ADOPTION PATH, for a settlement whose child this plugin never filed.
+ *
+ * WHY IT EXISTS. `runDirForChild` attributes a child by the `subagents/<delegation>/child-<id>/` layout that a
+ * delegation writes, and it refuses to guess — its own comment: *"filing a settlement into the wrong run is worse
+ * than not filing it: it would attach one run's evidence to another run's chain. A miss costs a settlement the
+ * loop will report as 'no settlement yet', which is recoverable; mis-filing is not."*
+ *
+ * That refusal is right, and it has a cost this feature cannot accept: a child started through the harness's own
+ * tools (or any path that did not write a delegation directory) settles into nothing, so the run loses evidence
+ * of work that really happened — and a phase artifact that must cite an action record cannot cite one that was
+ * never filed.
+ *
+ * THE RULE IS PROGRESSIVE AND NEVER GUESSES BETWEEN RUNS:
+ *   1. exactly one run under the root  → file into THAT run, under a clearly-marked `adopted-<child>/` directory,
+ *      and say in the record that it was adopted and why;
+ *   2. more than one run               → file into a ROOT-level `adopted-settlements.jsonl` instead, because
+ *      choosing between runs is exactly the mis-filing the rule above forbids. The fact is still recorded, in a
+ *      place that can attribute nothing to the wrong chain.
+ *
+ * Returns the path it wrote, or null when there was nothing to write. Never throws: this rides the same hot path
+ * as `captureSettlement` and must not break the session it observes.
+ */
+export function adoptSettlement(root: string, notice: SettlementNotice): string | null {
+  if (notice.childId === '') return null
+  try {
+    const runsRoot = join(root, '.recursive', 'run')
+    let runs: string[] = []
+    try {
+      runs = readdirSync(runsRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort()
+    } catch {
+      return null
+    }
+
+    // Case 2 — ambiguous, so it is recorded OUTSIDE every run's evidence chain.
+    if (runs.length !== 1) {
+      const path = join(root, '.recursive', 'adopted-settlements.jsonl')
+      mkdirSync(dirname(path), { recursive: true })
+      appendFileSync(path, JSON.stringify({
+        adopted: true,
+        reason: 'no delegation directory for this child, and ' + runs.length + ' runs exist',
+        run: null,
+        childId: notice.childId,
+        summary: notice.summary,
+        closingText: notice.closingText,
+      }) + '\n', 'utf8')
+      return path
+    }
+
+    // Case 1 — one run, so the child can only belong to it. Still marked as adopted: the delegation directory
+    // the normal path would have used does not exist, and a reader must be able to tell the two apart.
+    const path = join(runsRoot, runs[0]!, 'subagents', 'adopted-' + notice.childId, 'settlement.jsonl')
+    mkdirSync(dirname(path), { recursive: true })
+    appendFileSync(path, JSON.stringify({
+      adopted: true,
+      reason: 'no delegation directory for this child; single-run workspace',
+      childId: notice.childId,
+      summary: notice.summary,
+      closingText: notice.closingText,
+    }) + '\n', 'utf8')
+    return path
+  } catch {
+    return null
+  }
+}
+
+export function readSettlements(runDir: string): SettlementNotice[] {  let raw: string
+  try {
+    raw = readFileSync(settlementLogPath(runDir), 'utf8')
+  } catch {
+    return []
+  }
+  const out: SettlementNotice[] = []
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim()
+    if (trimmed === '') continue
+    try {
+      const parsed = asRecord(JSON.parse(trimmed))
+      if (parsed !== null && typeof parsed.childId === 'string' && typeof parsed.summary === 'string') {
+        const notice: SettlementNotice = {
+          childId: parsed.childId,
+          summary: parsed.summary,
+          closingText: typeof parsed.closingText === 'string' ? parsed.closingText : '',
+        }
+        if (typeof parsed.messageId === 'string') notice.messageId = parsed.messageId
+        out.push(notice)
+      }
+    } catch {
+      // A malformed line is skipped rather than failing the whole read: a log
+      // that a partial write corrupted must not make the run unobservable.
+    }
+  }
+  return out
+}
+
+/** The LATEST recorded settlement for one child, or null when none has landed. */
+export function readSettlement(runDir: string, childId: string): SettlementNotice | null {
+  const mine = readSettlements(runDir).filter((n) => n.childId === childId)
+  return mine.length === 0 ? null : mine[mine.length - 1]!
+}
+
+/**
+ * Turn a recorded settlement into the result shape the delegation loop reads.
+ *
+ * `success` is deliberately NOT asserted from the summary: the notice reports how
+ * the child's turn ENDED, not whether its work is acceptable. Acceptance is the
+ * verdict's job (`readVerdict` + `evaluateDelegationResult`), and defaulting to
+ * success here would let a stopped child be treated as a passing review — the
+ * exact silent-approval failure `delegateContinuable` refuses to fabricate.
+ */
+export function settlementResult(notice: SettlementNotice): SubagentResultLike {
+  const result: SubagentResultLike = {
+    output: notice.closingText,
+    stopReason: 'completed',
+  } as SubagentResultLike
+  // A child that reported structured JSON leaves it as the closing text.
+  const parsed = (() => {
+    try { return JSON.parse(notice.closingText) } catch { return undefined }
+  })()
+  if (parsed !== undefined) (result as { structured?: unknown }).structured = parsed
+  return result
+}
+
+/**
+ * Build the `awaitRoundResult` observer the continuable loop injects.
+ *
+ * ⚠ IT NOW WAITS, AND THAT IS THE FU-9 DECISION (option a, chosen by the user). It used to read the
+ * settlement log ONCE and return null immediately, which the loop reports as `parked` — a correct signal, but
+ * it meant the parent returned before the child had run at all. The control that shows why that matters: the
+ * harness's own team fixture, same recipe, completed two teammates while this plugin's delegated child never
+ * got a turn — and the engine's contract explains it, `submitAdmitted` *"crosses the final admission cutoff
+ * and submits without yielding"*, so a parent that returns lets the host go idle, and an idle one-shot session
+ * never pumps the child's inbox.
+ *
+ * ⚠ THE PARK IS KEPT, as the fallback it always was. The wait is bounded by `timeoutMs`; when the deadline
+ * passes the observer STILL returns null, so the caller still parks, still resumes on a later turn with the
+ * SAME child id, and still never treats an unobserved round as approval — the T36 rules are intact. What
+ * changed is that parking is now what happens AFTER a real wait rather than INSTEAD of one.
+ *
+ * `sleep` is injectable so a test asserts the waiting without spending wall-clock time, and `timeoutMs: 0`
+ * reproduces the old read-once behaviour exactly — which is what the tests that assert a park use.
+ */
+export function settlementRoundObserver(
+  runDir: string,
+  options: { timeoutMs?: number; pollMs?: number; sleep?: (ms: number) => Promise<void> } = {},
+): (childId: ContinuableChildId, messageId: ContinuableMessageId) => Promise<SubagentResultLike | null> {
+  const timeoutMs = options.timeoutMs ?? 30_000
+  const pollMs = options.pollMs ?? 250
+  const sleep = options.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)))
+  return async (childId: ContinuableChildId) => {
+    const deadline = Date.now() + timeoutMs
+    for (;;) {
+      const notice = readSettlement(runDir, String(childId))
+      if (notice !== null) return settlementResult(notice)
+      if (Date.now() >= deadline) return null
+      await sleep(pollMs)
+    }
+  }
+}
+
+/**
+ * Handle one delivered session event: record it when it is a settlement, and
+ * report whether it was one. Wired to `ctx.on('session/event', …)`, which the
+ * harness documents as the delivery point for every committed event.
+ */
+export function captureSettlement(runDir: string, event: SessionEventLike): SettlementNotice | null {
+  const notice = settlementFromEvent(event)
+  if (notice === null) return null
+  recordSettlement(runDir, notice)
+  return notice
+}
+
+/**
+ * FU-3 — the children a run has on its books, read from the layout the delegations already write.
+ *
+ * WHY FROM DISK AND NOT FROM MEMORY. A delegation records itself as `subagents/<delegationId>/child-<childId>/`
+ * (see {@link runDirForChild}), which is the same fact the settlement log is keyed on. Reading it back
+ * means a drain at closeout works **in a fresh process** — after a resume, a crash or a compaction — where
+ * an in-memory list of children would be empty and the run would silently leak every child it started.
+ *
+ * ⚠ AN EMPTY ANSWER IS A REAL ANSWER: a run that delegated nothing has no children, and the caller must
+ * be able to tell that from a failed lookup — hence a plain `[]` rather than `null`.
+ */
+export function runChildIds(runDir: string): string[] {
+  const base = join(runDir, 'subagents')
+  if (!existsSync(base)) return []
+  const ids: string[] = []
+  for (const delegation of readdirSync(base, { withFileTypes: true })) {
+    if (!delegation.isDirectory()) continue
+    const delegationDir = join(base, delegation.name)
+    for (const child of readdirSync(delegationDir, { withFileTypes: true })) {
+      if (child.isDirectory() && child.name.startsWith('child-')) {
+        const id = child.name.slice('child-'.length)
+        if (id !== '' && !ids.includes(id)) ids.push(id)
+      }
+    }
+  }
+  return ids
+}

package/src/skills-phase.ts

@@ -0,0 +1,143 @@
+/**
+ * T12 — register each phase's rules as a SKILL, so they are discoverable in the catalogue.
+ *
+ * WHY. Phase 8 writes skill memory to the filesystem, and a phase's rules otherwise live only in
+ * this plugin's `phase-rules.ts` — reachable by grepping a checkout, not by the agent or a child
+ * asking what a phase requires. The native `ctx.skills` registry is a *catalogue*: a skill it
+ * holds is discoverable by name, addressable by `get()`, and visible to a discovery consumer.
+ * Registering the phase rules there is what turns "the rules are in the source" into "the rules
+ * are answerable".
+ *
+ * ⚠ THE REGISTRATION IS A RUNTIME CONTRIBUTION, and the harness names that source explicitly
+ * (`SkillSource` includes `'runtime'`). Declaring `source: 'runtime'` is not decoration: it is how
+ * the registry can tell this skill apart from one a checkout or a user directory supplied, and it
+ * is what makes the plugin's contribution replaceable rather than tangled with the filesystem's.
+ *
+ * ⚠ AN ABSENT REGISTRY IS NOT A FAILURE. `ctx.skills` is an optional service; with none mounted
+ * the helper does nothing and SAYS it did nothing (`skipped: true`) — the plugin's convention for
+ * every optional seam, because a composition without a catalogue should still run the workflow.
+ */
+import { phaseRulesFor, type PhaseRules } from './phase-rules.ts'
+
+/** The prefix every phase skill carries, so the plugin's contributions are recognisable. */
+export const PHASE_SKILL_PREFIX = 'recursive-phase'
+
+/**
+ * One runtime skill contribution.
+ *
+ * Structural rather than imported from the harness: the plugin models every harness touchpoint as
+ * a minimal seam, and this keeps the shape testable with a fake registry.
+ */
+export interface PhaseSkillRegistration {
+  name: string
+  description: string
+  whenToUse?: string
+  content: string
+  /** A RUNTIME contribution — see the module comment for why this is declared, not implied. */
+  source: 'runtime'
+}
+
+export interface SkillRegistryLike {
+  register(registration: PhaseSkillRegistration): () => void
+}
+
+/**
+ * The skill name for a phase file.
+ *
+ * Kebab-case, because the registry addresses skills by a kebab-case identifier — and STABLE,
+ * because a discoverable rule nobody can name is not discoverable. `01.5-root-cause.md` becomes
+ * `recursive-phase-01-5-root-cause`: the dot cannot survive, and dropping the sub-phase number
+ * would collide it with a whole phase.
+ */
+export function phaseSkillName(fileName: string): string {
+  const slug = fileName
+    .replace(/\.md$/i, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+  return PHASE_SKILL_PREFIX + '-' + slug
+}
+
+/** The markdown body a reader gets from the catalogue. */
+function phaseSkillContent(rules: PhaseRules): string {
+  const lines: string[] = []
+  lines.push('# Phase rules: ' + rules.fileName)
+  lines.push('')
+  lines.push('This phase is ' + rules.label + '. Its required sections are checked by the linter,')
+  lines.push('and a missing one is a lint failure — not a style preference.')
+  lines.push('')
+  lines.push('## Required sections')
+  lines.push('')
+  for (const section of rules.requiredSections) {
+    lines.push('- ' + section)
+  }
+  if (rules.requiredSections.length === 0) {
+    lines.push('- (none declared for this phase)')
+  }
+  lines.push('')
+  lines.push('## Flags')
+  lines.push('')
+  lines.push('- audited: ' + (rules.audited ? 'yes — this phase needs a delegated audit' : 'no'))
+  lines.push('- tdd: ' + (rules.tdd ? 'yes — the TDD Compliance gate applies' : 'no'))
+  lines.push('- qa: ' + (rules.qa ? 'yes — the manual QA gate applies' : 'no'))
+  return lines.join('\n')
+}
+
+/** Build the registration for one phase. Pure, so the mapping is testable without a registry. */
+export function phaseSkillRegistration(rules: PhaseRules): PhaseSkillRegistration {
+  const gates: string[] = []
+  if (rules.audited) gates.push('audited')
+  if (rules.tdd) gates.push('TDD')
+  if (rules.qa) gates.push('QA')
+  return {
+    name: phaseSkillName(rules.fileName),
+    description: 'Rules for ' + rules.fileName + ' (' + rules.label + '): its required sections and gates.',
+    whenToUse: 'Use when authoring, linting or reviewing ' + rules.fileName
+      + (gates.length === 0 ? '.' : ', which carries the ' + gates.join(' / ') + ' gate(s).'),
+    content: phaseSkillContent(rules),
+    source: 'runtime',
+  }
+}
+
+export interface PhaseSkillRegistrationResult {
+  /** Names registered, in phase order. */
+  registered: string[]
+  /** Disposers, so a caller can withdraw the contribution with its own effects. */
+  disposers: Array<() => void>
+  /** True when there was no registry: nothing was registered, and that is not an error. */
+  skipped: boolean
+}
+
+/**
+ * Register every phase's rules as a skill.
+ *
+ * Takes `fileNames` rather than reading a directory so the caller decides WHICH phases this
+ * composition exposes; the rules themselves come from `phaseRulesFor`, so there is one definition
+ * of what a phase requires and no second copy to drift.
+ */
+export function registerPhaseSkills(
+  skills: SkillRegistryLike | null | undefined,
+  fileNames: readonly string[],
+  workflowProfile?: string,
+): PhaseSkillRegistrationResult {
+  if (skills === null || skills === undefined || typeof skills.register !== 'function') {
+    return { registered: [], disposers: [], skipped: true }
+  }
+  const registered: string[] = []
+  const disposers: Array<() => void> = []
+  for (const fileName of fileNames) {
+    const registration = phaseSkillRegistration(phaseRulesFor(fileName, workflowProfile))
+    disposers.push(skills.register(registration))
+    registered.push(registration.name)
+  }
+  return { registered, disposers, skipped: false }
+}
+
+/**
+ * A board-facing line for the registration result — says SKIPPED out loud rather than leaving a
+ * reader to infer a missing catalogue from an empty list.
+ */
+export function describePhaseSkills(result: PhaseSkillRegistrationResult): string {
+  if (result.skipped) return 'phase rules were NOT registered as skills: no skill registry is mounted'
+  return result.registered.length + ' phase rule skill(s) registered: ' + result.registered.join(', ')
+}

package/src/skills.ts

@@ -0,0 +1,151 @@
+/**
+ * Packaged `recursive-mode` skill (dsh plugin standard).
+ *
+ * Ships the workflow's operating contract as a bundled skill through
+ * `ctx.skills.registerProvider(...)` — the same shape as the shipped
+ * `dsh-skill-badge` provider: a `bundled` candidate at `BUNDLED_SKILL_RANK`
+ * (600), body read from the package's shipped `skills/recursive-mode/SKILL.md`
+ * (never an inlined TS string literal), with a directory resource base so the
+ * skill can resolve its own assets. Skills are optional instructions, not
+ * session events: this emits nothing and never appends a recursive/* event.
+ *
+ * Optionality: `skills` is a host-plane registry; when the composition has
+ * none, this is a no-op (returns undefined) rather than failing boot.
+ */
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Context } from '@deepseek-ai/cordis'
+
+/** Package root: <package>/src/.. — skills/ sits next to src/. */
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url))
+const PACKAGE_ROOT = join(MODULE_DIR, '..')
+
+/** Precedence rank for packaged/bundled skills (mirrors `BUNDLED_SKILL_RANK`). */
+const BUNDLED_SKILL_RANK = 600
+const SKILL_NAME = 'recursive-mode'
+const PROVIDER_NAME = 'recursive-mode'
+const SKILL_BODY_PATH = join(PACKAGE_ROOT, 'skills', SKILL_NAME, 'SKILL.md')
+const SKILL_RESOURCE_BASE = join(PACKAGE_ROOT, 'skills', SKILL_NAME)
+const SKILL_DESCRIPTION =
+  'Drive the recursive-mode workflow: an audit-gated, phase-disciplined loop that carries one requirement from AS-IS through TO-BE plan, implementation, test, and manual QA to locked control-plane state and durable memory. Use whenever the user asks to implement, resume, or advance a recursive run, or when a repo carries a /.recursive/ control plane.'
+
+/** Invocation policy: both the model catalog and user `/name` surfaces may load it. */
+const INVOCATION = { modelInvocable: true, userInvocable: true } as const
+
+/** One skill contribution, mirrored from the `dsh-skill` registry contract. */
+export interface SkillInvocationPolicyLike {
+  readonly modelInvocable: boolean
+  readonly userInvocable: boolean
+}
+
+/** Provider-owned base for relative resource resolution. */
+export type SkillResourceBaseLike =
+  | { readonly kind: 'directory'; readonly path: string }
+  | { readonly kind: 'url'; readonly url: string }
+  | { readonly kind: 'opaque'; readonly description: string }
+
+/** Invocation-neutral summary fields shared by candidates and definitions. */
+export interface SkillSummaryLike {
+  readonly name: string
+  readonly description: string
+  readonly whenToUse?: string
+  readonly invocation: SkillInvocationPolicyLike
+  readonly source: string
+  readonly provider: string
+  readonly resourceBase?: SkillResourceBaseLike
+}
+
+/** Provider catalog entry: a summary plus rank and an opaque locator. */
+export interface SkillCandidateLike extends SkillSummaryLike {
+  readonly rank: number
+  readonly locator: unknown
+  readonly path?: string
+}
+
+/** Complete loaded skill: a summary plus the markdown instruction body. */
+export interface SkillDefinitionLike extends SkillSummaryLike {
+  readonly content: string
+  readonly path?: string
+}
+
+/** Lookup options passed to provider `list`/`get`. */
+export interface SkillLookupOptionsLike {
+  readonly cwd?: string | undefined
+  readonly signal?: AbortSignal | undefined
+}
+
+/** Registration-scoped control borrowed by one provider. */
+export interface SkillProviderControlLike {
+  readonly signal: AbortSignal
+  readonly invalidate: () => void
+}
+
+/** One source of skills, mirrored from the `dsh-skill` SkillProvider contract. */
+export interface SkillProviderLike {
+  readonly name: string
+  readonly list: (options: SkillLookupOptionsLike) => Promise<readonly SkillCandidateLike[] | { readonly candidates: readonly SkillCandidateLike[]; readonly complete: boolean }>
+  readonly get: (candidate: SkillCandidateLike, options: SkillLookupOptionsLike) => Promise<SkillDefinitionLike | undefined>
+}
+
+/** Minimal host-realm contract for ctx.skills (the seam we call). */
+export interface SkillsRuntimeLike {
+  registerProvider(create: (control: SkillProviderControlLike) => SkillProviderLike): () => void
+}
+
+/** The bundled candidate, stable across every `list()` call. */
+function candidate(): SkillCandidateLike {
+  return {
+    name: SKILL_NAME,
+    description: SKILL_DESCRIPTION,
+    invocation: INVOCATION,
+    provider: PROVIDER_NAME,
+    source: 'bundled',
+    resourceBase: { kind: 'directory', path: SKILL_RESOURCE_BASE },
+    rank: BUNDLED_SKILL_RANK,
+    locator: SKILL_BODY_PATH,
+    path: SKILL_BODY_PATH,
+  }
+}
+
+/** Read the shipped operating-contract body (fail loud if the package lost it). */
+function readBody(): string {
+  return readFileSync(SKILL_BODY_PATH, 'utf8').replace(/\r\n/g, '\n').replace(/\r/g, '\n')
+}
+
+/** The one bundled provider this plugin contributes. */
+function provider(): SkillProviderLike {
+  return {
+    name: PROVIDER_NAME,
+    list: () => Promise.resolve([candidate()]),
+    get: async () => ({
+      name: SKILL_NAME,
+      description: SKILL_DESCRIPTION,
+      invocation: INVOCATION,
+      provider: PROVIDER_NAME,
+      source: 'bundled',
+      resourceBase: { kind: 'directory', path: SKILL_RESOURCE_BASE },
+      content: readBody(),
+      path: SKILL_BODY_PATH,
+    }),
+  }
+}
+
+/**
+ * Register the packaged `recursive-mode` skill into the host `skills` registry.
+ *
+ * Reads `ctx.get('skills')` optionally (the registry is host-plane; a
+ * composition without it is valid). On success returns the exact disposer that
+ * unregisters the provider; on absence returns undefined (a no-op, never a boot
+ * failure).
+ */
+export function registerRecursiveSkill(ctx: Context): (() => void) | undefined {
+  const skills = ctx.get('skills')
+  if (skills === undefined || skills === null) return undefined
+  // SAFETY: the single boundary cast asserts the live ctx.skills satisfies the
+  // structural SkillsRuntimeLike seam (registerProvider). The live registry's
+  // method is a superset of this seam; the provider we return is a plain owned
+  // object read through its own leaf fields, never serialized.
+  const registry = skills as SkillsRuntimeLike
+  return registry.registerProvider(() => provider())
+}