@evoclock/pi-agentic-driver 0.6.0 → 0.8.0

package/README.md

@@ -1,4 +1,4 @@
-# pi-agentic-driver v0.6.0
+# pi-agentic-driver v0.8.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.6.0-blue?style=flat" alt="Version 0.6.0"/>
+  <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/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"/>
@@ -49,6 +49,8 @@ proofs for agentic workflows.
 | `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_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 |
 
 **Status: active development and testing.** Each extension ships only after
 it passes fixture-based acceptance, native tests, live-session checks, and
@@ -187,6 +189,34 @@ silently, and return results as untrusted evidence.
 </details>
 
 
+<details>
+<summary><strong>task board, planned work you can see</strong> <em>(released, 0.8.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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+</details>
+
 - **project status and state review.** Read-only projections of workspace Git
   state, formal records, and task-state health.
 - **role-lane routing and warm sessions.** Separate lanes handle
@@ -345,18 +375,72 @@ Small models on your own desk are worth taking seriously as reviewers.
 
 </details>
 
+<details>
+<summary><strong>autonomous journeys, overnight operation</strong> <em>(released, 0.7.0)</em></summary>
+
+Dispatch a worker journey that runs end to end while you are away. The
+journey proceeds through steps without pausing for confirmation, replaces
+agents that get stuck, and records everything in one report you read when
+you come back.
+
+Autonomy is entered by your words alone. Say "run these overnight end to
+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.
+
+### The cast
+
+You name the agents for the journey, and that list becomes the standing
+permission. If the implementer gets stuck at 3am, a replacement spawns
+automatically: same role, same model, both in the list you authorized.
+If a task needs an agent you didn't name, the attempt is recorded and that
+thread stops. Nothing outside your list can appear while you sleep.
+
+The cast is frozen at dispatch and never grows. It can only shrink in
+practice (roles finishing their work), never widen.
+
+### When agents get stuck
+
+A stuck agent doesn't block the journey. The journey detects the stall,
+spawns a replacement from the cast, and the replacement starts with a
+mandatory gap analysis: read the task spec, inspect the repository, consult
+the journey history, and state what remains before resuming. The replacement
+must show that the remaining work is smaller than what its predecessor left.
+If it can't, the journey stops that role and continues with the others.
+
+### The morning report
+
+One block tells you what happened: the terminal state, each step's outcome,
+every replacement with its gap analysis and progress judgment, and any
+denials. Every claim is tied to a receipt or a report excerpt. No prose
+narrative to reconstruct; you read the report and know exactly where things
+stand.
+
+</details>
+
+<details>
+<summary><strong>attended-authority guard</strong> <em>(released, 0.7.0)</em></summary>
+
+The safety net between an agent and your shell. When a model tries to
+delete, overwrite, or push, the guard stops it and asks you. Safe commands
+pass through untouched. If you deny, you get a clear reason and the session
+continues, and the agent does not retry behind your back. In headless runs
+where no human can confirm, destructive commands are refused rather than
+silently allowed.
+
+</details>
+
 **Under development in this theme:**
 
 - **native macOS container proof.** The native Apple Container runtime has
   passed a fixed local isolation qualification: read-only repository mount,
   no network, automatic removal. The native Pi adapter is not yet part of the
   released package.
-- **attended-authority guard.** The safety net between an agent and your
-  shell. When a model tries to delete, overwrite, or push, the guard stops it
-  and asks you. Safe commands pass through untouched. If you deny, you get a
-  clear reason and the session continues, and the agent does not retry behind
-  your back. In headless runs where no human can confirm, destructive
-  commands are refused rather than silently allowed.
 
 ## Session continuity
 
@@ -436,7 +520,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.6.0
+pi install git:github.com/evoclock/pi-agentic-driver@v0.8.0
 ```
 
 Released extensions load standalone; neither requires the other.
@@ -450,7 +534,7 @@ extensions you want with the object form in your Pi settings:
 {
   "packages": [
     {
-      "source": "npm:@evoclock/pi-agentic-driver@0.6.0",
+      "source": "npm:@evoclock/pi-agentic-driver@0.8.0",
       "extensions": [
         "extensions/aidr.ts",
         "extensions/code-phage.js"

package/extensions/attended-authority-guard.ts

@@ -0,0 +1,7 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+export default async function attendedAuthorityGuard(pi) {
+  const module = await import(new URL("../scripts/enforcement/attended_authority_guard.js", import.meta.url).href);
+  return module.registerAttendedAuthorityGuard(pi);
+}

package/extensions/task-board.ts

@@ -0,0 +1,31 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+// BOARD-1 provider extension (§5 reversibility): the board surface registers
+// only when a real board file is observed in the workspace. No board file,
+// no behavior change and no new tool.
+
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+// Documented board locations (design §2): workspace-level Obsidian Kanban
+// Markdown, or vogelkop's simpler TASKS.md shape.
+const BOARD_FILENAMES = ["board.md", "TASKS.md"];
+
+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;
+}
+
+export default async function taskBoardPi(pi) {
+  const module = await import(new URL("../scripts/enforcement/task_board_core_pi.js", import.meta.url).href);
+  const boardPath = resolveBoardPath(pi?.ctx?.cwd);
+  if (boardPath === null) {
+    return { registered: [], observation: { present: false, boardPath: null } };
+  }
+  return module.registerKanbanBoardTools(pi, { boardPath });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evoclock/pi-agentic-driver",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Guardrail extensions for Agentic Driver: advisory review, bounded Herdr communication, and guarded worker lifecycle.",
   "type": "module",
   "license": "AGPL-3.0-or-later",
@@ -34,9 +34,12 @@
     "governance"
   ],
   "files": [
+    "extensions/attended-authority-guard.ts",
+    "scripts/enforcement/attended_authority_guard.js",
     "extensions/code-phage.js",
     "extensions/herdr-communication.ts",
     "extensions/herdr-dispatch.ts",
+    "extensions/task-board.ts",
     "lib/adapters/diff-scope.mjs",
     "lib/adapters/evidence.mjs",
     "lib/adapters/narrative.mjs",
@@ -62,7 +65,8 @@
     "PROVENANCE.md",
     "extensions/aidr.ts",
     "scripts/aidr_writing_review.js",
-    "templates/AGENTS.md"
+    "templates/AGENTS.md",
+    "scripts/enforcement/task_board_core_pi.js"
   ],
   "pi": {
     "extensions": [

package/scripts/aidr_writing_review.js

@@ -40,6 +40,18 @@ const STE_PHRASAL_GUIDANCE = Object.freeze({
   "look at": "examine",
   "set up": "configure or install",
 });
+// Project terminology rules (established in session guidance, encoded here so
+// AI;DR enforces them advisorially):
+// - "limited" for numeric limits; "controlled" or "authorised" for authority
+//   and behavior; "approved" or "authorised" for tasks.
+// - "fundamental" or "crucial" instead of the metaphor "load-bearing".
+// - Avoid "bounded" in prose entirely; use "limited" for numeric limits.
+//   (The boundedText identifier is a code name, not prose, and is flagged
+//   separately for a future rename.)
+const TERMINOLOGY_GUIDANCE = Object.freeze({
+  bounded: "use limited for numeric limits; avoid bounded in prose",
+  "load-bearing": "use fundamental or crucial",
+});
 const STE_MODAL_GUIDANCE = Object.freeze({
   should: "use must for a requirement, or state the recommendation directly",
   may: "use can for ability or must have permission language when needed",
@@ -154,6 +166,13 @@ function steFindings(prose, sentences, documentType) {
     message: "State requirement, ability, permission, or condition precisely; do not leave the modal meaning implicit.",
     examples: modalExamples,
   });
+  const terminologyExamples = steTermExamples(prose, TERMINOLOGY_GUIDANCE);
+  if (terminologyExamples.length) findings.push({
+    rule: "STE-T1",
+    kind: "ste-project-terminology",
+    message: "Use the project terminology: limited for numeric limits, controlled or authorised for authority and behavior, approved or authorised for tasks, fundamental or crucial instead of load-bearing, and avoid bounded in prose.",
+    examples: terminologyExamples,
+  });
   if (/\band\/or\b/i.test(prose)) findings.push({
     rule: "STE-C1",
     kind: "ste-conjunction",

package/scripts/enforcement/attended_authority_guard.js

@@ -0,0 +1,223 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+// Attended-authority destructive-command guard for Pi.
+//
+// Ported observable behavior (private reference: scripts/enforcement/
+// pi_attended_authority.js + cc_destructive_command_guard_hook.py):
+// - Intercept tool calls before execution via the `tool_call` event.
+// - Destructive shell/Git operations require native confirmation.
+// - Safe reads/builds/tests pass through untouched.
+// - An explicit denial returns a clear reason and the session continues;
+//   no hidden retry and no automatic re-ask.
+// - Headless / no-confirmation contexts refuse destructive operations
+//   fail-closed.
+// - No bypasses, no model-supplied authority, no silent escalation. The
+//   model cannot mark a call safe; classification is structural only.
+
+import { isNativeTuiContext } from "./native_tui_context.js";
+
+export const GUARD_SCHEMA = "pi-agentic-driver.attended-authority.v1";
+
+// Tool names that can mutate the workspace.
+const MUTATING_TOOLS = new Set(["bash", "write", "edit"]);
+
+// Read-only / build / test commands that always pass through.
+const SAFE_COMMAND_PREFIXES = [
+  "cat", "ls", "head", "tail", "grep", "rg", "find", "sed -n", "awk",
+  "wc", "file", "stat", "which", "echo", "pwd", "date", "env",
+  "node --check", "node --test", "npm test", "npm run",
+  "python3 -m pytest", "pytest", "make", "cmake",
+  "git status", "git log", "git diff", "git show", "git branch",
+  "git remote", "git rev-parse", "git blame", "git describe",
+  "git config --get", "git ls-files",
+];
+
+// Arbitrary-code interpreter execution: any code payload can perform a
+// destructive operation, so these forms are classified fail-closed.
+const DESTRUCTIVE_SHELL_PATTERNS = [
+  { pattern: /\brm\b[^|;&]*\s(-[a-z]*[rf][a-z]*\s|--recursive|--force)/, kind: "recursive or forced file deletion" },
+  { pattern: /\bsudo\s+rm\b/, kind: "privileged file deletion" },
+  { pattern: /\brmdir\b|\bunlink\b/, kind: "file or directory deletion" },
+  { pattern: /\bmkfs\b|\bshred\b|\bdd\b\s+if=/, kind: "irreversible disk or file operation" },
+  { pattern: /\btruncate\s+-s\s*0\b/, kind: "file truncation" },
+  { pattern: /\bkill\b\s+-9\b|\bpkill\b/, kind: "forced process termination" },
+  { pattern: /\bchmod\s+-R\b|\bchown\s+-R\b/, kind: "recursive permission change" },
+  { pattern: /\bnode\s+(-e|--eval)\b/, kind: "arbitrary JavaScript execution via node -e" },
+  { pattern: /\bpython3?\s+-c\b/, kind: "arbitrary Python execution via python -c" },
+  { pattern: /\bnpx\b/, kind: "arbitrary package execution via npx" },
+];
+
+// Scope note: plain `rm file` (no -r/-f) is intentionally NOT classified
+// destructive here; the guard targets recursive/forced deletion and
+// irreversible operations. Any `git push`, forced or not, is treated
+// conservatively as destructive because pushes publish history to remotes.
+
+// Destructive Git operations.
+const DESTRUCTIVE_GIT_PATTERNS = [
+  { pattern: /\bgit\s+push\b[^|;&]*(--force|-f\b)/, kind: "forced Git push" },
+  { pattern: /\bgit\s+push\b/, kind: "Git push" },
+  { pattern: /\bgit\s+reset\s+--hard\b/, kind: "hard Git reset" },
+  { pattern: /\bgit\s+reset\b/, kind: "Git reset" },
+  { pattern: /\bgit\s+clean\b/, kind: "Git clean" },
+  { pattern: /\bgit\s+checkout\s+--\s/, kind: "Git working-tree discard" },
+  { pattern: /\bgit\s+restore\b/, kind: "Git working-tree discard" },
+  { pattern: /\bgit\s+stash\s+(drop|clear|pop)\b/, kind: "Git stash mutation" },
+  { pattern: /\bgit\s+stash\b/, kind: "Git stash mutation" },
+  { pattern: /\bgit\s+rebase\b/, kind: "Git history rewrite" },
+  { pattern: /\bgit\s+filter-(branch|repo)\b/, kind: "Git history rewrite" },
+  { pattern: /\bgit\s+commit\b[^|;&]*--amend\b/, kind: "Git history rewrite" },
+  { pattern: /\bgit\s+branch\s+(-D|-d)\b/, kind: "protected branch deletion" },
+  { pattern: /\bgit\s+tag\s+-d\b/, kind: "protected tag deletion" },
+  { pattern: /\bgit\s+cherry-pick\b|\bgit\s+revert\b/, kind: "Git history mutation" },
+];
+
+// Paths whose deletion or overwrite is always treated as destructive.
+const PROTECTED_PATHS = [
+  ".env", ".ssh", ".gnupg", "node_modules", ".git",
+  "package-lock.json", "pnpm-lock.yaml", "Cargo.lock", "poetry.lock",
+];
+
+// Quote-aware tokenization: normalizes shell quoting so `rm '-rf'`,
+// `git "push"`, and split/embedded quoting such as `r'm' '-rf'` still
+// expose their destructive tokens to the patterns. Escapes are also
+// stripped (`\rm` -> `rm`) so an escaped destructive token cannot dodge
+// classification. Normalization is only used for the destructive
+// patterns, never to widen the safe-prefix list.
+function unquoteTokens(text) {
+  return String(text ?? "")
+    .split(/[\s\n]+/)
+    .map((token) => token
+      .replace(/^"/, "").replace(/"$/, "")
+      .replace(/^'/, "").replace(/'$/, "")
+      .replace(/["']/g, "")
+      .replace(/\\(.)/g, "$1"))
+    .join(" ");
+}
+
+export function classifyBashCommand(command) {
+  const text = String(command ?? "").trim();
+  if (!text) return { destructive: false };
+  // A safe prefix wins only when the whole command is that single simple
+  // command (no chaining, redirection, or command substitution), so a
+  // destructive payload cannot hide behind a safe-looking prefix.
+  const compound = /[;&|>`]|\$\(|\n/.test(text);
+  const redirection = /(^|\s)(>{1,2}|<)/.test(text);
+  // Structural destructive verdicts win over safe-looking prefixes, so a
+  // destructive form such as `git branch -D` cannot hide behind a safe
+  // prefix such as `git branch`.
+  for (const { pattern, kind } of DESTRUCTIVE_SHELL_PATTERNS) {
+    if (pattern.test(text) || pattern.test(unquoteTokens(text))) return { destructive: true, kind };
+  }
+  for (const { pattern, kind } of DESTRUCTIVE_GIT_PATTERNS) {
+    if (pattern.test(text) || pattern.test(unquoteTokens(text))) return { destructive: true, kind };
+  }
+  if (!compound && !redirection) {
+    for (const prefix of SAFE_COMMAND_PREFIXES) {
+      if (text === prefix || text.startsWith(`${prefix} `) || text.startsWith(`${prefix}\t`)) {
+        return { destructive: false };
+      }
+    }
+  }
+  // Output redirection overwrites an existing file in place.
+  const redirect = text.match(/(?:^|\s)>{1,2}\s*([^\s;&|]+)\s*$/);
+  if (redirect) {
+    const target = redirect[1].replace(/^["']|["']$/g, "");
+    return {
+      destructive: true,
+      kind: `file overwrite via redirection to ${target}`,
+    };
+  }
+  // Unrecognized non-safe commands are not destructive by default; the
+  // guard only intercepts structurally destructive operations.
+  return { destructive: false };
+}
+
+function touchesProtectedPath(path) {
+  const normalized = String(path ?? "").replace(/\\/g, "/");
+  return PROTECTED_PATHS.some((entry) =>
+    normalized === entry
+    || normalized.endsWith(`/${entry}`)
+    || normalized.includes(`/${entry}/`)
+    || normalized.startsWith(`./${entry}`),
+  );
+}
+
+// Existing-file overwrite detection is injected so tests stay filesystem-free.
+export function classifyWriteCall(toolName, input, existsSync) {
+  if (toolName !== "write" && toolName !== "edit") {
+    return { destructive: false };
+  }
+  const path = input?.path ?? input?.file_path ?? "";
+  if (touchesProtectedPath(path)) {
+    return { destructive: true, kind: `protected path write to ${path}` };
+  }
+  if (toolName === "write" && typeof existsSync === "function" && path && existsSync(path)) {
+    return { destructive: true, kind: `overwrite of existing file ${path}` };
+  }
+  return { destructive: false };
+}
+
+export function confirmationBody(toolName, input, kind) {
+  return [
+    `Attended-authority guard: ${kind}.`,
+    `Tool: ${toolName}`,
+    toolName === "bash" ? `Command: ${input?.command}` : `Path: ${input?.path ?? input?.file_path ?? ""}`,
+    "",
+    "Allow this destructive operation?",
+  ].join("\n");
+}
+
+export function denialReason(toolName, kind, context) {
+  if (!isNativeTuiContext(context)) {
+    return `${GUARD_SCHEMA}: destructive ${toolName} operation (${kind}) refused fail-closed: no native confirmation surface in this headless context`;
+  }
+  return `${GUARD_SCHEMA}: destructive ${toolName} operation (${kind}) denied by user; the session continues and this call is not retried`;
+}
+
+/**
+ * Core guard for one tool call. Returns undefined to allow the call, or
+ * `{ block: true, reason }` to refuse it. Confirmation is native-only:
+ * `ctx.ui.confirm` in an interactive TUI. Headless contexts never confirm.
+ * Model-supplied fields on the event can never grant authority.
+ */
+export async function guardToolCall(event, ctx, options = {}) {
+  const toolName = String(event?.toolName ?? "").toLowerCase();
+  if (!MUTATING_TOOLS.has(toolName)) return undefined;
+  const input = event?.input && typeof event.input === "object" ? event.input : {};
+
+  const bash = toolName === "bash"
+    ? classifyBashCommand(input.command)
+    : { destructive: false };
+  const write = toolName === "bash"
+    ? { destructive: false }
+    : classifyWriteCall(toolName, input, options.existsSync);
+  const verdict = bash.destructive ? bash : write;
+  if (!verdict.destructive) return undefined;
+
+  const context = options.context ?? ctx;
+  if (!isNativeTuiContext(context)) {
+    return { block: true, reason: denialReason(toolName, verdict.kind, context) };
+  }
+  const confirmed = await context.ui.confirm(
+    "Destructive operation",
+    confirmationBody(toolName, input, verdict.kind),
+  );
+  if (confirmed === true) return undefined;
+  return { block: true, reason: denialReason(toolName, verdict.kind, context) };
+}
+
+/**
+ * Register the guard on a Pi host instance. Duplicate registration on the
+ * same instance is ignored.
+ */
+const REGISTERED = new WeakSet();
+
+export function registerAttendedAuthorityGuard(pi, options = {}) {
+  if (!pi || REGISTERED.has(pi)) return undefined;
+  REGISTERED.add(pi);
+  pi.on?.("tool_call", (event, ctx) => guardToolCall(event, ctx, options));
+  return { registered: true, schema: GUARD_SCHEMA };
+}
+
+export default guardToolCall;