Polish Task Passport continuity cadence

Author: ihorponom

docs/CLI.md

@@ -49,7 +49,7 @@ agentpack task close
 
 Write scopes are repo-relative paths. `.` means the repository root.
 
-`task passport` prints the current `passport.json`. `task switch <id>` points the worktree at another open passport. `task update` patches objective, constraints, write scope, next actions, tags, and risk without changing lifecycle status; list fields are appended and deduplicated. Empty or no-op updates fail, and unknown risk values are rejected. `task audit` checks the current passport for stale source conclusions, branch/head drift, missing next actions, open verification, and closed-task anomalies. `task update-verification` writes verification status, evidence IDs, and summary into the passport; without flags it marks verification as `pending`, and with `--status`, `--evidence`, and `--summary` it can close the audit warning with evidence-backed verification. When a current passport exists, `resume` and MCP `load_context` include it above the repo-level ledger so agents can see the active task before broader history.
+`task start` refuses to replace an active, blocked, or verifying current task; park or close the current task first when starting unrelated work. Invalid risk values are rejected instead of being treated as unknown. `task passport` prints the current `passport.json`. `task switch <id>` points the worktree at another open passport. `task update` patches objective, constraints, write scope, next actions, tags, and risk without changing lifecycle status; list fields are appended and deduplicated. Empty or no-op updates fail, and unknown risk values are rejected. `task audit` checks the current passport for stale source conclusions, branch/head drift, missing next actions, open verification, and closed-task anomalies. `task update-verification` writes verification status, evidence IDs, and summary into the passport; without flags it marks verification as `pending`, and with `--status`, `--evidence`, and `--summary` it can close the audit warning with evidence-backed verification. When a current passport exists, `resume` and MCP `load_context` include it above the repo-level ledger so agents can see the active task before broader history.
 
 ## Record Durable State
 

docs/DOGFOOD.md

@@ -8,7 +8,6 @@ Load a small context first:
 
 ```text
 load_context(preset: "quick")
-source_status()
 ```
 
 Use `agent` instead of `quick` when the task needs more history.
@@ -40,9 +39,11 @@ Record only durable context. Agentpack is not an activity logger, and it should
 
 Default cadence:
 
-- At task start, load Agentpack context and source status.
+- At task start, load Agentpack context.
+- Call source status only when you need a full stale-source check beyond the loaded context.
 - During normal coding, keep working locally; record only durable decisions, dead ends, source conclusions, and evidence.
-- At the end of a coherent step, record the useful sources/evidence, update status and next actions, then checkpoint.
+- Sequence state-changing Agentpack calls; do not run them in parallel with audit, status, or checkpoint calls.
+- At the end of a coherent step, record aggregated evidence, update status and next actions, then checkpoint.
 - Use full safe mode for risky or release-like changes: record important findings as they happen and run the full verification loop.
 
 This keeps Agentpack useful without turning every micro-step into ledger traffic. The intended default cost is one context load near the start and one durable save near the end.
@@ -84,8 +85,10 @@ Git still owns code history. Agentpack owns task memory.
 
 While dogfooding, look for friction:
 
-- Did the agent call `load_context` and `source_status` early enough?
+- Did the agent call `load_context` early enough without repeating status checks unnecessarily?
 - Were unchanged sources avoided when recorded conclusions were enough?
+- Did `record_source` capture only reusable source conclusions instead of one event per changed file?
+- Were state-changing Agentpack calls sequenced so audits read the latest state?
 - Were decisions and dead ends recorded at useful moments?
 - Was evidence too noisy or too thin?
 - Was the checkpoint useful to the next session?

docs/MCP.md

@@ -11,10 +11,12 @@ Reference: [Model Context Protocol transports](https://modelcontextprotocol.io/d
 Generated Codex, Claude Code, and Cursor instructions tell connected agents to use the MCP tools as a small hybrid continuity loop:
 
 1. Start by calling `load_context` with a focused query and compact preset.
-2. Call `source_status` before relying on previously recorded source conclusions.
+2. Call `source_status` only when you need a full stale-source check beyond the context you just loaded.
 3. Record durable decisions, dead ends, evidence, and reviewed source conclusions while working.
 4. Call `checkpoint` after meaningful progress so the next session inherits status, next actions, git state, and compact resume context.
 
+For small tasks, prefer one aggregated evidence item plus one checkpoint summary. Do not call `source_status` repeatedly when `load_context`, `task_audit`, or a recent status check already answered the question. Do not call `record_source` for every changed file just to clear an audit warning; refresh a source record only when its durable conclusion changed.
+
 The CLI exposes the same operations for setup, inspection, debugging, demos, and web-chat fallback. See [CLI.md](CLI.md) for manual command examples.
 
 ## Tools

docs/RELEASE_NOTES.md

@@ -0,0 +1,30 @@
+# Release Notes Draft
+
+## Next patch release
+
+Draft scope since `0.1.10`:
+
+- Add Task Passport update flow for objective, constraints, write scope, next actions, tags, and risk.
+- Expose `task_update` through MCP alongside `task_audit` and `task_update_verification`.
+- Preserve `.` as a repo-root write scope.
+- Protect the current-passport workflow: `task start` now refuses to replace active, blocked, or verifying work.
+- Reject invalid task risk values consistently in `task start`, `task update`, and MCP `task_update`.
+- Clarify generated Codex, Claude, and Cursor instructions so agents use compact ledger cadence instead of repeated status checks or per-file source-record spam.
+- Add collaboration modes and safety guidance to generated project instructions.
+- Align CLI, MCP, Dogfood, and Task Passport docs with the implemented behavior.
+
+Verification before release:
+
+- `npm test`
+- `npm run mcp:smoke`
+- `npm pack --dry-run`
+- privacy scan for local paths and secret-like values
+- `git diff --check`
+- `agentpack doctor`
+- `agentpack task audit`
+
+Release gate:
+
+- Complete final review of the accumulated local commits.
+- Push only after review is accepted.
+- Cut the npm release only after the pushed branch is stable and docs match the release scope.

docs/TASK-PASSPORT.md

@@ -184,6 +184,8 @@ agentpack task close
 
 `resume` and MCP `load_context` read the current passport automatically when one exists, then show the broader repo-level ledger below it.
 
+`task start` creates a new current passport only when there is no current task, the current task is closed, or the current task is parked. If the current task is active, blocked, or verifying, Agentpack asks you to park or close it first so unrelated work does not silently overwrite the handoff pointer. Invalid risk values are rejected instead of being treated as unknown.
+
 `task audit` is a diagnostic pass for continuity risk. It checks the current passport for branch/head drift, missing next actions, open verification, stale source conclusions, and closed-current-task anomalies.
 
 `task update` patches the current passport without changing lifecycle status. It can add objective, constraints, write scope, next actions, tags, and risk after the task has already started. List fields append and deduplicate; omitted fields are preserved. Empty or no-op updates fail, and unknown risk values are rejected.

src/cli/index.ts

@@ -211,7 +211,7 @@ Usage:
   agentpack set goal <text>
   agentpack set status <text>
   agentpack set next <item> [--next <item>]
-  agentpack task start <title> [--objective <text>] [--write-scope <path>]
+  agentpack task start <title> [--objective <text>] [--constraint <text>] [--write-scope <path>] [--next <item>] [--tag <tag>] [--risk low|medium|high]
   agentpack task update [--objective <text>] [--constraint <text>] [--write-scope <path>] [--next <item>] [--tag <tag>] [--risk low|medium|high]
   agentpack task list
   agentpack task passport
@@ -285,15 +285,17 @@ function taskCommand(root: string, rest: string[]): void {
   if (subcommand === "start") {
     const parsed = parseArgs(args);
     const title = parsed.positionals.join(" ").trim();
-    const passport = startTask(root, {
+    const startOptions = {
       title: redactForRoot(root, title),
       objective: redactForRoot(root, stringOption(parsed.options.objective)),
       constraints: toArray(parsed.options.constraint).map((item) => redactForRoot(root, item)),
       writeScope: toArray(parsed.options["write-scope"]),
       nextActions: toArray(parsed.options.next).map((item) => redactForRoot(root, item)),
-      tags: toArray(parsed.options.tag),
-      risk: riskOption(parsed.options.risk)
-    });
+      tags: toArray(parsed.options.tag)
+    };
+    const passport = startTask(root, optionValue(parsed.options, "risk")
+      ? { ...startOptions, risk: taskRiskOption(parsed.options.risk) }
+      : startOptions);
     process.stdout.write(`Started task ${passport.id}\n`);
     return;
   }
@@ -663,14 +665,6 @@ function budgetOption(options: Record<string, ArgValue>, fallback = 0): number {
   }, fallback);
 }
 
-function riskOption(value: ArgValue | undefined): "low" | "medium" | "high" | "unknown" {
-  const risk = stringOption(value);
-  if (risk === "low" || risk === "medium" || risk === "high") {
-    return risk;
-  }
-  return "unknown";
-}
-
 function taskRiskOption(value: ArgValue | undefined): "low" | "medium" | "high" | "unknown" {
   const risk = stringOption(value);
   if (risk === "unknown" || risk === "low" || risk === "medium" || risk === "high") {

src/core/tasks.ts

@@ -72,6 +72,12 @@ export function startTask(root: string, options: TaskStartOptions): TaskPassport
 
   return withPackWriteLock(root, () => {
     ensureTasksDir(root);
+    const currentTask = getCurrentPassport(root);
+    if (currentTask && !CLOSED_STATUSES.has(currentTask.status) && currentTask.status !== "parked") {
+      throw new Error(
+        `Current task ${currentTask.id} is ${currentTask.status}; park or close it before starting a new task.`
+      );
+    }
 
     const now = new Date().toISOString();
     const git = getGitInfo(root);

src/integrations/install.ts

@@ -30,7 +30,7 @@ ${collaborationModesSection()}
 
 At the start of a task:
 - call \`load_context\` with a small preset first
-- call \`source_status\` before re-reading previously inspected files
+- call \`source_status\` only when you need a full stale-source check beyond the context you just loaded
 
 During work:
 - call \`record_source\` only when you have a durable conclusion about an important file; avoid repeated records for the same file unless the conclusion changed
@@ -40,11 +40,14 @@ During work:
 
 Avoid turning Agentpack into an activity log:
 - do not record every file read, mode switch, minor diff check, or routine command
-- for small tasks, prefer one final source record per touched important file plus one verification evidence and one checkpoint
+- do not call \`source_status\` repeatedly when \`load_context\`, \`task_audit\`, or a recent status check already answered the question
+- do not call \`record_source\` for every changed file just to make an audit warning disappear; prefer a checkpoint summary for batch changes and refresh source records only when the durable conclusion changed
+- for small tasks, prefer one aggregated verification evidence and one checkpoint; add source records only for important implementation files with reusable conclusions
 
 Default cadence:
 - start with Agentpack context
 - work locally without recording every micro-step
+- sequence state-changing Agentpack calls; do not run them in parallel with audit/status/checkpoint calls
 - record durable findings and evidence before a checkpoint
 - use full safe mode for risky or release-like changes
 

tests/agentpack.test.ts

@@ -446,6 +446,17 @@ test("manages a current task passport", () => {
     "low"
   ]);
   assert.match(started, /Started task task_/);
+  assert.match(
+    runExpectError(dir, ["task", "start", "Overlapping task", "--write-scope", "src/index.ts"]),
+    /Current task .* is active; park or close it before starting a new task\./
+  );
+  assert.match(runExpectError(dir, [
+    "task",
+    "start",
+    "Invalid risk task",
+    "--risk",
+    "urgent"
+  ]), /Unknown task risk: urgent/);
 
   const taskId = readFileSync(path.join(dir, ".agentpack", "tasks", "current"), "utf8").trim();
   const passportPath = path.join(dir, ".agentpack", "tasks", taskId, "passport.json");
@@ -552,6 +563,15 @@ test("manages a current task passport", () => {
   const repoWide = JSON.parse(run(dir, ["task", "passport"]));
   assert.deepEqual(repoWide.writeScope, ["."]);
   assert.doesNotMatch(run(dir, ["task", "audit"]), /Task has no write scope/);
+
+  assert.match(run(dir, ["task", "close"]), /Closed task/);
+  assert.match(runExpectError(dir, [
+    "task",
+    "start",
+    "Invalid risk task",
+    "--risk",
+    "urgent"
+  ]), /Unknown task risk: urgent/);
 });
 
 test("redacts secrets from stored context and handoff outputs", () => {
@@ -846,6 +866,10 @@ test("previews and writes project-local MCP client install files", () => {
   assert.match(readFileSync(path.join(dir, "AGENTS.md"), "utf8"), /checkpoint mode: summarize what was decided/);
   assert.match(readFileSync(path.join(dir, "AGENTS.md"), "utf8"), /Avoid turning Agentpack into an activity log/);
   assert.match(readFileSync(path.join(dir, "AGENTS.md"), "utf8"), /record_source` only when you have a durable conclusion/);
+  assert.match(readFileSync(path.join(dir, "AGENTS.md"), "utf8"), /source_status` only when you need a full stale-source check/);
+  assert.match(readFileSync(path.join(dir, "AGENTS.md"), "utf8"), /prefer one aggregated verification evidence and one checkpoint/);
+  assert.match(readFileSync(path.join(dir, "AGENTS.md"), "utf8"), /sequence state-changing Agentpack calls/);
+  assert.doesNotMatch(readFileSync(path.join(dir, "AGENTS.md"), "utf8"), /source_status` before re-reading/);
   const codexConfig = readFileSync(path.join(dir, ".codex", "config.toml"), "utf8");
   assert.match(codexConfig, new RegExp(`\\[mcp_servers\\.${escapeRegExp(serverName)}\\]`));
   assert.doesNotMatch(codexConfig, /\[mcp_servers\.agentpack\]/);