@kendoo.agentdesk/agentdesk 0.30.0 → 0.31.1

package/CHANGELOG.md

@@ -8,6 +8,21 @@ All user-facing changes to AgentDesk. Each entry is tagged:
 
 Internal refactors, infrastructure changes, and architectural notes are not listed here.
 
+## [0.31.1] — 2026-09-21
+
+### Fixed
+- `[Both]` Saving project settings without credentials (which the CLI's config sync does by design) no longer erases the stored Jira, Linear or GitHub credentials, and no longer resets settings the write did not mention. 0.31.0 made the CLI re-sync settings on every run, which wiped tracker credentials for affected projects — if pre-flight says your tracker email or token is missing, re-enter it once in project settings.
+
+## [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

package/README.md

@@ -267,6 +267,10 @@ The `REVIEW` phase is a read-only completeness check (no code changes) — it ve
 
 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.

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
@@ -129,13 +134,19 @@ export async function loadConfig(dir, opts = {}) {
 // True when `local` has any non-null leaf that's null/missing on `server`.
 // Walked recursively for nested blocks (linear, jira, github). Used to
 // decide whether it's worth pushing a heal sync.
-function hasFieldsServerLacks(local, server) {
+//
+// Only fields the server actually accepts (SETTINGS_FIELDS) count at the top
+// level: a local-only field such as teamProfile can never be "healed", and
+// treating it as a gap made every run push a credential-free payload —
+// which is what a heal push is, by design — forever.
+function hasFieldsServerLacks(local, server, top = true) {
   const isObj = v => v && typeof v === "object" && !Array.isArray(v);
   for (const [key, v] of Object.entries(local || {})) {
+    if (top && !SETTINGS_FIELDS.includes(key)) continue;
     if (v === null || v === undefined) continue;
     const s = server?.[key];
     if (isObj(v)) {
-      if (!isObj(s) || hasFieldsServerLacks(v, s)) return true;
+      if (!isObj(s) || hasFieldsServerLacks(v, s, false)) return true;
     } else {
       if (s === null || s === undefined) return true;
     }

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

@@ -51,12 +51,23 @@ 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 { clean = git(cwd, ["status", "--porcelain"], extraEnv) === ""; } catch {}
+  try {
+    const lines = git(cwd, ["status", "--porcelain"], extraEnv).split("\n").filter(Boolean);
+    clean = lines.every(isEngineFile);
+  } catch {}
   return { revision, clean };
 }
 

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/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

@@ -14,6 +14,7 @@ import { wrapUntrusted, PROMPT_SECURITY_HEADER, MEMORY_INSTRUCTIONS, loadProject
 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));
 
@@ -134,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, evidence = null,
+  sessionUrl, cwd, sessionMemory = "", retryVerdict = null, evidence = null, openItems = [],
+  roster = null, profile = null,
 }) {
   const vars = {
     TASK_ID: taskId,
@@ -150,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();
@@ -166,6 +179,7 @@ export function renderPhasePrompt({
   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,14 +17,14 @@ 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";
@@ -33,6 +33,8 @@ import {
   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";
@@ -215,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`);
@@ -247,6 +251,11 @@ async function executeSession({
   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 });
@@ -271,6 +280,7 @@ async function executeSession({
     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") {
@@ -294,13 +304,16 @@ async function executeSession({
   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 {}
     }
   };
 
-  const queue = solo ? ["SOLO"] : [...PHASES];
+  // --- 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) {
@@ -312,6 +325,13 @@ 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" });
@@ -329,6 +349,7 @@ async function executeSession({
         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;
         }
       }
@@ -339,7 +360,7 @@ async function executeSession({
 
       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({
@@ -349,6 +370,10 @@ async function executeSession({
           sessionMemory: memoryText(),
           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`;
@@ -410,6 +435,7 @@ 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;
       }
 
@@ -419,6 +445,7 @@ async function executeSession({
         const approval = evaluateApproval({ verdict, evidence, headNow: now });
         appendMemory(renderMemorySection("REVIEW", summary.structuredOutput));
         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;
       }
 
@@ -427,9 +454,28 @@ 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);
@@ -462,5 +508,7 @@ async function executeSession({
     aborted, status, reviewResolved, lastPhase,
     verdict: lastVerdict,
     approvedRevision: reviewResolved ? approvedRevision : null,
+    openItems,
+    profile,
   };
 }

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kendoo.agentdesk/agentdesk",
-  "version": "0.30.0",
+  "version": "0.31.1",
   "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 tests/engine-evidence.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 tests/project-settings.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",