@evoclock/pi-agentic-driver 0.9.2 → 0.9.4

package/PROVENANCE.md

@@ -72,3 +72,12 @@ This repository is the public package source for `@evoclock/pi-agentic-driver`.
   change it, the switch is not persisted, and each microVM run still requires
   native confirmation. Headless sessions fail closed. The existing trusted
   facts, fixed argv, receipt validation, and cleanup checks remain unchanged.
+- The unified tasks skill (session task tools + owner-initiated TaskPromote)
+  reimplements the documented behavior of @ladbabynpm/picc-tasks v0.2.0 (MIT,
+  Copyright (c) 2026 Ladbaby) as prior art: the same tool names, the same
+  storage model (session JSONL snapshot entries plus a disk mirror at
+  ~/.pi/tasks/{taskListId}/tasks.json), and the same result text. No code is
+  copied; this is a clean AGPL-3.0-only reimplementation to the same behavior
+  spec, so no MIT license text is vendored. picc-tasks is an independent
+  project by its author, used as reference; it is not affiliated with, nor
+  does it endorse, pi-agentic-driver.

package/README.md

@@ -43,6 +43,7 @@ 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 |
 | `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 |
@@ -53,6 +54,8 @@ proofs for agentic workflows.
 | `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 |
+| 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
@@ -93,14 +96,169 @@ only, not a runtime dependency).
 
 </details>
 
+<details>
+<summary><strong>tasks, from session plan to durable work</strong> <em>(shipped)</em></summary>
+
+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.
+- **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.
+
+</details>
+
+**Available now:**
+
+- **task-ledger integration.** Agents can read and act within board card
+  states while the trusted writer retains authority over admission,
+  completion, reconciliation, and migration. The Tasks skill also bridges
+  session planning to the durable `TASKS.md` board.
+- **role and phase routing.** The router separates planning, implementation,
+  review, and escalation phases. It reports endpoint warm state when
+  configured. Warm-session preference remains future work; route affinity
+  never overrides authority.
+
+**Planned in this theme:**
+
+- **prompted planning lifecycle.** Turn natural-language goals into complete
+  proposals with parent and scope choices at native boundaries. No retry
+  loops or model-supplied identifiers.
+- **native assignment selection.** Choose planned assignments through a
+  native UI over derived candidates, never through model-supplied targets.
+- **inventory refresh.** Regenerate the Git-aware codebase inventory with
+  verification receipts so prior-art matching stays honest.
+- **project status and state review.** Add read-only views of workspace Git
+  state, formal records, and task-state health.
+
+<details>
+<summary><strong>router, capacity/policy routing with a binding dispatch gate</strong> <em>(released, 0.9.2)</em></summary>
+
+Board Pulse selects a route seat through the capacity/policy router. The
+router reads a closed configuration file and a local-first SQLite file for
+operational state (reservations, observations, route-decision audit).
+
+Two router features call **Janus** — a separate local service, bundled under
+`janus/`, that is the only component allowed to talk to the TypeSafe Jev
+models:
+
+- **Semantic ranking** (optional): Janus ranks up to eight eligible seats;
+  on any Janus failure the router falls back to preference order.
+- **The binding dispatch gate**: before a task is claimed, Janus judges
+  whether the task fits the selected seat. No verdict, no dispatch — the
+  gate fails closed when Janus is unreachable.
+
+Janus binds loopback only (`127.0.0.1:8787`), reads its API key from the
+macOS Keychain at runtime, redacts state before every external call, and
+coalesces identical requests. See `janus/README.md` for the endpoint
+contract, Keychain provisioning, and configuration.
+
+- **Repository defaults** ship at `.agentic-driver/router.defaults.json`. The
+template contains no accounts and one disabled placeholder seat, so it loads
+out of the box and schedules nothing until you enable a real seat.
+- **User profile (precedence over defaults):**
+`~/.config/agentic-driver/router/profile.json`, or the path in the
+`AGENTIC_DRIVER_ROUTER_PROFILE` environment variable. A profile section
+replaces the matching defaults section wholesale; the merged config must
+validate or the router refuses to produce decisions (fails closed).
+- **Operational state:** `~/.local/share/agentic-driver/router/state.db`, or
+`AGENTIC_DRIVER_ROUTER_DB`. This store is operational state only. The
+authenticated claims file and the board writer remain the only dispatch
+authority; the system repairs SQLite from them, never the reverse.
+- **Runtime requirement:** the operational store uses the built-in
+`node:sqlite` module. You need Node.js 22.5 or newer.
+
+<details>
+<summary><strong>Tunable configuration values</strong> <em>(all keys required, defaults are conservative starting values)</em></summary>
+
+Every numeric policy in the router is a configuration key — never a
+constant in code. All keys are **required**. The repository defaults below
+are conservative starting values. Your profile overrides them. A missing key
+is a configuration validation failure: the router fails closed rather than
+guess. Changing a value participates in the configuration digest, so cached
+routing decisions computed under the old values no longer apply.
+
+| Section | Key | Default | What it controls |
+|---|---|---|---|
+| `eligibility.reserve` | `floorPercent` | 40 | Share of every quota window kept in reserve (per account, per window). Headroom for an unexpected burst and your next interactive session, without idling the account. |
+| `eligibility.reserve` | `scope` | `account-window` | How widely the reserve floor applies (per account per window at launch). |
+| `eligibility.reserve` | `coldStartFraction` | 0.25 | Consumption assumed for a seat with too little history: deliberately generous, so a mis-estimate fails eligibility instead of draining the account. |
+| `eligibility.reserve` | `estimateSamples` | 20 | How many recent dispatches the consumption estimate averages: enough to smooth outliers, quick enough to track a model change. |
+| `eligibility.reserve` | `estimateMinSamples` | 5 | Below this many observations, the estimator treats the average as noise and uses the cold-start value instead. |
+| `eligibility.reserve` | `estimateOutlierSigma` | 3 | Outlier cut for the estimate: one unusually slow dispatch cannot inflate the average, real tail latency is kept. |
+| `eligibility.reserve` | `ownerInteractiveOverride` | false | Whether your own interactive dispatches bypass the reserve rule (they do not, at launch). |
+| `ranking` | `janusUrl` | `http://127.0.0.1:8787` | The local Janus evaluation service endpoint used for semantic ranking. |
+| `ranking` | `maxCandidates` | 8 | The router ranks at most eight eligible seats per request; preference order trims the list first. |
+| `ranking` | `fallback` | `preference-order` | What happens when ranking is unavailable: dispatch falls back to your preference order and never blocks. |
+| `gate` | `threshold` | 0.9 | The dispatch gate's confidence threshold. A task is only dispatched when the evaluation clears it. Lower it only with evidence from your own audit log. |
+| `gate` | `timeoutMs` | 8000 | How long the gate waits for an evaluation. On timeout there is no verdict, and the gate blocks dispatch (fail closed). |
+| `gate` | `requestBudgetTokens` | 30000 | Maximum size of a gate evaluation request. Normal evaluations use under a thousand tokens. |
+| seat record | `maxConcurrency` | 4 | How many workers one seat may run at once. The default suits a typical single machine or hosted seat. Tune it per seat: a cluster takes more, a constrained subscription endpoint may take less. |
+| automation policy | `maxConcurrent` | 4 | How many workers may run at once across all seats. The default is a conservative start. Tune it to the capacity you actually have, and raise it when you add seats or hardware. |
+
+Seats are named for infrastructure, not models: `dgx-spark`,
+`dgx-spark-cluster`, `mac-studio`, `mac-studio-cluster`, `strix-halo`,
+`strix-halo-cluster`, `merge-gateway-worker`. The model is a mutable field on
+the seat, so changing models never renumbers your configuration. Each seat
+also carries `scopeStatements`: plain-language descriptions of what the seat
+is for. The dispatch gate reads them when judging whether a task fits.
+
+</details>
 
-- **prompted planning lifecycle.** Natural-language goals become complete
-  semantic proposals with parent and scope choices at native boundaries. No
-  retry loops, no model-supplied identifiers.
-- **native assignment selection.** Planned assignments are chosen through a
-  native UI over derived candidates, never by model-supplied targets.
-- **inventory refresh.** Git-aware codebase inventory regeneration with
-  verification receipts, so prior-art matching stays honest.
+</details>
+
+<details>
+<summary><strong>Janus, local Jev evaluation service</strong> <em>(shipped)</em></summary>
+
+Janus is the local evaluation service bundled in this repository under
+`janus/`. It is the only component allowed to talk to the TypeSafe Jev
+model. It wraps the official TypeSafe SDK. It exposes one evaluation endpoint
+and health probes on loopback. The router's semantic ranking and binding
+dispatch gate call it. Nothing else in the harness talks to Jev directly.
+
+**Guarantees:**
+
+- **Loopback only.** Janus binds `127.0.0.1:8787` and nothing else. There is
+  deliberately no bind-address option: it is a local tool.
+- **Key stays in the macOS Keychain.** Janus reads the TypeSafe API key at
+  runtime with a guarded `security` lookup. It never passes the key to
+  subprocesses. It never writes the key to logs or transcripts.
+- **Redaction before every external call.** A secrets/PII pass runs over the
+  state before anything leaves the machine. No disable knob exists.
+- **Single-flight.** Janus coalesces identical requests. It caps distinct
+  in-flight evaluations. It rejects overflow with `busy` instead of queuing
+  silently.
+- **Controlled requests.** Janus enforces a 30k-token request budget. It
+  rejects oversized requests instead of truncating them.
+
+**Running it:**
+
+```sh
+cd janus
+```
+
+```sh
+npm install
+```
+
+```sh
+npx tsx janus/server.ts
+```
+
+For a persistent setup, use the launchd template at
+`janus/user.janus.plist`. Provision the TypeSafe Direct key once in the
+Keychain. The command is in `janus/README.md`.
+
+**When Janus is down:** semantic ranking falls back to preference order. The
+binding dispatch gate blocks dispatch and fails closed. Janus never becomes a
+silent dependency: its absence is loud.
+
+See `janus/README.md` for the full endpoint contract, the error taxonomy, and
+configuration.
+
+</details>
 
 ## Multi-agent communication
 
@@ -504,20 +662,21 @@ silently allowed.
 
 *Extensions that keep routine Git low-friction and consequential Git guarded.*
 
-**In development:**
+**Planned:**
 
-- **git workflow safeguards.** Design only; the package contains no Git
-  extension yet. The planned capability covers exact-file staging, native
-  confirmation, post-confirmation drift checks, and protected-operation
-  boundaries.
-- **assignment-aware Git journeys.** Merge and protected-push flows bound to
-  a verified assignment, so consequential Git operations carry their own
-  recorded provenance.
+- **git workflow safeguards.** Not packaged yet. The planned capability covers
+  exact-file staging, native confirmation, post-confirmation drift checks,
+  and protected-operation boundaries.
+- **assignment-aware Git journeys.** Planned merge and protected-push flows
+  bound to a verified assignment, so consequential Git operations carry their
+  own recorded provenance.
 
 ## Package integrity
 
 *Extensions that keep the installed set honest and the record controlled.*
 
+**Planned:**
+
 - **security and integrity scanning.** Static scanning of MCP configs, agent
   skills, and extension packages for hardcoded secrets, prompt and shell
   injection, data-exfiltration endpoints, untrusted integrations, PII
@@ -575,64 +734,10 @@ extensions you want with the object form in your Pi settings:
 }
 ```
 
-The package includes the `herdr-communication.ts`, `herdr-lifecycle.ts`, and
-`herdr-dispatch.ts` extensions. It also includes `linux-microvm.ts`. Use `pi config` to enable or
-disable individual resources from an installed package. You are not required
-to use every extension.
-
-## Router configuration
-
-Board Pulse selects a route seat through the capacity/policy router. The
-router reads a closed configuration file and a local-first SQLite file for
-operational state (reservations, observations, route-decision audit).
-
-- **Repository defaults** ship at `.agentic-driver/router.defaults.json`. The
-template contains no accounts and one disabled placeholder seat, so it loads
-out of the box and schedules nothing until you enable a real seat.
-- **User profile (precedence over defaults):**
-`~/.config/agentic-driver/router/profile.json`, or the path in the
-`AGENTIC_DRIVER_ROUTER_PROFILE` environment variable. A profile section
-replaces the matching defaults section wholesale; the merged config must
-validate or the router refuses to produce decisions (fails closed).
-- **Operational state:** `~/.local/share/agentic-driver/router/state.db`, or
-`AGENTIC_DRIVER_ROUTER_DB`. This store is operational state only. The
-authenticated claims file and the board writer remain the only dispatch
-authority, and SQLite is repaired from them, never the reverse.
-- **Runtime requirement:** the operational store uses the built-in
-`node:sqlite` module. Node.js 22.5 or newer is required.
-
-### Tunable configuration values
-
-Every numeric policy in the router is a configuration key — never a
-constant in code. All keys are **required**. The repository defaults below
-are conservative starting values. Your profile overrides them. A missing key
-is a configuration validation failure: the router fails closed rather than
-guess. Changing a value participates in the configuration digest, so cached
-routing decisions computed under the old values no longer apply.
-
-| Section | Key | Default | What it controls |
-|---|---|---|---|
-| `eligibility.reserve` | `floorPercent` | 40 | Share of every quota window kept in reserve (per account, per window). Headroom for an unexpected burst and your next interactive session, without idling the account. |
-| `eligibility.reserve` | `scope` | `account-window` | How widely the reserve floor applies (per account per window at launch). |
-| `eligibility.reserve` | `coldStartFraction` | 0.25 | Consumption assumed for a seat with too little history: deliberately generous, so a mis-estimate fails eligibility instead of draining the account. |
-| `eligibility.reserve` | `estimateSamples` | 20 | How many recent dispatches the consumption estimate averages: enough to smooth outliers, quick enough to track a model change. |
-| `eligibility.reserve` | `estimateMinSamples` | 5 | Below this many observations the average is treated as noise and the cold-start value is used instead. |
-| `eligibility.reserve` | `estimateOutlierSigma` | 3 | Outlier cut for the estimate: one unusually slow dispatch cannot inflate the average, real tail latency is kept. |
-| `eligibility.reserve` | `ownerInteractiveOverride` | false | Whether your own interactive dispatches bypass the reserve rule (they do not, at launch). |
-| `ranking` | `janusUrl` | `http://127.0.0.1:8787` | The local janus evaluation service endpoint used for semantic ranking. |
-| `ranking` | `maxCandidates` | 8 | At most eight eligible seats are ranked per request; preference order trims first. |
-| `ranking` | `fallback` | `preference-order` | What happens when ranking is unavailable: dispatch falls back to your preference order and never blocks. |
-| `gate` | `threshold` | 0.9 | The dispatch gate's confidence threshold. A task is only dispatched when the evaluation clears it. Lower it only with evidence from your own audit log. |
-| `gate` | `timeoutMs` | 8000 | How long the gate waits for an evaluation. On timeout there is no verdict and dispatch is blocked (fail closed). |
-| `gate` | `requestBudgetTokens` | 30000 | Maximum size of a gate evaluation request. Normal evaluations use under a thousand tokens. |
-| seat record | `maxConcurrency` | 4 | How many workers one seat may run at once. The default suits a typical single machine or hosted seat. Tune it per seat: a cluster takes more, a constrained subscription endpoint may take less. |
-| automation policy | `maxConcurrent` | 4 | How many workers may run at once across all seats. The default is a conservative start. Tune it to the capacity you actually have, and raise it when you add seats or hardware. |
-
-Seats are named for infrastructure, not models: `dgx-spark-cluster`,
-`mac-studio`, `merge-gateway-worker`. The model is a mutable field on the
-seat, so changing models never renumbers your configuration. Each seat also
-carries `scopeStatements`: plain-language descriptions of what the seat is
-for. The dispatch gate reads them when judging whether a task fits.
+The package includes the Herdr communication, lifecycle, and dispatch
+extensions, the board and Tasks extensions, and `linux-microvm.ts`. Use
+`pi config` to enable or disable individual resources from an installed
+package. You are not required to use every extension.
 
 ## License