@try-works/dsh-recursive-mode 0.4.6 → 0.4.8

package/lib/delegation.d.ts

@@ -336,9 +336,40 @@ export interface ActionRecordInput {
      * nothing else: a delegation that FAILED and a delegation that NEVER HAPPENED read identically, which is what
      * let me conclude for three rounds that the host was not scheduling children. The caller ALREADY passed
      * `stopReason`, and the live record said `n/a` — because there was no result to take a stop reason from.
+     *
+     * ⚠ AND IT IS EMITTED ONLY FOR A GENUINE FAILURE. A PARKED round is neither accepted nor failed, so it
+     * carries {@link ActionRecordInput.parked} instead: calling a live child a failure is the defect this
+     * field's own history is made of.
      */
     failure?: string;
+    /**
+     * ⚠ THE THIRD STATE, AND WHY `success` COULD NOT CARRY IT.
+     *
+     * A continuable round that has not settled is NOT a failure — `ContinuableDelegationLike.parked` says so in
+     * its own doc comment, and the tool result already surfaces it. The RECORD did not: a live run's child was
+     * parked, the record said `Status: failed` with "the child never reported, or never ran", the main agent
+     * read that as a dead child and obtained the review elsewhere — while the child was still working and
+     * replied eighteen minutes later. `success: false` cannot express "still in flight", because a genuinely
+     * dead child also produces `success: false`, so a second field is required rather than a cleverer boolean.
+     *
+     * When true, the record says `parked` and carries a `Parked:` line (never a `Failure:` line) whose text
+     * states only what is KNOWN, names the `childId`, and names the resume step. It takes precedence over
+     * `success`: an unobserved round is never an acceptance, whatever a caller passes alongside it.
+     */
+    parked?: boolean;
 }
+/**
+ * The status a record states, in ONE place, because the three states are the fix and a second writer would
+ * drift from this one.
+ *
+ * The wording is chosen for two readers at once. The MODEL reads it to decide whether to resume or to give up
+ * and obtain the result another way — the exact decision the live defect got wrong — so the token must not
+ * read as a failure and must not need the rest of the document to be understood. A HUMAN reading the run tree
+ * months later needs to tell "died" from "still working" at a glance. Hence `parked (still running; no
+ * settlement yet)`: a third token rather than a renamed second, qualified with the two facts that separate it
+ * from `failed`, and short enough to sit in a status line.
+ */
+export declare function actionRecordStatus(input: Pick<ActionRecordInput, 'success' | 'parked'>): string;
 /**
  * Write a durable action record under subagents/ in the shape this repo's own
  * linter accepts (ts-lint.ts lintSubagentActionRecordFile — every top-level .md
@@ -351,7 +382,10 @@ export interface ActionRecordInput {
  *     `Code Refs` strictly inside ## Inputs Provided. The linter resolves each of
  *     those through the heading body, so a field under another heading is not
  *     found at all.
- * A success:false attempt is written with a failed status and is NOT accepted.
+ * A success:false attempt is written with a failed status and is NOT accepted. A round that PARKED is written
+ * with a status of its own (`parked (still running; no settlement yet)`, see {@link actionRecordStatus}) and a
+ * `Parked:` line instead of a `Failure:` one, because no settlement is not a death: it is the caller's signal to
+ * resume the same child. Only a genuine failure carries `Failure:`.
  */
 export declare function writeActionRecord(input: ActionRecordInput): string;
 /**

package/lib/errors.d.ts

@@ -151,6 +151,19 @@ export declare const TOOL_ERRORS: {
         readonly problem: "the run has unresolved delegated work, so this phase cannot lock yet";
         readonly next: "call recursive_status to see the pending delegation, have the child write its reply.md, then lock again";
     };
+    /**
+     * THE ORDERING DEFECT, AS A CODE. `recursive_ask gate=run-start` used to raise "start this run or hold?"
+     * over a Phase 0 document that was still the scaffold `recursive_init` wrote — placeholder requirements,
+     * unchecked lists, `FAIL` gates — and nothing put that document in front of the person either. The owner:
+     * *"i was never shown the spec before that so how could i approve if i havent seen it"*. Approving an
+     * unfilled template is not a decision about a spec, so the gate refuses to be raised until there is one.
+     */
+    readonly RUN_START_SPEC_UNFILLED: {
+        readonly code: "RM4404";
+        readonly klass: "state";
+        readonly problem: "the Phase 0 requirements document is still the unfilled template, so there is no run spec for a person to approve";
+        readonly next: "fill the requirements document in (define the requirement ids and their acceptance criteria, and complete the TODO list) and then call recursive_ask with gate: run-start again";
+    };
     readonly RUN_START_NO_CHANNEL: {
         readonly code: "RM5502";
         readonly klass: "runtime";

package/lib/index.js

@@ -5480,6 +5480,19 @@ const TOOL_ERRORS = {
 		problem: "the run has unresolved delegated work, so this phase cannot lock yet",
 		next: "call recursive_status to see the pending delegation, have the child write its reply.md, then lock again"
 	},
+	/**
+	* THE ORDERING DEFECT, AS A CODE. `recursive_ask gate=run-start` used to raise "start this run or hold?"
+	* over a Phase 0 document that was still the scaffold `recursive_init` wrote — placeholder requirements,
+	* unchecked lists, `FAIL` gates — and nothing put that document in front of the person either. The owner:
+	* *"i was never shown the spec before that so how could i approve if i havent seen it"*. Approving an
+	* unfilled template is not a decision about a spec, so the gate refuses to be raised until there is one.
+	*/
+	RUN_START_SPEC_UNFILLED: {
+		code: "RM4404",
+		klass: "state",
+		problem: "the Phase 0 requirements document is still the unfilled template, so there is no run spec for a person to approve",
+		next: "fill the requirements document in (define the requirement ids and their acceptance criteria, and complete the TODO list) and then call recursive_ask with gate: run-start again"
+	},
 	RUN_START_NO_CHANNEL: {
 		code: "RM5502",
 		klass: "runtime",
@@ -6864,6 +6877,79 @@ function extractAndGroup(runner, env, options = {}) {
 	};
 }
 //#endregion
+//#region src/run-spec.ts
+/** The named evidence classes, so a reader can tell a placeholder from an unmet gate. */
+const ARTIFACT_MARKER_IDS = {
+	placeholder: "placeholder",
+	uncheckedTodo: "unchecked-todo",
+	failedGate: "failed-gate"
+};
+/** Every marker, in the order they are reported for a single line. */
+const MARKER_PATTERNS = [
+	{
+		id: ARTIFACT_MARKER_IDS.placeholder,
+		re: /(^\s*\.\.\.\s*$)|(\[[^[\]\n<>]{2,120}\])|(<[^<>\n]{2,120}>)/
+	},
+	{
+		id: ARTIFACT_MARKER_IDS.uncheckedTodo,
+		re: /^\s*[-*]\s*\[ \]/
+	},
+	{
+		id: ARTIFACT_MARKER_IDS.failedGate,
+		re: /^\s*(Coverage|Approval):\s*FAIL\b/i
+	}
+];
+/**
+* Which marker a single line carries, or null.
+*
+* Exported because the client prints the marker NAMES beside the quoted lines, and a second classifier that
+* re-derived them would be a second answer to the same question.
+*/
+function markerIdsOnLine(line) {
+	const ids = [];
+	for (const pattern of MARKER_PATTERNS) if (pattern.re.test(line)) ids.push(pattern.id);
+	return ids;
+}
+/**
+* Classify one artifact's text.
+*
+* A verdict of `unfilled` means the document still carries the template's own placeholder text — the
+* evidence travels with it, line by line, so the refusal (and the client notice) can name what is missing
+* instead of asserting a state the reader cannot check.
+*/
+function classifyArtifact(text) {
+	const lines = text.split(/\r?\n/);
+	const hits = [];
+	for (let i = 0; i < lines.length; i += 1) {
+		const line = lines[i];
+		for (const id of markerIdsOnLine(line)) hits.push({
+			id,
+			line: i + 1,
+			text: line.trim()
+		});
+	}
+	return {
+		verdict: hits.some((hit) => hit.id === ARTIFACT_MARKER_IDS.placeholder) ? "unfilled" : "filled",
+		hits
+	};
+}
+/** The unfilled evidence only (what a refusal names). */
+function unfilledEvidence(result) {
+	return result.hits.filter((hit) => hit.id === ARTIFACT_MARKER_IDS.placeholder);
+}
+/**
+* One line naming what is missing, for a refusal sentence.
+*
+* The line number and the text are both quoted: "line 12: <short title>" is a thing a reader can go and
+* look at, while "the requirements are not filled in" is an assertion they would have to take on trust.
+*/
+function describeEvidence(hits, limit = 3) {
+	const shown = hits.slice(0, limit).map((hit) => "line " + String(hit.line) + ": " + hit.text);
+	const rest = hits.length - shown.length;
+	const suffix = rest > 0 ? " (and " + String(rest) + " more)" : "";
+	return shown.join(" | ") + suffix;
+}
+//#endregion
 //#region src/run-start.ts
 /**
 * PHASE 0 — STARTING A RUN IS A HUMAN DECISION, NOT A SIDE EFFECT OF SCAFFOLDING.
@@ -6986,6 +7072,43 @@ function readRunStartApproval(root, runId) {
 * the same string instead of re-typing it (a re-typed reason is a caller that silently stops matching).
 */
 const RUN_START_NOT_APPROVED = "run not started: phase 0 approval has not been granted";
+/**
+* PHASE 0 — THE GATE CANNOT BE RAISED BEFORE THERE IS A SPEC TO DECIDE ABOUT.
+*
+* THE DEFECT. `recursive_init` scaffolds Phase 0 as a TEMPLATE, and `recursive_ask gate=run-start` raised
+* "start this run or hold?" over it immediately — while every requirement was still `<short title>`, every
+* acceptance criterion was still `[observable condition 1]`, and nothing put the document in front of the
+* person at all. The owner: *"the card ui for accepting the spec appeared, but i was never shown the spec
+* before that so how could i approve if i havent seen it"*. Approving an unfilled template is not a decision
+* about a spec; there is no spec yet, and a card that asks the question anyway teaches a person to answer
+* without reading.
+*
+* ⚠ WHAT THIS DOES *NOT* TOUCH. It does not weaken the gate's own contract, it does not add a second way to
+* start a run, and it does not make the plugin the decider: it only refuses to ASK. A person's own answer
+* still wins (`recordRunStartAnswer` is unchanged), a spec still creates no goal, and cancellation / abort /
+* timeout are still unrelayable. The check runs BEFORE the question is put to anybody, so no card is shown
+* for a document that cannot be approved meaningfully.
+*
+* ⚠ AND IT IS A CHECK ON THE DOCUMENT, NOT ON THE CALLER. A `runId` that does not resolve is not this
+* refusal's business — the ask path already reports that — so the guard says `ok: true` there and lets the
+* existing route handle it.
+*/
+function runStartSpecGuard(root, runId) {
+	const content = readRunStartArtifact(root, runId);
+	if (content === null) return {
+		ok: false,
+		reason: toolError("RUN_START_SPEC_UNFILLED", "there is no Phase 0 document to approve: " + runStartArtifactPath(root, runId) + " does not exist yet")
+	};
+	const verdict = classifyArtifact(content);
+	if (verdict.verdict === "filled") return { ok: true };
+	const evidence = unfilledEvidence(verdict);
+	const context = verdict.hits.filter((hit) => hit.id !== "placeholder");
+	const contextNote = context.length === 0 ? "" : " (it also carries " + String(context.length) + " unfinished marker(s) of its own, starting at line " + String(context[0]?.line ?? 0) + ")";
+	return {
+		ok: false,
+		reason: toolError("RUN_START_SPEC_UNFILLED", "00-requirements.md for run " + JSON.stringify(runId) + " still carries the template scaffold" + contextNote + ": " + describeEvidence(evidence))
+	};
+}
 //#endregion
 //#region src/recursive_ask.tool.ts
 /**
@@ -7201,7 +7324,7 @@ function pendingGateFor(artifactFile, artifactText) {
 function createRecursiveAskTool(recursive) {
 	return defineTool({
 		name: "recursive_ask",
-		description: "Ask a human gate as a structured decision (tdd-mode, qa-signoff, gate-block), or ASK TO START A RUN (run-start: nothing runs, and no goal exists, until this gate is approved). Call without `answer` to ask; call with it to write the answer into the artifact as a durable marker. For run-start the mounted human channel is asked first and its own selection wins; when that channel cannot deliver the question, the refusal names the cause and `relay=true` with an explicit `answer` records the person's relayed approval. One ask per step.",
+		description: "Ask a human gate as a structured decision (tdd-mode, qa-signoff, gate-block), or ASK TO START A RUN (run-start: nothing runs, and no goal exists, until this gate is approved). Call without `answer` to ask; call with it to write the answer into the artifact as a durable marker. For run-start the mounted human channel is asked first and its own selection wins; when that channel cannot deliver the question, the refusal names the cause and `relay=true` with an explicit `answer` records the person's relayed approval. The run-start gate is REFUSED while the Phase 0 requirements document is still the unfilled template — the refusal quotes the placeholder lines, and there is nothing to approve until they are written. One ask per step.",
 		parameters: {
 			gate: {
 				type: "string",
@@ -7240,6 +7363,16 @@ function createRecursiveAskTool(recursive) {
 			const root = await recursive.resolveWorkspaceRoot(exec.agent);
 			if (!root) return { error: toolError("NO_WORKSPACE") };
 			const artifact = (isRunStartGate(gateId) ? RUN_START_ARTIFACT : args.artifact ?? GATE_DEFAULT_ARTIFACT[gateId]).trim();
+			if (isRunStartGate(gateId)) {
+				const guard = runStartSpecGuard(root, runId);
+				if (!guard.ok) return {
+					error: guard.reason,
+					gate: RUN_START_GATE_ID,
+					runId,
+					artifact: RUN_START_ARTIFACT,
+					question: buildAskQuestionFor(RUN_START_GATE_ID)
+				};
+			}
 			let question;
 			try {
 				question = buildAskQuestionFor(gateId);
@@ -8646,7 +8779,7 @@ async function delegateContinuable(input) {
 			const observed = await input.awaitRoundResult(childId, lastMessageId);
 			if (observed === null) return {
 				ok: false,
-				reason: "no settlement has landed for round " + (round + 1) + " yet (the child is still working)",
+				reason: "no settlement has landed for round " + (round + 1) + " yet, so the round is PARKED, not failed: the child may still be working. Resume it on a later turn with childId " + String(childId) + " (the `resumeChild` argument) — do not start a second child.",
 				childId,
 				messageIds,
 				rounds,
@@ -8860,6 +8993,21 @@ function validateReferences(root, references) {
 		checked
 	};
 }
+/**
+* The status a record states, in ONE place, because the three states are the fix and a second writer would
+* drift from this one.
+*
+* The wording is chosen for two readers at once. The MODEL reads it to decide whether to resume or to give up
+* and obtain the result another way — the exact decision the live defect got wrong — so the token must not
+* read as a failure and must not need the rest of the document to be understood. A HUMAN reading the run tree
+* months later needs to tell "died" from "still working" at a glance. Hence `parked (still running; no
+* settlement yet)`: a third token rather than a renamed second, qualified with the two facts that separate it
+* from `failed`, and short enough to sit in a status line.
+*/
+function actionRecordStatus(input) {
+	if (input.parked === true) return "parked (still running; no settlement yet)";
+	return input.success ? "accepted" : "failed";
+}
 function slugify(value) {
 	return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "action";
 }
@@ -8875,7 +9023,10 @@ function slugify(value) {
 *     `Code Refs` strictly inside ## Inputs Provided. The linter resolves each of
 *     those through the heading body, so a field under another heading is not
 *     found at all.
-* A success:false attempt is written with a failed status and is NOT accepted.
+* A success:false attempt is written with a failed status and is NOT accepted. A round that PARKED is written
+* with a status of its own (`parked (still running; no settlement yet)`, see {@link actionRecordStatus}) and a
+* `Parked:` line instead of a `Failure:` one, because no settlement is not a death: it is the caller's signal to
+* resume the same child. Only a genuine failure carries `Failure:`.
 */
 function writeActionRecord(input) {
 	const { root, runId } = input;
@@ -8913,8 +9064,8 @@ function writeActionRecord(input) {
 		"- Phase: " + input.phase,
 		"- Purpose: " + input.purpose,
 		"- Execution Mode: " + input.executionMode,
-		"- Status: " + (input.success ? "accepted" : "failed"),
-		...input.success === false && input.failure !== void 0 ? ["- Failure: " + input.failure] : [],
+		"- Status: " + actionRecordStatus(input),
+		...input.success === false && input.failure !== void 0 ? [input.parked === true ? "- Parked: " + input.failure : "- Failure: " + input.failure] : [],
 		"- Stop Reason: " + (input.stopReason ?? "n/a"),
 		"- Timestamp: " + (/* @__PURE__ */ new Date()).toISOString(),
 		"",
@@ -10694,7 +10845,10 @@ var RecursiveRuntime = class extends Service {
 				} else if (continuable.ok && continuable.rounds.length > 0) {
 					result = continuable.rounds[continuable.rounds.length - 1].result ?? null;
 					if (!result) error = "continuable child produced no final result";
-				} else error = continuable.reason ?? "continuable delegation failed";
+				} else {
+					result = continuable.rounds[continuable.rounds.length - 1]?.result ?? null;
+					if (result === null) error = continuable.reason ?? "continuable delegation failed";
+				}
 			} else try {
 				result = await delegate({
 					subagents,
@@ -10719,7 +10873,7 @@ var RecursiveRuntime = class extends Service {
 			id: operation,
 			act: "delegate-review",
 			at: (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d{3}Z$/, "Z"),
-			outcome: evaluation.accepted ? "accepted" : "unaccepted",
+			outcome: parked ? "parked" : evaluation.accepted ? "accepted" : "unaccepted",
 			phase: input.phase
 		});
 		const actionRecordPath = writeActionRecord({
@@ -10738,7 +10892,8 @@ var RecursiveRuntime = class extends Service {
 			findings: evaluation.accepted && result?.structured ? [result.structured?.verdict ?? "accepted"] : void 0,
 			success: evaluation.accepted,
 			stopReason: result?.stopReason,
-			failure: evaluation.accepted ? void 0 : result == null ? input.mode !== "one-shot" ? "the continuable start was made and NO SETTLEMENT arrived within the wait (the child never reported, or never ran); tier " + decision.tier + ", provider " + (decision.provider ?? "none chosen") + ", names on offer [" + (this.lastProviderNames.join(", ") || "none") + "]; parent id " + (input.parent?.id ?? "none") + ", parent session keys [" + (input.parent === void 0 ? "no parent" : Object.keys(input.parent).join(", ")) + "]" : "no delegate result was produced by the one-shot path; tier " + decision.tier + ", provider " + (decision.provider ?? "none chosen") : "the delegation returned without acceptance; stop reason " + (result.stopReason ?? "none reported")
+			...parked ? { parked: true } : {},
+			failure: evaluation.accepted ? void 0 : parked ? "no settlement had landed when the wait ended, so this round is PARKED, not failed: nothing was accepted and nothing was refused, and the child may still be working. The next step is to RESUME this round, not to re-dispatch it or replace the child: call `recursive_review` again on a later turn with childId " + String(continuable?.childId ?? input.childId) + " (the child the round was started for, which stays resumable). Diagnostics: tier " + decision.tier + ", provider " + (decision.provider ?? "none chosen") + ", names on offer [" + (this.lastProviderNames.join(", ") || "none") + "]; parent id " + (input.parent?.id ?? "none") + ", parent session keys [" + (input.parent === void 0 ? "no parent" : Object.keys(input.parent).join(", ")) + "]" : result == null ? input.mode !== "one-shot" ? "the continuable start was made and NO SETTLEMENT arrived within the wait (the child never reported, or never ran); tier " + decision.tier + ", provider " + (decision.provider ?? "none chosen") + ", names on offer [" + (this.lastProviderNames.join(", ") || "none") + "]; parent id " + (input.parent?.id ?? "none") + ", parent session keys [" + (input.parent === void 0 ? "no parent" : Object.keys(input.parent).join(", ")) + "]" : "no delegate result was produced by the one-shot path; tier " + decision.tier + ", provider " + (decision.provider ?? "none chosen") : "the delegation returned without acceptance; stop reason " + (result.stopReason ?? "none reported") + (result.success === false ? " (the child itself reported success:false)" : "")
 		});
 		const delegationMode = continuable !== null ? continuable.fellBackToOneShot ? "continuable-unavailable" : "continuable" : result !== null ? "one-shot" : "none";
 		return {
@@ -14660,4 +14815,4 @@ function apply(ctx, config) {
 	});
 }
 //#endregion
-export { Config, DEFAULT_BUDGETS, DEFAULT_ENFORCEMENT, OPTIONAL_PHASES, PHASES, PHASE_POSITIONS, PHASE_SEQUENCE, RECURSIVE_API_PREFIX, RUN_ARTIFACT_SEQUENCE, RUN_STATES, RecursiveRuntime, apply, auditToPass, buildDelegationPrompt, buildReviewBundle, buildWorkSlice, builtInToolPolicy, capabilityProbe, childScratchPath, coerceAskToDecision, contentSha256, contractDigest, coupleGateBlockToGoal, createChildBrief, createHandoff, createRecursiveCloseoutTool, createRecursiveInitTool, createRecursiveLintTool, createRecursiveLockTool, createRecursivePhaseTool, createRecursiveScratchTool, createRecursiveStatusTool, createRecursiveWorktreeTool, currentPhaseArtifact, defaultReviewToolFilter, delegate, delegateContinuable, delegationDecisionBasis, delegationError, detectTamper, discoverRuns, drainContinuableChildren, drainContinuableDescendants, escapeRegExp, evaluateDelegationResult, evaluateToolGuard, foldDiagnostics, foldRun, foldRunCard, getAllStaleReceipts, getArtifactState, getGateStatus, getLatestRunDirectory, getLockStatus, getMdFieldValue, getNextLegalPhase, getPrerequisiteBlockers, getPrerequisites, getStaleDownstreamPhases, getTodoStats, getWorkflowProfile, inject, interruptContinuable, invalidateReceipt, isCoreArtifact, isTaskClaimedBy, loadRouterPolicy, lockHashFromContent, makeRecursiveRoutes, mountRecursiveRoutesOnce, name, normalizeForLockHash, parseReplyVerdict, pendingWork, phaseIndex, phasePosition, probeCapabilities, readReceipt, readRepairFromReply, readRepairFromStructured, readVerdictFromReply, readVerdictFromStructured, receiptPath, referencesFromResult, registerRecursiveSkill, remainingDepthFor, renderPhaseTail, renderRecursivePolicy, renderStableContract, renderTaskHistory, replyPath, resetFoldCache, resolveEnforcementConfig, resolveRole, resolveRunDir, resolveToolPolicyForGuard, reviewBundleDir, reviewOutputSchema, routerPolicyPath, snapshotWorkspace, tamperCandidatePath, trimMdValue, validateChain, validateReferences, validateTransition, writeActionRecord, writeReceipt };
+export { Config, DEFAULT_BUDGETS, DEFAULT_ENFORCEMENT, OPTIONAL_PHASES, PHASES, PHASE_POSITIONS, PHASE_SEQUENCE, RECURSIVE_API_PREFIX, RUN_ARTIFACT_SEQUENCE, RUN_STATES, RecursiveRuntime, actionRecordStatus, apply, auditToPass, buildDelegationPrompt, buildReviewBundle, buildWorkSlice, builtInToolPolicy, capabilityProbe, childScratchPath, coerceAskToDecision, contentSha256, contractDigest, coupleGateBlockToGoal, createChildBrief, createHandoff, createRecursiveCloseoutTool, createRecursiveInitTool, createRecursiveLintTool, createRecursiveLockTool, createRecursivePhaseTool, createRecursiveScratchTool, createRecursiveStatusTool, createRecursiveWorktreeTool, currentPhaseArtifact, defaultReviewToolFilter, delegate, delegateContinuable, delegationDecisionBasis, delegationError, detectTamper, discoverRuns, drainContinuableChildren, drainContinuableDescendants, escapeRegExp, evaluateDelegationResult, evaluateToolGuard, foldDiagnostics, foldRun, foldRunCard, getAllStaleReceipts, getArtifactState, getGateStatus, getLatestRunDirectory, getLockStatus, getMdFieldValue, getNextLegalPhase, getPrerequisiteBlockers, getPrerequisites, getStaleDownstreamPhases, getTodoStats, getWorkflowProfile, inject, interruptContinuable, invalidateReceipt, isCoreArtifact, isTaskClaimedBy, loadRouterPolicy, lockHashFromContent, makeRecursiveRoutes, mountRecursiveRoutesOnce, name, normalizeForLockHash, parseReplyVerdict, pendingWork, phaseIndex, phasePosition, probeCapabilities, readReceipt, readRepairFromReply, readRepairFromStructured, readVerdictFromReply, readVerdictFromStructured, receiptPath, referencesFromResult, registerRecursiveSkill, remainingDepthFor, renderPhaseTail, renderRecursivePolicy, renderStableContract, renderTaskHistory, replyPath, resetFoldCache, resolveEnforcementConfig, resolveRole, resolveRunDir, resolveToolPolicyForGuard, reviewBundleDir, reviewOutputSchema, routerPolicyPath, snapshotWorkspace, tamperCandidatePath, trimMdValue, validateChain, validateReferences, validateTransition, writeActionRecord, writeReceipt };

package/lib/run-spec.d.ts

@@ -0,0 +1,78 @@
+/**
+ * IS THIS RUN SPEC STILL A HOLLOW TEMPLATE? — one answer, two callers.
+ *
+ * WHY THIS MODULE EXISTS. `recursive_init` scaffolds Phase 0 as a TEMPLATE: the requirement block
+ * still reads `### \`R1\` <short title>`, the acceptance criteria are still `[observable condition 1]`,
+ * the checklists are still unchecked and both gates still read `FAIL`. The owner's defect report is that
+ * `recursive_ask gate=run-start` raised the "start this run or hold?" gate while the document was in
+ * exactly that state — *"i was never shown the spec before that so how could i approve if i havent seen
+ * it"*. Approving an unfilled template is not a decision about a spec; there is no spec yet.
+ *
+ * So the QUESTION "is this document still the template?" must have ONE answer, and two consumers need it:
+ *
+ *   1. the SERVER gate (`recursive_ask`), which must REFUSE to raise the run-start question while the
+ *      answer is yes, and
+ *   2. the CLIENT sheet (`client/spec-sheet.tsx`), which must SAY SO plainly rather than dress a hollow
+ *      document up as an approvable one — the honesty rule of `client/settings-view.ts`, applied to a
+ *      document instead of a value.
+ *
+ * ⚠ THIS MODULE IS NODE-FREE ON PURPOSE. It is reached by both halves of the bundle, and the client bundle
+ * is a BROWSER closure: a `node:fs` import anywhere in its graph breaks the page. So the file reading stays
+ * in `run-start.ts` (which owns the artifact path) and this module takes TEXT and returns a VERDICT.
+ *
+ * ⚠ AND IT PINS THE TEMPLATE, NOT A COPY OF IT. The markers below are the literal lines
+ * `init-templates.ts::requirementsContent` writes. A checker that instead carried its own copy of the whole
+ * template would silently stop matching the moment the template changed; a checker that carried a CHECKSUM
+ * would call every edited document filled and every untouched one unfilled on the strength of a byte count.
+ * Naming the placeholder markers is the check that keeps meaning what it says.
+ */
+/** What the checker decided about one artifact's text. */
+export type ArtifactVerdict = 'unfilled' | 'filled';
+/** One piece of evidence found in the document, quoted with its line number. */
+export interface ArtifactMarkerHit {
+    /** Stable id of the marker that matched. */
+    id: string;
+    /** 1-based line number in the document as it was read. */
+    line: number;
+    /** The line verbatim, trimmed of surrounding whitespace. */
+    text: string;
+}
+/** The verdict plus the evidence for it. */
+export interface ArtifactVerdictResult {
+    verdict: ArtifactVerdict;
+    /** Marker hits, in line order. Empty exactly when the verdict is `filled`. */
+    hits: ArtifactMarkerHit[];
+}
+/** The named evidence classes, so a reader can tell a placeholder from an unmet gate. */
+export declare const ARTIFACT_MARKER_IDS: {
+    readonly placeholder: "placeholder";
+    readonly uncheckedTodo: "unchecked-todo";
+    readonly failedGate: "failed-gate";
+};
+export type ArtifactMarkerId = (typeof ARTIFACT_MARKER_IDS)[keyof typeof ARTIFACT_MARKER_IDS];
+/**
+ * Which marker a single line carries, or null.
+ *
+ * Exported because the client prints the marker NAMES beside the quoted lines, and a second classifier that
+ * re-derived them would be a second answer to the same question.
+ */
+export declare function markerIdsOnLine(line: string): ArtifactMarkerId[];
+/**
+ * Classify one artifact's text.
+ *
+ * A verdict of `unfilled` means the document still carries the template's own placeholder text — the
+ * evidence travels with it, line by line, so the refusal (and the client notice) can name what is missing
+ * instead of asserting a state the reader cannot check.
+ */
+export declare function classifyArtifact(text: string): ArtifactVerdictResult;
+/** The unfilled evidence only (what a refusal names). */
+export declare function unfilledEvidence(result: ArtifactVerdictResult): ArtifactMarkerHit[];
+/** The weak, contextual markers (unchecked boxes, FAIL gates). */
+export declare function contextEvidence(result: ArtifactVerdictResult): ArtifactMarkerHit[];
+/**
+ * One line naming what is missing, for a refusal sentence.
+ *
+ * The line number and the text are both quoted: "line 12: <short title>" is a thing a reader can go and
+ * look at, while "the requirements are not filled in" is an assertion they would have to take on trust.
+ */
+export declare function describeEvidence(hits: readonly ArtifactMarkerHit[], limit?: number): string;

package/lib/run-start.d.ts

@@ -53,3 +53,30 @@ export declare function readRunStartApproval(root: string, runId: string): {
  * the same string instead of re-typing it (a re-typed reason is a caller that silently stops matching).
  */
 export declare const RUN_START_NOT_APPROVED = "run not started: phase 0 approval has not been granted";
+/**
+ * PHASE 0 — THE GATE CANNOT BE RAISED BEFORE THERE IS A SPEC TO DECIDE ABOUT.
+ *
+ * THE DEFECT. `recursive_init` scaffolds Phase 0 as a TEMPLATE, and `recursive_ask gate=run-start` raised
+ * "start this run or hold?" over it immediately — while every requirement was still `<short title>`, every
+ * acceptance criterion was still `[observable condition 1]`, and nothing put the document in front of the
+ * person at all. The owner: *"the card ui for accepting the spec appeared, but i was never shown the spec
+ * before that so how could i approve if i havent seen it"*. Approving an unfilled template is not a decision
+ * about a spec; there is no spec yet, and a card that asks the question anyway teaches a person to answer
+ * without reading.
+ *
+ * ⚠ WHAT THIS DOES *NOT* TOUCH. It does not weaken the gate's own contract, it does not add a second way to
+ * start a run, and it does not make the plugin the decider: it only refuses to ASK. A person's own answer
+ * still wins (`recordRunStartAnswer` is unchanged), a spec still creates no goal, and cancellation / abort /
+ * timeout are still unrelayable. The check runs BEFORE the question is put to anybody, so no card is shown
+ * for a document that cannot be approved meaningfully.
+ *
+ * ⚠ AND IT IS A CHECK ON THE DOCUMENT, NOT ON THE CALLER. A `runId` that does not resolve is not this
+ * refusal's business — the ask path already reports that — so the guard says `ok: true` there and lets the
+ * existing route handle it.
+ */
+export declare function runStartSpecGuard(root: string, runId: string): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@try-works/dsh-recursive-mode",
   "description": "recursive-mode workflow as a DeepSeek Harness bundle: RecursiveRuntime service + 13 recursive_* tools (recursive_status, recursive_init, recursive_lock, recursive_lint, recursive_closeout, recursive_scratch, recursive_worktree, recursive_phase, recursive_audit_team, recursive_review, recursive_delegate, recursive_ask, recursive_preview)",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/src/client/contract.ts

@@ -62,6 +62,16 @@ export interface ClientSlots {
 /** A registered slot's options. */
 export interface SlotOptions {
   name: string
+  /**
+   * The dispatch key of a KEYED seat (`tool.call.toolview` is one), required there and ignored elsewhere.
+   *
+   * ⚠ THIS FIELD WAS MISSING AND ITS ABSENCE WAS NOT COSMETIC: `slots.ts` registers the run-start spec sheet
+   * on `tool.call.toolview` under the tool's wire name, and the harness's own options type makes `key`
+   * mandatory for a keyed slot (`KindOptions` in `packages/client/ui-slots`, where a keyed registration with
+   * no key THROWS `keyed slot "<name>" requires options.key`). Without the field here the face did not match
+   * the API it describes, so `tsc --noEmit` rejected the registration and the sheet was unreachable code.
+   */
+  key?: string
   id?: string
   order?: number
   label?: string