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

package/README.md

@@ -289,10 +289,9 @@ Two conventions matter more than they look:
 repoRoot)` resolves the workspace the *session* is in. A plugin that used `process.cwd()` would silently lint the
 wrong repository when the host checkout and the workspace differ.
 
-**The memory plane is read at `<controlPlaneRoot>/memory/<kind>/`.** This was measured, not assumed: a probe
-showed `<dir>/memory/domains` is selected, `<dir>/.recursive/memory/...` is not, and using `.recursive` as the
-root is selected again. A behaviour test that seeds the wrong path fails *exactly like* a broken implementation,
-which is why the distinction is written down here.
+**The memory plane is read from the plane the scaffold creates, not from beside it.** `loadMemoryIndex` resolves each kind under `<controlPlaneRoot>/.recursive/memory/<kind>/` — the directory `bootstrap.ts` scaffolds, `ts-lint.ts` lints, and the review bundle already read — and falls back to `<controlPlaneRoot>/memory/<kind>/` only when that kind has no readable shard there. That is the same **prefer-then-fall-back, never merge** rule `readFeedback` follows for its own moved sidecar: the earlier location is consulted only when the current one yields nothing, because two snapshots of one shard added together would count a shard twice.
+
+Before that fallback existed the loader joined `memory/` straight onto the root it was handed, so it read `<dir>/memory/domains` — **a directory no real workspace has** — while the plane sat at `<dir>/.recursive/memory/domains`. Measured live: a workspace with the plane scaffolded, `memory/training/` included, and no `<dir>/memory/` at all, where `selectMemory` reported *"the memory plane is empty"* on every phase of every run. Passing `.recursive` itself as the root still resolves, through the second entry.
 
 ---
 
@@ -562,11 +561,12 @@ inputs are visible.
 
 ```mermaid
 flowchart LR
-    subgraph sources["memory/&lt;kind&gt;/*.md"]
+    subgraph sources[".recursive/memory/&lt;kind&gt;/*.md"]
         D1["domains/"]
         D2["patterns/"]
-        D3["incidents/"]
-        D4["episodes/"]
+        D3["episodes/"]
+        D4["training/"]
+        D5["skills/"]
     end
 
     Q["query:<br/>the run's own<br/>00-requirements.md<br/>(first 4000 chars)"] --> SEL
@@ -578,8 +578,9 @@ flowchart LR
     D2 --> IDX
     D3 --> IDX
     D4 --> IDX
+    D5 --> IDX
 
-    SEL --> OUT["top N shards →<br/>the review bundle"]
+    SEL --> OUT["top N shards →<br/>the phase payload<br/>and the review bundle"]
     SEL --> REC["recordInjection()<br/>memory-injections.json"]
     REC --> SET["settleInjections() at closeout<br/>over the LOCKED phases only"]
     SET --> FB
@@ -588,6 +589,12 @@ flowchart LR
     class Q,F,P,FB input
 ```
 
+**`MEMORY_KINDS` is the list of kinds that are auto-loaded, and it is exactly those five.** `incidents/` and
+`archive/` are stored and documented by the router but are *not* auto-loaded — `archive/` is historical by the
+router's own definition, and adding `incidents/` is a ranking decision rather than a typo fix. `training/` **is**
+in the list because it is the kind the phase-8 trigger writes: with it absent, the shards training produced were
+written and registered in `MEMORY.md` while the loader that was supposed to score them could not see the kind.
+
 **Scoring is additive and inspectable.** A shard scores for matching the query, for overlapping the changed
 paths (`MEMORY_PATH_MATCH_WEIGHT = 3`), for applying to the current phase (`MEMORY_PHASE_MATCH_WEIGHT = 2`), and
 for its feedback history (`feedbackBonus`, clamped to ±1). `explainMemorySelection` returns the **components** per
@@ -689,6 +696,12 @@ Which closes the loop the [memory plane](#9-how-it-works-the-memory-plane) opene
 closeout, and `feedbackBonus` nudges the next selection. The plugin's prompts and its context are meant to
 improve from its own recorded outcomes rather than from someone's recollection of them.
 
+**And the loop is only closed when the reader can see every kind the writer produces.** The trigger writes one
+shard per subsystem into `memory/domains/` *and* one per task type into `memory/training/<task-type>.md`, and the
+second of those is the reason `training` is in `MEMORY_KINDS` (§9): a writer whose output the reader cannot reach
+is the loop being described rather than closed. `tests/training-trigger.spec.ts` asserts the round trip end to
+end — trigger writes, loader finds the shard it wrote — because either half can look correct alone.
+
 **Design and status:** [TRAINING.md](TRAINING.md) is the design — including the phases P1–P5, each with a live
 acceptance, and the measured comparison with the reference implementation it deliberately does **not** copy.
 Its non-goals are as load-bearing as its goals: this is not a fine-tuning pipeline, and it does not ship a model

package/lib/config.d.ts

@@ -48,6 +48,13 @@ export interface RecursiveModeConfig {
 export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     shellOnly: z<boolean, boolean, "defined">;
     repoRoot: z<string, string, "plain">;
+    /**
+     * ⚠ THE THREE MODE DEFAULTS READ `DEFAULT_ENFORCEMENT_MODE` FROM `enforcement.ts`, and
+     * that is deliberate: the schema default and the runtime default are the SAME value, and
+     * two literals here would be two defaults. A caller that omits the section gets
+     * `DEFAULT_ENFORCEMENT` from the runtime; a caller that supplies a partial section gets
+     * the resolver's fill. Both must be the enforcing posture — see the const for why.
+     */
     enforcement: z<Schemastery.ObjectS<NoInfer<{
         preStep: z<"strict" | "advisory", "strict" | "advisory", "defined">;
         toolGuards: z<"strict" | "advisory", "strict" | "advisory", "defined">;
@@ -125,6 +132,13 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
 }>>, Schemastery.ObjectT<NoInfer<{
     shellOnly: z<boolean, boolean, "defined">;
     repoRoot: z<string, string, "plain">;
+    /**
+     * ⚠ THE THREE MODE DEFAULTS READ `DEFAULT_ENFORCEMENT_MODE` FROM `enforcement.ts`, and
+     * that is deliberate: the schema default and the runtime default are the SAME value, and
+     * two literals here would be two defaults. A caller that omits the section gets
+     * `DEFAULT_ENFORCEMENT` from the runtime; a caller that supplies a partial section gets
+     * the resolver's fill. Both must be the enforcing posture — see the const for why.
+     */
     enforcement: z<Schemastery.ObjectS<NoInfer<{
         preStep: z<"strict" | "advisory", "strict" | "advisory", "defined">;
         toolGuards: z<"strict" | "advisory", "strict" | "advisory", "defined">;

package/lib/enforcement.d.ts

@@ -1,4 +1,5 @@
 import { builtInToolPolicyDefault, type ToolPolicy } from './policy-globs.ts';
+import { type GateBlockAsk } from './recursive_ask.tool.ts';
 /**
  * The BUILT-IN default rule list (T16) is defined in `src/policy-globs.ts`,
  * beside the evaluator and the loader that use it as the ABSENT-file fallback,
@@ -40,6 +41,28 @@ export interface EnforcementConfig {
     /** T28: the caps. Always present, so a caller never has to guess a default. */
     budgets: BudgetConfig;
 }
+/**
+ * THE DEFAULT POSTURE: STRICT, on all three gates — and this const is the ONE literal.
+ *
+ * The owner's rule is *only one phase may be active at a time, and the phases should be
+ * sequential and the active phase must be locked before proceeding to next phase*. In
+ * `advisory` that rule is only WARNED about, and a live run showed what that costs: the
+ * run ignored the lock chain for over an hour, wrote phase 8 before phase 1.5 and locked
+ * nothing (twelve DRAFT artifacts, one operations entry). Strict was previously unsafe as
+ * a default because it also refused the run's OWN artifacts — a false positive. That was
+ * fixed, and `tests/strict-run-tree.spec.ts` now walks all twelve phases asserting the
+ * active artifact stays writable while a later one is refused. Strict therefore refuses
+ * exactly the ordering violations it is meant to refuse, so the default is the enforcing
+ * posture rather than a warning nobody has to act on.
+ *
+ * ⚠ WHY IT IS A NAMED CONST AND NOT THREE LITERALS. A default restated per site is this
+ * project's recurring failure: the same value exists in the Config schema, in
+ * `DEFAULT_ENFORCEMENT`, in an omitted config section, and in the parameter defaults of
+ * the helpers below, and moving only some of them leaves a caller that "still gets
+ * advisory". Every one of those sites now reads THIS const, so a revert is a one-line
+ * change and nothing can drift from it.
+ */
+export declare const DEFAULT_ENFORCEMENT_MODE: EnforcementMode;
 /**
  * Validate the enforcement config shape (unknown keys fail at plugin load).
  *
@@ -49,6 +72,12 @@ export interface EnforcementConfig {
  * A config error is loud at load, not mysterious later.
  */
 export declare function resolveEnforcementConfig(config: unknown): EnforcementConfig;
+/**
+ * The runtime default: what a caller gets when it supplies no `enforcement` section at all
+ * (a profile mounting this plugin with no config, e.g. `preset/recursive.patch.yml`). It is
+ * `DEFAULT_ENFORCEMENT_MODE` per gate, so this object and the resolver cannot disagree —
+ * see that const for WHY the default is strict.
+ */
 export declare const DEFAULT_ENFORCEMENT: EnforcementConfig;
 /**
  * T15: the rule that produced a guard decision (a machine-readable reason for
@@ -77,22 +106,39 @@ export interface GuardTransition {
  * optional — `coerceAskToDecision` is asserted with `toEqual({ kind: ... })`
  * (an EXACT match) in tests/enforcement.spec.ts, so the coercion path may never
  * grow extra keys. `evaluateToolGuard` itself always sets `rule`.
+ *
+ * ⚠ FU-7: `ask` IS OPTIONAL AND ADDITIVE TOO, for the same reason and one more. A refusal that a
+ * PERSON has to resolve carries the gate-block decision alongside its sentence (see `verdictFor`),
+ * 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;
+    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;
@@ -122,12 +168,84 @@ export declare function resolveToolPolicyForGuard(worktreeRoot: string, runId: s
  * needs, because a cached phase would apply yesterday's baseline to today's lock.
  */
 export declare function currentPhaseArtifact(worktreeRoot: string, runId: string): string;
+/**
+ * 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 declare function resolveGuardRunId(name: string, args: Record<string, unknown>, worktreeRoot: string, activeRunId: string): string;
+/**
+ * `mode` is the gate's configured posture. Its parameter default FOLLOWS the config
+ * default by REFERENCE (`DEFAULT_ENFORCEMENT.toolGuards`) rather than repeating the
+ * literal: a bare call is "the caller had no mode to hand", and the answer to that must
+ * be the same posture the config would have produced. Two literals are two defaults, and
+ * a helper left on the old `advisory` literal while the config moved to `strict` is
+ * exactly the twin-default hole this change closes — a caller that forgot the argument
+ * would silently get the permissive branch, which no config could then undo. Every
+ * production call site passes the mode explicitly (`index.ts` `runToolGuard`,
+ * `runtime.ts` `guardTool`, the preview tool); this default serves bare callers, and a
+ * bare caller must not be the one place enforcement quietly turns itself off.
+ */
 export declare function evaluateToolGuard(exec: ToolExecLike, worktreeRoot: string, activeRunId: string, mode?: EnforcementMode): ToolGuardDecision;
 /**
  * T6 (approval ask→policy bridge): an `ask` decision must never be a silent
  * allow. Under `strict` it coerces to `deny`; under `advisory` it stays `allow`
  * but flags a `warn` so the caller never lets it through unlogged. Non-ask
  * decisions pass through unchanged.
+ *
+ * ⚠ THE `mode` DEFAULT IS DELIBERATE, and it is NOT a neutral fallback — there is no
+ * neutral branch here. The domain is two postures, one of which ALLOWS the call, so
+ * "unspecified" has to be resolved rather than left open, and this codebase's rule for an
+ * undecidable path is to fail CLOSED (`index.ts`: *"we could not decide" is not
+ * permission*). It therefore FOLLOWS the config default by REFERENCE
+ * (`DEFAULT_ENFORCEMENT.toolGuards`), for the same reason as `evaluateToolGuard`'s: an
+ * `advisory` literal here would be a second, hidden copy of the old default inside the
+ * very module this change moves, and a future caller that omitted the argument would
+ * re-open the permissive path with no config able to close it. The production call site
+ * (`index.ts` `runToolGuard`) always passes the configured mode, so this changes no live
+ * behaviour — it removes the last place where "we were not told" meant "allow".
  */
 export declare function coerceAskToDecision(decision: ToolGuardDecision, mode?: EnforcementMode): ToolGuardDecision;
 /**

package/lib/guard-log.d.ts

@@ -1,8 +1,14 @@
 import type { GuardRule } from './enforcement.ts';
+import type { GateBlockAsk } from './recursive_ask.tool.ts';
 /**
  * One logged guard decision (the JSONL record shape the board/tests read).
  * `rule` is always set (the guard's own machine-readable reason for the
  * verdict); `transition` is present whenever the transition gate was consulted.
+ *
+ * FU-7: a REFUSAL that a person has to resolve also carries `ask` — the gate-block decision, in the
+ * same shape `recursive_lock` attaches to its own refusal. It is recorded because the log is where
+ * "why was this lock refused?" is answered, and the options are the other half of that answer; a
+ * caller (or a board) reading the trace can act on the refusal without parsing the sentence.
  */
 export interface GuardDecisionRecord {
     at: string;
@@ -15,6 +21,7 @@ export interface GuardDecisionRecord {
         passed: boolean;
         failures: string[];
     };
+    ask?: GateBlockAsk;
 }
 /** One logged observed-write tamper (a LOCKED artifact whose hash no longer matches). */
 export interface ObservedTamperRecord {