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

package/lib/phase-graph.d.ts

@@ -0,0 +1,111 @@
+/**
+ * T17 — the phase dependency as a GRAPH, not a flat sequence.
+ *
+ * WHY. Three core queries in this plugin are graph operations being run over a linear array:
+ * `getStaleDownstreamPhases` is a REACHABILITY query, `getPrerequisites` is an IN-EDGE query, and
+ * `getNextLegalPhase` is a topological walk. An array can answer all three only while the dependency
+ * happens to be linear — and the moment an artifact depends on something LATER than itself (an
+ * addendum written to close an upstream gap), the array model answers *wrongly* rather than not at
+ * all. That is the case this module exists to get right.
+ *
+ * ⚠ A HAND-ROLLED GRAPH, DELIBERATELY. The item's note is explicit: Effect ships a stable,
+ * runtime-free `Graph` doing exactly this, and adopting it would trade this plugin's zero-dependency
+ * posture and its parity goldens for a few hundred lines it does not need. The queries below are
+ * small because the graph is small.
+ *
+ * ⚠ BACK-EDGES ARE FIRST-CLASS, NOT AN ERROR. An `upstream-gap` addendum legitimately points at a
+ * LATER artifact: the gap was discovered downstream and must be closed upstream. A depth-first walk
+ * with a VISITED set answers reachability over such a graph; a walk without one loops forever, and an
+ * array cannot express the edge at all.
+ */
+/** One node: an artifact on disk, or one being asked about before it exists. */
+export interface PhaseNode {
+    /** Artifact file name, the node's identity. */
+    id: string;
+    /** Position in the canonical sequence — used for ordering, NOT as the dependency model. */
+    index: number;
+    /** Whether the artifact is on disk. A queried, absent node emits no prerequisite edge. */
+    present?: boolean;
+    /** Whether the artifact is locked, when the caller knows. */
+    locked?: boolean;
+}
+/** One directed edge: `to` depends on `from`. */
+export interface PhaseEdge {
+    from: string;
+    to: string;
+    /** `prerequisite` — an earlier artifact that must be locked first. `addendum` — a cited dependency. */
+    kind: 'prerequisite' | 'addendum';
+}
+export interface PhaseGraph {
+    nodes: PhaseNode[];
+    edges: PhaseEdge[];
+}
+/**
+ * Build the graph for one run.
+ *
+ * `sequence` is the canonical phase order; `present` is what exists on disk, so a phase that was
+ * never created is not a node and cannot be waited on forever. `addenda` are the cited dependencies a
+ * document declares — including ones pointing FORWARD, which is what makes the graph a graph.
+ */
+export declare function buildPhaseGraph(input: {
+    sequence: readonly string[];
+    present: readonly string[];
+    locked?: readonly string[];
+    /** Declared dependencies: `from` must be settled before `to`. Order is irrelevant. */
+    citations?: ReadonlyArray<{
+        from: string;
+        to: string;
+    }>;
+    /**
+     * Artifacts to answer ABOUT, whether or not they exist yet.
+     *
+     * ⚠ THIS EXISTS BECAUSE OF A MEASURED PARITY FAILURE, and it is the item's central modelling gap:
+     * with nodes limited to what is present, a query about an artifact **that does not exist yet**
+     * found no in-edges and answered `[]` — but checking prerequisites **before creating** the artifact
+     * is the NORMAL case, so that made every pre-write check silently vacuous. A queried node is
+     * therefore a node for EDGE TARGETS ONLY: it emits no outgoing prerequisite edge, because an
+     * artifact that does not exist cannot block anything.
+     */
+    queried?: readonly string[];
+}): PhaseGraph;
+/** The nodes that must be settled before `id` — the IN-EDGE query. */
+export declare function prerequisitesOf(graph: PhaseGraph, id: string): string[];
+/** The artifacts that depend, directly, on `id` — the OUT-EDGE query. */
+export declare function dependentsOf(graph: PhaseGraph, id: string): string[];
+/**
+ * Everything reachable downstream of `id` — the REACHABILITY query behind `getStaleDownstreamPhases`.
+ *
+ * ⚠ The VISITED set is load-bearing, not defensive: a back-edge makes the graph cyclic, and a walk
+ * without a visited set recurses forever on exactly the input this item exists to support.
+ */
+export declare function reachableFrom(graph: PhaseGraph, id: string): string[];
+/**
+ * The next phase a run may work on.
+ *
+ * ⚠ THIS MODELS THE SHIPPED RULES EXACTLY, because `lock.ts` delegates to it and `lock.parity.spec.ts`
+ * is the proof. Three of them are easy to miss and are asserted in the spec:
+ *   1. a LOCKED node is skipped;
+ *   2. a node that is **absent and declared OPTIONAL** is skipped — an optional phase nobody created
+ *      must not stop the run;
+ *   3. if the first node that survives 1 and 2 has a prerequisite that is not LOCKED, the answer is
+ *      **`null`, NOT the next node** — the run is BLOCKED, and returning the node after it would
+ *      silently skip a dependency.
+ *
+ * ⚠ RULE 3 IS WHERE A GRAPH EARNS ITS KEEP, and it is invisible in a linear array: with a back-edge
+ * (an `upstream-gap` addendum citing a LATER artifact), an EARLY unlocked node can be blocked by a
+ * LATER one — so "continue to the next node" and "blocked, report null" give different answers, and
+ * only the second is correct.
+ *
+ * Nodes must cover the whole sequence for this query (an absent, required phase is a legitimate
+ * answer); `queried` is how the caller supplies them.
+ */
+export declare function nextLegalPhase(graph: PhaseGraph, options?: {
+    optional?: ReadonlySet<string>;
+}): string | null;
+/**
+ * Whether the graph has a back-edge — an edge pointing at a LATER phase than its source.
+ *
+ * Reported rather than hidden: a back-edge is legitimate (an upstream gap), and it is exactly the
+ * shape a linear model cannot represent. A caller that wants to warn about it should be able to ask.
+ */
+export declare function backEdges(graph: PhaseGraph): PhaseEdge[];

package/lib/phase-rules.d.ts

@@ -1,11 +1,4 @@
-/**
- * Phase rules (R5): canonical parity port of lint-recursive-run.py's
- * get_artifact_required_sections + workflow/audit constants. Single source of
- * truth for per-phase required section headings and audit extras; consumed by
- * initRun templates, renderRecursivePolicy, and the pre-step lint-rules
- * injection. Values are byte-identical to the canonical linter (recursive-
- * mode-audit-v2).
- */
+import { tddEvidenceVerdict as tddEvidenceMatch, type ToolPolicy, type ToolPolicyRule, type Verdict } from './policy-globs.ts';
 export declare const CURRENT_WORKFLOW_PROFILE = "recursive-mode-audit-v2";
 export declare const STRICT_WORKFLOW_PROFILE = "recursive-mode-audit-v1";
 export declare const COMPAT_WORKFLOW_PROFILE = "memory-phase8";
@@ -57,3 +50,69 @@ export declare function phaseRulesFor(fileName: string, workflowProfile?: string
  * from the prior inline build so r5-parity.spec.ts stays green.
  */
 export declare function phaseLintRulesMessage(fileName: string, workflowProfile?: string): string;
+export declare function policyVerdictRank(verdict: Verdict): number;
+/**
+ * The phase number an artifact belongs to: the leading digits of its canonical
+ * filename (`03-implementation-summary.md` -> `3`). Returns `''` when the
+ * filename carries no phase number, so a caller can skip the baseline rather
+ * than guess.
+ */
+export declare function phaseNumberForArtifact(fileName: string): string;
+/**
+ * PER-PHASE BASELINE (plan §4 T16). Additive, phase-scoped rules that can only
+ * NARROW the global policy. Three honest limits, stated here rather than hidden:
+ *
+ *   1. The two structures the plan names — phase 6 "writes only under
+ *      `.recursive/DECISIONS.md`" and phase 8 "only under `.recursive/memory/**`"
+ *      — as ABSOLUTE path scopes would also forbid the normal artifact edits of
+ *      those phases, so they are implemented as the narrower rules that bite
+ *      without blocking the phase's own work: no source-tree writes in phases
+ *      6-8 (by then the repo changes are done and the run documents its
+ *      decisions/state/memory), and the memory planes are read-only in phases
+ *      1-2 and 6-7. `deny` on `write` in phase 6 is also deliberately absent,
+ *      because phase 6's own artifact is `<run>/06-decisions-update.md` and a
+ *      blanket write denial would make the phase uncompletable.
+ *   2. Narrowing is enforced MECHANICALLY in withPhaseBaseline, not by trusting
+ *      this table: a phase rule whose verdict is ranked above the strictest
+ *      global verdict for the same pattern — which would widen `ask` to `allow`,
+ *      or soften a global `deny` — is DROPPED before it can be evaluated.
+ *   3. No rule below uses the bare catch-all `*`. A phase rule of that shape
+ *      would outrank every specific global rule at once (precedence is
+ *      specificity-first), including `recursive_lock*`, and would deny the phase
+ *      its own tools. The write-tool family is spelled `write*`.
+ *
+ * Phase 3's TDD-evidence rule is the one the plan states verbatim: a phase-3
+ * lock is denied until RED + GREEN evidence exists. It is reached for the phase
+ * whose artifact is the current one, i.e. the phase-3 lock itself — before that
+ * point the earlier phases are still unlocked, so the global lock-order rule
+ * already refuses.
+ */
+export declare function phaseBaselineRules(fileName: string): ToolPolicyRule[];
+/**
+ * Resolve a tool-target path to an absolute path. Mirrors enforcement.ts's
+ * resolution rules: an absolute path stays as it is; a relative path resolves
+ * against the worktree root. `null` when the value cannot be a path at all.
+ */
+export declare function resolveFrom(worktreeRoot: string, target: string): string | null;
+/** The tool-target path of a call (same key order enforcement.ts uses). */
+export declare function policyTargetPath(args: Record<string, unknown>): string | null;
+/**
+ * TDD evidence predicate for a phase-3 lock: `deny` when the artifact declares
+ * `TDD Mode: strict` without both RED and GREEN evidence, `null` otherwise
+ * (nothing to say — the global rules still apply). Lives in `policy-globs.ts`
+ * beside the built-in list, which carries the same `tdd-evidence` guard rule.
+ */
+export declare const tddEvidenceVerdict: typeof tddEvidenceMatch;
+/**
+ * Compose the effective policy for a phase: the phase baseline rules FIRST (so
+ * a narrowing rule is reached before the global rule it tightens), then the
+ * global rules.
+ *
+ * NARROWING IS MECHANICAL, not a convention this table is trusted to respect. A
+ * baseline rule whose verdict is ranked ABOVE the strictest global verdict for
+ * the same pattern is DROPPED before it can be evaluated, so no per-phase
+ * baseline can turn a global `deny` into an `allow` (or an `ask` into an
+ * `allow`). A baseline rule for a pattern the global policy does not mention is
+ * always kept: it can only add a restriction.
+ */
+export declare function withPhaseBaseline(policy: ToolPolicy, fileName: string, runDir?: string): ToolPolicy;

package/lib/plan-gate.d.ts

@@ -0,0 +1,68 @@
+/**
+ * T13 — planMode for the discovery phases, and the gate out of them.
+ *
+ * WHY. Requirements / AS-IS / TO-BE-Plan are NON-MUTATING discovery. Running them under the
+ * harness's planMode enforces "plan before implement" at the harness level instead of by
+ * convention: a phase that cannot write cannot quietly start implementing while it is still
+ * deciding what to implement. Convention is what fails at 2am; a mode is what holds.
+ *
+ * ⚠ THE PHASE-FORM TRAP, which is why this module exists rather than a one-line comparison.
+ * This codebase names a phase THREE ways — `'2'`, `'02'`, and the artifact filename
+ * `'02-to-be-plan.md'` — and a mapping that understood only one of them would return `false`
+ * for the others. That failure is SILENT and in the dangerous direction: it turns the
+ * non-mutating guarantee OFF for exactly the phases that need it. So the index is parsed from
+ * the leading numeric run, and every form lands on the same answer.
+ *
+ * ⚠ AN UNRECOGNISED PHASE ANSWERS `false`, deliberately. Claiming plan mode for a phase we
+ * cannot identify would be guessing about the one property this module exists to guarantee;
+ * the safe reading of "I do not know what this is" is "do not assert a mode about it". The
+ * caller that needs certainty has {@link phaseIndexOf} and can refuse instead.
+ */
+/**
+ * The numeric index of a phase, from any of the forms this codebase uses, or `null` when the
+ * input names no phase at all.
+ *
+ * Takes the leading numeric run, so `'2'`, `'02'`, `' 2 '` and `'02-to-be-plan.md'` all give
+ * `2`, and `'01.5-root-cause.md'` gives `1.5` — the fractional sub-phase keeps its position
+ * between 01 and 02, which is what makes `phaseUsesPlanMode` include it.
+ */
+export declare function phaseIndexOf(phase: string): number | null;
+/**
+ * The exclusive upper bound of the discovery block: phases below this are non-mutating.
+ *
+ * 3 = implementation. Everything strictly below it (0 requirements, 1 AS-IS, 1.5 root cause,
+ * 2 TO-BE plan) is discovery, which is the item's "00-02" plus the sub-phase that sits inside
+ * that range.
+ */
+export declare const IMPLEMENTATION_PHASE_INDEX = 3;
+/** True when the phase is discovery and must run non-mutating. */
+export declare function phaseUsesPlanMode(phase: string): boolean;
+/**
+ * True when a transition LEAVES the discovery block — the plan gate.
+ *
+ * The gate is on the DESTINATION, not the distance: `02 -> 03` and `02 -> 04` both need an
+ * approved plan, because skipping ahead does not make the plan less necessary. A transition
+ * that stays inside discovery (0 -> 1) is not gated, and one that starts after the boundary
+ * (3 -> 4) is not either — the plan was already required to get there.
+ */
+export declare function planGateRequired(from: string, to: string): boolean;
+/** A one-line, board-facing statement of what the phase owes, for a phase rules section. */
+export declare function describePlanMode(phase: string): string;
+/**
+ * T13 — should `exit_plan_mode` be allowed, given the phase the run is WAITING on?
+ *
+ * The run's "next legal phase" is exactly the right input: while it is still a discovery
+ * phase, the plan is not finished and leaving plan mode would start implementing on an
+ * unfinished plan; once it is an implementation phase, discovery is done and the gate is
+ * open. So the gate needs no separate state — it reads the state the run already keeps, and
+ * that is why it cannot drift from the workflow.
+ *
+ * ⚠ A NULL next phase means "nothing is pending", which is NOT the same as "discovery is
+ * done". It allows the exit, because refusing forever on a completed or unrecognised run
+ * would make plan mode a trap rather than a gate — and the reason is stated so a reader can
+ * tell the two cases apart.
+ */
+export declare function planGateForExit(nextPhase: string | null): {
+    allow: boolean;
+    reason: string;
+};

package/lib/policy-globs.d.ts

@@ -0,0 +1,222 @@
+/** The three verdicts a rule may carry. */
+export type Verdict = 'allow' | 'deny' | 'ask';
+/**
+ * The policy engine's own decision shape (no `warn`/`transition` — those are the
+ * guard's, see enforcement.ts). `rule` is the `label` of the rule that decided
+ * the call, so a verdict is traceable to an auditable line in the policy file;
+ * it is absent when the no-match default decided.
+ */
+export interface Decision {
+    kind: Verdict;
+    reason?: string;
+    rule?: string;
+}
+/**
+ * Extra facts a rule predicate may need. `args` is always the tool call's
+ * arguments; the run coordinates are present only when the caller has them
+ * (a guard call from a real session does; a pure policy unit test need not).
+ */
+export interface ToolPolicyContext {
+    args: Record<string, unknown>;
+    runDir?: string;
+    runId?: string;
+    worktreeRoot?: string;
+}
+/**
+ * What a rule predicate returns when the condition it guards DOES apply:
+ * the verdict, plus an optional `detail` appended to the rule's own `reason`.
+ * The rule keeps the static, auditable sentence (the same sentence the policy
+ * file and the built-in list carry, so the two cannot drift); the predicate adds
+ * only the per-call particular — which artifact blocked the lock, and its status.
+ *
+ * `null` means the condition does NOT apply, and the engine falls through to the
+ * NEXT rule. That fall-through is how an id-glob rule such as `write` can guard
+ * write tools without deciding for an ordinary write that violates nothing
+ * (which a bare pattern match would otherwise deny).
+ */
+export interface ToolPolicyPredicateMatch {
+    verdict: Verdict;
+    detail?: string;
+}
+export type ToolPolicyPredicate = (id: string, args: Record<string, unknown>, ctx: ToolPolicyContext) => ToolPolicyPredicateMatch | null;
+export interface ToolPolicyRule {
+    pattern: string;
+    verdict: Verdict;
+    reason: string;
+    /** The guard's machine-readable rule label for a decision this rule makes. */
+    label?: string;
+    predicate?: ToolPolicyPredicate;
+}
+/**
+ * The `defaults` block of a policy file. `no_match_verdict` is documented for a
+ * human reader and may only ever be `"ask"`: the no-match default is a property
+ * of the engine, not a knob, because a configurable one would let a policy file
+ * silently allow (or deny) every unlisted tool.
+ */
+export interface ToolPolicyFileDefaults {
+    no_match_verdict?: 'ask';
+}
+export interface ToolPolicy {
+    version: number;
+    description?: string;
+    rules: ToolPolicyRule[];
+}
+/** Where the shipped default policy lives, relative to the worktree root. */
+export declare const TOOL_POLICY_RELATIVE_PATH = ".recursive/config/recursive-permissions.json";
+/** Absolute path of the policy file for a worktree. */
+export declare function toolPolicyPath(worktreeRoot: string): string;
+/**
+ * The syntax error in `pattern`, or null when it is well formed.
+ *
+ * Beyond the character rule there are two STRUCTURAL rules, because a pattern
+ * that a human reads as "the worker tools" must not be a silent no-op:
+ *   - a pattern may not END with a separator (`worker::`, `a.`, `a:`) — a
+ *     dangling separator names nothing, so it would sit in the file looking like
+ *     a rule while matching no tool id at all;
+ *   - a pattern may not START with one (`.foo`), for the same reason.
+ * `worker::*` is unaffected: it ends with the wildcard, which is how the id-glob
+ * form is written.
+ */
+export declare function patternSyntaxError(pattern: unknown): string | null;
+export declare function isValidGlobPattern(pattern: unknown): boolean;
+/**
+ * Glob-match a tool id. Every `*` matches strictly up to the next literal, so
+ * the matcher is anchored at both ends: `worker::*` does NOT match `xworker::y`.
+ * Single-restart backtracking, no recursion.
+ */
+export declare function globMatch(pattern: string, id: string): boolean;
+/** The first syntax/contract problem in a policy, in rule order. */
+export declare function firstPolicyDefect(policy: ToolPolicy): string | null;
+/** The fail-closed decision: everything is denied, and the defect is named. */
+export declare function failClosedDecision(defect: string): Decision;
+/** True when the pattern is the bare catch-all (`*`), which is least specific. */
+export declare function isCatchAllPattern(pattern: unknown): boolean;
+/**
+ * Evaluation PRECEDENCE: SPECIFICITY FIRST, THEN FILE ORDER.
+ *
+ * T16 asks for "deny wins over allow" AND for "first-match-wins", which cannot
+ * both hold under adversarial ordering. The reconciliation — and the semantics
+ * this engine implements — is:
+ *
+ *   1. Among the rules whose pattern MATCHES the call, a rule with a MORE
+ *      SPECIFIC pattern outranks one with a less specific pattern. So a
+ *      catch-all `*` allow can never shield an id from a specific `deny` written
+ *      BELOW it.
+ *   2. Among equally specific matching rules, the EARLIER rule in the file wins.
+ *   3. A rule whose predicate ABSTAINS (`null`) does not participate at all: it
+ *      is as if the rule were not in the file for this call, so the next rule in
+ *      precedence order decides.
+ *
+ * Why not plain first-match-wins: it would make "deny wins over allow" merely a
+ * property of how the file happens to be ordered. A hand-edit that put a
+ * catch-all allow at the top would then silently disable every deny in the file,
+ * which is precisely the failure the phrase exists to prevent.
+ *
+ * Specificity tiers, most to least:
+ *   3  an EXACT id (`write`) — the narrowest thing a pattern can name;
+ *   2  a PREFIX glob (`worker::*`, `recursive_*`) — still names a family;
+ *   1  a glob with a wildcard in the middle (`*_write`) — matched anywhere in
+ *      the id, so it is narrower than the bare catch-all but names no family;
+ *   0  the bare catch-all (`*`).
+ * These are TIERS, not a fine-grained metric: patterns within a tier are
+ * "equally specific" and are decided by file order.
+ */
+export declare function patternSpecificity(pattern: string): number;
+/**
+ * Evaluate a tool call against a policy. PURE: no filesystem, no config, no
+ * caching. The loader resolves WHICH policy applies; this decides what it says,
+ * using the precedence above.
+ */
+export declare function evaluateToolPolicy(policy: ToolPolicy, id: string, args?: Record<string, unknown>, ctx?: ToolPolicyContext): Decision;
+export interface ToolPolicyLoadResult {
+    ok: boolean;
+    /** `file` when a policy file was found, `builtin` when it was ABSENT. */
+    source: 'file' | 'builtin';
+    policy: ToolPolicy;
+    /** Absolute path of the policy file, when one was found. */
+    path?: string;
+    /** Why the file could not be used, when `ok` is false. */
+    error?: string;
+}
+/** Wire the built-in default policy used when no policy file exists. */
+export declare function setBuiltInToolPolicy(factory: () => ToolPolicy): void;
+/** The built-in policy in force for the absent-file case. */
+export declare function builtInToolPolicy(): ToolPolicy;
+/** Tool names the locked-artifact write rule guards. */
+export declare const WRITE_TOOL_NAMES: Set<string>;
+/** Tool names the monotonic lock-order rule guards. */
+export declare const LOCK_TOOL_NAMES: Set<string>;
+/**
+ * The BUILT-IN default rule list — the pre-T16 guard behaviour expressed as
+ * data:
+ *
+ *   `recursive_lock*`  -> the monotonic lock-order denial;
+ *   the write-tool ids -> the locked-artifact write denial;
+ *   `*`                -> allow, so an ordinary tool is not turned into an `ask`.
+ *
+ * Every `deny` precedes the `allow`, which is what makes "deny wins over allow" a
+ * fact about the list rather than a hope. The predicates return `null` when
+ * their condition does not apply, so a matched-but-clean write falls through to
+ * the allow instead of being denied by the pattern alone.
+ *
+ * `.recursive/config/recursive-permissions.json` mirrors this list in the same
+ * order with the same reasons: a reviewer reads either one and predicts the same
+ * verdict.
+ */
+export declare function builtInToolPolicyRules(): ToolPolicyRule[];
+/** The built-in default policy (the absent-file fallback), as a policy object. */
+export declare function builtInToolPolicyDefault(): ToolPolicy;
+/**
+ * Attach the CODE-side condition to a rule that was authored in JSON.
+ *
+ * This is the seam that makes a policy file honest. JSON cannot carry a
+ * function, so a `deny` rule read from a file has no way to know whether its
+ * condition actually holds — and an unguarded `deny` is an UNCONDITIONAL denial,
+ * i.e. a policy file that denies locks whose prerequisites are met and writes to
+ * artifacts that are not locked. The pattern identifies the rule's subject, so
+ * the pattern is what selects the condition:
+ *
+ *   `recursive_lock*` -> the monotonic lock-order condition;
+ *   any write-tool id -> the locked-artifact condition.
+ *
+ * A pattern the code knows nothing about keeps NO condition and is therefore an
+ * absolute verdict — which is the honest reading of a rule like
+ * `{"pattern": "run_code", "verdict": "deny"}` with no lock condition behind it.
+ */
+export declare function attachPolicyPredicate(rule: ToolPolicyRule): ToolPolicyRule;
+/**
+ * TDD evidence predicate for a phase-3 lock (the `tdd-evidence` guard rule): the
+ * denial match when the artifact declares `TDD Mode: strict` without both RED
+ * and GREEN evidence, `null` otherwise — nothing to say, so the global lock rules
+ * still apply. `phase-rules.ts` uses it for the phase-3 baseline.
+ */
+export declare function tddEvidenceVerdict(artifact: string, runDir: string | undefined): ToolPolicyPredicateMatch | null;
+/**
+ * Read and validate the policy file. NEVER throws: an unreadable or malformed
+ * file yields `ok: false` plus a fail-closed policy, so the guard reasons about
+ * it instead of crashing the tools/pre-execute listener.
+ */
+export declare function loadToolPolicyFile(worktreeRoot: string): ToolPolicyLoadResult;
+/**
+ * Parse policy JSON into a policy. A parse/validation failure does NOT throw and
+ * does NOT return an empty rule list (which would mean "ask everything" and hide
+ * the defect) — it returns a single deny-all rule carrying the defect, plus
+ * `ok: false` and the same defect as `error`, so a caller can tell a healthy
+ * policy from a fail-closed one WITHOUT having to compare reasons. Both the
+ * malformed-JSON case and the PRESENT-but-empty case are `ok: false`.
+ */
+export declare function parseToolPolicy(raw: string, path?: string): ToolPolicyParseResult;
+export interface ToolPolicyParseResult {
+    ok: boolean;
+    policy: ToolPolicy;
+    /** The defect the policy failed closed on, when `ok` is false. */
+    error?: string;
+}
+/** A one-rule policy denying everything, with the defect as its reason. */
+export declare function failClosedPolicy(defect: string): ToolPolicy;
+/**
+ * Resolve the effective policy for a worktree: the file when present (even when
+ * broken — a present-but-invalid file fails closed), the built-in list when
+ * absent. Thin, so callers never re-implement the absent/present distinction.
+ */
+export declare function resolveToolPolicy(worktreeRoot: string): ToolPolicy;

package/lib/policy-write.d.ts

@@ -0,0 +1,42 @@
+/** Which level a write targets. The narrowest matching level wins at resolution time. */
+export type SelectionScope = 'general' | 'phase' | 'role';
+/** What to write. Every field is optional; omitting one leaves that field alone. */
+export interface SelectionPatch {
+    scope: SelectionScope;
+    /** Required for `phase` and `role`. */
+    phase?: string;
+    /** Required for `role`. */
+    role?: string;
+    /** The SUBAGENT provider — who creates the child. */
+    provider?: string;
+    /** The model id. */
+    model?: string;
+    /** The LLM provider — who SERVES the model. Not the same thing as `provider` above. */
+    modelProvider?: string;
+    /** Remove the named fields instead of setting them. With no field names, removes the whole level. */
+    clear?: boolean;
+}
+export interface SelectionWriteResult {
+    path: string;
+    /** One sentence, naming the level, what changed, and the rule that history is untouched. */
+    message: string;
+    /** Whether anything actually changed — a no-op write still rewrites the file, but says it was already so. */
+    changed: boolean;
+}
+/** Apply one patch to a policy object IN PLACE. Returns whether anything changed, or a refusal reason. */
+export declare function applySelectionPatch(policy: Record<string, unknown>, patch: SelectionPatch): {
+    changed: boolean;
+} | {
+    refused: string;
+};
+/**
+ * Write a selection patch to a workspace's policy file.
+ *
+ * Returns a refusal instead of throwing when the patch is incomplete, and a message that always states the rule
+ * the objective names: this applies to future delegations and never rewrites a run's recorded history.
+ */
+export declare function writePolicySelection(root: string, patch: SelectionPatch, options?: {
+    path?: string;
+}): SelectionWriteResult | {
+    refused: string;
+};

package/lib/policy.d.ts

@@ -10,3 +10,42 @@ export interface PolicyContext {
  * Render the current-phase contract. Empty string when no run is active.
  */
 export declare function renderRecursivePolicy(context: PolicyContext | null): string;
+/**
+ * T22 — the STABLE contract: the part of the policy section that does not depend on the phase.
+ *
+ * WHY A SPLIT AT ALL, given the item's own premise check: the mechanism this was modelled on
+ * (iii's `system_sections` + `cache_boundary` + `cache_intent.surface_digest`) does **not** exist in
+ * DSH as a plugin-visible seam — the harness's only cache concepts live in the provider layer
+ * (`llm-pi-ai` accepts prompt-cache MARKERS and a retention preference), and whether any provider
+ * caches the prefix is **provider-side and unverified**. The item **withdrew its "largest cost
+ * lever" label for exactly that reason**, and this module keeps only what survives the check:
+ * **a byte-identical prefix is a PRECONDITION for any provider-side caching**, whatever the provider
+ * does with it — and a stable prefix costs nothing to produce.
+ *
+ * ⚠ THE CONTRACT DEPENDS ON THE CONFIG, NOT ON THE PHASE, and that distinction is the whole point:
+ * the enforcement modes and the lock rules are fixed for a RUN, so they belong in the prefix; the
+ * current phase, its required sections and its gate checklist change per phase and belong in the
+ * tail. A prefix that varied with the phase would be stable in name only.
+ */
+export declare function renderStableContract(config?: EnforcementConfig): string;
+/**
+ * T22 — a LOCAL identifier for the contract, not a cache directive.
+ *
+ * The item's rescope is explicit that the digest is worth computing as a **local identifier**: it is
+ * stable within a run and changes when the contract changes, which is what makes "did the contract
+ * change under me?" answerable from the prompt alone. It claims **nothing** about provider caching —
+ * a digest that implied one would be the withdrawn label wearing a hash.
+ */
+export declare function contractDigest(config?: EnforcementConfig): string;
+/**
+ * T22 — the per-phase TAIL: everything that legitimately changes between phases.
+ *
+ * Kept as its own name so the split is a fact in the code rather than a convention: a caller that
+ * wants a cacheable prefix takes {@link renderStableContract} and puts this after it.
+ */
+export declare function renderPhaseTail(phase: {
+    label: string;
+    phaseName: string;
+    status: string;
+    key?: string;
+} | null): string;

package/lib/recursive_ask.tool.d.ts

@@ -0,0 +1,88 @@
+import type { RecursiveRuntime } from './runtime.ts';
+/** The identifiers the workflow uses for its three human gates. */
+export declare const ASK_GATE_IDS: readonly ["tdd-mode", "qa-signoff", "gate-block"];
+export type AskGateId = (typeof ASK_GATE_IDS)[number];
+/** The plugin's own documented bounds — see the module comment on why these are not a claimed mirror. */
+export declare const MAX_HEADER_CHARS = 12;
+export declare const MAX_LABEL_CHARS = 30;
+export declare const MAX_DESCRIPTION_CHARS = 200;
+export interface AskOption {
+    label: string;
+    description?: string;
+}
+/** A structured question, in the shape the ask flow renders as a card. */
+export interface AskQuestion {
+    id: string;
+    header: string;
+    question: string;
+    options: AskOption[];
+}
+/** One of the three gates, as data: what to ask, what the options mean, and what the answer means. */
+export interface AskGate {
+    id: AskGateId;
+    header: string;
+    question: string;
+    options: AskOption[];
+    /** The artifact marker name the answer is written under. */
+    marker: string;
+}
+export declare const ASK_GATES: Record<AskGateId, AskGate>;
+/** Thrown for a request the ask flow would refuse; carries the FAILING FIELD PATH. */
+export declare class AskValidationError extends Error {
+    readonly field: string;
+    constructor(field: string, message: string);
+}
+/**
+ * Validate a question and return it unchanged.
+ *
+ * The FIELD PATH travels in the error because a caller fixing an over-long header needs to know
+ * WHICH field — a bare "too long" for a request with four fields is a puzzle, not a diagnostic.
+ */
+export declare function validateAskQuestion(question: AskQuestion): AskQuestion;
+/** Build the question for a gate, validated. */
+export declare function buildAskQuestion(gateId: AskGateId): AskQuestion;
+/**
+ * Validate an answer against its gate.
+ *
+ * An answer that is not one of the offered labels is REFUSED rather than recorded: a marker saying
+ * `TDD Mode: maybe` would look like a decision and be a transcription error.
+ */
+export declare function validateAskAnswer(gateId: AskGateId, answer: string): string;
+/** The durable marker an accepted answer is written back as — a fact, not a chat aside. */
+export declare function answerMarker(gateId: AskGateId, answer: string): string;
+/**
+ * One-ask-per-step guard.
+ *
+ * A step that asks twice yields two cards for one decision and the second answer silently wins —
+ * so the second ask is REFUSED, naming the gate already asked this step.
+ */
+export declare function createAskLedger(): {
+    claim(gateId: AskGateId): void;
+    asked(): AskGateId[];
+};
+/** Which artifact each gate's answer belongs in, when the caller does not name one. */
+export declare const GATE_DEFAULT_ARTIFACT: Record<AskGateId, string>;
+/**
+ * FU-7 — THE CALL POINTS: which gate, if any, a phase ENTRY still owes.
+ *
+ * ⚠ THE ARTIFACT IS THE RECORD, so no ledger is needed to ask once: if the document already carries the
+ * gate's marker line, the question has been answered and is not asked again. That is the same
+ * "once per run at entry" property T29 got from riding an existing gate — one mechanism, not two.
+ *
+ * ⚠ AND AN UNKNOWN PHASE OWES NOTHING. Returning a gate for a phase that has no such decision would ask a
+ * person a question the workflow does not act on, which is worse than not asking at all.
+ */
+export declare function pendingGateFor(artifactFile: string, artifactText: string | null): AskGateId | null;
+/**
+ * T23 — the tool.
+ *
+ * TWO BRANCHES, and the split is the point: called WITHOUT an answer it ASKS (returning the validated
+ * question, which the host renders as a card), and called WITH one it RECORDS — validating the label,
+ * writing the marker into the artifact, and reporting the line it wrote. A tool that did both in one
+ * call would have to invent the answer.
+ *
+ * ⚠ THE WRITE-BACK IS A MARKER LINE, REPLACED IN PLACE when the artifact already carries one. A
+ * second `TDD Mode:` line would leave two answers to one question and make "what was decided?"
+ * depend on which a reader found first.
+ */
+export declare function createRecursiveAskTool(recursive: RecursiveRuntime): import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/recursive_closeout.tool.d.ts

@@ -1,6 +1,6 @@
 import type { RecursiveRuntime } from './runtime.ts';
 /**
- * `recursive_closeout` — scaffold a Phase 4/5/6/7/8 closeout receipt under the
+ * `recursive_closeout` — scaffold a Phase 0-8 closeout receipt under the
  * SESSION's workspace only (R1 workspace-scoping invariant). The run is resolved
  * via the session agent's cwd -> workspace registry; a runId outside the current
  * workspace is rejected.