agentpack-cli 0.1.8 → 0.1.10

package/docs/TASK-PASSPORT.md

@@ -0,0 +1,229 @@
+# Task Passport
+
+Task Passport is the handoff artifact for one coherent unit of agentic work.
+
+It captures the reviewed state a future agent needs in order to continue the current task without rediscovering context, repeating dead ends, or guessing what is safe to touch.
+
+## Model
+
+Default rule:
+
+- one active Task Passport owns a repo worktree
+- a repo may keep many completed or parked passports over time
+- worktrees can carry different active passports
+- the shared repo source cache remains repo-level
+- decisions, dead ends, evidence, checkpoints, and next actions become passport-scoped
+
+This keeps source knowledge reusable while preventing unrelated work from mixing task state.
+
+## File Shape
+
+Target local layout:
+
+```text
+.agentpack/
+  config.json
+  sources.json
+  tasks/
+    current
+    task_20260518_source_cleanup/
+      passport.json
+      events.jsonl
+      checkpoints/
+      evidence/
+      exports/
+```
+
+`tasks/current` is a small pointer to the active task id for this worktree. If it is missing, Agentpack can fall back to the current v0 repo-level state.
+
+## Passport Schema
+
+`passport.json` should be compact, readable, and safe to inspect manually.
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "task_20260518_source_cleanup",
+  "title": "Add source cache cleanup commands",
+  "status": "active",
+  "createdAt": "2026-05-18T11:00:00.000Z",
+  "updatedAt": "2026-05-18T11:30:00.000Z",
+  "closedAt": null,
+  "objective": "Let Agentpack remove stale source records safely.",
+  "constraints": [
+    "Preserve existing source add/status behavior",
+    "Do not delete source records broadly without an explicit guard"
+  ],
+  "branch": "main",
+  "baseHead": "8d22011",
+  "currentHead": "21fe674",
+  "worktree": "/path/to/repo",
+  "writeScope": [
+    "src/operations.ts",
+    "src/cli/index.ts",
+    "tests/agentpack.test.ts",
+    "docs/CLI.md"
+  ],
+  "risk": "low",
+  "roles": {
+    "scout": {
+      "status": "done",
+      "summary": "Inspected source add/status flow and tests."
+    },
+    "builder": {
+      "status": "done",
+      "summary": "Implemented remove/prune commands inside declared write scope."
+    },
+    "reviewer": {
+      "status": "done",
+      "summary": "Verified tests, doctor, and dogfood cleanup."
+    },
+    "archivist": {
+      "status": "done",
+      "summary": "Recorded source conclusions, evidence, and checkpoint."
+    }
+  },
+  "verification": {
+    "status": "passed",
+    "evidence": [
+      "evt_example_test_output"
+    ],
+    "summary": "npm test passed; doctor clean after source cache refresh."
+  },
+  "nextActions": [
+    "Design Task Passport schema and state transitions"
+  ],
+  "tags": [
+    "source-cache",
+    "trust-foundation"
+  ]
+}
+```
+
+Required fields for v1:
+
+- `schemaVersion`
+- `id`
+- `title`
+- `status`
+- `createdAt`
+- `updatedAt`
+- `objective`
+- `branch`
+- `baseHead`
+- `worktree`
+- `writeScope`
+- `nextActions`
+
+Optional but recommended:
+
+- `constraints`
+- `currentHead`
+- `risk`
+- `roles`
+- `verification`
+- `tags`
+- `closedAt`
+
+## Statuses
+
+Initial statuses:
+
+- `active`: current work is in progress in this worktree
+- `parked`: intentionally paused and not the current task
+- `blocked`: waiting on user input, external dependency, or unresolved risk
+- `verifying`: implementation is done, but evidence/review is not complete
+- `completed`: task finished with verification or explicit acceptance
+- `abandoned`: task stopped and should not be resumed without a new decision
+
+Default context should show the active passport in full, and show parked or blocked passports only as compact references unless explicitly requested.
+
+## State Transitions
+
+Allowed transitions:
+
+```text
+none -> active              task start
+active -> parked            task park
+parked -> active            task switch/resume
+active -> blocked           task block
+blocked -> active           task unblock/resume
+active -> verifying         task update-verification
+verifying -> active         verification found more work
+verifying -> completed      verification passed
+active -> completed         small/docs task accepted directly
+active -> abandoned         task abandon
+parked -> abandoned         stale parked task is discarded
+blocked -> abandoned        blocked task is discarded
+```
+
+Closed statuses are `completed` and `abandoned`. Closed passports remain inspectable history but should not appear in the default resume unless they are query-relevant.
+
+## CLI Shape
+
+Target first CLI surface:
+
+```bash
+agentpack task start "Add source cache cleanup commands" \
+  --objective "Let Agentpack remove stale source records safely" \
+  --write-scope src/operations.ts \
+  --write-scope src/cli/index.ts
+
+agentpack task list
+agentpack task passport
+agentpack task switch task_20260518_source_cleanup
+agentpack task audit
+agentpack task park
+agentpack task block --reason "Waiting for API decision"
+agentpack task update-verification --status passed --evidence evt_... --summary "Focused checks passed"
+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 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-verification` updates the verification state. Without flags it marks verification as `pending`; with `--status`, `--evidence`, and `--summary` it links verification to recorded evidence so the audit warning can become a reviewed result.
+
+## Role Lanes
+
+Roles are coordination lanes inside one passport, not separate tasks.
+
+- Scout: read-oriented; records source conclusions, risks, and known unknowns
+- Builder: write-oriented; works inside the declared write scope
+- Reviewer: read-oriented; checks diff, tests, risks, and regression surface
+- Archivist: state-oriented; records evidence, checkpoints, and handoff notes
+
+For v1, roles should be metadata and prompts, not a multi-agent runtime. Orchestrators can later map their own workers onto these lanes.
+
+## Consistency Rules
+
+Agentpack should warn before work continues when:
+
+- the current git branch does not match the passport branch
+- the current git head moved since the last passport update
+- the current worktree path does not match the passport worktree
+- a source conclusion in the current context is changed or missing
+- a new active passport would overlap another open passport's write scope
+- a Builder role attempts changes outside the declared write scope
+- a task is marked completed without evidence or an explicit acceptance note
+
+Agentpack should not try to resolve code conflicts. It should point the user toward one of three safe paths:
+
+- reuse the current passport
+- park one task before starting another
+- move parallel work into a separate worktree
+
+## Migration
+
+Existing v0 packs should remain valid.
+
+When task support is introduced, Agentpack can create an initial passport from the current repo-level state:
+
+- `goal` becomes `objective`
+- `currentStatus` becomes a summary or active status note
+- `nextActions` copy into the passport
+- existing events remain readable as legacy repo-level events
+- `sources.json` stays repo-level
+
+This avoids breaking existing users while moving new work into passport-scoped ledgers.

package/docs/VISION.md

@@ -12,11 +12,12 @@ As agent UIs evolve from chat boxes into execution workspaces, handoffs will bec
 
 Branches and transcripts are not enough. Agents need reviewed task state that is portable, inspectable, and client-neutral.
 
-Agentpack is not trying to replace execution engines. Codex, Claude Code, Cursor, LangGraph, Temporal, OpenAI Agents SDK, and similar systems can own execution loops, retries, approvals, tool calls, and durable runs. Agentpack should own the neutral repo-scoped continuity layer that those surfaces can share.
+Codex, Claude Code, Cursor, LangGraph, Temporal, OpenAI Agents SDK, and similar systems can own execution loops, retries, approvals, tool calls, and durable runs. Agentpack should own the neutral repo-scoped continuity layer that those surfaces can share.
 
 ## What Agentpack Should Own
 
 - repo-native continuity
+- task passports as the handoff artifact
 - semantic checkpoints
 - source-inspection cache
 - dead-end memory
@@ -25,19 +26,39 @@ Agentpack is not trying to replace execution engines. Codex, Claude Code, Cursor
 - portable bundles between worktrees, machines, and clients
 - orchestrator recipes later
 
+## Task Passport Model
+
+A Task Passport is the handoff artifact for one coherent unit of agentic work. It should capture the objective, constraints, write scope, relevant source conclusions, decisions, dead ends, evidence, verification state, checkpoints, and next actions.
+
+See [TASK-PASSPORT.md](TASK-PASSPORT.md) for the target schema and state transitions.
+
+One active Task Passport should own the work in a repo worktree by default. A repo can keep many closed or parked passports over time, but Agentpack should not turn one working directory into a backlog or a multi-task merge engine.
+
+Workstreams are how passports stay separated across repo work, branches, and worktrees. They are for history, parked work, and handoff boundaries, not a substitute for issue tracking or code conflict resolution.
+
+Multi-role agents should collaborate inside one Task Passport:
+
+- Scout: inspect sources and record source conclusions
+- Builder: make changes inside the declared write scope
+- Reviewer: check the diff, risks, and verification
+- Archivist: record evidence, checkpoints, and handoff state
+
+Agentpack should support those role lanes as lightweight prompts, metadata, and consistency checks before it attempts any heavier orchestration.
+
 ## Operating Principles
 
 - Git stores code state. Agentpack stores reviewed task state.
 - Execution engines run the work. Agentpack preserves what future agents need to continue it.
 - Continuity should be native to the repo, not reconstructed from chat history.
+- One Task Passport owns the current work; multiple roles can contribute to it.
 - Prefer small, inspectable, local files before hosted sync or hidden databases.
 - Prefer portable MCP, CLI, and file surfaces over framework lock-in.
 - Record durable context, not every action.
 
-## Non-Goals
+## Scope Boundaries
 
-- Do not become a general chat archive.
-- Do not replace LangGraph, Temporal, OpenAI Agents SDK, Codex, Claude Code, Cursor, or other execution engines.
-- Do not make cloud sync or hosted memory required for the core workflow.
-- Do not treat automatic full-session capture as the default source of truth.
-- Do not require embeddings or network calls before deterministic file/hash/source summaries stop being enough.
+- Keep the core artifact focused on reviewed task state.
+- Keep backlog, issue tracking, and code merge conflict resolution in the tools that already own them.
+- Keep execution loops, retries, approvals, tool calls, and durable runs in execution engines.
+- Keep the core workflow local-first; hosted sync can remain optional future work.
+- Keep deterministic file, hash, and source summaries as the default before adding embeddings or network calls.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentpack-cli",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Local task-state ledger for AI coding agents.",
   "type": "module",
   "repository": {

package/scripts/mcp-smoke.mjs

@@ -29,7 +29,7 @@ try {
 
   const toolsResponse = await client.request("tools/list", {});
   const toolNames = toolsResponse.result?.tools?.map((tool) => tool.name).sort() || [];
-  for (const expected of ["load_context", "record_decision", "record_source", "resume", "source_status"]) {
+  for (const expected of ["load_context", "record_decision", "record_source", "resume", "source_status", "task_audit", "task_update_verification"]) {
     assertIncludes(toolNames, expected, `tools/list includes ${expected}`);
   }
 
@@ -55,6 +55,43 @@ try {
   });
   assertMatch(sourceStatus.result?.content?.[0]?.text || "", /UNCHANGED index\.js/, "source_status reports unchanged source");
 
+  const initialAudit = await client.request("tools/call", {
+    name: "task_audit",
+    arguments: {}
+  });
+  assertMatch(initialAudit.result?.content?.[0]?.text || "", /No current task passport/, "task_audit reports missing task before start");
+
+  runCli([
+    "task",
+    "start",
+    "MCP smoke verification",
+    "--write-scope",
+    "index.js",
+    "--next",
+    "Complete smoke verification"
+  ]);
+
+  const evidence = await client.request("tools/call", {
+    name: "attach_evidence",
+    arguments: {
+      kind: "test-output",
+      content: "MCP smoke verification passed."
+    }
+  });
+  const evidenceText = evidence.result?.content?.[0]?.text || "";
+  const evidenceId = evidenceText.match(/Attached evidence ([^.]+)\./)?.[1] || "";
+  assertMatch(evidenceId, /^evt_/, "attach_evidence returns an evidence event id");
+
+  const taskVerify = await client.request("tools/call", {
+    name: "task_update_verification",
+    arguments: {
+      status: "passed",
+      evidence: [evidenceId],
+      summary: "MCP smoke verification passed."
+    }
+  });
+  assertMatch(taskVerify.result?.content?.[0]?.text || "", /Updated verification for task .* \(passed\)/, "task_update_verification marks verification as passed");
+
   const resume = await client.request("tools/call", {
     name: "resume",
     arguments: {
@@ -67,7 +104,7 @@ try {
 
   console.log("MCP server OK");
   console.log(`Tools: ${toolNames.join(", ")}`);
-  console.log("Flow: initialize -> tools/list -> record_decision -> record_source -> source_status -> resume");
+  console.log("Flow: initialize -> tools/list -> record_decision -> record_source -> source_status -> task_audit -> task_update_verification -> resume");
 } catch (error) {
   console.error("MCP smoke failed");
   console.error(error instanceof Error ? error.message : String(error));