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

package/src/enforcement.ts

@@ -176,8 +176,13 @@ export 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 {

package/src/memory-feedback.ts

@@ -49,6 +49,43 @@ export const LEGACY_FEEDBACK_FILE = 'memory/.feedback.json'
 /** Where a run records what it was shown. */
 export 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`.
+ */
+export const MEMORY_READ_SOURCE = 'memory-read:attempt'
+
+/** The receipt a phase entry leaves for a read that happened at `phase`. */
+export interface MemoryReadRecord extends InjectionRecord {
+  /** Always {@link MEMORY_READ_SOURCE}. */
+  source: typeof MEMORY_READ_SOURCE
+  /** The phase ENTRY that performed the read — an artifact name (`00-requirements.md`), as shards use. */
+  phase: string
+  /** True when anything was injected; FALSE is a satisfied read, not a missing one. */
+  injected: boolean
+  /** How many shards were injected. `0` on an empty plane, which is the case this whole record exists for. */
+  shards: number
+  /** WHY the read returned what it did — `selectMemory`'s own reason, carried verbatim. */
+  reason: string
+  /** Always `0`: a receipt is not a ranking, so it can never move a counter. */
+  score: 0
+}
+
 /** One entry the agent was shown, as the run recorded it. */
 export interface InjectionRecord {
   /** The entry's source path, which is also its identity in the counters. */
@@ -116,12 +153,95 @@ export function readInjections(runDir: string, readFile: (path: string) => strin
   }
 }
 
+/**
+ * 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.
+ */
+export function isMemoryReadRecord(record: unknown): record is MemoryReadRecord {
+  if (record === null || typeof record !== 'object') return false
+  const candidate = record as Partial<MemoryReadRecord>
+  return candidate.source === MEMORY_READ_SOURCE
+    && 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.
+ */
+export function readMemoryReads(runDir: string, readFile: (path: string) => string | null = defaultRead): MemoryReadRecord[] {
+  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.
+ */
+export function recordMemoryRead(
+  runDir: string,
+  phase: string,
+  read: { injected: boolean; shards: number; reason: string },
+  write: (path: string, content: string) => void = defaultWrite,
+  readFile: (path: string) => string | null = defaultRead,
+): MemoryReadRecord[] {
+  const existing = readMemoryReads(runDir, readFile)
+  const byPhase = new Map<string, MemoryReadRecord>()
+  for (const record of existing) byPhase.set(record.phase, record)
+  byPhase.set(phase, {
+    source: MEMORY_READ_SOURCE,
+    // The title is the phase, so the row is readable in the file without decoding the receipt.
+    title: phase,
+    phase,
+    score: 0,
+    injected: read.injected,
+    shards: read.shards,
+    reason: read.reason,
+  })
+  const receipts = [...byPhase.values()].sort(compareRecords)
+  // The shard rows are carried through UNTOUCHED — see the note on `recordInjection` for why each writer
+  // must preserve the other's rows.
+  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).
  */
 export function recordInjection(
   runDir: string,
@@ -132,16 +252,19 @@ export function recordInjection(
 ): InjectionRecord[] {
   const existing = readInjections(runDir, readFile)
   const byKey = new Map<string, InjectionRecord>()
-  for (const record of existing) byKey.set(keyOf(record), record)
+  for (const record of existing) {
+    if (isMemoryReadRecord(record)) continue
+    byKey.set(keyOf(record), record)
+  }
   for (const entry of entries) {
     const candidate: InjectionRecord = { source: entry.source, title: entry.title, phase, score: entry.score }
     const key = keyOf(candidate)
     const prior = byKey.get(key)
     byKey.set(key, prior === undefined || candidate.score > prior.score ? candidate : prior)
   }
+  const receipts = existing.filter(isMemoryReadRecord)
   // Deterministic order, so the file is comparable between runs.
-  const merged = [...byKey.values()].sort((a, b) => a.phase.localeCompare(b.phase)
-    || a.source.localeCompare(b.source) || a.title.localeCompare(b.title))
+  const merged = sortRecords([...byKey.values(), ...receipts])
   write(join(runDir, INJECTIONS_FILE), JSON.stringify(merged, null, 2) + '\n')
   return merged
 }
@@ -173,6 +296,13 @@ export function settleInjections(
   // what to do with it; what is missing is an honest SOURCE for it (a re-opened phase), and until there is
   // one, this function reports only what it can prove.
   for (const record of injections) {
+    // ⚠ A READ RECEIPT IS NOT AN INJECTION, so it can never settle a counter. It carries no shard — its
+    // subject is the reserved {@link MEMORY_READ_SOURCE}, which no memory entry can hold — so without this
+    // line an empty plane would write a counter row for a source that does not exist and the book would
+    // carry evidence about nothing. Filtered HERE rather than at the reader, because `readInjections` is a
+    // documented shape (`tests/memory-feedback.spec.ts` pins the row it returns) and a second reader would
+    // be a second answer to "what is in this file".
+    if (isMemoryReadRecord(record)) continue
     if (!locked.has(record.phase)) continue
     const counter = book[record.source] ?? { applied: 0, contradicted: 0 }
     counter.applied += 1
@@ -206,6 +336,21 @@ function countPhase(injections: readonly InjectionRecord[], phase: string): numb
   return injections.filter((record) => record.phase === phase).length
 }
 
+/**
+ * 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: InjectionRecord, b: InjectionRecord): number {
+  return a.phase.localeCompare(b.phase) || a.source.localeCompare(b.source) || a.title.localeCompare(b.title)
+}
+
+function sortRecords(records: readonly InjectionRecord[]): InjectionRecord[] {
+  return [...records].sort(compareRecords)
+}
+
 function keyOf(record: { source: string; title: string; phase: string }): string {
   return record.phase + '\u0000' + record.source + '\u0000' + record.title
 }

package/src/memory.ts

@@ -149,12 +149,38 @@ export function readMemoryEntries(
   return entries
 }
 
-/** Render the retrieved memory for a review bundle: sections a reviewer can cite by title. */
-export function renderMemorySection(entries: readonly MemoryEntry[]): string {  if (entries.length === 0) {
-    return 'No prior-run memory matched this review. Do not assume the absence is conclusive:'
+/**
+ * WHERE A RENDERED SECTION IS GOING TO BE READ — the one thing the section's wording depends on.
+ *
+ * ⚠ WHY THIS IS A PARAMETER AND NOT A SECOND RENDERER. The section is rendered for two readers: a
+ * delegated REVIEW bundle (`runtime.ts` `buildReviewBundle`, context `'review'`) and the PHASE-ENTRY
+ * payload `recursive_phase` returns (`runtime.ts` `phaseRules`, context `'phase'`). The wording used to
+ * be the reviewer's — *"Prior-run memory relevant to this REVIEW"* — and the phase payload inherited it,
+ * so an agent that had just been handed prior-run learning at phase entry was told it was a review: the
+ * reader the text addressed was not the reader holding it. Copying the renderer to change one sentence
+ * would have been two renderers to keep in step, which is how the two answers to one question appear in
+ * this plugin; the sentence is instead selected from this context, so there is still ONE renderer.
+ */
+export type MemoryRenderContext = 'review' | 'phase'
+
+/** Render the retrieved memory: sections a reader can cite by title. See {@link MemoryRenderContext}. */
+export function renderMemorySection(
+  entries: readonly MemoryEntry[],
+  context: MemoryRenderContext = 'review',
+): string {
+  // The default is `'review'` so every existing caller keeps the sentence it has always rendered — a
+  // truthfulness fix must not silently restate what a caller already read (`tests/memory-retrieval.spec.ts`
+  // pins that wording). The phase payload opts IN, which is the change the owner's second point asks for.
+  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: string[] = ['Prior-run memory relevant to this review (cite by title if you rely on it):']
+  const lines: string[] = [context === 'phase'
+    // The phase payload's whole purpose is to put prior-run learning IN FRONT of the work, so the heading
+    // says what to do with it — rely on it, and cite it so the reliance is traceable.
+    ? '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)

package/src/policy-globs.ts

@@ -42,6 +42,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { basename, dirname, join, resolve } from 'node:path'
 import { getLockStatus, getPrerequisiteBlockers, type PrerequisiteBlocker } from './lock.ts'
+import { readMemoryReads } from './memory-feedback.ts'
 import { getMdFieldValue } from './status.ts'
 import { phaseNumberForArtifact, policyTargetPath, resolveFrom } from './phase-rules.ts'
 
@@ -602,6 +603,96 @@ function phaseOrderRule(target: string | null, ctx: ToolPolicyContext): ToolPoli
   }
 }
 
+/**
+ * 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: string | null, ctx: ToolPolicyContext): ToolPolicyPredicateMatch | null {
+  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: string): boolean {
+  return readMemoryReads(runDir).some((receipt) => phaseNumberForArtifact(receipt.phase) === '0')
+}
+
 /**
  * The BUILT-IN default rule list — the pre-T16 guard behaviour expressed as
  * data:
@@ -653,6 +744,19 @@ export function builtInToolPolicyRules(): ToolPolicyRule[] {
       predicate: (id, args, ctx) => (WRITE_TOOL_NAMES.has(id) ? phaseOrderRule(policyTargetPath(args), ctx) : null),
     })
   }
+  // …and a THIRD conditional deny on the same patterns: the memory-read gate. It is LAST of the three
+  // deliberately, because it is the narrowest of them and the other two must keep their labels on the
+  // cases they already own (an out-of-order write is a phase-order refusal, not a memory one). The engine
+  // decides equally specific rules by FILE ORDER, so this position is the precedence.
+  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',
@@ -700,6 +804,13 @@ export function attachPolicyPredicate(rule: ToolPolicyRule): ToolPolicyRule {
   if (rule.label === 'phase-order') {
     return { ...rule, predicate: (id, args, ctx) => (WRITE_TOOL_NAMES.has(id) ? phaseOrderRule(policyTargetPath(args), ctx) : null) }
   }
+  // …and the memory-read gate is attached the same way, by LABEL. Without this branch the file's rule
+  // would take the pattern's condition below (the locked-artifact one) and the gate would exist in the
+  // built-in list but never in a repo that ships the policy file — which is this repo, and every repo
+  // scaffolded from it.
+  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) }
   }

package/src/policy.ts

@@ -114,6 +114,23 @@ export function renderStableContract(config: EnforcementConfig = DEFAULT_ENFORCE
     '- 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 CONTRACT NOW SAYS MEMORY IS READ, AND IT HAS TO SAY IT HERE RATHER THAN IN THE TAIL.
+    //
+    // MEASURED BEFORE THIS LINE EXISTED: `grep -E 'memor|shard|learn' src/policy.ts` returned ZERO hits, so
+    // the model-facing contract — the text the agent reads on every turn — never mentioned that prior-run
+    // memory is read at phase entry, never said what an empty plane means, and never said to cite what it
+    // relies on. The read itself was not missing (`runtime.phaseRules` calls `selectMemory` and returns the
+    // section); it was INVISIBLE, which is the same class of defect that produced three live runs with zero
+    // locks: a mechanism nothing announces is a mechanism the model has no reason to use.
+    //
+    // It belongs in the STABLE prefix, not the per-phase tail, because it is true of every phase — the tail
+    // is precisely what changes between them. It carries NO selection (no shard, no count, no match), so the
+    // prefix stays byte-identical for the whole run, which is the split's only precondition.
+    '- 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')
 }
 

package/src/recursive_phase.tool.ts

@@ -11,6 +11,22 @@ import type { RecursiveRuntime } from './runtime.ts'
  * 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,
@@ -22,7 +38,14 @@ import type { RecursiveRuntime } from './runtime.ts'
 export function createRecursivePhaseTool(recursive: RecursiveRuntime) {
   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.' },
     },