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

package/src/enforcement.ts

@@ -3,11 +3,12 @@
  * (Phase C R3/R4/R7/R8, PROPOSAL 8.4/8.6/13.5).
  *
  * Layer 2 (tool guards) and Layer 8 (tamper) are the remaining enforcement
- * layers. Configurable strict|advisory per gate (default advisory).
+ * layers. Configurable strict|advisory per gate (default strict).
  */
 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,
@@ -15,6 +16,7 @@ import {
   type ToolPolicy, type ToolPolicyContext, type Decision as PolicyDecision,
 } from './policy-globs.ts'
 import { withPhaseBaseline, phaseNumberForArtifact, resolveFrom } from './phase-rules.ts'
+import { buildGateBlockAsk, type GateBlockAsk } from './recursive_ask.tool.ts'
 
 /**
  * The BUILT-IN default rule list (T16) is defined in `src/policy-globs.ts`,
@@ -75,6 +77,29 @@ const BUDGET_KEYS: ReadonlyArray<keyof BudgetConfig> = [
   'maxAuditRounds', 'maxRepairAttempts', 'maxDelegationDepth', 'maxChildrenPerPhase', 'maxResultBytes',
 ]
 
+/**
+ * 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 const DEFAULT_ENFORCEMENT_MODE: EnforcementMode = 'strict'
+
 /**
  * Validate the enforcement config shape (unknown keys fail at plugin load).
  *
@@ -89,7 +114,17 @@ export function resolveEnforcementConfig(config: unknown): EnforcementConfig {
   if (unknown.length > 0) {
     throw new Error('EnforcementConfig has unknown key(s) ' + unknown.join(', ') + ' - config is { preStep, toolGuards, tamper, budgets }')
   }
-  const mode = (value: unknown): EnforcementMode => (value === 'strict' ? 'strict' : 'advisory')
+  // ⚠ AN ABSENT MODE RESOLVES TO THE DEFAULT MODE, not to the permissive branch. This is
+  // the twin-default trap in its most consequential form: a caller that supplies a PARTIAL
+  // section — `enforcement: { toolGuards: 'advisory' }` from a settings patch, or just the
+  // budgets — leaves the other gates unstated, and filling those with `advisory` would
+  // hand back a config that is looser than the plugin's own default with nothing saying so.
+  // An UNRECOGNIZED value resolves the same way and thus fails CLOSED. The Config schema in
+  // src/config.ts still rejects a typo loudly at the settings boundary; this resolver is
+  // the lenient one, and a lenient resolver must bend towards the safe posture: a typo that
+  // blocks is a visible stop, a typo that permits is the hour-long out-of-order run again.
+  const mode = (value: unknown): EnforcementMode =>
+    value === 'strict' ? 'strict' : value === 'advisory' ? 'advisory' : DEFAULT_ENFORCEMENT_MODE
 
   const rawBudgets = (raw.budgets ?? {}) as Record<string, unknown>
   if (typeof raw.budgets !== 'undefined' && (raw.budgets === null || typeof raw.budgets !== 'object')) {
@@ -117,10 +152,16 @@ export 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 const DEFAULT_ENFORCEMENT: EnforcementConfig = {
-  preStep: 'advisory',
-  toolGuards: 'advisory',
-  tamper: 'advisory',
+  preStep: DEFAULT_ENFORCEMENT_MODE,
+  toolGuards: DEFAULT_ENFORCEMENT_MODE,
+  tamper: DEFAULT_ENFORCEMENT_MODE,
   budgets: DEFAULT_BUDGETS,
 }
 
@@ -153,11 +194,24 @@ 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 }
-  | { kind: 'deny'; reason: string; rule?: GuardRule; transition?: GuardTransition }
-  | { 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
@@ -249,15 +303,100 @@ 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
+ * 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 function evaluateToolGuard(
   exec: ToolExecLike,
   worktreeRoot: string,
   activeRunId: string,
-  mode: EnforcementMode = 'advisory',
+  mode: EnforcementMode = DEFAULT_ENFORCEMENT.toolGuards,
 ): 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
@@ -276,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), 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 }
 }
 
 /**
@@ -284,12 +426,35 @@ export function evaluateToolGuard(
  * `advisory` asks (the pre-T16 wording, unchanged), `allow` stays an allow. The
  * decision's `rule` is the label of the rule that decided it, so a policy
  * verdict is traceable to an auditable line in the policy file.
+ *
+ * ⚠ FU-7 — THE ORDERING REFUSAL CARRIES THE HUMAN'S CHOICE. `fix | reopen | abandon` is how a
+ * person unblocks a lock, and before this the ask was attached ONLY by `recursive_lock`'s own
+ * catch — the branch that runs when the guard ABSTAINS. Under the strict default the guard
+ * refuses a lock ahead of its prerequisites BEFORE dispatch, so that branch never ran on the
+ * default path and the caller got a bare sentence: the recovery options existed in the code and
+ * were unreachable in the product, which is worse than the advisory posture they replaced (an
+ * advisory `ask` at least surfaced the reason).
+ *
+ * THE TRIGGER IS THE BLOCKERS, NOT THE LABEL. `PolicyDecision.blockers` is present exactly when a
+ * predicate read prerequisite blockers from disk and they were non-empty, so gating on it means
+ * "this refusal was decided from an ordering violation" — including a policy FILE whose
+ * `recursive_lock*` deny carries no label (the file-authored rule is given the same condition by
+ * `attachPolicyPredicate`, and its `rule` would otherwise read `none`). Nothing is recomputed
+ * here: the blockers arrive from the rule that already resolved them.
+ *
+ * IT IS ATTACHED TO THE REFUSAL ONLY. Under `advisory` the same verdict becomes an `ask` that the
+ * live path coerces to an allow-with-warning, and the tool then refuses with its OWN payload when
+ * `lockArtifact` throws — so an ask attached here would be a claim about a refusal that this layer
+ * did not make. One refusal, one ask.
  */
-function verdictFor(mode: EnforcementMode, decision: PolicyDecision): ToolGuardDecision {
+function verdictFor(mode: EnforcementMode, decision: PolicyDecision, artifact: string): ToolGuardDecision {
   const rule = (decision.rule ?? 'none') as GuardRule
   if (decision.kind === 'allow') return { kind: 'allow', rule }
   const reason = decision.reason ?? 'tool policy denied this call'
-  return mode === 'strict' ? { kind: 'deny', reason, rule } : { kind: 'ask', reason, rule }
+  if (mode !== 'strict') return { kind: 'ask', reason, rule }
+  const blocked = decision.blockers
+  if (blocked === undefined || blocked.length === 0) return { kind: 'deny', reason, rule }
+  return { kind: 'deny', reason, rule, ask: buildGateBlockAsk(artifact, reason) }
 }
 
 /**
@@ -337,10 +502,17 @@ function advisory(decision: ToolGuardDecision, transition: GateCheckResult | und
   if (transition.passed) return { ...decision, transition }
   // The verdict stays `allow`; the gate only names itself as the dissenting
   // voice, so an advisory pass is never silent.
+  //
+  // ⚠ FU-7 (the log fix) — "REPORT-ONLY", NOT "advisory". This sentence travels into the guard's
+  // log line and into the decision a caller reads, and `advisory` there named the GATE's posture
+  // — not the configured mode — while the line around it said `tool guard (advisory)`. Under the
+  // strict default a reader was told enforcement was off while every gate was strict. What is
+  // actually true of this gate in BOTH modes is that it reports and never changes the verdict, so
+  // that is what it now says. The warn-on-allow semantics are untouched.
   return {
     ...decision,
     rule: 'transition',
-    warn: 'transition gate (advisory) failed: ' + transition.failures.join('; '),
+    warn: 'transition gate (report-only) failed: ' + transition.failures.join('; '),
     transition,
   }
 }
@@ -350,8 +522,23 @@ function advisory(decision: ToolGuardDecision, transition: GateCheckResult | und
  * 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 function coerceAskToDecision(decision: ToolGuardDecision, mode: EnforcementMode = 'advisory'): ToolGuardDecision {
+export function coerceAskToDecision(
+  decision: ToolGuardDecision,
+  mode: EnforcementMode = DEFAULT_ENFORCEMENT.toolGuards,
+): ToolGuardDecision {
   if (decision.kind !== 'ask') return decision
   if (mode === 'strict') {
     return { kind: 'deny', reason: decision.reason ?? 'ask under strict enforcement denies' }

package/src/guard-log.ts

@@ -22,11 +22,17 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 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
@@ -36,6 +42,7 @@ export interface GuardDecisionRecord {
   rule: GuardRule
   reason?: string
   transition?: { passed: boolean; failures: string[] }
+  ask?: GateBlockAsk
 }
 
 /** One logged observed-write tamper (a LOCKED artifact whose hash no longer matches). */