@try-works/dsh-recursive-mode 0.5.0 → 0.6.0

package/lib/index.js

@@ -1,5 +1,5 @@
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
-import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { Service } from "@deepseek-ai/cordis";
 import { createHash, randomUUID } from "node:crypto";
@@ -1483,15 +1483,34 @@ const LOCK_TOOL_NAMES = /* @__PURE__ */ new Set(["recursive_lock", "recursive_lo
 * sentence; the predicate adds the blocking artifact and its status, which is
 * what distinguishes a guard refusal from `lockArtifact`'s own
 * `Prerequisite blockers:` error (`tests/guard-path.spec.ts` asserts both).
+*
+* ⚠ ISSUE 2 (b) — AND IT NAMES THE RUN IT READ, `ctx.runId`, as `[run: <id>]`.
+*
+* The blockers above are read FROM A DIRECTORY (`runDir`), and until this suffix existed the refusal said
+* only "an earlier phase must be locked first  00-requirements.md (DRAFT)" — a sentence with no run in it.
+* That is what let a refusal MIX TWO RUNS in one payload: a call naming run-b could be judged against
+* run-a's tree (the guard resolved the run from the filesystem, the tool from `args.runId`) and the caller
+* was told about `00-requirements.md (DRAFT)` while the guard-decision record said `runId: run-a` and the
+* gate-block ask said `artifact: 01-as-is.md`. The blocking artifact, the artifact the caller named and the
+* run the record attributed it to were three answers to one question.
+*
+* The fix is two-sided: the guard now judges the run the CALL NAMES (see `resolveGuardRunId` in
+* `enforcement.ts`), and this suffix makes the evaluated run part of the sentence, so the payload can be
+* read without cross-referencing the log record — and a reader can SEE which run was read, which is what
+* makes a future mismatch visible instead of silent.
+*
+* `runId` is optional because the pure policy layer may be called with no run context at all (a policy
+* unit test, a preview probe): the sentence is then exactly what it always was, and no run is invented.
 */
-function lockOrderRule(artifact, runDir) {
+function lockOrderRule(artifact, runDir, runId) {
 	const name = String(artifact ?? "");
 	if (!name || !runDir) return null;
 	const blockers = getPrerequisiteBlockers(runDir, name);
 	if (blockers.length === 0) return null;
+	const where = typeof runId === "string" && runId.trim() !== "" ? " [run: " + runId.trim() + "]" : "";
 	return {
 		verdict: "deny",
-		detail: blockers.map((b) => b.artifact + " (" + b.status + ")").join(", "),
+		detail: blockers.map((b) => b.artifact + " (" + b.status + ")").join(", ") + where,
 		blockers
 	};
 }
@@ -1622,7 +1641,7 @@ function builtInToolPolicyRules() {
 		verdict: "deny",
 		reason: "monotonic lock-order: an earlier phase must be locked first",
 		label: "lock-order",
-		predicate: (id, args, ctx) => LOCK_TOOL_NAMES.has(id) ? lockOrderRule(args.artifact, ctx.runDir) : null
+		predicate: (id, args, ctx) => LOCK_TOOL_NAMES.has(id) ? lockOrderRule(args.artifact, ctx.runDir, ctx.runId) : null
 	}];
 	for (const name of WRITE_TOOL_NAMES) rules.push({
 		pattern: name,
@@ -1674,7 +1693,7 @@ function attachPolicyPredicate(rule) {
 	if (rule.predicate) return rule;
 	if (rule.pattern === "recursive_lock*") return {
 		...rule,
-		predicate: (id, args, ctx) => LOCK_TOOL_NAMES.has(id) ? lockOrderRule(args.artifact, ctx.runDir) : null
+		predicate: (id, args, ctx) => LOCK_TOOL_NAMES.has(id) ? lockOrderRule(args.artifact, ctx.runDir, ctx.runId) : null
 	};
 	if (rule.label === "phase-order") return {
 		...rule,
@@ -2028,6 +2047,66 @@ const SECTION_MAP = {
 	]
 };
 /**
+* T40 — `.recursive/memory/`, the plane THIS plugin writes, and the phase-8 step that was prose.
+*
+* ⚠ WHY THIS EXISTS, MEASURED. Three completed runs in a live workspace left `.recursive/memory/`
+* exactly as `bootstrap.ts` scaffolded it: `MEMORY.md` and the skill docs were still the
+* bootstrap-created placeholders, while run 03's `08-memory-impact.md` had its
+* "Write the durable ones to memory, with provenance" box TICKED and its `Inputs` line naming
+* ANOTHER plugin's store (`memory_search` / `memory_status` is dsh-memory, not this plugin). So the
+* phase declared its memory step done against a system this plugin does not own, and the plugin's
+* own learning never activated — the owner's words: *"the agent should write to .recursive/memory/
+* in phase 8, that's a hard requirement that needs to be enforced"*.
+*
+* ⚠ THE FIX IS A FACT, NOT A STRONGER SENTENCE. A prose step is ticked by the agent that would have
+* had to do it, which is exactly what happened. What follows is the same requirement in the form the
+* workflow can CHECK: a path under the plane, declared in the artifact, whose own text on disk
+* carries this run's provenance (`Source-Runs`). "The run wrote its durable memory" then stops being
+* a claim about the run's intentions and becomes a claim about files.
+*
+* ⚠ WHY IT IS NOT IN `SECTION_MAP`, deliberately: that map is byte-parity with the canonical
+* linter's `get_artifact_required_sections` (`tests/phase-rules.parity.spec.ts` pins all twelve
+* lists), and a section added there would be a parity break dressed up as a feature. The requirement
+* rides on a section the canonical template ALREADY scaffolds — `## Affected Memory Docs` — plus a
+* field the plane's own linter already requires, so the artifact shape stays canonical.
+*/
+const PHASE8_MEMORY_ARTIFACT = "08-memory-impact.md";
+const PHASE8_MEMORY_WRITE_RULE = {
+	artifact: PHASE8_MEMORY_ARTIFACT,
+	plane: ".recursive/memory/",
+	section: "Affected Memory Docs",
+	provenanceField: "Source-Runs",
+	alwaysAvailable: ".recursive/memory/episodes/<run-id>.md",
+	kinds: Object.keys({
+		domain: {
+			dir: ".recursive/memory/domains",
+			type: "domain"
+		},
+		pattern: {
+			dir: ".recursive/memory/patterns",
+			type: "pattern"
+		},
+		incident: {
+			dir: ".recursive/memory/incidents",
+			type: "incident"
+		},
+		episode: {
+			dir: ".recursive/memory/episodes",
+			type: "episode"
+		},
+		skill: {
+			dir: ".recursive/memory/skills/patterns",
+			type: "pattern"
+		}
+	}),
+	summary: "HARD: this run must have WRITTEN at least one doc under .recursive/memory/ before 08-memory-impact.md locks — .recursive/memory/episodes/<run-id>.md is always available — declared by path under `## Affected Memory Docs` and carrying `Source-Runs: <this-run-id>`; citing a shard this run did not write does not count.",
+	instruction: "HARD REQUIREMENT, CHECKED AT LOCK: before 08-memory-impact.md locks, this run must have WRITTEN at least one doc under .recursive/memory/ and declared that path under `## Affected Memory Docs`. A declared path counts ONLY when the doc on disk carries `Source-Runs` naming THIS run, because that is what separates \"the run wrote its memory\" from \"the run cited someone else's\". Render the doc with the metadata the memory-plane lint requires (Type, Status, Scope, Owns-Paths, Watch-Paths, Source-Runs, Validated-At-Commit, Last-Validated, Tags): .recursive/memory/episodes/<run-id>.md is always available for a run-local lesson, `.recursive/memory/domains/`, `.recursive/memory/patterns/` and `.recursive/memory/incidents/` hold generalized knowledge, and `.recursive/memory/skills/patterns/` is where a promoted skill lesson belongs. A doc missing a required field, or carrying a Type/Status the plane lint rejects, FAILS the memory plane — write it in the canonical shape. The written path enters the run diff under .recursive/memory/, which phase 8 OWNS in its Worktree Diff Audit and Requirement Completion Status."
+};
+/** The memory-write rule for an artifact, or null when that phase owes no memory write. */
+function phase8MemoryWriteRuleFor(fileName) {
+	return fileName === "08-memory-impact.md" ? PHASE8_MEMORY_WRITE_RULE : null;
+}
+/**
 * get_artifact_required_sections(file_name, workflow_profile): canonical-parity
 * required section headings for a phase artifact. Defaults to TODO + Coverage
 * Gate + Approval Gate for unknown files. Audited phases in strict profiles get
@@ -2069,7 +2148,8 @@ function phaseRulesFor(fileName, workflowProfile = CURRENT_WORKFLOW_PROFILE) {
 		requiredSections: getArtifactRequiredSections(fileName, workflowProfile),
 		audited: AUDITED_PHASE_FILES$1.has(fileName),
 		tdd: fileName === "03-implementation-summary.md",
-		qa: fileName === "05-manual-qa.md"
+		qa: fileName === "05-manual-qa.md",
+		memoryWrite: phase8MemoryWriteRuleFor(fileName)
 	};
 }
 /**
@@ -2088,6 +2168,7 @@ function phaseLintRulesMessage(fileName, workflowProfile = CURRENT_WORKFLOW_PROF
 		"Audited phases: end with Audit: PASS before setting Coverage/Approval PASS; record Audit Context and Audit Verdict.",
 		"TDD (phase 3): declare TDD Mode: strict|pragmatic; strict requires RED + GREEN evidence paths.",
 		"QA (phase 5): declare QA Execution Mode: human|agent-operated|hybrid; human/hybrid need user sign-off.",
+		...rules.memoryWrite === null ? [] : ["Memory write (phase 8, HARD): " + rules.memoryWrite.summary],
 		"</system-reminder>"
 	].join("\n");
 }
@@ -2184,7 +2265,7 @@ function phaseBaselineRules(fileName) {
 		pattern: "write*",
 		verdict: "deny",
 		reason: "phase " + phase + " is a documentation phase: writes outside the run tree are denied (the implementation is frozen)",
-		predicate: (_id, args, ctx) => writesOutsideRunTree(args, ctx) ? { verdict: "deny" } : null
+		predicate: (_id, args, ctx) => writesOutsideRunTree(args, ctx) && !(phase === "8" && writesOwnMemoryPlane(args, ctx)) ? { verdict: "deny" } : null
 	});
 	if (phase === "6" || phase === "7") rules.push({
 		pattern: "write*",
@@ -2222,6 +2303,23 @@ function memoryPlanePath(abs) {
 	return /\/(decisions|state)\.md$/i.test(normalized) || /\/\.recursive\/memory(\/|$)/.test(normalized);
 }
 /**
+* True when the call writes `.recursive/memory/**` — THIS PLUGIN'S OWN plane, and nothing else.
+*
+* ⚠ DELIBERATELY NARROWER THAN {@link writesMemoryPlane}, which also matches `DECISIONS.md` and
+* `STATE.md`: phase 8's carve-out (T40) is about durable memory, not about handing phase 8 the two
+* planes phases 6-7 own.
+*
+* ⚠ AND AN UNRESOLVABLE TARGET IS `false` HERE — the OPPOSITE of every other fail-closed answer in
+* this file, because this is the PERMISSIVE branch: `true` means "do not deny", so a path the rules
+* cannot place must not be admitted by it. "We could not tell where this lands" is a reason to
+* refuse, never a reason to allow.
+*/
+function writesOwnMemoryPlane(args, ctx) {
+	const abs = baselineTarget(args, ctx);
+	if (abs === "unresolvable") return false;
+	return /\/\.recursive\/memory(\/|$)/.test(abs.replace(/\\/g, "/"));
+}
+/**
 * 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.
@@ -6326,10 +6424,23 @@ function defaultWrite(path, content) {
 * so the result is reproducible from the inputs alone.
 */
 /** The kinds this plugin's memory layer holds, in the order the scaffold creates them. */
+/**
+* ⚠ `training` IS IN THIS LIST BECAUSE IT IS THE KIND THE PLUGIN'S OWN TRAINING PATH WRITES.
+*
+* The phase-8 trigger (`training.ts`) writes `memory/training/<task-type>.md` and advertises that path in
+* `memory/MEMORY.md`; the shipped router (`references/bodies/memory-router.md`) tells an agent to load "the
+* relevant docs under `/.recursive/memory/training/`". With `training` absent from this list the loader
+* COULD NOT SEE THE SHARDS THE TRIGGER WROTE — the writer's own output was unreachable by the reader, so
+* "the plane's next run scores it" (README §10) was not true of exactly the shards training produces.
+*
+* `incidents/` and `archive/` stay out deliberately: `archive/` is historical by the router's own definition,
+* and widening retrieval to `incidents/` is a separate ranking decision that this change does not make.
+*/
 const MEMORY_KINDS = [
 	"domains",
 	"patterns",
 	"episodes",
+	"training",
 	"skills"
 ];
 /**
@@ -6454,6 +6565,27 @@ function entryAppliesTo(entry) {
 	if (!match || match[1] === void 0) return [];
 	return match[1].split(",").map((part) => part.replace(/[^0-9.]/g, "")).filter((part) => part !== "");
 }
+/**
+* Where the plane may live under a workspace root, in PREFERENCE order.
+*
+* ⚠ THE MEASURED DEFECT THIS FIXES. `defaultMemoryList` used to join `memory/<kind>/` straight onto the
+* root it was handed — i.e. `<root>/memory/` — and that directory EXISTS IN NO REAL WORKSPACE. `bootstrap.ts`
+* scaffolds the plane at `<root>/.recursive/memory/`, `ts-lint.ts` lints it there, and the review bundle reads
+* it there; this loader alone looked beside it. Measured live on a workspace whose `.recursive/memory/` was
+* scaffolded and whose `<root>/memory/` did not exist: `selectMemory` reported "the memory plane is empty"
+* over a plane that was there, every phase of every run — and the training shards `training.ts` writes were
+* therefore unreachable by the loader that is supposed to score them.
+*
+* ⚠ PREFER, THEN FALL BACK — NEVER MERGE. This is the rule `readFeedback` already follows for its own moved
+* sidecar (`memory-feedback.ts`: `FEEDBACK_FILE` then `LEGACY_FEEDBACK_FILE`): the current location wins, and
+* the earlier one is consulted ONLY when the current one yields nothing, because two snapshots of one shard
+* added together would count a shard twice and a duplicated shard would outrank a real one.
+*
+* ⚠ AND IT MAKES THE CALLER'S CONVENTION IRRELEVANT. Passing the workspace root resolves
+* `<root>/.recursive/memory/`; passing `.recursive` itself resolves through the second entry. Both are
+* accepted, which is what README §6 means by "using `.recursive` as the root is selected again".
+*/
+const MEMORY_PLANE_BASES = [".recursive/memory", "memory"];
 /** Read the whole plane, minus nothing: filtering is the SELECTOR's job, not the reader's. */
 function loadMemoryIndex(root, readFile = defaultMemoryRead, listFiles = (kind) => defaultMemoryList(root, kind)) {
 	return readMemoryEntries(readFile, listFiles);
@@ -6517,12 +6649,14 @@ function defaultMemoryRead(path) {
 	}
 }
 function defaultMemoryList(root, kind) {
-	const dir = join(root, "memory", kind);
-	try {
-		return readdirSync(dir).filter((name) => name.endsWith(".md")).map((name) => join(dir, name));
-	} catch {
-		return [];
+	for (const base of MEMORY_PLANE_BASES) {
+		const dir = join(root, base, kind);
+		try {
+			const files = readdirSync(dir).filter((name) => name.endsWith(".md")).map((name) => join(dir, name));
+			if (files.length > 0) return files;
+		} catch {}
 	}
+	return [];
 }
 //#endregion
 //#region src/training.ts
@@ -6551,7 +6685,7 @@ function defaultMemoryList(root, kind) {
 * history of a learning stays readable; and a PINNED entry is untouchable by every automatic path.
 */
 /** The artifact whose lock marks a run as complete enough to learn from. */
-const PHASE8_ARTIFACT = "08-memory-impact.md";
+const PHASE8_ARTIFACT = PHASE8_MEMORY_ARTIFACT;
 /** The parent's exit codes, kept as names so a caller cannot mistake one failure for the other. */
 const TRAINING_EXIT = {
 	/** The extractor could not be reached or run. */
@@ -6742,13 +6876,30 @@ function runPhase8Trigger(root, runId, options = {}) {
 *
 * ⚠ ONE ITEM PER RUN IS NAMED, so a reader can trace a learning back to the run that produced it —
 * and the group is never presented as more evidence than it is.
+*
+* ⚠ T40 — AND IT NOW CARRIES THE PLANE'S METADATA HEADER, which it did not before. `memory/domains/
+* <subsystem>.md` is a doc the memory-plane lint validates like any other, and this renderer wrote a
+* bare `# Learnings:` heading — so the plugin's own cross-run extraction produced a doc its own
+* `lint_memory_plane` FAILS for nine missing fields. The extraction was right and its output shape was
+* wrong, which is exactly the kind of defect a write surface exists to prevent.
 */
-function renderGroupShard(group) {
+function renderGroupShard(group, options = {}) {
+	const runs = [...new Set(group.items.map((item) => item.runId))];
 	const lines = [
+		...renderMemoryMetadata({
+			type: "domain",
+			status: "CURRENT",
+			scope: "Learnings extracted for subsystem " + group.subsystem + " (" + group.mode + ") from " + runs.length + " run(s).",
+			sourceRuns: runs,
+			validatedAtCommit: "extracted-at-run-close",
+			lastValidated: options.lastValidated ?? isoSeconds(),
+			tags: [group.subsystem, group.mode]
+		}).trimEnd().split("\n"),
+		"",
 		"# Learnings: " + group.subsystem,
 		"",
 		"- Mode: " + group.mode,
-		"- Runs: " + group.runs + " (" + [...new Set(group.items.map((item) => item.runId))].join(", ") + ")",
+		"- Runs: " + group.runs + " (" + runs.join(", ") + ")",
 		""
 	];
 	for (const item of group.items) lines.push("- [" + item.runId + "] " + item.text);
@@ -6909,8 +7060,20 @@ function updateMemoryRegistry(existing, entries) {
 function taskTypeShardPath(mode) {
 	return "memory/training/" + mode + ".md";
 }
-function renderTaskTypeShard(groups) {
+/** T40: same metadata-header reason as {@link renderGroupShard} — see the note there. */
+function renderTaskTypeShard(groups, options = {}) {
+	const runs = [...new Set(groups.flatMap((group) => group.items.map((item) => item.runId)))];
 	const lines = [
+		...renderMemoryMetadata({
+			type: "pattern",
+			status: "CURRENT",
+			scope: "Training shards extracted under mode " + groups[0].mode + ", one section per subsystem group.",
+			sourceRuns: runs,
+			validatedAtCommit: "extracted-at-run-close",
+			lastValidated: options.lastValidated ?? isoSeconds(),
+			tags: ["training", groups[0].mode]
+		}).trimEnd().split("\n"),
+		"",
 		"# Training shards: " + groups[0].mode,
 		"",
 		"Groups extracted under this mode, one section each. Learning happens through files, not model mutation.",
@@ -6975,6 +7138,41 @@ function extractAndGroup(runner, env, options = {}) {
 		groups: groupLearnings(items, options.isWinner ?? (() => true))
 	};
 }
+/** `2026-10-10T08:39:59Z` — the lock fields' own timestamp shape, and the docs' `Last-Validated` one. */
+function isoSeconds(now = /* @__PURE__ */ new Date()) {
+	return now.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+function bullets(values) {
+	return (values ?? []).map((value) => "- `" + value.replace(/`/g, "'") + "`");
+}
+/**
+* The metadata header every durable doc carries: the nine fields `lint_memory_doc` requires, in the
+* order the SHIPPED docs use them (`Owns-Paths:` / `Watch-Paths:` / `Tags:` stand bare when empty,
+* which is what the workspace's own promoted docs do and what `has_header_field` accepts).
+*
+* ⚠ A BACKTICK INSIDE A FIELD VALUE IS REPLACED, NOT ESCAPED, because these values are read back by
+* a line-based field reader: a stray backtick would end the value early and leave the rest of the
+* sentence in the doc as if it were a field.
+*/
+function renderMemoryMetadata(input) {
+	const lines = [
+		"Type: `" + input.type + "`",
+		"Status: `" + input.status + "`",
+		"Scope: `" + input.scope.replace(/`/g, "'") + "`",
+		"Owns-Paths:",
+		...bullets(input.ownsPaths),
+		"Watch-Paths:",
+		...bullets(input.watchPaths),
+		"Source-Runs:",
+		...bullets(input.sourceRuns),
+		"Validated-At-Commit: `" + input.validatedAtCommit.replace(/`/g, "'") + "`",
+		"Last-Validated: `" + input.lastValidated.replace(/`/g, "'") + "`",
+		"Tags:",
+		...bullets(input.tags)
+	];
+	if (input.parent !== void 0 && input.parent.trim() !== "") lines.push("Parent: `" + input.parent.replace(/`/g, "'") + "`");
+	return lines.join("\n") + "\n";
+}
 //#endregion
 //#region src/run-spec.ts
 /** The named evidence classes, so a reader can tell a placeholder from an unmet gate. */
@@ -7724,6 +7922,75 @@ async function askRunStartDirectly(channel, exec) {
 	}
 }
 //#endregion
+//#region src/run-id.ts
+/**
+* A RUN ID IS A NAME, NOT A PATH.
+*
+* WHY THIS MODULE EXISTS. Every consumer of a run id JOINS it onto a directory
+* that already carries the meaning "the run layer":
+*
+*     join(root, '.recursive', 'run', runId)   // runtime.ts, run.ts, handoff.ts, scratch.ts
+*     join(repoRoot, '.worktrees', runId)      // worktree.ts (a linked worktree)
+*     'recursive/' + runId                     // worktree.ts (the run's git branch)
+*
+* `join` is a PATH operation: absolute paths, drive specifiers and `..` segments
+* are all legal input to it, and each one silently changes what the call means.
+* A caller who passes `E:\tmp\rm-live-diagnostics\01-calculator-lib` is asking
+* for a run "on another drive"; what they get is a `mkdir` of
+*
+*     <workspace>\.recursive\run\E:\tmp\rm-live-diagnostics\01-calculator-lib
+*
+* which is not drive-qualified at all — on POSIX and Windows alike the colon is
+* just another character in a relative component. The result is a bogus nested
+* folder INSIDE the workspace, created before anything can refuse it, surfacing
+* far away as an ENOENT-shaped runtime failure (RM5501) with the operator's
+* filesystem already dirty.
+*
+* SO THE RULE IS ENFORCED WHERE THE NAME ENTERS, and NOT by teaching the runtime
+* to accept a path. The joins in `runtime.ts` are CORRECT for a name; what was
+* missing was a gate on the name. Do not "fix" this back: a run on another drive
+* or in a worktree is reached through the session's control-plane root
+* (`recursive_worktree`, `00-worktree.md`) — the run layer is never relocated by
+* smuggling a path into the id.
+*
+* The charset below is deliberately the SAME one the read path already uses
+* (`live-route.ts` `DOC_SAFE_RE`) so a name this gate accepts is a name that
+* route can serve.
+*/
+/**
+* The accepted shape, as prose that can be embedded in a model-facing parameter
+* description and in a refusal detail, so the rule is stated once.
+*/
+const RUN_ID_RULE = "letters, digits, dot, underscore or dash only, no leading or trailing dot, no path separator, no drive specifier and no \"..\" segment";
+/** Directory-name charset — the read path's `DOC_SAFE_RE`, verbatim. */
+const RUN_ID_CHARS = /^[A-Za-z0-9._-]+$/;
+/**
+* Why a run id is refused, or `null` when it is a usable NAME.
+*
+* The returned string is the SPECIFIC problem (which rule the id broke), with no
+* trailing punctuation and no sentence of its own, so a caller can hand it to
+* `toolError('BAD_RUN_ID', …)` as the detail. `RUN_ID_RULE` states the shape.
+*
+* The order of the checks is part of the message quality: a Windows absolute
+* path is reported as a drive-qualified path (what the caller passed) rather
+* than as a separator complaint (what that path is made of).
+*/
+function runIdProblem(raw) {
+	if (raw === "") return "runId is empty";
+	if (raw.length > 100) return "runId is " + raw.length + " characters, over the 100 allowed";
+	if (/^[A-Za-z]:/.test(raw)) return "runId is a Windows drive-qualified path, starting with \"" + raw.slice(0, 2) + "\"";
+	if (raw.includes("/") || raw.includes("\\")) return "runId contains the path separator \"" + (raw.includes("/") ? "/" : "\\") + "\"";
+	if (raw.includes(":")) return "runId contains a colon (\":\"), which is a drive and stream separator on Windows";
+	if (raw.includes("..")) return "runId contains a \"..\" segment, which escapes the run directory";
+	if (raw.startsWith(".")) return "runId starts with \".\", which makes it a hidden name or a relative path segment";
+	if (raw.endsWith(".")) return "runId ends with \".\"";
+	if (!RUN_ID_CHARS.test(raw)) {
+		if (/\s/.test(raw)) return "runId contains a space or other whitespace character inside the name";
+		return "runId contains a character outside the allowed set";
+	}
+	return null;
+}
+//#endregion
 //#region src/lifecycle.ts
 /**
 * Transition gate validation + goal coupling (Phase C R1/R2/R6, PROPOSAL 8.4).
@@ -7982,6 +8249,64 @@ function currentPhaseArtifact(worktreeRoot, runId) {
 	return inForce !== "" ? inForce : best;
 }
 /**
+* ISSUE 2 (a) — THE RUN A GUARD CALL IS ABOUT, and the one whose tree it may read.
+*
+* THE DEFECT THIS ANSWERS, measured before the fix: `recursive_lock {runId: 'run-b', artifact:
+* '01-as-is.md'}` was REFUSED with `monotonic lock-order: … 00-requirements.md (DRAFT)` — run-A's blocker —
+* while `run-b` had `00-requirements.md` LOCKED and `01-as-is.md` DRAFT, so locking it in run-b was LEGAL.
+* The guard resolved the run from the FILESYSTEM (`resolveRunDir`, i.e. the active/newest run) while the
+* tool resolves it from `args.runId`, so the guard judged a DIFFERENT RUN than the call was about. Under
+* `advisory` the deny was coerced to an allow-with-warning and the tool refused on its own terms, which is
+* why the strict default is what made it bite.
+*
+* SO THE RULE IS: for a LOCK call that NAMES a run, the guard judges THAT RUN. It is the same choice the
+* tool makes, so the two layers cannot disagree about which tree the ordering rule is a property of. A
+* caller that names nothing (every real `write`, and a lock that relies on the active run) is unaffected:
+* the active run still governs, which is what the write-side rules rely on.
+*
+* ⚠ THIS IS SCOPED TO THE LOCK TOOLS DELIBERATELY, and the scope is per rule, not per convenience:
+*
+*   - `lock-order` (`recursive_lock*`) — the caller's run WINS. The tool acts on `args.runId`, and the
+*     rule is about THAT run's prerequisites, so the guard must not answer for another run. This is the
+*     measured defect.
+*   - `locked-write` (the write-tool family) — NOT APPLICABLE, by construction: the rule resolves no run
+*     at all. It reads the target file's own `Status:` through the path the caller named, so there is no
+*     run to prefer and nothing could disagree.
+*   - `phase-order` (the write-tool family) — the ACTIVE run KEEPS WINNING, and this function does not
+*     touch it. Two reasons, both deliberate: (1) a `write` call carries no run id — no write tool declares
+*     one — so consulting `args.runId` here would hand a caller a way to ESCAPE the active run's ordering
+*     by naming some other run in an argument the tool ignores; and (2) the rule's declared scope is the
+*     run being worked in (it abstains for another run's tree, documented in `phaseOrderRule`), and moving
+*     that scope would be a new refusal, not a consistency fix.
+*
+* ⚠ A CALLER-SUPPLIED ID IS A NAME, NEVER A PATH, and it is validated before it can point the guard at
+* anything: the id is trimmed the way `recursive_lock` trims it, then put through `runIdProblem` — the
+* SAME gate the run-id-shaped tools use, which refuses separators, drive specifiers, `..`, a colon, a
+* leading/trailing dot and an over-long name — and finally the resolved directory must sit UNDER this
+* worktree's `<root>/.recursive/run`, the containment rule `runtime.ts` applies to a run directory.
+*
+* An id that fails any of those is NOT USED: the guard falls back to the active run, exactly as it behaved
+* before this change. Falling back (rather than denying) is deliberate: an unusable id is a caller mistake
+* the tool itself refuses (`BAD_RUN_ID` / `Artifact not found`), and inventing a new guard refusal for it
+* would be a second, competing answer to a question `runIdProblem` already owns.
+*
+* A usable id does NOT have to name an EXISTING run: a run with no tree has no unlocked prerequisites, so
+* the ordering rule abstains and the LOCK TOOL still refuses the lock (it checks the artifact exists before
+* anything else). Requiring existence would instead re-introduce the defect in its ugliest form — a refusal
+* built from ANOTHER run's blockers.
+*/
+function resolveGuardRunId(name, args, worktreeRoot, activeRunId) {
+	if (!LOCK_TOOL_NAMES.has(name) || !worktreeRoot) return activeRunId;
+	const raw = args.runId;
+	if (typeof raw !== "string") return activeRunId;
+	const declared = raw.trim();
+	if (declared === "" || runIdProblem(declared) !== null) return activeRunId;
+	const runRoot = resolve(worktreeRoot, ".recursive", "run");
+	const prefix = runRoot.endsWith(sep) ? runRoot : runRoot + sep;
+	if (!resolve(join(runRoot, declared)).startsWith(prefix)) return activeRunId;
+	return declared;
+}
+/**
 * `mode` is the gate's configured posture. Its parameter default FOLLOWS the config
 * default by REFERENCE (`DEFAULT_ENFORCEMENT.toolGuards`) rather than repeating the
 * literal: a bare call is "the caller had no mode to hand", and the answer to that must
@@ -7996,17 +8321,20 @@ function currentPhaseArtifact(worktreeRoot, runId) {
 function evaluateToolGuard(exec, worktreeRoot, activeRunId, mode = DEFAULT_ENFORCEMENT.toolGuards) {
 	const name = exec.name;
 	const args = exec.arguments ?? {};
-	const runId = typeof activeRunId === "string" ? activeRunId.trim() : "";
+	const runId = resolveGuardRunId(name, args, worktreeRoot, typeof activeRunId === "string" ? activeRunId.trim() : "");
 	const runDir = join(worktreeRoot, ".recursive", "run", runId);
 	const transition = consultTransitionGate(name, args, worktreeRoot, runId);
 	const activePhaseArtifact = currentPhaseArtifact(worktreeRoot, runId);
-	return advisory(verdictFor(mode, evaluateToolPolicy(resolveToolPolicyForGuard(worktreeRoot, runId, activePhaseArtifact), name, args, {
-		args,
-		runDir,
-		runId,
-		worktreeRoot,
-		activePhaseArtifact
-	}), String(args.artifact ?? "")), transition);
+	return {
+		...advisory(verdictFor(mode, evaluateToolPolicy(resolveToolPolicyForGuard(worktreeRoot, runId, activePhaseArtifact), name, args, {
+			args,
+			runDir,
+			runId,
+			worktreeRoot,
+			activePhaseArtifact
+		}), String(args.artifact ?? "")), transition),
+		runId
+	};
 }
 /**
 * Map the policy's verdict onto the guard's decision kind: `strict` denies,
@@ -10751,14 +11079,14 @@ var RecursiveRuntime = class extends Service {
 					responseFile: join(runDir, "training-response.json")
 				}),
 				write: (relativePath, content) => {
-					const target = join(root, relativePath);
+					const target = join(root, ".recursive", relativePath);
 					mkdirSync(dirname(target), { recursive: true });
 					writeFileSync(target, content, "utf8");
 					return relativePath;
 				},
 				readText: (relativePath) => {
 					try {
-						return readFileSync(join(root, relativePath), "utf8");
+						return readFileSync(join(root, ".recursive", relativePath), "utf8");
 					} catch {
 						return null;
 					}
@@ -11874,75 +12202,6 @@ function createRecursiveStatusTool(recursive) {
 	});
 }
 //#endregion
-//#region src/run-id.ts
-/**
-* A RUN ID IS A NAME, NOT A PATH.
-*
-* WHY THIS MODULE EXISTS. Every consumer of a run id JOINS it onto a directory
-* that already carries the meaning "the run layer":
-*
-*     join(root, '.recursive', 'run', runId)   // runtime.ts, run.ts, handoff.ts, scratch.ts
-*     join(repoRoot, '.worktrees', runId)      // worktree.ts (a linked worktree)
-*     'recursive/' + runId                     // worktree.ts (the run's git branch)
-*
-* `join` is a PATH operation: absolute paths, drive specifiers and `..` segments
-* are all legal input to it, and each one silently changes what the call means.
-* A caller who passes `E:\tmp\rm-live-diagnostics\01-calculator-lib` is asking
-* for a run "on another drive"; what they get is a `mkdir` of
-*
-*     <workspace>\.recursive\run\E:\tmp\rm-live-diagnostics\01-calculator-lib
-*
-* which is not drive-qualified at all — on POSIX and Windows alike the colon is
-* just another character in a relative component. The result is a bogus nested
-* folder INSIDE the workspace, created before anything can refuse it, surfacing
-* far away as an ENOENT-shaped runtime failure (RM5501) with the operator's
-* filesystem already dirty.
-*
-* SO THE RULE IS ENFORCED WHERE THE NAME ENTERS, and NOT by teaching the runtime
-* to accept a path. The joins in `runtime.ts` are CORRECT for a name; what was
-* missing was a gate on the name. Do not "fix" this back: a run on another drive
-* or in a worktree is reached through the session's control-plane root
-* (`recursive_worktree`, `00-worktree.md`) — the run layer is never relocated by
-* smuggling a path into the id.
-*
-* The charset below is deliberately the SAME one the read path already uses
-* (`live-route.ts` `DOC_SAFE_RE`) so a name this gate accepts is a name that
-* route can serve.
-*/
-/**
-* The accepted shape, as prose that can be embedded in a model-facing parameter
-* description and in a refusal detail, so the rule is stated once.
-*/
-const RUN_ID_RULE = "letters, digits, dot, underscore or dash only, no leading or trailing dot, no path separator, no drive specifier and no \"..\" segment";
-/** Directory-name charset — the read path's `DOC_SAFE_RE`, verbatim. */
-const RUN_ID_CHARS = /^[A-Za-z0-9._-]+$/;
-/**
-* Why a run id is refused, or `null` when it is a usable NAME.
-*
-* The returned string is the SPECIFIC problem (which rule the id broke), with no
-* trailing punctuation and no sentence of its own, so a caller can hand it to
-* `toolError('BAD_RUN_ID', …)` as the detail. `RUN_ID_RULE` states the shape.
-*
-* The order of the checks is part of the message quality: a Windows absolute
-* path is reported as a drive-qualified path (what the caller passed) rather
-* than as a separator complaint (what that path is made of).
-*/
-function runIdProblem(raw) {
-	if (raw === "") return "runId is empty";
-	if (raw.length > 100) return "runId is " + raw.length + " characters, over the 100 allowed";
-	if (/^[A-Za-z]:/.test(raw)) return "runId is a Windows drive-qualified path, starting with \"" + raw.slice(0, 2) + "\"";
-	if (raw.includes("/") || raw.includes("\\")) return "runId contains the path separator \"" + (raw.includes("/") ? "/" : "\\") + "\"";
-	if (raw.includes(":")) return "runId contains a colon (\":\"), which is a drive and stream separator on Windows";
-	if (raw.includes("..")) return "runId contains a \"..\" segment, which escapes the run directory";
-	if (raw.startsWith(".")) return "runId starts with \".\", which makes it a hidden name or a relative path segment";
-	if (raw.endsWith(".")) return "runId ends with \".\"";
-	if (!RUN_ID_CHARS.test(raw)) {
-		if (/\s/.test(raw)) return "runId contains a space or other whitespace character inside the name";
-		return "runId contains a character outside the allowed set";
-	}
-	return null;
-}
-//#endregion
 //#region src/recursive_init.tool.ts
 /**
 * PHASE 0 — SCAFFOLDING IS NOT STARTING, AND THE TOOL SAYS SO AT THE MOMENT IT MATTERS.
@@ -13245,10 +13504,12 @@ function createRecursivePreviewTool(recursive) {
 * Idempotent scaffold installer (R3). TS port of install-recursive-mode.py's
 * core: bootstrap the FULL canonical /.recursive/ control plane + cross-tool
 * bridges byte-identically (RECURSIVE.md marker-wrapped, AGENTS.md, STATE/
-* DECISIONS, memory routers + shards, config/recursive-router.json, .gitignore,
-* vendored runtime scripts copied into .recursive/scripts/), plus the
-* agent/session-start Stage B (new vs resume) workspace-scoped to the session's
-* control-plane root (R1).
+* DECISIONS, memory routers + shards, config/recursive-router.json, .gitignore),
+* plus the agent/session-start Stage B (new vs resume) workspace-scoped to the
+* session's control-plane root (R1).
+*
+* ⚠ NO `.recursive/scripts/` IS CREATED, and a legacy one is removed once it is empty — see the block in
+* the scaffold below for the measurement that decided it.
 *
 * Templates + bodies + runtime scripts are SHIPPED package files under
 * references/ (never inlined TS string literals) and resolved relative to this
@@ -13485,11 +13746,13 @@ function bootstrapScaffold(root) {
 		".recursive/memory/skills/patterns/.gitkeep",
 		".recursive/run/.gitkeep"
 	]) noteFile(rel, "");
-	noteDir(".recursive/scripts");
 	{
 		const scriptsDir = join(recursiveRoot, "scripts");
 		if (existsSync(scriptsDir)) {
 			for (const name of readdirSync(scriptsDir)) if (name.endsWith(".py") || name.endsWith(".ps1")) rmSync(join(scriptsDir, name), { force: true });
+			try {
+				if (readdirSync(scriptsDir).length === 0) rmdirSync(scriptsDir);
+			} catch {}
 		}
 	}
 	noteFile(".recursive/RECURSIVE.md", "# RECURSIVE.md\n");
@@ -14735,15 +14998,17 @@ function runToolGuard(recursive, exec, root, runId) {
 	const guardMode = recursive.enforcementConfig.toolGuards;
 	const decision = evaluateToolGuard(exec, root, runId, guardMode);
 	const coerced = coerceAskToDecision(decision, guardMode);
+	const evaluatedRunId = decision.runId ?? runId;
 	const final = coerced === decision ? decision : {
 		...coerced,
 		rule: decision.rule,
-		transition: decision.transition
+		transition: decision.transition,
+		runId: evaluatedRunId
 	};
 	if (root) {
 		const record = {
 			at: (/* @__PURE__ */ new Date()).toISOString(),
-			runId,
+			runId: evaluatedRunId,
 			tool: exec?.name ?? "",
 			kind: final.kind,
 			rule: final.rule ?? "none"
@@ -14757,6 +15022,54 @@ function runToolGuard(recursive, exec, root, runId) {
 	}
 	return final;
 }
+/**
+* ISSUE 1 — THE GOAL BLOCK, FROM THE LAYER THAT REFUSED.
+*
+* WHERE THIS BELONGS, decided from the code rather than assumed: the GUARD CANNOT DO THIS ITSELF.
+* `evaluateToolGuard` is a pure policy layer — it takes an exec, a worktree root, a run id and a mode, and
+* it has no goals service, no live agent and no runtime handle; it is also called from a dry-run preview
+* (`src/recursive_preview.tool.ts`), where a side effect would be a lie about a call that never happened.
+* The ONE place where a guard refusal becomes real is the `tools/pre-execute` listener below: it holds the
+* runtime (which owns `blockRunToGoal` and the late-attached goals service), the live agent from the exec
+* payload, and the decision itself — and it is the same boundary that already renders the refusal's ask
+* into the caller's text (FU-7). So this is called there, and nowhere else.
+*
+* WHY IT IS NEEDED AT ALL. `lockArtifact` blocks the run's goal when its OWN ordering check refuses
+* (`runtime.ts`, the `Prerequisite blockers:` branch). Under the strict default the guard refuses an
+* out-of-order lock BEFORE DISPATCH, so `lockArtifact` never runs, its block never happens, and the run was
+* told it was blocked while the goal machinery was not — the goal stayed armed and kept driving rounds
+* through a refused gate.
+*
+* ⚠ WHY THIS CANNOT DOUBLE-BLOCK. The two block sites are on MUTUALLY EXCLUSIVE branches of one call:
+* this one runs only when the guard DENIED (so the tool is never dispatched), and the tool's own block runs
+* only when the guard let the call through to `lockArtifact`. One refusal, one dispatch decision, one
+* block. A repeat of the SAME refused call re-enters this branch, and the second block is refused by the
+* goal service itself (`block` requires an ACTIVE goal; an already-blocked goal is not active), which is
+* swallowed here exactly as the tool path swallows it — the goal stays blocked, and it is not blocked
+* twice.
+*
+* ⚠ THE TRIGGER IS THE ASK, NOT THE RULE LABEL — the same trigger FU-7 uses, for the same reason: an ask is
+* present exactly when the refusal was DECIDED FROM REAL ORDERING BLOCKERS (`PolicyDecision.blockers` read
+* from disk), which includes a policy FILE whose `recursive_lock*` deny carries no label (its `rule` reads
+* `none`). Gating on the label instead would silently skip the goal block in every repo that ships a policy
+* file — the shipped default here.
+*
+* ⚠ AND IT IS THE LOCK ORDERING REFUSAL ONLY. The phase-order WRITE rule refuses a write ahead of the
+* active phase, and it has NO tool-layer counterpart that blocks a goal — `lockArtifact` is the only
+* tool-side blocker in the plugin. Blocking a goal on it would be a NEW behaviour, not the consistency this
+* fix is for: the defect was one refusal with two layers disagreeing, not a rule that should start
+* blocking.
+*/
+function blockGoalOnGuardRefusal(recursive, exec, decision, activeRunId) {
+	if (decision.kind !== "deny" || decision.ask === void 0) return;
+	const agent = exec?.agent ?? null;
+	try {
+		recursive.blockRunToGoal(agent, decision.runId ?? activeRunId, {
+			code: "prerequisite-blockers",
+			message: decision.reason ?? "the lock was refused: its prerequisites are unmet"
+		});
+	} catch {}
+}
 function apply(ctx, config) {
 	if (config?.shellOnly) return;
 	ctx.effect(function* () {
@@ -14907,10 +15220,13 @@ function apply(ctx, config) {
 				kind: "deny",
 				reason: "the tool guard produced no decision"
 			};
-			if (final.kind === "deny") return final.ask === void 0 ? final : {
-				...final,
-				reason: final.reason + " " + renderGateBlockAsk(final.ask)
-			};
+			if (final.kind === "deny") {
+				blockGoalOnGuardRefusal(recursive, exec, final, runId);
+				return final.ask === void 0 ? final : {
+					...final,
+					reason: final.reason + " " + renderGateBlockAsk(final.ask)
+				};
+			}
 			if (final.kind === "allow" && final.warn) console.warn("[recursive] tool guard (" + recursive.enforcementConfig.toolGuards + ") allowed this call: " + final.warn);
 			return typeof next === "function" ? next() : { kind: "allow" };
 		}));
@@ -15028,4 +15344,4 @@ function apply(ctx, config) {
 	});
 }
 //#endregion
-export { Config, DEFAULT_BUDGETS, DEFAULT_ENFORCEMENT, DEFAULT_ENFORCEMENT_MODE, 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 };
+export { Config, DEFAULT_BUDGETS, DEFAULT_ENFORCEMENT, DEFAULT_ENFORCEMENT_MODE, 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, resolveGuardRunId, resolveRole, resolveRunDir, resolveToolPolicyForGuard, reviewBundleDir, reviewOutputSchema, routerPolicyPath, snapshotWorkspace, tamperCandidatePath, trimMdValue, validateChain, validateReferences, validateTransition, writeActionRecord, writeReceipt };