@kendoo.agentdesk/agentdesk 0.29.3 → 0.31.0

package/CHANGELOG.md

@@ -8,6 +8,23 @@ All user-facing changes to AgentDesk. Each entry is tagged:
 
 Internal refactors, infrastructure changes, and architectural notes are not listed here.
 
+## [0.31.0] — 2026-09-21
+
+### Changed
+- `[CLI]` The team now follows the task. `INTAKE` assesses the scope — `small` or `standard`, and which areas the change touches (UI, copy, docs, API, data). A small task skips `PLAN` (Dennis states the approach at the start of `EXECUTION`) and is reviewed by Bart and Vera; Sam's architecture audit still gates the PR. Luna, Mark and Nora join only when the task touches their area, and the phase instructions only name the agents who are actually on the team. Set `"teamProfile": "small"` or `"standard"` in `.agentdesk.json` to force it.
+- `[CLI]` The engine keeps a handoff ledger (`.agentdesk/handoffs.jsonl`): one record per phase run with the commit before and after, the phase's output, the verification evidence and what is still open. Unresolved findings and deferred items are carried into the next phase's prompt as open items, so nothing is quietly dropped or quietly picked up.
+- `[CLI]` An `EXECUTION` that reports implemented work without making a commit is now flagged to the reviewers and in the session feed.
+
+### Fixed
+- `[CLI]` The engine's own runtime files (`.agentdesk/`, `.agentdesk-resume.md`) no longer count as uncommitted changes when deciding whether a tree is clean.
+
+## [0.30.0] — 2026-09-21
+
+### Changed
+- `[CLI]` A review approval now refers to one verified commit. Before the reviewers are asked, the engine itself runs the project's `test`/`build`/`lint` commands (from project settings, or the `package.json` scripts) inside the session sandbox. A failing check goes straight back to EXECUTION with the real output as findings; the reviewers only see work whose checks pass, and their prompt shows what the engine observed. If the code changes after an approval, the approval no longer counts and the session ends for human review instead of reporting success. In a session worktree, uncommitted changes block review.
+- `[CLI]` The SUMMARY phase is now enforced read-only: it can no longer edit files, commit, move `HEAD`, push, or open a PR.
+- `[UI]` The session feed shows each verification command the engine ran and its result.
+
 ## [0.29.3] — 2026-09-21
 
 ### Fixed

package/README.md

@@ -265,6 +265,12 @@ Valid values: `"default"`, `"opus"`, `"sonnet"`, `"haiku"`. `"default"` resolves
 
 The `REVIEW` phase is a read-only completeness check (no code changes) — it verifies the implementation meets requirements, flags missed documentation updates or silently-deferred scope. If gaps are found, the orchestrator loops back to `EXECUTION` once before moving on. The `SUMMARY` phase writes the final tracker comments and session protocol.
 
+Before the reviewers are asked, the engine runs the project's own checks itself — `commands.test`, `commands.build` and `commands.lint` from project settings, or the `test`/`build`/`lint` scripts in `package.json` when those are unset — inside the session sandbox, at the current commit. A failing check goes straight back to `EXECUTION` with the real output as findings; the reviewers are only asked once the checks pass. An approval is pinned to that commit: if the code changes afterwards, the approval no longer counts and the session ends for human review instead of reporting success. In a session worktree, uncommitted changes block review too — an approval refers to a committed revision. `SUMMARY` cannot commit, move `HEAD`, or push; it writes messages only.
+
+The team follows the task. `INTAKE` assesses the scope — `small` or `standard`, and which areas the change touches (`ui`, `copy`, `docs`, `api`, `data`). A small task skips `PLAN` (Dennis states the approach at the start of `EXECUTION`) and is reviewed by Bart and Vera; Sam's architecture audit still gates the PR inside `EXECUTION`. Luna, Mark and Nora join only when the task touches UI, user-facing copy or docs respectively. Set `"teamProfile": "small"` or `"standard"` in `.agentdesk.json` to force it (`"auto"`, the default, lets `INTAKE` decide).
+
+Every phase run is also recorded by the engine in `.agentdesk/handoffs.jsonl` (revision before and after, the phase's structured output, the verification evidence, and what is still open). Unresolved findings and deferred items are carried into the next phase's prompt as open items, and an `EXECUTION` that reports work without making a commit is flagged to the reviewers.
+
 ## How It Works
 
 All agents collaborate in a single Claude process — each with distinct roles, ground rules, and areas of expertise.
@@ -317,7 +323,7 @@ Once running, a "Run Team" button appears on [agentdesk.live](https://agentdesk.
 - **Credentials prerequisite** — scoped sessions push code over HTTPS using a per-project GitHub token. `agentdesk init` saves it to the project's `.env` as `GITHUB_TOKEN`; if you skip that step, the session refuses to start with an actionable message. SSH-only remotes (`git@github.com:...`) are also rejected — the sandbox intentionally isolates `~/.ssh`. Switch the origin to `https://github.com/<owner>/<repo>.git` or run without scoped isolation.
 - **Outbound only** — no ports opened on your machine
 - **Project allowlist** — only runs on projects registered via `agentdesk init`
-- **No arbitrary commands** — only spawns Claude with a fixed set of allowed tools
+- **No arbitrary commands** — spawns Claude with a fixed set of allowed tools, plus the project's own configured `test`/`build`/`lint` commands (run inside the same sandbox, before each review) — nothing the server can push
 - **Metadata-only logs** — session logs in `~/.agentdesk/logs/` contain timestamps and file paths, never sensitive data
 - **Fail closed** — unknown projects or exceeded session limits are rejected
 

package/cli/config.mjs

@@ -27,6 +27,11 @@ const DEFAULTS = {
   // Missing entry or "default" falls back to the phase default
   // (sonnet for INTAKE/PLAN/EXECUTION, haiku for REVIEW/SUMMARY).
   phaseModels: {},
+  // Team composition: "auto" lets INTAKE assess the task (small tasks skip
+  // PLAN and run with implementer + reviewers; specialists join only for the
+  // areas the task touches); "small" | "standard" force it. Local-only for
+  // now — not synced to the server.
+  teamProfile: "auto",
   instructions: null,
   // Optional display name shown wherever AgentDesk identifies itself (UI,
   // future tracker-comment prefixes). Leave null to fall back to agent

package/cli/engine/agents/index.mjs

@@ -29,6 +29,27 @@ export const PHASE_ROSTER = Object.freeze({
   SUMMARY:   { Dennis: RO_BASH },
 });
 
+// Specialists join only when INTAKE says the task touches their area.
+export const SPECIALISTS = Object.freeze({ Luna: "ui", Mark: "copy", Nora: "docs" });
+// A small task is reviewed by the QA and test engineers; the architecture
+// audit still gates publishing inside EXECUTION.
+const SMALL_REVIEW = Object.freeze(["Bart", "Vera"]);
+
+// The built-in roster for one phase under a team profile (team-profile.mjs).
+// No profile means the legacy full roster.
+export function rosterFor(phase, profile = null) {
+  const base = PHASE_ROSTER[phase] || {};
+  if (!profile) return base;
+  const touches = Array.isArray(profile.touches) ? profile.touches : [];
+  const roster = {};
+  for (const [name, tools] of Object.entries(base)) {
+    if (SPECIALISTS[name] && !touches.includes(SPECIALISTS[name])) continue;
+    if (profile.size === "small" && phase === "REVIEW" && !SMALL_REVIEW.includes(name)) continue;
+    roster[name] = tools;
+  }
+  return roster;
+}
+
 // Phases where project-defined custom agents (config.projectAgents) join.
 const CUSTOM_AGENT_PHASES = new Set(["PLAN", "EXECUTION"]);
 
@@ -108,9 +129,10 @@ export function soloDefinition(agent) {
 // team        — resolveTeam(config) output (array of { name, role, description, ... })
 // phase       — one of PHASES
 // phaseModels — config.phaseModels
+// profile     — teamProfileFor() output; omitted → the full roster
 // Returns { agents: Record<name, AgentDefinition>, allowedTools: string[], lead: "Jane" }
-export function agentsForPhase({ phase, team, phaseModels = {} }) {
-  const roster = PHASE_ROSTER[phase] || {};
+export function agentsForPhase({ phase, team, phaseModels = {}, profile = null }) {
+  const roster = rosterFor(phase, profile);
   const subagentModel = (phase === "REVIEW" || phase === "SUMMARY") ? modelForPhase(phase, phaseModels) : "inherit";
 
   const agents = {};

package/cli/engine/evidence.mjs

@@ -0,0 +1,193 @@
+// The engine's own evidence for an approval.
+//
+// REVIEW's verdict is an agent's structured claim. Before the engine asks for
+// that claim it runs the project's own checks (test/build/lint) at a known
+// revision, and afterwards it only accepts "APPROVED" if the checks passed and
+// the code has not moved since. Discipline belongs in the system; judgement
+// belongs with the agents.
+//
+// Pure decisions (resolveChecks, evaluateApproval, evidenceFindings, the
+// renderers) are unit-tested without spawning anything. runChecks takes an
+// injectable runner so the session loop is testable with scripted results.
+
+import { execFileSync, spawn } from "node:child_process";
+import { killTree } from "../proc.mjs";
+
+export const ENGINE_REVIEWER = "AgentDesk";
+export const CHECK_ORDER = Object.freeze(["test", "build", "lint"]);
+export const DEFAULT_CHECK_TIMEOUT_MS = 15 * 60 * 1000;
+export const OUTPUT_TAIL_BYTES = 4096;
+
+export const shortRev = revision => String(revision || "").slice(0, 7);
+
+// config.commands.{test,build,lint} win; the project's detected commands fill
+// the gaps; a slot with neither is simply not a check.
+export function resolveChecks({ config = {}, project = {} } = {}) {
+  const detected = { test: project.testCommand, build: project.buildCommand, lint: project.lintCommand };
+  const checks = [];
+  for (const name of CHECK_ORDER) {
+    const configured = config.commands?.[name];
+    const command = typeof configured === "string" && configured.trim() ? configured.trim() : (detected[name] || null);
+    if (command) checks.push({ name, command });
+  }
+  return checks;
+}
+
+export function checkTimeoutMs(config = {}) {
+  const v = Number(config.checkTimeoutMs);
+  return Number.isFinite(v) && v > 0 ? v : DEFAULT_CHECK_TIMEOUT_MS;
+}
+
+// Worktree sessions commit into a private Git dir (worktree-git.mjs); the
+// engine must look where the agents commit, so the session's GIT_* env is
+// overlaid on a scrubbed environment.
+function gitEnv(extra = {}) {
+  const env = { ...process.env, GIT_TERMINAL_PROMPT: "0", GIT_CONFIG_NOSYSTEM: "1", GIT_CONFIG_GLOBAL: "/dev/null" };
+  for (const key of Object.keys(env)) if (/^GIT_(DIR|WORK_TREE|COMMON_DIR|INDEX_FILE|OBJECT_DIRECTORY|ALTERNATE_OBJECT_DIRECTORIES|CONFIG_COUNT|CONFIG_KEY_\d+|CONFIG_VALUE_\d+|CONFIG_PARAMETERS)$/.test(key)) delete env[key];
+  return { ...env, ...extra };
+}
+
+function git(cwd, args, extra) {
+  return execFileSync("git", args, { cwd, env: gitEnv(extra), encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 30000 }).trim();
+}
+
+// The engine's own runtime files (session memory, ledger, findings, resume
+// note) live inside the project when no worktree is used. They are never the
+// agents' uncommitted work and must not make a tree look dirty.
+const ENGINE_FILES = /(^|\/)(\.agentdesk\/|\.agentdesk-resume\.md$)/;
+function isEngineFile(statusLine) {
+  return ENGINE_FILES.test(statusLine.slice(3).replace(/^"|"$/g, ""));
+}
+
+// Independent lookups: a repository with an unborn branch has no HEAD yet
+// but can still have a dirty tree.
+export function gitState(cwd, extraEnv = {}) {
+  let revision = null, clean = null;
+  try { revision = git(cwd, ["rev-parse", "HEAD"], extraEnv) || null; } catch {}
+  try {
+    const lines = git(cwd, ["status", "--porcelain"], extraEnv).split("\n").filter(Boolean);
+    clean = lines.every(isEngineFile);
+  } catch {}
+  return { revision, clean };
+}
+
+export function plainSpawnCommand({ command, cwd, env }) {
+  return spawn("/bin/sh", ["-c", command], { cwd, env, stdio: ["ignore", "pipe", "pipe"], shell: false, detached: true });
+}
+
+// spawnCommand({ command, cwd, env }) → ChildProcess with piped stdout/stderr.
+export function createCheckRunner({ spawnCommand, tailBytes = OUTPUT_TAIL_BYTES } = {}) {
+  return function runCheck({ command, cwd, env, timeoutMs = DEFAULT_CHECK_TIMEOUT_MS, signal }) {
+    return new Promise(resolve => {
+      const startedAt = Date.now();
+      let child;
+      try { child = spawnCommand({ command, cwd, env }); }
+      catch (error) { return resolve({ exitCode: null, output: "", timedOut: false, durationMs: 0, error: error.message }); }
+      let tail = "";
+      const append = chunk => { tail = (tail + chunk.toString()).slice(-tailBytes); };
+      child.stdout?.on("data", append);
+      child.stderr?.on("data", append);
+      let timedOut = false, settled = false;
+      const timer = setTimeout(() => { timedOut = true; killTree(child, { graceMs: 1000 }); }, timeoutMs);
+      const onAbort = () => killTree(child, { graceMs: 0 });
+      signal?.addEventListener("abort", onAbort, { once: true });
+      const finish = (exitCode, error) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+        resolve({ exitCode, output: tail.trim(), timedOut, durationMs: Date.now() - startedAt, ...(error && { error }) });
+      };
+      child.once("error", err => finish(null, err.message));
+      child.once("close", (code, sig) => finish(code, sig && !timedOut ? `terminated by ${sig}` : undefined));
+    });
+  };
+}
+
+// Runs the checks in order at the current revision. `runCheck` is the
+// per-check runner (createCheckRunner or a scripted stand-in).
+export async function runChecks({ checks = [], cwd, env = {}, gitEnv: extraGitEnv = {}, runCheck, timeoutMs = DEFAULT_CHECK_TIMEOUT_MS, signal, requireClean = false }) {
+  const startedAt = Date.now();
+  const { revision, clean } = gitState(cwd, extraGitEnv);
+  const results = [];
+  let aborted = false;
+  for (const check of checks) {
+    if (signal?.aborted) { aborted = true; break; }
+    const r = await runCheck({ ...check, cwd, env, timeoutMs, signal });
+    results.push({
+      name: check.name, command: check.command,
+      exitCode: r.exitCode ?? null, durationMs: r.durationMs ?? 0, timedOut: !!r.timedOut,
+      output: String(r.output || "").slice(-OUTPUT_TAIL_BYTES),
+      ...(r.error && { error: r.error }),
+    });
+    if (signal?.aborted) { aborted = true; break; }
+  }
+  const checksPassed = results.every(r => r.exitCode === 0 && !r.timedOut);
+  const dirty = requireClean && clean === false;
+  return {
+    revision, clean, requireClean, checked: checks.length > 0,
+    startedAt, durationMs: Date.now() - startedAt, results, aborted,
+    passed: !aborted && checksPassed && !dirty,
+  };
+}
+
+// An approval stands only on: an explicit APPROVED, passing checks, and the
+// same revision the checks and reviewers saw.
+export function evaluateApproval({ verdict, evidence, headNow }) {
+  if (!verdict || verdict.outcome !== "APPROVED") return { approved: false, reason: "review did not approve" };
+  if (evidence && !evidence.passed) return { approved: false, reason: evidence.aborted ? "verification was cancelled" : "engine checks did not pass" };
+  if (evidence?.revision && headNow && evidence.revision !== headNow) {
+    return { approved: false, reason: `code changed after verification (${shortRev(evidence.revision)} → ${shortRev(headNow)})` };
+  }
+  return { approved: true, reason: null };
+}
+
+const seconds = ms => `${(Number(ms || 0) / 1000).toFixed(1)}s`;
+
+function describeResult(r) {
+  if (r.timedOut) return `TIMED OUT after ${seconds(r.durationMs)}`;
+  if (r.exitCode === 0) return `passed in ${seconds(r.durationMs)}`;
+  return `FAILED (${r.exitCode == null ? r.error || "no exit code" : `exit ${r.exitCode}`}) in ${seconds(r.durationMs)}`;
+}
+
+// Findings in the REVIEW verdict shape, so a failed check flows through the
+// same retry path as a reviewer's finding.
+export function evidenceFindings(evidence) {
+  const findings = [];
+  if (!evidence) return findings;
+  if (evidence.requireClean && evidence.clean === false) {
+    findings.push({ reviewer: ENGINE_REVIEWER, title: "Uncommitted changes in the session worktree", detail: "Commit or discard them before review — an approval refers to a committed revision." });
+  }
+  for (const r of evidence.results || []) {
+    if (r.exitCode === 0 && !r.timedOut) continue;
+    const title = r.timedOut ? `\`${r.command}\` timed out after ${seconds(r.durationMs)}` : `\`${r.command}\` failed (${r.exitCode == null ? r.error || "no exit code" : `exit ${r.exitCode}`})`;
+    findings.push({ reviewer: ENGINE_REVIEWER, title, detail: r.output || "(no output)" });
+  }
+  return findings;
+}
+
+export function formatEvidenceForPrompt(evidence) {
+  if (!evidence) return "";
+  const where = evidence.revision ? ` at ${shortRev(evidence.revision)}` : "";
+  const tree = evidence.clean == null ? "" : ` (tree ${evidence.clean ? "clean" : "has uncommitted changes"})`;
+  if (!evidence.checked) {
+    return `No verification commands are configured for this project (commands.test/build/lint in .agentdesk.json)${where}${tree} — reviewers must run the checks themselves and report the output.`;
+  }
+  const lines = [`Engine verification${where}${tree}:`];
+  for (const r of evidence.results) {
+    lines.push(`- \`${r.command}\` — ${describeResult(r)}`);
+    if (r.exitCode !== 0 || r.timedOut) for (const l of String(r.output || "(no output)").split("\n")) lines.push(`  ${l}`);
+  }
+  if (evidence.aborted) lines.push("- (verification was cancelled before every check ran)");
+  return lines.join("\n");
+}
+
+export function renderEvidenceSection(evidence) {
+  if (!evidence) return "";
+  const lines = ["## Evidence", `- Revision: ${evidence.revision ? shortRev(evidence.revision) : "(no repository)"}`];
+  if (evidence.clean != null) lines.push(`- Tree: ${evidence.clean ? "clean" : "uncommitted changes"}`);
+  if (!evidence.checked) lines.push("- Checks: none configured");
+  for (const r of evidence.results || []) lines.push(`- ${r.name}: \`${r.command}\` — ${describeResult(r)}`);
+  lines.push(`- Result: ${evidence.passed ? "passed" : "not passed"}`, "");
+  return lines.join("\n");
+}

package/cli/engine/handoff.mjs

@@ -0,0 +1,75 @@
+// The handoff ledger: what each phase run actually did, at which revision,
+// with what evidence, and what is still open — written by the engine, not
+// by the agents, so the next phase starts from a record instead of a recap.
+//
+// `.agentdesk/handoffs.jsonl` is append-only, one entry per phase run. The
+// open-items list is the part that travels forward into the next prompt.
+
+import { appendFileSync, readFileSync } from "node:fs";
+import { shortRev } from "./evidence.mjs";
+
+export function createLedger(path) {
+  return {
+    path,
+    record(entry) {
+      try { appendFileSync(path, `${JSON.stringify(entry)}\n`); } catch {}
+      return entry;
+    },
+    entries() {
+      try {
+        return readFileSync(path, "utf8").split("\n").filter(Boolean).map(line => JSON.parse(line));
+      } catch { return []; }
+    },
+  };
+}
+
+function location(f) {
+  return f.file ? ` (${f.file}${f.line ? `:${f.line}` : ""})` : "";
+}
+
+// Open items after a review has been settled. Review and engine items are
+// unresolved work; deferred items are carried so the summary can list them
+// and nobody quietly picks them up.
+export function openItemsFrom({ verdict = null } = {}) {
+  const items = [];
+  if (!verdict) return items;
+  if (!verdict.approved) {
+    const source = verdict.engineOnly ? "engine" : "review";
+    for (const f of verdict.findings || []) items.push({ source, title: `${f.title}${location(f)}`, detail: f.detail || "", reviewer: f.reviewer });
+    for (const claim of verdict.unverifiedClaims || []) items.push({ source: "review", title: "Unverified claim", detail: String(claim) });
+    if (verdict.outcome === "APPROVED" && verdict.approvalReason) {
+      items.push({ source: "engine", title: "Approval not accepted", detail: verdict.approvalReason });
+    }
+  }
+  for (const d of verdict.deferred || []) items.push({ source: "deferred", title: String(d), detail: "" });
+  return items;
+}
+
+// An EXECUTION that reports implemented work while HEAD did not move and the
+// tree is clean has nothing to review. Surfaced, not blocked: the reviewers
+// decide, with the fact in front of them.
+export function noCommitItem({ phase, revisionBefore, revisionAfter, clean, output }) {
+  if (phase !== "EXECUTION" || !revisionBefore || revisionAfter !== revisionBefore || clean !== true) return null;
+  const implemented = Array.isArray(output?.implemented) ? output.implemented : [];
+  if (implemented.length === 0) return null;
+  return {
+    source: "engine",
+    title: "EXECUTION reported work but made no commits",
+    detail: `HEAD is still ${shortRev(revisionBefore)} and the tree is clean; the ${implemented.length} implemented item(s) are not backed by a commit.`,
+  };
+}
+
+export function renderOpenItems(items = []) {
+  if (!items.length) return "";
+  const lines = [
+    "## OPEN ITEMS",
+    "",
+    "Carried from earlier phases by the engine. Resolve the review and engine items. Deferred items are explicitly out of scope — do not address them, but make sure the final summary lists them.",
+    "",
+  ];
+  for (const item of items) {
+    const detail = item.detail ? ` — ${item.detail}` : "";
+    lines.push(item.source === "deferred" ? `- [deferred] ${item.title}` : `- [${item.source}] **${item.title}**${detail}`);
+  }
+  return lines.join("\n");
+}

package/cli/engine/hooks.mjs

@@ -19,6 +19,14 @@ export function isPublishCommand(command) {
   return PUBLISH_RE.test(String(command || ""));
 }
 
+// Commands that move HEAD or rewrite the tree. SUMMARY reports on an approved
+// revision; it must not be able to change which revision that is.
+const HISTORY_RE = /(^|[;&|]\s*)git\s+(commit|merge|rebase|reset|checkout|switch|cherry-pick|revert|am|apply|stash|restore|clean)\b/;
+
+export function isHistoryCommand(command) {
+  return HISTORY_RE.test(String(command || ""));
+}
+
 // The auditor whose sign-off gates publishing. "Sam's audit is a blocking
 // gate — not advisory" used to be prose; now it is the observable fact that a
 // Sam subagent finished in this EXECUTION phase (SubagentStop).
@@ -62,6 +70,16 @@ export function decidePreToolUse({ phase, input, state = {} }) {
     return { decision: "deny", reason: "REVIEW is read-only: report findings; fixes happen back in EXECUTION." };
   }
 
+  // The approval refers to one revision. SUMMARY may read it and talk about
+  // it; it may not edit, commit, move HEAD, or publish.
+  if (phase === "SUMMARY") {
+    if (MUTATING_TOOLS.has(tool)) return { decision: "deny", reason: "SUMMARY writes messages only — the approved revision must not change." };
+    const command = input?.tool_input?.command;
+    if (tool === "Bash" && (isPublishCommand(command) || isHistoryCommand(command))) {
+      return { decision: "deny", reason: "SUMMARY writes messages only — it cannot commit, move HEAD, or publish; the approved revision must not change." };
+    }
+  }
+
   if (phase === "EXECUTION" && tool === "Bash" && isPublishCommand(input?.tool_input?.command)) {
     const open = Array.isArray(state.openFindings) ? state.openFindings : [];
     if (state.awaitingAudit || open.length > 0) {

package/cli/engine/phases/EXECUTION.md

@@ -15,7 +15,7 @@ The reviewers returned the following. Work from this list; do not re-derive it.
 
 - Follow CLAUDE.md conventions (if present). Do not modify files unrelated to the task.
 - **Sam's audit is a blocking gate.** After Dennis implements, Sam must read every changed file and run his full checklist, citing file:line for every finding — "looks clean" without evidence is invalid. Dennis fixes every violation before Bart creates the PR. Publishing is refused while findings are open.
-- Nora's sign-off is a gate too: Bart cannot create the PR until Nora reports either "No doc impact — skipped" or "Docs updated: [files]".
+{{#HAS_NORA}}- Nora's sign-off is a gate too: Bart cannot create the PR until Nora reports either "No doc impact — skipped" or "Docs updated: [files]".{{/HAS_NORA}}
 - Do NOT post the final tracker summary or transition the task here — SUMMARY owns all final tracker writes.
 
 {{#SCREENSHOTS_ENABLED}}
@@ -33,12 +33,12 @@ Screenshots are **disabled** for this project. Do not capture any unless the use
 
 ## Your mission
 
-Drive the plan from session memory step by step. Delegate each step with the Agent tool, give the agent the exact step and the relevant decisions, and require an observation for every claim ("tests pass" means the test output, "endpoint works" means the response). In order:
+{{#NO_PLAN}}This task was assessed as small, so there was no PLAN phase. First have Dennis state the approach in two or three lines — files to change, the risk, how it will be verified — and confirm it; that is the plan. Then drive it step by step.{{/NO_PLAN}}{{#HAS_PLAN}}Drive the plan from session memory step by step.{{/HAS_PLAN}} Delegate each step with the Agent tool, give the agent the exact step and the relevant decisions, and require an observation for every claim ("tests pass" means the test output, "endpoint works" means the response). In order:
 
 1. **Dennis implements** — create the branch, implement per the plan, run linter and build, commit. Report files changed and technical decisions.
 2. **Sam audits** — every changed file, full checklist (feature envy, separation of concerns, clear interfaces, layering, god files), file:line for each finding. If there are violations, send Dennis back to fix them, then have Sam re-audit.
 3. **Vera tests** — unit/regression tests for the changed code, run and verified, committed.
-4. **Luna / Mark / Nora** — only where applicable (UI, user-facing copy, user-facing behaviour). Each proposes exact changes; Dennis applies them.
+{{#HAS_SPECIALISTS}}4. **{{SPECIALISTS}}** — only where applicable (UI, user-facing copy, user-facing behaviour). Each proposes exact changes; Dennis applies them.{{/HAS_SPECIALISTS}}
 5. **Bart reviews and publishes** — reads all changed files, checks edge cases and error handling, runs linter and build, captures screenshots if applicable, pushes and creates the PR, posts the PR link on the tracker, posts screenshots as a separate comment.
 6. Ask Dennis, Sam and Bart to post their brief tracker comments (files changed & decisions; architecture findings or clean audit with evidence; PR link, test results, screenshots).
 

package/cli/engine/phases/PLAN.md

@@ -18,9 +18,9 @@ Task: {{TASK_ID}}
    - Dennis: implementation plan — files to modify, approach, complexity (S/M/L).
    - Sam: architecture review — existing patterns, module boundaries, whether the approach keeps concerns separated.
    - Vera: test plan — which functions need coverage, regression cases.
-   - Luna (only if the task touches UI): visual impact, accessibility, and a screenshot plan (pages, viewports).
-   - Mark (only if user-facing text changes): copy audit.
-   - Nora (only if user-facing behaviour changes): which docs/README/help surfaces must change.
+{{#HAS_LUNA}}   - Luna (only if the task touches UI): visual impact, accessibility, and a screenshot plan (pages, viewports).{{/HAS_LUNA}}
+{{#HAS_MARK}}   - Mark (only if user-facing text changes): copy audit.{{/HAS_MARK}}
+{{#HAS_NORA}}   - Nora (only if user-facing behaviour changes): which docs/README/help surfaces must change.{{/HAS_NORA}}
 3. Relay the substance of each report in a few lines. Ask for objections once. Resolve them and declare the plan final — do not brainstorm beyond two rounds.
 
 The structured output required by the schema is captured automatically — approach, files to modify, decisions, risks, agent assignments, and the ordered implementation steps. Do not repeat the JSON object in chat; keep any closing chat message brief and human-readable.

package/cli/engine/phases/REVIEW.md

@@ -11,9 +11,10 @@ Task: {{TASK_ID}}
 
 ## Your mission
 
-1. **Delegate to three reviewers in parallel.** Each should inspect the actual changes themselves (`git diff <base>...HEAD` against the branch the work started from, and read the changed files) and report findings with file:line:
-   - **Sam** — does the code match the PLAN? Partially-implemented helpers, dead branches, TODOs, error paths not wired. Hidden cross-cutting concerns: docs, changelog, config schema, migrations, dependent callers. **Verification audit:** for every claim EXECUTION made (deployed, tests pass, endpoint works, migration ran), confirm it is backed by an observation he can reproduce; anything resting on inference is a finding.
+1. **Delegate to the reviewers in parallel.** Each should inspect the actual changes themselves (`git diff <base>...HEAD` against the branch the work started from, and read the changed files) and report findings with file:line:
+{{#HAS_SAM}}   - **Sam** — does the code match the PLAN? Partially-implemented helpers, dead branches, TODOs, error paths not wired. Hidden cross-cutting concerns: docs, changelog, config schema, migrations, dependent callers. **Verification audit:** for every claim EXECUTION made (deployed, tests pass, endpoint works, migration ran), confirm it is backed by an observation he can reproduce; anything resting on inference is a finding.{{/HAS_SAM}}
    - **Bart** — does the implementation meet the acceptance criteria from INTAKE? Is any requirement missed or silently deferred? Is the PR description accurate, does it reference the task, are screenshots attached where expected?
+{{#NO_SAM}}   - **Bart** also runs the verification audit in Sam's place: for every claim EXECUTION made (deployed, tests pass, endpoint works, migration ran), confirm it is backed by an observation he can reproduce; anything resting on inference is a finding.{{/NO_SAM}}
    - **Vera** — run the test suite and report the real output; is the changed code covered; do the new tests exercise the behaviour that changed?
 2. Weigh the reports. Be strict but not pedantic: only actual gaps against the task requirements and the plan — not stylistic preferences or speculative refactors.
 3. Decide: `APPROVED` or `NEEDS_MORE_WORK`.

package/cli/engine/prompts.mjs

@@ -13,6 +13,8 @@ import { fileURLToPath } from "url";
 import { wrapUntrusted, PROMPT_SECURITY_HEADER, MEMORY_INSTRUCTIONS, loadProjectMemory } from "../prompt.mjs";
 import { generateContext } from "../detect.mjs";
 import { formatFindingsForRetry } from "./verdict.mjs";
+import { formatEvidenceForPrompt } from "./evidence.mjs";
+import { renderOpenItems } from "./handoff.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 
@@ -133,7 +135,8 @@ function createTaskSection({ tracker, config, description }) {
 // Returns the full user prompt for one phase's query().
 export function renderPhasePrompt({
   phase, taskId, taskLink, description, createTask, tracker, config = {}, project = {},
-  sessionUrl, cwd, sessionMemory = "", retryVerdict = null,
+  sessionUrl, cwd, sessionMemory = "", retryVerdict = null, evidence = null, openItems = [],
+  roster = null, profile = null,
 }) {
   const vars = {
     TASK_ID: taskId,
@@ -149,6 +152,17 @@ export function renderPhasePrompt({
   if (tracker) flags.add(tracker.toUpperCase()); else flags.add("NO_TRACKER");
   if (retryVerdict) flags.add("RETRY");
 
+  // The prompt names only the agents that exist in this phase (agents/index.mjs
+  // rosterFor): a gate or a step that names an absent agent would send the lead
+  // chasing someone she cannot delegate to. No roster → the legacy full team.
+  const names = Array.isArray(roster) ? roster : ["Dennis", "Sam", "Vera", "Bart", "Luna", "Mark", "Nora"];
+  for (const n of ["Sam", "Luna", "Mark", "Nora"]) if (names.includes(n)) flags.add(`HAS_${n.toUpperCase()}`);
+  if (!names.includes("Sam")) flags.add("NO_SAM");
+  const specialists = ["Luna", "Mark", "Nora"].filter(n => names.includes(n));
+  if (specialists.length) flags.add("HAS_SPECIALISTS");
+  vars.SPECIALISTS = specialists.join(" / ");
+  flags.add(profile?.size === "small" ? "NO_PLAN" : "HAS_PLAN");
+
   vars.TRACKER_SECTION = trackerSection(tracker, phase, vars);
 
   let body = renderTemplate(template(`phases/${phase}.md`), { flags, vars }).trim();
@@ -162,6 +176,10 @@ export function renderPhasePrompt({
   if (config.instructions) {
     body += `\n\n## ADDITIONAL INSTRUCTIONS\n\n${config.instructions}`;
   }
+  if (evidence) {
+    body += `\n\n## ENGINE VERIFICATION\n\nThe engine ran the project's own checks before this phase. Build on these observations; do not re-run the whole suite blind.\n\n${formatEvidenceForPrompt(evidence)}`;
+  }
+  if (openItems.length) body += `\n\n${renderOpenItems(openItems)}`;
   if (sessionMemory) {
     body += `\n\n## SESSION MEMORY (previous phases)\n\n${sessionMemory}`;
   }

package/cli/engine/schemas.mjs

@@ -15,7 +15,7 @@ export const PHASE_OUTPUT_SCHEMAS = Object.freeze({
   INTAKE: {
     type: "object",
     additionalProperties: false,
-    required: ["title", "taskSummary", "requirements", "assessment", "subtasks", "nextPhaseFocus"],
+    required: ["title", "taskSummary", "requirements", "assessment", "subtasks", "nextPhaseFocus", "scope"],
     properties: {
       title: { type: "string", description: "4-8 word session title" },
       taskSummary: { type: "string" },
@@ -23,6 +23,16 @@ export const PHASE_OUTPUT_SCHEMAS = Object.freeze({
       assessment: { ...strList, description: "existing branches/PRs, code patterns, resume context" },
       subtasks: { ...strList, description: "subtasks created, if the task was decomposed; else empty" },
       nextPhaseFocus: strList,
+      scope: {
+        type: "object",
+        additionalProperties: false,
+        required: ["size", "touches"],
+        description: "how big the change is and which areas it touches — decides the team and phases",
+        properties: {
+          size: { type: "string", enum: ["small", "standard"], description: "small: a contained change one implementer and independent reviewers can handle without a planning round; standard: multi-area or user-facing work" },
+          touches: { type: "array", items: { type: "string", enum: ["ui", "copy", "docs", "api", "data"] }, description: "areas the change touches; specialists join only for the areas listed" },
+        },
+      },
     },
   },
   PLAN: {
@@ -93,6 +103,7 @@ export function renderMemorySection(phase, out) {
         "## Task",
         `- Title: ${out.title || ""}`,
         `- Summary: ${out.taskSummary || ""}`,
+        ...(out.scope?.size ? [`- Scope: ${out.scope.size}${Array.isArray(out.scope.touches) && out.scope.touches.length ? ` (${out.scope.touches.join(", ")})` : ""}`] : []),
         "",
         "## Requirements",
         bullets(out.requirements),

package/cli/engine/session.mjs

@@ -17,17 +17,24 @@ import { fileURLToPath } from "url";
 import { createScratchHome } from "../session-sandbox.mjs";
 import { resolveGitHubCreds, assertPushable, PreflightError } from "../session-preflight.mjs";
 import {
-  PHASES, MAX_REVIEW_RETRIES, MAX_PHASE_RUNS, phaseFailed, finalStatus, archiveStaleMemory,
+  MAX_REVIEW_RETRIES, MAX_PHASE_RUNS, phaseFailed, finalStatus, archiveStaleMemory,
 } from "../phase-loop.mjs";
 import { buildChildEnv } from "./env.mjs";
 import { loadDotEnv } from "../dotenv.mjs";
 import { checkClaudeAuth } from "./claude-auth.mjs";
 import { createEventMapper, timestamp } from "./events.mjs";
 import { captureOutcome, githubRepository, currentBranch, replyMarker } from "./outcome.mjs";
-import { agentsForPhase, modelForPhase, soloDefinition } from "./agents/index.mjs";
+import { agentsForPhase, modelForPhase, soloDefinition, rosterFor } from "./agents/index.mjs";
 import { renderPhasePrompt, renderSoloPrompt } from "./prompts.mjs";
 import { renderMemorySection } from "./schemas.mjs";
 import { verdictFromResult } from "./verdict.mjs";
+import {
+  resolveChecks, runChecks, createCheckRunner, evaluateApproval, evidenceFindings,
+  renderEvidenceSection, gitState, checkTimeoutMs, shortRev,
+} from "./evidence.mjs";
+import { spawnSandboxedCommand } from "./spawn.mjs";
+import { createLedger, openItemsFrom, noCommitItem } from "./handoff.mjs";
+import { teamProfileFor, phasesFor } from "./team-profile.mjs";
 import { buildQueryOptions, defaultRunQuery } from "./query.mjs";
 import { armPublishGate, onSubagentStopped } from "./hooks.mjs";
 import { prepareWorkspace } from "../worktrees.mjs";
@@ -132,6 +139,7 @@ async function executeSession({
   onEvent, apiKey, serverUrl, sessionId, onChild, abortSignal,
   soloAgent = null, childStrategy = null,
   runQuery = defaultRunQuery,
+  runCheck = null,
   authCheck = checkClaudeAuth,
   sourceCwd = cwd, workspaceRecord, workspaceStateDir, resumingWorkspace = false,
   workspaceGitEnv = {},
@@ -209,10 +217,12 @@ async function executeSession({
   const stateDir = workspaceStateDir || join(cwd, ".agentdesk");
   const memoryPath = join(stateDir, "session-memory.md");
   const findingsPath = join(stateDir, "review-findings.json");
+  const ledgerPath = join(stateDir, "handoffs.jsonl");
   try { mkdirSync(stateDir, { recursive: true }); } catch {}
   if (!resumingWorkspace || !existsSync(memoryPath)) {
     if (archiveStaleMemory(memoryPath)) console.error("[agentdesk] archived stale session-memory.md from a previous run");
     try { if (existsSync(findingsPath)) unlinkSync(findingsPath); } catch {}
+    try { if (existsSync(ledgerPath)) unlinkSync(ledgerPath); } catch {}
     writeFileSync(memoryPath, `# Session Memory\n\n## Task\n- ID: ${taskId}\n${taskLink ? `- Link: ${taskLink}\n` : ""}\n`);
   } else {
     appendFileSync(memoryPath, `\n## Resumed session\n${sessionUrl || sessionId}\n`);
@@ -226,7 +236,84 @@ async function executeSession({
   let reviewRetries = 0, phaseRuns = 0, lastVerdict = null, lastPhase = null;
   let isolationLogged = false;
 
-  const queue = solo ? ["SOLO"] : [...PHASES];
+  // --- evidence (engine-owned) ---------------------------------------------
+  // The engine runs the project's checks itself before every REVIEW and pins
+  // any approval to the revision they ran at. In a session worktree the tree
+  // must be clean too: an approval refers to a committed revision.
+  const checks = resolveChecks({ config, project });
+  const requireClean = !!workspaceRecord;
+  const runOneCheck = runCheck || createCheckRunner({
+    spawnCommand: ({ command, cwd: checkCwd, env }) => spawnSandboxedCommand({
+      command, cwd: checkCwd, env, sandbox, onChild,
+      extraWritePaths: workspaceStateDir ? [workspaceStateDir, workspaceRecord.tree || cwd] : [],
+    }),
+  });
+  const headNow = () => gitState(cwd, workspaceGitEnv).revision;
+  let approvedRevision = null;
+
+  // --- handoff ledger (engine-owned) ---------------------------------------
+  // One entry per phase run; the open-items list travels into the next prompt.
+  const ledger = createLedger(ledgerPath);
+  let openItems = [];
+
+  const reportEvidence = evidence => {
+    emit({ type: "session:evidence", phase: "REVIEW", revision: evidence.revision, clean: evidence.clean,
+      passed: evidence.passed, checked: evidence.checked, results: evidence.results });
+    const at = evidence.revision ? ` at ${shortRev(evidence.revision)}` : "";
+    if (!evidence.checked) {
+      emit({ type: "agent:message", agent: "Jane", tag: "SAY", message: `No verification commands configured (commands.test/build/lint) — review relies on the reviewers alone${at}.` });
+    }
+    for (const r of evidence.results) {
+      const took = `${(r.durationMs / 1000).toFixed(1)}s`;
+      const status = r.timedOut ? `timed out after ${took}` : r.exitCode === 0 ? `passed (${took})` : `FAILED (exit ${r.exitCode ?? "?"}, ${took})`;
+      emit({ type: "agent:message", agent: "Jane", tag: "ACT", message: `Ran \`${r.command}\`${at} — ${status}` });
+    }
+    if (evidence.requireClean && evidence.clean === false) {
+      emit({ type: "agent:message", agent: "Jane", tag: "SAY", message: "Uncommitted changes in the session worktree — review cannot approve an uncommitted state." });
+    }
+  };
+
+  // One place decides what a REVIEW outcome means for the loop, whether the
+  // verdict came from the reviewers or was synthesised from failed checks.
+  function settleReview(verdict) {
+    lastVerdict = verdict;
+    reviewResolved = verdict.approved === true;
+    if (reviewResolved) approvedRevision = verdict.headNow || verdict.revision || null;
+    state.openFindings = reviewResolved ? [] : verdict.findings;
+    openItems = openItemsFrom({ verdict });
+    try { writeFileSync(findingsPath, JSON.stringify(verdict, null, 2)); } catch {}
+    if (reviewResolved) return;
+    if (verdict.outcome === "MISSING") {
+      emit({ type: "session:error", code: "REVIEW_VERDICT_MISSING", message: `REVIEW ended without a verdict (${verdict.reason}) — treating as not approved.` });
+    } else if (verdict.outcome === "APPROVED") {
+      emit({ type: "session:error", code: "REVIEW_STALE", message: `Review approved ${shortRev(verdict.revision)} but the code is now at ${shortRev(verdict.headNow)} — the approval does not carry over.` });
+    }
+    const count = `${verdict.findings.length} finding(s)`;
+    if (reviewRetries < MAX_REVIEW_RETRIES) {
+      reviewRetries++;
+      const why = verdict.engineOnly ? `Verification failed (${count})` : `Review did not approve (${verdict.outcome}, ${count})`;
+      emit({ type: "agent:message", agent: "Jane", tag: "SAY", message: `${why} — returning to EXECUTION (retry ${reviewRetries}/${MAX_REVIEW_RETRIES}).` });
+      queue.unshift("EXECUTION", "REVIEW");
+    } else {
+      const why = verdict.engineOnly ? "Verification still failing" : "Review still unresolved";
+      emit({ type: "agent:message", agent: "Jane", tag: "SAY", message: `${why} after ${reviewRetries} retry — ending session for human review.` });
+    }
+  }
+
+  // An approval is void the moment the code moves past the reviewed revision.
+  const invalidateApproval = now => {
+    reviewResolved = false;
+    emit({ type: "session:error", code: "REVIEW_STALE", message: `Code changed after approval (${shortRev(approvedRevision)} → ${shortRev(now)}) — the approval no longer applies; ending for human review.` });
+    openItems = [...openItems, { source: "engine", title: "Approval invalidated", detail: `Code changed after approval (${shortRev(approvedRevision)} → ${shortRev(now)}).` }];
+    if (lastVerdict) {
+      lastVerdict = { ...lastVerdict, approved: false, approvalReason: "code changed after approval", headNow: now };
+      try { writeFileSync(findingsPath, JSON.stringify(lastVerdict, null, 2)); } catch {}
+    }
+  };
+
+  // --- team profile (INTAKE assesses the task; config may force) -----------
+  let profile = teamProfileFor({ intake: null, config });
+  const queue = solo ? ["SOLO"] : phasesFor(profile);
 
   try {
     while (queue.length > 0) {
@@ -238,13 +325,42 @@ async function executeSession({
 
       const phase = queue.shift();
       lastPhase = phase;
+      const run = { index: phaseRuns, startedAt: Date.now(), revisionBefore: headNow() };
+      const finishRun = ({ output = null, evidence: runEvidence = null, status }) => {
+        const entry = { phase, run: run.index, startedAt: run.startedAt, durationMs: Date.now() - run.startedAt,
+          revisionBefore: run.revisionBefore, revisionAfter: headNow(), output, evidence: runEvidence, openItems: [...openItems], status };
+        ledger.record(entry);
+        emit({ type: "session:handoff", ...entry });
+      };
       // The dashboard knows the five team phases; solo shows as EXECUTION.
       const model = modelForPhase(phase === "SOLO" ? "EXECUTION" : phase, config.phaseModels);
       emit({ type: "phase:change", phase: phase === "SOLO" ? "EXECUTION" : phase, model: model || "default" });
 
+      // Verification runs before the reviewers are asked. If it fails, the
+      // reviewers are not asked at all: the failing output goes straight back
+      // to EXECUTION as findings, through the same retry path.
+      let evidence = null;
+      if (phase === "REVIEW") {
+        evidence = await runChecks({ checks, cwd, env: buildChildEnv({ dotenv, sandboxEnv: sandbox.env, extra: workspaceGitEnv }),
+          gitEnv: workspaceGitEnv, runCheck: runOneCheck, timeoutMs: checkTimeoutMs(config), signal: abortController.signal, requireClean });
+        if (abortController.signal.aborted) { aborted = true; break; }
+        reportEvidence(evidence);
+        appendMemory(renderEvidenceSection(evidence));
+        if (!evidence.passed) {
+          settleReview({ outcome: "NEEDS_MORE_WORK", findings: evidenceFindings(evidence), deferred: [], unverifiedClaims: [], reason: null,
+            revision: evidence.revision, headNow: evidence.revision, evidence, approved: false, approvalReason: "engine checks did not pass", engineOnly: true });
+          finishRun({ evidence, status: "checks-failed" });
+          continue;
+        }
+      }
+      if (phase === "SUMMARY" && reviewResolved && approvedRevision) {
+        const now = headNow();
+        if (now !== approvedRevision) invalidateApproval(now);
+      }
+
       const { agents, allowedTools, lead } = solo
         ? soloDefinition(solo)
-        : agentsForPhase({ phase, team, phaseModels: config.phaseModels });
+        : agentsForPhase({ phase, team, phaseModels: config.phaseModels, profile });
       let prompt = solo
         ? renderSoloPrompt({ agent: solo, taskId, taskLink, description, tracker, config, project, sessionUrl, cwd, childStrategy })
         : renderPhasePrompt({
@@ -252,7 +368,12 @@ async function executeSession({
           createTask: phase === "INTAKE" ? createTask : false,
           tracker, config, project, sessionUrl, cwd,
           sessionMemory: memoryText(),
-          retryVerdict: phase === "EXECUTION" && lastVerdict && lastVerdict.outcome !== "APPROVED" ? lastVerdict : null,
+          retryVerdict: phase === "EXECUTION" && lastVerdict && !lastVerdict.approved ? lastVerdict : null,
+          evidence,
+          // A retry already carries the verdict's findings; open items feed the other phases.
+          openItems: phase === "EXECUTION" && lastVerdict && !lastVerdict.approved ? [] : openItems,
+          roster: Object.keys(agents).filter(name => name !== lead),
+          profile,
         });
       if (workspaceRecord) {
         prompt += `\n\n## SESSION WORKSPACE\nAll file reads, writes, shell commands and Git operations must use ${cwd}.\nThe session branch ${workspaceRecord.branch} is already checked out; use it instead of creating or switching branches. The starting branch is ${workspaceRecord.baseRef}. Keep this branch until the session ends. Runtime session memory lives at ${memoryPath}.\n`;
@@ -314,29 +435,17 @@ async function executeSession({
         emit({ type: "session:error", code: "PHASE_FAILED", message: `${phase} failed (${detail}) — session incomplete.` });
         handoff = true;
         writeResumeFile({ cwd, taskId, sessionUrl, phase, duration: seconds(startedAt), steps: totals.steps, workspaceId: workspaceRecord?.id });
+        finishRun({ status: "failed" });
         break;
       }
 
       if (phase === "REVIEW") {
         const verdict = verdictFromResult({ is_error: summary.isError, subtype: summary.subtype, structured_output: summary.structuredOutput });
-        lastVerdict = verdict;
-        reviewResolved = verdict.outcome === "APPROVED";
-        state.openFindings = reviewResolved ? [] : verdict.findings;
+        const now = headNow();
+        const approval = evaluateApproval({ verdict, evidence, headNow: now });
         appendMemory(renderMemorySection("REVIEW", summary.structuredOutput));
-        try { writeFileSync(findingsPath, JSON.stringify(verdict, null, 2)); } catch {}
-
-        if (!reviewResolved) {
-          if (verdict.outcome === "MISSING") {
-            emit({ type: "session:error", code: "REVIEW_VERDICT_MISSING", message: `REVIEW ended without a verdict (${verdict.reason}) — treating as not approved.` });
-          }
-          if (reviewRetries < MAX_REVIEW_RETRIES) {
-            reviewRetries++;
-            emit({ type: "agent:message", agent: "Jane", tag: "SAY", message: `Review did not approve (${verdict.outcome}, ${verdict.findings.length} finding(s)) — returning to EXECUTION (retry ${reviewRetries}/${MAX_REVIEW_RETRIES}).` });
-            queue.unshift("EXECUTION", "REVIEW");
-          } else {
-            emit({ type: "agent:message", agent: "Jane", tag: "SAY", message: `Review still unresolved after ${reviewRetries} retry — ending session for human review.` });
-          }
-        }
+        settleReview({ ...verdict, revision: evidence?.revision ?? null, headNow: now, evidence, approved: approval.approved, approvalReason: approval.reason });
+        finishRun({ output: summary.structuredOutput ?? null, evidence, status: lastVerdict.approved ? "ok" : "not-approved" });
         continue;
       }
 
@@ -345,15 +454,40 @@ async function executeSession({
         emit({ type: "session:error", code: "PHASE_OUTPUT_MISSING", message: `${phase} produced no structured summary — later phases will have less context.` });
       }
       appendMemory(renderMemorySection(phase, summary.structuredOutput));
+      if (phase === "EXECUTION") {
+        const after = gitState(cwd, workspaceGitEnv);
+        const missing = noCommitItem({ phase, revisionBefore: run.revisionBefore, revisionAfter: after.revision, clean: after.clean, output: summary.structuredOutput });
+        if (missing) {
+          openItems = [...openItems, missing];
+          emit({ type: "agent:message", agent: "Jane", tag: "SAY", message: `${missing.title} — ${missing.detail}` });
+        }
+      }
+      finishRun({ output: summary.structuredOutput ?? null, status: summary.structuredOutput ? "ok" : "missing-output" });
       if (phase === "INTAKE" && summary.structuredOutput?.title) {
         emit({ type: "session:update", title: String(summary.structuredOutput.title).slice(0, 60) });
       }
+      if (phase === "INTAKE") {
+        profile = teamProfileFor({ intake: summary.structuredOutput, config });
+        if (profile.size === "small") {
+          const at = queue.indexOf("PLAN");
+          if (at >= 0) queue.splice(at, 1);
+        }
+        const names = Object.keys(rosterFor("EXECUTION", profile)).join(", ");
+        const areas = profile.touches.length ? ` (${profile.touches.join(", ")})` : "";
+        emit({ type: "agent:message", agent: "Jane", tag: "SAY", message: `Team for this task: ${profile.size}${areas} — ${names}.${profile.size === "small" ? " Skipping PLAN." : ""}` });
+      }
     }
   } finally {
     abortSignal?.removeEventListener?.("abort", onExternalAbort);
     sandbox.cleanup();
   }
 
+  // Belt to SUMMARY's braces: nothing may have moved the approved revision.
+  if (!aborted && reviewResolved && approvedRevision) {
+    const now = headNow();
+    if (now !== approvedRevision) invalidateApproval(now);
+  }
+
   const duration = seconds(startedAt);
   const status = finalStatus({ aborted, crashed: handoff, reviewResolved });
   const resumePath = join(cwd, ".agentdesk-resume.md");
@@ -373,5 +507,8 @@ async function executeSession({
     handoff: status !== "complete",
     aborted, status, reviewResolved, lastPhase,
     verdict: lastVerdict,
+    approvedRevision: reviewResolved ? approvedRevision : null,
+    openItems,
+    profile,
   };
 }

package/cli/engine/spawn.mjs

@@ -35,6 +35,34 @@ export function bundledClaudeDir() {
   }
 }
 
+// One isolation policy for everything a session runs — Claude itself and the
+// engine's own verification commands. Shared Git metadata is exposed
+// read-only and the worktree's private Git state is protected, so a check
+// command has exactly the reach a Bash tool call inside the session has.
+function wrapForSession({ cmd, args, cwd, env = {}, sandbox, extraReadPaths = [], extraWritePaths = [] }) {
+  const sharedGit = workspaceGitPaths(cwd);
+  const wrapped = wrapIsolatedSpawn({
+    cmd, args, cwd,
+    scratchHome: sandbox.home,
+    extraReadPaths: [bundledClaudeDir(), ...sharedGit, ...extraReadPaths].filter(Boolean),
+    extraWritePaths,
+    protectedPaths: sharedGit.length ? [...sharedGit, join(env.GIT_WORK_TREE || cwd, ".git"), ...(env.GIT_DIR ? [join(dirname(env.GIT_DIR), "..", "git-pending")] : [])] : [],
+  });
+  if (sharedGit.length && wrapped.isolation.policy !== "strict") throw new Error("Worktree sessions require strict kernel isolation; shared Git metadata cannot be exposed writable.");
+  return wrapped;
+}
+
+// Run one shell command under the session's isolation, in its own process
+// group, tracked for teardown. Used by the engine's verification checks.
+export function spawnSandboxedCommand({ command, cwd, env, sandbox, extraReadPaths = [], extraWritePaths = [], onChild }) {
+  installExitGuards();
+  const wrapped = wrapForSession({ cmd: "/bin/sh", args: ["-c", command], cwd, env, sandbox, extraReadPaths, extraWritePaths });
+  const child = spawn(wrapped.cmd, wrapped.args, { cwd, env, stdio: ["ignore", "pipe", "pipe"], shell: false, detached: true });
+  trackChild(child);
+  onChild?.(child);
+  return child;
+}
+
 // Build the `spawnClaudeCodeProcess` callback for one session.
 //
 //   sandbox      — result of createScratchHome() (its `home` hosts the profile)
@@ -46,17 +74,7 @@ export function createSandboxedSpawn({ sandbox, onChild, extraReadPaths = [], ex
   let reported = false;
 
   return function spawnClaudeCodeProcess(opts) {
-    const sharedGit = workspaceGitPaths(opts.cwd);
-    const wrapped = wrapIsolatedSpawn({
-      cmd: opts.command,
-      args: opts.args,
-      cwd: opts.cwd,
-      scratchHome: sandbox.home,
-      extraReadPaths: [bundledClaudeDir(), ...sharedGit, ...extraReadPaths].filter(Boolean),
-      extraWritePaths,
-      protectedPaths: sharedGit.length ? [...sharedGit, join(opts.env.GIT_WORK_TREE || opts.cwd, ".git"), ...(opts.env.GIT_DIR ? [join(dirname(opts.env.GIT_DIR), "..", "git-pending")] : [])] : [],
-    });
-    if (sharedGit.length && wrapped.isolation.policy !== "strict") throw new Error("Worktree sessions require strict kernel isolation; shared Git metadata cannot be exposed writable.");
+    const wrapped = wrapForSession({ cmd: opts.command, args: opts.args, cwd: opts.cwd, env: opts.env, sandbox, extraReadPaths, extraWritePaths });
 
     if (!reported) {
       reported = true;

package/cli/engine/team-profile.mjs

@@ -0,0 +1,30 @@
+// Team composition follows the task.
+//
+// INTAKE assesses the scope (size + areas touched); the engine turns that
+// into a profile that decides which phases run and which specialists join.
+// A missing or malformed assessment falls back to the full team — the safe
+// direction. config.teamProfile ("small" | "standard") overrides the
+// assessment; "auto" (default) lets INTAKE decide.
+
+import { PHASES } from "../phase-loop.mjs";
+
+export const PROFILES = Object.freeze(["small", "standard"]);
+export const TOUCH_AREAS = Object.freeze(["ui", "copy", "docs", "api", "data"]);
+
+export function teamProfileFor({ intake = null, config = {} } = {}) {
+  const override = config?.teamProfile;
+  const assessed = intake?.scope?.size;
+  // No usable assessment of the touched areas → every specialist joins.
+  const touches = Array.isArray(intake?.scope?.touches)
+    ? [...new Set(intake.scope.touches.filter(t => TOUCH_AREAS.includes(t)))]
+    : [...TOUCH_AREAS];
+  if (PROFILES.includes(override)) return { size: override, touches, source: "config" };
+  if (PROFILES.includes(assessed)) return { size: assessed, touches, source: "intake" };
+  return { size: "standard", touches, source: "default" };
+}
+
+// A small task has no separate planning phase: the implementer states the
+// approach at the start of EXECUTION instead.
+export function phasesFor(profile) {
+  return profile?.size === "small" ? PHASES.filter(p => p !== "PLAN") : [...PHASES];
+}

package/cli/engine/verdict.mjs

@@ -64,7 +64,10 @@ export function verdictFromResult(result) {
 // reviewers' concrete list rather than re-deriving it.
 export function formatFindingsForRetry(verdict) {
   const lines = ["## Review findings to resolve", ""];
-  if (verdict.findings.length === 0 && verdict.unverifiedClaims.length === 0) {
+  if (verdict.approvalReason && verdict.outcome === "APPROVED") {
+    lines.push(`- **The reviewers approved, but the engine could not accept it** — ${verdict.approvalReason}. Re-verify at the current revision.`);
+  }
+  if (verdict.findings.length === 0 && verdict.unverifiedClaims.length === 0 && !verdict.approvalReason) {
     lines.push("- (review did not approve but listed no findings — re-verify every claim from the last execution)");
   }
   for (const f of verdict.findings) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kendoo.agentdesk/agentdesk",
-  "version": "0.29.3",
+  "version": "0.31.0",
   "description": "AI team orchestrator for Claude Code — run collaborative agent sessions from your terminal",
   "type": "module",
   "bin": {
@@ -22,7 +22,7 @@
     "server": "node server/index.mjs",
     "build": "vite build",
     "preview": "vite preview",
-    "test": "node --test tests/server.test.mjs tests/agents.test.mjs tests/homepage.test.mjs tests/sessionUtils.test.mjs tests/tracker-url.test.mjs tests/session-preflight.test.mjs tests/access.test.mjs tests/project-ownership.test.mjs tests/random-hex.test.mjs tests/projects-registry.test.mjs tests/phase-loop.test.mjs tests/proc.test.mjs tests/crypto.test.mjs tests/dotenv.test.mjs tests/update-check.test.mjs tests/setup-helpers.test.mjs tests/project-key.test.mjs tests/tracker-project.test.mjs tests/tracker-check.test.mjs tests/config.test.mjs tests/engine-env.test.mjs tests/engine-events.test.mjs tests/engine-verdict.test.mjs tests/engine-hooks.test.mjs tests/engine-agents.test.mjs tests/session-isolation.test.mjs tests/engine-session.test.mjs tests/engine-prompts.test.mjs tests/engine-schemas.test.mjs tests/engine-claude-auth.test.mjs tests/worktrees.test.mjs tests/workspaces-api.test.mjs tests/engine-outcome.test.mjs tests/session-outcomes.test.mjs tests/outcome-hydration.test.mjs tests/mobile-outcomes.test.mjs tests/session-queue.test.mjs tests/useFollowScroll.test.mjs tests/session-usage.test.mjs tests/task-lookup.test.mjs",
+    "test": "node --test tests/server.test.mjs tests/agents.test.mjs tests/homepage.test.mjs tests/sessionUtils.test.mjs tests/tracker-url.test.mjs tests/session-preflight.test.mjs tests/access.test.mjs tests/project-ownership.test.mjs tests/random-hex.test.mjs tests/projects-registry.test.mjs tests/phase-loop.test.mjs tests/proc.test.mjs tests/crypto.test.mjs tests/dotenv.test.mjs tests/update-check.test.mjs tests/setup-helpers.test.mjs tests/project-key.test.mjs tests/tracker-project.test.mjs tests/tracker-check.test.mjs tests/config.test.mjs tests/engine-env.test.mjs tests/engine-events.test.mjs tests/engine-verdict.test.mjs tests/engine-hooks.test.mjs tests/engine-agents.test.mjs tests/session-isolation.test.mjs tests/engine-session.test.mjs tests/engine-prompts.test.mjs tests/engine-schemas.test.mjs tests/engine-claude-auth.test.mjs tests/worktrees.test.mjs tests/workspaces-api.test.mjs tests/engine-outcome.test.mjs tests/session-outcomes.test.mjs tests/outcome-hydration.test.mjs tests/mobile-outcomes.test.mjs tests/session-queue.test.mjs tests/useFollowScroll.test.mjs tests/session-usage.test.mjs tests/task-lookup.test.mjs tests/engine-evidence.test.mjs tests/engine-handoff.test.mjs tests/engine-team-profile.test.mjs",
     "test:coverage": "node --test --experimental-test-coverage --test-coverage-include='cli/**' --test-coverage-include='server/**' --test-coverage-lines=60 --test-coverage-branches=62 tests/*.test.mjs",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",