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

package/references/bootstrap/RECURSIVE.md

@@ -90,8 +90,8 @@ Required read behavior:
 - If relevant prior runs are found, read only the docs needed from those runs to understand the affected codebase areas before writing the new run artifacts.
 - If no relevant prior runs are identified, skip that step.
 - After reading `MEMORY.md`, load only the memory docs relevant to the current task. Do not load the entire memory tree by default.
-- If the task may benefit from prior experiential learnings, load only the relevant docs under `/.recursive/memory/training/` and `/.recursive/memory/domains/`, preferably by using the training loader with filesystem-backed discovery.
-- If the optional `recursive-training` skill is installed, run `/.recursive/scripts/recursive-training-loader.py` after reading `MEMORY.md` and before planning or implementation whenever the task may benefit from experiential memory. If no automatic hook is wired, the agent must still manually load relevant training docs from the memory index when they matter.
+- If the task may benefit from prior experiential learnings, load only the relevant docs under `/.recursive/memory/training/` and `/.recursive/memory/domains/`.
+- The plugin loads those docs itself, **in-process and in TypeScript**: call `recursive_phase` on entering a phase and it returns the memory shards that match the run and the phase in play, with the reason stated when none matched. For an on-demand lookup, `/recursive memory "<task>" [--phase <nn>]` prints the same selection with the score component behind each shard and a reason for each shard it excluded. Nothing is loaded by running a script — this plugin ships no `.recursive/scripts/` helper and no Python — and nothing is ever fabricated: an empty result means continue normally.
 - If the run plans delegated review, subagent help, review bundles, smoke harness portability work, or other skill-sensitive execution, load `/.recursive/memory/skills/SKILLS.md` and the relevant skill-memory shards before planning or auditing.
 - Prefer `Status: CURRENT` memory docs for planning/execution.
 - `Status: SUSPECT` memory docs may be used as leads but must be revalidated before trust.
@@ -559,9 +559,10 @@ Phase 8 — Memory maintenance and impact review
 - Audit must verify memory updates and status transitions against reviewed final product/worktree paths, touched memory docs, prior memory truth, `STATE.md`, and `DECISIONS.md`
 - Must include `## Run-Local Skill Usage Capture` with concrete availability / attempted / used / worked-well / issue / recommendation fields whenever skill usage is relevant to the run
 - Must include `## Skill Memory Promotion Review` explaining what durable lessons were promoted, what stayed run-local, and why
-- If the optional `recursive-training` skill is installed, run `/.recursive/scripts/recursive-training-phase8-trigger.py` immediately after `08-memory-impact.md` locks to extract or refresh cross-run experiential learnings.
-- `recursive-lock` does not invoke training by itself. After Phase 8 locks, either run the trigger directly or re-run `recursive-closeout --phase 08` (without `--force`) so the helper can call `recursive-training-phase8-trigger.py --auto`.
-- Treat trigger/GRPO exit `2` (extractor unavailable) and exit `3` (zero items written) as unsuccessful training; do not claim the memory plane was updated.
+- The training pass runs **in-process**: re-run the closeout for the phase — `recursive_closeout` with `phase 08` for a run whose `08-memory-impact.md` has already been closed out once — and the plugin's phase-8 trigger extracts or refreshes cross-run experiential learnings then.
+- `recursive_lock` does not invoke training by itself, and neither does the FIRST closeout of phase 08: training at the first lock would train the run on itself. The trigger fires on the closeout **re-run**, and it needs at least two runs with a LOCKED `08-memory-impact.md` before it will extract — one run is an anecdote, not evidence. There is no trigger script to run.
+- The extractor is the operator environment variable `RECURSIVE_TRAINING_EXTRACTOR_CMD`, and its answer comes back through a response file rather than a pipe. An unset command is a named failure, never a silent success.
+- Treat trigger exit `2` (extractor unavailable) and exit `3` (nothing usable to extract, including too little evidence) as unsuccessful training; do not claim the memory plane was updated.
 - **TODO Requirement:** Phase artifact MUST include `## TODO` section with checkable items
 - **TODO Enforcement:** ALL TODO items must be checked off before locking
 - **Completion rule:** the run is not fully complete before Phase 8 passes
@@ -752,7 +753,7 @@ Recursive phases are one-way. Iteration is allowed within a phase, but after a p
 ### DRAFT vs LOCKED
 
 - While a phase is in progress, its output artifact status is `DRAFT`. The agent may revise it until both gates pass.
-- When both gates pass, the agent must lock the artifact with `.recursive/scripts/recursive-lock.py` or `.recursive/scripts/recursive-lock.ps1`. The lock command is the primary supported path and must:
+- When both gates pass, the agent must lock the artifact with the **`recursive_lock` tool**. It is the primary supported path and it must:
   1) verify the artifact is lockable,
   2) set Status to `LOCKED`,
   3) set `LockedAt`,
@@ -779,11 +780,11 @@ that contains its own hash.
 
 #### Preferred: use the lock command
 
-Use `.recursive/scripts/recursive-lock.py` (cross-platform) or `.recursive/scripts/recursive-lock.ps1` (PowerShell) to lock a draft artifact. Those commands validate lockability, write `Status: LOCKED`, write `LockedAt`, and compute `LockHash` using the canonical normalization rules.
+Use the **`recursive_lock`** tool to lock a draft artifact — run **`recursive_lint`** first when you want the artifact machine-checked before you attempt the lock. It validates lockability, writes `Status: LOCKED`, writes `LockedAt`, and computes `LockHash` using the canonical normalization rules; it refuses a lock whose gates or whose earlier phases are unmet. This plugin runs in-process in TypeScript: there is no lock script to call under `.recursive/scripts/`, and no Python in the package at all.
 
 #### Secondary: verify an existing lock
 
-Use `.recursive/scripts/verify-locks.py` (cross-platform) or `.recursive/scripts/verify-locks.ps1` (PowerShell) to verify and (optionally) fix mismatched hashes on already locked artifacts.
+Use the **`recursive_status`** tool to verify already locked artifacts: it recomputes every `LockHash` and reports each artifact's state, naming a `Status: LOCKED` artifact whose hash no longer matches as `TAMPERED`. There is no separate verifier to call, and deliberately no fix-up mode — see the tampering action below.
 
 #### Manual computation examples
 
@@ -1763,8 +1764,8 @@ The LockHash is a SHA-256 hash of the normalized artifact content at lock time.
 "How to compute LockHash" above for the canonical normalization rules.
 
 **Preferred:**
-- use `.recursive/scripts/verify-locks.py` for cross-platform verification (and optional fixing)
-- use `.recursive/scripts/verify-locks.ps1` when running in PowerShell environments
+- use the `recursive_status` tool: it recomputes every `LockHash` under the run and reports the lock state per artifact
+- use the `recursive_lint` tool to machine-check one artifact against its phase rules before or after locking
 
 **PowerShell:**
 ```powershell
@@ -1796,28 +1797,18 @@ A phase artifact is **lock-valid** only when ALL of the following are true:
 
 ### Automated Verification
 
-Use the provided verifier scripts to verify all locks:
+Use the plugin's own tools to verify locks. There is no verifier script to run:
 
-```bash
-# Verify specific run
-python ./.recursive/scripts/verify-locks.py --run-id "<run-id>"
-
-# Scan all runs
-python ./.recursive/scripts/verify-locks.py
-
-# Fix incorrect hashes (use with caution)
-python ./.recursive/scripts/verify-locks.py --run-id "<run-id>" --fix
-```
-
-```powershell
-# Verify specific run
-.\.agents\skills\recursive-mode\scripts\verify-locks.ps1 -RunId "<run-id>"
+```text
+# One run: the phase table and per-artifact lock state. A LockHash that no longer
+# matches its content is reported as TAMPERED, with the receipt it was locked under.
+recursive_status  { "runId": "<run-id>" }
 
-# Scan all runs
-.\.agents\skills\recursive-mode\scripts\verify-locks.ps1
+# All runs in the workspace, from the slash-command surface
+/recursive status <run-id>
 
-# Fix incorrect hashes (use with caution)
-.\.agents\skills\recursive-mode\scripts\verify-locks.ps1 -RunId "<run-id>" -Fix
+# Machine-check a single artifact against its phase rules before locking it
+recursive_lint  { "runId": "<run-id>", "artifact": "<artifact>.md" }
 ```
 
 ### Tampering Detection
@@ -1829,7 +1820,7 @@ If LockHash doesn't match the canonical normalized content:
 3. **Line endings changed** (CRLF vs LF)
 
 **Action:**
-- If accidental: Use `verify-locks.py --fix` (or `verify-locks.ps1 -Fix`) to update hash
+- If accidental: restore the artifact's content. The plugin has **no `--fix` on purpose** — re-hashing a changed artifact would erase the only evidence that it changed, so the mismatch is reported as `TAMPERED` and the decision (restore the content, or record an addendum) stays with you.
 - If intentional modification: This is an anti-pattern. Use addenda instead.
 
 ### Phase Transition Lock Chain

package/src/bootstrap.ts

@@ -2,16 +2,18 @@
  * Idempotent scaffold installer (R3). TS port of install-recursive-mode.py's
  * core: bootstrap the FULL canonical /.recursive/ control plane + cross-tool
  * bridges byte-identically (RECURSIVE.md marker-wrapped, AGENTS.md, STATE/
- * DECISIONS, memory routers + shards, config/recursive-router.json, .gitignore,
- * vendored runtime scripts copied into .recursive/scripts/), plus the
- * agent/session-start Stage B (new vs resume) workspace-scoped to the session's
- * control-plane root (R1).
+ * DECISIONS, memory routers + shards, config/recursive-router.json, .gitignore),
+ * plus the agent/session-start Stage B (new vs resume) workspace-scoped to the
+ * session's control-plane root (R1).
+ *
+ * ⚠ NO `.recursive/scripts/` IS CREATED, and a legacy one is removed once it is empty — see the block in
+ * the scaffold below for the measurement that decided it.
  *
  * Templates + bodies + runtime scripts are SHIPPED package files under
  * references/ (never inlined TS string literals) and resolved relative to this
  * module (package install location), never process.cwd().
  */
-import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync, readFileSync, rmSync } from 'node:fs'
+import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync, readFileSync, rmSync, rmdirSync } from 'node:fs'
 import { join, dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
@@ -224,15 +226,21 @@ export function bootstrapScaffold(root: string): BootstrapResult {
     '.recursive/memory/skills/issues/.gitkeep', '.recursive/memory/skills/patterns/.gitkeep', '.recursive/run/.gitkeep',
   ]) noteFile(rel, '')
 
-  // Runtime scripts: TS-only scaffold (R2). No .py/.ps1 are vendored; the
-  // plugin's lint/lock/status/init run in-process via TS tools, so the
-  // scaffold carries an empty .recursive/scripts/ dir (kept for canonical
-  // tree-shape parity with the golden fixture).
-  noteDir('.recursive/scripts')
-  // R3 (run 09): TS-only repair — drop python-era artifacts from an EXISTING
-  // workspace's .recursive/scripts/ (the pre-0.1.6 scaffold vendored 29 .py +
-  // .ps1 wrappers; those are no longer shipped or needed). Deletes only
-  // .py/.ps1 under scripts/; never touches user content elsewhere.
+  // Runtime scripts: TS-ONLY, AND THE EMPTY DIRECTORY IS NO LONGER CREATED.
+  //
+  // ⚠ WHY IT GONE. It used to be scaffolded EMPTY — no .py/.ps1 is vendored, because lint/lock/status/
+  // closeout all run in-process as TS tools — while two shipped documents pointed INTO it: the `CLAUDE.md`
+  // memory pointers at `.recursive/scripts/recursive-training-loader.py`, and the canonical `RECURSIVE.md`
+  // at `.recursive/scripts/recursive-lock.py` / `verify-locks.py`. An empty directory that shipped documents
+  // send an agent into is a TRAP, not tree-shape parity: the agent follows the documented path, finds
+  // nothing, and the memory plane those documents promised never loads. Measured in three live runs — the
+  // directory was empty in every one, and no run ever locked a phase. Nothing in this package reads or
+  // executes anything from it; the only code that ever touched it is the legacy cleanup below.
+  //
+  // ⚠ THE CLEANUP STAYS, AND NOW FINISHES THE JOB. The pre-0.1.6 scaffold vendored 29 .py + .ps1 wrappers
+  // into real workspaces, so those are still deleted wherever they are found — and the directory is then
+  // removed when it is EMPTY, because leaving it behind is the same trap for the next agent. A directory
+  // still holding anything else is that user's and is left untouched.
   {
     const scriptsDir = join(recursiveRoot, 'scripts')
     if (existsSync(scriptsDir)) {
@@ -241,6 +249,14 @@ export function bootstrapScaffold(root: string): BootstrapResult {
           rmSync(join(scriptsDir, name), { force: true })
         }
       }
+      // ⚠ `rmdirSync`, NOT `rmSync({ recursive: false })`: measured — the latter throws `ERR_FS_EISDIR`
+      // on a directory, and a silently caught error here would leave exactly the empty directory this
+      // block exists to remove. A spec asserts the directory is GONE, so the wrong call cannot hide.
+      try {
+        if (readdirSync(scriptsDir).length === 0) rmdirSync(scriptsDir)
+      } catch {
+        // A directory that cannot be removed is not a scaffold failure, and never a reason to stop.
+      }
     }
   }
 

package/src/enforcement.ts

@@ -8,6 +8,7 @@
 import { existsSync, readdirSync } from 'node:fs'
 import { join, isAbsolute, resolve, sep } from 'node:path'
 import { getLockStatus } from './lock.ts'
+import { runIdProblem } from './run-id.ts'
 import { validateTransition, type GateCheckResult } from './lifecycle.ts'
 import {
   evaluateToolPolicy, loadToolPolicyFile,
@@ -199,11 +200,18 @@ export interface GuardTransition {
  * and the payload is built by `buildGateBlockAsk` — the SAME builder the lock tool uses, so the two
  * refusals cannot offer different options. It is absent on every decision that is not a lock-order
  * refusal decided from real blockers, which is why every reader must treat it as optional.
+ *
+ * ⚠ ISSUE 2 (b): `runId` IS THE RUN THE GUARD RESOLVED AND READ — optional and additive for the same
+ * reason. `evaluateToolGuard` sets it on EVERY decision, allow included, and `index.ts` logs it instead of
+ * the filesystem's active run: a record whose `runId` came from one resolution while the rule read another
+ * is exactly the two-answers-in-one-payload defect this pairs with. It stays OPTIONAL so a hand-built
+ * decision (and `coerceAskToDecision`'s key-frozen input/output) is unaffected; a reader falls back to the
+ * active run when it is absent, which is the pre-existing behaviour.
  */
 export type ToolGuardDecision =
-  | { kind: 'allow'; warn?: string; rule?: GuardRule; transition?: GuardTransition }
-  | { kind: 'deny'; reason: string; rule?: GuardRule; transition?: GuardTransition; ask?: GateBlockAsk }
-  | { kind: 'ask'; reason?: string; rule?: GuardRule; transition?: GuardTransition }
+  | { kind: 'allow'; warn?: string; rule?: GuardRule; transition?: GuardTransition; runId?: string }
+  | { kind: 'deny'; reason: string; rule?: GuardRule; transition?: GuardTransition; ask?: GateBlockAsk; runId?: string }
+  | { kind: 'ask'; reason?: string; rule?: GuardRule; transition?: GuardTransition; runId?: string }
 
 export interface ToolExecLike {
   name: string
@@ -295,6 +303,75 @@ export function currentPhaseArtifact(worktreeRoot: string, runId: string): strin
   return inForce !== '' ? inForce : best
 }
 
+/**
+ * ISSUE 2 (a) — THE RUN A GUARD CALL IS ABOUT, and the one whose tree it may read.
+ *
+ * THE DEFECT THIS ANSWERS, measured before the fix: `recursive_lock {runId: 'run-b', artifact:
+ * '01-as-is.md'}` was REFUSED with `monotonic lock-order: … 00-requirements.md (DRAFT)` — run-A's blocker —
+ * while `run-b` had `00-requirements.md` LOCKED and `01-as-is.md` DRAFT, so locking it in run-b was LEGAL.
+ * The guard resolved the run from the FILESYSTEM (`resolveRunDir`, i.e. the active/newest run) while the
+ * tool resolves it from `args.runId`, so the guard judged a DIFFERENT RUN than the call was about. Under
+ * `advisory` the deny was coerced to an allow-with-warning and the tool refused on its own terms, which is
+ * why the strict default is what made it bite.
+ *
+ * SO THE RULE IS: for a LOCK call that NAMES a run, the guard judges THAT RUN. It is the same choice the
+ * tool makes, so the two layers cannot disagree about which tree the ordering rule is a property of. A
+ * caller that names nothing (every real `write`, and a lock that relies on the active run) is unaffected:
+ * the active run still governs, which is what the write-side rules rely on.
+ *
+ * ⚠ THIS IS SCOPED TO THE LOCK TOOLS DELIBERATELY, and the scope is per rule, not per convenience:
+ *
+ *   - `lock-order` (`recursive_lock*`) — the caller's run WINS. The tool acts on `args.runId`, and the
+ *     rule is about THAT run's prerequisites, so the guard must not answer for another run. This is the
+ *     measured defect.
+ *   - `locked-write` (the write-tool family) — NOT APPLICABLE, by construction: the rule resolves no run
+ *     at all. It reads the target file's own `Status:` through the path the caller named, so there is no
+ *     run to prefer and nothing could disagree.
+ *   - `phase-order` (the write-tool family) — the ACTIVE run KEEPS WINNING, and this function does not
+ *     touch it. Two reasons, both deliberate: (1) a `write` call carries no run id — no write tool declares
+ *     one — so consulting `args.runId` here would hand a caller a way to ESCAPE the active run's ordering
+ *     by naming some other run in an argument the tool ignores; and (2) the rule's declared scope is the
+ *     run being worked in (it abstains for another run's tree, documented in `phaseOrderRule`), and moving
+ *     that scope would be a new refusal, not a consistency fix.
+ *
+ * ⚠ A CALLER-SUPPLIED ID IS A NAME, NEVER A PATH, and it is validated before it can point the guard at
+ * anything: the id is trimmed the way `recursive_lock` trims it, then put through `runIdProblem` — the
+ * SAME gate the run-id-shaped tools use, which refuses separators, drive specifiers, `..`, a colon, a
+ * leading/trailing dot and an over-long name — and finally the resolved directory must sit UNDER this
+ * worktree's `<root>/.recursive/run`, the containment rule `runtime.ts` applies to a run directory.
+ *
+ * An id that fails any of those is NOT USED: the guard falls back to the active run, exactly as it behaved
+ * before this change. Falling back (rather than denying) is deliberate: an unusable id is a caller mistake
+ * the tool itself refuses (`BAD_RUN_ID` / `Artifact not found`), and inventing a new guard refusal for it
+ * would be a second, competing answer to a question `runIdProblem` already owns.
+ *
+ * A usable id does NOT have to name an EXISTING run: a run with no tree has no unlocked prerequisites, so
+ * the ordering rule abstains and the LOCK TOOL still refuses the lock (it checks the artifact exists before
+ * anything else). Requiring existence would instead re-introduce the defect in its ugliest form — a refusal
+ * built from ANOTHER run's blockers.
+ */
+export function resolveGuardRunId(
+  name: string,
+  args: Record<string, unknown>,
+  worktreeRoot: string,
+  activeRunId: string,
+): string {
+  if (!LOCK_TOOL_NAMES.has(name) || !worktreeRoot) return activeRunId
+  const raw = args.runId
+  if (typeof raw !== 'string') return activeRunId
+  // The lock tool's own normalisation (`args.runId.trim()`), applied before the shape gate so a padded id
+  // is judged as the name the tool will act on, not as the padded string the guard happened to receive.
+  const declared = raw.trim()
+  if (declared === '' || runIdProblem(declared) !== null) return activeRunId
+  // CONTAINMENT. With a shape-valid name the join cannot escape, but the rule is asserted rather than
+  // assumed: a future change to the id grammar must not be able to move the guard's read outside the run
+  // layer, where the "prerequisites" it found would belong to something else entirely.
+  const runRoot = resolve(worktreeRoot, '.recursive', 'run')
+  const prefix = runRoot.endsWith(sep) ? runRoot : runRoot + sep
+  if (!resolve(join(runRoot, declared)).startsWith(prefix)) return activeRunId
+  return declared
+}
+
 /**
  * `mode` is the gate's configured posture. Its parameter default FOLLOWS the config
  * default by REFERENCE (`DEFAULT_ENFORCEMENT.toolGuards`) rather than repeating the
@@ -315,7 +392,11 @@ export function evaluateToolGuard(
 ): ToolGuardDecision {
   const name = exec.name
   const args = (exec.arguments ?? {}) as Record<string, unknown>
-  const runId = typeof activeRunId === 'string' ? activeRunId.trim() : ''
+  // ⚠ ISSUE 2 — THE RUN IS RESOLVED ONCE, HERE, for the whole call: the policy's phase baseline, the
+  // lock-order rule's subject and the decision's own `runId` all read this one answer, so a refusal cannot
+  // describe a run the rule did not read. See `resolveGuardRunId` for which rule prefers the caller's run
+  // and why the others do not.
+  const runId = resolveGuardRunId(name, args, worktreeRoot, typeof activeRunId === 'string' ? activeRunId.trim() : '')
   const runDir = join(worktreeRoot, '.recursive', 'run', runId)
 
   // T15: the transition gate is consulted BEFORE the verdict so its result can
@@ -334,7 +415,10 @@ export function evaluateToolGuard(
   const policy = resolveToolPolicyForGuard(worktreeRoot, runId, activePhaseArtifact)
   const context: ToolPolicyContext = { args, runDir, runId, worktreeRoot, activePhaseArtifact }
   const decision = evaluateToolPolicy(policy, name, args, context)
-  return advisory(verdictFor(mode, decision, String(args.artifact ?? '')), transition)
+  // The resolved run rides on EVERY decision, including an allow: the guard-decision log records which run
+  // a decision was about, and a record that named the ACTIVE run while the rule read another one is exactly
+  // the two-answers-in-one-payload defect this pairs with (see `[run: <id>]` in `lockOrderRule`).
+  return { ...advisory(verdictFor(mode, decision, String(args.artifact ?? '')), transition), runId }
 }
 
 /**