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

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

@@ -0,0 +1,54 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import type { JsonValue } from '@deepseek-ai/dsh-tools'
+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 function createRecursiveWorktreeTool(recursive: RecursiveRuntime) {
+  return defineTool({
+    name: 'recursive_worktree',
+    description: 'Create a linked git worktree for a recursive-mode run and/or promote a branch up the dev/stage/main chain. Workspace-scoped under the current session workspace.',
+    parameters: {
+      runId: { type: 'string', description: 'Run id the worktree is created for (e.g. 03-something). Required for create.' },
+      action: { type: 'string', description: 'create | promote | status. Default: create.' },
+      fromBranch: { type: 'string', description: 'Source branch for a promote action (the branch holding the new commits).' },
+      toBranch: { type: 'string', description: 'Promotion target branch for a promote action (feature -> dev -> stage -> main).' },
+      baseBranch: { type: 'string', description: 'Base branch the worktree branch is cut from (default: current HEAD branch).' },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+    },
+    async execute(args: { action?: string; runId?: string; fromBranch?: string; toBranch?: string; baseBranch?: string }, exec) {
+      const action = args.action ?? 'create'
+      // Resolve the control-plane root: agent cwd first, repoRoot fallback (B4),
+      // so tests and headless callers work without a live session header.
+      const root = await recursive.resolveRootFor(exec.agent as { session?: { header?: { cwd?: string } } } | null)
+      if (!root) {
+        return { error: 'session is not attached to a registered workspace (cannot resolve control-plane root)' } as const
+      }
+      if (action === 'create') {
+        if (!args.runId || args.runId.trim() === '') {
+          return { error: 'runId is required for create' } as const
+        }
+        const result = recursive.createRunWorktree(root, args.runId.trim(), args.baseBranch?.trim() || undefined)
+        return result as unknown as JsonValue
+      }
+      if (action === 'promote') {
+        if (!args.fromBranch || !args.toBranch) {
+          return { error: 'fromBranch and toBranch are required for promote' } as const
+        }
+        const result = recursive.promoteRunBranch(root, args.fromBranch.trim(), args.toBranch.trim())
+        return result as unknown as JsonValue
+      }
+      if (action === 'status') {
+        const result = recursive.worktreeStatus(root)
+        return result as unknown as JsonValue
+      }
+      return { error: 'action must be create | promote | status' } as const
+    },
+  })
+}

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'
@@ -26,6 +27,8 @@ import { resolveEnforcementConfig, DEFAULT_ENFORCEMENT, evaluatePreStepGate, eva
 import type { Session } from '@deepseek-ai/dsh-session'
 import { renderRecursivePolicy, type PolicyContext } from './policy.ts'
 import { snapshotWorkspace } from './snapshot.ts'
+import { createLinkedWorktree, promoteBranch, listWorktrees, defaultWorktreeBranch, type CreateWorktreeResult, type PromoteBranchResult } from './worktree.ts'
+import { gitFacts } from './git-context.ts'
 
 declare module '@deepseek-ai/cordis' {
   interface Context {
@@ -336,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
@@ -343,11 +363,24 @@ export 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).
    */
-  async initRun(runId: string, agent?: { session?: { header?: { cwd?: string } } } | null): Promise<{ runDir: string; runId: string; created: string[]; existing: string[] }> {
+  async initRun(runId: string, agent?: { session?: { header?: { cwd?: string } } } | null, opts?: { createWorktree?: boolean; baseBranch?: string }): Promise<{ runDir: string; runId: string; created: string[]; existing: string[]; worktree?: CreateWorktreeResult }> {
     const root = await this.resolveRootFor(agent)
     if (!root) throw new Error('cannot resolve workspace control-plane root for this session')
-    const runDir = join(root, '.recursive', 'run', runId)
+    let scaffoldRoot = root
+    let worktree: CreateWorktreeResult | undefined
+    if (opts?.createWorktree) {
+      worktree = createLinkedWorktree({ repoRoot: root, runId, baseBranch: opts.baseBranch })
+      if (!worktree.ok) throw new Error(worktree.error ?? 'worktree create failed')
+      scaffoldRoot = worktree.worktreeDir
+    }
+    const runDir = join(scaffoldRoot, '.recursive', 'run', runId)
     mkdirSync(runDir, { recursive: true })
     const created: string[] = []
     const existing: string[] = []
@@ -360,13 +393,14 @@ export class RecursiveRuntime extends Service {
       created.push(dir + '/')
     }
 
-    // Git context for the Phase 0 diff-basis prefill (canonical parity).
-    const { context: gitContext, error: prefillError } = detectGitContext(root)
+    // Git context for the Phase 0 diff-basis prefill (canonical parity). When a
+    // worktree was created, the git context + Phase 0 record the WORKTREE.
+    const { context: gitContext, error: prefillError } = detectGitContext(scaffoldRoot)
 
     // Phase 0 templates: byte-identical to canonical recursive-init.py.
     const phase0: Array<[string, string]> = [
       ['00-requirements.md', requirementsContent(runId, 'feature', '')],
-      ['00-worktree.md', worktreeContent(runId, root, gitContext, prefillError)],
+      ['00-worktree.md', worktreeContent(runId, scaffoldRoot, gitContext, prefillError)],
     ]
     for (const [file, content] of phase0) {
       const path = join(runDir, file)
@@ -395,7 +429,42 @@ export class RecursiveRuntime extends Service {
       created.push(file)
     }
 
-    return { runDir, runId, created, existing }
+    const result: { runDir: string; runId: string; created: string[]; existing: string[]; worktree?: CreateWorktreeResult } = { runDir, runId, created, existing }
+    if (worktree) result.worktree = worktree
+    return result
+  }
+
+  /**
+   * 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 {
+    return createLinkedWorktree({ repoRoot: root, runId, baseBranch })
+  }
+
+  /**
+   * Promote a branch up the dev/stage/main chain (fast-forward). Workspace-scoped.
+   */
+  promoteRunBranch(root: string, fromBranch: string, toBranch: string): PromoteBranchResult {
+    return promoteBranch({ repoRoot: root, fromBranch, toBranch })
+  }
+
+  /**
+   * 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> {
+    const facts = gitFacts(root)
+    const worktrees = listWorktrees(root)
+    return {
+      root,
+      isWorktree: facts.isWorktree,
+      branch: facts.branch,
+      upstreamBranch: facts.upstreamBranch,
+      worktrees,
+    }
   }
 
   /**

package/src/ts-lint.ts

@@ -10,6 +10,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
 import { join, basename, dirname } from 'node:path'
 import { createHash } from 'node:crypto'
 import { execFileSync } from 'node:child_process'
+import { verifyBranchBase, verifyWorktreeBranch } from './git-context.ts'
 import {
   CURRENT_WORKFLOW_PROFILE,
   STRICT_WORKFLOW_PROFILE,
@@ -441,6 +442,26 @@ export 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 function verifyRecordedBranches(repoRoot: string, diffBasis: Record<string, string | null>, runDir: string): string[] {
+  const fails: string[] = []
+  const baseBranch = trimMdValue(diffBasis.base_branch ?? '')
+  const worktreeBranch = trimMdValue(diffBasis.worktree_branch ?? '')
+  // Nothing recorded -> nothing to verify (defer, consistent with missing fields).
+  if (!baseBranch && !worktreeBranch) return fails
+  const wtCheck = verifyWorktreeBranch(repoRoot, worktreeBranch || null)
+  if (!wtCheck.ok && wtCheck.reason) fails.push(wtCheck.reason)
+  const baseCheck = verifyBranchBase(repoRoot, baseBranch || null, worktreeBranch || null)
+  if (!baseCheck.ok && baseCheck.reason) fails.push(baseCheck.reason)
+  return fails
+}
+
 /** normalize_diff_basis: validate + compute the executable diff basis. */
 export function normalizeDiffBasis(repoRoot: string, diffBasis: Record<string, string | null>): [Record<string, string> | null, string | null] {
   const baselineType = normalizeBaselineType(diffBasis.baseline_type)
@@ -2007,6 +2028,16 @@ export function lintRun(repoRoot: string, runId: string): LintResult {
     let diffBasisError: string | null = null
     if (STRICT_WORKFLOW_PROFILES.has(workflowProfile)) {
       const diffBasis = getRunDiffBasis(runDir)
+      // Worktree + branch awareness: verify the recorded base/worktree branch
+      // context against live git before trusting the diff basis. Emits FAIL when
+      // the run's recorded checkout/branch no longer matches reality (e.g. lint
+      // running from the main checkout instead of the run's worktree, or the
+      // worktree branch changed after Phase 0 locked).
+      const branchFails = verifyRecordedBranches(root, diffBasis, runDir)
+      for (const message of branchFails) {
+        totalFail += 1
+        writeIssue('FAIL', runDir, message)
+      }
       if (diffBasis.baseline_reference || diffBasis.normalized_baseline) {
         const [rawChanged, gitError] = getGitChangedFiles(root, diffBasis)
         if (gitError) {

package/src/worktree.ts

@@ -0,0 +1,229 @@
+/**
+ * worktree.ts — drive linked-worktree creation and branch promotion.
+ *
+ * Worktree + branch awareness, operational half (R?): after detection
+ * (git-context.ts) and lint validation (ts-lint.ts), this module performs the
+ * git operations that actually realize the dev/stage/main worktree workflow:
+ *
+ * - `createLinkedWorktree`: create a linked worktree at
+ *   `<repoRoot>/.worktrees/<runId>/` on a worktree branch based on a base
+ *   branch (default: the upstream/promotion source branch).
+ * - `promoteBranch`: fast-forward one branch into a target promotion stage
+ *   (feature -> dev -> stage -> main). The promotion is verified to be a
+ *   fast-forward first (the target must be an ancestor of the source) and
+ *   then applied where it is safe:
+ *     - if the target branch is checked out in a worktree, `git merge
+ *       --ff-only` runs THERE (safe: moves the branch and its working tree
+ *       forward together, never a merge commit);
+ *     - otherwise the branch ref is updated directly.
+ *   It never rewrites history and never creates a merge commit.
+ *
+ * Both operations are explicit, workspace-scoped, and total: they return
+ * { ok, ... } rather than corrupting git state. No operation ever touches a
+ * branch other than the explicitly requested one.
+ */
+import { execFileSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+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
+}
+
+/** Run git; throw on failure (callers catch to turn into a result). */
+function gitThrow(repoRoot: string, ...args: string[]): string {
+  return execFileSync('git', args, { cwd: repoRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim()
+}
+
+/** Resolve the current branch of a repo dir (short name or null when detached). */
+function currentBranch(repoRoot: string): string | null {
+  try {
+    return gitThrow(repoRoot, 'symbolic-ref', '--quiet', '--short', 'HEAD')
+  } catch {
+    return null
+  }
+}
+
+/** Default worktree branch name for a run. */
+export function defaultWorktreeBranch(runId: string): string {
+  return 'recursive/' + runId
+}
+
+/** 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 function listWorktrees(repoRoot: string): WorktreeInfo[] {
+  let out: string
+  try {
+    out = gitThrow(repoRoot, 'worktree', 'list', '--porcelain')
+  } catch {
+    return []
+  }
+  const result: WorktreeInfo[] = []
+  let current: WorktreeInfo | null = null
+  for (const line of out.split(/\r?\n/)) {
+    const trimmed = line.trim()
+    if (!trimmed) { if (current) { result.push(current); current = null } continue }
+    if (trimmed.startsWith('worktree ')) {
+      current = { path: trimmed.slice('worktree '.length), branch: null, detached: false }
+    } else if (trimmed.startsWith('branch refs/heads/') && current) {
+      current.branch = trimmed.slice('branch refs/heads/'.length)
+    } else if (trimmed === 'detached' && current) {
+      current.detached = true
+    }
+  }
+  if (current) result.push(current)
+  return result
+}
+
+/**
+ * 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 function findWorktreeForBranch(repoRoot: string, branch: string): string | null {
+  let out: string
+  try {
+    out = gitThrow(repoRoot, 'worktree', 'list', '--porcelain')
+  } catch {
+    return null
+  }
+  let currentPath: string | null = null
+  for (const line of out.split(/\r?\n/)) {
+    const trimmed = line.trim()
+    if (!trimmed) { currentPath = null; continue }
+    if (trimmed.startsWith('worktree ')) {
+      currentPath = trimmed.slice('worktree '.length)
+    } else if (trimmed.startsWith('branch refs/heads/')) {
+      const name = trimmed.slice('branch refs/heads/'.length)
+      if (name === branch && currentPath) return currentPath
+    }
+  }
+  return 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 function createLinkedWorktree(opts: CreateWorktreeOptions): CreateWorktreeResult {
+  const { repoRoot, runId } = opts
+  const baseBranch = opts.baseBranch ?? currentBranch(repoRoot) ?? 'main'
+  const worktreeBranch = opts.worktreeBranch ?? defaultWorktreeBranch(runId)
+  const worktreeDir = join(repoRoot, '.worktrees', runId)
+
+  if (existsSync(worktreeDir)) {
+    return { ok: true, worktreeDir, worktreeBranch, baseBranch, error: undefined }
+  }
+  // Guard: never create a worktree over an in-progress run directory.
+  const runDir = join(repoRoot, '.recursive', 'run', runId)
+  if (existsSync(runDir)) {
+    return { ok: false, worktreeDir, worktreeBranch, baseBranch, error: 'run directory already exists: ' + runDir + ' (refusing to create a worktree for an existing run)' }
+  }
+  // Base branch must resolve.
+  try {
+    gitThrow(repoRoot, 'rev-parse', '--verify', baseBranch + '^{commit}')
+  } catch {
+    return { ok: false, worktreeDir, worktreeBranch, baseBranch, error: 'base branch does not resolve: ' + baseBranch }
+  }
+  try {
+    gitThrow(repoRoot, 'worktree', 'add', '-b', worktreeBranch, worktreeDir, baseBranch)
+  } catch (err) {
+    return { ok: false, worktreeDir, worktreeBranch, baseBranch, error: 'git worktree add failed: ' + (err as Error).message }
+  }
+  return { ok: true, worktreeDir, worktreeBranch, baseBranch }
+}
+
+/**
+ * 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 function promoteBranch(opts: PromoteBranchOptions): PromoteBranchResult {
+  const { repoRoot, fromBranch, toBranch } = opts
+  if (fromBranch === toBranch) {
+    return { ok: false, fromBranch, toBranch, action: 'fast-forward', error: 'from and to branches are identical: ' + fromBranch }
+  }
+  // Resolve the source commit; the target may or may not exist yet.
+  let fromSha: string | null = null
+  try { fromSha = gitThrow(repoRoot, 'rev-parse', '--verify', fromBranch + '^{commit}') } catch { /* missing */ }
+  if (!fromSha) {
+    return { ok: false, fromBranch, toBranch, action: 'fast-forward', error: 'from branch does not resolve: ' + fromBranch }
+  }
+  let toSha: string | null = null
+  try { toSha = gitThrow(repoRoot, 'rev-parse', '--verify', toBranch + '^{commit}') } catch { /* missing */ }
+
+  if (!toSha) {
+    // Target doesn't exist yet — create it at the source commit (first promotion).
+    try {
+      gitThrow(repoRoot, 'branch', toBranch, fromSha)
+      return { ok: true, fromBranch, toBranch, action: 'created' }
+    } catch (err) {
+      return { ok: false, fromBranch, toBranch, action: 'created', error: 'git branch failed: ' + (err as Error).message }
+    }
+  }
+
+  // Verify the target is an ancestor of the source (a pure fast-forward).
+  try {
+    execFileSync('git', ['-C', repoRoot, 'merge-base', '--is-ancestor', toBranch, fromBranch], { stdio: ['ignore', 'pipe', 'pipe'] })
+  } catch {
+    return { ok: false, fromBranch, toBranch, action: 'fast-forward', error: 'promotion is not a fast-forward: ' + toBranch + ' is not an ancestor of ' + fromBranch }
+  }
+
+  // Apply the fast-forward where it is safe:
+  //  - if the target branch is checked out in a worktree, merge --ff-only there
+  //    (moves the branch AND its working tree forward together, never a merge);
+  //  - otherwise update the branch ref directly.
+  const checkedOutIn = findWorktreeForBranch(repoRoot, toBranch)
+  if (checkedOutIn) {
+    try {
+      gitThrow(checkedOutIn, 'merge', '--ff-only', fromBranch)
+      return { ok: true, fromBranch, toBranch, action: 'fast-forward' }
+    } catch (err) {
+      return { ok: false, fromBranch, toBranch, action: 'fast-forward', error: 'fast-forward merge in ' + checkedOutIn + ' failed: ' + (err as Error).message }
+    }
+  }
+  try {
+    gitThrow(repoRoot, 'update-ref', 'refs/heads/' + toBranch, fromSha)
+    return { ok: true, fromBranch, toBranch, action: 'fast-forward' }
+  } catch (err) {
+    return { ok: false, fromBranch, toBranch, action: 'fast-forward', error: 'git update-ref failed: ' + (err as Error).message }
+  }
+}