@evoclock/pi-agentic-driver 0.8.3 → 0.9.0

package/README.md

@@ -1,4 +1,4 @@
-# pi-agentic-driver v0.8.0
+# pi-agentic-driver v0.9.0
 
 <p align="center">
   <img src="assets/Yamagane-origami.png" alt="pi-agentic-driver, Yamagane origami mark" width="140"/>
@@ -7,7 +7,7 @@
 <p align="center">
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL%20v3-blue?style=flat" alt="License: AGPL v3"/></a>
   <a href="https://www.npmjs.com/package/@evoclock/pi-agentic-driver"><img src="https://img.shields.io/npm/v/@evoclock/pi-agentic-driver?style=flat" alt="npm version"/></a>
-  <img src="https://img.shields.io/badge/version-0.8.0-blue?style=flat" alt="Version 0.8.0"/>
+  <img src="https://img.shields.io/badge/version-0.9.0-blue?style=flat" alt="Version 0.9.0"/>
   <img src="https://img.shields.io/badge/status-active%20development%20%26%20testing-orange?style=flat" alt="Status"/>
   <img src="https://img.shields.io/badge/JavaScript-F7DF1E?style=flat&logo=javascript&logoColor=black" alt="JavaScript"/>
   <img src="https://img.shields.io/badge/TypeScript-3178C6?style=flat&logo=typescript&logoColor=white" alt="TypeScript"/>
@@ -51,6 +51,8 @@ proofs for agentic workflows.
 | `agentic_worker_dispatch` | Runs controlled worker journeys and observes worker liveness. | 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 |
 
 **Status: active development and testing.** Each extension ships only after
 it passes fixture-based acceptance, native tests, live-session checks, and
@@ -190,30 +192,51 @@ silently, and return results as untrusted evidence.
 
 
 <details>
-<summary><strong>task board, planned work you can see</strong> <em>(released, 0.8.0)</em></summary>
+<summary><strong>task board, planned and automated work you can see</strong> <em>(released, 0.9.0)</em></summary>
 
-Keep planned work on a Kanban board. You read and edit the board in
-Obsidian or in the Vogelkop Task Board pane (our upcoming Scientific and
-Research Workbench). Agents read the same board and add cards to it.
+Keep planned work in canonical `TASKS.md`. You can read it directly or use
+the generated `board.md` view in Obsidian. Agents use the same canonical
+record through natural-language board tools.
 
-The board appears only when a `board.md` or `TASKS.md` file exists in the
-workspace. With no board file, the tools do not appear and nothing changes.
+You can tell an agent to add, edit, move, block, propose, close, or remove a
+card. The trusted writer assigns its ID, checks its fields, records your
+instruction, and protects its dispatch provenance.
 
-When an agent adds a card, a trusted writer does the bookkeeping: it
-assigns the card ID, computes the integrity hash, checks the card, and
-records who authorized the work. The record comes from you: your
-instruction, or your approval of an agent's proposal. A card without that
-record cannot be dispatched. A hand-edited card cannot fake the record, and
-a tampered card refuses to run.
+Agents cannot invent additional work or complete a card on their own. An
+agent report is evidence for your review. Only your clear instruction or
+direct board action completes the card.
 
-Only you complete a card. Move it to done in your board UI, or tell an
-agent to close it. An agent report that says the work is finished is
-evidence for your review. It is never the completion itself.
+For automated work, you set an explicit policy for the board. It defines:
 
-The card format is shared. The same board renders in Obsidian, with
-optional Tasks-plugin emoji, and in the Vogelkop Task Board pane. The
-machine-readable fields are the single source of truth, so there is no
-second copy to keep in sync.
+- allowed roles and repositories;
+- contained placement;
+- the maximum concurrent work;
+- the policy expiry; and
+- the risk ceiling.
+
+Without a valid policy, automated dispatch is refused.
+
+`agentic_kanban_board_dispatch` claims the highest-priority eligible card and
+creates a single-attempt assignment envelope. The envelope binds the card,
+repository, 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.
+
+Consuming an envelope releases the claim. It does not mark the card done.
+
+Claims and envelopes are kept in authenticated state beside `TASKS.md`. The
+derived `board.md` view shows active claims but never becomes an authority
+source.
+
+Coming next:
+
+- an optional watcher that checks for dispatchable work;
+- Vogelkop support for the shared card fields; and
+- our own Obsidian plugin for canonical `TASKS.md`.
 
 </details>
 
@@ -388,10 +411,10 @@ 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.
 
-The journeys run work you dispatch in natural language: work that is real
-and authorized but not yet formally placed on a kanban board. A task board
-integration is planned, and once it ships, planned journeys will execute
-board-managed work with the same containment and safety guarantees.
+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.
 
 ### The cast
 
@@ -520,7 +543,7 @@ pi install npm:@evoclock/pi-agentic-driver
 Or from Git at a pinned tag:
 
 ```sh
-pi install git:github.com/evoclock/pi-agentic-driver@v0.8.0
+pi install git:github.com/evoclock/pi-agentic-driver@v0.9.0
 ```
 
 Released extensions load standalone; neither requires the other.
@@ -534,7 +557,7 @@ extensions you want with the object form in your Pi settings:
 {
   "packages": [
     {
-      "source": "npm:@evoclock/pi-agentic-driver@0.8.0",
+      "source": "npm:@evoclock/pi-agentic-driver@0.9.0",
       "extensions": [
         "extensions/aidr.ts",
         "extensions/code-phage.js"

package/extensions/task-board.ts

@@ -9,18 +9,25 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 
-const BOARD_FILENAMES = ["board.md", "TASKS.md"];
+// The canonical file comes first: the projection (board.md) is a derived
+// view and must never be the board the tools operate on.
+const BOARD_FILENAMES = ["TASKS.md", "board.md"];
 
+// Returns the board path for the workspace: an existing board file if one is
+// present, otherwise the canonical TASKS.md candidate (the write tool
+// bootstraps a fresh board there). Null only when the workspace is unknown.
 export function resolveBoardPath(cwd) {
   if (typeof cwd !== "string" || cwd === "") return null;
   for (const name of BOARD_FILENAMES) {
     const candidate = join(cwd, name);
     if (existsSync(candidate)) return candidate;
   }
-  return null;
+  return join(cwd, "TASKS.md");
 }
 
 export default async function taskBoardPi(pi) {
   const module = await import(new URL("../scripts/enforcement/task_board_core_pi.js", import.meta.url).href);
-  return module.registerKanbanBoardTools(pi, { resolveBoardPath });
+  return module.registerKanbanBoardTools(pi, {
+    resolveBoardPath: (ctx) => resolveBoardPath(typeof ctx === "string" ? ctx : ctx?.cwd || process.cwd()),
+  });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evoclock/pi-agentic-driver",
-  "version": "0.8.3",
+  "version": "0.9.0",
   "description": "Guardrail extensions for Agentic Driver: advisory review, bounded Herdr communication, and guarded worker lifecycle.",
   "type": "module",
   "license": "AGPL-3.0-or-later",

package/scripts/enforcement/herdr_async_dispatch_pi.js

@@ -16,6 +16,7 @@ import {
   HERDR_COMMUNICATION_ACTIONS,
 } from "./herdr_communication_pi.js";
 import { isNativeTuiContext } from "./native_tui_context.js";
+import { prepareEnvelopeForExecution, validateEnvelopeForExecution, consumeEnvelope } from "./task_board_core_pi.js";
 
 export const WORKER_DISPATCH_TOOL = "agentic_worker_dispatch";
 export const WORKER_DISPATCH_SCHEMA = "agentic-driver.worker-dispatch.v1";
@@ -246,24 +247,53 @@ export async function runWorkerJourney(params, context, options = {}, signal) {
   const communicationOptions = options.communication ?? options;
   const replacementRole = options.replacementRole ?? role;
   const replacementModel = options.replacementModel ?? options.model ?? params.model;
-  const finish = (status) => ({
-    schema: WORKER_DISPATCH_SCHEMA,
-    ok: status === "completed" || status === "exhausted" || status === "waiting-approval",
-    action: "dispatch",
-    mode,
-    autonomy,
-    ...(journey.cast ? { cast: journey.cast } : {}),
-    role,
-    status,
-    steps: journey.steps,
-    stepCount: journey.steps.filter((step) => step.status === "done").length,
-    code: journey.code,
-    report: journeyReceipt(journey),
-    reportMarkers: { open: "[WORKER_JOURNEY_REPORT_BEGIN]", close: "[WORKER_JOURNEY_REPORT_END]" },
-    handoff: journey.handoff,
-    nonAuthorizing: true,
-    persisted: false,
-  });
+  const board = options.board && typeof options.board === "object"
+    && typeof options.board.boardPath === "string" && options.board.envelope
+    ? options.board
+    : null;
+  let boardAttemptStarted = false;
+  let envelopeConsumed = false;
+  const finish = async (requestedStatus) => {
+    let status = requestedStatus;
+    if (board && boardAttemptStarted && !envelopeConsumed) {
+      const reason = ["completed", "exhausted", "cancelled", "failed", "waiting-approval", "role-blocked", "worker-unresponsive"].includes(status)
+        ? status
+        : status.startsWith("worker-unresponsive") ? "worker-unresponsive" : "failed";
+      let consumed;
+      try {
+        consumed = consumeEnvelope({ boardPath: board.boardPath, envelopeId: board.envelope.envelopeId, reason });
+      } catch (error) {
+        consumed = { ok: false, code: error?.code, reason: String(error?.message || error) };
+      }
+      if (consumed?.ok !== true) {
+        status = "failed";
+        journey.status = "failed";
+        journey.code = consumed?.code || "envelope-consume-failed";
+        journey.steps.push({ step: journey.steps.length + 1, taskId: null, status: "failed", error: consumed?.reason || "envelope consumption failed closed" });
+      } else {
+        envelopeConsumed = true;
+      }
+    }
+    journey.status = status;
+    return {
+      schema: WORKER_DISPATCH_SCHEMA,
+      ok: status === "completed" || status === "exhausted" || status === "waiting-approval",
+      action: "dispatch",
+      mode,
+      autonomy,
+      ...(journey.cast ? { cast: journey.cast } : {}),
+      role,
+      status,
+      steps: journey.steps,
+      stepCount: journey.steps.filter((step) => step.status === "done").length,
+      code: journey.code,
+      report: journeyReceipt(journey),
+      reportMarkers: { open: "[WORKER_JOURNEY_REPORT_BEGIN]", close: "[WORKER_JOURNEY_REPORT_END]" },
+      handoff: journey.handoff,
+      nonAuthorizing: true,
+      persisted: false,
+    };
+  };
 
   // Explicit unstuck path: with native confirmation, spin up a replacement
   // worker for the same trusted repository/role through the existing
@@ -375,6 +405,35 @@ export async function runWorkerJourney(params, context, options = {}, signal) {
   }
   if (signal?.aborted) return finish("cancelled");
 
+  // Board-planned journey: authenticate the persisted envelope, prepare its
+  // assigned branch exactly once, then validate again. Every consequential
+  // prompt below repeats validation so mid-journey drift fails closed.
+  const checkBoardEnvelope = () => board
+    ? validateEnvelopeForExecution({ boardPath: board.boardPath, envelope: board.envelope })
+    : { ok: true };
+  if (board) {
+    let guard;
+    try {
+      const prepared = prepareEnvelopeForExecution({ boardPath: board.boardPath, envelope: board.envelope });
+      if (!prepared.ok) guard = prepared;
+      else {
+        boardAttemptStarted = true;
+        guard = checkBoardEnvelope();
+      }
+    } catch (error) {
+      journey.status = "failed";
+      journey.code = error?.code || "envelope-invalid";
+      journey.steps.push({ step: 0, taskId: null, status: "failed", error: String(error?.message || error).slice(0, 256) });
+      return finish("failed");
+    }
+    if (!guard.ok) {
+      journey.status = "failed";
+      journey.code = guard.code || "envelope-invalid";
+      journey.steps.push({ step: 0, taskId: null, status: "failed", error: guard.reason });
+      return finish("failed");
+    }
+  }
+
   for (let stepIndex = 1; stepIndex <= maxSteps; stepIndex += 1) {
     if (signal?.aborted) { journey.status = "cancelled"; return finish("cancelled"); }
 
@@ -452,6 +511,19 @@ export async function runWorkerJourney(params, context, options = {}, signal) {
       }
     }
 
+    // Revalidate immediately before the consequential prompt. This catches
+    // expiry, card/claim changes, and repository/branch/revision drift that
+    // occurred during pulse, queue observation, or confirmation.
+    if (board) {
+      const guard = checkBoardEnvelope();
+      if (!guard.ok) {
+        journey.status = "failed";
+        journey.code = guard.code || "envelope-invalid";
+        journey.steps.push({ step: stepIndex, taskId: task.id, status: "failed", error: guard.reason });
+        return finish("failed");
+      }
+    }
+
     // One prompt exchange. Any failure is terminal for the journey; there is
     // no invisible retry or resend.
     const exchange = await executeHerdrCommunication(