@evoclock/pi-agentic-driver 0.10.1 → 1.0.0

package/.agentic-driver/nudge.defaults.json

@@ -0,0 +1,11 @@
+{
+  "schema": "agentic-driver.herdr-nudge-config.v1",
+  "revision": 1,
+  "nudge": {
+    "enabled": false,
+    "reasonAttemptWindowPolls": 12,
+    "backoffCycles": 2,
+    "backoffMaxCycles": 8,
+    "nudgeMaxBytes": 2048
+  }
+}

package/.githooks/pre-commit

@@ -0,0 +1,4 @@
+#!/bin/sh
+# Repository-local gate; preserve any existing hook chain before opting in.
+repo=$(git rev-parse --show-toplevel) || exit 1
+exec python3 "$repo/scripts/codebase_inventory_gate.py" --repo "$repo"

package/README.md

@@ -13,7 +13,7 @@
   <img src="https://img.shields.io/badge/Python-3776AB?style=flat&logo=python&logoColor=white" alt="Python"/>
 </p>
 
-An agent without guardrails will rewrite code an existing abstraction already
+An agent without guardrails will sometimes rewrite code an existing abstraction already
 covers. It will ship to the wrong remote. It will lose context and report
 success without evidence. Pi is deliberately lean by design: the harness is yours to
 shape. That philosophy is exactly what these extensions practice, they make them mine (and possibly yours too). They take
@@ -21,14 +21,14 @@ some concerns I consider worth addressing, and make them part of the
 harness.
 
 **pi-agentic-driver makes agent work verifiable and controllable. The agent does
-the work and each extension makes sure the work can be checked.** Review happens
-before code is written. Communication carries reports without asserting authority that isn't granted.
-Isolation proofs verify their own cleanup. Sessions survive compaction and
+the work and each extension makes sure the work can be checked.** Reviewing happens
+before code is written. Communication involves reports without asserting authority that isn't granted.
+Isolation proofs exist to verify their own cleanup. Sessions survive compaction and
 Git operations stay exact, confirmed, and protected.
 
-Every capability passes fixture-based acceptance, native tests, live-session
-checks, and independent model review before release. I/we document each
-extension's restrictions before release, not after.
+Features have different evidence levels: focused tests and independent review
+support the shipped contracts, while live host-dependent proof is stated only
+where it has actually run. A receipt or worker report is evidence, not approval.
 
 Extensions for [Pi](https://github.com/earendil-works/pi-coding-agent):
 advisory code review, controlled role communication, and governed isolation
@@ -43,24 +43,26 @@ proofs for agentic workflows.
 | Tool | What it does | Status |
 |------|--------------|--------|
 | `code_phage` | Reviews a plan against a stated goal before code is written and advises your agent. | shipped |
-| `tasks` | Keeps a session plan close to the work, then lets the owner make selected items durable in `TASKS.md`. | shipped |
-| `agentic_herdr_communication` | Exchanges marked reports with worker agents; never grants authority. | shipped |
+| `tasks` | Keeps a priority-ordered session plan, then lets the owner make selected items durable in `TASKS.md`. | shipped |
+| `agentic_herdr_communication` | Submits one prompt and observes delivery and marked reports; never grants authority. | shipped |
 | `agentic_herdr_spawn_worker` | Starts one Pi worker in a pane or tab, with native confirmation. | shipped |
 | `agentic_aidr` | A remedy for AI;DR. Reviews writing for clarity, simplicity, brevity, and humanity. | shipped |
 | `agentic_linux_microvm_cutover` | Runs one job in a throwaway QEMU/KVM virtual machine on a Linux host, with a severity-tiered killswitch that stops escape attempts. | user-enabled, native confirmation |
-| `agentic_worker_dispatch` | Runs controlled worker journeys and observes worker liveness. | shipped |
+| `agentic_worker_dispatch` | Runs bounded worker journeys and observes worker liveness; recovery is not activated. | shipped |
 | `agentic_kanban_board` | Shows the workspace task board: lanes, flags, priorities, dependencies, and which cards can run. | shipped |
 | `agentic_kanban_board_write` | Adds cards to the board through the trusted writer, which records who authorized the work. | shipped |
 | `agentic_kanban_board_update` | Moves, closes, flags, edits, or removes cards on the board, always recording who authorized the change. | shipped |
 | `agentic_kanban_board_dispatch` | Claims an eligible board card for automated contained work and creates its assignment envelope. | shipped |
 | `agentic_kanban_pulse` | Checks for ready work and available capacity, then starts assignments under the board policy. | shipped |
+| `/agentic-recovery-evidence` | Opens private recovery evidence in the local TUI; it is not a model-callable tool or recovery authorization. | shipped, local review only |
 | Router | Capacity/policy routing for Board Pulse: seats with scope statements, tunable policy values, and a binding dispatch gate. | shipped |
 | Janus (bundled service) | Local Jev evaluation service on loopback: semantic ranking, the dispatch-gate judgment, redaction before every external call. See `janus/README.md`. | shipped |
 
-**Status: active development and testing.** Each extension ships only after
-it passes fixture-based acceptance, native tests, live-session checks, and
-independent model review. You can install released components. Pending
-components are listed here for transparency and are not packaged.
+**Status: active development and testing.** The disabled NUDGE classifier and
+private evidence store are packaged foundations, not a running recovery
+ladder. Herdr 0.9.1 has no proven modal-safe nudge channel. No terminal
+`prompt` or `send-keys` fallback is enabled. Pending integrations below are
+not presented as live features.
 
 ## Code review and planning
 
@@ -101,13 +103,13 @@ only, not a runtime dependency).
 
 Plans stay close to the work. They do not become board work by accident. The tasks skill gives Pi a familiar session list. It adds an owner-approved way to keep selected tasks in the durable `TASKS.md` board.
 
-- **Keep the working list simple.** Use `TaskCreate`, `TaskGet`, `TaskList`, and `TaskUpdate` as usual; the above-editor widget and footer pill stay live as tasks change.
+- **Keep the working list simple.** Use `TaskCreate`, `TaskGet`, `TaskList`, and `TaskUpdate` as usual. Set an optional P0–P3 session priority; ranked open work appears first, unranked work keeps ID order, and completed work appears last. Priority does not authorize board dispatch. The widget and footer stay live as tasks change.
 - **Keep the Claude-like view.** `/tasks` provides descriptions, active forms, and internal-task markers without mutating the plan.
 - **Make durable work deliberate.** `TaskPromote` never runs automatically. It previews the exact cards and destination before the owner confirms.
 - **Keep authority clear.** The trusted board writer creates and updates `TASKS.md`. The skill does not bypass it.
 - **Make migration gentle.** Existing task files remain readable. Moving to the driver-owned skill does not strand current plans.
 
-The result is a clean handoff from a session plan to durable work. Selected tasks can survive the session, appear on the shared board, and become available for controlled dispatch when ready.
+The result is a clean handoff from a session plan to durable work. Selected tasks can survive the session, appear on the shared board, and become available for controlled dispatch when ready. A session priority is not copied into a board card without an owner-approved board action.
 
 </details>
 
@@ -276,11 +278,15 @@ across versions rather than pinning one).
 - **List and observe.** Worker roles are filtered to trusted repositories: a
   checked-in registry plus canonical-path validation. Unlisted or
   symlink-escaped repositories are denied.
-- **Prompt exactly once.** The tool re-observes the role, sends one approved
-  prompt with a role-specific report contract, waits for terminal settlement,
-  and reads exactly one complete marked report. No retry, no target
-  substitution, no resend on timeout.
-- **Wait and read.** The same trust checks apply to partial journeys.
+- **Submit once and observe separately.** A prompt returns an immediate,
+  non-authorizing delivery receipt. The `delivery` action can report queued,
+  delivered, answered, failed, unknown, or unattributed. A marked answer is
+  attributed only to its own delivery boundary and exact correlation line;
+  missing or ambiguous evidence is never called success.
+- **Wait and read.** The same trust checks apply to settlement and marked
+  reports. Unknown delivery never causes an automatic retry or resend.
+  Duplicate submissions within the bounded uncertainty window return the
+  existing delivery ID, not another handoff.
 - **Grant nothing.** Fixed argv, `shell: false`, a pinned executable, the
   coordinator role class denied. Results come back as untrusted evidence. The
   tool cannot control panes, start agents, run shells, or create authority.
@@ -383,9 +389,8 @@ starting revision, assigned branch, allowed paths, stopping point, expiry, and
 interaction profile.
 
 Blocked, altered, expired, reused, or unauthorized assignments fail closed.
-The journey validates the authenticated envelope before each consequential
-step. It runs on the assigned branch and consumes the envelope when the
-attempt ends.
+Board Pulse handles board assignment with full route evidence. The session
+worker journey does not claim board cards or mint board envelopes.
 
 Consuming an envelope releases the claim. It does not mark the card done.
 
@@ -579,10 +584,13 @@ end" or "don't wait for me" and the journey runs in autonomous mode. Say
 "do these two things" and it runs in the normal mode, pausing for you
 between steps. The mode is recorded in the report either way.
 
-Autonomous journeys can run work you dispatch directly or work claimed from
-a task board. Board-managed journeys use the card's authenticated assignment
-envelope and the board's automation policy. Direct journeys continue to work
-without a board.
+`agentic_worker_dispatch` observes coordinator session tasks through a
+read-only task store; dispatch no longer fails for lack of that store.
+Interactive steps require native confirmation. Autonomous journeys follow
+the session's existing autonomy semantics. Board cards in canonical
+`TASKS.md` are assigned by Board Pulse and `agentic_kanban_board_dispatch`,
+which own the route evidence needed for claims and envelopes. The session
+journey never claims board cards.
 
 ### The cast
 
@@ -652,9 +660,13 @@ silently allowed.
   notes, governed checkpoint mutation, watchdog handoff, and fresh-session
   resumption that identifies goal, changed files, checks, and next step
   without executing anything.
-- **evidence ledger.** Deterministic evidence indexing, lossless source
-  projection, universal checkpoint produce/store/recover, and run-ledger
-  records with crash and corruption vectors tested.
+- **recovery journey.** A private exact-evidence store and read-only TUI review
+  are packaged. Trusted journey authorization, safe handoff, durable unknown-
+  delivery lock, and a modal-safe nudge channel are still missing. No recovery
+  action is enabled by a stored hash, receipt, or display token.
+- **broader evidence ledger.** Deterministic indexing, lossless projection,
+  checkpoint produce/store/recover, and tested multihost reconciliation remain
+  planned beyond the bounded private store.
 - **offline multihost evidence.** Record run evidence on each host while
   disconnected and reconcile it deterministically on reconnection, with no
   host as sole authority.

package/config/codebase-inventory.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/evoclock/pi-agentic-driver/blob/main/config/codebase-inventory.schema.json",
+  "title": "Codebase inventory file record v1",
+  "description": "One compact JSON object per tracked code file; JSONL lines sorted by repository-relative path. Static extraction is best-effort; this is a search aid, not an authorization source.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["path", "subdir", "filename", "blob_sha", "loc", "size_bytes", "language", "functions", "classes", "dependencies", "exported_symbols"],
+  "properties": {
+    "path": {"type": "string", "minLength": 1, "description": "Repository-relative POSIX path"},
+    "subdir": {"type": "string"},
+    "filename": {"type": "string", "minLength": 1},
+    "blob_sha": {"type": "string", "pattern": "^[a-f0-9]{40}$", "description": "Git SHA-1 blob ID for the source bytes, even in SHA-256 repositories this v1 field denotes the SHA-1 blob computation"},
+    "loc": {"type": "integer", "minimum": 0},
+    "size_bytes": {"type": "integer", "minimum": 0},
+    "language": {"enum": ["python", "shell", "javascript", "typescript"]},
+    "functions": {"type": "array", "items": {"$ref": "#/$defs/named"}, "uniqueItems": true},
+    "classes": {"type": "array", "items": {"$ref": "#/$defs/named"}, "uniqueItems": true},
+    "dependencies": {"type": "array", "items": {"type": "string"}, "uniqueItems": true},
+    "exported_symbols": {"type": "array", "items": {"type": "string"}, "uniqueItems": true}
+  },
+  "$defs": {"named": {"type": "object", "required": ["name"], "additionalProperties": false, "properties": {"name": {"type": "string", "minLength": 1}}}}
+}

package/docs/codebase-inventory.md

@@ -0,0 +1,15 @@
+# Codebase inventory
+
+`pipeline_output/codebase_inventory.jsonl` is a searchable list of tracked code files. Before adding a module or function, search it for a filename or `"name":"symbol"`, then read any match. It is a discovery aid, not evidence that code is correct or safe.
+
+## Provenance and schema
+
+The earlier Claude Code `cc_pre_commit_verify_hook.py` in `agent-infra` called `pre_commit_verify.py`, which called `codebase_inventory_gate.py` and refreshed the inventory on commit. The original Python/shell-only generator missed JavaScript repositories. A later `agentic-driver/scripts/codebase_inventory.py` added JS/TS recognition and richer per-file records. Among inspected existing inventories, `local-assist-model` has the most records (1,524 files), while `agentic-driver` has the most complete *fields* per record (path, filename, blob hash, lines, bytes, language, functions, classes, dependencies, exports). This repository's documented v1 subset follows the latter format and is defined in `config/codebase-inventory.schema.json`. The compact line layout intentionally supports exact `grep '"name":"symbol"'` lookups. Static JS/TS symbol detection is approximate and never executes source; Python uses `ast`, shell uses bounded patterns. No function bodies, secret-bearing values, or docstrings are copied into the inventory.
+
+Every JSONL line is a file record sorted by repository-relative path. Its `blob_sha` is the SHA-1 Git blob ID of the working-tree file, allowing drift checks. Only Git-indexed Python, shell, JS, JSX, TS and TSX files (including `.mjs`, `.cjs`, `.mts` and Python/shell shebang scripts) are scanned. Generated/untracked files are not scanned. Empty symbol lists do not mean that a file is inert; dynamic exports can evade static patterns.
+
+## Refresh and commit gate
+
+Run `python3 scripts/codebase_inventory.py` to regenerate the inventory. Review and stage both the code and `pipeline_output/codebase_inventory.jsonl`. `python3 scripts/codebase_inventory.py --check` compares without writing. `python3 scripts/codebase_inventory_gate.py` refreshes and blocks if inventoried source has unstaged edits or if the regenerated bytes differ from the staged inventory. It does not stage changes for you.
+
+The repository ships an **opt-in Git pre-commit hook** at `.githooks/pre-commit` (no `cc_` prefix). If this repo has no existing hooks path, enable it with `git config --local core.hooksPath .githooks` and make the hook executable. **Do not replace an existing hook chain:** call `python3 scripts/codebase_inventory_gate.py` from that chain instead. Hook configuration is local and is not changed automatically by this package. No hook can intercept commits made with Git hooks disabled; this is a workflow freshness check, not a security boundary. The gate does not install dependencies or run code from inventoried files.

package/docs/recovery-evidence-store.md

@@ -0,0 +1,9 @@
+# Recovery evidence: store contract (Phase 2, first slice)
+
+The driver owns the NUDGE ledger and its evidence format. A host supplies a canonical, owner-private local directory: Vogelkop will choose its app-data root and provide a review UI; the Pi host will supply its own trusted root. Neither host may replace the driver's evidence checks or treat a digest as dispatch authority. No default path is selected, and no current journey calls this module.
+
+`scripts/enforcement/recovery_evidence_store_pi.js` stores exact, schema-validated NUDGE ledger entries in a dedicated SQLite file. The caller MUST persist a `requested` entry **before** attempting a nudge or replacement. The caller later records one terminal result; the store retains both immutable phases, links the terminal to the requested digest, and checks the SHA-256 hash, byte count, entry identity, phase, and predecessor when reading. A reference contains `{schema, journeyId, entryId, phase, sha256, bytes}`. It is a retrieval and integrity pointer, **not** proof of authorization, tamper-proof authentication, or evidence that an action was delivered. The owner-private file contains exact message text; it must not be sent unredacted to Jev or printed in a public report.
+
+The owner-provided root must be absolute, canonical, non-symlinked, and private (mode 0700). The DB file must be regular, non-symlinked, and private (0600). Read-only open never creates storage. Writes serialize in SQLite transactions and fail on duplicates, invalid entries, per-record size, total evidence-byte quota, or record-count quota. No automatic eviction or deletion API exists; a full store blocks **new recovery actions** until the owner reviews capacity. A failed terminal write **after** an attempted action means the caller must retain its unknown-delivery identity lock and must not resend or replace blindly. This module does not implement that journey lock.
+
+There is deliberately no retention timer yet. A host review/acknowledgment and retention policy must be specified before any deletion feature. A lost store cannot be reconstructed from its hash. An attacker able to rewrite both DB contents and hashes can forge non-authorizing evidence; filesystem permissions are the local privacy boundary, not a substitute for a signed audit service. The current 32 KiB journey report, its truncation behavior, Jev selection, Vogelkop UI, and N1 Herdr transport remain unchanged. Before journey wiring, add host-provided root and read-access control, receipt pointers with mandatory pinned fields, crash/ambiguous-delivery tests, and a verified owner review route.

package/extensions/herdr-dispatch.ts

@@ -1,7 +1,9 @@
 // SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
 // SPDX-License-Identifier: AGPL-3.0-only
 
-export default async function herdrDispatchPi(pi) {
+import { createTaskStore } from "./task-store-adapter.ts";
+
+async function herdrDispatchCore(pi) {
   const dispatch = await import(new URL("../scripts/enforcement/herdr_async_dispatch_pi.js", import.meta.url).href);
   const lifecycle = await import(new URL("../scripts/enforcement/herdr_lifecycle_pi.js", import.meta.url).href);
 
@@ -23,5 +25,16 @@ export default async function herdrDispatchPi(pi) {
       signal,
     );
 
-  return dispatch.registerWorkerDispatchInterface(pi, { spawnReplacement });
+  // A fresh read-only session view per journey; registration remains keyed
+  // on the real Pi API identity for the enforcement module's dedupe guard.
+  return dispatch.registerWorkerDispatchInterface(pi, { spawnReplacement, taskStoreFactory: createTaskStore });
+}
+
+// Async transport seam (vogelkop phase #47): submit returns a versioned,
+// non-authorizing receipt immediately; poll/observe/read are separate
+// single-attempt operations. No retries, no resends, no authority.
+export default async function herdrDispatchPi(pi) {
+  await herdrDispatchCore(pi);
+  const asyncSeam = await import(new URL("../scripts/enforcement/herdr_async_seam_pi.js", import.meta.url).href);
+  return asyncSeam.registerAsyncDispatchInterface(pi);
 }

package/extensions/recovery-evidence.ts

@@ -0,0 +1,14 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// Thin extension wrapper for the owner-only recovery-evidence review command.
+// Deliberately registers no model-callable tool: the full evidence surface is
+// the interactive native TUI overlay only. The registration is async (the
+// trusted root is resolved and snapshotted); Pi awaits an asynchronous
+// default factory before startup continues (extensions.md), so no return
+// value or extra await is needed here.
+import { registerRecoveryEvidenceReview } from "../scripts/enforcement/recovery_evidence_review_pi.js";
+
+export default async function registerRecoveryEvidenceReviewExtension(pi: any) {
+  await registerRecoveryEvidenceReview(pi);
+}

package/extensions/task-store-adapter.ts

@@ -0,0 +1,101 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import {
+  TASK_STATE_ENTRY, resolveTaskListId, tasksMirrorPath, loadSnapshotFile, validateSnapshot,
+  sessionTaskDisplayId, PROVENANCE_CAPTURE_STATUSES,
+} from "../scripts/enforcement/session_tasks_core_pi.js";
+import { createHash } from "node:crypto";
+
+// Match TaskList's branch-first/high-water-mark observation in tasks.ts.
+// The session mirror is a fallback; neither reader changes either source.
+function observeSessionTasks(ctx) {
+  const id = resolveTaskListId({ session: ctx?.sessionManager?.getSessionId?.() ?? null });
+  let branch = null;
+  try {
+    const entries = ctx?.sessionManager?.getBranch?.() ?? [];
+    const snapshots = entries.filter((entry) => entry?.type === "custom" && entry?.customType === TASK_STATE_ENTRY);
+    const candidate = snapshots.at(-1)?.data;
+    if (validateSnapshot(candidate)) branch = candidate;
+  } catch { /* disk mirror remains available */ }
+  const disk = id ? loadSnapshotFile(tasksMirrorPath(id)) : null;
+  const fromDisk = (Number(disk?.highWaterMark) || 0) > (Number(branch?.highWaterMark) || 0);
+  const snapshot = fromDisk ? disk : branch ?? disk;
+  return { tasks: snapshot?.tasks ?? [], taskListId: id, source: fromDisk || (!branch && disk) ? "disk" : branch ? "branch" : "none" };
+}
+
+export function sessionTasks(ctx) {
+  return observeSessionTasks(ctx).tasks;
+}
+
+// Audit evidence only. A task-list environment override may select a different
+// mirror; never attribute that mirror to the host session identity.
+export function captureSessionTaskProvenance(ctx) {
+  const hostSessionId = ctx?.sessionManager?.getSessionId?.();
+  const observation = observeSessionTasks(ctx);
+  const source = { hostSessionId: typeof hostSessionId === "string" && hostSessionId.trim() ? hostSessionId : null,
+    taskListId: observation.taskListId, kind: observation.source };
+  if (!source.hostSessionId) return { status: "host-session-unavailable", source, tasks: [] };
+  if (source.taskListId !== source.hostSessionId) return { status: "task-list-mismatch", source, tasks: [] };
+  if (source.kind === "none") return { status: "source-unavailable", source, tasks: [] };
+  const capturedAt = new Date().toISOString();
+  const tasks = observation.tasks.map(({ id, subject, description }) => {
+    const material = { id, title: subject ?? null, description: description ?? null, capturedAt };
+    const canonical = JSON.stringify({ capturedAt, description: material.description, id, title: material.title });
+    return Object.freeze({ material: Object.freeze(material), digest: createHash("sha256").update(canonical, "utf8").digest("hex") });
+  });
+  return Object.freeze({ status: "captured", source: Object.freeze(source), tasks: Object.freeze(tasks) });
+}
+
+// Model-visible projection: task identity, deterministic digest, and source
+// only. Raw titles and descriptions can carry private planning text or
+// secrets, so they never leave the local capture used for revalidation.
+export function projectSessionTaskProvenance(capture) {
+  const rawStatus = capture?.status;
+  const status = typeof rawStatus === "string" && PROVENANCE_CAPTURE_STATUSES.includes(rawStatus)
+    ? rawStatus
+    : "source-unavailable";
+  const tasks = Array.isArray(capture?.tasks) && status === "captured"
+    ? capture.tasks.map((entry) => ({ taskDisplayId: sessionTaskDisplayId(entry?.material?.id), digest: typeof entry?.digest === "string" ? entry.digest : null }))
+    : [];
+  return Object.freeze({
+    status,
+    source: capture?.source ? Object.freeze({
+      hostSessionId: capture.source.hostSessionId ?? null,
+      taskListId: capture.source.taskListId ?? null,
+      kind: capture.source.kind ?? "none",
+    }) : null,
+    tasks: Object.freeze(tasks),
+  });
+}
+
+export function revalidateSessionTaskProvenance(ctx, capture, taskId) {
+  if (capture?.status !== "captured") return { status: "capture-unavailable" };
+  const current = captureSessionTaskProvenance(ctx);
+  if (current.status !== "captured") return { status: current.status };
+  if (current.source.hostSessionId !== capture.source.hostSessionId || current.source.taskListId !== capture.source.taskListId
+    || current.source.kind !== capture.source.kind)
+    return { status: "identity-mismatch" };
+  const original = capture.tasks.find((entry) => entry.material.id === taskId);
+  const observed = current.tasks.find((entry) => entry.material.id === taskId);
+  if (!original || !observed) return { status: "task-missing" };
+  return { status: original.material.title === observed.material.title
+    && original.material.description === observed.material.description ? "matched" : "content-drift" };
+}
+
+// One instance per journey: observeAdvance only skips an already-dispatched
+// head in this journey. It never updates TaskList or persists a completion.
+export function createTaskStore(ctx) {
+  const skipped = new Set();
+  return {
+    list() {
+      return sessionTasks(ctx).filter((task) => !skipped.has(task.id)).map((task) => ({
+        id: task.id, status: task.status, blockedBy: [...(task.blockedBy ?? [])], owner: task.owner ?? null,
+      }));
+    },
+    observeAdvance(id) { skipped.add(id); },
+    captureProvenance() { return captureSessionTaskProvenance(ctx); },
+    projectProvenance(capture) { return projectSessionTaskProvenance(capture); },
+    revalidateProvenance(capture, id) { return revalidateSessionTaskProvenance(ctx, capture, id); },
+  };
+}

package/extensions/tasks.ts

@@ -26,7 +26,7 @@ import {
   buildPromotionPreview, buildBatchPromotionPreview,
   reconcileDependencies, applyDependencyEdges,
   promotionIdempotencyKey, forwardLinkFor, findExistingPromotedCard,
-  resolveCallerOrigin, canPromote, hasTasksCapability,
+  resolveCallerOrigin, canPromote, hasTasksCapability, SESSION_TASK_PRIORITIES,
 } from "../scripts/enforcement/session_tasks_core_pi.js";
 import { writeCard, updateCard, parseBoard } from "../scripts/enforcement/task_board_core_pi.js";
 
@@ -69,6 +69,15 @@ export default async function tasksPi(pi) {
   const TASK_ICONS = Object.freeze({ pending: "▫", in_progress: "▪", completed: "✓" });
 
   const isVisible = (task) => task?.metadata?._internal !== true;
+  // Presentation only: priority never grants board claim or dispatch authority.
+  const orderedVisibleTasks = () => tasks.filter(isVisible).sort((a, b) => {
+    if (a.status === "completed" && b.status !== "completed") return 1;
+    if (b.status === "completed" && a.status !== "completed") return -1;
+    const rankA = SESSION_TASK_PRIORITIES.indexOf(a.priority);
+    const rankB = SESSION_TASK_PRIORITIES.indexOf(b.priority);
+    if (rankA !== rankB) return (rankA < 0 ? 4 : rankA) - (rankB < 0 ? 4 : rankB);
+    return Number(a.id) - Number(b.id) || a.id.localeCompare(b.id);
+  });
   const unresolvedTaskIds = () => new Set(
     tasks.filter((task) => task.status !== "completed").map((task) => task.id),
   );
@@ -77,6 +86,7 @@ export default async function tasksPi(pi) {
     const parts = [
       `${TASK_ICONS[task.status] ?? "?"} #${task.id}`,
       `[${task.status}]`,
+      ...(task.priority ? [`[${task.priority}]`] : []),
       task.subject,
     ];
     if (task.owner) parts.push(`(${task.owner})`);
@@ -88,7 +98,7 @@ export default async function tasksPi(pi) {
   };
 
   const renderTaskListLineForLLM = (task) => {
-    const parts = [`#${task.id}`, `[${task.status}]`, task.subject];
+    const parts = [`#${task.id}`, `[${task.status}]`, ...(task.priority ? [`[${task.priority}]`] : []), task.subject];
     if (task.owner) parts.push(`(${task.owner})`);
     let line = parts.join(" ");
     const unresolved = unresolvedTaskIds();
@@ -109,6 +119,7 @@ export default async function tasksPi(pi) {
     const parts = [
       TASK_ICONS[task.status] ?? "?",
       `[${task.status}]`,
+      ...(task.priority ? [`[${task.priority}]`] : []),
       task.subject,
     ];
     if (task.owner) parts.push(`(${task.owner})`);
@@ -136,7 +147,7 @@ export default async function tasksPi(pi) {
       return;
     }
 
-    const visible = tasks.filter(isVisible);
+    const visible = orderedVisibleTasks();
     try {
       if (typeof uiHost.ui.setWidget === "function") {
         if (visible.length === 0) {
@@ -150,9 +161,7 @@ export default async function tasksPi(pi) {
           const header = `Tasks  ${counts.pending} pending · ${counts.in_progress} in progress · ${counts.completed} done`;
           const unresolved = unresolvedTaskIds();
           const theme = uiHost.ui.theme;
-          const rows = [...visible]
-            .sort((a, b) => Number(a.id) - Number(b.id) || a.id.localeCompare(b.id))
-            .map((task) => renderWidgetTaskLine(theme, task, unresolved));
+          const rows = visible.map((task) => renderWidgetTaskLine(theme, task, unresolved));
           uiHost.ui.setWidget(WIDGET_KEY, [themed(theme, "fg", ["dim", header], header), ...rows], { placement: "aboveEditor" });
         }
       }
@@ -239,10 +248,14 @@ export default async function tasksPi(pi) {
           description: { type: "string", description: "What needs to be done" },
           activeForm: { type: "string", description: "Present continuous form shown in spinner when in_progress (e.g., \"Running tests\")" },
           metadata: { type: "object", description: "Arbitrary metadata to attach to the task", additionalProperties: true, properties: {} },
+          priority: { type: "string", enum: ["P0", "P1", "P2", "P3"], description: "Optional session-list display priority; does not affect board dispatch." },
         },
         required: ["subject", "description"],
       },
       async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+        if (params.priority !== undefined && !SESSION_TASK_PRIORITIES.includes(params.priority)) {
+          return failResult("invalid-priority", "priority must be P0, P1, P2, or P3");
+        }
         highWaterMark += 1;
         let task = {
           id: String(highWaterMark),
@@ -253,6 +266,7 @@ export default async function tasksPi(pi) {
           blockedBy: [],
           ...(params.activeForm !== undefined ? { activeForm: params.activeForm } : {}),
           ...(params.metadata !== undefined ? { metadata: params.metadata } : {}),
+          ...(params.priority !== undefined ? { priority: params.priority } : {}),
         };
         task = stampOrigin(task);
         tasks.push(task);
@@ -273,7 +287,7 @@ export default async function tasksPi(pi) {
       async execute(_toolCallId, params) {
         const task = findTask(params.taskId);
         if (!task) return { content: [{ type: "text", text: "Task not found" }], details: { task: null } };
-        const lines = [`Task #${task.id}: ${task.subject}`, `Status: ${task.status}`, `Description: ${task.description}`];
+        const lines = [`Task #${task.id}: ${task.subject}`, `Status: ${task.status}`, ...(task.priority ? [`Priority: ${task.priority}`] : []), `Description: ${task.description}`];
         if (task.blockedBy.length > 0) lines.push(`Blocked by: ${task.blockedBy.map((id) => `#${id}`).join(", ")}`);
         if (task.blocks.length > 0) lines.push(`Blocks: ${task.blocks.map((id) => `#${id}`).join(", ")}`);
         // picc-tasks v0.2.0 TaskGet details carry the restricted task shape
@@ -299,16 +313,17 @@ export default async function tasksPi(pi) {
     pi.registerTool({
       name: "TaskList",
       label: "TaskList",
-      description: "Use this tool to list all tasks in the task list.\n\n## When to Use This Tool\n\n- To see what tasks are available to work on (status: 'pending', no owner, not blocked)\n- To check overall progress on the project\n- To find tasks that are blocked and need dependencies resolved\n- After completing a task, to check for newly unblocked work or claim the next available task\n- **Prefer working on tasks in ID order** (lowest ID first) when multiple tasks are available, as earlier tasks often set up context for later ones\n\n## Output\n\nReturns a summary of each task:\n- **id**: Task identifier (use with TaskGet, TaskUpdate)\n- **subject**: Brief description of the task\n- **status**: 'pending', 'in_progress', or 'completed'\n- **owner**: Agent ID if assigned, empty if available\n- **blockedBy**: List of open task IDs that must be resolved first (tasks with blockedBy cannot be claimed until dependencies resolve)\n\nUse TaskGet with a specific task ID to view full details including description and comments.",
+      description: "Use this tool to list all tasks in the task list.\n\n## When to Use This Tool\n\n- To see what tasks are available to work on (status: 'pending', no owner, not blocked)\n- To check overall progress on the project\n- To find tasks that are blocked and need dependencies resolved\n- After completing a task, to check for newly unblocked work or claim the next available task\n- Choose unblocked work by explicit P0–P3 priority, then stable ID order. Unranked tasks follow ranked tasks; completed tasks display last. Session priority never grants board or dispatch authority.\n\n## Output\n\nReturns a summary of each task:\n- **id**: Task identifier (use with TaskGet, TaskUpdate)\n- **subject**: Brief description of the task\n- **status**: 'pending', 'in_progress', or 'completed'\n- **priority**: P0–P3 when set; absent means unranked\n- **owner**: Agent ID if assigned, empty if available\n- **blockedBy**: List of open task IDs that must be resolved first (tasks with blockedBy cannot be claimed until dependencies resolve)\n\nUse TaskGet with a specific task ID to view full details including description and comments.",
       parameters: { type: "object", additionalProperties: false, properties: {} },
       async execute() {
-        const visible = tasks.filter(isVisible);
+        const visible = orderedVisibleTasks();
         if (visible.length === 0) return { content: [{ type: "text", text: "No tasks found" }], details: { tasks: [] } };
         const unresolved = unresolvedTaskIds();
         const list = visible.map((t) => ({
           id: t.id,
           subject: t.subject,
           status: t.status,
+          ...(t.priority !== undefined ? { priority: t.priority } : {}),
           ...(t.owner !== undefined ? { owner: t.owner } : {}),
           blockedBy: t.blockedBy.filter((id) => unresolved.has(id)),
         }));
@@ -321,7 +336,7 @@ export default async function tasksPi(pi) {
     pi.registerTool({
       name: "TaskUpdate",
       label: "TaskUpdate",
-      description: "Use this tool to update a task in the task list.\n\n## When to Use This Tool\n\n**Mark tasks as resolved:**\n- When you have completed the work described in a task\n- When a task is no longer needed or has been superseded\n- IMPORTANT: Always mark your assigned tasks as resolved when you finish them\n- After resolving, call TaskList to find your next task\n\n- ONLY mark a task as completed when you have FULLY accomplished it\n- If you encounter errors, blockers, or cannot finish, keep the task as in_progress\n- When blocked, create a new task describing what needs to be resolved\n- Never mark a task as completed if:\n  - Tests are failing\n  - Implementation is partial\n  - You encountered unresolved errors\n  - You couldn't find necessary files or dependencies\n\n**Delete tasks:**\n- When a task is no longer relevant or was created in error\n- Setting status to `deleted` permanently removes the task\n\n**Update task details:**\n- When requirements change or become clearer\n- When establishing dependencies between tasks\n\n## Fields You Can Update\n\n- **status**: The task status (see Status Workflow below)\n- **subject**: Change the task title (imperative form, e.g., \"Run tests\")\n- **description**: Change the task description\n- **activeForm**: Present continuous form shown in spinner when in_progress (e.g., \"Running tests\")\n- **owner**: Change the task owner (agent name)\n- **metadata**: Merge metadata keys into the task (set a key to null to delete it)\n- **addBlocks**: Mark tasks that cannot start until this one completes\n- **addBlockedBy**: Mark tasks that must complete before this one can start\n\n## Status Workflow\n\nStatus progresses: `pending` → `in_progress` → `completed`\n\nUse `deleted` to permanently remove a task.\n\n## Staleness\n\nMake sure to read a task's latest state using `TaskGet` before updating it.\n\n## Examples\n\nMark task as in progress when starting work:\n```json\n{\"taskId\": \"1\", \"status\": \"in_progress\"}\n```\n\nMark task as completed after finishing work:\n```json\n{\"taskId\": \"1\", \"status\": \"completed\"}\n```\n\nDelete a task:\n```json\n{\"taskId\": \"1\", \"status\": \"deleted\"}\n```\n\nClaim a task by setting owner:\n```json\n{\"taskId\": \"1\", \"owner\": \"my-name\"}\n```\n\nSet up task dependencies:\n```json\n{\"taskId\": \"2\", \"addBlockedBy\": [\"1\"]}\n```",
+      description: "Use this tool to update a task in the task list.\n\n## When to Use This Tool\n\n**Mark tasks as resolved:**\n- When you have completed the work described in a task\n- When a task is no longer needed or has been superseded\n- IMPORTANT: Always mark your assigned tasks as resolved when you finish them\n- After resolving, call TaskList to find your next task\n\n- ONLY mark a task as completed when you have FULLY accomplished it\n- If you encounter errors, blockers, or cannot finish, keep the task as in_progress\n- When blocked, create a new task describing what needs to be resolved\n- Never mark a task as completed if:\n  - Tests are failing\n  - Implementation is partial\n  - You encountered unresolved errors\n  - You couldn't find necessary files or dependencies\n\n**Delete tasks:**\n- When a task is no longer relevant or was created in error\n- Setting status to `deleted` permanently removes the task\n\n**Update task details:**\n- When requirements change or become clearer\n- When establishing dependencies between tasks\n\n## Fields You Can Update\n\n- **status**: The task status (see Status Workflow below)\n- **subject**: Change the task title (imperative form, e.g., \"Run tests\")\n- **description**: Change the task description\n- **activeForm**: Present continuous form shown in spinner when in_progress (e.g., \"Running tests\")\n- **owner**: Change the task owner (agent name)\n- **priority**: Set P0–P3, or null to clear session-list priority\n- **metadata**: Merge metadata keys into the task (set a key to null to delete it)\n- **addBlocks**: Mark tasks that cannot start until this one completes\n- **addBlockedBy**: Mark tasks that must complete before this one can start\n\n## Status Workflow\n\nStatus progresses: `pending` → `in_progress` → `completed`\n\nUse `deleted` to permanently remove a task.\n\n## Staleness\n\nMake sure to read a task's latest state using `TaskGet` before updating it.\n\n## Examples\n\nMark task as in progress when starting work:\n```json\n{\"taskId\": \"1\", \"status\": \"in_progress\"}\n```\n\nMark task as completed after finishing work:\n```json\n{\"taskId\": \"1\", \"status\": \"completed\"}\n```\n\nDelete a task:\n```json\n{\"taskId\": \"1\", \"status\": \"deleted\"}\n```\n\nClaim a task by setting owner:\n```json\n{\"taskId\": \"1\", \"owner\": \"my-name\"}\n```\n\nSet up task dependencies:\n```json\n{\"taskId\": \"2\", \"addBlockedBy\": [\"1\"]}\n```",
       parameters: {
         type: "object",
         additionalProperties: false,
@@ -331,6 +346,7 @@ export default async function tasksPi(pi) {
           description: { type: "string", description: "New description for the task" },
           activeForm: { type: "string", description: "Present continuous form shown in spinner when in_progress (e.g., \"Running tests\")" },
           owner: { type: "string", description: "New owner for the task" },
+          priority: { type: ["string", "null"], enum: ["P0", "P1", "P2", "P3", null], description: "Set P0–P3 display priority, or null to clear. No board authority." },
           metadata: { type: "object", description: "Metadata keys to merge into the task. Set a key to null to delete it.", additionalProperties: true, properties: {} },
           status: { type: "string", enum: ["pending", "in_progress", "completed", "deleted"], description: "New status for the task" },
           addBlocks: { type: "array", items: { type: "string" }, description: "Task IDs that this task blocks" },
@@ -344,12 +360,19 @@ export default async function tasksPi(pi) {
           return { content: [{ type: "text", text: "Task not found" }], details: { success: false, taskId: params.taskId, error: "Task not found", updatedFields: [] } };
         }
         const task = tasks[idx];
+        if (params.priority !== undefined && params.priority !== null && !SESSION_TASK_PRIORITIES.includes(params.priority)) {
+          return failResult("invalid-priority", "priority must be P0, P1, P2, P3, or null to clear");
+        }
         const updatedFields = [];
         let statusChange;
         if (params.subject !== undefined && params.subject !== task.subject) { task.subject = params.subject; updatedFields.push("subject"); }
         if (params.description !== undefined && params.description !== task.description) { task.description = params.description; updatedFields.push("description"); }
         if (params.activeForm !== undefined && params.activeForm !== task.activeForm) { task.activeForm = params.activeForm; updatedFields.push("activeForm"); }
         if (params.owner !== undefined && params.owner !== task.owner) { task.owner = params.owner; updatedFields.push("owner"); }
+        if (params.priority !== undefined && params.priority !== task.priority) {
+          if (params.priority === null) delete task.priority; else task.priority = params.priority;
+          updatedFields.push("priority");
+        }
         if (params.metadata !== undefined) {
           const merged = { ...(task.metadata ?? {}) };
           for (const [k, v] of Object.entries(params.metadata)) {
@@ -692,7 +715,7 @@ export default async function tasksPi(pi) {
             return;
           }
           const blocks = [];
-          for (const task of tasks) {
+          for (const task of [...orderedVisibleTasks(), ...tasks.filter((task) => !isVisible(task))]) {
             const internal = task.metadata?._internal === true ? " [internal]" : "";
             blocks.push(`${renderTaskListLine(task)}${internal}`);
             blocks.push(`    ${task.description}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evoclock/pi-agentic-driver",
-  "version": "0.10.1",
+  "version": "1.0.0",
   "description": "Guardrail extensions for Agentic Driver: advisory review, bounded Herdr communication, and guarded worker lifecycle.",
   "type": "module",
   "license": "AGPL-3.0-only",
@@ -42,6 +42,7 @@
     "extensions/code-phage.js",
     "extensions/herdr-communication.ts",
     "extensions/herdr-dispatch.ts",
+    "extensions/task-store-adapter.ts",
     "extensions/task-board.ts",
     "extensions/pulse.ts",
     "lib/adapters/diff-scope.mjs",
@@ -54,6 +55,18 @@
     "lib/typescript_ast_metrics.mjs",
     "scripts/enforcement/herdr_communication_pi.js",
     "scripts/enforcement/herdr_async_dispatch_pi.js",
+    "scripts/enforcement/herdr_async_seam_pi.js",
+    "scripts/enforcement/board_claim_bridge_pi.js",
+    "scripts/enforcement/nudge_classifier_pi.js",
+    "scripts/enforcement/nudge_config_pi.js",
+    "scripts/enforcement/nudge_ledger_pi.js",
+    "scripts/enforcement/recovery_evidence_store_pi.js",
+    "extensions/recovery-evidence.ts",
+    "scripts/enforcement/recovery_evidence_review_pi.js",
+    "docs/recovery-evidence-store.md",
+    "scripts/enforcement/nudge_reason_state_pi.js",
+    "scripts/enforcement/nudge_validate_pi.js",
+    ".agentic-driver/nudge.defaults.json",
     "README.md",
     "LICENSE",
     "extensions/herdr-lifecycle.ts",
@@ -69,6 +82,11 @@
     "PROVENANCE.md",
     "extensions/aidr.ts",
     "scripts/aidr_writing_review.js",
+    "scripts/codebase_inventory.py",
+    "scripts/codebase_inventory_gate.py",
+    "config/codebase-inventory.schema.json",
+    "docs/codebase-inventory.md",
+    ".githooks/pre-commit",
     "templates/AGENTS.md",
     "scripts/enforcement/task_board_core_pi.js",
     "scripts/enforcement/pulse_core_pi.js",