@tarcisiopgs/lisa 1.2.0 → 1.3.0

package/dist/index.js

@@ -498,6 +498,21 @@ function registerCleanup() {
   });
 }
 
+// src/pr-body.ts
+function sanitizePrBody(raw) {
+  let text2 = raw.trim();
+  if (!text2) return "";
+  text2 = text2.replace(/<[^>]*>/g, "");
+  text2 = text2.replace(/^(\s*)\* /gm, "$1- ");
+  if (!text2.includes("\n")) {
+    const sentences = text2.match(/[^.!?]+[.!?]+/g);
+    if (sentences && sentences.length > 1) {
+      text2 = sentences.map((s) => `- ${s.trim()}`).join("\n");
+    }
+  }
+  return text2.trim();
+}
+
 // src/prompt.ts
 import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
 import { join, resolve as resolve3 } from "path";
@@ -564,98 +579,17 @@ Do NOT update README.md for:
 If an update is needed, keep the existing README style and structure. Include the README change in the same commit as the implementation.
 `;
 }
-function buildWorktreeMultiRepoPrompt(issue, config2) {
-  const workspace = resolve3(config2.workspace);
-  const repoBlock = config2.repos.map((r) => {
-    const absPath = resolve3(workspace, r.path);
-    return [
-      `- **${r.name}**: \`${absPath}\``,
-      `  - Base branch: \`${r.base_branch}\``,
-      `  - Worktrees dir: \`${join(absPath, ".worktrees")}\``
-    ].join("\n");
-  }).join("\n\n");
-  const readmeBlock = buildReadmeInstructions();
-  const hookBlock = buildPreCommitHookInstructions();
-  const manifestPath = join(workspace, ".lisa-manifest.json");
-  return `You are an autonomous implementation agent working in a multi-repository workspace.
-Your job is to determine the correct repository, create an English-named branch, implement the issue, commit, and write a manifest file.
-
-You are in the workspace: \`${workspace}\`
-
-## Issue
-
-- **ID:** ${issue.id}
-- **Title:** ${issue.title}
-- **URL:** ${issue.url}
-
-### Description
-
-${issue.description}
-
-## Available Repositories
-
-${repoBlock}
-
-## Instructions
-
-1. **Identify the correct repository**: Read the issue title and description carefully.
-   Determine which single repository above is the right target. Consider:
-   - File paths or module names mentioned in the description
-   - Technologies and frameworks referenced
-   - The nature of the change (e.g., API endpoint \u2192 api repo, UI component \u2192 frontend repo)
-
-2. **Choose an English branch name**: Create a slug in English following:
-   \`feat/${issue.id.toLowerCase()}-short-english-description\`
-   The description part MUST be in English regardless of the issue title language.
-   Example: for "${issue.id} Implementar rate limiting na API" \u2192 \`feat/${issue.id.toLowerCase()}-add-rate-limiting-to-api\`
-
-3. **Set up the worktree**: In the chosen repo, run:
-   \`\`\`
-   git fetch origin <base_branch>
-   git worktree add -b <your-english-branch> <repoPath>/.worktrees/<your-english-branch> origin/<base_branch>
-   cd <repoPath>/.worktrees/<your-english-branch>
+function buildPrBodyInstructions() {
+  return `The \`prBody\` MUST follow this exact markdown structure:
    \`\`\`
-
-4. **Implement**: Work inside the worktree. Follow the issue description exactly:
-   - Read all relevant files listed in the description first (if present)
-   - Follow the implementation instructions exactly
-   - Verify each acceptance criteria (if present)
-   - Respect any stack or technical constraints (if present)
-${readmeBlock}${hookBlock}
-5. **Validate**: Run the project's linter/typecheck/tests if available:
-   - Check \`package.json\` for lint, typecheck, check, or test scripts.
-   - Run whichever validation scripts exist (e.g., \`npm run lint\`, \`npm run typecheck\`, \`npm run test\`).
-   - Fix any errors before proceeding.
-
-6. **Commit (do NOT push)**: Make atomic commits with conventional commit messages.
-   Do NOT run \`git push\` \u2014 the caller handles pushing.
-   **IMPORTANT \u2014 Language rules:**
-   - All commit messages MUST be in English.
-   - Use conventional commits format: \`feat: ...\`, \`fix: ...\`, \`refactor: ...\`, \`chore: ...\`
-
-7. **Write the manifest**: After committing, create \`${manifestPath}\` with JSON:
-   \`\`\`json
-   {
-     "repoPath": "<absolute path to the chosen repo>",
-     "branch": "<your English branch name>",
-     "prTitle": "<PR title in English, conventional commit format>",
-     "prBody": "<English summary of what was implemented and why, 2-5 sentences>"
-   }
+   - **What**: one-line summary of the change
+   - **Why**: motivation or issue context
+   - **Key changes**:
+     - \`src/foo.ts\` \u2014 added X functionality
+     - \`src/bar.ts\` \u2014 refactored Y to support Z
+   - **Testing**: what was validated (e.g. "all unit tests pass", "manually tested endpoint")
    \`\`\`
-   The \`prBody\` should describe WHAT was changed and WHY, not just repeat the title. Mention key files modified, new behavior added, or bugs fixed. Write in English.
-   Do NOT commit this file.
-
-## Rules
-
-- **ALL git commits, branch names, PR titles, and PR descriptions MUST be in English.**
-- The issue description may be in any language \u2014 read it for context but write all code artifacts in English.
-- Do NOT push \u2014 the caller handles that.
-- Do NOT create pull requests \u2014 the caller handles that.
-- Do NOT update the issue tracker \u2014 the caller handles that.
-- Do NOT install new dependencies unless the issue explicitly requires it.
-- If you get stuck or the issue is unclear, STOP and explain why.
-- One issue only. Do not pick up additional issues.
-- If the repo has a CLAUDE.md, read it first and follow its conventions.`;
+   Write in English. Do NOT write a wall of text \u2014 structure the summary using the template above.`;
 }
 function buildWorktreePrompt(issue, testRunner) {
   const testBlock = buildTestInstructions(testRunner ?? null);
@@ -701,9 +635,9 @@ ${testBlock}${readmeBlock}${hookBlock}
 
 4. **Write manifest**: Create \`.lisa-manifest.json\` in the **current directory** with JSON:
    \`\`\`json
-   {"branch": "<final English branch name>", "prTitle": "<English PR title, conventional commit format>", "prBody": "<English summary of what was implemented and why, 2-5 sentences>"}
+   {"branch": "<final English branch name>", "prTitle": "<English PR title, conventional commit format>", "prBody": "<markdown-formatted English summary>"}
    \`\`\`
-   The \`prBody\` should describe WHAT was changed and WHY, not just repeat the title. Mention key files modified, new behavior added, or bugs fixed. Write in English.
+   ${buildPrBodyInstructions()}
    Do NOT commit this file.
 
 ## Rules
@@ -771,9 +705,9 @@ ${testBlock}${readmeBlock}${hookBlock}
 
 6. **Write manifest**: Before finishing, create \`${manifestPath}\` with JSON:
    \`\`\`json
-   {"repoPath": "<absolute path to this repo>", "branch": "<branch name>", "prTitle": "<English PR title, conventional commit format>", "prBody": "<English summary of what was implemented and why, 2-5 sentences>"}
+   {"repoPath": "<absolute path to this repo>", "branch": "<branch name>", "prTitle": "<English PR title, conventional commit format>", "prBody": "<markdown-formatted English summary>"}
    \`\`\`
-   The \`prBody\` should describe WHAT was changed and WHY, not just repeat the title. Mention key files modified, new behavior added, or bugs fixed. Write in English.
+   ${buildPrBodyInstructions()}
    Do NOT commit this file.
 
 ## Rules
@@ -814,6 +748,198 @@ ${hookErrors}
 
 Focus only on fixing the hook errors. Do not make unrelated changes.`;
 }
+function buildNativeWorktreePrompt(issue, repoPath, testRunner) {
+  const testBlock = buildTestInstructions(testRunner ?? null);
+  const readmeBlock = buildReadmeInstructions();
+  const hookBlock = buildPreCommitHookInstructions();
+  const prBodyBlock = buildPrBodyInstructions();
+  const manifestLocation = repoPath ? `\`${join(repoPath, ".lisa-manifest.json")}\`` : "`.lisa-manifest.json` in the **current directory**";
+  return `You are an autonomous implementation agent. Your job is to implement a single
+issue, validate it, and commit.
+
+You are working inside a git worktree that was automatically created for this task.
+Work on the current branch \u2014 it was created for you.
+
+## Issue
+
+- **ID:** ${issue.id}
+- **Title:** ${issue.title}
+- **URL:** ${issue.url}
+
+### Description
+
+${issue.description}
+
+## Instructions
+
+1. **Implement**: Follow the issue description exactly:
+   - Read all relevant files listed in the description first (if present)
+   - Follow the implementation instructions exactly
+   - Verify each acceptance criteria (if present)
+   - Respect any stack or technical constraints (if present)
+${testBlock}${readmeBlock}${hookBlock}
+2. **Validate**: Run the project's linter/typecheck/tests if available:
+   - Check \`package.json\` (or equivalent) for lint, typecheck, check, or test scripts.
+   - Run whichever validation scripts exist (e.g., \`npm run lint\`, \`npm run typecheck\`).
+   - Fix any errors before proceeding.
+
+3. **Commit**: Make atomic commits with conventional commit messages.
+   **Branch name must be in English.** If the current branch name contains non-English words,
+   rename it: \`git branch -m <current-name> feat/${issue.id.toLowerCase()}-short-english-slug\`
+   Do NOT push \u2014 the caller handles pushing.
+   **IMPORTANT \u2014 Language rules:**
+   - All commit messages MUST be in English.
+   - Use conventional commits format: \`feat: ...\`, \`fix: ...\`, \`refactor: ...\`, \`chore: ...\`
+
+4. **Write manifest**: Create ${manifestLocation} with JSON:
+   \`\`\`json
+   {"branch": "<final English branch name>", "prTitle": "<English PR title, conventional commit format>", "prBody": "<markdown-formatted English summary>"}
+   \`\`\`
+   ${prBodyBlock}
+   Do NOT commit this file.
+
+## Rules
+
+- **ALL git commits, branch names, PR titles, and PR descriptions MUST be in English.**
+- The issue description may be in any language \u2014 read it for context but write all code artifacts in English.
+- Do NOT push \u2014 the caller handles that.
+- Do NOT install new dependencies unless the issue explicitly requires it.
+- If you get stuck or the issue is unclear, STOP and explain why.
+- One issue only. Do not pick up additional issues.
+- If the repo has a CLAUDE.md, read it first and follow its conventions.
+- Do NOT create pull requests \u2014 the caller handles that.
+- Do NOT update the issue tracker \u2014 the caller handles that.`;
+}
+function buildPlanningPrompt(issue, config2) {
+  const workspace = resolve3(config2.workspace);
+  const repoBlock = config2.repos.map((r) => {
+    const absPath = resolve3(workspace, r.path);
+    return `- **${r.name}**: \`${absPath}\` (base branch: \`${r.base_branch}\`)`;
+  }).join("\n");
+  const planPath = join(workspace, ".lisa-plan.json");
+  return `You are an issue analysis agent. Your job is to read the issue below, determine which repositories are affected, and produce an execution plan.
+
+**Do NOT implement anything.** Only analyze the issue and produce the plan file.
+
+## Issue
+
+- **ID:** ${issue.id}
+- **Title:** ${issue.title}
+- **URL:** ${issue.url}
+
+### Description
+
+${issue.description}
+
+## Available Repositories
+
+${repoBlock}
+
+## Instructions
+
+1. **Analyze the issue**: Read the title and description carefully. Determine which repositories above are affected by this change.
+   Consider:
+   - File paths or module names mentioned in the description
+   - Technologies and frameworks referenced
+   - Dependencies between repos (e.g., backend API changes needed before frontend can consume them)
+
+2. **Determine execution order**: If multiple repos are affected, decide the order. Repos that produce APIs, schemas, or shared libraries should come first. Repos that consume them should come later.
+
+3. **Write the plan**: Create \`${planPath}\` with JSON:
+   \`\`\`json
+   {
+     "steps": [
+       { "repoPath": "<absolute path to repo>", "scope": "<what to implement in this repo>", "order": 1 },
+       { "repoPath": "<absolute path to repo>", "scope": "<what to implement in this repo>", "order": 2 }
+     ]
+   }
+   \`\`\`
+
+## Rules
+
+- Only include repos that are actually affected by the issue. Do NOT include repos that don't need changes.
+- The \`scope\` field should be a concise English description of what needs to be done in that specific repo.
+- Order matters: lower order numbers execute first.
+- Do NOT implement anything. Do NOT create branches, write code, or commit.
+- Do NOT push, create pull requests, or update the issue tracker.
+- If only one repo is affected, the plan should have a single step.`;
+}
+function buildScopedImplementPrompt(issue, step, previousResults, testRunner) {
+  const testBlock = buildTestInstructions(testRunner ?? null);
+  const readmeBlock = buildReadmeInstructions();
+  const hookBlock = buildPreCommitHookInstructions();
+  const prBodyBlock = buildPrBodyInstructions();
+  const previousBlock = previousResults.length > 0 ? `
+## Previous Steps
+
+The following repos have already been implemented as part of this issue:
+
+${previousResults.map((r) => `- **${r.repoPath}**: branch \`${r.branch}\`${r.prUrl ? ` \u2014 PR: ${r.prUrl}` : ""}`).join("\n")}
+
+Use this context if the current step depends on changes from previous steps.
+` : "";
+  return `You are an autonomous implementation agent. Your job is to implement a specific part of an issue in a single repository.
+
+You are working inside a git worktree that was automatically created for this task.
+Work on the current branch \u2014 it was created for you.
+
+## Issue
+
+- **ID:** ${issue.id}
+- **Title:** ${issue.title}
+- **URL:** ${issue.url}
+
+### Description
+
+${issue.description}
+
+## Your Scope
+
+You are responsible for **this specific part** of the issue:
+
+> ${step.scope}
+
+Focus only on this scope. Do NOT implement changes outside this scope.
+${previousBlock}
+## Instructions
+
+1. **Implement**: Follow the scope above. Read the full issue description for context, but only implement what is described in "Your Scope":
+   - Read all relevant files first
+   - Follow the implementation instructions exactly
+   - Verify each acceptance criteria relevant to your scope
+${testBlock}${readmeBlock}${hookBlock}
+2. **Validate**: Run the project's linter/typecheck/tests if available:
+   - Check \`package.json\` (or equivalent) for lint, typecheck, check, or test scripts.
+   - Run whichever validation scripts exist (e.g., \`npm run lint\`, \`npm run typecheck\`).
+   - Fix any errors before proceeding.
+
+3. **Commit**: Make atomic commits with conventional commit messages.
+   **Branch name must be in English.** If the current branch name contains non-English words,
+   rename it: \`git branch -m <current-name> feat/${issue.id.toLowerCase()}-short-english-slug\`
+   Do NOT push \u2014 the caller handles pushing.
+   **IMPORTANT \u2014 Language rules:**
+   - All commit messages MUST be in English.
+   - Use conventional commits format: \`feat: ...\`, \`fix: ...\`, \`refactor: ...\`, \`chore: ...\`
+
+4. **Write manifest**: Create \`.lisa-manifest.json\` in the **current directory** with JSON:
+   \`\`\`json
+   {"branch": "<final English branch name>", "prTitle": "<English PR title, conventional commit format>", "prBody": "<markdown-formatted English summary>"}
+   \`\`\`
+   ${prBodyBlock}
+   Do NOT commit this file.
+
+## Rules
+
+- **ALL git commits, branch names, PR titles, and PR descriptions MUST be in English.**
+- The issue description may be in any language \u2014 read it for context but write all code artifacts in English.
+- Do NOT push \u2014 the caller handles that.
+- Do NOT install new dependencies unless the issue explicitly requires it.
+- If you get stuck or the issue is unclear, STOP and explain why.
+- One scope only. Do not pick up additional work outside your scope.
+- If the repo has a CLAUDE.md, read it first and follow its conventions.
+- Do NOT create pull requests \u2014 the caller handles that.
+- Do NOT update the issue tracker \u2014 the caller handles that.`;
+}
 
 // src/guardrails.ts
 import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "fs";
@@ -986,6 +1112,7 @@ function startOverseer(proc, cwd, config2, getSnapshot = getGitSnapshot) {
 // src/providers/claude.ts
 var ClaudeProvider = class {
   name = "claude";
+  supportsNativeWorktree = true;
   async isAvailable() {
     try {
       execSync("claude --version", { stdio: "ignore" });
@@ -1000,15 +1127,15 @@ var ClaudeProvider = class {
     const promptFile = join3(tmpDir, "prompt.md");
     writeFileSync4(promptFile, prompt, "utf-8");
     try {
-      const proc = spawn2(
-        "sh",
-        ["-c", `claude -p --dangerously-skip-permissions "$(cat '${promptFile}')"`],
-        {
-          cwd: opts.cwd,
-          stdio: ["ignore", "pipe", "pipe"],
-          env: { ...process.env, CLAUDECODE: void 0 }
-        }
-      );
+      const flags = ["-p", "--dangerously-skip-permissions"];
+      if (opts.useNativeWorktree) {
+        flags.push("--worktree");
+      }
+      const proc = spawn2("sh", ["-c", `claude ${flags.join(" ")} "$(cat '${promptFile}')"`], {
+        cwd: opts.cwd,
+        stdio: ["ignore", "pipe", "pipe"],
+        env: { ...process.env, CLAUDECODE: void 0 }
+      });
       const overseer = opts.overseer?.enabled ? startOverseer(proc, opts.cwd, opts.overseer) : null;
       const chunks = [];
       proc.stdout.on("data", (chunk) => {
@@ -1277,6 +1404,7 @@ async function runWithFallback(models, prompt, opts) {
         output: result.output,
         duration: result.duration,
         providerUsed: model,
+        provider,
         attempts
       };
     }
@@ -1302,6 +1430,7 @@ async function runWithFallback(models, prompt, opts) {
         output: result.output,
         duration: result.duration,
         providerUsed: model,
+        provider,
         attempts
       };
     }
@@ -1902,9 +2031,14 @@ function resolveModels(config2) {
 function buildPrBody(providerUsed, description) {
   const lines = [];
   if (description) {
-    lines.push(description, "");
+    const sanitized = sanitizePrBody(description);
+    if (sanitized) {
+      lines.push("## Summary", "", sanitized, "");
+    }
   }
   lines.push(
+    "---",
+    "",
     `Implemented by [lisa](https://github.com/tarcisiopgs/lisa) using **${providerUsed}**.`
   );
   return lines.join("\n");
@@ -1924,6 +2058,22 @@ function cleanupPrTitle(cwd) {
   } catch {
   }
 }
+var PLAN_FILE = ".lisa-plan.json";
+function readLisaPlan(dir) {
+  const planPath = join7(dir, PLAN_FILE);
+  if (!existsSync6(planPath)) return null;
+  try {
+    return JSON.parse(readFileSync5(planPath, "utf-8").trim());
+  } catch {
+    return null;
+  }
+}
+function cleanupPlan(dir) {
+  try {
+    unlinkSync4(join7(dir, PLAN_FILE));
+  } catch {
+  }
+}
 var MANIFEST_FILE = ".lisa-manifest.json";
 function readLisaManifest(dir) {
   const manifestPath = join7(dir, MANIFEST_FILE);
@@ -2269,6 +2419,24 @@ async function runTestValidation(cwd) {
     return false;
   }
 }
+async function findWorktreeForBranch(repoRoot, branch) {
+  try {
+    const { stdout } = await execa3("git", ["worktree", "list", "--porcelain"], { cwd: repoRoot });
+    const lines = stdout.split("\n");
+    let currentPath = null;
+    for (const line of lines) {
+      if (line.startsWith("worktree ")) {
+        currentPath = line.slice("worktree ".length);
+      }
+      if (line.startsWith("branch ") && line.endsWith(`/${branch}`)) {
+        return currentPath;
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
 async function runWorktreeSession(config2, issue, logFile, session, models) {
   if (config2.repos.length > 1) {
     return runWorktreeMultiRepoSession(config2, issue, logFile, session, models);
@@ -2276,6 +2444,140 @@ async function runWorktreeSession(config2, issue, logFile, session, models) {
   const workspace = resolve5(config2.workspace);
   const repoPath = determineRepoPath(config2.repos, issue, workspace) ?? workspace;
   const defaultBranch = resolveBaseBranch(config2, repoPath);
+  const primaryProvider = createProvider(models[0] ?? "claude");
+  const useNativeWorktree = primaryProvider.supportsNativeWorktree === true;
+  if (useNativeWorktree) {
+    return runNativeWorktreeSession(
+      config2,
+      issue,
+      logFile,
+      session,
+      models,
+      repoPath,
+      defaultBranch
+    );
+  }
+  return runManualWorktreeSession(config2, issue, logFile, session, models, repoPath, defaultBranch);
+}
+async function runNativeWorktreeSession(config2, issue, logFile, session, models, repoPath, defaultBranch) {
+  const failResult = (providerUsed, fallback) => ({
+    success: false,
+    providerUsed,
+    prUrls: [],
+    fallback: fallback ?? { success: false, output: "", duration: 0, providerUsed, attempts: [] }
+  });
+  const repo = findRepoConfig(config2, issue);
+  if (repo?.lifecycle) {
+    startSpinner(`${issue.id} \u2014 starting resources...`);
+    const started = await startResources(repo, repoPath);
+    stopSpinner();
+    if (!started) {
+      error(`Lifecycle startup failed for ${issue.id}. Aborting session.`);
+      return failResult(models[0] ?? "claude");
+    }
+  }
+  const testRunner = detectTestRunner(repoPath);
+  if (testRunner) log(`Detected test runner: ${testRunner}`);
+  cleanupManifest(repoPath);
+  const prompt = buildNativeWorktreePrompt(issue, repoPath, testRunner);
+  startSpinner(`${issue.id} \u2014 implementing (native worktree)...`);
+  log(`Implementing with native worktree... (log: ${logFile})`);
+  initLogFile(logFile);
+  const result = await runWithFallback(models, prompt, {
+    logFile,
+    cwd: repoPath,
+    guardrailsDir: repoPath,
+    issueId: issue.id,
+    overseer: config2.overseer,
+    useNativeWorktree: true
+  });
+  stopSpinner();
+  try {
+    appendFileSync6(
+      logFile,
+      `
+${"=".repeat(80)}
+Provider used: ${result.providerUsed}
+Full output:
+${result.output}
+`
+    );
+  } catch {
+  }
+  if (repo?.lifecycle) await stopResources();
+  if (!result.success) {
+    error(`Session ${session} failed for ${issue.id}. Check ${logFile}`);
+    cleanupManifest(repoPath);
+    return { success: false, providerUsed: result.providerUsed, prUrls: [], fallback: result };
+  }
+  const manifest = readLisaManifest(repoPath);
+  if (!manifest?.branch) {
+    error(`Agent did not produce a valid .lisa-manifest.json for ${issue.id}. Aborting.`);
+    cleanupManifest(repoPath);
+    return { success: false, providerUsed: result.providerUsed, prUrls: [], fallback: result };
+  }
+  const effectiveBranch = manifest.branch;
+  ok(`Agent created branch: ${effectiveBranch}`);
+  const worktreePath = await findWorktreeForBranch(repoPath, effectiveBranch);
+  const effectiveCwd = worktreePath ?? repoPath;
+  if (!worktreePath) {
+    warn(`No worktree found for branch ${effectiveBranch} \u2014 using repo root`);
+  }
+  startSpinner(`${issue.id} \u2014 validating tests...`);
+  const testsPassed = await runTestValidation(effectiveCwd);
+  stopSpinner();
+  if (!testsPassed) {
+    error(`Tests failed for ${issue.id}. Blocking PR creation.`);
+    cleanupManifest(repoPath);
+    if (worktreePath) await cleanupWorktree(repoPath, worktreePath);
+    return { success: false, providerUsed: result.providerUsed, prUrls: [], fallback: result };
+  }
+  startSpinner(`${issue.id} \u2014 pushing...`);
+  const pushResult = await pushWithRecovery({
+    branch: effectiveBranch,
+    cwd: effectiveCwd,
+    models,
+    logFile,
+    guardrailsDir: repoPath,
+    issueId: issue.id,
+    overseer: config2.overseer
+  });
+  stopSpinner();
+  if (!pushResult.success) {
+    error(`Failed to push branch to remote: ${pushResult.error}`);
+    cleanupManifest(repoPath);
+    if (worktreePath) await cleanupWorktree(repoPath, worktreePath);
+    return { success: false, providerUsed: result.providerUsed, prUrls: [], fallback: result };
+  }
+  startSpinner(`${issue.id} \u2014 creating PR...`);
+  const prTitle = manifest.prTitle ?? issue.title;
+  const prBody = manifest.prBody;
+  cleanupManifest(repoPath);
+  const prUrls = [];
+  try {
+    const repoInfo = await getRepoInfo(effectiveCwd);
+    const pr = await createPullRequest(
+      {
+        owner: repoInfo.owner,
+        repo: repoInfo.repo,
+        head: effectiveBranch,
+        base: defaultBranch,
+        title: prTitle,
+        body: buildPrBody(result.providerUsed, prBody)
+      },
+      config2.github
+    );
+    ok(`PR created: ${pr.html_url}`);
+    prUrls.push(pr.html_url);
+  } catch (err) {
+    error(`Failed to create PR: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  stopSpinner();
+  if (worktreePath) await cleanupWorktree(repoPath, worktreePath);
+  ok(`Session ${session} complete for ${issue.id}`);
+  return { success: true, providerUsed: result.providerUsed, prUrls, fallback: result };
+}
+async function runManualWorktreeSession(config2, issue, logFile, session, models, repoPath, defaultBranch) {
   const branchName = generateBranchName(issue.id, issue.title);
   startSpinner(`${issue.id} \u2014 creating worktree...`);
   log(`Creating worktree for ${branchName} (base: ${defaultBranch})...`);
@@ -2429,12 +2731,12 @@ ${result.output}
 async function runWorktreeMultiRepoSession(config2, issue, logFile, session, models) {
   const workspace = resolve5(config2.workspace);
   cleanupManifest(workspace);
-  const prompt = buildWorktreeMultiRepoPrompt(issue, config2);
-  startSpinner(`${issue.id} \u2014 implementing...`);
-  log(`Multi-repo worktree session for ${issue.id} (agent selects repo and branch name)`);
-  log(`Implementing (agent selects repo)... (log: ${logFile})`);
+  cleanupPlan(workspace);
+  startSpinner(`${issue.id} \u2014 analyzing issue...`);
+  log(`Multi-repo planning phase for ${issue.id}`);
   initLogFile(logFile);
-  const result = await runWithFallback(models, prompt, {
+  const planPrompt = buildPlanningPrompt(issue, config2);
+  const planResult = await runWithFallback(models, planPrompt, {
     logFile,
     cwd: workspace,
     guardrailsDir: workspace,
@@ -2447,87 +2749,197 @@ async function runWorktreeMultiRepoSession(config2, issue, logFile, session, mod
       logFile,
       `
 ${"=".repeat(80)}
-Provider used: ${result.providerUsed}
-Full output:
-${result.output}
+Planning phase \u2014 provider: ${planResult.providerUsed}
+${planResult.output}
 `
     );
   } catch {
   }
-  if (!result.success) {
-    error(`Session ${session} failed for ${issue.id}. Check ${logFile}`);
-    cleanupManifest(workspace);
-    return { success: false, providerUsed: result.providerUsed, prUrls: [], fallback: result };
+  if (!planResult.success) {
+    error(`Planning phase failed for ${issue.id}. Check ${logFile}`);
+    cleanupPlan(workspace);
+    return {
+      success: false,
+      providerUsed: planResult.providerUsed,
+      prUrls: [],
+      fallback: planResult
+    };
   }
-  const manifest = readLisaManifest(workspace);
-  if (!manifest?.repoPath || !manifest.branch) {
-    error(
-      `Agent did not produce a valid .lisa-manifest.json (requires repoPath + branch) for ${issue.id}. Aborting.`
+  const plan = readLisaPlan(workspace);
+  if (!plan?.steps || plan.steps.length === 0) {
+    error(`Agent did not produce a valid .lisa-plan.json for ${issue.id}. Aborting.`);
+    cleanupPlan(workspace);
+    return {
+      success: false,
+      providerUsed: planResult.providerUsed,
+      prUrls: [],
+      fallback: planResult
+    };
+  }
+  const sortedSteps = [...plan.steps].sort((a, b) => a.order - b.order);
+  ok(
+    `Plan produced ${sortedSteps.length} step(s): ${sortedSteps.map((s) => s.repoPath).join(" \u2192 ")}`
+  );
+  cleanupPlan(workspace);
+  const prUrls = [];
+  const previousResults = [];
+  let lastFallback = planResult;
+  let lastProvider = planResult.providerUsed;
+  for (const [i, step] of sortedSteps.entries()) {
+    const stepNum = i + 1;
+    divider(stepNum);
+    log(`Step ${stepNum}/${sortedSteps.length}: ${step.repoPath} \u2014 ${step.scope}`);
+    const stepResult = await runMultiRepoStep(
+      config2,
+      issue,
+      step,
+      previousResults,
+      logFile,
+      models,
+      stepNum
     );
-    cleanupManifest(workspace);
-    return { success: false, providerUsed: result.providerUsed, prUrls: [], fallback: result };
+    lastFallback = stepResult.fallback;
+    lastProvider = stepResult.providerUsed;
+    if (!stepResult.success) {
+      error(`Step ${stepNum} failed for ${step.repoPath}. Aborting remaining steps.`);
+      return {
+        success: false,
+        providerUsed: lastProvider,
+        prUrls,
+        fallback: lastFallback
+      };
+    }
+    if (stepResult.prUrl) {
+      prUrls.push(stepResult.prUrl);
+    }
+    previousResults.push({
+      repoPath: step.repoPath,
+      branch: stepResult.branch,
+      prUrl: stepResult.prUrl
+    });
   }
-  ok(`Provider chose repo: ${manifest.repoPath}, branch: ${manifest.branch}`);
-  const worktreePath = join7(manifest.repoPath, ".worktrees", manifest.branch);
-  const baseBranch = resolveBaseBranch(config2, manifest.repoPath);
-  const hasWorktree = existsSync6(worktreePath);
-  const effectiveCwd = hasWorktree ? worktreePath : manifest.repoPath;
-  if (!hasWorktree) {
-    warn(`Worktree not found at ${worktreePath} \u2014 using repo root for git operations`);
+  ok(`Session ${session} complete for ${issue.id} \u2014 ${prUrls.length} PR(s) created`);
+  return { success: true, providerUsed: lastProvider, prUrls, fallback: lastFallback };
+}
+async function runMultiRepoStep(config2, issue, step, previousResults, logFile, models, stepNum) {
+  const repoPath = step.repoPath;
+  const defaultBranch = resolveBaseBranch(config2, repoPath);
+  const branchName = generateBranchName(issue.id, issue.title);
+  const failResult = (providerUsed, fallback) => ({
+    success: false,
+    providerUsed,
+    branch: branchName,
+    fallback: fallback ?? { success: false, output: "", duration: 0, providerUsed, attempts: [] }
+  });
+  startSpinner(`${issue.id} step ${stepNum} \u2014 creating worktree...`);
+  let worktreePath;
+  try {
+    worktreePath = await createWorktree(repoPath, branchName, defaultBranch);
+  } catch (err) {
+    stopSpinner();
+    error(`Failed to create worktree: ${err instanceof Error ? err.message : String(err)}`);
+    return failResult(models[0] ?? "claude");
   }
-  startSpinner(`${issue.id} \u2014 validating tests...`);
-  const testsPassed = await runTestValidation(effectiveCwd);
+  stopSpinner();
+  ok(`Worktree created at ${worktreePath}`);
+  const testRunner = detectTestRunner(worktreePath);
+  if (testRunner) log(`Detected test runner: ${testRunner}`);
+  const prompt = buildScopedImplementPrompt(issue, step, previousResults, testRunner);
+  startSpinner(`${issue.id} step ${stepNum} \u2014 implementing...`);
+  const result = await runWithFallback(models, prompt, {
+    logFile,
+    cwd: worktreePath,
+    guardrailsDir: repoPath,
+    issueId: issue.id,
+    overseer: config2.overseer
+  });
+  stopSpinner();
+  try {
+    appendFileSync6(
+      logFile,
+      `
+${"=".repeat(80)}
+Step ${stepNum} \u2014 provider: ${result.providerUsed}
+${result.output}
+`
+    );
+  } catch {
+  }
+  if (!result.success) {
+    error(`Step ${stepNum} implementation failed. Check ${logFile}`);
+    await cleanupWorktree(repoPath, worktreePath);
+    return { ...failResult(result.providerUsed, result), branch: branchName };
+  }
+  const manifest = readLisaManifest(worktreePath);
+  let effectiveBranch = branchName;
+  if (manifest?.branch && manifest.branch !== branchName) {
+    log(`Renaming branch to: ${manifest.branch}`);
+    try {
+      await execa3("git", ["branch", "-m", branchName, manifest.branch], { cwd: worktreePath });
+      effectiveBranch = manifest.branch;
+    } catch (err) {
+      warn(`Branch rename failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  startSpinner(`${issue.id} step ${stepNum} \u2014 validating tests...`);
+  const testsPassed = await runTestValidation(worktreePath);
   stopSpinner();
   if (!testsPassed) {
-    error(`Tests failed for ${issue.id}. Blocking PR creation.`);
-    if (hasWorktree) await cleanupWorktree(manifest.repoPath, worktreePath);
-    cleanupManifest(workspace);
-    return { success: false, providerUsed: result.providerUsed, prUrls: [], fallback: result };
+    error(`Tests failed for step ${stepNum}. Blocking PR creation.`);
+    cleanupManifest(worktreePath);
+    await cleanupWorktree(repoPath, worktreePath);
+    return { ...failResult(result.providerUsed, result), branch: effectiveBranch };
   }
-  startSpinner(`${issue.id} \u2014 pushing...`);
+  startSpinner(`${issue.id} step ${stepNum} \u2014 pushing...`);
   const pushResult = await pushWithRecovery({
-    branch: manifest.branch,
-    cwd: effectiveCwd,
+    branch: effectiveBranch,
+    cwd: worktreePath,
     models,
     logFile,
-    guardrailsDir: manifest.repoPath,
+    guardrailsDir: repoPath,
     issueId: issue.id,
     overseer: config2.overseer
   });
   stopSpinner();
   if (!pushResult.success) {
-    error(`Failed to push branch to remote: ${pushResult.error}`);
-    if (hasWorktree) await cleanupWorktree(manifest.repoPath, worktreePath);
-    cleanupManifest(workspace);
-    return { success: false, providerUsed: result.providerUsed, prUrls: [], fallback: result };
+    error(`Failed to push step ${stepNum}: ${pushResult.error}`);
+    cleanupManifest(worktreePath);
+    await cleanupWorktree(repoPath, worktreePath);
+    return { ...failResult(result.providerUsed, result), branch: effectiveBranch };
   }
-  startSpinner(`${issue.id} \u2014 creating PR...`);
-  const prTitle = manifest.prTitle ?? issue.title;
-  const prBody = manifest.prBody;
-  const prUrls = [];
+  startSpinner(`${issue.id} step ${stepNum} \u2014 creating PR...`);
+  const prTitle = manifest?.prTitle ?? issue.title;
+  const prBody = manifest?.prBody;
+  cleanupManifest(worktreePath);
+  let prUrl;
   try {
-    const repoInfo = await getRepoInfo(effectiveCwd);
+    const repoInfo = await getRepoInfo(worktreePath);
     const pr = await createPullRequest(
       {
         owner: repoInfo.owner,
         repo: repoInfo.repo,
-        head: manifest.branch,
-        base: baseBranch,
+        head: effectiveBranch,
+        base: defaultBranch,
         title: prTitle,
         body: buildPrBody(result.providerUsed, prBody)
       },
       config2.github
     );
     ok(`PR created: ${pr.html_url}`);
-    prUrls.push(pr.html_url);
+    prUrl = pr.html_url;
   } catch (err) {
     error(`Failed to create PR: ${err instanceof Error ? err.message : String(err)}`);
   }
   stopSpinner();
-  cleanupManifest(workspace);
-  if (hasWorktree) await cleanupWorktree(manifest.repoPath, worktreePath);
-  ok(`Session ${session} complete for ${issue.id}`);
-  return { success: true, providerUsed: result.providerUsed, prUrls, fallback: result };
+  await cleanupWorktree(repoPath, worktreePath);
+  ok(`Step ${stepNum} complete: ${repoPath}`);
+  return {
+    success: true,
+    providerUsed: result.providerUsed,
+    branch: effectiveBranch,
+    prUrl,
+    fallback: result
+  };
 }
 async function runBranchSession(config2, issue, logFile, session, models) {
   const workspace = resolve5(config2.workspace);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tarcisiopgs/lisa",
-	"version": "1.2.0",
+	"version": "1.3.0",
 	"description": "Deterministic autonomous issue resolver — structured AI agent loop for Linear/Trello",
 	"license": "MIT",
 	"type": "module",