@try-works/dsh-recursive-mode 0.6.1 → 0.7.0

package/lib/enforcement.d.ts

@@ -90,8 +90,13 @@ export declare const DEFAULT_ENFORCEMENT: EnforcementConfig;
  * active phase must be locked before proceeding to next phase*: `'lock-order'` refuses
  * locking ahead, `'phase-order'` refuses WRITING ahead. Two labels rather than one,
  * because the guard log has to tell the owner which of the two the agent attempted.
+ *
+ * `'memory-read'` is the third WRITE-side rule and the owner's other requirement, verbatim: *the memory must
+ * be read before writing requirements.md*. It rides the same write-tool family as `'phase-order'` (see
+ * `memoryReadRule` in `policy-globs.ts`) and is listed here because this union is what the guard's decision
+ * record is typed by — a label the record's type does not know is a label the log cannot honestly carry.
  */
-export type GuardRule = 'lock-order' | 'phase-order' | 'tdd-evidence' | 'locked-write' | 'transition' | 'none';
+export type GuardRule = 'lock-order' | 'phase-order' | 'memory-read' | 'tdd-evidence' | 'locked-write' | 'transition' | 'none';
 /** T15: the transition gate's verdict as attached to a decision (advisory only). */
 export interface GuardTransition {
     passed: boolean;

package/lib/index.js

@@ -640,6 +640,277 @@ function jsonValueIndent(value, depth) {
 	return "null";
 }
 //#endregion
+//#region src/memory-feedback.ts
+/**
+* Memory feedback (FU-13 P3) — which entries were injected into which run, and how that run turned out.
+*
+* ⚠ WHAT THIS IS, HONESTLY LABELLED: a COUNTER, not learning. `TRAINING.md` puts model training (the
+* reference's 58 KB GRPO script) out of scope for a workflow plugin. What is in scope is the loop that makes
+* retrieval improve with evidence: record what was injected, settle it against the run's outcome, and let the
+* selector prefer what has held up.
+*
+* ⚠ AND WHY THE COUNTERS LIVE IN A SIDECAR, NOT IN THE SHARDS. The memory plane's documents are
+* human-authored: a person writes the lesson. Rewriting one to bump a number would be the silent-overwrite
+* defect this repo already produced once (the closeout writing over phase documents), applied to the memory
+* plane. So the counters live in `.recursive/memory/.feedback.json`, which is machine-owned and disposable —
+* delete it and you lose ranking evidence, not knowledge.
+*
+* ⚠ NO TIMESTAMPS ANYWHERE: two runs with the same inputs must produce identical files, which is the same
+* discipline the lock receipts, the closeout receipts and the selection output all follow.
+*/
+/** Where the machine-owned counters live — inside the memory plane, but never a shard a person writes. */
+const FEEDBACK_FILE = ".recursive/memory/.feedback.json";
+/**
+* WHERE THE COUNTERS LIVED BEFORE the constant above carried its `.recursive/` prefix.
+*
+* ⚠ READ, BUT DELIBERATELY NEITHER MOVED NOR DELETED. Read, because evidence a previous run recorded is
+* not the plugin's to discard, and without the fallback the first settle after the move would start the
+* new file from an empty book — a counter lost silently, which is the one outcome ruled out. NOT moved,
+* because a delete is the single action that could re-create the very defect the prefix fixes: a legacy
+* file that is TRACKED and COMMITTED is absent from the run's diff while it is clean, so removing it
+* mid-run puts `D memory/.feedback.json` into the diff of every diff-audited phase authored before the
+* delete, which is the same retro-invalidation. Left alone, an untracked legacy file is in the diff from
+* the run's first phase (and is therefore accounted for), while a committed one stays invisible.
+* `readFeedback` prefers {@link FEEDBACK_FILE}, so the legacy counters are folded forward by the next
+* settle and this file then only sits there; it is machine-owned and disposable, so delete it by hand.
+*/
+const LEGACY_FEEDBACK_FILE = "memory/.feedback.json";
+/** Where a run records what it was shown. */
+const INJECTIONS_FILE = "memory-injections.json";
+/**
+* THE SUBJECT A READ-RECEIPT CARRIES, AND WHY IT CANNOT COLLIDE WITH A SHARD.
+*
+* ⚠ THE GAP THIS CLOSES, MEASURED. This file used to record only the SHARDS a phase was shown, so a phase
+* whose selection came back empty — the documented, legitimate state of a workspace with no memory plane —
+* left NO trace at all. "A record exists" and "the read happened" were therefore the same sentence, and a
+* gate that required the former would REFUSE FOREVER in a fresh workspace: there would be nothing to
+* record, so nothing would ever be recorded. `selectMemory` says it plainly (`memory.ts`): *"the memory
+* plane is empty, so nothing is injected"* is an ANSWER, not a failure.
+*
+* So the read is recorded as a FACT OF ITS OWN — a receipt saying "at this phase entry, the plane was read,
+* and this is what the read said" — instead of being inferred from what the read returned. An empty plane
+* produces a receipt like any other, which is what makes the gate satisfiable in a new repo.
+*
+* ⚠ AND THE SUBJECT IS A RESERVED NAME. A memory entry's `source` is the shard's own PATH
+* (`selectMemory` -> `loadMemoryIndex` -> `entry.source`), always a `.md` path under the memory plane, so
+* `memory-read:attempt` is not a name any plane entry can hold. That is the property a collision would
+* need to break the gate, and it is asserted in `tests/memory-feedback.spec.ts`.
+*/
+const MEMORY_READ_SOURCE = "memory-read:attempt";
+/**
+* Read the counters. A missing or unreadable file is an empty book, never an error.
+*
+* ⚠ THE LEGACY PATH IS A FALLBACK AND ONLY A FALLBACK: it is consulted when — and only when — there is
+* no usable file at {@link FEEDBACK_FILE} yet, which is exactly the first run after the path moved. The
+* two are never merged, because they are two SNAPSHOTS of one counter and adding them would count a run
+* twice. A file that exists at the current path but does not parse stays an empty book, which is what
+* this function has always promised: a corrupt sidecar is not an invitation to read a different file.
+*/
+function readFeedback(root, readFile = defaultRead$1) {
+	const current = readFile(join(root, FEEDBACK_FILE));
+	if (current !== null && current.trim() !== "") return parseBook(current);
+	const legacy = readFile(join(root, LEGACY_FEEDBACK_FILE));
+	return legacy === null ? {} : parseBook(legacy);
+}
+/** One counters file as a book: anything unreadable or unshaped is `{}`, never an error. */
+function parseBook(text) {
+	try {
+		const parsed = JSON.parse(text);
+		if (typeof parsed !== "object" || parsed === null) return {};
+		const book = {};
+		for (const [key, value] of Object.entries(parsed)) {
+			const record = value;
+			if (record === null || typeof record !== "object") continue;
+			book[key] = {
+				applied: Number.isFinite(record.applied) ? Number(record.applied) : 0,
+				contradicted: Number.isFinite(record.contradicted) ? Number(record.contradicted) : 0
+			};
+		}
+		return book;
+	} catch {
+		return {};
+	}
+}
+/** Read what a run recorded being shown. */
+function readInjections(runDir, readFile = defaultRead$1) {
+	const text = readFile(join(runDir, INJECTIONS_FILE));
+	if (text === null || text.trim() === "") return [];
+	try {
+		const parsed = JSON.parse(text);
+		return Array.isArray(parsed) ? parsed : [];
+	} catch {
+		return [];
+	}
+}
+/**
+* True for the read receipt, false for a shard the phase was shown.
+*
+* ⚠ THE DISCRIMINATOR IS THE SUBJECT **AND** THE SHAPE. The reserved subject alone would be enough if no
+* plane entry could hold it, but a caller can hand-write this file, so a row is a receipt only when it also
+* carries the receipt's own fields. A hand-edited file therefore cannot make a shard row look like a read,
+* and `tests/memory-feedback.spec.ts` asserts the negative case.
+*
+* Accepts `unknown` rather than `InjectionRecord` because its callers hold JSON off disk (an array of
+* whatever the file contains), and a type guard that could only be applied to a value already known to be
+* well-shaped would not be worth having.
+*/
+function isMemoryReadRecord(record) {
+	if (record === null || typeof record !== "object") return false;
+	const candidate = record;
+	return candidate.source === "memory-read:attempt" && typeof candidate.phase === "string" && typeof candidate.injected === "boolean" && typeof candidate.shards === "number" && typeof candidate.reason === "string";
+}
+/**
+* The read receipts this run holds, in the file's own deterministic order.
+*
+* The reader the gate uses (see `hasMemoryRead` in `policy-globs.ts`): it is a NON-EMPTY answer even when
+* every receipt says `injected: false`, because a receipt is evidence that the read RAN.
+*/
+function readMemoryReads(runDir, readFile = defaultRead$1) {
+	return readInjections(runDir, readFile).filter(isMemoryReadRecord);
+}
+/**
+* Record that a phase entry READ the memory plane, whatever the read returned.
+*
+* ⚠ THIS IS THE ATTEMPT, NOT THE RESULT, AND THE DIFFERENCE IS THE WHOLE POINT. `recordInjection` can only
+* write a row when a shard was selected, so it is silent on an empty plane — and an empty plane is a
+* legitimate state a fresh workspace is in, not a failure to record. A receipt written here says "the plane
+* was read at this phase entry, and the read answered: <reason>", so `injected: false` is a SATISFIED read.
+*
+* ⚠ ONE RECEIPT PER PHASE, REPLACED (not appended). A phase is re-entered while it is still DRAFT — that is
+* the ordinary path, not an edge case — so appending would turn one read per entry into an unbounded log
+* and make the file grow with every reminder. The merge key is the phase, the newest read wins, and the
+* rewrite is byte-identical when the same phase is read twice with the same answer, which is the
+* determinism the lock receipts and the selection output already follow.
+*
+* ⚠ AND IT SHARES THE FILE WITH THE SHARD ROWS rather than living in a second sidecar: `recordInjection`
+* preserves receipts when it rewrites (below), so the two writers cannot erase each other. A separate file
+* would be a second answer to "what did this run read", which is the drift this repo keeps paying for.
+*/
+function recordMemoryRead(runDir, phase, read, write = defaultWrite, readFile = defaultRead$1) {
+	const existing = readMemoryReads(runDir, readFile);
+	const byPhase = /* @__PURE__ */ new Map();
+	for (const record of existing) byPhase.set(record.phase, record);
+	byPhase.set(phase, {
+		source: MEMORY_READ_SOURCE,
+		title: phase,
+		phase,
+		score: 0,
+		injected: read.injected,
+		shards: read.shards,
+		reason: read.reason
+	});
+	const receipts = [...byPhase.values()].sort(compareRecords);
+	const shards = readInjections(runDir, readFile).filter((record) => !isMemoryReadRecord(record));
+	write(join(runDir, INJECTIONS_FILE), JSON.stringify(sortRecords([...shards, ...receipts]), null, 2) + "\n");
+	return receipts;
+}
+/**
+* Record what the run was shown, MERGED by (source, title, phase).
+*
+* ⚠ MERGED RATHER THAN APPENDED, because a phase can be re-entered while it is still DRAFT and the same
+* entries are selected again. Appending would count one decision as four, and the counters exist to be
+* evidence. The highest score seen wins, since that is what the agent was most recently shown.
+*
+* ⚠ AND THE READ RECEIPTS SURVIVE THE REWRITE. This function owns the file, so a version of it that wrote
+* only `merged` would delete the receipt `recordMemoryRead` had just written — the gate would then refuse a
+* write in the same phase entry that satisfied it. The two kinds of row are therefore written together,
+* sorted by the same key, and a receipt is never a candidate for the score merge (it carries no shard).
+*/
+function recordInjection(runDir, entries, phase, write = defaultWrite, readFile = defaultRead$1) {
+	const existing = readInjections(runDir, readFile);
+	const byKey = /* @__PURE__ */ new Map();
+	for (const record of existing) {
+		if (isMemoryReadRecord(record)) continue;
+		byKey.set(keyOf(record), record);
+	}
+	for (const entry of entries) {
+		const candidate = {
+			source: entry.source,
+			title: entry.title,
+			phase,
+			score: entry.score
+		};
+		const key = keyOf(candidate);
+		const prior = byKey.get(key);
+		byKey.set(key, prior === void 0 || candidate.score > prior.score ? candidate : prior);
+	}
+	const receipts = existing.filter(isMemoryReadRecord);
+	const merged = sortRecords([...byKey.values(), ...receipts]);
+	write(join(runDir, INJECTIONS_FILE), JSON.stringify(merged, null, 2) + "\n");
+	return merged;
+}
+/**
+* Settle a finished run against its own outcome and return the updated book.
+*
+* ⚠ THE OUTCOME SIGNAL, and it is deliberately modest: an entry injected for a phase that **locked** was
+* APPLIED; an entry injected for a phase that had to come round again before it locked is CONTRADICTED — the
+* memory did not carry the phase the first time. That is a real signal available from the run's own files,
+* and it is not dressed up as more than that: no model was trained, and an entry is never deleted for losing.
+*/
+function settleInjections(root, runDir, lockedPhases, write = defaultWrite, readFile = defaultRead$1) {
+	const injections = readInjections(runDir, readFile);
+	const book = readFeedback(root, readFile);
+	const locked = new Set(lockedPhases);
+	for (const record of injections) {
+		if (isMemoryReadRecord(record)) continue;
+		if (!locked.has(record.phase)) continue;
+		const counter = book[record.source] ?? {
+			applied: 0,
+			contradicted: 0
+		};
+		counter.applied += 1;
+		book[record.source] = counter;
+	}
+	const feedbackPath = join(root, FEEDBACK_FILE);
+	mkdirSync(dirname(feedbackPath), { recursive: true });
+	write(feedbackPath, JSON.stringify(sortBook(book), null, 2) + "\n");
+	return book;
+}
+/**
+* What the counters are worth in the ranking: `applied - contradicted`, clamped to one step.
+*
+* Clamped because a single long-lived entry should not be able to dominate the ranking forever, and because
+* the counter is evidence about retrieval, not a verdict about the lesson.
+*/
+function feedbackBonus(book, source) {
+	const counter = book[source];
+	if (counter === void 0) return 0;
+	const net = counter.applied - counter.contradicted;
+	return net === 0 ? 0 : net > 0 ? 1 : -1;
+}
+/**
+* The file's ONE ordering, applied by both writers: phase, then source, then title.
+*
+* Both writers sort through this function rather than each carrying a copy, so two rows for one phase can
+* never end up in an order that depends on which writer ran last — the property that keeps the file
+* comparable between runs, and between a `recursive_phase` call and a `recursive_init` call.
+*/
+function compareRecords(a, b) {
+	return a.phase.localeCompare(b.phase) || a.source.localeCompare(b.source) || a.title.localeCompare(b.title);
+}
+function sortRecords(records) {
+	return [...records].sort(compareRecords);
+}
+function keyOf(record) {
+	return record.phase + "\0" + record.source + "\0" + record.title;
+}
+function sortBook(book) {
+	const sorted = {};
+	for (const key of Object.keys(book).sort()) sorted[key] = book[key];
+	return sorted;
+}
+function defaultRead$1(path) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch {
+		return null;
+	}
+}
+function defaultWrite(path, content) {
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, content, "utf8");
+}
+//#endregion
 //#region src/types.ts
 const PHASE_POSITIONS = [
 	"absent",
@@ -1618,6 +1889,92 @@ function phaseOrderRule(target, ctx) {
 	};
 }
 /**
+* THE MEMORY-READ GATE — the owner's rule, verbatim: *"the memory must be read before writing requirements.md"*.
+*
+* ⚠ THE ORDERING WAS INSTRUCTED AND NOT ENFORCED, and that is what this predicate changes. `recursive_phase`
+* calls `selectMemory` and hands the run what it found (`runtime.ts` `phaseRules`), so memory reaches the
+* agent at PHASE ENTRY — while `recursive_init` reads no memory at all. A run could therefore author
+* `00-requirements.md`, the artifact that defines what the whole run builds, BEFORE anything from
+* `.recursive/memory/` had reached it, and nothing refused that.
+*
+* ⚠ AND THE TRAP THAT DECIDES THE WHOLE DESIGN: `recordInjection` records the SHARDS, so when the memory
+* plane is EMPTY nothing is written — and a gate keyed on "a record exists" would then REFUSE FOREVER in a
+* fresh workspace. A repo with no memory is a legitimate, expected state (`selectMemory` answers
+* *"the memory plane is empty, so nothing is injected"*), so this predicate reads the READ RECEIPT rather
+* than the shards: `recordMemoryRead` writes one on every phase entry, with the selection's own reason and
+* `injected: false` when nothing matched. An empty plane therefore SATISFIES the gate, a never-entered
+* phase does not, and the two cases cannot be confused because one of them has a row.
+*
+* WHAT IT REFUSES, exactly: a write to a PHASE-0 artifact (`00-requirements.md` / `00-worktree.md` — the two
+* files `recursive_init` scaffolds, which share phase number 0 and which the phase-order rule already treats
+* as one phase) when this run holds no read receipt for phase 0, and the target is not already LOCKED.
+* Everything else abstains, so the rule costs a run nothing it should not pay:
+*
+*   - a target that is not a DIRECT CHILD of this run's directory — an ordinary product file, and the run's
+*     support files (`evidence/`, `scratch/`, `operations/`, a plain `<run>/notes.md`) — ABSTAINS. This is
+*     what keeps the gate off the write path in general: `tests/strict-run-tree.spec.ts` walks every one of
+*     those and asserts they stay writable.
+*   - a target whose phase number is anything but `0` (a LATER phase, and an EARLIER one, which cannot exist
+*     at phase 0) ABSTAINS: the ordering rules own those verdicts. A later phase in particular must keep
+*     reporting `phase-order`, which is why this rule is declared LAST of the three that share these
+*     patterns (file order within a specificity tier: locked-write, then phase-order, then this rule).
+*   - a LOCKED target ABSTAINS: the locked-artifact rule owns it, and a completed run is not re-gated.
+*   - a target that does not exist AT ALL does not abstain: `recursive_init` is not the only way to reach
+*     phase 0, and a run whose requirements were deleted still has to read before it writes them again.
+*     (In practice the refusal that fires there is the phase-order rule — an absent ACTIVE artifact still
+*     makes the run phase 0 — so this rule is the second answer, not the first.)
+*
+* ⚠ RESUMED AND EXISTING RUNS. The gate is decided from the receipt alone — never from the artifact's text,
+* which a caller controls and could therefore forge — so the recovery is the same for every run, old or
+* new: read memory for this phase. `recursive_phase` is that call, it costs one call, and a run whose
+* `00-requirements.md` was written before this rule existed keeps every other guarantee it had (a completed
+* or locked phase 0 is untouched above; a run parked at phase 0 simply makes the read it never made). The
+* refusal SAYS that, because a refusal a caller cannot act on is the failure mode this rule must not have.
+*
+* ⚠ MODE SEMANTICS FOLLOW THE EXISTING CONTRACT EXACTLY (`enforcement.ts` `verdictFor`): a policy `deny`
+* under `strict` blocks, and under `advisory` becomes an `ask` that the live path coerces to an
+* allow-WITH-WARNING — never a silent allow, never a block. Like the phase-order rule, this is a `deny`
+* verdict, so the mode decides it and nothing here special-cases the mode.
+*
+* WHERE IT LIVES, AND WHY THIS LAYER RATHER THAN `lockArtifact`. The precedent in `lockArtifact` (the
+* phase-8 memory gate, `runtime.ts`) guards a LOCK: it is a state check on a run whose artifact already
+* exists, placed after quiescence and before lint. This rule guards a WRITE, and its whole subject is that
+* the write must not happen — a check at lock time would be too late by exactly the phase it is about, since
+* the requirements document has by then been authored and every later phase built on it. The repo already
+* has the write-side layer for ordering (`phase-order`), applied to the same write-tool family through
+* `attachPolicyPredicate`; a second copy of the check in `lockArtifact` would be the duplicate this repo has
+* ruled out, so there is exactly one, here.
+*/
+function memoryReadRule(target, ctx) {
+	if (!target || !ctx.runDir || !ctx.worktreeRoot) return null;
+	const normalized = target.replace(/\\/g, "/");
+	if (!normalized.endsWith(".md")) return null;
+	const abs = resolveFrom(ctx.worktreeRoot, normalized);
+	if (!abs) return null;
+	const name = directChildName(abs, ctx.runDir);
+	if (name === null) return null;
+	if (phaseNumberForArtifact(name) !== "0") return null;
+	if (getLockStatus(abs) === "LOCKED") return null;
+	if (hasMemoryRead(ctx.runDir)) return null;
+	return {
+		verdict: "deny",
+		detail: name + ": no memory read is recorded for phase 0 of this run - call recursive_phase, which reads the memory plane and records it, then write this artifact (an EMPTY memory plane satisfies this: the read is what is required, not a match)"
+	};
+}
+/**
+* Read the run's read receipts and answer whether PHASE 0 has been read.
+*
+* ⚠ EITHER PHASE-0 ARTIFACT COUNTS, and that is a decision rather than a shortcut: `00-requirements.md` and
+* `00-worktree.md` share phase number 0, `currentPhaseArtifact` reports whichever of the two the directory
+* listing yields first, and `runtime.phaseRules` records the receipt under the artifact `getNextLegalPhase`
+* named — so keying the gate on the ONE name that happened to be active would make the verdict depend on
+* `readdirSync` order. `tests/strict-run-tree.spec.ts` asserts the two are one phase for the ordering rule;
+* this makes the gate agree with it. The phase NUMBER is the key, not the name, for exactly that reason.
+*/
+function hasMemoryRead(runDir) {
+	return readMemoryReads(runDir).some((receipt) => phaseNumberForArtifact(receipt.phase) === "0");
+}
+/**
 * The BUILT-IN default rule list — the pre-T16 guard behaviour expressed as
 * data:
 *
@@ -1657,6 +2014,13 @@ function builtInToolPolicyRules() {
 		label: "phase-order",
 		predicate: (id, args, ctx) => WRITE_TOOL_NAMES.has(id) ? phaseOrderRule(policyTargetPath(args), ctx) : null
 	});
+	for (const name of WRITE_TOOL_NAMES) rules.push({
+		pattern: name,
+		verdict: "deny",
+		reason: "memory read gate: memory must be read before the requirements artifact that defines the run is written",
+		label: "memory-read",
+		predicate: (id, args, ctx) => WRITE_TOOL_NAMES.has(id) ? memoryReadRule(policyTargetPath(args), ctx) : null
+	});
 	rules.push({
 		pattern: "*",
 		verdict: "allow",
@@ -1699,6 +2063,10 @@ function attachPolicyPredicate(rule) {
 		...rule,
 		predicate: (id, args, ctx) => WRITE_TOOL_NAMES.has(id) ? phaseOrderRule(policyTargetPath(args), ctx) : null
 	};
+	if (rule.label === "memory-read") return {
+		...rule,
+		predicate: (id, args, ctx) => WRITE_TOOL_NAMES.has(id) ? memoryReadRule(policyTargetPath(args), ctx) : null
+	};
 	if (WRITE_TOOL_NAMES.has(rule.pattern)) return {
 		...rule,
 		predicate: (id, args, ctx) => WRITE_TOOL_NAMES.has(id) ? lockedWriteRule(policyTargetPath(args), ctx.worktreeRoot) : null
@@ -6258,172 +6626,6 @@ function reviewBundleDir(root, runId) {
 	return join(resolveUnderRoot$2(root, ".recursive/run/" + runId), "evidence", "review-bundles");
 }
 //#endregion
-//#region src/memory-feedback.ts
-/**
-* Memory feedback (FU-13 P3) — which entries were injected into which run, and how that run turned out.
-*
-* ⚠ WHAT THIS IS, HONESTLY LABELLED: a COUNTER, not learning. `TRAINING.md` puts model training (the
-* reference's 58 KB GRPO script) out of scope for a workflow plugin. What is in scope is the loop that makes
-* retrieval improve with evidence: record what was injected, settle it against the run's outcome, and let the
-* selector prefer what has held up.
-*
-* ⚠ AND WHY THE COUNTERS LIVE IN A SIDECAR, NOT IN THE SHARDS. The memory plane's documents are
-* human-authored: a person writes the lesson. Rewriting one to bump a number would be the silent-overwrite
-* defect this repo already produced once (the closeout writing over phase documents), applied to the memory
-* plane. So the counters live in `.recursive/memory/.feedback.json`, which is machine-owned and disposable —
-* delete it and you lose ranking evidence, not knowledge.
-*
-* ⚠ NO TIMESTAMPS ANYWHERE: two runs with the same inputs must produce identical files, which is the same
-* discipline the lock receipts, the closeout receipts and the selection output all follow.
-*/
-/** Where the machine-owned counters live — inside the memory plane, but never a shard a person writes. */
-const FEEDBACK_FILE = ".recursive/memory/.feedback.json";
-/**
-* WHERE THE COUNTERS LIVED BEFORE the constant above carried its `.recursive/` prefix.
-*
-* ⚠ READ, BUT DELIBERATELY NEITHER MOVED NOR DELETED. Read, because evidence a previous run recorded is
-* not the plugin's to discard, and without the fallback the first settle after the move would start the
-* new file from an empty book — a counter lost silently, which is the one outcome ruled out. NOT moved,
-* because a delete is the single action that could re-create the very defect the prefix fixes: a legacy
-* file that is TRACKED and COMMITTED is absent from the run's diff while it is clean, so removing it
-* mid-run puts `D memory/.feedback.json` into the diff of every diff-audited phase authored before the
-* delete, which is the same retro-invalidation. Left alone, an untracked legacy file is in the diff from
-* the run's first phase (and is therefore accounted for), while a committed one stays invisible.
-* `readFeedback` prefers {@link FEEDBACK_FILE}, so the legacy counters are folded forward by the next
-* settle and this file then only sits there; it is machine-owned and disposable, so delete it by hand.
-*/
-const LEGACY_FEEDBACK_FILE = "memory/.feedback.json";
-/** Where a run records what it was shown. */
-const INJECTIONS_FILE = "memory-injections.json";
-/**
-* Read the counters. A missing or unreadable file is an empty book, never an error.
-*
-* ⚠ THE LEGACY PATH IS A FALLBACK AND ONLY A FALLBACK: it is consulted when — and only when — there is
-* no usable file at {@link FEEDBACK_FILE} yet, which is exactly the first run after the path moved. The
-* two are never merged, because they are two SNAPSHOTS of one counter and adding them would count a run
-* twice. A file that exists at the current path but does not parse stays an empty book, which is what
-* this function has always promised: a corrupt sidecar is not an invitation to read a different file.
-*/
-function readFeedback(root, readFile = defaultRead$1) {
-	const current = readFile(join(root, FEEDBACK_FILE));
-	if (current !== null && current.trim() !== "") return parseBook(current);
-	const legacy = readFile(join(root, LEGACY_FEEDBACK_FILE));
-	return legacy === null ? {} : parseBook(legacy);
-}
-/** One counters file as a book: anything unreadable or unshaped is `{}`, never an error. */
-function parseBook(text) {
-	try {
-		const parsed = JSON.parse(text);
-		if (typeof parsed !== "object" || parsed === null) return {};
-		const book = {};
-		for (const [key, value] of Object.entries(parsed)) {
-			const record = value;
-			if (record === null || typeof record !== "object") continue;
-			book[key] = {
-				applied: Number.isFinite(record.applied) ? Number(record.applied) : 0,
-				contradicted: Number.isFinite(record.contradicted) ? Number(record.contradicted) : 0
-			};
-		}
-		return book;
-	} catch {
-		return {};
-	}
-}
-/** Read what a run recorded being shown. */
-function readInjections(runDir, readFile = defaultRead$1) {
-	const text = readFile(join(runDir, INJECTIONS_FILE));
-	if (text === null || text.trim() === "") return [];
-	try {
-		const parsed = JSON.parse(text);
-		return Array.isArray(parsed) ? parsed : [];
-	} catch {
-		return [];
-	}
-}
-/**
-* Record what the run was shown, MERGED by (source, title, phase).
-*
-* ⚠ MERGED RATHER THAN APPENDED, because a phase can be re-entered while it is still DRAFT and the same
-* entries are selected again. Appending would count one decision as four, and the counters exist to be
-* evidence. The highest score seen wins, since that is what the agent was most recently shown.
-*/
-function recordInjection(runDir, entries, phase, write = defaultWrite, readFile = defaultRead$1) {
-	const existing = readInjections(runDir, readFile);
-	const byKey = /* @__PURE__ */ new Map();
-	for (const record of existing) byKey.set(keyOf(record), record);
-	for (const entry of entries) {
-		const candidate = {
-			source: entry.source,
-			title: entry.title,
-			phase,
-			score: entry.score
-		};
-		const key = keyOf(candidate);
-		const prior = byKey.get(key);
-		byKey.set(key, prior === void 0 || candidate.score > prior.score ? candidate : prior);
-	}
-	const merged = [...byKey.values()].sort((a, b) => a.phase.localeCompare(b.phase) || a.source.localeCompare(b.source) || a.title.localeCompare(b.title));
-	write(join(runDir, INJECTIONS_FILE), JSON.stringify(merged, null, 2) + "\n");
-	return merged;
-}
-/**
-* Settle a finished run against its own outcome and return the updated book.
-*
-* ⚠ THE OUTCOME SIGNAL, and it is deliberately modest: an entry injected for a phase that **locked** was
-* APPLIED; an entry injected for a phase that had to come round again before it locked is CONTRADICTED — the
-* memory did not carry the phase the first time. That is a real signal available from the run's own files,
-* and it is not dressed up as more than that: no model was trained, and an entry is never deleted for losing.
-*/
-function settleInjections(root, runDir, lockedPhases, write = defaultWrite, readFile = defaultRead$1) {
-	const injections = readInjections(runDir, readFile);
-	const book = readFeedback(root, readFile);
-	const locked = new Set(lockedPhases);
-	for (const record of injections) {
-		if (!locked.has(record.phase)) continue;
-		const counter = book[record.source] ?? {
-			applied: 0,
-			contradicted: 0
-		};
-		counter.applied += 1;
-		book[record.source] = counter;
-	}
-	const feedbackPath = join(root, FEEDBACK_FILE);
-	mkdirSync(dirname(feedbackPath), { recursive: true });
-	write(feedbackPath, JSON.stringify(sortBook(book), null, 2) + "\n");
-	return book;
-}
-/**
-* What the counters are worth in the ranking: `applied - contradicted`, clamped to one step.
-*
-* Clamped because a single long-lived entry should not be able to dominate the ranking forever, and because
-* the counter is evidence about retrieval, not a verdict about the lesson.
-*/
-function feedbackBonus(book, source) {
-	const counter = book[source];
-	if (counter === void 0) return 0;
-	const net = counter.applied - counter.contradicted;
-	return net === 0 ? 0 : net > 0 ? 1 : -1;
-}
-function keyOf(record) {
-	return record.phase + "\0" + record.source + "\0" + record.title;
-}
-function sortBook(book) {
-	const sorted = {};
-	for (const key of Object.keys(book).sort()) sorted[key] = book[key];
-	return sorted;
-}
-function defaultRead$1(path) {
-	try {
-		return readFileSync(path, "utf8");
-	} catch {
-		return null;
-	}
-}
-function defaultWrite(path, content) {
-	mkdirSync(dirname(path), { recursive: true });
-	writeFileSync(path, content, "utf8");
-}
-//#endregion
 //#region src/memory.ts
 /**
 * T14 — retrieve prior-run memory into the review bundle, so the recursion COMPOUNDS.
@@ -6550,10 +6752,11 @@ function readMemoryEntries(readFile, listFiles, kinds = MEMORY_KINDS) {
 	}
 	return entries;
 }
-/** Render the retrieved memory for a review bundle: sections a reviewer can cite by title. */
-function renderMemorySection(entries) {
-	if (entries.length === 0) return "No prior-run memory matched this review. Do not assume the absence is conclusive: memory is retrieved by relevance to the artifact and phase, not by recency.";
-	const lines = ["Prior-run memory relevant to this review (cite by title if you rely on it):"];
+/** Render the retrieved memory: sections a reader can cite by title. See {@link MemoryRenderContext}. */
+function renderMemorySection(entries, context = "review") {
+	const where = context === "phase" ? "this phase" : "this review";
+	if (entries.length === 0) return "No prior-run memory matched " + where + ". Do not assume the absence is conclusive: memory is retrieved by relevance to the artifact and phase, not by recency.";
+	const lines = [context === "phase" ? "Prior-run memory injected for this phase (rely on it, and cite by title when you use it):" : "Prior-run memory relevant to this review (cite by title if you rely on it):"];
 	for (const entry of entries) {
 		lines.push("");
 		lines.push("### [" + entry.kind + "] " + entry.title);
@@ -8786,7 +8989,8 @@ function renderStableContract(config = DEFAULT_ENFORCEMENT) {
 		"- Writes to a Status: LOCKED phase doc are denied/asked; reopen explicitly to edit.",
 		"- Phase order binds WRITES as well as locks: only the ACTIVE phase (the lowest-numbered artifact not yet LOCKED) may be written; a write to a LATER phase artifact is denied/asked. Run support files (evidence/, scratch/, addenda/, subagents/, operations/) are not phases.",
 		"- Phase 3 lock requires TDD evidence (strict) or rationale (pragmatic); Phase 5 requires QA evidence.",
-		"- The control-plane root is resolved STRICTLY from this session workspace (never scanned from another)."
+		"- The control-plane root is resolved STRICTLY from this session workspace (never scanned from another).",
+		"- Memory is READ AT PHASE ENTRY by recursive_phase: it returns what the memory plane holds for this run and phase (the selected shards, or `memoryReason` saying why nothing was injected). Read it when entering a phase, rely on what it gives you, and cite a shard by title wherever you act on it. An EMPTY plane is a normal result, not a failure: \"the memory plane is empty, so nothing is injected\" is an answer, and the phase proceeds with what the run itself knows."
 	].join("\n");
 }
 /**
@@ -11747,11 +11951,16 @@ var RecursiveRuntime = class extends Service {
 			title: shard.entry.title,
 			score: shard.score
 		})), phase);
+		recordMemoryRead(resolved.runDir, phase, {
+			injected: selection.injected,
+			shards: selection.shards.length,
+			reason: selection.reason
+		});
 		return {
 			runId: resolved.runId,
 			phase,
 			...phaseRulesFor(phase),
-			memory: selection.injected ? renderMemorySection(selection.shards.map((shard) => shard.entry)) : "",
+			memory: selection.injected ? renderMemorySection(selection.shards.map((shard) => shard.entry), "phase") : "",
 			memoryReason: selection.reason,
 			...pending === null ? {} : { ask: {
 				gate: pending,
@@ -12828,6 +13037,22 @@ function createRecursiveWorktreeTool(recursive) {
 * reminder, so the agent can re-ask for the rules without re-injecting them on
 * every step. Returns { error } when no active phase is found.
 *
+* ⚠ AND IT IS WHERE PRIOR-RUN MEMORY ARRIVES — say so in the DESCRIPTION, which is the only surface a
+* model reads before choosing a tool. The description used to promise rules and instructions only, so
+* nothing in the tool list gave a caller a reason to expect memory here (the owner's own report: *"the
+* memory must be read before writing requirements.md"*, and *"recursive_phase should also read memories"*).
+* The read WAS already happening — `phaseRules` calls `selectMemory` and returns the section plus its
+* reason — so the defect was that the contract was SILENT about it, not that the mechanism was absent.
+* Every sentence below is a claim about what this call actually returns: the payload's `memory` and
+* `memoryReason` fields come from `selectMemory`, `runId`/`phase` from the resolved run, `requiredSections`
+* / `audited` / `tdd` / `qa` / `memoryWrite` from `phaseRulesFor`, and `ask` from `pendingGateFor`. A
+* description that advertised a field the payload does not carry would be worse than the silence it fixes.
+*
+* ⚠ AND AN EMPTY PLANE IS SAID TO BE NORMAL, because that is the honest reading and the one a model needs:
+* `selectMemory` answers *"the memory plane is empty, so nothing is injected"*, which is a RESULT — the
+* plane was read and had nothing to say — not a failure of the call and not a reason to retry it. Without
+* that sentence an agent seeing an empty section could reasonably conclude the read had not happened.
+*
 * A RUN ID IS A NAME, NOT A PATH HERE TOO, INCLUDING WHEN IT IS OMITTED. Omitted and path-shaped are
 * different cases and must stay different: omitted means "the latest run by mtime", which `resolveRunDir`
 * answers by DISCOVERY rather than by joining anything, and that case is untouched below. A path-shaped id,
@@ -12839,7 +13064,7 @@ function createRecursiveWorktreeTool(recursive) {
 function createRecursivePhaseTool(recursive) {
 	return defineTool({
 		name: "recursive_phase",
-		description: "Return the lint rules + instructions for the current recursive-mode phase (required sections, gates, TDD/QA notes). Call once when entering a new phase; the same rules are also auto-injected once per phase transition.",
+		description: "Enter the current recursive-mode phase: returns that phase's lint rules and instructions (required sections, gates, TDD/QA notes) AND the prior-run memory selected for this run and phase. `memory` carries the shards to use, each titled so it can be cited, and `memoryReason` says why nothing was injected when it is empty — an EMPTY memory plane is a normal result of a read, never a failure, so do not retry because of it. Nothing from the memory plane reaches a run before this call, so MAKE IT ONCE WHEN ENTERING A PHASE and before authoring that phase's artifact (`00-requirements.md` included: a write to it is refused until a read is recorded for the run). The same rules are also auto-injected once per phase transition.",
 		parameters: { runId: {
 			type: "string",
 			description: "Optional run id — the NAME of the run directory under .recursive/run/ (e.g. 03-something), never a path: " + RUN_ID_RULE + ". Omit it for the latest run by mtime."