scrumrun 2.5.1 → 2.6.1

package/lib/runtime/orchestrator.js

@@ -15,11 +15,12 @@ const {
   withArtifactLock
 } = require("../v2/artifacts");
 const { buildContextPackage } = require("./context");
-const { evaluatePolicy } = require("./policy-engine");
+const { agentIdentity, evaluatePolicy } = require("./policy-engine");
 const { artifactSnapshot, canonicalFingerprint, canonicalWatchSnapshot } = require("./canonical-snapshot");
 const { decodeApproval } = require("./request-engine");
 const { extractLearningCandidates } = require("../code-intel/learning");
-const { appendRunEvent, createRunBody, instant } = require("./run-ledger");
+const { appendRunEvent, appendTechnicalSummary, createRunBody, instant } = require("./run-ledger");
+const { generateBriefing } = require("./briefing");
 const { policyState, prepareCompletion, publicWorkspace, verifyWorkspaceIntegrity, workspaceState } = require("./mutation-gateway");
 const { recoverPendingTransactions, runKernelTransaction } = require("../v2/transaction");
 
@@ -48,16 +49,7 @@ function stateFingerprint(repository) {
 }
 
 function stateProjection(repository) {
-  const snapshot = artifactSnapshot(repository.scrumDir);
-  const linesFor = (kinds) => kinds.flatMap((kind) => (snapshot.records[kind] || [])
-    .filter((record) => record.id && !TERMINAL.has(record.status))
-    .map((record) => `- ${record.id} | ${kind} | ${record.status} | ${record.title || record.id}`));
-  const work = linesFor(["feature", "task", "sprint", "run", "review"]);
-  const memory = linesFor(["decision", "knowledge", "insight", "dossier"]);
-  const sourceFingerprint = canonicalFingerprint(repository.scrumDir, snapshot.hashes);
-  const watch = canonicalWatchSnapshot(repository.scrumDir);
-  const content = `# ScrumRun State\n\nProjection schema: 1\nGenerated: ${new Date().toISOString()}\nSource fingerprint: ${sourceFingerprint}\nWatch fingerprint: ${watch.fingerprint}\nAuthority: none; rebuild from canonical artifacts.\n\n## Active Work\n\n${work.length ? work.join("\n") : "- No active canonical work."}\n\n## Relevant Memory\n\n${memory.length ? memory.join("\n") : "- No active canonical memory."}\n`;
-  return { content, sourceFingerprint, watchFingerprint: watch.fingerprint, sourceFiles: watch.files };
+  return generateBriefing(repository.scrumDir, repository);
 }
 
 function renderState(repository) {
@@ -122,6 +114,7 @@ function approveRequestUnlocked(projectRoot, token, { failurePoint = null, inter
     method: METHOD_VERSION,
     feature: null,
     sprint: null,
+    assignee: agentIdentity(scrumDir) || "agent",
     approval_id: approvalId,
     context_fingerprint: payload.fingerprint,
     risk: payload.risk.level
@@ -141,7 +134,8 @@ function approveRequestUnlocked(projectRoot, token, { failurePoint = null, inter
     workspace: 1,
     approval_id: approvalId
   };
-  const taskBody = `# ${titleFor(payload.request)}\n\n## Request\n\n${payload.request}\n\n## Classification\n\n- Type: ${payload.classification.type}\n- Reason: ${payload.classification.reason}\n- Risk: ${payload.risk.level}\n\n## Approval\n\n- Explicit approval token: ${approvalId}\n- Context fingerprint: ${payload.fingerprint}`;
+  const previewSection = payload.preview ? `\n\n## Preview\n\n${payload.preview}\n` : "";
+  const taskBody = `# ${titleFor(payload.request)}\n\n## Request\n\n${payload.request}\n\n## Acceptance Criteria\n\n- [ ] _Define what "done" means before execution._\n${previewSection}\n\n## Classification\n\n- Type: ${payload.classification.type}\n- Reason: ${payload.classification.reason}\n- Risk: ${payload.risk.level}\n\n## Approval\n\n- Explicit approval token: ${approvalId}\n- Context fingerprint: ${payload.fingerprint}`;
   const runBody = createRunBody(run, {
     approvalId,
     obligations: payload.policy.obligations || [],
@@ -169,7 +163,7 @@ function approveRequest(projectRoot, token, options = {}) {
   return withArtifactLock(path.join(projectRoot, ".scrumrun"), "approval", () => approveRequestUnlocked(projectRoot, token, options));
 }
 
-function transitionedArtifactContent(content, kind, nextStatus, updated) {
+function transitionedArtifactContent(content, kind, nextStatus, updated, assignee = null) {
   const parsed = parseArtifact(content);
   const errors = [...parsed.errors, ...validateArtifact(parsed.record, kind)];
   if (errors.length) throw new Error(`Invalid ${kind} artifact: ${errors.join("; ")}`);
@@ -178,6 +172,11 @@ function transitionedArtifactContent(content, kind, nextStatus, updated) {
   let frontmatter = frontmatterMatch[1]
     .replace(/^status:\s*.*$/m, `status: ${nextStatus}`)
     .replace(/^updated:\s*.*$/m, `updated: ${nextRecord.updated}`);
+  if (assignee) {
+    frontmatter = /^assignee:/m.test(frontmatter)
+      ? frontmatter.replace(/^assignee:\s*.*$/m, `assignee: ${assignee}`)
+      : `${frontmatter}\nassignee: ${assignee}`;
+  }
   const next = `---\n${frontmatter}\n---${frontmatterMatch[2]}`;
   const validated = parseArtifact(next);
   const nextErrors = [...validated.errors, ...validateArtifact(validated.record, kind)];
@@ -200,8 +199,9 @@ function transitionedRunContent(content, nextStatus, options = {}) {
   };
 }
 
-function transitionRunUnlocked(projectRoot, runId, nextStatus, { note = null, evidence = [], actor = "agent", occurredAt = null, failurePoint = null, interruptPoint = null } = {}) {
+function transitionRunUnlocked(projectRoot, runId, nextStatus, { note = null, evidence = [], actor = "agent", occurredAt = null, summary = null, failurePoint = null, interruptPoint = null } = {}) {
   const scrumDir = path.join(projectRoot, ".scrumrun");
+  const effectiveActor = actor === "agent" ? (agentIdentity(scrumDir) || "agent") : actor;
   const recovered = recoverPendingTransactions(scrumDir);
   const repository = new ArtifactRepository(scrumDir);
   const runArtifact = repository.read("run", runId);
@@ -229,11 +229,15 @@ function transitionRunUnlocked(projectRoot, runId, nextStatus, { note = null, ev
   const taskPrevious = fs.readFileSync(taskArtifact.file, "utf8");
   const prepared = nextStatus === "completed" ? prepareCompletion(projectRoot, runArtifact, { occurredAt }) : null;
   const transitionSource = prepared ? serializeArtifact(prepared.record, prepared.body) : runPrevious;
-  const runNext = transitionedRunContent(transitionSource, nextStatus, { note, evidence, actor, occurredAt });
+  const runNext = transitionedRunContent(transitionSource, nextStatus, { note, evidence, actor: effectiveActor, occurredAt });
+  let runContent = runNext.content;
+  if (nextStatus === "completed" && summary) {
+    runContent = appendTechnicalSummary(runNext.record, runContent, summary);
+  }
   const taskNext = transitionedArtifactContent(taskPrevious, "task", nextTaskStatus, runNext.record.updated);
   try {
     runKernelTransaction(scrumDir, "transition-run-task", [
-      { file: runArtifact.file, previous: runPrevious, next: runNext.content },
+      { file: runArtifact.file, previous: runPrevious, next: runContent },
       { file: taskArtifact.file, previous: taskPrevious, next: taskNext.content }
     ], { failurePoint, interruptPoint });
   } catch (error) {
@@ -332,4 +336,74 @@ function retryTask(projectRoot, taskId, options = {}) {
   return withArtifactLock(path.join(projectRoot, ".scrumrun"), `task-${String(taskId).toLowerCase()}`, () => retryTaskUnlocked(projectRoot, taskId, options));
 }
 
-module.exports = { approveRequest, nextId, refreshState, renderState, retryTask, stateFingerprint, stateIsStale, transitionRun };
+function nextBacklogTask(repository) {
+  const artifact = repository.list("task")
+    .find((entry) => entry.record && !entry.errors.length && entry.record.status === "backlog");
+  return artifact ? artifact.record : null;
+}
+
+function startBacklogTaskUnlocked(projectRoot, taskId, { note = "Backlog Task started.", failurePoint = null, interruptPoint = null } = {}) {
+  const scrumDir = path.join(projectRoot, ".scrumrun");
+  const recovered = recoverPendingTransactions(scrumDir);
+  const repository = new ArtifactRepository(scrumDir);
+  const taskArtifact = repository.read("task", taskId);
+  if (!taskArtifact) throw new Error(`Task not found: ${taskId}`);
+  if (taskArtifact.record.status !== "backlog") {
+    throw new Error(`Task ${taskId} is ${taskArtifact.record.status}; start requires backlog.`);
+  }
+  const identity = agentIdentity(scrumDir) || "agent";
+  const requestMatch = taskArtifact.body.match(/^## Request[ \t]*\r?\n\r?\n([\s\S]*?)(?=^## |(?![\s\S]))/m);
+  const request = requestMatch ? requestMatch[1].trim() : `Start ${taskId}`;
+  const context = buildContextPackage(projectRoot, request);
+  const policy = evaluatePolicy(context);
+  if (policy.status !== "passed") throw new Error(`Start is blocked by current policy: ${policy.violations.join("; ")}`);
+  const enforceablePolicy = policyState(projectRoot);
+  const baseline = publicWorkspace(workspaceState(projectRoot));
+  const run = {
+    id: nextId(repository, "run"),
+    kind: "run",
+    status: "executing",
+    created: date(),
+    updated: date(),
+    method: METHOD_VERSION,
+    task: taskId,
+    sprint: taskArtifact.record.sprint || null,
+    attempt: 1,
+    ledger: 1,
+    guardrails: 1,
+    workspace: 1,
+    approval_id: taskArtifact.record.approval_id || null
+  };
+  const runBody = createRunBody(run, {
+    title: `Run for ${taskId}`,
+    actor: identity,
+    reason: note,
+    evidence: [{ kind: "approval", summary: note }],
+    obligations: policy.obligations || [],
+    policyFingerprint: enforceablePolicy.fingerprint,
+    workspaceBaseline: baseline
+  }).body;
+  const runContent = serializeArtifact(run, runBody);
+  const taskPrevious = fs.readFileSync(taskArtifact.file, "utf8");
+  const taskNext = transitionedArtifactContent(taskPrevious, "task", "running", date(), identity);
+  try {
+    runKernelTransaction(scrumDir, "start-backlog-task", [
+      { file: repository.pathFor(run), previous: null, next: runContent },
+      { file: taskArtifact.file, previous: taskPrevious, next: taskNext.content }
+    ], {
+      failurePoint: failurePoint === "after-run" ? "after-1" : failurePoint,
+      interruptPoint
+    });
+  } catch (error) {
+    if (failurePoint === "after-run") throw new Error(`Injected start failure after Run creation: ${error.message}`);
+    throw error;
+  }
+  refreshState(scrumDir);
+  return { run, task: taskNext.record, content: runContent, recovered };
+}
+
+function startBacklogTask(projectRoot, taskId, options = {}) {
+  return withArtifactLock(path.join(projectRoot, ".scrumrun"), `task-${String(taskId).toLowerCase()}`, () => startBacklogTaskUnlocked(projectRoot, taskId, options));
+}
+
+module.exports = { approveRequest, nextBacklogTask, nextId, refreshState, renderState, retryTask, startBacklogTask, stateFingerprint, stateIsStale, transitionRun };

package/lib/runtime/policy-engine.js

@@ -1,5 +1,7 @@
 "use strict";
 
+const fs = require("node:fs");
+const path = require("node:path");
 const { containsSecret } = require("../security/secrets");
 
 const GUARDRAIL_STATUSES = new Set(["active", "retired", "superseded"]);
@@ -92,6 +94,25 @@ function configFields(content) {
   return fieldMap(String(content || ""));
 }
 
+function agentIdentity(scrumDir) {
+  if (process.env.SCRUMRUN_AGENT) {
+    const env = String(process.env.SCRUMRUN_AGENT).trim();
+    if (/^[A-Za-z0-9._-]{1,64}$/.test(env)) return env;
+  }
+  const configFile = path.join(scrumDir, "config.md");
+  if (!fs.existsSync(configFile) || !fs.lstatSync(configFile).isFile()) return null;
+  let content;
+  try {
+    content = fs.readFileSync(configFile, "utf8");
+  } catch {
+    return null;
+  }
+  const value = configFields(content).agent_identity;
+  if (!value) return null;
+  const clean = String(value).trim();
+  return /^[A-Za-z0-9._-]{1,64}$/.test(clean) ? clean : null;
+}
+
 function readOnlyPaths(content) {
   const value = configFields(content).read_only_paths;
   if (!value) return [];
@@ -255,6 +276,7 @@ function normalizeGuardrailDocument(content) {
 }
 
 module.exports = {
+  agentIdentity,
   configWeakeningAttempts,
   evaluatePolicy,
   inferEnforcement,

package/lib/runtime/request-engine.js

@@ -73,6 +73,7 @@ function encodeApproval(plan) {
     risk: plan.risk,
     policy: plan.policy,
     workspaceFingerprint: plan.workspaceFingerprint,
+    preview: plan.preview || null,
     issuedAt: plan.issuedAt
   };
   const encoded = Buffer.from(stableJson(payload)).toString("base64url");
@@ -95,7 +96,15 @@ function decodeApproval(token) {
   return payload;
 }
 
-function planRequest(projectRoot, request) {
+const TYPE_MAP = {
+  fix: { type: "fix", taskType: "fix" },
+  task: { type: "task", taskType: "task" },
+  feature: { type: "feature", taskType: "feature" },
+  docs: { type: "task", taskType: "docs" },
+  discovery: { type: "discovery", taskType: "discovery" }
+};
+
+function planRequest(projectRoot, request, { typeOverride = null, preview = null } = {}) {
   const normalized = String(request || "").trim();
   if (!normalized) throw new Error("A non-empty request is required for intake.");
   if (normalized.length > 10000) throw new Error("Request exceeds the 10,000 character intake limit.");
@@ -103,7 +112,17 @@ function planRequest(projectRoot, request) {
   const workspaceFingerprint = workspaceState(projectRoot).fingerprint;
   const policy = applyPolicy(context);
   const risk = assessRisk(normalized);
-  const classification = classifyRequest(normalized);
+  let classification = classifyRequest(normalized);
+  if (typeOverride) {
+    const override = TYPE_MAP[typeOverride];
+    if (!override) throw new Error(`Invalid --type: ${typeOverride}. Valid: ${Object.keys(TYPE_MAP).join(", ")}.`);
+    classification = { type: override.type, taskType: override.taskType, reason: "explicitly specified by agent" };
+  }
+  let safePreview = null;
+  if (preview) {
+    if (containsSecret(preview)) throw new Error("Preview contains secret-like content.");
+    safePreview = String(preview).trim().slice(0, 2000);
+  }
   const plan = {
     state: policy.status === "passed" ? "awaiting_approval" : "blocked",
     pipeline: ["received", "contextualizing", "policy", "risk", "classification", "planning", policy.status === "passed" ? "awaiting_approval" : "blocked"],
@@ -113,6 +132,7 @@ function planRequest(projectRoot, request) {
     policy,
     risk,
     classification,
+    preview: safePreview,
     proposal: {
       create: ["Task", "Run"],
       sprint: classification.type === "sprint" ? "propose only after confirming real batch/timebox membership" : null,

package/lib/runtime/run-ledger.js

@@ -461,6 +461,20 @@ function appendRunEvent(record, body, nextRecord, {
   return { body: nextBody, event, events: validated.events };
 }
 
+function appendTechnicalSummary(record, body, summary) {
+  const summaryText = String(summary || "").trim();
+  if (!summaryText) return body;
+  if (containsSecret(summaryText)) throw new Error("Technical summary contains secret-like content.");
+  const validated = validateRunLedger(record, body);
+  if (validated.errors.length) throw new Error(`Cannot append technical summary to invalid Run ledger: ${validated.errors.join("; ")}`);
+  return `${String(body).trimEnd()}\n\n## Technical Summary\n\n${summaryText}\n`;
+}
+
+function extractTechnicalSummary(body) {
+  const match = String(body || "").match(/^## Technical Summary[ \t]*\r?\n\r?\n([\s\S]*?)(?=^## |(?![\s\S]))/m);
+  return match ? match[1].trim() : null;
+}
+
 function legacyTransitionEvents(record, body, legacyHash) {
   const raw = [];
   const log = String(body || "").match(/^## Transition Log[ \t]*\r?\n([\s\S]*?)(?=^## |(?![\s\S]))/m);
@@ -531,11 +545,13 @@ module.exports = {
   appendGuardrailEvent,
   appendMutationEvent,
   appendRunEvent,
+  appendTechnicalSummary,
   createRunBody,
   dateInstant,
   eventId,
   eventsSection,
   evidenceForTransition,
+  extractTechnicalSummary,
   guardrailState,
   instant,
   makeRunEvent,

package/lib/v2/conformance.js

@@ -213,6 +213,13 @@ function auditProject(projectRoot) {
       findings.push(finding("high", "TASK_RUN_STATUS_MISMATCH", `${task.record.id}.status ${task.record.status} disagrees with latest ${latest.id}.status ${latest.status}.`, task.file));
     }
   }
+  for (const task of records.task || []) {
+    if (!task.record || task.errors.length) continue;
+    if (["backlog", "proposed", "cancelled"].includes(task.record.status)) continue;
+    if (!/^## Acceptance Criteria\b/m.test(task.body || "")) {
+      findings.push(finding("warning", "ACCEPTANCE_CRITERIA_MISSING", `${task.record.id} has no Acceptance Criteria section; define what "done" means before execution.`, task.file));
+    }
+  }
   for (const sprint of records.sprint || []) {
     if (!sprint.record || sprint.errors.length) continue;
     const heading = /^## Tasks[ \t]*$/m.exec(sprint.body);

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "scrumrun",
-  "version": "2.5.1",
+  "version": "2.6.1",
   "description": "Evidence-driven Agile runtime and semantic project memory for AI coding agents.",
   "bin": {
     "scrumrun": "bin/scrumrun.js",
     "sr-claude": "bin/claude-install.js"
   },
+  "types": "types/index.d.ts",
   "files": [
     "bin",
     "lib",
+    "types",
     "scripts",
     "templates",
     "CORE.md",
@@ -24,7 +26,10 @@
     "docs:contract": "node scripts/generate-contract-docs.js",
     "check:contract": "node scripts/generate-contract-docs.js --check",
     "test": "node scripts/generate-contract-docs.js --check && node --test tests/*.test.js",
-    "benchmark": "node --test tests/performance.test.js"
+    "benchmark": "node --test tests/performance.test.js",
+    "coverage": "c8 --reporter=text --reporter=lcov node --test tests/*.test.js",
+    "lint": "eslint .",
+    "prepublishOnly": "node scripts/sync-readme-version.js && npm test"
   },
   "keywords": [
     "ai",
@@ -54,5 +59,10 @@
   "license": "MIT",
   "engines": {
     "node": ">=22.13.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "c8": "^12.0.0",
+    "eslint": "^10.8.1"
   }
-}
+}

package/scripts/sync-readme-version.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const root = path.resolve(__dirname, "..");
+const { version } = require(path.join(root, "package.json"));
+const readmeFile = path.join(root, "README.md");
+
+const readme = fs.readFileSync(readmeFile, "utf8");
+const updated = readme.replace(/(\*\*Package:\*\* `)(\d+\.\d+\.\d+)(`)/, `$1${version}$3`);
+
+if (updated === readme) {
+  process.exit(0);
+}
+
+fs.writeFileSync(readmeFile, updated);
+console.log(`Synced README badge to ${version}`);

package/templates/project/.scrumrun/config.md

@@ -6,5 +6,8 @@ Language: English
 Interaction Mode: guided
 Execution Approval: always
 Quick Tasks: ask
+Agent Identity: agent
 
 These are operating preferences. They can never weaken `.scrumrun/guardrails.md`.
+
+`Agent Identity` is the default agent name recorded as the Task `assignee` and Run event `actor`. In shared teams, prefer the per-agent `SCRUMRUN_AGENT` environment variable over this project-wide default.

package/templates/project/AGENTS.md

@@ -7,19 +7,21 @@ This project uses ScrumRun. The method is mandatory; `/sc` is its single optiona
 For normal work, read:
 
 1. `.scrumrun/guardrails.md` — canonical project policy;
-2. `.scrumrun/state.md` — disposable index of active ids;
-3. the referenced Task, Sprint, Feature, Run, Memory, and Review artifacts relevant to the request;
+2. `.scrumrun/state.md` — the briefing: active work, recent completions, open decisions, active memory, backlog queue, and pointers;
+3. the referenced Task, Sprint, Feature, Run, Memory, and Review artifacts relevant to the request (go deeper only when the briefing lacks what you need);
 4. `.scrumrun/core.md` when the method contract or an exceptional transition is needed.
 
 Natural-language product requests automatically enter the read-only ScrumRun intake pipeline. Before explicit approval, do not create canonical records or modify application code.
 
 After approval:
 
-- Task is the atomic work item;
+- Task is the atomic work item; define its `## Acceptance Criteria` before execution;
 - Sprint is only a real timebox/batch of Tasks;
 - Run is one execution attempt and follows `executing → validating → learning → completed|failed|blocked`;
 - a retry creates a new Run and preserves the old one;
-- learning proposes evidence-backed Knowledge, Decisions, or candidate Insights.
+- record a `## Technical Summary` at completion so the next agent inherits what was done;
+- when a Run completes and work remains queued, surface it with `sc plan task --next` and start it with `sc plan task --start` — starting is explicit approval;
+- learning proposes evidence-backed Knowledge, Decisions, or candidate Insights;
 - every application/source edit requires a path-scoped Mutation Gateway permit, immediate hash recording, and resolution of the Run's Guardrail obligations before completion.
 
 Never bypass guardrails or edit around the Mutation Gateway, overwrite owner work, treat generated state/cache as truth, auto-confirm AI knowledge, auto-migrate a v1 project, or print vault values.

package/templates/project-lean/AGENTS.md

@@ -5,13 +5,13 @@
 This project stores the complete ScrumRun v2 truth but uses a bounded default read path:
 
 1. `.scrumrun/guardrails.md`;
-2. `.scrumrun/state.md`;
-3. only canonical artifacts referenced by active ids;
+2. `.scrumrun/state.md` — the briefing: active work, recent completions, open decisions, active memory, backlog queue, and pointers;
+3. only canonical artifacts referenced by the briefing's pointers (go deeper only when the briefing lacks what you need);
 4. `.scrumrun/core.md` only when method details are needed.
 
 Do not scan every Task, Run, Sprint, Feature, or Memory file by default. Generated `state.md`, `map.md`, and `.cache/` guide retrieval but never override canonical Markdown.
 
-Natural-language product work begins as read-only intake. Explicit approval creates/updates a Task and creates one Run. A Sprint exists only for a real batch/timebox. Run state is `executing → validating → learning → completed|failed|blocked`; retries preserve prior Runs.
+Natural-language product work begins as read-only intake. Explicit approval creates/updates a Task and creates one Run. A Sprint exists only for a real batch/timebox. Run state is `executing → validating → learning → completed|failed|blocked`; retries preserve prior Runs. Define the Task's `## Acceptance Criteria` before execution and record a `## Technical Summary` at completion. When work remains queued, surface it with `sc plan task --next` and start it with `sc plan task --start`.
 
 Every application/source edit requires a short-lived path-scoped Mutation Gateway permit and immediate hash recording in the active Run. Resolve all persisted Guardrail obligations before completion; policy/workspace drift fails closed.
 

package/templates/shared/skills/scrumrun/SKILL.md

@@ -32,8 +32,8 @@ Normal hot path:
 1. read `.scrumrun/method.json` — its `paths` block is the authoritative index of every canonical location; navigate by that index and never grep for legacy paths (`goals/`, `backlog.md`, `sprint.md`, `history.md`);
 2. read `AGENTS.md`;
 3. read `.scrumrun/guardrails.md`;
-4. read `.scrumrun/state.md`;
-5. follow the ids/pointers to only the relevant canonical artifacts;
+4. read `.scrumrun/state.md` — the **briefing**: active work, recent completions with their technical summaries, open decisions, active memory, backlog queue, and pointers;
+5. follow the briefing's pointers to only the relevant canonical artifacts; go deeper only when the briefing lacks what you need (`## Where to look`, `sc knowledge study "<topic>"`);
 6. load `.scrumrun/core.md` when the method contract or an exceptional transition is needed.
 
 **Never write Run events by hand.** Only the CLI mutates `runs/RUN-NNN.md`: `sc plan run --validate | --learn | --complete | --resume | --fail | --block | --satisfy-guardrail | --authorize-mutation | --record-mutation`. Direct edits produce invalid ledger events (unknown `type` like `execution`/`validation`/`learning`, unknown evidence `kind` like `guardrail-check`/`build`/`task-status`, missing snapshot invariant) and break project conformance. If the CLI does not expose the shape you need, propose a spec change instead of inventing vocabulary. Recover hand-written Runs via `sc plan run --normalize-legacy` — originals are preserved byte-exact under `.scrumrun/.migration-backup/runs/`.
@@ -81,6 +81,8 @@ At intake:
 
 Evaluate every active Guardrail into a structured `passed`, `blocked`, or `deferred` result. Report blocked results with the exact `GR-NNN` id and reason code. Keep deferred results visible and enforce them at the mutation, migration, review, or owner gate they identify; never describe a deferred check as passed.
 
+Assert the classification explicitly when the keyword inference is wrong: `sc plan intake "…" --type fix|task|feature|docs|discovery`. Attach a short technical explanation before approval with `--preview "…"` (rendered in the terminal, bound into the token, stored as `## Preview` on the Task).
+
 Do not create canonical artifacts, change status, edit application code, or treat ambiguous acknowledgement as approval. Temporary context may exist only in ignored disposable cache.
 
 The approval token binds both canonical context and a complete workspace fingerprint. Any canonical or source change after planning invalidates it and requires a new intake.
@@ -98,15 +100,19 @@ During execution:
 
 1. keep the change inside the approved Task scope;
 2. preserve existing owner work and unrelated dirty files;
-3. enforce guardrails before every material mutation: obtain a short-lived path-scoped Mutation Gateway permit before editing and record its verified before/after hashes immediately afterward;
-4. validate in proportion to risk;
-5. record exactly one structured `RUN-NNN-EVT-NNN` event per state transition, with RFC3339 time, actor, reason, and typed evidence;
-6. run configured reviewers;
-7. extract candidate learning only after validation;
-8. complete the Run, then Task, and only then the Sprint when its whole batch is done.
+3. define or confirm the Task's `## Acceptance Criteria` before execution and check them off as evidence;
+4. enforce guardrails before every material mutation: obtain a short-lived path-scoped Mutation Gateway permit before editing and record its verified before/after hashes immediately afterward;
+5. validate in proportion to risk and against the acceptance criteria;
+6. record exactly one structured `RUN-NNN-EVT-NNN` event per state transition, with RFC3339 time, actor, reason, and typed evidence;
+7. run configured reviewers;
+8. extract candidate learning only after validation;
+9. record a `## Technical Summary` at completion (`sc plan run --complete --summary "…"`) so the next agent inherits what was actually done;
+10. complete the Run, then Task, and only then the Sprint when its whole batch is done.
 
 Never overwrite a prior attempt. Never mark work complete because time/token budget ended.
 
+When a Run completes and work remains queued, the briefing's `## Next Up` names the next backlog Task. Surface it with `sc plan task --next` and start it with `sc plan task --start [TASK-NNN]` — starting is the explicit approval; the owner can always decline. Each agent declares its identity via `SCRUMRUN_AGENT` (or `Agent Identity` in `config.md`); it is recorded as the Task `assignee` and the Run event `actor`.
+
 Every deferred policy result is an append-only Run obligation. Unrecorded workspace drift, policy drift, an expired/missing permit, out-of-scope changes, unsafe symlinks, newly introduced secret-like content, or an unresolved obligation blocks validation/completion. The ignored permit cache is disposable; deleting it invalidates outstanding permits and never creates authority.
 
 Run is the sole operational-history authority. Task synchronizes current status without copying Run events. Validation, learning, completion, failure, block, and resume require a reason or structured evidence; completion also requires evidenced validation and learning. Early v2 prose Runs are migrated explicitly, with deterministic chains recovered and uncertain history represented as an evidenced snapshot.
@@ -159,11 +165,11 @@ Dry-run must not write project data. Apply requires a hashed inventory, byte-exa
 
 ### `/sc plan`
 
-- `task`: add/list/show/run/audit/cancel/retry atomic work; use `type: fix` for fixes and `status: backlog` for parked work.
+- `task`: add/list/show/run/audit/cancel/retry atomic work; use `type: fix` for fixes and `status: backlog` for parked work. `--next` surfaces the oldest backlog Task; `--start [TASK-NNN]` promotes it and creates its first Run.
 - `sprint`: add/list/show/start/complete/block a real Task batch/timebox.
 - `feature`: add/list/show/activate/complete long-lived initiatives.
-- `run`: list/show/authorize-mutation/record-mutation/satisfy-guardrail/validate/learn/complete/resume/fail/block concrete Task attempts.
-- `intake <request>`: execute the read-only request pipeline.
+- `run`: list/show/render/stats/normalize-legacy/authorize-mutation/record-mutation/satisfy-guardrail/validate/learn/complete/resume/fail/block concrete Task attempts. `--complete` accepts `--summary "…"` to store a technical summary.
+- `intake <request>`: execute the read-only request pipeline; accepts `--type fix|task|feature|docs|discovery` and `--preview "…"`.
 - `challenge <question>`: deep read-only analysis with evidence, risks, options, and recommendation.
 
 ### `/sc knowledge`