pi-squad 0.6.5 → 0.14.0

package/src/scheduler.ts

@@ -9,6 +9,8 @@
  * - Detects squad completion
  */
 
+import * as fs from "node:fs";
+import * as path from "node:path";
 import type { AgentDef, Squad, SquadConfig, Task, TaskMessage, TaskStatus } from "./types.js";
 import { AgentPool, type AgentEvent } from "./agent-pool.js";
 import { Monitor } from "./monitor.js";
@@ -16,6 +18,7 @@ import { Router } from "./router.js";
 import * as store from "./store.js";
 import { debug, logError } from "./logger.js";
 import { buildAgentSystemPrompt } from "./protocol.js";
+import { buildAdvisorConsultText, formatAdvisorSteerMessage, adviceNeedsHuman, type AdvisorConsultInput } from "./advisor.js";
 
 // ============================================================================
 // Types
@@ -44,6 +47,16 @@ export interface SchedulerEvent {
 
 export type SchedulerEventListener = (event: SchedulerEvent) => void;
 
+/** Host-session capabilities passed in by the extension (index.ts) */
+export interface SchedulerSpawnContext {
+	/** Resolve a model string (or null = default model) to its context window in tokens */
+	resolveContextWindow?: (model: string | null) => number | undefined;
+	/** Resolve the squad default model/thinking policy (settings.json + main session state) */
+	getDefaultModelThinking?: () => { model?: string; thinking?: string };
+	/** Consult the advisor model with a curated digest. Returns advice text, or null when disabled/unavailable. */
+	consultAdvisor?: (input: AdvisorConsultInput) => Promise<string | null>;
+}
+
 // ============================================================================
 // Scheduler
 // ============================================================================
@@ -55,6 +68,7 @@ export class Scheduler {
 	private router: Router;
 	private listeners: SchedulerEventListener[] = [];
 	private skillPaths: string[] = [];
+	private spawnContext?: SchedulerSpawnContext;
 	private running = false;
 	/** Track spawn retries to allow one retry per task */
 	private spawnRetries = new Set<string>();
@@ -64,9 +78,10 @@ export class Scheduler {
 		return store.loadSquad(this.squadId)?.cwd;
 	}
 
-	constructor(squadId: string, skillPaths: string[]) {
+	constructor(squadId: string, skillPaths: string[], spawnContext?: SchedulerSpawnContext) {
 		this.squadId = squadId;
 		this.skillPaths = skillPaths;
+		this.spawnContext = spawnContext;
 		this.pool = new AgentPool();
 		this.monitor = new Monitor(this.pool, squadId);
 		this.router = new Router(this.pool, squadId);
@@ -81,11 +96,16 @@ export class Scheduler {
 			} else if (action.type === "abort") {
 				this.handleTaskFailed(action.taskId, action.reason);
 			} else if (action.type === "escalate") {
-				this.emit({
-					type: "escalation",
-					squadId: this.squadId,
-					taskId: action.taskId,
-					message: action.reason,
+				// Advisor-first: try a strong-model rescue before interrupting the human
+				void this.tryAdvisorRescue(action.taskId, action.agentName, action.reason).then((rescued) => {
+					if (rescued) return;
+					this.emit({
+						type: "escalation",
+						squadId: this.squadId,
+						taskId: action.taskId,
+						agentName: action.agentName,
+						message: action.reason,
+					});
 				});
 			}
 		});
@@ -248,11 +268,25 @@ export class Scheduler {
 			return;
 		}
 
-		// Apply squad-level model override
+		// Apply squad-level model/thinking overrides
 		const squadAgentEntry = squad.agents[task.agent];
 		if (squadAgentEntry?.model) {
 			agentDef.model = squadAgentEntry.model;
 		}
+		if (squadAgentEntry?.thinking) {
+			agentDef.thinking = squadAgentEntry.thinking;
+		}
+
+		// Apply squad defaults for anything still unset (policy resolved by the
+		// extension host: "main" = main session's model/thinking, "pi-default" =
+		// leave unset, or an explicit value from ~/.pi/squad/settings.json)
+		const defaults = this.spawnContext?.getDefaultModelThinking?.();
+		if (!agentDef.model && defaults?.model) {
+			agentDef.model = defaults.model;
+		}
+		if (!agentDef.thinking && defaults?.thinking) {
+			agentDef.thinking = defaults.thinking;
+		}
 
 		// Build modified files map from all running agents
 		const modifiedFiles: Record<string, string[]> = {};
@@ -285,6 +319,9 @@ export class Scheduler {
 			agentName: task.agent,
 		});
 
+		// Decide whether to fork the main session for context inheritance
+		const forkSessionFile = this.resolveForkSession(task, squad, agentDef);
+
 		try {
 			await this.pool.spawn({
 				taskId: task.id,
@@ -299,6 +336,14 @@ export class Scheduler {
 				},
 				cwd: squad.cwd,
 				skillPaths: this.skillPaths,
+				...(forkSessionFile
+					? {
+							forkSession: {
+								file: forkSessionFile,
+								sessionDir: path.join(store.getSquadDir(this.squadId), "sessions"),
+							},
+						}
+					: {}),
 			});
 		} catch (error) {
 			this.handleTaskFailed(task.id, (error as Error).message);
@@ -307,6 +352,123 @@ export class Scheduler {
 		this.updateContext();
 	}
 
+	/** Advisor consultations per task (advisor-first escalation) */
+	private advisorAttempts = new Map<string, number>();
+
+	/**
+	 * Consult the advisor for a stuck agent and steer it with the advice.
+	 * Returns true when the agent was steered (escalation suppressed).
+	 * Returns false when the advisor is disabled, exhausted, unavailable,
+	 * failed, or explicitly said the problem needs human input.
+	 */
+	private async tryAdvisorRescue(taskId: string, agentName: string | undefined, reason: string): Promise<boolean> {
+		try {
+			const consult = this.spawnContext?.consultAdvisor;
+			if (!consult) return false;
+
+			const settings = store.loadSquadSettings();
+			if (!settings.advisor.enabled) return false;
+
+			const attempts = this.advisorAttempts.get(taskId) || 0;
+			if (attempts >= settings.advisor.maxCallsPerTask) {
+				debug("squad-advisor", `${taskId}: advisor exhausted (${attempts}/${settings.advisor.maxCallsPerTask}), escalating`);
+				return false;
+			}
+			if (!this.pool.isRunning(taskId)) return false;
+
+			const task = store.loadTask(this.squadId, taskId);
+			const squad = store.loadSquad(this.squadId);
+			if (!task || !squad) return false;
+			const agentDef = store.loadAgentDef(task.agent, squad.cwd);
+			const activity = this.pool.getActivity(taskId);
+
+			this.advisorAttempts.set(taskId, attempts + 1);
+
+			const input: AdvisorConsultInput = {
+				taskId,
+				taskTitle: task.title,
+				taskDescription: task.description,
+				agentName: task.agent,
+				agentRole: agentDef?.role || task.agent,
+				reason,
+				recentMessages: store.loadMessages(this.squadId, taskId).slice(-12).map((m) => ({ from: m.from, type: m.type, text: m.text })),
+				recentToolCalls: activity ? [...activity.recentToolCalls] : [],
+				turnCount: activity?.turnCount || 0,
+				elapsedMinutes: activity ? (Date.now() - activity.startedAt) / 60000 : 0,
+			};
+
+			const advice = await consult(input);
+			if (!advice) return false;
+
+			store.appendMessage(this.squadId, taskId, {
+				ts: store.now(),
+				from: "advisor",
+				type: "message",
+				text: advice,
+			});
+
+			// Advisor says a human decision is required — escalate with the advice attached
+			if (adviceNeedsHuman(advice)) {
+				this.emit({
+					type: "escalation",
+					squadId: this.squadId,
+					taskId,
+					agentName,
+					message: `${reason}\n\nAdvisor assessment:\n${advice.slice(0, 800)}`,
+				});
+				return true; // escalation already emitted with richer context
+			}
+
+			const delivered = await this.pool.steer(taskId, formatAdvisorSteerMessage(advice, reason));
+			debug("squad-advisor", `${taskId}: advisor steered agent (attempt ${attempts + 1}, delivered=${delivered})`);
+			return delivered;
+		} catch (error) {
+			logError("squad-advisor", `rescue failed for ${taskId}: ${(error as Error).message}`);
+			return false;
+		}
+	}
+
+	/**
+	 * Decide whether this task's agent should be spawned as a fork of the main
+	 * pi session (context inheritance). Guards against blowing the child model's
+	 * context window: forks only when the estimated session tokens fit within
+	 * 50% of the agent model's context window.
+	 */
+	private resolveForkSession(task: Task, squad: Squad, agentDef: AgentDef): string | undefined {
+		if (!task.inheritContext) return undefined;
+
+		const skip = (reason: string): undefined => {
+			logError("squad-scheduler", `inheritContext skipped for ${task.id}: ${reason}`);
+			store.appendMessage(this.squadId, task.id, {
+				ts: store.now(),
+				from: "system",
+				type: "status",
+				text: `Context inheritance skipped: ${reason}. Agent starts with standard squad context only.`,
+			});
+			return undefined;
+		};
+
+		const sessionFile = squad.sessionFile;
+		if (!sessionFile) return skip("main session has no session file (ephemeral --no-session run)");
+		if (!fs.existsSync(sessionFile)) return skip(`session file not found: ${sessionFile}`);
+
+		// Rough token estimate: JSONL bytes / 4. Overestimates (JSON overhead), which is safe.
+		const estTokens = Math.ceil(fs.statSync(sessionFile).size / 4);
+
+		const window = this.spawnContext?.resolveContextWindow?.(agentDef.model ?? null);
+		if (!window) {
+			return skip(`cannot determine context window for model "${agentDef.model || "(default)"}"`);
+		}
+		if (estTokens > window * 0.5) {
+			return skip(
+				`estimated session context (~${Math.round(estTokens / 1000)}k tokens) exceeds 50% of ${agentDef.model || "default model"}'s ${Math.round(window / 1000)}k window — restate key context in the task description instead`,
+			);
+		}
+
+		debug("squad-scheduler", `inheritContext: forking ${sessionFile} for ${task.id} (~${Math.round(estTokens / 1000)}k tokens, window ${Math.round(window / 1000)}k)`);
+		return sessionFile;
+	}
+
 	// =========================================================================
 	// Event Handlers
 	// =========================================================================
@@ -463,10 +625,6 @@ export class Scheduler {
 			text: "Task completed",
 		});
 
-		// Reload task after status update so overview has output, completed time, etc.
-		const updatedTask = store.loadTask(this.squadId, taskId) || task;
-		this.appendTaskOverview(updatedTask, taskId, messages);
-
 		this.emit({
 			type: "task_completed",
 			squadId: this.squadId,
@@ -603,7 +761,7 @@ export class Scheduler {
 	 */
 	private checkForRework(task: Task, output: string): boolean {
 		// Only trigger rework for QA/test agent tasks
-		const qaAgents = ["qa", "tester", "security"];
+		const qaAgents = ["qa", "tester", "security", "reviewer"];
 		if (!qaAgents.includes(task.agent)) return false;
 
 		// Parse verdict from output
@@ -614,7 +772,7 @@ export class Scheduler {
 		const allTasks = store.loadAllTasks(this.squadId);
 		const implDeps = task.depends
 			.map((depId) => allTasks.find((t) => t.id === depId))
-			.filter((t): t is Task => t !== null && !qaAgents.includes(t.agent));
+			.filter((t): t is Task => t !== undefined && !qaAgents.includes(t.agent));
 
 		if (implDeps.length === 0) return false;
 
@@ -653,6 +811,7 @@ export class Scheduler {
 				agent: implTask.agent,
 				status: "pending",
 				depends: [],
+				...(implTask.inheritContext ? { inheritContext: true } : {}),
 				created: store.now(),
 				started: null,
 				completed: null,
@@ -943,88 +1102,6 @@ export class Scheduler {
 		return textParts.length > 0 ? textParts.join("\n") : null;
 	}
 
-	// =========================================================================
-	// Overview Document — append task summary after completion
-	// =========================================================================
-
-	/**
-	 * Build a concise markdown summary of a completed task and append it
-	 * to the squad's OVERVIEW.md. This gives subsequent agents a narrative
-	 * understanding of what was accomplished, issues hit, and decisions made.
-	 */
-	private appendTaskOverview(
-		task: Task,
-		taskId: string,
-		messages: import("./types.js").TaskMessage[],
-	): void {
-		try {
-			const lines: string[] = [];
-
-			// Header
-			lines.push(`## ${task.id}: ${task.title}`);
-			lines.push(``);
-			lines.push(`**Agent:** ${task.agent} | **Status:** ${task.status}`);
-			if (task.started && task.completed) {
-				const dur = new Date(task.completed).getTime() - new Date(task.started).getTime();
-				lines.push(`**Duration:** ${formatElapsed(dur)}`);
-			}
-			lines.push(``);
-
-			// Output
-			if (task.output) {
-				lines.push(`### Output`);
-				lines.push(task.output.slice(0, 800));
-				if (task.output.length > 800) lines.push(`... (truncated)`);
-				lines.push(``);
-			}
-
-			// Issues / errors encountered
-			const errors = messages.filter((m) => m.type === "error" && m.from !== "system");
-			if (errors.length > 0) {
-				lines.push(`### Issues Encountered`);
-				for (const err of errors.slice(-5)) {
-					lines.push(`- ${err.text.split("\n")[0].slice(0, 200)}`);
-				}
-				lines.push(``);
-			}
-
-			// Decisions — scan agent text for decision-like language
-			const decisionPatterns = /\b(decided|chose|approach|instead of|trade-?off|opted|going with|switched to|using .+ because)\b/i;
-			const agentTexts = messages.filter((m) => m.from === task.agent && m.type === "text");
-			const decisions: string[] = [];
-			for (const msg of agentTexts) {
-				for (const line of msg.text.split("\n")) {
-					if (decisionPatterns.test(line) && line.trim().length > 10) {
-						decisions.push(line.trim().slice(0, 200));
-					}
-				}
-			}
-			if (decisions.length > 0) {
-				lines.push(`### Decisions`);
-				for (const d of decisions.slice(-5)) {
-					lines.push(`- ${d}`);
-				}
-				lines.push(``);
-			}
-
-			// Files modified
-			const activity = this.pool.getActivity(taskId);
-			if (activity && activity.modifiedFiles.size > 0) {
-				lines.push(`### Files Modified`);
-				for (const f of Array.from(activity.modifiedFiles).slice(0, 15)) {
-					lines.push(`- ${f}`);
-				}
-				if (activity.modifiedFiles.size > 15) {
-					lines.push(`- ... and ${activity.modifiedFiles.size - 15} more`);
-				}
-				lines.push(``);
-			}
-
-			store.appendOverview(this.squadId, lines.join("\n"));
-		} catch (err) {
-			logError("squad-scheduler", `Failed to append overview for ${taskId}: ${(err as Error).message}`);
-		}
-	}
 }
 
 function formatElapsed(ms: number): string {

package/src/skills/squad-architecture/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: squad-architecture
+description: >
+  System architecture practices — project structure, API contracts, shared types,
+  monorepo setup, and technical decision documentation. Use when designing system
+  architecture, defining contracts between components, or setting up project structure.
+version: 1.0.0
+---
+
+# Architecture & System Design
+
+## Project Structure
+- Define clear boundaries between components (backend, frontend, shared)
+- Use a monorepo with workspaces when frontend and backend share types
+- Create a shared types/constants package that both sides import
+- Document the project structure in a README or ARCHITECTURE.md
+
+## API Contract Definition
+When defining API contracts that other agents will implement:
+- List EVERY endpoint with method, path, request body, and response shape
+- Specify exact field names, types, and which fields are optional
+- Define error response format consistently
+- Specify authentication requirements per endpoint
+- Include example request/response pairs
+
+Example:
+```
+POST /api/auth/login
+  Request:  { email: string, password: string }
+  Response: { user: { id, email, name }, accessToken: string, refreshToken: string }
+  Errors:   401 { error: "Invalid credentials" }
+```
+
+## Shared Types
+- Define TypeScript interfaces for all data models
+- Include validation schemas (zod) alongside types
+- Export constants (status enums, priority levels, config values)
+- Version the shared package so consumers know when contracts change
+
+## Technical Decisions
+Document every significant decision in your output:
+- What was decided and why
+- What alternatives were considered
+- What trade-offs were accepted
+
+This helps downstream agents understand the rationale and stay consistent.
+
+## Handoff Quality
+Your output is the contract that all other agents build against. Be precise:
+- Don't leave ambiguity in field names or types
+- Specify exact port numbers, file paths, directory structure
+- Include the database schema with column types and constraints
+- List all environment variables needed

package/src/skills/squad-backend-dev/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: squad-backend-dev
+description: >
+  Backend engineering practices — API design, database patterns, auth implementation,
+  input validation, error handling, and security. Use when building APIs, servers,
+  databases, or backend services.
+version: 1.0.0
+---
+
+# Backend Development
+
+## API Design
+- RESTful conventions: GET (read), POST (create), PUT (replace), PATCH (update), DELETE (remove)
+- Consistent response format: success returns data directly, errors return `{ error: string, code?: string }`
+- Validate all inputs at the boundary (use zod, joi, or manual checks)
+- Paginate list endpoints (limit/offset or cursor-based)
+- Use proper HTTP status codes: 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 500 Server Error
+- Document every endpoint in your completion output (method, path, request/response shape)
+
+## Database
+- Use migrations for schema changes (never ALTER in application code)
+- Add indexes for frequently queried columns and foreign keys
+- Use foreign keys with appropriate ON DELETE behavior (CASCADE, SET NULL)
+- Use transactions for multi-step writes
+- Sanitize all user inputs in queries (parameterized queries, never string interpolation)
+
+## Authentication
+- Never store passwords in plain text — use bcrypt with sufficient rounds (10+)
+- JWT access tokens: short-lived (15min), stateless verification
+- Refresh tokens: longer-lived (7d), stored server-side, rotated on use
+- Validate tokens on every protected endpoint via middleware
+- Return 401 for invalid/expired tokens, 403 for insufficient permissions
+
+## Error Handling
+- Catch errors at route level, don't let unhandled rejections crash the server
+- Log errors with context (request id, user id, endpoint)
+- Never expose stack traces or internal details in API responses
+- Use typed error classes for different error categories
+- Implement graceful shutdown (close DB connections, finish in-flight requests)
+
+## Security
+- Rate-limit public endpoints (login, register, password reset)
+- Set security headers (CORS, Helmet for Express)
+- Validate file uploads (type whitelist, size limits)
+- Never log sensitive data (passwords, tokens, PII)

package/src/skills/squad-code-review/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: squad-code-review
+description: >
+  Code review methodology — two-pass review (correctness/scope, then
+  over-engineering), surgical-change discipline, complexity findings with
+  delete/stdlib/native/yagni/shrink tags, machine-parsed verdicts. Use when
+  reviewing diffs, implementations, or pull requests.
+version: 1.0.0
+---
+
+# Code Review
+
+Two passes, in order. Findings from pass 1 gate the verdict; pass 2 findings
+are usually non-blocking. Derived from the karpathy-guidelines and ponytail
+review disciplines.
+
+## Pass 1 — Correctness & Scope
+
+**Every changed line must trace to the task.**
+- Flag unrequested refactors, drive-by "improvements", formatting churn in
+  untouched code, and deleted code the task didn't ask to remove
+- Orphan check: did the change leave now-unused imports/variables/functions
+  it created? (Pre-existing dead code is a mention, not a finding)
+
+**Verify with evidence, not by reading.**
+- Run the task's Verify criterion yourself (tests, build, curl). Your review
+  is only as strong as the commands you ran
+- Reproduce at least one happy path and one failure path where practical
+- If you can't run something, say so explicitly — don't imply you did
+
+**Assumptions and interpretations.**
+- If the implementation silently picked one of several readings of the task,
+  name the choice and whether it matches the task's Goal/Boundaries
+- Check the task's Boundaries were respected (unchanged APIs, schemas, configs)
+
+**Error handling in the right places.**
+- Trust boundaries (user input, network, file I/O) must handle failure
+- Impossible-scenario handling is noise — flag it in pass 2 as yagni
+
+## Pass 2 — Complexity Hunt
+
+Climb the ladder for each addition; stop at the first rung that holds:
+need to exist? → already in codebase? → stdlib? → native platform? →
+installed dep? → one line? → minimum that works.
+
+One line per finding — location, what to cut, what replaces it:
+
+- `delete:` dead code, unused flexibility, speculative feature → nothing
+- `stdlib:` hand-rolled thing the standard library ships → name the function
+- `native:` dep/code doing what the platform does → name the feature
+- `yagni:` abstraction with one implementation, config nobody sets, layer with one caller
+- `shrink:` same logic, fewer lines → show the shorter form
+
+Example: `api.ts:L88: yagni: RepositoryFactory with one product. Inline it until a second exists.`
+
+**Never flag as bloat**: trust-boundary validation, data-loss handling,
+security, accessibility, or a minimal test. Lean is not careless.
+
+If nothing to cut: `Lean already.` — don't invent findings to look thorough.
+
+## Verdict (machine-parsed — REQUIRED)
+
+End your final message with exactly:
+
+```
+## Verdict: PASS | FAIL | PASS WITH ISSUES
+
+## Issues
+1. **[file:line]** (Critical/High/Medium/Low) description
+   - Expected: X
+   - Got: Y
+   - Fix: specific change
+
+## Evidence
+[commands run + output]
+```
+
+- **FAIL**: pass-1 problems (correctness, scope violations, broken Verify).
+  Creates a rework task — the fixer only sees your Issues section
+- **PASS WITH ISSUES**: works and in-scope, but pass-2 cuts are worth making
+- **PASS**: correct, in scope, lean. Say what you verified
+- Severity: correctness/security → Critical/High; complexity → Medium/Low
+- Do not rename the sections — `## Issues` is extracted verbatim as fix feedback
+
+## You Don't Fix
+
+You report; the squad routes fixes to the original agent. Applying fixes
+yourself would bypass the rework loop and confuse file ownership. If a fix
+is truly one character, still report it — with the exact edit in the Fix line.

package/src/skills/{collaboration → squad-collaboration}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: collaboration
+name: squad-collaboration
 description: Multi-agent collaboration patterns — how to build on others' work, ask questions, share knowledge, and work as a team.
 ---
 
@@ -22,10 +22,14 @@ Bad: "@backend FYI I'm working on the frontend" (no question, wastes their time)
 Don't just post conclusions. Explain why you made a choice, so others can course-correct early.
 "I chose RS256 over HS256 because the frontend needs to verify tokens without the signing secret"
 
-## Admit uncertainty
+## Admit uncertainty — flag gaps, never guess
 If you're not sure about something, say so and ask.
 "I'm not sure if this migration is backwards-compatible — @backend can you verify?"
 
+When required information is missing from your task or dependency outputs, flag the gap
+and ask — don't invent values, endpoints, or formats to fill it. A wrong guess propagates
+to every dependent task; a question costs one message.
+
 Better to ask than to silently introduce a breaking change.
 
 ## Respond when asked

package/src/skills/squad-debugging/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: squad-debugging
+description: >
+  Debugging and rework discipline — reproduce-first workflow, hypothesis testing,
+  minimal fixes, regression tests. Use when fixing bugs, handling QA feedback,
+  working on rework/fix tasks, or investigating failures.
+version: 1.0.0
+---
+
+# Debugging & Rework
+
+## The Iron Rule: Reproduce First
+
+Never change code before you've seen the failure with your own eyes.
+
+1. **REPRODUCE**: Run the failing test, repro steps, or command from the QA
+   feedback. Confirm you see the same failure. If you can't reproduce it,
+   say so explicitly — don't "fix" what you can't observe.
+2. **LOCALIZE**: Read the error, stack trace, or diff. Form ONE hypothesis
+   about the cause. State it before changing anything.
+3. **FIX**: Make the smallest change that addresses the hypothesized cause.
+4. **VERIFY**: Re-run the exact reproduction from step 1 — it must now pass.
+   Then run the surrounding test suite to catch regressions.
+5. **PROTECT**: Add a regression test if none exists for this failure mode.
+
+## Hypothesis Discipline
+
+- One hypothesis at a time. If the fix doesn't work, REVERT it before trying
+  the next hypothesis — never stack speculative changes
+- If two hypotheses fail, stop and gather more evidence (add logging, isolate
+  with a minimal test case) instead of guessing a third time
+- Distinguish "the symptom moved" from "the cause is fixed" — re-run the
+  ORIGINAL repro, not just your new test
+
+## Rework Tasks (QA sent your work back)
+
+- Fix ONLY the issues listed in the QA feedback — no rewrites, no opportunistic
+  refactoring, no unrelated improvements
+- Reproduce each reported issue before touching code (the feedback includes
+  Expected/Got/Repro for each — use them)
+- If a reported issue looks wrong or is not reproducible, say so explicitly
+  with evidence instead of silently skipping it
+- Your completion message must show each issue → what changed → re-run evidence
+
+## Common Traps
+
+- **Fixing the test instead of the code** — only adjust a test when you can
+  argue the test itself was wrong, and say so
+- **Shotgun debugging** — many small changes at once; you won't know which
+  one mattered and you'll introduce new breakage
+- **Environment blame** — "works on my machine" requires evidence: show the
+  environment difference, don't assume it
+- **Silent scope creep** — noticing other bugs is good; fixing them inside a
+  rework task is not. Mention them so the squad can create tasks
+
+## Output Checklist
+
+Your completion message must include:
+1. Each issue: root cause (one sentence) + the fix (file:line)
+2. Evidence: the original failing command now passing (actual output)
+3. Regression scope: which suites you ran and their results