@try-works/dsh-recursive-mode 0.4.2 → 0.4.4

package/README.md

@@ -7,10 +7,10 @@ plans, plans before code, independent review before a lock, tests before a claim
 that says who locked it and on what evidence. The discipline lives in the harness, not in a prompt, so it cannot
 be skipped by an agent that is in a hurry.
 
-- **12 tools** on the agent surface, one slash command, a workspace control plane, and a memory plane that
+- **13 tools** on the agent surface, one slash command, a workspace control plane, and a memory plane that
   learns from what actually got used.
 - **Zero runtime dependencies** beyond the harness itself — everything is a structural seam.
-- **862 tests across 91 files**, three parity specs against the reference implementation, a live-session
+- **A full test suite**, three parity specs against the reference implementation, a live-session
   harness, and a fresh-clone check that runs unattended.
 
 > **Honest status, up front.** One capability in this repository is **implemented but NOT VERIFIED live**: the
@@ -117,7 +117,7 @@ flowchart TB
         LOCK["lock.ts<br/>monotonic locks + receipts"]
         DELEG["delegation.ts + router.ts<br/>who reviews"]
         MEM["memory*.ts<br/>what gets injected"]
-        TOOLSET["12 recursive_* tools"]
+        TOOLSET["13 recursive_* tools"]
     end
 
     subgraph disk["Workspace control plane (.recursive/)"]
@@ -164,7 +164,7 @@ control plane on disk is the only state it trusts across restarts.
 
 ## 4. Capabilities
 
-### 4.1 The twelve tools
+### 4.1 The thirteen tools
 
 | Tool | What it does |
 |---|---|
@@ -173,11 +173,12 @@ control plane on disk is the only state it trusts across restarts.
 | `recursive_lock` | Lock a phase — refuses if the artifact does not meet the standard |
 | `recursive_lint` | Lint a run or an artifact against the phase standard, with remediation text |
 | `recursive_closeout` | Report what a phase artifact is missing; **writes a receipt, never the artifact** |
-| `recursive_phase` | Read the phase graph: what is required, what is next, what is blocked |
-| `recursive_worktree` | Create/promote a git worktree for a run, so work is isolated |
 | `recursive_scratch` | The child's scratch space: durable, per-run working notes |
-| `recursive_review` | **Independent review** of the phase artifact, with a repair path |
+| `recursive_worktree` | Create/promote a git worktree for a run, so work is isolated |
+| `recursive_phase` | Read the phase graph: what is required, what is next, what is blocked |
 | `recursive_audit_team` | Fan a phase out across roles (audit) |
+| `recursive_review` | **Independent review** of the phase artifact, with a repair path |
+| `recursive_delegate` | **Delegate the work of a phase** to a durable child; it produces, you judge |
 | `recursive_ask` | Ask the workspace a question, with the control plane as context |
 | `recursive_preview` | Preview what a tool would do, without doing it |
 
@@ -434,6 +435,10 @@ flowchart TB
     P035 ==>|"the review phase"| REV
     P08 -.->|"memory-auditor role"| REV
 
+    DELEG["recursive_delegate(phase)<br/>the phase's WORK, handed to a durable child<br/>the child produces · the main agent judges"]
+    P01 -.->|"work delegation, in any phase"| DELEG
+    P03 -.->|"the phase's actual work"| DELEG
+
     TEAM["recursive_audit_team<br/>one phase per ROLE, one item per reviewer"]
     P01 -.-> TEAM
     P02 -.-> TEAM
@@ -500,7 +505,7 @@ progress reads as a per-phase per-role review rather than an undifferentiated pi
 > phase's skill carries `audited: yes — this phase needs a delegated audit` or `audited: no`
 > (`skills-phase.ts`), so the expectation is stated per phase rather than implied.
 >
-> **Two delegation paths exist, and they are different animals.** The workflow's own — `recursive_review`,
+> **Three delegation paths exist, and they are different animals.** `recursive_delegate` hands the *work itself* to a durable child and the main agent judges what comes back; `recursive_review` asks for an *independent judgement* and carries a repair leg; `recursive_audit_team` fans a phase out across roles. The first produces, the second judges, the third multiplies. The workflow's own — `recursive_review`,
 > `recursive_audit_team` — is phase-aware and writes evidence **into the run** (brief, reply, action record,
 > settlement), which is what makes the per-phase contract checkable. The harness's generic subagent and team
 > tools are always available and know nothing about phases; work delegated through those leaves no run-scoped
@@ -717,7 +722,7 @@ The plugin ships **two halves that mount in different planes**, and knowing whic
 | Half | Artifact | Plane | What it carries |
 |---|---|---|---|
 | **Bundle** | `cordis.patch.yml` (declared as `dsh.bundle.patch`) | **profile** | one enabled row so the host's ClientModuleRegistry can discover the UI half |
-| **Agent preset** | `preset/recursive/agent.cordis.yml` + `preset/recursive/preset.yml` | **agent plane** | **the entire server surface**: the `RecursiveRuntime` service, the twelve tools, `/recursive`, the policy prompt section |
+| **Agent preset** | `preset/recursive/agent.cordis.yml` + `preset/recursive/preset.yml` | **agent plane** | **the entire server surface**: the `RecursiveRuntime` service, the thirteen tools, `/recursive`, the policy prompt section |
 
 ```mermaid
 flowchart TB
@@ -739,7 +744,7 @@ flowchart TB
         SEL["session selects the recursive preset<br/>registered by the bundle row"]
         STD["the standard coding agent surface<br/>+ tool-presentation mode: both"]
         REALM["group recursive-realm<br/>isolate: true"]
-        SURF["RecursiveRuntime + 12 tools<br/>+ /recursive + recursive:policy"]
+        SURF["RecursiveRuntime + 13 tools<br/>+ /recursive + recursive:policy"]
         SEL --> STD
         SEL --> REALM --> SURF
     end
@@ -887,11 +892,11 @@ surface arrives when a session opts into the `recursive` preset. See
 
 | Claim | How it is established |
 |---|---|
-| The workflow's own rules hold | `pnpm test` — **862 tests, 91 files**, including three **parity specs** (lock, status, lint) against the reference implementation |
+| The workflow's own rules hold | `pnpm test` — the whole suite, including three **parity specs** (lock, status, lint) against the reference implementation |
 | The tree is sound | `pnpm typecheck` (0 errors), `pnpm build` (0) |
-| The docs match the code | `docs-contract.spec.ts` — 15 tests asserting documented paths, tools, and sections exist |
+| The docs match the code | `docs-contract.spec.ts` — asserts that documented paths, tools, sections and the README tool table all match the code |
 | The plugin runs under a real harness | `pnpm e2e` — the FU-1 harness, **10/10**, including the behaviour test where removing one shard changes what the agent is told |
-| A fresh checkout works unattended | `git clone` → `pnpm install` → **862/862**, verified in the closing sweep |
+| A fresh checkout works unattended | `git clone` → `pnpm install` → **the suite passes**, verified in the closing sweep |
 | The plugin runs in a real CLI session | `scripts/live-session-plugin.mjs` — headless CLI, temp HOME, scripted LLM; the run reaches the review tool and the control plane is written |
 | Memory actually reaches the model | the P5 harness test, end to end |
 | The guard refuses locked writes | enforcement specs plus the live probe that found the overwrite defect |
@@ -927,7 +932,7 @@ unverified.**
 | The guard | `enforcement.ts`, `policy-globs.ts`, `fs-intent.ts`, `guard-log.ts`, `errors.ts` |
 | Delegation & review | `delegation.ts`, `router.ts`, `role-route.ts`, `review.ts`, `review-round.ts`, `settlement.ts`, `handoff.ts`, `teams-loop.ts`, `live-route.ts` |
 | Memory | `memory.ts`, `memory-select.ts`, `memory-feedback.ts` |
-| Surfaces | `recursive_*.tool.ts` (12), `commands.ts`, `hooks.ts`, `status.ts` |
+| Surfaces | `recursive_*.tool.ts` (13), `commands.ts`, `hooks.ts`, `status.ts` |
 | Infrastructure | `jobs-runner.ts`, `job-log.ts`, `goals-projection.ts`, `lifecycle.ts`, `bootstrap.ts`, `init-templates.ts`, `worktree.ts`, `git-context.ts`, `scratch.ts`, `skills.ts`, `skills-phase.ts`, `training.ts`, `workflow-audit.ts`, `plan-gate.ts`, `result-cap.ts`, `json-safe.ts`, `identity.ts`, `policy.ts` |
 
 **Documents:**
@@ -954,6 +959,6 @@ pointer files a workspace gets), `scripts/` (harness, e2e, live-session, install
 sections, monotonic locks with receipts, a guard that refuses writes to locked artifacts, an independent review
 routed to whichever provider is actually available, a memory plane whose scoring is printed on demand, and a
 closeout that lints the whole run and writes a receipt instead of touching the agent's work. It is verified by
-862 tests, three parity specs against the reference implementation, a live-session harness, and an unattended
+a full test suite, three parity specs against the reference implementation, a live-session harness, and an unattended
 fresh-clone check — and it reports the one capability it has not managed to prove live, with the host-side
 reason, rather than describing it as working.

package/lib/client/index.d.ts

@@ -16,7 +16,9 @@ export { Board, listRuns } from './board.tsx';
 export { Inspector } from './inspector.tsx';
 export { DocViewer, parseDoc, parseInline } from './doc-viewer.tsx';
 export { RecursiveView } from './slots.ts';
-export { RecursiveSettings } from './settings.tsx';
+export { RecursiveSettings, RecursiveSettingsLive } from './settings.tsx';
+export { settingsView } from './settings-view.ts';
+export type { SettingsView, SettingsRunView, SettingsRow } from './settings-view.ts';
 export { useLiveProjection } from './use-live.ts';
 export type { LiveProjectionSnapshot } from './use-live.ts';
 export { fetchLiveState, subscribeLiveEvents } from './host-api.ts';

package/lib/client/settings-view.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Pure display model for the Recursive settings panel (read-only report).
+ *
+ * WHY THIS MODULE EXISTS. The old panel rendered one sentence and no values — it
+ * claimed to report the host's configuration while reporting nothing. The data
+ * was already arriving: `host-api.ts` serves {root, projection, revision} on
+ * every fs change plus a 15s heartbeat, and `derive.ts` already derives board
+ * facts from the same projection. This module adds no data path; it is the same
+ * projection read for a different surface, and it is PURE (no React, no fs, no
+ * session window — the read-only-client + projection-over-files invariant, §11.9).
+ *
+ * THE ABSENCE RULE (`text()` + `SettingsRow.value === null`): a value is printed
+ * only when the projection carried it. A missing/blank value renders as
+ * `not reported` — never an empty row and never a plausible default. Note that
+ * `derive.cardFacts()` deliberately defaults a subagent's absent `status` to
+ * 'done'; this model does NOT, because a report that invents "done" is a report
+ * that lies. Required collection fields (`tampers`, `subagents`) that are present
+ * but empty print `none` — that IS their value; fields the card omits print
+ * `not reported`.
+ */
+import type { PhasePosition, RecursiveRunCard } from '../types.ts';
+import type { LiveProjectionValue } from './contract.ts';
+import { type PillKind } from './derive.ts';
+/** A label/value line. `value === null` means the projection carried NO value. */
+export interface SettingsRow {
+    id: string;
+    label: string;
+    value: string | null;
+}
+/** One folded phase row, with the T21 single derived position printed verbatim. */
+export interface SettingsPhaseRow {
+    phase: string;
+    /** The phase doc filename, or null for a slot this run does not have (03.5). */
+    fileName: string | null;
+    /** The raw folded status ('LOCKED' / 'DRAFT' / '—'). */
+    status: string;
+    /** T21 single derived position; null when the producer carried none. */
+    position: PhasePosition | null;
+    lockedAt: string | null;
+    lockHash: string | null;
+    present: boolean;
+    pill: PillKind;
+}
+/** One subagent record: role/provider exactly as the host fold recorded them. */
+export interface SettingsSubagentRow {
+    childId: string;
+    role: string | null;
+    provider: string | null;
+    status: string | null;
+}
+/** One unresolved in-flight work item (T18). */
+export interface SettingsPendingRow {
+    kind: string;
+    delegationId: string;
+    detail: string;
+}
+/** One run's report. */
+export interface SettingsRunView {
+    runId: string;
+    worktreeRoot: string;
+    state: string;
+    pill: PillKind;
+    /** Scalar facts; a null value means the card did not carry that field. */
+    rows: SettingsRow[];
+    phases: SettingsPhaseRow[];
+    /** null when the card carried no `subagents` key; [] when it carried an empty one. */
+    subagents: SettingsSubagentRow[] | null;
+    /** null when the card carried no `pendingWork` key; [] when it carried an empty one. */
+    pendingWork: SettingsPendingRow[] | null;
+}
+/** Whether the route has answered, and whether it resolved a recursive root. */
+export type SettingsStatus = 'no-frame' | 'no-root' | 'connected';
+/** The whole panel model. */
+export interface SettingsView {
+    status: SettingsStatus;
+    root: string | null;
+    revision: number | null;
+    runs: SettingsRunView[];
+    /**
+     * Route-level facts the payload does not carry AT ALL — the panel names them
+     * so a reader is never left to assume the client is hiding them.
+     */
+    notCarried: SettingsRow[];
+}
+/**
+ * The `/state` payload is {root, projection, revision} (host-api.ts /
+ * live-route.ts, both typed by LiveProjectionValue). Nothing else rides it, so
+ * anything else is reported as not carried rather than guessed.
+ */
+export declare const NOT_CARRIED: readonly SettingsRow[];
+/** One run card -> its report. */
+export declare function settingsRunView(card: RecursiveRunCard): SettingsRunView;
+/**
+ * The panel model for one live snapshot (null = the route has not answered yet).
+ * Every run in the projection is reported; nothing is filtered or defaulted.
+ */
+export declare function settingsView(snapshot: LiveProjectionValue | null): SettingsView;

package/lib/client/settings.d.ts

@@ -1,6 +1,30 @@
+import { type LiveProjectionValue, type SessionListStateLike, type SnapshotSelectorHook, type WorkspaceListStateLike } from './contract.ts';
+/** Rendered in place of every value the projection did not carry. */
+export declare const ABSENT_LABEL = "not reported";
 export interface RecursiveSettingsProps {
     close: () => void;
+    /** The live host-route frame, or null while the first fetch is in flight. */
+    snapshot?: LiveProjectionValue | null;
 }
-export declare function RecursiveSettings({ close }: RecursiveSettingsProps): import("react").DetailedReactHTMLElement<{
+/** The panel: a report of one live frame. Pure — snapshot in, tree out. */
+export declare function RecursiveSettings({ close, snapshot }: RecursiveSettingsProps): import("react").DetailedReactHTMLElement<{
     className: string;
 }, HTMLElement>;
+/** The settings seat props: the root standard kit plus the shell's close affordance. */
+export interface RecursiveSettingsSeatProps {
+    close: () => void;
+    useSessions?: SnapshotSelectorHook<SessionListStateLike>;
+    useWorkspaces?: SnapshotSelectorHook<WorkspaceListStateLike>;
+}
+export interface RecursiveSettingsLiveProps {
+    close: () => void;
+    useSessions: SnapshotSelectorHook<SessionListStateLike>;
+    useWorkspaces: SnapshotSelectorHook<WorkspaceListStateLike>;
+}
+/**
+ * The live seat: same scope resolution as the board seats (sessionId PRIMARY,
+ * workspace path as the cwd hint, session cwd while workspaces hydrate). Hooks
+ * are called unconditionally — the seat only renders this component when both
+ * selector hooks are present (slots.ts), so the hook order is fixed.
+ */
+export declare function RecursiveSettingsLive({ close, useSessions, useWorkspaces }: RecursiveSettingsLiveProps): import("react").FunctionComponentElement<RecursiveSettingsProps>;