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

package/src/policy-globs.ts

@@ -40,10 +40,10 @@
  * just wrote and believes is in force.
  */
 import { existsSync, readFileSync } from 'node:fs'
-import { join } from 'node:path'
-import { getLockStatus, getPrerequisiteBlockers } from './lock.ts'
+import { basename, dirname, join, resolve } from 'node:path'
+import { getLockStatus, getPrerequisiteBlockers, type PrerequisiteBlocker } from './lock.ts'
 import { getMdFieldValue } from './status.ts'
-import { policyTargetPath, resolveFrom } from './phase-rules.ts'
+import { phaseNumberForArtifact, policyTargetPath, resolveFrom } from './phase-rules.ts'
 
 /** The three verdicts a rule may carry. */
 export type Verdict = 'allow' | 'deny' | 'ask'
@@ -58,6 +58,18 @@ export interface Decision {
   kind: Verdict
   reason?: string
   rule?: string
+  /**
+   * THE FACTS THE PREDICATE DECIDED FROM, when it read any. The lock-order rule resolves the
+   * artifact's prerequisites from disk, and the layer that turns this decision into a refusal
+   * needs those same facts to build the caller's recovery options. Carrying them is what makes
+   * "the guard already has them" true: a second `getPrerequisiteBlockers` call from the denial
+   * would re-read a run tree that is on disk and unlocked, and could answer differently.
+   *
+   * Absent for every rule that decides on its pattern alone, and absent when the predicate read
+   * nothing — so its presence means "this refusal was decided from these blockers", not "the
+   * policy mentions blockers".
+   */
+  blockers?: readonly PrerequisiteBlocker[]
 }
 
 /**
@@ -70,6 +82,18 @@ export interface ToolPolicyContext {
   runDir?: string
   runId?: string
   worktreeRoot?: string
+  /**
+   * The ACTIVE phase artifact of the run — the LOWEST-numbered phase artifact that is not
+   * LOCKED, falling back to the highest when every one of them is locked.
+   *
+   * ⚠ THIS IS NOT A SECOND SELECTOR. It is the answer `currentPhaseArtifact` in
+   * `enforcement.ts` produced for this call, carried here so a rule in THIS module can
+   * compare against it. `policy-globs.ts` cannot import that function (enforcement.ts
+   * imports this module, and the repo has already paid once for a value-level import
+   * cycle), so the value is passed in rather than recomputed. A caller that omits it
+   * gets NO phase-order verdict — the rule abstains rather than guessing a phase.
+   */
+  activePhaseArtifact?: string
 }
 
 /**
@@ -87,6 +111,12 @@ export interface ToolPolicyContext {
 export interface ToolPolicyPredicateMatch {
   verdict: Verdict
   detail?: string
+  /**
+   * The blockers the predicate READ, when it read any (see `Decision.blockers`). Optional and
+   * additive: a predicate that decided from something else returns none, and the engine's
+   * verdict is unchanged either way.
+   */
+  blockers?: readonly PrerequisiteBlocker[]
 }
 
 export type ToolPolicyPredicate = (
@@ -326,7 +356,7 @@ export function evaluateToolPolicy(
       // Abstention: this rule does not govern this call, so it does not
       // participate and the next rule in precedence order decides.
       if (match === null) continue
-      return decide(rule, match.verdict, match.detail ? rule.reason + ' ' + match.detail : rule.reason)
+      return decide(rule, match.verdict, match.detail ? rule.reason + ' ' + match.detail : rule.reason, match.blockers)
     }
     return decide(rule, rule.verdict, rule.reason)
   }
@@ -335,10 +365,17 @@ export function evaluateToolPolicy(
   return { kind: 'ask', reason: 'no policy rule matches ' + id + ' - ask is the no-match default' }
 }
 
-/** One place where a rule's verdict becomes a decision, so `label` cannot drift. */
-function decide(rule: ToolPolicyRule, kind: Verdict, reason: string): Decision {
+/**
+ * One place where a rule's verdict becomes a decision, so `label` cannot drift.
+ *
+ * `blockers` rides along untouched when the predicate supplied any (see `Decision.blockers`);
+ * an EMPTY list is dropped rather than carried, so `blockers` on a decision always means "there
+ * were blockers", never "the rule looked and found none".
+ */
+function decide(rule: ToolPolicyRule, kind: Verdict, reason: string, blockers?: readonly PrerequisiteBlocker[]): Decision {
   const decision: Decision = { kind, reason }
   if (rule.label) decision.rule = rule.label
+  if (blockers !== undefined && blockers.length > 0) decision.blockers = blockers
   return decision
 }
 
@@ -413,7 +450,14 @@ function lockOrderRule(artifact: unknown, runDir: string | undefined): ToolPolic
   if (!name || !runDir) return null
   const blockers = getPrerequisiteBlockers(runDir, name)
   if (blockers.length === 0) return null
-  return { verdict: 'deny', detail: blockers.map((b) => b.artifact + ' (' + b.status + ')').join(', ') }
+  return {
+    verdict: 'deny',
+    detail: blockers.map((b) => b.artifact + ' (' + b.status + ')').join(', '),
+    // THE SAME READ, carried up rather than thrown away: the denial's recovery options are built
+    // from these blockers, and re-deriving them one layer higher would be a second filesystem
+    // answer to a question this rule has already answered.
+    blockers,
+  }
 }
 
 /**
@@ -452,12 +496,95 @@ function lockedWriteRule(target: string | null, worktreeRoot: string | undefined
   return { verdict: 'deny', detail: normalized + ' carries Status: LOCKED (reopen explicitly to edit)' }
 }
 
+/**
+ * The file name when `abs` is a DIRECT CHILD of `runDir`, and `null` otherwise.
+ *
+ * ⚠ THE DIRECT-CHILD TEST IS NOT TIDINESS — IT IS WHAT KEEPS THE RULE OFF THE SUPPORT
+ * FILES. `phaseNumberForArtifact` reads the leading digits of a NAME, so
+ * `<run>/evidence/01-as-is.md` or `<run>/subagents/child/03-brief.md` would look like
+ * phase 1 and phase 3 artifacts if the name were all that was examined. A phase artifact
+ * is a file the run tree holds DIRECTLY beside the others (`recursive_init` writes all
+ * twelve into `<run>/` itself), so the parent directory is part of the definition.
+ *
+ * The comparison normalizes separators and case: the same run directory reached through
+ * a Windows spelling that differs in case is the same directory, and the rule must not
+ * abstain on one spelling and fire on the other.
+ */
+function directChildName(abs: string, runDir: string): string | null {
+  const normalize = (path: string) => resolve(path).replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase()
+  if (normalize(dirname(abs)) !== normalize(runDir)) return null
+  return basename(abs)
+}
+
+/**
+ * PHASE-ORDER rule: a denial when the target is a LATER phase's artifact than the phase
+ * currently active, `null` when it is not.
+ *
+ * ⚠ THE HOLE THIS CLOSES. The monotonic rule was enforced on `recursive_lock` ONLY. An
+ * agent could therefore write `08-memory-impact.md` while the run sat at phase 0 — and a
+ * live run did exactly that: twelve artifacts, not one of them locked, written out of
+ * order, with a single line in `operations/operations.jsonl`. Ordering that only binds
+ * the lock tool is not ordering; the model's ordinary `write` is the path that mattered.
+ *
+ * The owner's rule, verbatim: *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*. The ACTIVE phase is the one the selector names (`ctx.activePhaseArtifact`), so:
+ *
+ *   - the target is the ACTIVE artifact, or shares its phase number (`00-requirements.md`
+ *     and `00-worktree.md` are both phase 0; `01-as-is.md` and `01.5-root-cause.md` are
+ *     both phase 1) -> ABSTAIN, the write is allowed;
+ *   - the target is an EARLIER phase -> ABSTAIN. Such an artifact is LOCKED by
+ *     construction (the active phase is the lowest UNLOCKED one), so the locked-artifact
+ *     rule above decides it, and its rule label is preserved;
+ *   - the target is a LATER phase -> DENY: working ahead.
+ *
+ * ⚠ THE ALLOW HALF IS LOAD-BEARING. An enforcement rule in this exact area was once the
+ * bug: strict enforcement denied the run's OWN artifacts in every phase and made the
+ * workflow unusable (see `resolveFrom` and `currentPhaseArtifact`). "The active artifact
+ * stays writable at every phase" is therefore asserted by walking every phase, not by
+ * one case — `tests/strict-run-tree.spec.ts` (d).
+ *
+ * WHAT IT ABSTAINS ON, deliberately:
+ *   - no `activePhaseArtifact` (a caller with no run context, or a run with no phase
+ *     artifacts yet) -> abstain, never guess a phase;
+ *   - a target outside the active run's own directory -> abstain. The rule is about THIS
+ *     run's sequence; another run's tree is a different question and denying it here
+ *     would be a false positive;
+ *   - a support file (anything not a direct child) -> abstain: `evidence/`, `scratch/`,
+ *     `addenda/`, `subagents/`, `operations/` and a plain `<run>/notes.md` are not phases.
+ *
+ * The predicate adds only the per-call particular — which artifact, which phase, which is
+ * active; the rule keeps the static, auditable sentence.
+ */
+function phaseOrderRule(target: string | null, ctx: ToolPolicyContext): ToolPolicyPredicateMatch | null {
+  const active = ctx.activePhaseArtifact
+  if (!target || !ctx.runDir || !ctx.worktreeRoot) return null
+  if (typeof active !== 'string' || active === '') return null
+  const activePhaseText = phaseNumberForArtifact(active)
+  if (!activePhaseText) return null
+  const normalized = target.replace(/\\/g, '/')
+  if (!normalized.endsWith('.md')) return null
+  const abs = resolveFrom(ctx.worktreeRoot, normalized)
+  if (!abs) return null
+  const name = directChildName(abs, ctx.runDir)
+  if (name === null) return null
+  const phaseText = phaseNumberForArtifact(name)
+  if (!phaseText) return null
+  if (Number(phaseText) <= Number(activePhaseText)) return null
+  return {
+    verdict: 'deny',
+    detail: name + ' is phase ' + phaseText + ' but the ACTIVE phase is ' + active
+      + ' (phase ' + activePhaseText + ') - the active phase must be locked before writing a later phase',
+  }
+}
+
 /**
  * The BUILT-IN default rule list — the pre-T16 guard behaviour expressed as
  * data:
  *
  *   `recursive_lock*`  -> the monotonic lock-order denial;
  *   the write-tool ids -> the locked-artifact write denial;
+ *   the write-tool ids -> the phase-order (write-ahead) denial;
  *   `*`                -> allow, so an ordinary tool is not turned into an `ask`.
  *
  * Every `deny` precedes the `allow`, which is what makes "deny wins over allow" a
@@ -488,6 +615,20 @@ export function builtInToolPolicyRules(): ToolPolicyRule[] {
       predicate: (id, args, ctx) => (WRITE_TOOL_NAMES.has(id) ? lockedWriteRule(policyTargetPath(args), ctx.worktreeRoot) : null),
     })
   }
+  // The SAME write-tool ids get a SECOND conditional deny, the phase-order rule. Two rules
+  // share one pattern on purpose: the engine's predicates ABSTAIN (`null`) when their
+  // condition does not apply, so a clean write falls through both to the catch-all allow,
+  // and a target that is BOTH locked and a later phase is reported by the locked rule
+  // first (file order within a specificity tier), which is the pre-existing wording.
+  for (const name of WRITE_TOOL_NAMES) {
+    rules.push({
+      pattern: name,
+      verdict: 'deny',
+      reason: 'phase order: only one phase may be active at a time - the active phase must be locked before a later phase artifact is written',
+      label: 'phase-order',
+      predicate: (id, args, ctx) => (WRITE_TOOL_NAMES.has(id) ? phaseOrderRule(policyTargetPath(args), ctx) : null),
+    })
+  }
   rules.push({
     pattern: '*',
     verdict: 'allow',
@@ -523,6 +664,18 @@ export function attachPolicyPredicate(rule: ToolPolicyRule): ToolPolicyRule {
   if (rule.pattern === 'recursive_lock*') {
     return { ...rule, predicate: (id, args, ctx) => (LOCK_TOOL_NAMES.has(id) ? lockOrderRule(args.artifact, ctx.runDir) : null) }
   }
+  // ⚠ THE LABEL IS CONSULTED BEFORE THE PATTERN, because the phase-order rule and the
+  // locked-artifact rule share EVERY write-tool pattern (see `builtInToolPolicyRules`).
+  // Selecting by pattern alone would give BOTH rules the locked-artifact condition — the
+  // second would then deny a locked target with the wrong reason and the phase-order
+  // condition would never be attached at all, so the hole would stay open in every repo
+  // that ships a policy file. The `label` is already the rule's machine-readable identity
+  // (`firstPolicyDefect` admits it, `decide` surfaces it as the decision's `rule`), so the
+  // label is what names the condition. A rule with NO label keeps the pattern's condition,
+  // exactly as before.
+  if (rule.label === 'phase-order') {
+    return { ...rule, predicate: (id, args, ctx) => (WRITE_TOOL_NAMES.has(id) ? phaseOrderRule(policyTargetPath(args), ctx) : null) }
+  }
   if (WRITE_TOOL_NAMES.has(rule.pattern)) {
     return { ...rule, predicate: (id, args, ctx) => (WRITE_TOOL_NAMES.has(id) ? lockedWriteRule(policyTargetPath(args), ctx.worktreeRoot) : null) }
   }

package/src/policy.ts

@@ -111,6 +111,7 @@ export function renderStableContract(config: EnforcementConfig = DEFAULT_ENFORCE
       + ', tamper detection ' + config.tamper + '.',
     '- A transition that fails its gates is BLOCKED (strict) or warns (advisory); no rejected transition proceeds silently.',
     '- Writes to a Status: LOCKED phase doc are denied/asked; reopen explicitly to edit.',
+    '- Phase order binds WRITES as well as locks: only the ACTIVE phase (the lowest-numbered artifact not yet LOCKED) may be written; a write to a LATER phase artifact is denied/asked. Run support files (evidence/, scratch/, addenda/, subagents/, operations/) are not phases.',
     '- Phase 3 lock requires TDD evidence (strict) or rationale (pragmatic); Phase 5 requires QA evidence.',
     '- The control-plane root is resolved STRICTLY from this session workspace (never scanned from another).',
   ].join('\n')

package/src/recursive_ask.tool.ts

@@ -170,6 +170,54 @@ export function buildAskQuestion(gateId: AskGateId): AskQuestion {
   })
 }
 
+/**
+ * FU-7 — THE GATE-BLOCK REFUSAL PAYLOAD, BUILT IN ONE PLACE.
+ *
+ * A blocked lock is refused by TWO layers. The TOOL refuses when `lockArtifact` throws
+ * `Prerequisite blockers:`; the GUARD refuses pre-dispatch when the lock-order rule fires
+ * (`monotonic lock-order`), and under the strict default that is the layer the caller meets
+ * first. Both must hand the caller the SAME choice, so both build it HERE.
+ *
+ * ⚠ WHY NOT TWO LITERALS. `fix | reopen | abandon` is the human's way out of a blocked lock,
+ * and it existed in exactly one call site (`recursive_lock.tool.ts`). The guard's refusal moved
+ * to the default path, and a second hand-written copy of the options there would be a second
+ * answer to "what can a person do about this?": the day the options change, one of the two
+ * refusals keeps offering the old set and nothing fails. One builder, called from both.
+ *
+ * `blocked` is the refusal's OWN sentence — the guard's rule text or the tool's exception
+ * message — carried as data so the payload says what it is about without a reader having to
+ * match it against the text beside it.
+ */
+export interface GateBlockAsk extends AskQuestion {
+  gate: 'gate-block'
+  artifact: string
+  blocked: string
+}
+
+/** The payload, as the refusal carries it. Validated through `buildAskQuestion`. */
+export function buildGateBlockAsk(artifact: string, blocked: string): GateBlockAsk {
+  return { gate: 'gate-block', ...buildAskQuestion('gate-block'), artifact, blocked }
+}
+
+/**
+ * FU-7 — THE OPTIONS AS TEXT, DERIVED FROM THE PAYLOAD rather than restated.
+ *
+ * WHY A RENDERER IS NEEDED AT ALL: the harness renders a `tools/pre-execute` denial as
+ * `Error: <reason>` and drops every other field of the decision (measured in
+ * `packages/core/tools`: `content: [{ type: 'text', text: 'Error: ' + denialReason }]`), so an
+ * ask that rode along as a SIBLING field would reach the model as nothing at all — which is
+ * exactly how a strict-by-default guard made the recovery path unreachable. The refusal
+ * therefore renders the payload into the text it hands back, and it renders THIS object, so
+ * the visible sentence and the structured payload cannot disagree.
+ */
+export function renderGateBlockAsk(ask: GateBlockAsk): string {
+  const options = ask.options
+    .map((option) => option.label + (option.description === undefined ? '' : ' (' + option.description + ')'))
+    .join(' ')
+  const target = ask.artifact === '' ? 'recursive_ask gate=gate-block' : 'recursive_ask gate=gate-block artifact=' + ask.artifact
+  return ask.header + ': ' + ask.question + ' Options: ' + options + ' Answer with ' + target + '.'
+}
+
 /**
  * PHASE 0 — build the question for ANY accepted gate, including the run-start gate.
  *

package/src/recursive_lock.tool.ts

@@ -1,6 +1,6 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { codeRuntimeRefusal, toolError } from './errors.ts'
-import { buildAskQuestion } from './recursive_ask.tool.ts'
+import { buildGateBlockAsk } from './recursive_ask.tool.ts'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import type { RecursiveRuntime } from './runtime.ts'
 
@@ -37,10 +37,16 @@ export function createRecursiveLockTool(recursive: RecursiveRuntime) {
         // ⚠ IT IS ATTACHED TO THE ORDERING REFUSAL SPECIFICALLY (`Prerequisite blockers:`), because that
         // is the one a human resolves. A missing run id or an already-locked artifact is a caller mistake
         // with a mechanical fix, and offering "reopen / abandon the run" for those would be noise.
+        //
+        // ⚠ AND THE PAYLOAD COMES FROM `buildGateBlockAsk`, NOT FROM A LITERAL HERE. The GUARD refuses
+        // the same ordering violation pre-dispatch (it resolves the same blockers from the same run
+        // tree) and attaches this same payload; one builder is what keeps the two refusals offering the
+        // same options. This branch still fires whenever the guard ABSTAINS — most visibly when the call
+        // names a run other than the active one, because the guard resolves the run from the filesystem.
         if (message.startsWith('Prerequisite blockers:')) {
           return {
             error: refusal,
-            ask: { gate: 'gate-block', ...buildAskQuestion('gate-block'), artifact: args.artifact ?? '', blocked: message },
+            ask: buildGateBlockAsk(args.artifact ?? '', message),
           } as unknown as JsonValue
         }
         return { error: refusal } as const

package/src/runtime.ts

@@ -1881,7 +1881,7 @@ export class RecursiveRuntime extends Service {
     return coupleGateBlockToGoal(goalService as never, agent, ref, reason)
   }
 
-  /** Phase C R7: resolve the enforcement config (strict|advisory, default advisory). */
+  /** Phase C R7: resolve the enforcement config (strict|advisory, default strict). */
   get enforcementConfig(): EnforcementConfig {
     return this._enforcementConfig ?? DEFAULT_ENFORCEMENT
   }