@try-works/dsh-recursive-mode 0.2.0 → 0.2.1

package/lib/index.d.ts

@@ -8,6 +8,7 @@ export { createRecursiveLintTool } from './recursive_lint.tool.ts';
 export { createRecursiveCloseoutTool } from './recursive_closeout.tool.ts';
 export { createRecursiveScratchTool } from './recursive_scratch.tool.ts';
 export { createRecursiveWorktreeTool } from './recursive_worktree.tool.ts';
+export { createRecursivePhaseTool } from './recursive_phase.tool.ts';
 export * from './status.ts';
 export { PHASE_SEQUENCE, OPTIONAL_PHASES, normalizeForLockHash, lockHashFromContent, phaseIndex, isCoreArtifact, getPrerequisites, getLockStatus, getPrerequisiteBlockers, receiptPath, readReceipt, writeReceipt, invalidateReceipt, getStaleDownstreamPhases, getNextLegalPhase, getAllStaleReceipts, validateChain, } from './lock.ts';
 export type { LockReceipt, LockStatus, PrerequisiteBlocker, StaleDownstream, ChainPhaseResult, LockChainResult, } from './lock.ts';

package/lib/index.js

@@ -393,17 +393,43 @@ function getArtifactRequiredSections(fileName, workflowProfile = CURRENT_WORKFLO
 	return headings;
 }
 /**
+* LIVE BUG 6 (0.2.1): dedup gate for the agent/pre-step lint-rules reminder.
+* Keyed by (root, runId, phase) so each new run or phase transition gets its own
+* single injection, while re-arming steps in the SAME phase stay silent. Scoped
+* to the apply() effect/fiber lifetime (one instance per mount), matching the
+* repairedRoots dedup used by the scaffold repair above the injection point.
+*/
+var ReminderOnceGate = class {
+	seen = /* @__PURE__ */ new Set();
+	shouldInject(root, runId, phase) {
+		const key = root + "\0" + runId + "\0" + phase;
+		if (this.seen.has(key)) return false;
+		this.seen.add(key);
+		return true;
+	}
+};
+function phaseRulesFor(fileName, workflowProfile = CURRENT_WORKFLOW_PROFILE$1) {
+	return {
+		fileName,
+		label: fileName.replace(/\.md$/, ""),
+		requiredSections: getArtifactRequiredSections(fileName, workflowProfile),
+		audited: AUDITED_PHASE_FILES$2.has(fileName),
+		tdd: fileName === "03-implementation-summary.md",
+		qa: fileName === "05-manual-qa.md"
+	};
+}
+/**
 * Compact lint-rules message for the pre-step injection (R5): this phase's
-* required sections + phase-specific gate notes, derived from the canonical
-* artifact-template sections. Kept short enough to prepend as a system-style
-* reminder without bloating the step context.
+* required sections + phase-specific gate notes, built from phaseRulesFor
+* (single source of truth with the recursive_phase tool). Output is unchanged
+* from the prior inline build so r5-parity.spec.ts stays green.
 */
 function phaseLintRulesMessage(fileName, workflowProfile = CURRENT_WORKFLOW_PROFILE$1) {
-	const sections = getArtifactRequiredSections(fileName, workflowProfile);
+	const rules = phaseRulesFor(fileName, workflowProfile);
 	return [
 		"<system-reminder>",
 		"Recursive-mode phase lint rules for THIS phase (" + fileName + "):",
-		"Required sections: " + sections.join(" | "),
+		"Required sections: " + rules.requiredSections.join(" | "),
 		"Gates: Coverage: FAIL until all checkboxes pass; Approval: FAIL until user sign-off; lock only via recursive_lock (monotonic).",
 		"Audited phases: end with Audit: PASS before setting Coverage/Approval PASS; record Audit Context and Audit Verdict.",
 		"TDD (phase 3): declare TDD Mode: strict|pragmatic; strict requires RED + GREEN evidence paths.",
@@ -4841,7 +4867,8 @@ function renderRecursivePolicy(context) {
 		"- Phase 3 lock requires TDD evidence (strict) or rationale (pragmatic); Phase 5 requires QA sign-off for human/hybrid modes.",
 		"- The control-plane root is resolved STRICTLY from this session workspace (never scan other workspaces).",
 		"- Scratch is disposable, git-ignored, and never citable as an Input.",
-		"- The workflow spec lives at /.recursive/RECURSIVE.md; bootstrap it when missing."
+		"- The workflow spec lives at /.recursive/RECURSIVE.md; bootstrap it when missing.",
+		"- Call recursive_phase when entering a new phase; the same rules are auto-injected once per phase transition."
 	];
 	if (currentFile) {
 		const sections = getArtifactRequiredSections(currentFile, CURRENT_WORKFLOW_PROFILE$1);
@@ -5383,6 +5410,26 @@ var RecursiveRuntime = class extends Service {
 		return foldRun(resolved.runDir, resolved.runId);
 	}
 	/**
+	* LIVE BUG 6 refined: structured phase rules for the CURRENT phase. Resolves
+	* the workspace root (same as status/lock), finds the latest run (or the
+	* given runId), advances via getNextLegalPhase, and returns the phase's lint
+	* rules + instructions. Returns null when no active phase exists. This is the
+	* canonical data source for the recursive_phase tool.
+	*/
+	async phaseRules(runId, agent) {
+		const root = await this.resolveRootFor(agent);
+		if (!root) return null;
+		const resolved = resolveRunDir(root, runId);
+		if (!resolved) return null;
+		const phase = getNextLegalPhase(resolved.runDir);
+		if (!phase) return null;
+		return {
+			runId: resolved.runId,
+			phase,
+			...phaseRulesFor(phase)
+		};
+	}
+	/**
 	* Scaffold a run directory with FULL per-phase templates (no-op if exists).
 	* 00-requirements.md + 00-worktree.md are byte-identical to canonical
 	* recursive-init.py (incl. git-context prefill); later phases carry every
@@ -5974,6 +6021,37 @@ function createRecursiveWorktreeTool(recursive) {
 	});
 }
 //#endregion
+//#region src/recursive_phase.tool.ts
+/**
+* recursive_phase (refined LIVE BUG 6): the canonical on-demand home of the
+* current phase's lint rules + instructions. Reads the same structured source
+* (runtime.phaseRules -> phaseRulesFor) as the once-per-phase pre-step
+* 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.
+*/
+function createRecursivePhaseTool(recursive) {
+	return defineTool({
+		name: "recursive_phase",
+		description: "Return the lint rules + instructions for the current recursive-mode phase (required sections, gates, TDD/QA notes). Call once when entering a new phase; the same rules are also auto-injected once per phase transition.",
+		parameters: { runId: {
+			type: "string",
+			description: "Optional run id (defaults to the latest run by mtime)"
+		} },
+		output: {
+			schema: { type: "json" },
+			render: (_args, value) => [{
+				type: "text",
+				text: JSON.stringify(value, null, 2)
+			}]
+		},
+		async execute(args, exec) {
+			const result = await recursive.phaseRules(args.runId, exec.agent);
+			if (!result) return { error: "no recursive phase found" };
+			return result;
+		}
+	});
+}
+//#endregion
 //#region src/bootstrap.ts
 /**
 * Idempotent scaffold installer (R3). TS port of install-recursive-mode.py's
@@ -6845,6 +6923,7 @@ function apply(ctx, config) {
 			workspaceRegistry
 		});
 		const repairedRoots = /* @__PURE__ */ new Set();
+		const reminderGate = new ReminderOnceGate();
 		const disposers = [
 			ctx.tools.register(createRecursiveStatusTool(recursive)),
 			ctx.tools.register(createRecursiveInitTool(recursive)),
@@ -6852,7 +6931,8 @@ function apply(ctx, config) {
 			ctx.tools.register(createRecursiveLintTool(recursive)),
 			ctx.tools.register(createRecursiveCloseoutTool(recursive)),
 			ctx.tools.register(createRecursiveScratchTool(recursive)),
-			ctx.tools.register(createRecursiveWorktreeTool(recursive))
+			ctx.tools.register(createRecursiveWorktreeTool(recursive)),
+			ctx.tools.register(createRecursivePhaseTool(recursive))
 		];
 		const commands = ctx.get("commands");
 		if (commands) disposers.push(registerRecursiveCommand({ commands }, recursive));
@@ -6923,6 +7003,10 @@ function apply(ctx, config) {
 				kind: "enter",
 				messages
 			};
+			if (!reminderGate.shouldInject(root, runId, phase)) return {
+				kind: "enter",
+				messages
+			};
 			const reminder = phaseLintRulesMessage(phase);
 			return {
 				kind: "enter",
@@ -6954,4 +7038,4 @@ function apply(ctx, config) {
 	});
 }
 //#endregion
-export { DEFAULT_ENFORCEMENT, LifecycleDriver, OPTIONAL_PHASES, PHASES, PHASE_SEQUENCE, RECURSIVE_API_PREFIX, RUN_ARTIFACT_SEQUENCE, RUN_STATES, RecursiveRuntime, apply, buildDelegationPrompt, buildReviewBundle, capabilityProbe, childScratchPath, contentSha256, coupleGateBlockToGoal, createChildBrief, createHandoff, createRecursiveCloseoutTool, createRecursiveInitTool, createRecursiveLintTool, createRecursiveLockTool, createRecursiveScratchTool, createRecursiveStatusTool, createRecursiveWorktreeTool, defaultReviewToolFilter, delegate, delegationDecisionBasis, delegationError, detectTamper, detectTransitionIntent, discoverRuns, escapeRegExp, evaluateDelegationResult, evaluatePreStepGate, evaluateToolGuard, foldRecursivePhase, foldRun, foldRunCard, getAllStaleReceipts, getArtifactState, getGateStatus, getLatestRunDirectory, getLockStatus, getMdFieldValue, getNextLegalPhase, getPrerequisiteBlockers, getPrerequisites, getStaleDownstreamPhases, getTodoStats, getWorkflowProfile, hasOpenTurn, inject, invalidateReceipt, isCoreArtifact, loadRouterPolicy, lockHashFromContent, makeRecursiveRoutes, mountRecursiveRoutesOnce, name, normalizeForLockHash, phaseIndex, probeCapabilities, readReceipt, receiptPath, renderRecursivePolicy, replyPath, resolveEnforcementConfig, resolveRole, resolveRunDir, reviewBundleDir, reviewOutputSchema, routerPolicyPath, snapshotWorkspace, trimMdValue, validateChain, validateReferences, validateTransition, writeActionRecord, writeReceipt };
+export { DEFAULT_ENFORCEMENT, LifecycleDriver, OPTIONAL_PHASES, PHASES, PHASE_SEQUENCE, RECURSIVE_API_PREFIX, RUN_ARTIFACT_SEQUENCE, RUN_STATES, RecursiveRuntime, apply, buildDelegationPrompt, buildReviewBundle, capabilityProbe, childScratchPath, contentSha256, coupleGateBlockToGoal, createChildBrief, createHandoff, createRecursiveCloseoutTool, createRecursiveInitTool, createRecursiveLintTool, createRecursiveLockTool, createRecursivePhaseTool, createRecursiveScratchTool, createRecursiveStatusTool, createRecursiveWorktreeTool, defaultReviewToolFilter, delegate, delegationDecisionBasis, delegationError, detectTamper, detectTransitionIntent, discoverRuns, escapeRegExp, evaluateDelegationResult, evaluatePreStepGate, evaluateToolGuard, foldRecursivePhase, foldRun, foldRunCard, getAllStaleReceipts, getArtifactState, getGateStatus, getLatestRunDirectory, getLockStatus, getMdFieldValue, getNextLegalPhase, getPrerequisiteBlockers, getPrerequisites, getStaleDownstreamPhases, getTodoStats, getWorkflowProfile, hasOpenTurn, inject, invalidateReceipt, isCoreArtifact, loadRouterPolicy, lockHashFromContent, makeRecursiveRoutes, mountRecursiveRoutesOnce, name, normalizeForLockHash, phaseIndex, probeCapabilities, readReceipt, receiptPath, renderRecursivePolicy, replyPath, resolveEnforcementConfig, resolveRole, resolveRunDir, reviewBundleDir, reviewOutputSchema, routerPolicyPath, snapshotWorkspace, trimMdValue, validateChain, validateReferences, validateTransition, writeActionRecord, writeReceipt };

package/lib/phase-rules.d.ts

@@ -25,10 +25,35 @@ export declare const DIFF_BASIS_FIELDS: string[];
  * prior-evidence file set).
  */
 export declare function getArtifactRequiredSections(fileName: string, workflowProfile?: string): string[];
+/**
+ * LIVE BUG 6 (0.2.1): dedup gate for the agent/pre-step lint-rules reminder.
+ * Keyed by (root, runId, phase) so each new run or phase transition gets its own
+ * single injection, while re-arming steps in the SAME phase stay silent. Scoped
+ * to the apply() effect/fiber lifetime (one instance per mount), matching the
+ * repairedRoots dedup used by the scaffold repair above the injection point.
+ */
+export declare class ReminderOnceGate {
+    private seen;
+    shouldInject(root: string, runId: string, phase: string): boolean;
+}
+/**
+ * Structured, single-source-of-truth rules for one phase (refined LIVE BUG 6
+ * design): consumed by BOTH the recursive_phase tool and the once-per-phase
+ * pre-step reminder. Derived from the canonical artifact-template sections.
+ */
+export interface PhaseRules {
+    fileName: string;
+    label: string;
+    requiredSections: string[];
+    audited: boolean;
+    tdd: boolean;
+    qa: boolean;
+}
+export declare function phaseRulesFor(fileName: string, workflowProfile?: string): PhaseRules;
 /**
  * Compact lint-rules message for the pre-step injection (R5): this phase's
- * required sections + phase-specific gate notes, derived from the canonical
- * artifact-template sections. Kept short enough to prepend as a system-style
- * reminder without bloating the step context.
+ * required sections + phase-specific gate notes, built from phaseRulesFor
+ * (single source of truth with the recursive_phase tool). Output is unchanged
+ * from the prior inline build so r5-parity.spec.ts stays green.
  */
 export declare function phaseLintRulesMessage(fileName: string, workflowProfile?: string): string;

package/lib/recursive_phase.tool.d.ts

@@ -0,0 +1,9 @@
+import type { RecursiveRuntime } from './runtime.ts';
+/**
+ * recursive_phase (refined LIVE BUG 6): the canonical on-demand home of the
+ * current phase's lint rules + instructions. Reads the same structured source
+ * (runtime.phaseRules -> phaseRulesFor) as the once-per-phase pre-step
+ * 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.
+ */
+export declare function createRecursivePhaseTool(recursive: RecursiveRuntime): import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/runtime.d.ts

@@ -1,6 +1,7 @@
 import { Service, type Context } from '@deepseek-ai/cordis';
 import type { RecursiveStatusResult } from './types.ts';
 import { type WorkspaceRegistryLike } from './workspace.ts';
+import { type PhaseRules } from './phase-rules.ts';
 import { type ScratchTarget } from './scratch.ts';
 import { type ReviewBundleInput } from './review.ts';
 import { type SubagentProviderLike, type RouteDecision, type CapabilityProbe } from './router.ts';
@@ -174,6 +175,23 @@ export declare class RecursiveRuntime extends Service {
             };
         };
     } | null): Promise<RecursiveStatusResult | null>;
+    /**
+     * LIVE BUG 6 refined: structured phase rules for the CURRENT phase. Resolves
+     * the workspace root (same as status/lock), finds the latest run (or the
+     * given runId), advances via getNextLegalPhase, and returns the phase's lint
+     * rules + instructions. Returns null when no active phase exists. This is the
+     * canonical data source for the recursive_phase tool.
+     */
+    phaseRules(runId?: string, agent?: {
+        session?: {
+            header?: {
+                cwd?: string;
+            };
+        };
+    } | null): Promise<(PhaseRules & {
+        runId: string;
+        phase: string;
+    }) | null>;
     /**
      * Scaffold a run directory with FULL per-phase templates (no-op if exists).
      * 00-requirements.md + 00-worktree.md are byte-identical to canonical

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@try-works/dsh-recursive-mode",
   "description": "recursive-mode workflow as a DeepSeek Harness bundle: RecursiveRuntime service + recursive_status tool",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/src/index.ts

@@ -9,7 +9,8 @@ import { createRecursiveLockTool } from './recursive_lock.tool.ts'
 import { createRecursiveLintTool } from './recursive_lint.tool.ts'
 import { createRecursiveCloseoutTool } from './recursive_closeout.tool.ts'
 import { createRecursiveScratchTool } from './recursive_scratch.tool.ts'
-import { createRecursiveWorktreeTool } from './recursive_worktree.tool.ts'
+import { createRecursiveWorktreeTool } from './recursive_worktree.tool.ts'
+import { createRecursivePhaseTool } from './recursive_phase.tool.ts'
 import { registerRecursiveCommand } from './commands.ts'
 import { evaluateToolGuard } from './enforcement.ts'
 import { renderRecursivePolicy } from './policy.ts'
@@ -18,7 +19,7 @@ import { snapshotWorkspace } from './snapshot.ts'
 import { mountRecursiveRoutesOnce, makeRecursiveRoutes, type RecursiveRouteHost } from './live-route.ts'
 import { enumerateRuns, stageBWorkflowInit } from './bootstrap.ts'
 import { getNextLegalPhase, getLockStatus } from './lock.ts'
-import { phaseLintRulesMessage } from './phase-rules.ts'
+import { phaseLintRulesMessage, ReminderOnceGate } from './phase-rules.ts'
 
 export const name = '@try-works/dsh-recursive-mode'
 
@@ -29,7 +30,8 @@ export { createRecursiveLockTool } from './recursive_lock.tool.ts'
 export { createRecursiveLintTool } from './recursive_lint.tool.ts'
 export { createRecursiveCloseoutTool } from './recursive_closeout.tool.ts'
 export { createRecursiveScratchTool } from './recursive_scratch.tool.ts'
-export { createRecursiveWorktreeTool } from './recursive_worktree.tool.ts'
+export { createRecursiveWorktreeTool } from './recursive_worktree.tool.ts'
+export { createRecursivePhaseTool } from './recursive_phase.tool.ts'
 export * from './status.ts'
 export {
   PHASE_SEQUENCE,
@@ -101,7 +103,8 @@ export function apply(ctx: Context, config?: { shellOnly?: boolean; repoRoot?: s
     const workspaceRegistry = ctx.get('workspaceRegistry') as never
     const recursive = new RecursiveRuntime(ctx, { repoRoot: config?.repoRoot ?? process.cwd(), workspaceRegistry })
 
-    const repairedRoots = new Set<string>()
+    const repairedRoots = new Set<string>()
+    const reminderGate = new ReminderOnceGate()
     const disposers = [
       ctx.tools.register(createRecursiveStatusTool(recursive)),
       ctx.tools.register(createRecursiveInitTool(recursive)),
@@ -109,7 +112,8 @@ export function apply(ctx: Context, config?: { shellOnly?: boolean; repoRoot?: s
       ctx.tools.register(createRecursiveLintTool(recursive)),
       ctx.tools.register(createRecursiveCloseoutTool(recursive)),
       ctx.tools.register(createRecursiveScratchTool(recursive)),
-      ctx.tools.register(createRecursiveWorktreeTool(recursive)),
+      ctx.tools.register(createRecursiveWorktreeTool(recursive)),
+      ctx.tools.register(createRecursivePhaseTool(recursive)),
     ]
 
     // /recursive command (R4): preset-scoped registration, workspace-scoped dispatch.
@@ -207,7 +211,11 @@ export function apply(ctx: Context, config?: { shellOnly?: boolean; repoRoot?: s
         const phasePath = join(runDir, phase)
         const status = existsSync(phasePath) ? getLockStatus(phasePath) : null
         if (status !== 'DRAFT') return { kind: 'enter', messages } as const
-        const reminder = phaseLintRulesMessage(phase)
+        if (!reminderGate.shouldInject(root, runId, phase)) return { kind: 'enter', messages } as const
+                // LIVE BUG 6 (0.2.1): inject the lint-rules reminder AT MOST ONCE PER PHASE.
+                // The scaffold repair above is deduped via repairedRoots; the reminder itself was
+                // not, so every pre-step while DRAFT re-injected it.
+                const reminder = phaseLintRulesMessage(phase)
         return {
           kind: 'enter',
           messages: [...messages, createUserMessage({ content: [{ type: 'text', text: reminder }], source: { kind: 'plugin', plugin: '@try-works/dsh-recursive-mode' } })],

package/src/phase-rules.ts

@@ -240,18 +240,61 @@ export function getArtifactRequiredSections(fileName: string, workflowProfile: s
   return headings
 }
 
+/**
+ * LIVE BUG 6 (0.2.1): dedup gate for the agent/pre-step lint-rules reminder.
+ * Keyed by (root, runId, phase) so each new run or phase transition gets its own
+ * single injection, while re-arming steps in the SAME phase stay silent. Scoped
+ * to the apply() effect/fiber lifetime (one instance per mount), matching the
+ * repairedRoots dedup used by the scaffold repair above the injection point.
+ */
+export class ReminderOnceGate {
+  private seen = new Set<string>()
+
+  shouldInject(root: string, runId: string, phase: string): boolean {
+    const key = root + '\u0000' + runId + '\u0000' + phase
+    if (this.seen.has(key)) return false
+    this.seen.add(key)
+    return true
+  }
+}
+
+/**
+ * Structured, single-source-of-truth rules for one phase (refined LIVE BUG 6
+ * design): consumed by BOTH the recursive_phase tool and the once-per-phase
+ * pre-step reminder. Derived from the canonical artifact-template sections.
+ */
+export interface PhaseRules {
+  fileName: string
+  label: string
+  requiredSections: string[]
+  audited: boolean
+  tdd: boolean
+  qa: boolean
+}
+
+export function phaseRulesFor(fileName: string, workflowProfile: string = CURRENT_WORKFLOW_PROFILE): PhaseRules {
+  return {
+    fileName,
+    label: fileName.replace(/\.md$/, ''),
+    requiredSections: getArtifactRequiredSections(fileName, workflowProfile),
+    audited: AUDITED_PHASE_FILES.has(fileName),
+    tdd: fileName === '03-implementation-summary.md',
+    qa: fileName === '05-manual-qa.md',
+  }
+}
+
 /**
  * Compact lint-rules message for the pre-step injection (R5): this phase's
- * required sections + phase-specific gate notes, derived from the canonical
- * artifact-template sections. Kept short enough to prepend as a system-style
- * reminder without bloating the step context.
+ * required sections + phase-specific gate notes, built from phaseRulesFor
+ * (single source of truth with the recursive_phase tool). Output is unchanged
+ * from the prior inline build so r5-parity.spec.ts stays green.
  */
 export function phaseLintRulesMessage(fileName: string, workflowProfile: string = CURRENT_WORKFLOW_PROFILE): string {
-  const sections = getArtifactRequiredSections(fileName, workflowProfile)
+  const rules = phaseRulesFor(fileName, workflowProfile)
   const lines = [
     '<system-reminder>',
     'Recursive-mode phase lint rules for THIS phase (' + fileName + '):',
-    'Required sections: ' + sections.join(' | '),
+    'Required sections: ' + rules.requiredSections.join(' | '),
     'Gates: Coverage: FAIL until all checkboxes pass; Approval: FAIL until user sign-off; lock only via recursive_lock (monotonic).',
     'Audited phases: end with Audit: PASS before setting Coverage/Approval PASS; record Audit Context and Audit Verdict.',
     'TDD (phase 3): declare TDD Mode: strict|pragmatic; strict requires RED + GREEN evidence paths.',
@@ -259,4 +302,4 @@ export function phaseLintRulesMessage(fileName: string, workflowProfile: string
     '</system-reminder>',
   ]
   return lines.join('\n')
-}
+}

package/src/policy.ts

@@ -55,6 +55,7 @@ export function renderRecursivePolicy(context: PolicyContext | null): string {
     '- The control-plane root is resolved STRICTLY from this session workspace (never scan other workspaces).',
     '- Scratch is disposable, git-ignored, and never citable as an Input.',
     '- The workflow spec lives at /.recursive/RECURSIVE.md; bootstrap it when missing.',
+    '- Call recursive_phase when entering a new phase; the same rules are auto-injected once per phase transition.',
   ];
 
   // R5: surface the current phase's required sections + gate checklist.

package/src/recursive_phase.tool.ts

@@ -0,0 +1,29 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-tools'
+import type { RecursiveRuntime } from './runtime.ts'
+
+/**
+ * recursive_phase (refined LIVE BUG 6): the canonical on-demand home of the
+ * current phase's lint rules + instructions. Reads the same structured source
+ * (runtime.phaseRules -> phaseRulesFor) as the once-per-phase pre-step
+ * 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.
+ */
+export function createRecursivePhaseTool(recursive: RecursiveRuntime) {
+  return defineTool({
+    name: 'recursive_phase',
+    description: 'Return the lint rules + instructions for the current recursive-mode phase (required sections, gates, TDD/QA notes). Call once when entering a new phase; the same rules are also auto-injected once per phase transition.',
+    parameters: {
+      runId: { type: 'string', description: 'Optional run id (defaults to the latest run by mtime)' },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+    },
+    async execute(args: { runId?: string }, exec) {
+      const result = await recursive.phaseRules(args.runId, exec.agent as { session?: { header?: { cwd?: string } } } | null)
+      if (!result) return { error: 'no recursive phase found' } as const
+      return result as unknown as JsonValue
+    },
+  })
+}

package/src/runtime.ts

@@ -15,6 +15,7 @@ import {
 } from './lock.ts'
 import type { RecursiveStatusResult } from './types.ts'
 import { resolveControlPlaneRoot, type WorkspaceRegistryLike } from './workspace.ts'
+import { phaseRulesFor, type PhaseRules } from './phase-rules.ts'
 import { closeoutPhase } from './closeout.ts'
 import { readScratch, writeScratch, appendScratch, type ScratchTarget } from './scratch.ts'
 import { buildReviewBundle, type ReviewBundleInput } from './review.ts'
@@ -338,6 +339,23 @@ export class RecursiveRuntime extends Service {
     return foldRun(resolved.runDir, resolved.runId)
   }
 
+  /**
+   * LIVE BUG 6 refined: structured phase rules for the CURRENT phase. Resolves
+   * the workspace root (same as status/lock), finds the latest run (or the
+   * given runId), advances via getNextLegalPhase, and returns the phase's lint
+   * rules + instructions. Returns null when no active phase exists. This is the
+   * canonical data source for the recursive_phase tool.
+   */
+  async phaseRules(runId?: string, agent?: { session?: { header?: { cwd?: string } } } | null): Promise<(PhaseRules & { runId: string; phase: string }) | null> {
+    const root = await this.resolveRootFor(agent)
+    if (!root) return null
+    const resolved = resolveRunDir(root, runId)
+    if (!resolved) return null
+    const phase = getNextLegalPhase(resolved.runDir)
+    if (!phase) return null
+    return { runId: resolved.runId, phase, ...phaseRulesFor(phase) }
+  }
+
   /**
    * Scaffold a run directory with FULL per-phase templates (no-op if exists).
    * 00-requirements.md + 00-worktree.md are byte-identical to canonical