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

package/lib/memory.d.ts

@@ -18,7 +18,19 @@
  * so the result is reproducible from the inputs alone.
  */
 import { type FeedbackBook } from './memory-feedback.ts';
-export declare const MEMORY_KINDS: readonly ["domains", "patterns", "episodes", "skills"];
+/**
+ * ⚠ `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.
+ */
+export declare const MEMORY_KINDS: readonly ["domains", "patterns", "episodes", "training", "skills"];
 export type MemoryKind = (typeof MEMORY_KINDS)[number];
 /** One memory note: a titled section of a memory document. */
 export interface MemoryEntry {
@@ -95,7 +107,28 @@ export declare const MEMORY_PHASE_MATCH_WEIGHT = 2;
  */
 export declare function entryAppliesTo(entry: MemoryEntry): string[];
 /** The registry the loader starts from: the router, not the plane. */
-export declare const MEMORY_INDEX_FILE = "memory/MEMORY.md";
+export declare const MEMORY_INDEX_FILE = ".recursive/memory/MEMORY.md";
+/**
+ * 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".
+ */
+export declare const MEMORY_PLANE_BASES: readonly [".recursive/memory", "memory"];
 /** Progressive disclosure defaults, matching the parent (`--max-docs` 3, `--max-items` 10). */
 export declare const MAX_MEMORY_DOCS = 3;
 export declare const MAX_MEMORY_ITEMS = 10;

package/lib/phase-rules.d.ts

@@ -10,6 +10,100 @@ export declare const DIFF_AUDITED_FILES: Set<string>;
 export declare const TRACEABILITY_REQUIRED_FILES: Set<string>;
 export declare const AUDIT_REQUIRED_HEADINGS: string[];
 export declare const DIFF_BASIS_FIELDS: string[];
+/**
+ * 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.
+ */
+export declare const PHASE8_MEMORY_ARTIFACT = "08-memory-impact.md";
+/** The plane, repo-relative. The trailing slash is what every guard here tests for. */
+export declare const MEMORY_PLANE_PREFIX = ".recursive/memory/";
+/** The canonical section the declaration goes in — present in every scaffolded phase-8 artifact. */
+export declare const PHASE8_MEMORY_SECTION = "Affected Memory Docs";
+/**
+ * Where a durable doc may be filed, and the `Type` the memory-plane linter requires for it.
+ *
+ * ⚠ EVERY `dir` IS THE REAL PLANE, `.recursive/memory/…`, AND NOT A `memory/…` RELATIVE FORM. Measured:
+ * `bootstrap.ts` scaffolds the plane under `.recursive/`, `ts-lint.ts` lints it there, and the phase-8
+ * artifact cites it there — while the training trigger's own write seam joins its `memory/…` paths onto
+ * the workspace root, i.e. `<root>/memory/`, a directory that exists in no real workspace (the reader
+ * side of that defect was fixed in `memory.ts`; the writer side is `runtime.ts`'s seam and is reported,
+ * not edited). This table names the location a WRITE must land in, so it names the plane.
+ *
+ * ⚠ `skill` SHARES `pattern`'s Type ON PURPOSE: `/.recursive/memory/skills/patterns/` is where a
+ * promoted skill lesson ships (`bootstrap.ts` scaffolds three docs there), and the linter's allowed
+ * Types are `index|domain|pattern|incident|episode` — there is no `skill` Type to declare.
+ */
+export declare const MEMORY_DOC_LOCATIONS: {
+    readonly domain: {
+        readonly dir: ".recursive/memory/domains";
+        readonly type: "domain";
+    };
+    readonly pattern: {
+        readonly dir: ".recursive/memory/patterns";
+        readonly type: "pattern";
+    };
+    readonly incident: {
+        readonly dir: ".recursive/memory/incidents";
+        readonly type: "incident";
+    };
+    readonly episode: {
+        readonly dir: ".recursive/memory/episodes";
+        readonly type: "episode";
+    };
+    readonly skill: {
+        readonly dir: ".recursive/memory/skills/patterns";
+        readonly type: "pattern";
+    };
+};
+export type MemoryDocKind = keyof typeof MEMORY_DOC_LOCATIONS;
+/** The field that makes a doc THIS run's. It is the phase-8 gate's entire discriminator. */
+export declare const MEMORY_PROVENANCE_FIELD = "Source-Runs";
+/** Where a run that believes it learned nothing can always record what the run was and what it cost. */
+export declare const MEMORY_ALWAYS_AVAILABLE = ".recursive/memory/episodes/<run-id>.md";
+/**
+ * The phase-8 obligation, as data — so the pre-step reminder, the `recursive_phase` payload and the
+ * lock-time gate all describe ONE rule instead of three paraphrases of it.
+ */
+export interface Phase8MemoryWriteRule {
+    /** The artifact that must declare the write. */
+    artifact: string;
+    /** The plane the write must land in, repo-relative. */
+    plane: string;
+    /** The section the declaration goes in. */
+    section: string;
+    /** The field a doc must carry for the write to count as THIS run's. */
+    provenanceField: string;
+    /** The doc a run with nothing else to record can always write. */
+    alwaysAvailable: string;
+    kinds: readonly MemoryDocKind[];
+    /** One sentence per line the pre-step reminder injects. */
+    summary: string;
+    /** The full instruction, for a caller that asks for the phase's rules. */
+    instruction: string;
+}
+export declare const PHASE8_MEMORY_WRITE_RULE: Phase8MemoryWriteRule;
+/** The memory-write rule for an artifact, or null when that phase owes no memory write. */
+export declare function phase8MemoryWriteRuleFor(fileName: string): Phase8MemoryWriteRule | null;
 /**
  * get_artifact_required_sections(file_name, workflow_profile): canonical-parity
  * required section headings for a phase artifact. Defaults to TODO + Coverage
@@ -41,6 +135,14 @@ export interface PhaseRules {
     audited: boolean;
     tdd: boolean;
     qa: boolean;
+    /**
+     * T40 — the memory-write obligation for this phase, or null when it owes none.
+     *
+     * ⚠ IT IS PART OF THIS STRUCTURE, not a parallel table, because `runtime.phaseRules` spreads this
+     * object straight into the `recursive_phase` payload and the pre-step reminder is built from the
+     * same source: a rule that lives here is a rule the agent is actually told, in one place.
+     */
+    memoryWrite: Phase8MemoryWriteRule | null;
 }
 export declare function phaseRulesFor(fileName: string, workflowProfile?: string): PhaseRules;
 /**

package/lib/policy-globs.d.ts

@@ -1,3 +1,4 @@
+import { type PrerequisiteBlocker } from './lock.ts';
 /** The three verdicts a rule may carry. */
 export type Verdict = 'allow' | 'deny' | 'ask';
 /**
@@ -10,11 +11,28 @@ export interface Decision {
     kind: Verdict;
     reason?: string;
     rule?: string;
+    /**
+     * THE FACTS THE PREDICATE DECIDED FROM, when it read any. The lock-order rule resolves the
+     * artifact's prerequisites from disk, and the layer that turns this decision into a refusal
+     * needs those same facts to build the caller's recovery options. Carrying them is what makes
+     * "the guard already has them" true: a second `getPrerequisiteBlockers` call from the denial
+     * would re-read a run tree that is on disk and unlocked, and could answer differently.
+     *
+     * Absent for every rule that decides on its pattern alone, and absent when the predicate read
+     * nothing — so its presence means "this refusal was decided from these blockers", not "the
+     * policy mentions blockers".
+     */
+    blockers?: readonly PrerequisiteBlocker[];
 }
 /**
  * Extra facts a rule predicate may need. `args` is always the tool call's
  * arguments; the run coordinates are present only when the caller has them
  * (a guard call from a real session does; a pure policy unit test need not).
+ *
+ * ⚠ `runId` IS NOT DECORATION: the lock-order rule puts it in the refusal (`[run: <id>]`), so a refusal
+ * names the run whose tree it was decided from. It is the run the guard RESOLVED for this call — the run
+ * the call named when it named a usable one, otherwise the active run (see `resolveGuardRunId` in
+ * `enforcement.ts`) — never a second, independently-derived answer.
  */
 export interface ToolPolicyContext {
     args: Record<string, unknown>;
@@ -49,6 +67,12 @@ export interface ToolPolicyContext {
 export interface ToolPolicyPredicateMatch {
     verdict: Verdict;
     detail?: string;
+    /**
+     * The blockers the predicate READ, when it read any (see `Decision.blockers`). Optional and
+     * additive: a predicate that decided from something else returns none, and the engine's
+     * verdict is unchanged either way.
+     */
+    blockers?: readonly PrerequisiteBlocker[];
 }
 export type ToolPolicyPredicate = (id: string, args: Record<string, unknown>, ctx: ToolPolicyContext) => ToolPolicyPredicateMatch | null;
 export interface ToolPolicyRule {

package/lib/recursive_ask.tool.d.ts

@@ -58,6 +58,43 @@ export declare class AskValidationError extends Error {
 export declare function validateAskQuestion(question: AskQuestion): AskQuestion;
 /** Build the question for a gate, validated. */
 export declare function buildAskQuestion(gateId: AskGateId): AskQuestion;
+/**
+ * FU-7 — THE GATE-BLOCK REFUSAL PAYLOAD, BUILT IN ONE PLACE.
+ *
+ * A blocked lock is refused by TWO layers. The TOOL refuses when `lockArtifact` throws
+ * `Prerequisite blockers:`; the GUARD refuses pre-dispatch when the lock-order rule fires
+ * (`monotonic lock-order`), and under the strict default that is the layer the caller meets
+ * first. Both must hand the caller the SAME choice, so both build it HERE.
+ *
+ * ⚠ WHY NOT TWO LITERALS. `fix | reopen | abandon` is the human's way out of a blocked lock,
+ * and it existed in exactly one call site (`recursive_lock.tool.ts`). The guard's refusal moved
+ * to the default path, and a second hand-written copy of the options there would be a second
+ * answer to "what can a person do about this?": the day the options change, one of the two
+ * refusals keeps offering the old set and nothing fails. One builder, called from both.
+ *
+ * `blocked` is the refusal's OWN sentence — the guard's rule text or the tool's exception
+ * message — carried as data so the payload says what it is about without a reader having to
+ * match it against the text beside it.
+ */
+export interface GateBlockAsk extends AskQuestion {
+    gate: 'gate-block';
+    artifact: string;
+    blocked: string;
+}
+/** The payload, as the refusal carries it. Validated through `buildAskQuestion`. */
+export declare function buildGateBlockAsk(artifact: string, blocked: string): GateBlockAsk;
+/**
+ * FU-7 — THE OPTIONS AS TEXT, DERIVED FROM THE PAYLOAD rather than restated.
+ *
+ * WHY A RENDERER IS NEEDED AT ALL: the harness renders a `tools/pre-execute` denial as
+ * `Error: <reason>` and drops every other field of the decision (measured in
+ * `packages/core/tools`: `content: [{ type: 'text', text: 'Error: ' + denialReason }]`), so an
+ * ask that rode along as a SIBLING field would reach the model as nothing at all — which is
+ * exactly how a strict-by-default guard made the recovery path unreachable. The refusal
+ * therefore renders the payload into the text it hands back, and it renders THIS object, so
+ * the visible sentence and the structured payload cannot disagree.
+ */
+export declare function renderGateBlockAsk(ask: GateBlockAsk): string;
 /**
  * PHASE 0 — build the question for ANY accepted gate, including the run-start gate.
  *

package/lib/runtime.d.ts

@@ -743,7 +743,7 @@ export declare class RecursiveRuntime extends Service {
         code: string;
         message: string;
     }): boolean;
-    /** Phase C R7: resolve the enforcement config (strict|advisory, default advisory). */
+    /** Phase C R7: resolve the enforcement config (strict|advisory, default strict). */
     get enforcementConfig(): EnforcementConfig;
     setEnforcementConfig(config: unknown): EnforcementConfig;
 }

package/lib/training.d.ts

@@ -1,3 +1,4 @@
+import { type MemoryDocKind } from './phase-rules.ts';
 /** The artifact whose lock marks a run as complete enough to learn from. */
 export declare const PHASE8_ARTIFACT = "08-memory-impact.md";
 /** The parent's exit codes, kept as names so a caller cannot mistake one failure for the other. */
@@ -94,8 +95,16 @@ export declare function runPhase8Trigger(root: string, runId: string, 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.
  */
-export declare function renderGroupShard(group: TrainingGroup): string;
+export declare function renderGroupShard(group: TrainingGroup, options?: {
+    lastValidated?: string;
+}): string;
 /**
  * T30 — the extractor, resolved from the environment.
  *
@@ -182,7 +191,10 @@ export declare function updateMemoryRegistry(existing: string, entries: Readonly
  * one training shard from another here. Named so a reader can disagree with it instead of discovering it.
  */
 export declare function taskTypeShardPath(mode: TrainingGroup['mode']): string;
-export declare function renderTaskTypeShard(groups: readonly TrainingGroup[]): string;
+/** T40: same metadata-header reason as {@link renderGroupShard} — see the note there. */
+export declare function renderTaskTypeShard(groups: readonly TrainingGroup[], options?: {
+    lastValidated?: string;
+}): string;
 /**
  * T30 — turn the extractor's payload into items the grouping can use.
  *
@@ -209,3 +221,229 @@ export declare function extractAndGroup(runner: (cmd: string) => ExtractorRun, e
     items: TrainingItem[];
     groups: TrainingGroup[];
 };
+/**
+ * T40 — THE PLUGIN'S OWN WAY TO WRITE `.recursive/memory/`.
+ *
+ * ⚠ WHY A WRITE SURFACE AND NOT ANOTHER PARAGRAPH OF INSTRUCTIONS. The memory plane's shape is not a
+ * convention an author can guess: a durable doc must carry nine metadata fields, its `Type` must be
+ * one of five, and the plane's own lint FAILs the whole run when one is missing. Measured against the
+ * live workspace, the plane held NOTHING but the bootstrap placeholders — so the practical choice was
+ * between an agent hand-rolling a doc that fails the plane lint and no doc at all. This renders the
+ * canonical shape, stamps the provenance the phase-8 gate reads back, replaces the shard's line in
+ * the registry, and refuses to write a doc its own linter would reject.
+ *
+ * ⚠ WHAT IS DELIBERATE, DECIDED HERE RATHER THAN LEFT TO A CALLER:
+ *
+ *   - ATOMIC. `writeFileSync` to a sibling temp name, then a rename over the target. A memory doc is
+ *     read by the loader and linted by the plane, and a torn write is worse than a missing one: a
+ *     half-written doc is a FAILED lint that names a file nobody wrote, and there is no way to tell it
+ *     from a real one afterwards.
+ *   - PROVENANCE-CARRYING. `Source-Runs` names the run, and it is not decoration: it is the entire
+ *     discriminator between "the run wrote its memory" and "the run cited a shard that already
+ *     existed", which is the distinction the phase-8 gate turns on. It is also why the run id is
+ *     stamped from the CALL rather than trusted per-doc.
+ *   - DEDUPLICATED, IDEMPOTENTLY. Writing the same doc again from the same run is a no-op that SAYS
+ *     so (`UNCHANGED`), because phase 8 closeout runs more than once — the training trigger's own
+ *     reason for existing is the re-run — and a re-run must not duplicate a lesson or rewrite a doc
+ *     byte-differently for no reason.
+ *   - REFUSED WHEN THE ENTRY ALREADY EXISTS, unless the caller supersedes explicitly. Another run's
+ *     shard is that run's evidence; silently overwriting it destroys provenance for a shard the plane
+ *     could not restore. `supersede: true` is the deliberate path, and it ARCHIVES the previous
+ *     revision under `memory/archive/` first — supersede, never delete, the same discipline the
+ *     counters and the registry already follow.
+ *   - AND NOTHING IS INVENTED. An empty scope or body, an unknown kind, a slug that is not a name, or
+ *     a doc the linter would reject all come back as typed results with `written: false` — "zero
+ *     writes" is a property a test asserts by listing the tree, not a promise in a comment.
+ *
+ * ⚠ THIS WRITES THIS PLUGIN'S MEMORY AND NOTHING ELSE. It never calls, wraps or delegates to another
+ * plugin's memory tools: the plane it touches is the `.recursive/memory/` tree this plugin scaffolds
+ * and lints, reached through this repo's own paths.
+ */
+export interface MemoryDocSpec {
+    kind: MemoryDocKind;
+    /** The run that wrote it. Stamped into `Source-Runs`, which is what the phase-8 gate reads back. */
+    runId: string;
+    /** Filename stem (`03-ambientcss-redesign`). Sanitised: a slug is a NAME, never a path. */
+    slug: string;
+    /** Defaults to the slug. */
+    title?: string;
+    /** What the doc is about, in one sentence — the field a later run ranks on. */
+    scope: string;
+    /** The lesson itself. Empty is REFUSED rather than padded: an invented lesson is not memory. */
+    body: string;
+    status?: string;
+    ownsPaths?: readonly string[];
+    watchPaths?: readonly string[];
+    tags?: readonly string[];
+    /** The commit the doc was validated against. Defaults to a token NAMING the run (see below). */
+    validatedAtCommit?: string;
+    /** ISO timestamp. Defaults to the moment of the write, which is measured rather than invented. */
+    lastValidated?: string;
+    parent?: string;
+    /**
+     * Runs that contributed BEFORE this one, kept in `Source-Runs` when this write replaces a doc.
+     * Set by the writer on a supersede/update; a caller may set it, and the union is what keeps a
+     * replaced revision's history readable.
+     */
+    priorRuns?: readonly string[];
+}
+export interface MemoryWriteOptions {
+    /**
+     * Replace a shard ANOTHER RUN owns, by archiving it under `memory/archive/` first. Default false:
+     * the write is REFUSED and the refusal names both remedies.
+     */
+    supersede?: boolean;
+    /** The clock, injected so the caller (and a test) decides what "now" is. */
+    now?: () => Date;
+}
+export type MemoryWriteCode = 'WRITTEN' | 'UPDATED' | 'UNCHANGED' | 'REFUSED' | 'INVALID';
+export interface MemoryWriteResult {
+    code: MemoryWriteCode;
+    /** Repo-relative path (`memory/episodes/<slug>.md`); EMPTY only when no path could be resolved. */
+    path: string;
+    /** True only for `WRITTEN` and `UPDATED`. */
+    written: boolean;
+    /** Where a superseded revision was archived, when that happened. */
+    archived: string | null;
+    /** Always says what happened — a silent refusal is a lost work item. */
+    reason: string;
+}
+/** `2026-10-10T08:39:59Z` — the lock fields' own timestamp shape, and the docs' `Last-Validated` one. */
+export declare function isoSeconds(now?: Date): string;
+/** A slug is a FILE NAME: no separator, no traversal, no extension, no leading dot. */
+export declare function sanitizeMemorySlug(slug: string): string;
+/** The repo-relative path a doc gets, or null when the kind or the slug cannot name one. */
+export declare function memoryDocRelativePath(kind: MemoryDocKind, slug: string): string | null;
+/**
+ * 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.
+ */
+export declare function renderMemoryMetadata(input: {
+    type: string;
+    status: string;
+    scope: string;
+    sourceRuns: readonly string[];
+    validatedAtCommit: string;
+    lastValidated: string;
+    ownsPaths?: readonly string[];
+    watchPaths?: readonly string[];
+    tags?: readonly string[];
+    parent?: string;
+}): string;
+/**
+ * Render the whole doc: the canonical header, then the title, then the lesson.
+ *
+ * ⚠ `Validated-At-Commit` DEFAULTS TO A TOKEN THAT NAMES THE RUN, NOT A SHA. A run writing its own
+ * lesson has no commit to be validated against yet, and a placeholder SHA would be a fabricated fact
+ * in the one field a reader uses to decide whether the lesson still holds. The shipped generic docs
+ * use the same convention (`generic-repository-guidance`).
+ */
+export declare function renderMemoryDoc(spec: MemoryDocSpec, options?: {
+    lastValidated?: string;
+}): string;
+/**
+ * The problems that would make the memory plane FAIL this doc — checked with the LINTER'S own field
+ * list, allowed Types and allowed Statuses, so this cannot accept a doc the plane rejects.
+ */
+export declare function memoryDocProblems(content: string): string[];
+/**
+ * The values of a list field (`Source-Runs:`), inline or as bullets.
+ *
+ * ⚠ THE BLOCK ENDS AT THE FIRST BLANK LINE, HEADING OR NEW FIELD, and that strictness is the point:
+ * the alternative is a parser that reads an unrelated bullet list further down the document as
+ * provenance — and provenance is the one thing here that must never be guessed.
+ */
+export declare function parseMemoryListField(content: string, fieldName: string): string[];
+/** The runs a doc's `Source-Runs` names. EXACT matches: `run-1` is not `run-10`. */
+export declare function memoryDocProvenance(content: string): string[];
+/** The task-type token a shard's registry line carries, from the directory it lives in. */
+export declare function taskTypeForMemoryPath(path: string): string;
+/**
+ * Write ONE durable doc, atomically, with provenance — and refuse rather than guess.
+ *
+ * The four decided behaviours (see {@link MemoryDocSpec}'s block comment): atomic, provenance-carrying,
+ * idempotent for the same run, and refused when another run owns the path unless `supersede` is
+ * explicit — in which case the previous revision is ARCHIVED first, so nothing is ever deleted.
+ */
+export declare function writeMemoryDoc(root: string, spec: MemoryDocSpec, options?: MemoryWriteOptions): MemoryWriteResult;
+export interface RunMemoryWriteResult {
+    /** Repo-relative paths actually written (`WRITTEN` or `UPDATED`), in order. */
+    writes: string[];
+    results: MemoryWriteResult[];
+    /** The registry write (`memory/MEMORY.md`), or null when nothing was written. */
+    registry: MemoryWriteResult | null;
+    /** What happened, INCLUDING the failure sentence — a caller must not have to infer it. */
+    reason: string;
+}
+/**
+ * T40 — THE PHASE-8 CALL: write this run's durable docs and register them.
+ *
+ * ⚠ THE RUN ID COMES FROM THE ARGUMENT, NOT FROM EACH SPEC. A spec that named a different run would
+ * write provenance the phase-8 gate then refuses — a doc claiming a write this run did not make —
+ * and the caller would be left holding a file that blocks its own lock. One run per call removes
+ * that possibility instead of documenting it.
+ *
+ * ⚠ THE REGISTRY IS REFRESHED ONLY WHEN SOMETHING WAS WRITTEN, because the failure paths must write
+ * NOTHING (the module's standing contract) and because a registry refreshed over an unchanged plane
+ * is a claim that something changed. `updateMemoryRegistry` is reused rather than reimplemented: a
+ * shard's line is REPLACED, never duplicated, and a shard is never removed.
+ *
+ * ⚠ AND IT IS THE PLANE'S REGISTRY, `.recursive/memory/MEMORY.md` — the file `MEMORY_INDEX_FILE`
+ * names and the same one `bootstrap.ts` marker-upserts. The trigger's older `memory/MEMORY.md` is read
+ * as a FALLBACK so a registry the previous call site wrote is not silently discarded, and it is never
+ * written to: two registries in one workspace would be two answers to "what does this plane hold".
+ */
+export declare function writeRunMemory(root: string, runId: string, specs: readonly MemoryDocSpec[], options?: MemoryWriteOptions): RunMemoryWriteResult;
+/** Every `.recursive/memory/**` path a text declares, in the absolute or repo-relative spelling. */
+export declare function phase8MemoryRefs(text: string): string[];
+export interface Phase8MemoryEvidence {
+    ok: boolean;
+    /** Paths under the plane the artifact declares, repo-relative to the repo root (sorted, deduped). */
+    declared: string[];
+    /** Declared paths that exist on disk. */
+    existing: string[];
+    /** Declared paths whose own text carries THIS run's provenance: the writes that COUNT. */
+    written: string[];
+    reason: string;
+}
+/**
+ * T40 — THE CHECKABLE FACT BEHIND "the run wrote its durable memory".
+ *
+ * Three conditions, and each one exists because of a way the claim could be made without the work
+ * being done: the artifact DECLARES a path under the plane (not prose about memory in general); the
+ * path EXISTS (a declaration is not a write); and the doc on disk carries `Source-Runs` naming THIS
+ * run (a shard the run merely read, or one an earlier run wrote, is not this run's memory).
+ *
+ * ⚠ WHAT IT CANNOT TELL, stated rather than hidden: WHEN the doc was written. A run that wrote a
+ * memory doc before phase 8 and cites it here passes — and the phase 6/7 baselines deny memory-plane
+ * writes outright (`phaseBaselineRules`), so within this workflow the only phase that can produce
+ * such a doc is 8. The check is about the FACT existing at lock time, not about the clock.
+ */
+export declare function phase8MemoryEvidence(root: string, runId: string, artifactText: string, readText?: (path: string) => string | null): Phase8MemoryEvidence;
+/**
+ * T40 — THE REFUSAL, as a sentence, or null when the run may lock.
+ *
+ * ⚠ THE MESSAGE NAMES THE REMEDY, not only the fault. A refusal that says "no memory doc" leaves the
+ * agent to guess a format it cannot guess (nine fields, five allowed Types, a provenance list), which
+ * is how the step became a ticked box in the first place.
+ */
+export declare function phase8MemoryRefusal(root: string, runId: string, artifactText: string, readText?: (path: string) => string | null): string | null;
+/**
+ * T40 — THE LOCK-TIME ENTRY POINT: the refusal for the artifact being locked, or null.
+ *
+ * ⚠ THIS EXISTS SO THE GATE IS ONE LINE AT ITS CALL SITE. The decision (declared → exists → carries
+ * this run's provenance) belongs in this module with the write surface that produces it; `lockArtifact`
+ * should have to say only WHICH artifact it is locking, not how a memory doc is recognised. A caller
+ * that has to reproduce the rule would be a second copy of it.
+ *
+ * ⚠ AND A MISSING ARTIFACT IS NOT THIS GATE'S REFUSAL. `lockArtifact` already refuses an absent
+ * artifact before any gate can run, and returning a memory refusal for a file that does not exist
+ * would replace "the artifact is missing" with a sentence about memory — a misleading diagnosis in
+ * exchange for nothing.
+ */
+export declare function phase8MemoryLockRefusal(root: string, runId: string, artifact: string): string | null;

package/package.json

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