@kendoo.agentdesk/agentdesk 0.32.0 → 0.33.0

package/cli/engine/hooks.mjs

@@ -8,49 +8,117 @@
 //
 // decidePreToolUse() is pure so the policy is unit-tested without the SDK.
 
+import { classify } from "./commands.mjs";
+
 export const MUTATING_TOOLS = Object.freeze(new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]));
 export const CODE_TOOLS = Object.freeze(new Set([...MUTATING_TOOLS, "Bash"]));
 
-// Commands that publish work. Matched loosely on purpose: `gh pr create`,
-// `git push`, `git push --force-with-lease origin HEAD`, chained after `&&`.
-const PUBLISH_RE = /(^|[;&|]\s*)(gh\s+pr\s+create|git\s+push)\b/;
-
+// Commands that publish work: `git push`, `gh pr create` and their relatives,
+// however they are spelled — `git -C . push`, `env git push`, on a later
+// line, inside `sh -c`, behind `sudo`. commands.mjs parses the shell text;
+// anything it cannot model fails closed when the text hints at publishing.
 export function isPublishCommand(command) {
-  return PUBLISH_RE.test(String(command || ""));
+  return classify(command).publishes;
 }
 
 // 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 || ""));
+  return classify(command).history;
 }
 
 // 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).
+// gate — not advisory" used to be prose; now it is an explicit verdict the
+// engine reads from his report and ties to the revision he audited.
 export const AUDITOR = "Sam";
 
+// The last line of the auditor's report. Bold or plain, any case; an
+// optional commit after the verdict is checked against the real HEAD.
+const AUDIT_LINE_RE = /^[ \t]*(?:\*\*)?AUDIT:?(?:\*\*)?[ \t]*(?:\*\*)?(APPROVED|REJECTED)(?:\*\*)?\b(?:[ \t]*(?:at|@)?[ \t]*`?([0-9a-f]{7,40})`?)?/gim;
+
+export const AUDIT_INSTRUCTION = `End your report with exactly one line, on its own: \`AUDIT: APPROVED\` when the committed revision has no violations left, or \`AUDIT: REJECTED — <one line why>\` when it does. The engine reads that line: without it, or after REJECTED, nothing can be published. Audit committed code — a commit made after your approval needs a new audit.`;
+
+export function parseAuditVerdict(text) {
+  const s = String(text || "");
+  let m, last = null;
+  AUDIT_LINE_RE.lastIndex = 0;
+  while ((m = AUDIT_LINE_RE.exec(s))) last = m;
+  if (!last) return { verdict: "MISSING", statedRevision: null };
+  return { verdict: last[1].toUpperCase(), statedRevision: last[2] || null };
+}
+
+// The text of a tool result, whatever shape the harness hands it in.
+export function responseText(response) {
+  if (response == null) return "";
+  if (typeof response === "string") return response;
+  if (Array.isArray(response)) return response.map(responseText).filter(Boolean).join("\n");
+  if (typeof response === "object") {
+    if (typeof response.text === "string") return response.text;
+    if (response.content !== undefined) return responseText(response.content);
+    if (typeof response.result === "string") return response.result;
+    if (typeof response.output === "string") return response.output;
+  }
+  return "";
+}
+
 // Called at the start of every EXECUTION: nothing may be published until the
-// auditor has run in this phase. `openFindings` (from a rejected REVIEW) is
-// carried for the denial message so the team sees what is outstanding.
+// auditor has approved in this phase. `openFindings` (from a rejected REVIEW)
+// is carried for the denial message so the team sees what is outstanding.
 export function armPublishGate(state, openFindings = []) {
   state.awaitingAudit = true;
+  state.audit = null;
   state.openFindings = Array.isArray(openFindings) ? openFindings : [];
 }
 
-export function onSubagentStopped(state, { phase, agentType }) {
-  if (phase === "EXECUTION" && agentType === AUDITOR) {
-    state.awaitingAudit = false;
-    state.openFindings = [];
+// Records the auditor's verdict for the tree as it is right now.
+//   tree — { revision, clean } observed by the engine when the report arrived
+// Returns the audit record, or null when the report is not the auditor's in
+// EXECUTION. The latest report wins: a re-audit after fixes replaces the old.
+export function recordAudit(state, { phase, agentType, text, tree }) {
+  if (phase !== "EXECUTION" || agentType !== AUDITOR) return null;
+  const { verdict, statedRevision } = parseAuditVerdict(text);
+  const revision = tree?.revision ?? null;
+  const stale = !!(statedRevision && revision && !revision.startsWith(statedRevision));
+  const audit = { verdict: stale ? "STALE" : verdict, revision, clean: tree?.clean ?? null, statedRevision, at: new Date().toISOString() };
+  state.audit = audit;
+  state.awaitingAudit = audit.verdict !== "APPROVED";
+  if (audit.verdict === "APPROVED") state.openFindings = [];
+  return audit;
+}
+
+const short = rev => (rev ? String(rev).slice(0, 7) : "?");
+
+function auditDenial(state, treeNow) {
+  const open = Array.isArray(state.openFindings) ? state.openFindings : [];
+  const audit = state.audit;
+  const fixThenAudit = `have ${AUDITOR} audit the committed revision, fix what he flags, commit, have him re-audit, then publish`;
+  if (state.awaitingAudit || open.length > 0) {
+    const list = open.slice(0, 5).map(f => `- ${f.title || f}`).join("\n");
+    const findings = open.length > 0 ? `${open.length} review finding(s) are unresolved:\n${list}\n` : "";
+    let why;
+    if (audit?.verdict === "REJECTED") why = `${AUDITOR}'s audit REJECTED the change`;
+    else if (audit?.verdict === "STALE") why = `${AUDITOR} approved ${short(audit.statedRevision)} but the code is at ${short(audit.revision)}`;
+    else if (audit?.verdict === "MISSING") why = `${AUDITOR}'s report did not end with an AUDIT line`;
+    else why = `${AUDITOR} has not audited in this phase`;
+    return `Cannot publish yet — ${findings}${why}; ${fixThenAudit}.`;
   }
+  if (audit?.verdict === "APPROVED") {
+    const tree = typeof treeNow === "function" ? treeNow() : null;
+    if (tree?.revision && audit.revision && tree.revision !== audit.revision) {
+      return `Cannot publish: ${AUDITOR} approved ${short(audit.revision)} but HEAD is now ${short(tree.revision)} — the approval covers only the revision he read. Have ${AUDITOR} audit the new commits, then publish.`;
+    }
+    if (state.requireClean && audit.clean === false) {
+      return `Cannot publish: ${AUDITOR} audited while the tree had uncommitted changes, so his approval is not tied to a commit. Commit, have ${AUDITOR} audit the commit, then publish.`;
+    }
+  }
+  return null;
 }
 
-// input — the SDK PreToolUseHookInput ({ tool_name, tool_input, agent_id?, agent_type? }).
-//         `agent_id` is present only inside a subagent (BaseHookInput docs).
-// state — mutable session state; reads `awaitingAudit` and `openFindings`.
-export function decidePreToolUse({ phase, input, state = {} }) {
+// input   — the SDK PreToolUseHookInput ({ tool_name, tool_input, agent_id?, agent_type? }).
+//           `agent_id` is present only inside a subagent (BaseHookInput docs).
+// state   — mutable session state; reads `awaitingAudit`, `audit`, `openFindings`, `requireClean`.
+// treeNow — () => { revision, clean }; consulted only for a publish command.
+export function decidePreToolUse({ phase, input, state = {}, treeNow = state.treeNow }) {
   const tool = input?.tool_name;
   const isMainThread = !input?.agent_id;
 
@@ -84,17 +152,8 @@ export function decidePreToolUse({ phase, input, state = {} }) {
   }
 
   if (phase === "EXECUTION" && tool === "Bash" && isPublishCommand(input?.tool_input?.command)) {
-    const open = Array.isArray(state.openFindings) ? state.openFindings : [];
-    if (state.awaitingAudit || open.length > 0) {
-      const list = open.slice(0, 5).map(f => `- ${f.title || f}`).join("\n");
-      const why = open.length > 0
-        ? `${open.length} review finding(s) are unresolved:\n${list}\n`
-        : "";
-      return {
-        decision: "deny",
-        reason: `Cannot publish yet — ${why}${AUDITOR} must audit the changed files in this phase first (have the lead delegate the audit to ${AUDITOR}, fix what he flags, then publish).`,
-      };
-    }
+    const reason = auditDenial(state, treeNow);
+    if (reason) return { decision: "deny", reason };
   }
 
   return { decision: "allow" };
@@ -111,10 +170,10 @@ function denyOutput(reason) {
 }
 
 // Build the SDK `hooks` option for one phase.
-//   state         — shared session state (openFindings, verifyPublish, ...)
+//   state         — shared session state (openFindings, audit, verifyPublish, treeNow, ...)
 //   onToolUse     — ({ agentType, tool, input }) for the dashboard
-//   onToolResult  — ({ agentType, tool, response }) for the dashboard
-//   onSubagentStop — ({ agentType }) when a subagent finishes
+//   onToolResult  — ({ agentType, tool, input, actionId, response }) for the dashboard and the audit
+//   onSubagentStop — ({ agentType, text }) when a subagent finishes; `text` is its last message when the harness provides it
 //   verifyTimeoutSec — hook timeout for PreToolUse; publishing may run the
 //                      project's checks inside the hook (state.verifyPublish)
 export function hooksForPhase({ phase, state, onToolUse, onToolResult, onSubagentStop, verifyTimeoutSec } = {}) {
@@ -144,7 +203,7 @@ export function hooksForPhase({ phase, state, onToolUse, onToolResult, onSubagen
     }],
     SubagentStop: [{
       hooks: [async (input) => {
-        onSubagentStop?.({ agentType: input.agent_type || null });
+        onSubagentStop?.({ agentType: input.agent_type || null, text: typeof input.last_assistant_message === "string" ? input.last_assistant_message : null });
         return {};
       }],
     }],

package/cli/engine/lessons.mjs

@@ -0,0 +1,156 @@
+// Project lessons with provenance — an engine-owned ledger.
+//
+// `.agentdesk/memory.md` was free text the agents edited themselves: no
+// source, no scope, no way to correct or retire an entry, and in a worktree
+// session it was read from the worktree, where it never existed. This ledger
+// lives in the *source* project directory (shared by every worktree; local,
+// gitignored). Agents never write it: SUMMARY and SOLO propose lessons and
+// retirements in their structured handoff, the engine records them with
+// where they came from, and the engine's own verdict on the session decides
+// whether a lesson is `active` (session ended `complete`) or only `proposed`.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { TOUCH_AREAS } from "./team-profile.mjs";
+import { shortRev } from "./evidence.mjs";
+
+export const LESSON_STATUSES = Object.freeze(["proposed", "active", "retired"]);
+export const MAX_LESSONS = 500;        // ledger size; oldest retired, then oldest proposed, go first
+export const MAX_LESSON_TEXT = 1000;   // stored text
+export const MAX_LESSON_NOTE = 500;    // stored evidence / retirement reason
+export const INJECT_LIMIT = 30;        // entries per prompt
+export const INJECT_TEXT_LIMIT = 300;  // characters per entry in a prompt
+
+export function lessonsPath(sourceCwd) {
+  return join(sourceCwd, ".agentdesk", "lessons.json");
+}
+
+const EMPTY = () => ({ version: 1, lessons: [] });
+
+export function readLessons(path) {
+  try {
+    if (!existsSync(path)) return EMPTY();
+    const data = JSON.parse(readFileSync(path, "utf8"));
+    if (!data || data.version !== 1 || !Array.isArray(data.lessons)) return EMPTY();
+    return { version: 1, lessons: data.lessons.filter(l => l && typeof l.id === "string" && typeof l.text === "string") };
+  } catch { return EMPTY(); }
+}
+
+export function writeLessons(path, data) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(`${path}.tmp`, JSON.stringify(data, null, 2), { mode: 0o600 });
+  renameSync(`${path}.tmp`, path);
+}
+
+// "project" | "area:<ui|copy|docs|api|data>" | "path:<relative prefix>".
+// Anything else widens to "project" — the safe direction for a hint.
+export function normalizeScope(scope) {
+  const s = String(scope ?? "").trim();
+  if (s === "project") return s;
+  const area = s.match(/^area:([a-z]+)$/);
+  if (area) return TOUCH_AREAS.includes(area[1]) ? s : "project";
+  const path = s.match(/^path:(.+)$/);
+  if (path) {
+    const prefix = path[1].trim().replace(/^\.\//, "");
+    if (prefix && prefix.length <= 200 && !prefix.startsWith("/") && !prefix.split("/").includes("..")) return `path:${prefix}`;
+  }
+  return "project";
+}
+
+const clean = (text, max) => String(text ?? "").replace(/\s+/g, " ").trim().slice(0, max);
+const textKey = text => clean(text, MAX_LESSON_TEXT).toLowerCase();
+const newId = () => randomBytes(4).toString("hex");
+const byAge = (a, b) => String(a.createdAt).localeCompare(String(b.createdAt));
+
+// When the ledger outgrows MAX_LESSONS, drop the oldest retired entries, then
+// the oldest proposed ones. Active lessons are never dropped here.
+function bounded(list) {
+  const keep = [...list];
+  for (const status of ["retired", "proposed"]) {
+    while (keep.length > MAX_LESSONS) {
+      const victim = keep.filter(l => l.status === status).sort(byAge)[0];
+      if (!victim) break;
+      keep.splice(keep.indexOf(victim), 1);
+    }
+  }
+  return keep;
+}
+
+// Apply a single proposal to the lessons list, mutating list and counts.
+function applyProposal({ list, proposal, source, complete, at, counts }) {
+  const text = clean(proposal?.text, MAX_LESSON_TEXT);
+  if (!text) return;
+  const key = textKey(text);
+  const existing = list.find(l => l.status !== "retired" && textKey(l.text) === key);
+  if (existing) {
+    if (!complete) return; // an unverified session cannot confirm anything
+    if (!existing.confirmedBy.includes(source.sessionId)) existing.confirmedBy.push(source.sessionId);
+    if (existing.status === "proposed") { existing.status = "active"; counts.activated++; } else counts.confirmed++;
+    return;
+  }
+  list.push({
+    id: newId(), text, scope: normalizeScope(proposal?.scope), evidence: clean(proposal?.evidence, MAX_LESSON_NOTE),
+    source: { sessionId: source.sessionId, taskId: source.taskId || null, phase: source.phase, agent: source.agent, revision: source.revision || null },
+    createdAt: at, status: complete ? "active" : "proposed", confirmedBy: complete ? [source.sessionId] : [],
+  });
+  if (complete) counts.activated++; else counts.proposed++;
+}
+
+// Apply a single retirement to the lessons list, mutating list and counts.
+function applyRetirement({ list, retirement, source, at, counts }) {
+  const index = list.findIndex(l => l.id === retirement?.id);
+  if (index < 0 || list[index].status === "retired") return;
+  if (list[index].source?.sessionId === source.sessionId) { list.splice(index, 1); counts.dropped++; return; }
+  list[index] = { ...list[index], status: "retired", retired: { sessionId: source.sessionId, reason: clean(retirement?.reason, MAX_LESSON_NOTE), at } };
+  counts.retired++;
+}
+
+// Records what a session's SUMMARY/SOLO handed back. `complete` is the
+// engine's verdict on the whole session (verified approval), not the agents'.
+export function recordLessons({ path, proposals = [], retirements = [], source, complete = false, now = () => new Date().toISOString() }) {
+  const data = readLessons(path);
+  const list = data.lessons;
+  const at = now();
+  const counts = { activated: 0, proposed: 0, confirmed: 0, retired: 0, dropped: 0 };
+
+  for (const p of Array.isArray(proposals) ? proposals : []) {
+    applyProposal({ list, proposal: p, source, complete, at, counts });
+  }
+
+  for (const r of Array.isArray(retirements) ? retirements : []) {
+    applyRetirement({ list, retirement: r, source, at, counts });
+  }
+
+  const changed = Object.values(counts).some(n => n > 0);
+  data.lessons = bounded(list);
+  if (changed) writeLessons(path, data);
+  return { ...counts, changed, lessons: data.lessons };
+}
+
+// Active lessons in scope, newest first, bounded — what a prompt gets.
+export function selectLessons({ lessons = [], touches = [...TOUCH_AREAS], limit = INJECT_LIMIT, textLimit = INJECT_TEXT_LIMIT } = {}) {
+  const inScope = l => l.scope === "project" || String(l.scope).startsWith("path:")
+    || (String(l.scope).startsWith("area:") && touches.includes(String(l.scope).slice(5)));
+  return lessons
+    .filter(l => l.status === "active" && inScope(l))
+    .sort((a, b) => byAge(b, a))
+    .slice(0, limit)
+    .map(l => ({ ...l, text: l.text.length > textLimit ? `${l.text.slice(0, textLimit - 1)}…` : l.text }));
+}
+
+export function renderLessonsSection(lessons = []) {
+  if (!lessons.length) return "";
+  const lines = [
+    "## PROJECT LESSONS",
+    "",
+    "Recorded by the engine from earlier sessions on this project, newest first, each with its id and where it came from. Apply them. If one proved wrong or obsolete in this session, retire it in the SUMMARY handoff (`retireLessons`, with the id and why) — never edit files to change them.",
+    "",
+  ];
+  for (const l of lessons) {
+    const from = [l.source?.taskId, l.source?.phase, l.source?.revision ? shortRev(l.source.revision) : null, String(l.createdAt || "").slice(0, 10)]
+      .filter(Boolean).join(" · ");
+    lines.push(`- [${l.id}] (${l.scope}) ${l.text}${l.evidence ? ` — evidence: ${l.evidence}` : ""}${from ? ` — from ${from}` : ""}`);
+  }
+  return lines.join("\n");
+}

package/cli/engine/phases/EXECUTION.md

@@ -14,7 +14,7 @@ The reviewers returned the following. Work from this list; do not re-derive it.
 ## Rules
 
 - 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.
+- **Sam's audit is a blocking gate.** After Dennis implements and commits, Sam must read every changed file and run his full checklist, citing file:line for every finding — "looks clean" without evidence is invalid. Sam ends his report with `AUDIT: APPROVED` or `AUDIT: REJECTED — <why>`; the engine reads that line and ties an approval to the commit he audited. Publishing is refused without an approval for the current commit: after REJECTED, Dennis fixes and commits and Sam re-audits; any commit made after an approval needs a new audit too.
 {{#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.
 
@@ -36,10 +36,12 @@ Screenshots are **disabled** for this project. Do not capture any unless the use
 {{#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.
+2. **Sam audits the commit** — every changed file, full checklist (feature envy, separation of concerns, clear interfaces, layering, god files), file:line for each finding, closing with his `AUDIT:` line. If there are violations, send Dennis back to fix and commit them, then have Sam re-audit.
 3. **Vera tests** — unit/regression tests for the changed code, run and verified, committed.
 {{#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.
+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. Sam's approval must cover the commit being published: if anyone committed after his audit (Vera's tests, a specialist's change), have Sam audit the new commits first — a short re-audit is enough.
 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).
 
+After each report, decide whether its assignment is accepted, needs a specific correction, or is blocked. Name the next owner and action. Keep unmet acceptance criteria visible and send incomplete work back to its owner; do not simply pass the report to the next agent. If a required check cannot run, assign a bounded attempt to restore it and retain the requirement as unverified if that fails. For example, a CSS class assertion alone does not establish rendered button clearance. Preserve required audit gates when resolving disagreements, and keep unrelated cleanup out of this task. Carry accepted evidence in `qaResults` and unresolved criteria, blockers and their next owners/actions in `reviewerAttention`.
+
 The structured output required by the schema is captured automatically — what was implemented, files changed, the PR URL (empty string if none), QA results, issues fixed, and what the reviewers should look at. Do not repeat the JSON object in chat; keep any closing chat message brief and human-readable.

package/cli/engine/phases/INTAKE.md

@@ -28,7 +28,8 @@ Task description:
    - explore the code relevant to the task and report the patterns he finds.
    Ask him to report everything back plainly — you decide what matters.
 2. **Tracker session start.** Dictate the exact comment text ("Team session started. Session: {{SESSION_URL}}") and ask Dennis to post it and move the task to "In Progress", confirming with the command output.
-3. **Assess scope.** Restate the task as user outcomes and acceptance criteria. If it is too large for one session, decompose it into subtasks (basic vs deferred) in product terms and have Dennis create them in the tracker.
+3. **Set the delivery target.** Reconcile the original task, latest user corrections, and existing work. State what remains to deliver and what evidence will close each acceptance criterion. A previous agent's deferral is not permission to omit something the user now explicitly requires. Make routine scope interpretations yourself; ask only when missing information or a consequential choice cannot be resolved by the team. Decompose large work into owned steps without silently deferring requested scope; obtain a user decision if completing the request requires changing that scope.
 4. Announce `SESSION_TITLE: <4-8 word title>` on its own line.
+5. **Hand over a direction.** Put the current acceptance criteria in `requirements`, accepted facts and scope decisions in `assessment`, and the next owner, action and required evidence in `nextPhaseFocus`. Distinguish confirmed work from claims still needing verification.
 
 The structured output required by the schema is captured automatically — title, task summary, requirements, assessment (branches, PRs, patterns, resume context), subtasks, and what PLAN should focus on. Do not repeat the JSON object in chat; keep any closing chat message brief and human-readable.

package/cli/engine/phases/PLAN.md

@@ -7,13 +7,13 @@ Task: {{TASK_ID}}
 
 - Follow CLAUDE.md conventions (if present). Do not modify files unrelated to the task.
 - No code and no file changes in this phase. Plan only.
-- Sam's audit is a blocking gate in EXECUTION: the plan must leave room for it. The PR cannot be created until Sam signs off with file:line evidence.
+- Order the work correctly: PLAN chooses the approach; EXECUTION starts with implementation and tests; Sam then audits the resulting changes inside EXECUTION; approval permits publishing. Sam's code audit gates publishing, not entry into EXECUTION. Do not create a circular dependency by requiring an audit of unwritten changes before implementation can start.
 
 {{TRACKER_SECTION}}
 
 ## Your mission
 
-1. Restate the task in product terms — what the user gets, acceptance criteria, scope boundaries. No file names, no jargon.
+1. Set the delivery target — what the user gets, acceptance criteria, scope boundaries, and the highest-priority unresolved requirement. Explain technical constraints when they affect the decision.
 2. **Delegate in parallel** to the team, each with the task summary and requirements from session memory. Ask each to verify assumptions with tools (Glob, Grep, Read) — no guessing — and to report:
    - Dennis: implementation plan — files to modify, approach, complexity (S/M/L).
    - Sam: architecture review — existing patterns, module boundaries, whether the approach keeps concerns separated.
@@ -21,6 +21,7 @@ Task: {{TASK_ID}}
 {{#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.
+3. **Choose the plan.** Compare the proposals against acceptance criteria, existing project conventions and evidence. Ask for objections once; resolve factual disagreements with a focused check and record the decision and reason. Make routine implementation choices within the authorized scope without sending them back to the user. Do not brainstorm beyond two rounds.
+4. **Assign accountable work.** Each step needs one owner, dependencies, a bounded deliverable and the evidence that will demonstrate acceptance. Put these in `assignments` and `steps`; put tradeoffs and rationale in `decisions`. Include every required acceptance criterion and identify real blockers in `risks`.
 
 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

@@ -16,7 +16,7 @@ Task: {{TASK_ID}}
    - **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`.
+2. **Own the acceptance decision.** Reconcile conflicting reports against the current user requirements and direct observations. Request a focused check when evidence conflicts. Be strict but not pedantic: only actual gaps against the task requirements and the plan — not stylistic preferences or speculative refactors. An agent saying "done" or a majority vote cannot override a failed check, a missing observation, or a required acceptance criterion.
+3. Decide: `APPROVED` only when required outcomes have evidence and no blocking finding remains; otherwise `NEEDS_MORE_WORK`. For each finding, write `Owner: <agent name>; Action: <specific corrective work>; Accept when: <required observation>` in its `detail` so EXECUTION can act immediately. Assign implementation fixes to Dennis, test gaps to Vera, and missing user-flow or rendered acceptance checks to Bart. The reviewer field identifies who found the gap and does not replace the corrective owner. Reserve `deferred` for work explicitly outside the authorized scope or deferred by the user; a previous agent's convenience deferral does not remove a requirement.
 
 The structured output required by the schema is captured automatically — the verdict, the findings (reviewer, title, detail, file, line), items explicitly out of scope, and any claims that were not backed by an observation. Do not repeat the JSON object in chat; keep any closing chat message brief and human-readable.

package/cli/engine/phases/SOLO.md

@@ -112,4 +112,8 @@ This keeps everything in one branch — no conflicts, one PR to review.
 If the task has no child items, just work on it normally as a single task.
 {{/CHILD_TASKS}}
 
-The structured output required by the schema is captured automatically — a summary of what was done, files changed, the PR URL (empty string if none), deferred items, and manual steps. Do not repeat the JSON object in chat; keep any closing chat message brief and human-readable.
+## Lessons for future sessions
+
+The handoff has `lessons` and `retireLessons`. Propose a lesson only for something non-obvious that cost you time and would cost the next session too — a setup step, seed data, an environment quirk, a deployment step. Each needs the evidence (the command and its outcome) and a scope: `project`, `area:<ui|copy|docs|api|data>`, or `path:<file or directory prefix>`. Never store secrets — name the env var instead. Do not restate what README, CLAUDE.md or the code already says. If an entry under PROJECT LESSONS proved wrong or obsolete, retire it by its id with the reason. Empty arrays are the normal case.
+
+The structured output required by the schema is captured automatically — a summary of what was done, files changed, the PR URL (empty string if none), deferred items, manual steps, lessons, and retirements. Do not repeat the JSON object in chat; keep any closing chat message brief and human-readable.

package/cli/engine/phases/SUMMARY.md

@@ -12,12 +12,13 @@ Task: {{TASK_ID}}
 
 ## Your mission
 
-1. Dictate the final summary in product terms. It must include:
+1. **Own the delivery report.** Reconcile the latest review and engine verification before dictating the summary. Distinguish delivered, unverified, blocked and user-approved deferred items. If review remains unresolved, report the work as incomplete; do not describe it as ready or substitute a successful test for an unmet acceptance criterion. It must include:
    - **What was done** — outcome-focused, non-technical.
    - **What was omitted / deferred** — everything from REVIEW's out-of-scope list plus anything the team explicitly skipped.
-   - **Manual steps** — actions the developer must perform (migrations, config, deploys).
+   - **Manual steps** — every remaining action outside this session, including access recovery, migrations, config and deploys. Name the responsible person or role and how completion will be confirmed. Required work blocked on access is not an out-of-scope deferral.
    - **PR link**.
    - **Session link**: {{SESSION_URL}}
-2. Delegate the tracker writes to Dennis and require the command output for each: verify the PR link is attached (attach it if missing), transition the task to "In Review", post the final comment.
+2. Delegate the tracker writes to Dennis and require the command output for each: verify the existing PR link is attached (attach it if missing), transition the task to "In Review" only when the review and engine verification permit it, and post the accurate final comment. If a write fails, identify the blocker in `status` and put the recovery owner/action in `manualSteps`, including who retries delivery after access is restored and the receipt needed to confirm it. Do not leave `manualSteps` empty when an access fix is required. Put only the confirmed posted text in `summaryComment`, leaving it empty if posting was not confirmed. The final user-facing update must state the outcome and any remaining action with its owner.
+3. **Lessons for future sessions.** The handoff has `lessons` and `retireLessons`. Propose a lesson only for something non-obvious that cost this session time and would cost the next one too — a setup step, seed data, an environment quirk, a deployment step, a review finding that keeps recurring. Each needs the evidence (what happened: the command and its outcome) and a scope: `project`, `area:<ui|copy|docs|api|data>`, or `path:<file or directory prefix>`. Never store secrets — name the env var instead. Do not restate what README, CLAUDE.md or the code already says. If an entry under PROJECT LESSONS proved wrong or obsolete in this session, retire it by its id with the reason. Empty arrays are the normal case.
 
-The structured output required by the schema is captured automatically — status, PR URL, deferred items, manual steps, and the summary comment exactly as posted. Do not repeat the JSON object in chat; keep any closing chat message brief and human-readable.
+The structured output required by the schema is captured automatically — status, PR URL, deferred items, manual steps, the summary comment exactly as posted, lessons, and retirements. Do not repeat the JSON object in chat; keep any closing chat message brief and human-readable.

package/cli/engine/prompts.mjs

@@ -10,11 +10,12 @@
 import { readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
-import { wrapUntrusted, PROMPT_SECURITY_HEADER, MEMORY_INSTRUCTIONS, loadProjectMemory } from "../prompt.mjs";
+import { wrapUntrusted, PROMPT_SECURITY_HEADER, LEGACY_NOTES_HEADER } from "../prompt.mjs";
 import { generateContext } from "../detect.mjs";
 import { formatFindingsForRetry } from "./verdict.mjs";
 import { formatEvidenceForPrompt } from "./evidence.mjs";
 import { renderOpenItems } from "./handoff.mjs";
+import { renderLessonsSection } from "./lessons.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 
@@ -40,6 +41,16 @@ export function renderTemplate(text, { flags = new Set(), vars = {} } = {}) {
   return out;
 }
 
+// Engine-provided project knowledge: active lessons in scope, then the
+// hand-written notes from before the ledger existed (read-only).
+function projectKnowledge({ lessons = [], projectNotes = "" }) {
+  let out = "";
+  const block = renderLessonsSection(lessons);
+  if (block) out += `\n\n${block}`;
+  if (projectNotes) out += `\n\n${LEGACY_NOTES_HEADER}\n\n${projectNotes}`;
+  return out;
+}
+
 function trackerSection(tracker, phases, vars) {
   if (!tracker) return "";
   let text;
@@ -67,7 +78,7 @@ function soloSearchAndCreate({ tracker, config }) {
 // tools, no lead and no review gate. Ported from the legacy buildSoloPrompt.
 export function renderSoloPrompt({
   agent, taskId, taskLink, description, tracker, config = {}, project = {},
-  sessionUrl, cwd, childStrategy,
+  sessionUrl, childStrategy, lessons = [], projectNotes = "",
 }) {
   const hasRealTaskId = !!taskId && !String(taskId).startsWith("new-") && !String(taskId).startsWith("task-");
   const vars = {
@@ -104,9 +115,7 @@ export function renderSoloPrompt({
   }
   if (config.instructions) body += `\n\n## ADDITIONAL INSTRUCTIONS\n\n${config.instructions}`;
 
-  body += `\n\n${MEMORY_INSTRUCTIONS}`;
-  const memory = loadProjectMemory(cwd);
-  if (memory) body += `\n\n### Current memory\n\n${memory}`;
+  body += projectKnowledge({ lessons, projectNotes });
 
   const context = generateContext(project);
   const now = new Date();
@@ -135,8 +144,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, openItems = [],
-  roster = null, profile = null, handoffRetry = false,
+  sessionUrl, sessionMemory = "", retryVerdict = null, evidence = null, openItems = [],
+  roster = null, profile = null, handoffRetry = false, lessons = [], projectNotes = "",
 }) {
   const vars = {
     TASK_ID: taskId,
@@ -187,9 +196,7 @@ export function renderPhasePrompt({
     body += `\n\n## SESSION MEMORY (previous phases)\n\n${sessionMemory}`;
   }
 
-  body += `\n\n${MEMORY_INSTRUCTIONS}`;
-  const memory = loadProjectMemory(cwd);
-  if (memory) body += `\n\n### Current memory\n\n${memory}`;
+  body += projectKnowledge({ lessons, projectNotes });
 
   if (config.projectAgents?.length) {
     project.configAgents = config.projectAgents.map(a => ({ ...a, type: a.type || "declared", source: ".agentdesk.json" }));

package/cli/engine/recovery.mjs

@@ -0,0 +1,101 @@
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { PHASE_OUTPUT_SCHEMAS } from "./schemas.mjs";
+
+export function checkpointStore(directory, sessionId, { resume = false } = {}) {
+  mkdirSync(directory, { recursive: true });
+  const path = join(directory, `recovery-${createHash("sha256").update(sessionId).digest("hex").slice(0, 24)}.json`);
+  let data = { version: 1, sessionId, queue: null, receipts: {}, outcomes: [], instructions: [], transcript: [], totals: null };
+  if (resume) {
+    if (!existsSync(path)) throw new Error("No recovery checkpoint exists for this session. Start a separately reviewed continuation instead.");
+    data = JSON.parse(readFileSync(path, "utf8"));
+    if (data.version !== 1 || data.sessionId !== sessionId) throw new Error("Recovery checkpoint does not match this session.");
+  }
+  const save = patch => {
+    data = { ...data, ...patch };
+    writeFileSync(`${path}.tmp`, JSON.stringify(data), { mode: 0o600 });
+    renameSync(`${path}.tmp`, path);
+  };
+  return { get data() { return data; }, save, path };
+}
+
+export function validHandoff(phase, value) {
+  const matches = (schema, v) => {
+    if (schema.type === "object") return !!v && typeof v === "object" && !Array.isArray(v)
+      && (schema.required || []).every(k => k in v)
+      && Object.entries(v).every(([k, item]) => schema.properties?.[k] ? matches(schema.properties[k], item) : schema.additionalProperties !== false);
+    if (schema.type === "array") return Array.isArray(v) && v.every(item => matches(schema.items, item));
+    if (schema.type === "string") return typeof v === "string" && (!schema.enum || schema.enum.includes(v));
+    if (schema.type === "integer") return Number.isInteger(v);
+    return true;
+  };
+  return !!PHASE_OUTPUT_SCHEMAS[phase] && matches(PHASE_OUTPUT_SCHEMAS[phase], value);
+}
+
+// Conservative journal for externally visible commands. Exact repeats are
+// refused; uncertain responses require reconciliation, never automatic replay.
+export function externalActionKey(tool, input = {}) {
+  const command = String(input.command || "");
+  const external = tool.startsWith("mcp__") && /create|update|delete|transition|comment|post|send/i.test(tool) || (tool === "Bash" && (
+    /\bgh\s+(?:pr|issue)\s+(?:create|comment|edit|merge|close|reopen)\b/.test(command)
+    || /\bcurl\b/.test(command) && /(?:--data|-d\b|-X\s*(?:POST|PUT|PATCH|DELETE)|--request\s+(?:POST|PUT|PATCH|DELETE))/.test(command)
+  ));
+  if (!external) return null;
+  const canonical = value => Array.isArray(value) ? value.map(canonical)
+    : value && typeof value === "object" ? Object.fromEntries(Object.keys(value).sort().map(k => [k, canonical(value[k])])) : value;
+  // Bash descriptions/timeouts are presentation, not the external action.
+  return createHash("sha256").update(JSON.stringify([tool, tool === "Bash" ? command.trim() : canonical(input)])).digest("hex");
+}
+
+export function journalExternalActions(options, recovery) {
+  const previousPre = options.hooks.PreToolUse[0].hooks[0];
+  options.hooks.PreToolUse[0].hooks[0] = async input => {
+    const decision = await previousPre(input);
+    if (decision.hookSpecificOutput?.permissionDecision === "deny") return decision;
+    const key = externalActionKey(input.tool_name, input.tool_input);
+    if (!key) return decision;
+    const receipt = recovery.data.receipts[key];
+    if (receipt) return { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny",
+      permissionDecisionReason: `This external action is recorded as ${receipt.state}. Do not repeat or reword it to bypass this guard. Inspect the provider to reconcile its result; preserve the existing PR/comment.` } };
+    recovery.save({ receipts: { ...recovery.data.receipts, [key]: { state: "pending", tool: input.tool_name, at: Date.now() } } });
+    return decision;
+  };
+  const previousPost = options.hooks.PostToolUse[0].hooks[0];
+  options.hooks.PostToolUse[0].hooks[0] = async input => {
+    const result = await previousPost(input);
+    const key = externalActionKey(input.tool_name, input.tool_input);
+    if (key && recovery.data.receipts[key]) {
+      // A tool returning is not proof of an external write succeeding. Only
+      // the provider-specific outcome parser can produce a confirmed receipt.
+      recovery.save({ receipts: { ...recovery.data.receipts, [key]: { ...recovery.data.receipts[key], state: "response-received" } } });
+    }
+    return result;
+  };
+}
+
+export function repairQueryOptions(options) {
+  return { ...options, agents: {}, agent: undefined, allowedTools: ["StructuredOutput"], tools: ["StructuredOutput"], mcpServers: {},
+    hooks: { PreToolUse: [{ hooks: [async input => input.tool_name === "StructuredOutput" ? {} : {
+      hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: "Handoff repair cannot execute tools." },
+    }] }] }, maxTurns: 2 };
+}
+
+export function trackerAccessDenied(denials) {
+  return denials.some(d => /mcp__.*(?:jira|atlassian|linear|github)/i.test(d.tool_name || "")
+    || d.tool_name === "Bash" && /\bcurl\b|\bgh\s+(?:issue|pr)\s+(?:view|list)\b/.test(d.tool_input?.command || ""));
+}
+
+export function recoveryBrief(data, tree) {
+  return [
+    "## Authoritative task and user instructions",
+    `Original task: ${data.taskId || ""}\n${data.description || ""}`,
+    "Stay within this objective. Propose unrelated discoveries separately; do not expand scope to repair lost context.",
+    ...data.instructions.map((i, n) => `${n + 1}. ${i.text}`),
+    "Latest user corrections override earlier plans. Acknowledge their effect before working.",
+    `Current revision: ${tree.revision || "unknown"}; working tree clean: ${tree.clean}. Preserve unfinished edits. Inspect the diff and existing PR before continuing. Prior verification must be re-established.`,
+    `Recorded external actions: ${JSON.stringify(data.receipts)}`,
+    `Confirmed provider outcomes: ${JSON.stringify(data.outcomes || [])}`,
+    "Do not repeat confirmed actions. A pending or response-received entry is uncertain: reconcile it against the provider first. Never reword commands to bypass the replay guard. Never claim an action failed merely because this phase cannot access the provider.",
+  ].join("\n\n");
+}