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

package/lib/memory-feedback.d.ts

@@ -17,6 +17,41 @@ export declare const FEEDBACK_FILE = ".recursive/memory/.feedback.json";
 export declare const LEGACY_FEEDBACK_FILE = "memory/.feedback.json";
 /** Where a run records what it was shown. */
 export declare 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 declare 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. */
@@ -45,12 +80,60 @@ export type FeedbackBook = Record<string, FeedbackCounter>;
 export declare function readFeedback(root: string, readFile?: (path: string) => string | null): FeedbackBook;
 /** Read what a run recorded being shown. */
 export declare function readInjections(runDir: string, readFile?: (path: string) => string | null): InjectionRecord[];
+/**
+ * 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 declare function isMemoryReadRecord(record: unknown): record is MemoryReadRecord;
+/**
+ * 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 declare function readMemoryReads(runDir: string, readFile?: (path: string) => string | null): MemoryReadRecord[];
+/**
+ * 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 declare function recordMemoryRead(runDir: string, phase: string, read: {
+    injected: boolean;
+    shards: number;
+    reason: string;
+}, write?: (path: string, content: string) => void, readFile?: (path: string) => string | null): MemoryReadRecord[];
 /**
  * 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 declare function recordInjection(runDir: string, entries: readonly {
     source: string;

package/lib/memory.d.ts

@@ -74,8 +74,21 @@ export declare function retrieveMemory(entries: readonly MemoryEntry[], query: s
  * a filesystem), which is also how the layout stays in ONE place — `.recursive/memory/<kind>/*.md`.
  */
 export declare function readMemoryEntries(readFile: (path: string) => string | null, listFiles: (kind: string) => readonly string[], kinds?: readonly string[]): MemoryEntry[];
-/** Render the retrieved memory for a review bundle: sections a reviewer can cite by title. */
-export declare function renderMemorySection(entries: readonly MemoryEntry[]): string;
+/**
+ * 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 declare function renderMemorySection(entries: readonly MemoryEntry[], context?: MemoryRenderContext): string;
 /**
  * T29 — INJECT MEMORY AT RUN START: the loader.
  *

package/lib/recursive_phase.tool.d.ts

@@ -6,6 +6,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,

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

package/scripts/check-workflow-map-escapes.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * check-workflow-map-escapes.mjs — adversarial escaping check on the generated page.
+ *
+ * WHY A THIRD CHECK. `check-workflow-map.mjs` validates structure (ids, references,
+ * pairing). Neither it nor the generator's own `--verify` would catch the failure
+ * mode that a template-literal renderer actually has: a `${…}` that never
+ * interpolated, an `undefined` that reached the page, an unescaped `<` in prose, a
+ * bare `&`, or an unbalanced brace in a 22 KB inline stylesheet. Those do not throw
+ * — they ship, and they look like content.
+ *
+ * ⚠ THE SCRIPT AND STYLE BLOCKS ARE EXCLUDED FROM THE MARKUP CHECKS, ON PURPOSE.
+ * Inside `<script>` and `<style>`, HTML is RAW TEXT: `index < 0`, `a && b` and `{`
+ * are the language, not markup. A naive checker reports them as defects — it did,
+ * five times, on a file that was correct. A check that fails on correct input is
+ * worse than no check, so the regions are removed before the prose rules run.
+ *
+ * Usage: node scripts/check-workflow-map-escapes.mjs [path]
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const target = resolve(process.argv[2] ?? 'workflow-map/recursive-mode-workflow.html')
+if (!existsSync(target)) {
+  console.error('no such file: ' + target)
+  process.exit(2)
+}
+const html = readFileSync(target, 'utf8')
+const fails = []
+const passes = []
+
+const styleBlock = (html.match(/<style>([\s\S]*?)<\/style>/) || ['', ''])[1]
+const scriptBlock = (html.match(/<script>([\s\S]*?)<\/script>/) || ['', ''])[1]
+/** The document with its raw-text regions removed: what the prose rules apply to. */
+const markup = html.replace(/<style>[\s\S]*?<\/style>/, '').replace(/<script>[\s\S]*?<\/script>/, '')
+
+const check = (label, ok, detail = '') => (ok ? passes.push(label) : fails.push(label + (detail ? ' — ' + detail : '')))
+
+/* 1. no template or JS leftovers reached the page ------------------------- */
+for (const bad of ['${', '[object Object]']) {
+  const n = html.split(bad).length - 1
+  check('no leftover ' + JSON.stringify(bad) + ' in the output', n === 0, 'found ' + n)
+}
+// `undefined` / `NaN` as a WORD are leftovers; as part of a longer identifier they
+// are not. A word boundary is the difference between a real finding and noise.
+for (const bad of ['undefined', 'NaN']) {
+  const n = (markup.match(new RegExp('\\b' + bad + '\\b', 'g')) || []).length
+  check('no literal ' + bad + ' in the rendered content', n === 0, 'found ' + n)
+}
+check('no unresolved citation key reached the page', !/(^|[^a-zA-Z])SRC\.[a-zA-Z]/.test(markup))
+
+/* 2. markup escaping ------------------------------------------------------ */
+const strayLt = [...markup.matchAll(/<(?![/!a-zA-Z])/g)]
+check('no stray `<` in the rendered content', strayLt.length === 0, strayLt.length + ' found')
+const bareAmp = [...markup.matchAll(/&(?!(amp|lt|gt|quot|apos|#\d+|#x[0-9a-fA-F]+);)/g)]
+check('no bare `&` in the rendered content', bareAmp.length === 0, bareAmp.length + ' found')
+const rawLtInTag = [...markup.matchAll(/<[a-zA-Z][^>]*>/g)].filter((m) => m[0].slice(1).includes('<'))
+check('no `<` inside a tag (an unescaped attribute value)', rawLtInTag.length === 0, rawLtInTag.length + ' found')
+
+/* 3. balanced raw-text regions ------------------------------------------- */
+const braces = (s) => [(s.match(/{/g) || []).length, (s.match(/}/g) || []).length]
+const [ob, cb] = braces(styleBlock)
+check('the inline CSS has balanced braces', ob === cb, ob + ' open / ' + cb + ' close')
+check('exactly one <style> block', (html.match(/<style>/g) || []).length === 1)
+check('exactly one <script> block', (html.match(/<script>/g) || []).length === 1)
+check('<style> and </style> balance', (html.match(/<style>/g) || []).length === (html.match(/<\/style>/g) || []).length)
+check('<script> and </script> balance', (html.match(/<script>/g) || []).length === (html.match(/<\/script>/g) || []).length)
+check('the script block contains no nested closing script tag', !scriptBlock.includes('</script'))
+
+/* 4. the SVG is well formed enough to render ----------------------------- */
+const svg = (html.match(/<svg[\s\S]*?<\/svg>/) || [''])[0]
+check('there is exactly one inline <svg>', (html.match(/<svg/g) || []).length === 1)
+check('the svg has a viewBox', /viewBox="[^"]+"/.test(svg))
+check('the svg is labelled for assistive technology', /role="img"[^>]*aria-label="[^"]+"/.test(html))
+check('svg <text> elements balance', (svg.match(/<text/g) || []).length === (svg.match(/<\/text>/g) || []).length)
+check('every svg <rect> is self-closed', (svg.match(/<rect[^>]*\/>/g) || []).length === (svg.match(/<rect/g) || []).length)
+check('every svg <path> is self-closed', (svg.match(/<path[^>]*\/>/g) || []).length === (svg.match(/<path/g) || []).length)
+check('every svg <polygon> is self-closed', (svg.match(/<polygon[^>]*\/>/g) || []).length === (svg.match(/<polygon/g) || []).length)
+
+/* 5. no attribute is left unquoted ---------------------------------------
+   Parsed attribute by attribute, not by a scanning regex. A scanning regex reports
+   `content="width=device-width, initial-scale=1"` as an unquoted attribute, because
+   the text `scale=1` looks exactly like `name=value` — it did, on a correct file.
+   So: take each start tag, strip quoted regions first, and only then look for `=` at
+   all. That is the same "remove the raw text, then judge" discipline the rest of
+   this script uses. */
+const unquoted = []
+for (const tag of markup.matchAll(/<[a-zA-Z][^>]*>/g)) {
+  const stripped = tag[0].replace(/"[^"]*"/g, '""').replace(/'[^']*'/g, "''")
+  for (const m of stripped.matchAll(/([a-zA-Z-]+)=([^"'\s>][^\s>]*)/g)) unquoted.push(tag[0].slice(0, 70) + '  →  ' + m[0])
+  for (const m of stripped.matchAll(/([a-zA-Z-]+)=(?=[\s>]|$)/g)) unquoted.push(tag[0].slice(0, 70) + '  →  ' + m[0] + ' (no value)')
+}
+check('every attribute value is quoted', unquoted.length === 0, unquoted.slice(0, 3).join(' | '))
+
+/* report ------------------------------------------------------------------ */
+console.log('check-workflow-map-escapes — adversarial escaping and structure\n')
+console.log('  file: ' + target)
+console.log('  markup: ' + markup.length.toLocaleString('en-US') + ' bytes  ·  css: '
+  + styleBlock.length.toLocaleString('en-US') + '  ·  js: ' + scriptBlock.length.toLocaleString('en-US') + '\n')
+for (const p of passes) console.log('  PASS  ' + p)
+for (const f of fails) console.log('  FAIL  ' + f)
+console.log('\n  ' + passes.length + ' passed, ' + fails.length + ' failed')
+process.exit(fails.length === 0 ? 0 : 1)