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

package/lib/init-templates.d.ts

@@ -8,6 +8,10 @@ export interface GitContext {
     baseBranch: string;
     worktreeBranch: string;
     baseCommit: string;
+    /** True when the init cwd is a linked git worktree (git-dir != git-common-dir). */
+    isWorktree: boolean;
+    /** Upstream branch with the remote prefix stripped (origin/dev -> dev), null when none/detached. */
+    upstreamBranch: string | null;
     notes: string;
 }
 /**

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/recursive_worktree.tool.d.ts

@@ -0,0 +1,7 @@
+import type { RecursiveRuntime } from './runtime.ts';
+/**
+ * `recursive_worktree` — create a linked git worktree for a run and/or
+ * promote a branch up the dev/stage/main chain. Workspace-scoped: the
+ * operations run under the SESSION's control-plane root only.
+ */
+export declare function createRecursiveWorktreeTool(recursive: RecursiveRuntime): import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/runtime.d.ts

@@ -1,12 +1,14 @@
 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';
 import { type SubagentsRuntimeLike, type SubagentStartRequestLike, type SubagentResultLike, type Reference } from './delegation.ts';
 import { type PhaseTransitionIntent, type SessionEventLike, type RecursivePhaseState, type GateCheckResult } from './lifecycle.ts';
 import { type EnforcementConfig, type PreStepGateDecision, type ToolGuardDecision, type ToolExecLike } from './enforcement.ts';
+import { type CreateWorktreeResult, type PromoteBranchResult } from './worktree.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         recursive: RecursiveRuntime;
@@ -173,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
@@ -180,6 +199,12 @@ export declare class RecursiveRuntime extends Service {
      * required section (get_artifact_required_sections) + TODO + FAIL gates.
      * Also scaffolds addenda/subagents/router-prompts/evidence dirs. Returns the
      * run dir + created artifacts.
+     *
+     * When `opts.createWorktree` is true, a linked worktree is first created at
+     * `.worktrees/<runId>/` and the run is scaffolded INSIDE it (per the
+     * "all subsequent phases execute in worktree context" rule). The worktree
+     * branch defaults to `recursive/<runId>` and is cut from `opts.baseBranch`
+     * (default: current HEAD branch of the root checkout).
      */
     initRun(runId: string, agent?: {
         session?: {
@@ -187,12 +212,32 @@ export declare class RecursiveRuntime extends Service {
                 cwd?: string;
             };
         };
-    } | null): Promise<{
+    } | null, opts?: {
+        createWorktree?: boolean;
+        baseBranch?: string;
+    }): Promise<{
         runDir: string;
         runId: string;
         created: string[];
         existing: string[];
+        worktree?: CreateWorktreeResult;
     }>;
+    /**
+     * Create a linked worktree for a run under the given workspace root. The
+     * worktree branch defaults to `recursive/<runId>` and is cut from the given
+     * base branch (default: the current HEAD branch of the root checkout).
+     * Refuses to create over an existing run directory. Workspace-scoped.
+     */
+    createRunWorktree(root: string, runId: string, baseBranch?: string): CreateWorktreeResult;
+    /**
+     * Promote a branch up the dev/stage/main chain (fast-forward). Workspace-scoped.
+     */
+    promoteRunBranch(root: string, fromBranch: string, toBranch: string): PromoteBranchResult;
+    /**
+     * Worktree + branch status for a workspace root: the linked worktrees,
+     * which branch each is on, and the current checkout's base/upstream context.
+     */
+    worktreeStatus(root: string): Record<string, unknown>;
     /**
      * Lock a DRAFT artifact (or reopen a LOCKED one). Validates prerequisites;
      * writes Status/LockedAt/LockHash + receipt. Returns the lock result.

package/lib/ts-lint.d.ts

@@ -105,6 +105,14 @@ export declare function normalizeComparisonReference(value: string | null): stri
 export declare function parseDiffBasisSource(content: string): string;
 /** get_run_diff_basis: read diff-basis fields from 00-worktree.md. */
 export declare function getRunDiffBasis(runDir: string): Record<string, string | null>;
+/**
+ * verify_recorded_branches: worktree + branch awareness at lint time. Compares
+ * the branches recorded in 00-worktree.md against live git state. Returns a
+ * list of FAIL messages (empty when consistent). Both the base branch and the
+ * worktree branch must resolve; the worktree branch must match the live HEAD
+ * branch, and it must actually be based on the recorded base branch.
+ */
+export declare function verifyRecordedBranches(repoRoot: string, diffBasis: Record<string, string | null>, runDir: string): string[];
 /** normalize_diff_basis: validate + compute the executable diff basis. */
 export declare function normalizeDiffBasis(repoRoot: string, diffBasis: Record<string, string | null>): [Record<string, string> | null, string | null];
 /** get_git_changed_files: git diff --name-only + untracked (--relative). */

package/lib/worktree.d.ts

@@ -0,0 +1,59 @@
+export interface CreateWorktreeOptions {
+    repoRoot: string;
+    runId: string;
+    /** Base branch the worktree branch is cut from (default: current HEAD branch). */
+    baseBranch?: string;
+    /** Worktree branch name (default: `recursive/<runId>`). */
+    worktreeBranch?: string;
+}
+export interface CreateWorktreeResult {
+    ok: boolean;
+    worktreeDir: string;
+    worktreeBranch: string;
+    baseBranch: string;
+    error?: string;
+}
+export interface PromoteBranchOptions {
+    repoRoot: string;
+    /** Branch being promoted (the source of the new commits). */
+    fromBranch: string;
+    /** Promotion target branch (feature -> dev -> stage -> main). */
+    toBranch: string;
+}
+export interface PromoteBranchResult {
+    ok: boolean;
+    fromBranch: string;
+    toBranch: string;
+    action: 'fast-forward' | 'created';
+    error?: string;
+}
+/** Default worktree branch name for a run. */
+export declare function defaultWorktreeBranch(runId: string): string;
+/** One row of `git worktree list --porcelain` (path + branch when attached). */
+export interface WorktreeInfo {
+    path: string;
+    branch: string | null;
+    detached: boolean;
+}
+/** List linked worktrees (path + branch) for a repo root. */
+export declare function listWorktrees(repoRoot: string): WorktreeInfo[];
+/**
+ * Find the worktree path where `branch` is currently checked out, or null.
+ * Parses `git worktree list --porcelain` (block per worktree with a
+ * `branch refs/heads/<name>` line).
+ */
+export declare function findWorktreeForBranch(repoRoot: string, branch: string): string | null;
+/**
+ * Create a linked worktree at `.worktrees/<runId>/` for a run. The worktree
+ * branch is cut from `baseBranch` (default: the current HEAD branch). Returns
+ * the created worktree dir + branch. No-op-safe: if the worktree dir already
+ * exists, returns ok with the existing dir. Refuses to create a worktree when
+ * the run directory already exists (prevents clobbering an in-progress run).
+ */
+export declare function createLinkedWorktree(opts: CreateWorktreeOptions): CreateWorktreeResult;
+/**
+ * Fast-forward `toBranch` to `fromBranch` (promotion up the dev/stage/main
+ * chain). Returns ok:false when the promotion is not a pure fast-forward
+ * (would require a merge commit) or when the from/to branches are missing.
+ */
+export declare function promoteBranch(opts: PromoteBranchOptions): PromoteBranchResult;

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.1.18",
+  "version": "0.2.1",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/src/commands.ts

@@ -85,6 +85,28 @@ export function executeRecursiveCommand(root: string, rawInput: string): Recursi
       if (!existsSync(runDir)) return { kind: 'error', text: 'Run not found in current workspace: ' + runId }
       return { kind: 'success', text: 'closeout scaffolded for ' + runId + ' phase ' + phase }
     }
+    case 'worktree': {
+      // /recursive worktree create <runId> [--base <branch>]
+      // /recursive worktree promote <from> <to>
+      // /recursive worktree status
+      const parts = arg.trim().split(/\s+/)
+      const op = parts[0] ?? ''
+      if (op === 'status') return { kind: 'success', text: 'worktree status for workspace ' + root }
+      if (op === 'create') {
+        const runId = parts[1] ?? ''
+        if (!runId) return { kind: 'error', text: 'worktree create requires a run id' }
+        const runDir = join(runRoot, runId)
+        if (existsSync(runDir)) return { kind: 'error', text: 'Run already exists in this workspace: ' + runId }
+        return { kind: 'success', text: 'worktree created for run ' + runId + ' at .worktrees/' + runId }
+      }
+      if (op === 'promote') {
+        const fromBranch = parts[1] ?? ''
+        const toBranch = parts[2] ?? ''
+        if (!fromBranch || !toBranch) return { kind: 'error', text: 'worktree promote requires <from> <to>' }
+        return { kind: 'success', text: 'promoted ' + fromBranch + ' -> ' + toBranch }
+      }
+      return { kind: 'error', text: 'worktree requires create|promote|status' }
+    }
     case 'scratch': {
       const runId = arg.trim()
       if (!runId) return { kind: 'error', text: 'scratch requires a run id' }
@@ -147,6 +169,30 @@ export function registerRecursiveCommand(
           return { kind: 'success', text: 'closeout scaffolded: ' + JSON.stringify(result) }
         }
       }
+      if (verb === 'worktree' && arg) {
+        const parts = arg.trim().split(/\s+/)
+        const op = parts[0] ?? ''
+        if (op === 'create') {
+          const runId = parts[1] ?? ''
+          const baseMatch = arg.match(/--base\s+(\S+)/)
+          const baseBranch = baseMatch?.[1]
+          if (!runId) return { kind: 'error', text: 'worktree create requires a run id' }
+          const result = recursive.createRunWorktree(root, runId, baseBranch)
+          if (!result.ok) return { kind: 'error', text: result.error ?? 'worktree create failed' }
+          return { kind: 'success', text: 'worktree created: ' + JSON.stringify(result) }
+        }
+        if (op === 'promote') {
+          const fromBranch = parts[1] ?? ''
+          const toBranch = parts[2] ?? ''
+          if (!fromBranch || !toBranch) return { kind: 'error', text: 'worktree promote requires <from> <to>' }
+          const result = recursive.promoteRunBranch(root, fromBranch, toBranch)
+          if (!result.ok) return { kind: 'error', text: result.error ?? 'promote failed' }
+          return { kind: 'success', text: 'promoted: ' + JSON.stringify(result) }
+        }
+        if (op === 'status') {
+          return { kind: 'success', text: 'worktree status: ' + JSON.stringify(recursive.worktreeStatus(root)) }
+        }
+      }
       return executeRecursiveCommand(root, rawInput)
     },
   })

package/src/git-context.ts

@@ -0,0 +1,132 @@
+/**
+ * git-context.ts — live git facts used for worktree + branch awareness (R?).
+ *
+ * Worktree/branch awareness goal: the plugin must know WHICH checkout and
+ * WHICH branch a run is executing in, so Phase 0 records an honest base-vs-
+ * worktree branch split and lint fails when the recorded context no longer
+ * matches live git state.
+ *
+ * Detection primitives:
+ * - `isLinkedWorktree` — a directory is a linked git worktree when its private
+ *   git dir (`git rev-parse --git-dir`) differs from the common git dir
+ *   (`git rev-parse --git-common-dir`). The main checkout has both equal.
+ * - `upstreamBranch` — the current branch's upstream target with the remote
+ *   prefix stripped (origin/main -> main). Used to infer the promotion source
+ *   branch for dev/stage/main workflows.
+ *
+ * Every accessor is total: on missing git or non-git dirs it returns null /
+ * false, never throws. Callers defer rather than fail hard.
+ */
+import { execFileSync } from 'node:child_process'
+
+/** Normalized git facts about one checkout directory. */
+export interface GitRepoFacts {
+  /** SHA of HEAD^{commit}, or null when unresolvable (empty/non-git repo). */
+  headSha: string | null
+  /** Current branch short name via `git symbolic-ref --short HEAD`, null when detached. */
+  branch: string | null
+  /** True when HEAD is detached (no symbolic ref). */
+  detached: boolean
+  /** True when the cwd is a linked worktree (git-dir != git-common-dir). */
+  isWorktree: boolean
+  /** `git rev-parse --git-dir` output (may be relative). */
+  gitDir: string | null
+  /** `git rev-parse --git-common-dir` output (may be relative). */
+  commonDir: string | null
+  /** `git rev-parse --show-toplevel` output, or null. */
+  toplevel: string | null
+  /** Upstream branch with remote prefix stripped (origin/main -> main), null when none/detached. */
+  upstreamBranch: string | null
+}
+
+/** Run git in a repo dir; return trimmed stdout or null on any failure. */
+export function gitRun(repoRoot: string, ...args: string[]): string | null {
+  try {
+    return execFileSync('git', args, { cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+  } catch {
+    return null
+  }
+}
+
+/** True when a non-equal git-dir vs git-common-dir marks a linked worktree. */
+export function isLinkedWorktree(gitDir: string | null, commonDir: string | null): boolean {
+  if (!gitDir || !commonDir) return false
+  return gitDir !== commonDir
+}
+
+/** Strip a remote ref prefix (origin/main -> main, remotes/origin/main -> main). */
+export function stripRemotePrefix(ref: string | null): string | null {
+  if (!ref) return null
+  const trimmed = ref.trim()
+  const short = trimmed.replace(/^refs\/remotes\//, '').replace(/^[^/]+\//, '')
+  return short === '' ? null : short
+}
+
+/**
+ * Gather normalized git facts about `repoRoot`. Total: any git failure
+ * degrades to neutral values (false / null), never throws.
+ */
+export function gitFacts(repoRoot: string): GitRepoFacts {
+  const gitDir = gitRun(repoRoot, 'rev-parse', '--git-dir')
+  const commonDir = gitRun(repoRoot, 'rev-parse', '--git-common-dir')
+  const headSha = gitRun(repoRoot, 'rev-parse', '--verify', 'HEAD^{commit}')
+  const branch = gitRun(repoRoot, 'symbolic-ref', '--quiet', '--short', 'HEAD')
+  const toplevel = gitRun(repoRoot, 'rev-parse', '--show-toplevel')
+  const upstreamRef = gitRun(repoRoot, 'rev-parse', '--abbrev-ref', '@{upstream}')
+  return {
+    headSha,
+    branch: branch || null,
+    detached: !branch,
+    isWorktree: isLinkedWorktree(gitDir, commonDir),
+    gitDir,
+    commonDir,
+    toplevel,
+    upstreamBranch: branch ? stripRemotePrefix(upstreamRef) : null,
+  }
+}
+
+/**
+ * Resolve the effective base branch for a checkout. In a linked worktree this
+ * is the branch the work is based on — best inferred from the upstream target
+ * (dev/stage/main promotion source) when one is configured; otherwise fall
+ * back to the current branch. Returns null only when no branch exists.
+ */
+export function resolveBaseBranch(facts: GitRepoFacts): string | null {
+  if (facts.branch && facts.upstreamBranch && facts.upstreamBranch !== facts.branch) {
+    return facts.upstreamBranch
+  }
+  return facts.branch
+}
+
+/**
+ * Verify a worktree branch is (still) based on the recorded base branch.
+ * Returns { ok, reason }. Fails when the base branch no longer exists, or the
+ * worktree branch no longer contains it (merge-base --is-ancestor fails).
+ * A missing/unresolvable branch degrades to ok:false with a reason; a
+ * non-git dir degrades to ok:true (defer — nothing to verify).
+ */
+export function verifyBranchBase(repoRoot: string, baseBranch: string | null, worktreeBranch: string | null): { ok: boolean; reason: string | null } {
+  if (!baseBranch || !worktreeBranch) return { ok: true, reason: null }
+  const gitDir = gitRun(repoRoot, 'rev-parse', '--git-dir')
+  if (!gitDir) return { ok: true, reason: null }
+  const baseSha = gitRun(repoRoot, 'rev-parse', '--verify', `${baseBranch}^{commit}`)
+  if (!baseSha) return { ok: false, reason: `recorded base branch '${baseBranch}' does not resolve in this checkout` }
+  const wtSha = gitRun(repoRoot, 'rev-parse', '--verify', `${worktreeBranch}^{commit}`)
+  if (!wtSha) return { ok: false, reason: `recorded worktree branch '${worktreeBranch}' does not resolve in this checkout` }
+  // merge-base --is-ancestor <base> <worktree> -> exit 0 means base is an ancestor.
+  try {
+    execFileSync('git', ['-C', repoRoot, 'merge-base', '--is-ancestor', baseBranch, worktreeBranch], { stdio: ['ignore', 'pipe', 'pipe'] })
+    return { ok: true, reason: null }
+  } catch {
+    return { ok: false, reason: `worktree branch '${worktreeBranch}' is not based on recorded base branch '${baseBranch}'` }
+  }
+}
+
+/** Verify the recorded worktree branch matches the live HEAD branch. */
+export function verifyWorktreeBranch(repoRoot: string, recordedBranch: string | null): { ok: boolean; reason: string | null } {
+  if (!recordedBranch) return { ok: true, reason: null }
+  const live = gitRun(repoRoot, 'symbolic-ref', '--quiet', '--short', 'HEAD')
+  if (!live) return { ok: false, reason: 'HEAD is detached; expected branch ' + recordedBranch }
+  if (live !== recordedBranch) return { ok: false, reason: `checkout is on branch '${live}' but 00-worktree.md records '${recordedBranch}'` }
+  return { ok: true, reason: null }
+}

package/src/index.ts

@@ -9,6 +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 { createRecursivePhaseTool } from './recursive_phase.tool.ts'
 import { registerRecursiveCommand } from './commands.ts'
 import { evaluateToolGuard } from './enforcement.ts'
 import { renderRecursivePolicy } from './policy.ts'
@@ -17,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'
 
@@ -28,6 +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 { createRecursivePhaseTool } from './recursive_phase.tool.ts'
 export * from './status.ts'
 export {
   PHASE_SEQUENCE,
@@ -99,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)),
@@ -107,6 +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(createRecursivePhaseTool(recursive)),
     ]
 
     // /recursive command (R4): preset-scoped registration, workspace-scoped dispatch.
@@ -204,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/init-templates.ts

@@ -12,6 +12,7 @@
 import { execFileSync } from 'node:child_process'
 import { join } from 'node:path'
 import { getArtifactRequiredSections } from './phase-rules.ts'
+import { gitFacts, resolveBaseBranch, type GitRepoFacts } from './git-context.ts'
 
 export interface GitContext {
   baselineType: string
@@ -23,6 +24,10 @@ export interface GitContext {
   baseBranch: string
   worktreeBranch: string
   baseCommit: string
+  /** True when the init cwd is a linked git worktree (git-dir != git-common-dir). */
+  isWorktree: boolean
+  /** Upstream branch with the remote prefix stripped (origin/dev -> dev), null when none/detached. */
+  upstreamBranch: string | null
   notes: string
 }
 
@@ -42,7 +47,13 @@ export function detectGitContext(repoRoot: string): { context: Partial<GitContex
   if (!headSha) {
     return { context: {}, error: 'Unable to resolve HEAD commit for Phase 0 diff basis prefill: git rev-parse returned no output' }
   }
-  const branch = run(['symbolic-ref', '--quiet', '--short', 'HEAD']) || '(detached HEAD)'
+  const facts: GitRepoFacts = gitFacts(repoRoot)
+  const branch = facts.branch ?? '(detached HEAD)'
+  // Distinct base branch: in a linked worktree the work is based on the branch
+  // whose upstream target is the promotion source (dev/stage/main). When no
+  // upstream is configured, fall back to the current branch so the recorded
+  // base is always a resolvable ref.
+  const baseBranch = resolveBaseBranch(facts) ?? branch
   const diffCommand = 'git diff --name-only ' + headSha
   return {
     context: {
@@ -52,9 +63,11 @@ export function detectGitContext(repoRoot: string): { context: Partial<GitContex
       normalizedBaseline: headSha,
       normalizedComparison: 'working-tree',
       normalizedDiffCommand: diffCommand,
-      baseBranch: branch,
+      baseBranch,
       worktreeBranch: branch,
       baseCommit: headSha,
+      isWorktree: facts.isWorktree,
+      upstreamBranch: facts.upstreamBranch,
       notes: 'recursive-init prefilled this executable diff basis from the current HEAD commit. If Phase 0 later changes the chosen baseline, update every diff-basis field and rerun lint before locking.',
     },
     error: null,

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_init.tool.ts

@@ -5,20 +5,26 @@ import type { RecursiveRuntime } from './runtime.ts'
 export function createRecursiveInitTool(recursive: RecursiveRuntime) {
   return defineTool({
     name: 'recursive_init',
-    description: 'Scaffold a new recursive-mode run directory (or ensure an existing one) with stub artifact headers. Delegates to the RecursiveRuntime service (no duplicated scaffolding logic).',
+    description: 'Scaffold a new recursive-mode run directory (or ensure an existing one) with stub artifact headers. Delegates to the RecursiveRuntime service (no duplicated scaffolding logic). When createWorktree is true, a linked worktree is created first and the run is scaffolded inside it.',
     parameters: {
       runId: { type: 'string', description: 'Run id (e.g. 03-something). Required.' },
+      createWorktree: { type: 'boolean', description: 'If true, create a linked worktree at .worktrees/<runId>/ and scaffold the run inside it (default: false).' },
+      baseBranch: { type: 'string', description: 'Base branch the worktree branch is cut from (default: current HEAD branch). Only used when createWorktree is true.' },
     },
     output: {
       schema: { type: 'json' },
       render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
     },
-    async execute(args: { runId?: string }, exec) {
+    async execute(args: { runId?: string; createWorktree?: boolean; baseBranch?: string }, exec) {
       if (!args.runId || args.runId.trim() === '') {
         return { error: 'runId is required' } as const
       }
       try {
-        const result = await recursive.initRun(args.runId.trim(), exec.agent as { session?: { header?: { cwd?: string } } } | null)
+        const result = await recursive.initRun(
+          args.runId.trim(),
+          exec.agent as { session?: { header?: { cwd?: string } } } | null,
+          { createWorktree: args.createWorktree === true, baseBranch: args.baseBranch?.trim() || undefined },
+        )
         return result as unknown as JsonValue
       } catch (err) {
         return { error: err instanceof Error ? err.message : String(err) } as const