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

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

@@ -28,6 +28,11 @@ export interface Decision {
  * 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>;

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.5.0",
+  "version": "0.6.1",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/references/artifact-template.md

@@ -2437,49 +2437,32 @@ Approval: PASS
 
 Before locking (or when a lock verification fails unexpectedly), lint the run artifacts for required header fields, required section headings, and TODO completion rules:
 
-```powershell
-# Python (cross-platform):
-python ./.agents/skills/recursive-mode/scripts/lint-recursive-run.py --run-id "<run-id>"
-# Or, when running from this repo:
-python ./.recursive/scripts/lint-recursive-run.py --run-id "<run-id>"
-python3 ./.agents/skills/recursive-mode/scripts/lint-recursive-run.py --run-id "<run-id>"
-python3 ./.recursive/scripts/lint-recursive-run.py --run-id "<run-id>"
-
-# Treat WARN as FAIL
-python ./.agents/skills/recursive-mode/scripts/lint-recursive-run.py --run-id "<run-id>" --strict
-python ./.recursive/scripts/lint-recursive-run.py --run-id "<run-id>" --strict
-python3 ./.agents/skills/recursive-mode/scripts/lint-recursive-run.py --run-id "<run-id>" --strict
-python3 ./.recursive/scripts/lint-recursive-run.py --run-id "<run-id>" --strict
-
-# Lint specific run
-.\.agents\skills\recursive-mode\scripts\lint-recursive-run.ps1 -RunId "<run-id>"
-# Or, when running from this repo:
-.\scripts\lint-recursive-run.ps1 -RunId "<run-id>"
-
-# Treat WARN as FAIL
-.\.agents\skills\recursive-mode\scripts\lint-recursive-run.ps1 -RunId "<run-id>" -Strict
-.\scripts\lint-recursive-run.ps1 -RunId "<run-id>" -Strict
+```text
+# One artifact (defaults to the run's current phase). `mode: "summary"` returns a few
+# findings plus the true totals; `full` (default) returns up to 200 per list. When a list
+# is clipped, `elided` says how many and how to see the rest.
+recursive_lint  { "runId": "<run-id>", "artifact": "<artifact>.md", "mode": "summary" }
+
+# Treat WARN as FAIL is not a flag here: `errors` are the failures, `warnings` are not,
+# and both lists come back with their true `failCount`/`warnCount`.
+
+# The same read, from the slash-command surface
+/recursive status <run-id>
 ```
 
+This plugin is TypeScript and runs the linter in-process: there is no `lint-recursive-run.py`/`.ps1` to call, and no `.recursive/scripts/` to call it from.
+
 ## Locking Commands
 
 Preferred:
 
-```powershell
-# Python (cross-platform)
-python ./.agents/skills/recursive-mode/scripts/recursive-lock.py --run-id "<run-id>" --artifact "<artifact>.md"
-# Or, when running from this repo:
-python ./.recursive/scripts/recursive-lock.py --run-id "<run-id>" --artifact "<artifact>.md"
-python3 ./.agents/skills/recursive-mode/scripts/recursive-lock.py --run-id "<run-id>" --artifact "<artifact>.md"
-python3 ./.recursive/scripts/recursive-lock.py --run-id "<run-id>" --artifact "<artifact>.md"
-
-# PowerShell
-.\.agents\skills\recursive-mode\scripts\recursive-lock.ps1 -RunId "<run-id>" -Artifact "<artifact>.md"
-# Or, when running from this repo:
-.\scripts\recursive-lock.ps1 -RunId "<run-id>" -Artifact "<artifact>.md"
+```text
+# Lock one artifact once its gates pass. It refuses a lock whose gates or whose earlier
+# phases are unmet, and writes Status: LOCKED, LockedAt and LockHash.
+recursive_lock  { "runId": "<run-id>", "artifact": "<artifact>.md" }
 ```
 
-The lock command is the primary supported path. It must refuse to lock artifacts whose required gates or lint-critical structure are still invalid.
+The lock tool is the primary supported path. It refuses to lock artifacts whose required gates or lint-critical structure are still invalid.
 
 Manual fallback for hash computation only:
 
@@ -2521,34 +2504,16 @@ sed '/^LockHash:/d' .recursive/run/<run-id>/<artifact>.md | tr -d '\r' | sha256s
 
 ### Automated Verification
 
-Use the provided script to verify all locks in a run:
+Use the plugin's own tool to verify all locks in a run — there is no verifier script:
 
-```bash
-# Verify specific run
-python ./.agents/skills/recursive-mode/scripts/verify-locks.py --run-id "<run-id>"
-# Or, when running from this repo:
-python ./.recursive/scripts/verify-locks.py --run-id "<run-id>"
-python3 ./.agents/skills/recursive-mode/scripts/verify-locks.py --run-id "<run-id>"
-python3 ./.recursive/scripts/verify-locks.py --run-id "<run-id>"
-
-# Fix incorrect hashes (use with caution)
-python ./.agents/skills/recursive-mode/scripts/verify-locks.py --run-id "<run-id>" --fix
-# Or, when running from this repo:
-python ./.recursive/scripts/verify-locks.py --run-id "<run-id>" --fix
-python3 ./.agents/skills/recursive-mode/scripts/verify-locks.py --run-id "<run-id>" --fix
-python3 ./.recursive/scripts/verify-locks.py --run-id "<run-id>" --fix
-```
+```text
+# One run: the phase table and per-artifact lock state. A LockHash that no longer matches
+# its content is reported as TAMPERED, named against the receipt it was locked under.
+recursive_status  { "runId": "<run-id>" }
 
-```powershell
-# Verify specific run
-.\.agents\skills\recursive-mode\scripts\verify-locks.ps1 -RunId "<run-id>"
-# Or, when running from this repo:
-.\scripts\verify-locks.ps1 -RunId "<run-id>"
-
-# Fix incorrect hashes (use with caution)
-.\.agents\skills\recursive-mode\scripts\verify-locks.ps1 -RunId "<run-id>" -Fix
-# Or, when running from this repo:
-.\scripts\verify-locks.ps1 -RunId "<run-id>" -Fix
+# There is deliberately no `--fix`. Re-hashing a changed artifact would erase the only
+# evidence that it changed, so the mismatch is reported and the decision (restore the
+# content, or record an addendum) stays with the agent.
 ```
 
 ### Manual Verification

package/references/bodies/claude.md

@@ -3,5 +3,5 @@
 - Canonical repository memory lives under `/.recursive/memory/`.
 - Read `/.recursive/memory/MEMORY.md` before loading any other memory docs.
 - Load only the memory docs relevant to the current task.
-- When repository experiential memory may help, run `python .recursive/scripts/recursive-training-loader.py --repo-root . --query "<task>" --files "<path1,path2>"`.
+- When repository experiential memory may help, load it through the plugin's own TS loader: `recursive_phase` returns the prior-run memory shards relevant to this run and phase (with the reason when none matched), and `/recursive memory "<task>" [--phase <nn>]` prints the same selection with its score components. There is no script to run and no `.recursive/scripts/` step — retrieval is in-process.
 - Treat this file as a pointer only; the canonical memory store remains `/.recursive/memory/`.

package/references/bodies/copilot.md

@@ -3,5 +3,5 @@
 - Canonical repository memory lives under `/.recursive/memory/`.
 - Read `/.recursive/memory/MEMORY.md` before loading any other memory docs.
 - Load only the memory docs relevant to the current task.
-- When repository experiential memory may help, run `python .recursive/scripts/recursive-training-loader.py --repo-root . --query "<task>" --files "<path1,path2>"`.
+- When repository experiential memory may help, load it through the plugin's own TS loader: `recursive_phase` returns the prior-run memory shards relevant to this run and phase (with the reason when none matched), and `/recursive memory "<task>" [--phase <nn>]` prints the same selection with its score components. There is no script to run and no `.recursive/scripts/` step — retrieval is in-process.
 - Treat this file as a pointer only; the canonical memory store remains `/.recursive/memory/`.

package/references/bodies/cursorrules.md

@@ -2,6 +2,8 @@
 # Canonical repository memory lives under `/.recursive/memory/`.
 # Read `/.recursive/memory/MEMORY.md` before loading any other memory docs.
 # Load only the memory docs relevant to the current task.
-# When repository experiential memory may help, run:
-#   python .recursive/scripts/recursive-training-loader.py --repo-root . --query "<task>" --files "<path1,path2>"
+# When repository experiential memory may help, load it through the plugin's own TS loader: the
+# `recursive_phase` tool returns the prior-run memory shards relevant to this run and phase (with the
+# reason when none matched), and `/recursive memory "<task>" [--phase <nn>]` prints the same selection
+# with its score components. There is no script to run and no `.recursive/scripts/` step.
 # This file is only a pointer surface; the canonical memory store remains `/.recursive/memory/`.

package/references/bodies/memory-router.md

@@ -16,7 +16,7 @@ Control-plane docs are not memory docs:
 - Read this file before loading any other memory docs.
 - Load only the memory docs relevant to the current task.
 - If the task may benefit from prior recursive-mode experiential learnings, use this index to identify the relevant docs under `/.recursive/memory/training/` and `/.recursive/memory/domains/`.
-- The optional `recursive-training-sync.py` helper is read-only; it prints startup guidance about what to read, but does not modify `MEMORY.md` or the memory plane.
+- The plugin loads this plane **in-process, in TypeScript**: the `recursive_phase` tool returns the shards that match the run and the phase in play, and `/recursive memory "<task>" [--phase <nn>]` prints the same selection with the score component behind every shard and a reason for every shard it left out. There is no `recursive-training-loader`/`recursive-training-sync` script to run and no `.recursive/scripts/` helper in this plugin.
 - If the task plans delegated review, subagent help, review bundles, smoke-harness portability work, or capability-sensitive execution, read `/.recursive/memory/skills/SKILLS.md` and then load the relevant skill-memory shards.
 - If Phase 8 will need to promote durable lessons, first capture run-local skill usage in the run artifact and only then promote generalized conclusions into skill-memory shards.
 - Prefer `Status: CURRENT` docs for planning and execution.

package/references/bodies/recursive-agents-router.md

@@ -48,10 +48,11 @@ It exists to reduce blind doc-by-doc scanning. It is not a second workflow spec.
   - the installed `recursive-router`, `recursive-subagent`, and `recursive-review-bundle` skills
 - Working on memory behavior:
   - `/.recursive/memory/MEMORY.md`
-  - the installed `recursive-training` skill
-  - `/.recursive/scripts/recursive-training-loader.py`
-  - `/.recursive/memory/training/`
+  - the memory shards themselves: `/.recursive/memory/domains/`, `/.recursive/memory/training/`, and the rest of the registry in `MEMORY.md`
+  - the plugin's **TS** memory surfaces — `recursive_phase` (injects the shards that match this run and phase) and `/recursive memory "<task>" [--phase <nn>]` (the same selection, printed with its score components)
+  - `recursive_closeout --phase 08` for the run-close training trigger, which runs in-process; its extractor is the operator environment variable `RECURSIVE_TRAINING_EXTRACTOR_CMD`
   - `/.recursive/memory/skills/SKILLS.md`
+  - ⚠ there is no `.recursive/scripts/` helper and no Python anywhere in this plugin — lint, lock, status, closeout and retrieval all run in-process, so a script path is not a route to any of them
 
 ## Non-Canonical Bridges