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

package/lib/runtime.d.ts

@@ -1,10 +1,16 @@
 import { Service, type Context } from '@deepseek-ai/cordis';
-import type { RecursiveStatusResult } from './types.ts';
+import { type ReceiptChainResult } from './lock.ts';
+import type { PendingWorkItem, RecursiveStatusResult } from './types.ts';
+import { type HookRegistry } from './hooks.ts';
+import { type JobsRegistryLike } from './jobs-runner.ts';
+import { type LlmInventoryLike } from './model-inventory.ts';
+import { type GuardDecisionRecord } from './guard-log.ts';
 import { type WorkspaceRegistryLike } from './workspace.ts';
 import { type PhaseRules } from './phase-rules.ts';
 import { type ScratchTarget } from './scratch.ts';
 import { type ReviewBundleInput } from './review.ts';
-import { type SubagentProviderLike, type RouteDecision, type CapabilityProbe } from './router.ts';
+import type { WorkflowEngineLike } from './workflow-audit.ts';
+import { type RouterPolicyOverrides, type SubagentProviderLike, type RouteDecision, type CapabilityProbe } from './router.ts';
 import { type SubagentsRuntimeLike, type SubagentStartRequestLike, type SubagentResultLike, type Reference, type SubagentParentHandle } from './delegation.ts';
 import { type RecursivePhaseState } from './lifecycle.ts';
 import { type EnforcementConfig, type ToolGuardDecision, type ToolExecLike } from './enforcement.ts';
@@ -33,16 +39,151 @@ export interface LintArtifactResult {
     warnings: string[];
     passed: boolean;
 }
+/**
+ * T15 (G): the folded status PLUS the rolling guard-decision evidence. Declared
+ * as an intersection rather than by editing RecursiveStatusResult/foldRun — the
+ * fold's own shape is parity-asserted and stays exactly as it was.
+ */
+export type RecursiveStatusWithGuardDecisions = RecursiveStatusResult & {
+    guardDecisions?: GuardDecisionRecord[];
+    /**
+     * T18: unresolved in-flight work, derived from the run directory on every call.
+     * Always present (empty when nothing is in flight) so consumers need no null
+     * check, and non-empty explains a `RM4403` lock refusal.
+     */
+    pendingWork?: PendingWorkItem[];
+    /**
+     * T32: the receipt-chain verdict, derived read-only on every call. Always present
+     * so a caller can read `ok` without a null check; non-empty `breaks` names the
+     * first broken link. This is what makes a spliced or edited chain VISIBLE rather
+     * than merely detectable in a test.
+     */
+    receiptChain?: ReceiptChainResult;
+    /**
+     * T22: the local identifier of the policy section's STABLE prefix.
+     *
+     * Surfaced so "did the contract change under me?" is answerable from the status alone — the same
+     * digest the prompt carries, so a reader can compare them without re-rendering anything. It is an
+     * IDENTIFIER, not a cache directive: whether any provider caches the prefix is provider-side and
+     * unverified, which is why the item's "largest cost lever" label was withdrawn.
+     */
+    contractDigest?: string;
+};
 export declare class RecursiveRuntime extends Service {
     /** Recursive-mode runtime service. Owns run-state reads + lock/init/lint operations. */
     constructor(ctx: Context, config?: {
         repoRoot?: string;
         workspaceRegistry?: WorkspaceRegistryLike;
         goals?: GoalServiceLike | null;
+        jobs?: JobsRegistryLike | null;
+        subagents?: SubagentsRuntimeLike | null;
+        workflow?: WorkflowEngineLike | null;
     });
+    /** T10: the native jobs registry, when the composition mounts one. */
+    private readonly jobs;
+    /**
+     * T23 — write a gate's answer into an artifact as a marker line.
+     *
+     * ⚠ REPLACED IN PLACE when the artifact already carries that gate's marker: two `TDD Mode:` lines
+     * would leave two answers to one question and make "what was decided?" depend on which a reader
+     * found first. The write is confined to the run directory, and an artifact that does not exist is
+     * CREATED — a decision recorded nowhere is not recorded.
+     */
+    recordAskAnswer(root: string, runId: string, artifact: string, marker: string): {
+        path: string;
+        replaced: boolean;
+    };
+    /**
+     * T2: the workflow engine, when the composition mounts one.
+     *
+     * OPTIONAL like every other seam here — without it an audit fan-out reports that it could not be
+     * orchestrated rather than pretending a fan-out happened. The engine's `workflow/*` events are
+     * observe-only, so this is used to START a run and await its result, never to drive one.
+     */
+    private readonly workflow;
+    /**
+     * T39: the subagents seam the composition mounted, used when a caller does not pass one.
+     *
+     * ⚠ WHY THIS EXISTS, measured rather than assumed: `recursive_review.tool.ts` — the ONLY
+     * production caller of `delegateReview` — passes **no `subagents`** at its call site, and
+     * `delegateReview` reports *"no ctx.subagents runtime available (self-audit fallback)"* when
+     * the input lacks one. So on a composition that HAS the service, the review tool's rounds
+     * never reached a child at all, and the fallback message blamed a missing runtime that was
+     * in fact mounted. Resolving the seam here fixes the wiring without asking every call site to
+     * remember, while an explicit `input.subagents` still wins for a test or a narrower caller.
+     */
+    private subagentsSeam;
+    /** FU-19: the host's provider/model inventory, or null when no llm service is mounted. */
+    private llmInventory;
+    /**
+     * ⚠ FU-9 — ATTACH THE SEAM WHEN THE SERVICE APPEARS, not only when this plugin happens to apply.
+     *
+     * The composition resolved the seam with a ONE-SHOT `ctx.get('subagents')` at apply time, and a live run
+     * showed what that costs: the review fell back to self-audit, the action record said
+     * `Execution Mode: self-audit (continuable)` and `Status: failed`, and **no child was ever started** — while
+     * the child DIRECTORY existed all along, because the plugin writes its own brief before calling any service.
+     * I read the directory and built a host-limitation story on top of it; the record said otherwise.
+     *
+     * If the subagents service is mounted by a later loader layer, a one-shot get returns undefined and nothing
+     * re-resolves it. `ctx.inject(['subagents'], …)` is the harness's own pattern for exactly this, and calling
+     * this method from there makes the seam arrive whenever it arrives. Idempotent: the last attach wins, which
+     * is what a re-apply after a reload wants.
+     */
+    attachSubagents(seam: SubagentsRuntimeLike | null): void;
+    /**
+     * ⚠ FU-19 — THE LLM INVENTORY SEAM, resolved the same late-attaching way the subagents seam is and for the same
+     * measured reason: a one-shot `ctx.get` at apply time misses a service mounted by a later layer.
+     *
+     * Null is a legitimate value and it is NOT treated as "no models exist" — `describeInventory(null)` reports a
+     * named unavailability, and `checkModelChoice` turns that into the `unverified` verdict. A missing inventory
+     * therefore never silently approves a model and never silently replaces one.
+     */
+    attachLlmInventory(seam: LlmInventoryLike | null): void;
+    /** What the composition attached, for a caller that needs to report or assert it. */
+    attachedSubagents(): SubagentsRuntimeLike | null;
+    /**
+     * ⚠ FU-9 — THE ROUTER'S PROVIDER MAP, BUILT FROM THE SEAM THAT IS ALREADY ATTACHED.
+     *
+     * `router.ts` returns the NATIVE tier for the first of `[role, 'spawn', 'fork', 'dsh-sdk']` present in this
+     * map. Handed `{}` it tried the external CLI route (null in the default policy) and fell to the policy
+     * fallback — self-audit — with a message naming neither. The router already preferred native; nobody ever
+     * gave it a name. A live review self-audited for five rounds because of it.
+     *
+     * `SubagentProviderLike` is only a DESCRIPTOR (`{ name, capabilities? }`), so a provider is registered by
+     * ASKING the service for it rather than by wrapping it. A service that cannot enumerate yields an empty map
+     * and the previous behaviour, which is the correct degradation rather than a guess about the shape.
+     */
+    private providerMapFromSeam;
+    /** The provider names the last `providerMapFromSeam` call registered, for the record and for assertions. */
+    private lastProviderNames;
+    /** What the router could choose from, so a failure can say whether the name it used was ever on offer. */
+    knownProviderNames(): string[];
     private readonly repoRoot;
     private readonly workspaceRegistry;
     private readonly goalsService;
+    /**
+     * T27 — the hook registry, EXPOSED so a sibling plugin can participate in a run
+     * without patching this one:
+     *
+     *     ctx.recursive.hooks.register('pre_trigger', { name: 'my-check', priority: 10, run })
+     *
+     * That is the whole point of the item: the plugin's own enforcement will be
+     * re-expressed as built-in hooks on this same registry, so a sibling and a built-in
+     * are peers — same ordering rules, same failure policy, same audit trail — rather
+     * than one being privileged code and the other a guest.
+     *
+     * Public and created eagerly: a registry that has to be "got" before it can be used
+     * is a registry whose ordering depends on when someone remembered to fetch it.
+     */
+    readonly hooks: HookRegistry;
+    /**
+     * T7 — router overrides from the settings namespace. Kept beside the config rather than
+     * merged into the file so the workspace's `recursive-router.json` stays the declarative
+     * source: `loadRouterPolicy` reads the file and lays these on top.
+     */
+    private _routerOverrides;
+    /** T7: set (or clear) the router overrides. Called from `apply` on every plugin load. */
+    setRouterOverrides(overrides: RouterPolicyOverrides | undefined): void;
     private _enforcementConfig;
     /**
      * T3 (agentTeams task loop): run the audit→repair→re-audit state machine on
@@ -146,17 +287,41 @@ export declare class RecursiveRuntime extends Service {
      * Run-scoped closeout receipt scaffold (R2), rooted under the given
      * workspace root. Refuses runIds outside the root (never crosses workspaces).
      */
-    closeoutRun(root: string, runId: string, phase: string): {
-        error: string;
-    } | {
+    closeoutRun(root: string, runId: string, phase: string, agent?: {
+        session?: {
+            header?: {
+                cwd?: string;
+            };
+        };
+    } | null): Promise<{
+        drain?: {
+            children: number;
+            drained: boolean;
+            reason?: string;
+        } | undefined;
+        training?: import("./training.ts").TrainingResult | undefined;
         phase: string;
-        file: string;
-        created: string[];
-        existing: string[];
+        artifact: string;
+        label: string;
+        exists: boolean;
+        status: string;
+        findings: import("./closeout-report.ts").CloseoutFinding[];
+        prerequisites: Array<{
+            artifact: string;
+            status: string;
+        }>;
+        guidance: string[];
+        addenda: string[];
         closeoutPhase: string;
         runId: string;
-        error?: undefined;
-    };
+    } | {
+        drain?: {
+            children: number;
+            drained: boolean;
+            reason?: string;
+        } | undefined;
+        error: string;
+    }>;
     /**
      * Run-scoped scratchpad access (R5), rooted under the given workspace root.
      */
@@ -188,6 +353,19 @@ export declare class RecursiveRuntime extends Service {
      * ctx.subagents with the full request (R4). Workspace-scoped: every path
      * resolves under the session's control-plane root.
      *
+     * DELEGATION IS ALWAYS CONTINUABLE (T35). The default mode is `continuable`:
+     * an explicit `mode: 'one-shot'` is the ONLY way to give up the repair path,
+     * and that path only exists for a caller that genuinely discards the result.
+     *
+     * WHY THIS IS THE DEFAULT. A one-shot child is NOT resumable — the harness
+     * rejects a resume with "subagent cannot be resumed" — so choosing one-shot
+     * forfeits the ability to send a failed review back to the agent that did the
+     * work. A continuable child has ONE durable Session across activations, so a
+     * REVISE reaches the SAME child with its working context intact instead of
+     * spawning a fresh one that must re-read the whole handoff to rediscover what
+     * it already knew. Since verification that cannot be followed by repair is
+     * just a complaint, the repair path is the default rather than an option.
+     *
      * `mode: 'continuable'` (T4) runs the audit→repair→re-audit loop on ONE
      * durable continuable child (startContinuable → followup with the repair
      * instruction → settle) and drains the child on closeout. It requires an
@@ -215,8 +393,52 @@ export declare class RecursiveRuntime extends Service {
         subagents?: SubagentsRuntimeLike;
         maxDepth?: number;
         toolFilter?: unknown;
+        /**
+         * ⚠ FU-17 — THE BRIEF SLICE, WHEN THE CALLER OWNS IT.
+         *
+         * A review's slice is written here because a reviewer's briefing is review-shaped by definition. A WORK
+         * delegation needs the opposite kind of briefing — what to produce and the standard it will be linted
+         * against — and that is computed by `buildWorkSlice` from the phase rules. This seam lets a work caller pass
+         * it in without this method growing a second, drifting copy of the phase standard.
+         *
+         * ADDITIVE BY CONSTRUCTION: absent, the review slice below is built exactly as it always was, which is what
+         * keeps the review path's behaviour provable rather than merely claimed.
+         */
+        slice?: string;
+        /**
+         * ⚠ FU-17 — whether this delegation is WORK or a REVIEW. It changes two things and nothing else: the slice
+         * (when `slice` is passed) and the `Purpose` line of the action record, so a reader of the run can tell a
+         * child that produced something from a child that judged something.
+         */
+        kind?: 'review' | 'work';
+        /**
+         * T35: which child lifecycle to use. DEFAULT `continuable` — a one-shot
+         * child cannot be resumed, so one-shot forfeits the repair path and must be
+         * requested explicitly by a caller that will discard the result.
+         */
+        /**
+         * ⚠ FU-18 — IS THIS ROUND A CONTINUATION OF AN OPEN DELEGATION RATHER THAN A FRESH ONE?
+         *
+         * Set by a caller that is resuming the same child to deliver FEEDBACK. It is the difference between "run this
+         * operation again", which the T19 guard exists to refuse, and "carry on with the operation that is already
+         * open", which the guard must not refuse — see the guard below for why the obvious alternative is worse.
+         */
+        continuing?: boolean;
+        /**
+         * ⚠ FU-19 — A PER-CALL CHOICE, which is what "change them on demand" means. Both win over every configured
+         * level, and both are optional: absent means "resolve the ladder", NOT "clear".
+         */
+        providerOverride?: string | null;
+        modelOverride?: string | null;
         mode?: 'one-shot' | 'continuable';
         awaitRoundResult?: (childId: ContinuableChildId, messageId: ContinuableMessageId) => Promise<SubagentResultLike | null>;
+        /**
+         * T39: interrupt the LIVE child when this delegation's job is killed — the one thing T10's
+         * synchronous call sites cannot do, and the reason a delegation's kill can be genuinely
+         * pre-emptive. Optional: without it a kill still parks the round and cannot reach the
+         * child, which is stated rather than implied.
+         */
+        interrupt?: (childId: string, reason: string) => void;
         maxRounds?: number;
         /** T4: the exact live direct-parent Agent (object-identity authority). */
         parent?: SubagentParentHandle;
@@ -235,12 +457,28 @@ export declare class RecursiveRuntime extends Service {
             accepted: boolean;
             reason: string;
         };
+        /** T9: routing decisions that could NOT be applied, so a caller is told rather than left to infer. */
+        routingNotes: string[];
         actionRecordPath: string;
         error: string | null;
+        /** T35: which child lifecycle actually carried this delegation. */
+        delegationMode: "none" | "one-shot" | "continuable" | "continuable-unavailable";
+        /** T19: the deterministic id of this review, persisted so a restart can match it. */
+        operationId: string;
+        /**
+         * T36: true when the round has NOT settled yet, so the caller resumes with
+         * `continuable.childId` on a later turn. `parkedReason` carries the loop's own
+         * sentence ("the child is still working") without it being an `error`.
+         */
+        parked: boolean;
+        parkedReason: string | null;
         continuable: {
             rounds: import("./delegation.ts").ContinuableRoundLike[];
             childId: string | undefined;
             fellBackToOneShot: boolean | undefined;
+            parked: boolean;
+            ok: boolean;
+            reason: string | undefined;
         } | null;
     }>;
     /** R6: validate a child's claimed references against actual files. */
@@ -283,7 +521,7 @@ export declare class RecursiveRuntime extends Service {
                 cwd?: string;
             };
         };
-    } | null): Promise<RecursiveStatusResult | null>;
+    } | null): Promise<RecursiveStatusWithGuardDecisions | null>;
     /**
      * LIVE BUG 6 refined: structured phase rules for the CURRENT phase. Resolves
      * the workspace root (same as status/lock), finds the latest run (or the
@@ -297,9 +535,11 @@ export declare class RecursiveRuntime extends Service {
                 cwd?: string;
             };
         };
-    } | null): Promise<(PhaseRules & {
+    } | null, files?: readonly string[]): Promise<(PhaseRules & {
         runId: string;
         phase: string;
+        memory: string;
+        memoryReason: string;
     }) | null>;
     /**
      * Scaffold a run directory with FULL per-phase templates (no-op if exists).

package/lib/settlement.d.ts

@@ -0,0 +1,132 @@
+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;
+}
+/**
+ * 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 declare function settlementFromEvent(event: SessionEventLike): SettlementNotice | null;
+/** The run-scoped append-only settlement log. */
+export declare function settlementLogPath(runDir: string): string;
+/**
+ * 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 declare function runDirForChild(root: string, childId: string): string | 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 declare function recordSettlement(runDir: string, notice: SettlementNotice): string;
+/** 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 declare function adoptSettlement(root: string, notice: SettlementNotice): string | null;
+export declare function readSettlements(runDir: string): SettlementNotice[];
+/** The LATEST recorded settlement for one child, or null when none has landed. */
+export declare function readSettlement(runDir: string, childId: string): SettlementNotice | null;
+/**
+ * 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 declare function settlementResult(notice: SettlementNotice): SubagentResultLike;
+/**
+ * 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 declare function settlementRoundObserver(runDir: string, options?: {
+    timeoutMs?: number;
+    pollMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}): (childId: ContinuableChildId, messageId: ContinuableMessageId) => Promise<SubagentResultLike | null>;
+/**
+ * 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 declare function captureSettlement(runDir: string, event: SessionEventLike): SettlementNotice | null;
+/**
+ * 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 declare function runChildIds(runDir: string): string[];

package/lib/skills-phase.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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 { type PhaseRules } from './phase-rules.ts';
+/** The prefix every phase skill carries, so the plugin's contributions are recognisable. */
+export declare 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 declare function phaseSkillName(fileName: string): string;
+/** Build the registration for one phase. Pure, so the mapping is testable without a registry. */
+export declare function phaseSkillRegistration(rules: PhaseRules): PhaseSkillRegistration;
+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 declare function registerPhaseSkills(skills: SkillRegistryLike | null | undefined, fileNames: readonly string[], workflowProfile?: string): PhaseSkillRegistrationResult;
+/**
+ * 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 declare function describePhaseSkills(result: PhaseSkillRegistrationResult): string;

package/lib/skills.d.ts

@@ -0,0 +1,70 @@
+import type { Context } from '@deepseek-ai/cordis';
+/** 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;
+}
+/**
+ * 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 declare function registerRecursiveSkill(ctx: Context): (() => void) | undefined;