@davidorex/pi-project-workflows 0.14.6 → 0.28.0

package/CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.28.0] - 2026-06-03
+- Lockstep changes accumulating since v0.26.0; see member-package changelogs (pi-context, pi-workflows, pi-behavior-monitors, pi-agent-dispatch). The v0.27.0 tag is unpublished, so its bundled member changes remain unreleased here until the next publish.
+
+## [0.26.0] - 2026-05-25
+- Lockstep release to 0.26.0; see member-package changelogs (pi-context, pi-workflows, pi-behavior-monitors, pi-agent-dispatch).
+
+## [0.14.6] - 2026-04-28
+- Lockstep release to 0.14.6; see member-package changelogs (pi-context, pi-workflows, pi-behavior-monitors, pi-agent-dispatch).
+
+## [0.14.4] - 2026-04-07
+- Lockstep release to 0.14.4; see member-package changelogs (pi-context, pi-workflows, pi-behavior-monitors, pi-agent-dispatch).
+
+## [0.14.2] - 2026-04-06
+- Lockstep release to 0.14.2; see member-package changelogs (pi-context, pi-workflows, pi-behavior-monitors, pi-agent-dispatch).
+
+## [0.14.1] - 2026-04-06
+- Lockstep release to 0.14.1; see member-package changelogs (pi-context, pi-workflows, pi-behavior-monitors, pi-agent-dispatch).
+
+## [0.13.0] - 2026-04-06
+- Lockstep release to 0.13.0; see member-package changelogs (pi-context, pi-workflows, pi-behavior-monitors, pi-agent-dispatch).
+
+## [0.12.0] - 2026-04-06
+- Lockstep release to 0.12.0; see member-package changelogs (pi-context, pi-workflows, pi-behavior-monitors, pi-agent-dispatch).
+
+## [0.11.3] - 2026-04-04
+- Lockstep release to 0.11.3; see member-package changelogs (pi-context, pi-workflows, pi-behavior-monitors, pi-agent-dispatch).
+
+## [0.11.0] - 2026-04-04
+- Lockstep release to 0.11.0; see member-package changelogs (pi-context, pi-workflows, pi-behavior-monitors, pi-agent-dispatch).
+
+## [0.10.5] - 2026-04-02
+- Lockstep release to 0.10.5; see member-package changelogs (pi-context, pi-workflows, pi-behavior-monitors, pi-agent-dispatch).
+
+## [0.10.3] - 2026-04-02
+- Lockstep release to 0.10.3; see member-package changelogs (pi-context, pi-workflows, pi-behavior-monitors, pi-agent-dispatch).
+
+## [0.10.2] - 2026-04-02
+- Lockstep release to 0.10.2; see member-package changelogs (pi-context, pi-workflows, pi-behavior-monitors, pi-agent-dispatch).
+
+## [0.10.1] - 2026-04-02
+- Lockstep release to 0.10.1; see member-package changelogs (pi-context, pi-workflows, pi-behavior-monitors, pi-agent-dispatch).
+
+## [0.10.0] - 2026-04-02
+- Lockstep release to 0.10.0; see member-package changelogs (pi-context, pi-workflows, pi-behavior-monitors, pi-agent-dispatch).
+
+## [0.9.2] - 2026-03-31
+- Lockstep release to 0.9.2; see member-package changelogs (pi-context, pi-workflows, pi-behavior-monitors, pi-agent-dispatch).
+
+## [0.9.1] - 2026-03-31
+- Lockstep release to 0.9.1; see member-package changelogs (pi-context, pi-workflows, pi-behavior-monitors, pi-agent-dispatch).
+
+## [0.9.0] - 2026-03-29
+- Lockstep release to 0.9.0; see member-package changelogs (pi-context, pi-workflows, pi-behavior-monitors, pi-agent-dispatch).
+
+## [0.6.1] - 2026-03-28
+- Lockstep release to 0.6.1; see member-package changelogs (pi-context, pi-workflows, pi-behavior-monitors, pi-agent-dispatch).
+
+## [0.5.0] - 2026-03-28
+- Lockstep release to 0.5.0; see member-package changelogs (pi-context, pi-workflows, pi-behavior-monitors, pi-agent-dispatch).
+
+## [0.4.1] - 2026-03-27
+- Lockstep release to 0.4.1; see member-package changelogs (pi-context, pi-workflows, pi-behavior-monitors, pi-agent-dispatch).
+
+## [0.4.0] - 2026-03-27
+- Lockstep release to 0.4.0; see member-package changelogs (pi-context, pi-workflows, pi-behavior-monitors, pi-agent-dispatch).
+
+## [0.3.4] - 2026-03-27
+- Lockstep release to 0.3.4; see member-package changelogs (pi-context, pi-workflows, pi-behavior-monitors, pi-agent-dispatch).
+
+## [0.3.2] - 2026-03-26
+- Lockstep release to 0.3.2; see member-package changelogs (pi-context, pi-workflows, pi-behavior-monitors, pi-agent-dispatch).
+
+## [0.3.1] - 2026-03-25
+- Lockstep release to 0.3.1; see member-package changelogs (pi-context, pi-workflows, pi-behavior-monitors, pi-agent-dispatch).
+
+## [0.3.0] - 2026-03-19
+- Lockstep release to 0.3.0; see member-package changelogs (pi-context, pi-workflows, pi-behavior-monitors, pi-agent-dispatch).
+
+## [0.2.0] - 2026-03-17
+- Initial publish of the meta re-export package bundling the member Pi extensions; lockstep release to 0.2.0. See member-package changelogs (pi-context, pi-workflows, pi-behavior-monitors, pi-agent-dispatch).

package/README.md

@@ -1,6 +1,6 @@
 # @davidorex/pi-project-workflows
 
-Convenience meta-package that re-exports all three [Pi](https://github.com/badlogic/pi-mono) extensions — structured project state, workflow orchestration, and behavior monitoring — in a single install.
+Convenience meta-package that re-exports FOUR [Pi](https://github.com/badlogic/pi-mono) extensions plus the shared pi-jit-agents library. The four: pi-context (substrate), pi-workflows (orchestration), pi-behavior-monitors (classification/steering), pi-agent-dispatch (in-pi agent-as-tool dispatch + capability composition + the bounded north-star work-order loop). pi-jit-agents is a library consumed directly by pi-workflows and pi-agent-dispatch (no separate extension registration).
 
 ## Install
 
@@ -8,17 +8,19 @@ Convenience meta-package that re-exports all three [Pi](https://github.com/badlo
 pi install npm:@davidorex/pi-project-workflows
 ```
 
-This installs all three extensions:
-- **[@davidorex/pi-project](https://github.com/davidorex/pi-project-workflows/tree/main/packages/pi-project)** — schema-driven project state (typed blocks, validation, derived state)
+This installs the five constituent packages (four Pi extensions plus the shared library):
+- **[@davidorex/pi-context](https://github.com/davidorex/pi-project-workflows/tree/main/packages/pi-context)** — schema-driven project state (typed blocks, validation, derived state)
+- **[@davidorex/pi-jit-agents](https://github.com/davidorex/pi-project-workflows/tree/main/packages/pi-jit-agents)** — agent spec compilation and in-process dispatch runtime (library, not a Pi extension)
 - **[@davidorex/pi-workflows](https://github.com/davidorex/pi-project-workflows/tree/main/packages/pi-workflows)** — workflow orchestration (YAML specs, DAG execution, checkpoint/resume)
 - **[@davidorex/pi-behavior-monitors](https://github.com/davidorex/pi-project-workflows/tree/main/packages/pi-behavior-monitors)** — behavior monitors (autonomous watchdogs, pattern classification, steering corrections)
+- **[@davidorex/pi-agent-dispatch](https://github.com/davidorex/pi-project-workflows/tree/main/packages/pi-agent-dispatch)** — in-pi agent-as-tool dispatch + capability composition + bounded work-order loop (call-agent / author-agent-spec / run-real-checks / commit-attested / author-tool-grant / run-work-order-loop; dynamic composite-loader)
 
 ## Getting Started
 
 ```
-/project init     # scaffolds .project/ with schemas and starter blocks
+/context init <substrate-dir>   # create the empty substrate skeleton (pointer + dirs only; no config/schemas/blocks)
 /workflow init    # scaffolds .workflows/ for run state
-/project status   # see derived project state
+/context status   # see derived project state
 /workflow list    # discover and run workflows
 /monitors         # list all monitors, scope, and state
 ```
@@ -26,6 +28,8 @@ This installs all three extensions:
 ## Documentation
 
 See the package READMEs for full API docs, source maps, and LLM guidance:
-- [pi-project README](https://github.com/davidorex/pi-project-workflows/tree/main/packages/pi-project)
+- [pi-context README](https://github.com/davidorex/pi-project-workflows/tree/main/packages/pi-context)
+- [pi-jit-agents README](https://github.com/davidorex/pi-project-workflows/tree/main/packages/pi-jit-agents)
 - [pi-workflows README](https://github.com/davidorex/pi-project-workflows/tree/main/packages/pi-workflows)
 - [pi-behavior-monitors README](https://github.com/davidorex/pi-project-workflows/tree/main/packages/pi-behavior-monitors)
+- [pi-agent-dispatch README](https://github.com/davidorex/pi-project-workflows/tree/main/packages/pi-agent-dispatch)

package/dispatch-extension.ts

@@ -0,0 +1 @@
+export { default } from "@davidorex/pi-agent-dispatch";

package/package.json

@@ -1,6 +1,9 @@
 {
 	"name": "@davidorex/pi-project-workflows",
-	"version": "0.14.6",
+	"version": "0.28.0",
+	"publishConfig": {
+		"access": "public"
+	},
 	"description": "Pi extensions for structured project state, workflow orchestration, and behavior monitoring — single install for all three",
 	"license": "MIT",
 	"author": "David Ryan",
@@ -22,15 +25,17 @@
 		"extensions": [
 			"./project-extension.ts",
 			"./workflows-extension.ts",
-			"./monitors-extension.ts"
+			"./monitors-extension.ts",
+			"./dispatch-extension.ts"
 		],
 		"skills": [
 			"./skills"
 		]
 	},
 	"dependencies": {
-		"@davidorex/pi-project": "^0.14.6",
-		"@davidorex/pi-workflows": "^0.14.6",
-		"@davidorex/pi-behavior-monitors": "^0.14.6"
+		"@davidorex/pi-context": "^0.28.0",
+		"@davidorex/pi-workflows": "^0.28.0",
+		"@davidorex/pi-behavior-monitors": "^0.28.0",
+		"@davidorex/pi-agent-dispatch": "^0.28.0"
 	}
 }

package/project-extension.ts

@@ -1 +1 @@
-export { default } from "@davidorex/pi-project";
+export { default } from "@davidorex/pi-context";

package/skills/pi-agent-dispatch/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: pi-agent-dispatch
+description: >
+  Sibling Pi extension that registers in-pi agent-as-tool dispatch, capability
+  composition, real-check execution, attested commits, and the bounded north-star
+  work-order loop. Use when authoring agent specs, granting tool capabilities,
+  running deterministic checks, committing with writer attestation, loading
+  config-declared composite operations, or driving end-to-end work-orders through
+  their bounded retry loop.
+---
+
+<tools_reference>
+<tool name="author-agent-spec">
+Write a new .agent.yaml spec to the agents tier. Requires user authorization via interactive confirmation at the pi-dispatch auth-gate; on confirm, the verified terminal-operator identity is stamped as writer. The written file is AJV-validated against AgentSpec before persisting.
+
+*Author a privileged JIT-agent spec — declares input, prompts, tools grant, output schema, contextBlocks.*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | yes | Agent name (becomes <name>.agent.yaml filename + AgentSpec.name). |
+| `spec` | unknown | yes | AgentSpec object body (will be serialized to YAML). Must conform to AgentSpec shape. |
+| `writer` | object | yes | DispatchContext.writer payload; see pi-context/src/dispatch-context.ts for the discriminated union. |
+</tool>
+
+<tool name="call-agent">
+Dispatch a privileged JIT-agent as a typed tool call. Loads the named .agent.yaml, compiles with input, composes the tool grant (intersection of caller's parentGrant and the agent's requestedGrant), and executes via pi-jit-agents executeAgent (clamp enforces child ⊆ parent at dispatch boundary).
+
+*Dispatch a typed sub-agent with scoped capability grant.*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `spec_name` | string | yes | Name of the agent spec to load (resolves to <name>.agent.yaml in the agents tier). |
+| `input` | unknown | yes | Typed input passed to the agent's compileAgent context. |
+| `parent_grant` | array | no | The caller's own tool grant. Default-empty. |
+| `requested_grant` | array | no | The grant requested for the dispatched sub-agent. Will be clamped to the intersection with parent_grant. |
+| `max_tokens` | number | no | Max tokens for the LLM call. Defaults to 1024. |
+</tool>
+
+<tool name="run-real-checks">
+Run the deterministic real-checks declared on a work-order (build/check/test exit + runtime-demo + adversarial-probe). Returns a structured RealCheckResult. NEVER LLM self-report; verdict is the actual exit code.
+
+*Run a work-order's declared real-checks for verdict gating.*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `work_order_id` | string | yes | ID of the work-order whose real_check_criteria to run (e.g. 'WO-NNN'). |
+| `max_check_time_ms` | number | no | Max total time per check in milliseconds. Defaults to 600000 (10 minutes). |
+</tool>
+
+<tool name="commit-attested">
+Stage declared files + invoke git commit with DispatchContext writer.kind=agent attestation footer. Husky pre-commit runs as backup gate; never bypass (--no-verify forbidden per feedback_no_destructive_git_ops). The primary gate is run-real-checks called BEFORE this tool.
+
+*Commit agent-authored work-product files with attestation footer.*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `files` | array | yes | Files to stage + commit. Empty array refused. |
+| `message` | string | yes | Commit message body (the attestation footer is appended automatically). |
+| `agent_id` | string | yes | Agent id for writer.kind=agent attestation (e.g. 'spec-implementer-001'). |
+| `work_order_id` | string | no | Optional work-order id for the attestation footer. |
+</tool>
+
+<tool name="author-tool-grant">
+Add or remove an entry in config.tool_operations[] or config.tool_operations_forbidden[]. Requires user authorization via interactive confirmation at the pi-dispatch auth-gate; on confirm, the verified terminal-operator identity is stamped as writer. Refuses any attempt to register a framework-forbidden wholesale token.
+
+*Author a config tool-grant entry (operation registration or project-forbidden token).*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `target` | unknown | yes | Which config registry to mutate. |
+| `operation` | unknown | yes | amendConfigEntry operation. |
+| `key` | string | yes | For tool_operations: the canonical_id (must match entry.canonical_id). For tool_operations_forbidden: the token string. |
+| `entry` | unknown | no | ToolOperationDecl object — required for target=tool_operations + operation=add. |
+| `writer` | object | yes | DispatchContext.writer payload; see pi-context/src/dispatch-context.ts for the discriminated union. |
+</tool>
+
+<tool name="run-work-order-loop">
+Execute the bounded work-order loop: dispatch target_agent (via direct pi-jit-agents library) → run-real-checks (deterministic verdict — the actual exit code, never an LLM self-report) → on-pass commit-attested → on-fail human-OK retry at the iteration boundary. Bounded iterations (default 3); human-OK gate governs retry.
+
+*Execute the end-to-end work-order loop for a declared spec.*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `work_order_id` | string | yes | ID of the work-order to execute (loads from .project/work-orders.json schema). |
+| `max_iterations` | number | no | Max iteration count before fail-final. Default 3. |
+| `agent_grant` | array | no | Tool grant for the dispatched privileged agent (capability composition). Default empty. |
+</tool>
+
+</tools_reference>
+
+<events>
+`tool_call`, `tool_result`
+</events>
+
+<objective>
+pi-agent-dispatch is the harness-confined orchestrator's in-pi surface. It registers Pi tools the orchestrator agent invokes to dispatch sub-agents, author specs and tool grants, run deterministic checks the executive cannot fake, commit with writer attestation, and drive bounded work-order loops. It is the sibling-consumer registration site; pi-jit-agents stays a library consumed directly by this package and by pi-workflows.
+</objective>
+
+<dispatch_tools>
+| Tool | Purpose |
+|------|---------|
+| `call-agent` | Dispatch a declared agent spec with a composed tool grant (parent ∩ requested ∩ spec.tools). |
+| `author-agent-spec` | Write an `.agent.yaml` spec to the substrate. Human-authorized via auth-gate confirm at the pi-dispatch layer; the verified terminal-operator identity is stamped as writer on confirm. |
+| `run-work-order-loop` | Execute the bounded work-order loop: dispatch → run-real-checks → on-pass commit-attested → on-fail human-OK retry. |
+</dispatch_tools>
+
+<real_check_tools>
+| Tool | Purpose |
+|------|---------|
+| `run-real-checks` | Execute declared deterministic checks (build/check/test exit codes, schema validations, git diff probes, runtime event probes). Verdict is the actual exit code, never an LLM self-report. |
+| `commit-attested` | Stage + commit with writer-identity footer. Refuses on missing agent_id, files, or message. |
+</real_check_tools>
+
+<capability_authoring>
+Tool grants are config-declared (bounded composites) and authored only via the `author-tool-grant` Pi tool, which is human-authorized at the pi-dispatch auth-gate (interactive confirmation; on confirm the verified terminal-operator identity is stamped as writer). Default grant is empty; widening goes through the auth-gate. The FORBIDDEN_WHOLESALE_OPERATIONS set blocks shipping wholesale L1 surfaces (bash, write, edit) as a single composite token; the L1 ∪ L5 forbidden union check refuses tokens that already appear on the L1 wholesale-forbidden list.
+</capability_authoring>
+
+<composite_loader>
+On extension load, `composite-loader` reads the active substrate's `config.tool_operations[]` and dynamically registers each declared bounded composite as a Pi tool. Config-absent (no pointer or unbootstrapped substrate) degrades gracefully: extension still registers the 6 static tools; the absence is observed via the `extension_load_warning` TraceEntry and (when available) surfaced through `pi.ui.notify`. The substrate is the single source of truth — no parallel ungated path widens capability outside the loader.
+</composite_loader>
+
+<canonical_intention>
+Anchors:
+- Harness-confined orchestrator (positive clause: substrate-write + call-agent + author-agent-spec + run-real-checks + commit-attested + author-tool-grant + run-work-order-loop + declared composites; negative clause: NO bash/edit/write).
+- Sibling-consumer scope; pi-jit-agents stays a library.
+- Human-authorized authoring at the pi-dispatch auth-gate; default empty; terminal verdict = real deterministic checks.
+- Capability composition + end-to-end work-order loop + bounded-composite vocabulary + launch-chain integration.
+- Orchestrator uses jit-agents directly; capability composition lives in the dispatch layer.
+</canonical_intention>
+
+<success_criteria>
+- 6 static tools register on every load: call-agent, author-agent-spec, author-tool-grant, run-real-checks, commit-attested, run-work-order-loop.
+- Composite tools register from config.tool_operations[] when present; load proceeds with warning when absent.
+- Every write-bearing tool routes through the pi-dispatch auth-gate; the verified terminal-operator identity is stamped as writer on confirm.
+- Work-order loop honors max_iterations + human-OK retry gate + on-pass attested commit.
+</success_criteria>
+
+*Generated from source by `scripts/generate-skills.js` — do not edit by hand.*

package/skills/pi-behavior-monitors/SKILL.md

@@ -76,11 +76,11 @@ Subcommands: `on`, `off`, `help`, `commit-hygiene`, `fragility`, `hedge`, `unaut
 </commands_reference>
 
 <events>
-`session_start`, `agent_end`, `turn_start`, `message_end`, `turn_end`, `tool_call`
+`session_start`, `agent_end`, `turn_start`, `tool_call`
 </events>
 
 <bundled_resources>
-5 agents, 3 schemas, 21 examples bundled.
+5 agents, 5 schemas, 21 examples bundled.
 See references/bundled-resources.md for full inventory.
 </bundled_resources>
 
@@ -95,8 +95,8 @@ See references/bundled-resources.md for full inventory.
 | `tool_results` | `{tool_results}` / `{{ tool_results }}` | Tool results with tool name and error status | Last 5, truncated 2000 chars |
 | `tool_calls` | `{tool_calls}` / `{{ tool_calls }}` | Tool calls and results interleaved | Last 20, truncated 2000 chars |
 | `custom_messages` | `{custom_messages}` / `{{ custom_messages }}` | Custom extension messages since last user message | — |
-| `project_vision` | `{project_vision}` / `{{ project_vision }}` | .project/project.json vision, core_value, name | — |
-| `project_conventions` | `{project_conventions}` / `{{ project_conventions }}` | .project/conformance-reference.json principle names | — |
+| `project_vision` | `{project_vision}` / `{{ project_vision }}` | <substrate-dir>/project.json vision, core_value, name | — |
+| `project_conventions` | `{project_conventions}` / `{{ project_conventions }}` | <substrate-dir>/conformance-reference.json principle names | — |
 | `git_status` | `{git_status}` / `{{ git_status }}` | Output of git status --porcelain | 5s timeout |
 | `conversation_history` | `{conversation_history}` / `{{ conversation_history }}` | Prior turn summaries (user request + actions + assistant response) | 1-3 turns adaptive, 2000 char max |
 
@@ -209,7 +209,7 @@ A `.monitor.json` file conforms to `schemas/monitor.schema.json`:
     "on_flag": {
       "steer": "Fix the issue.",
       "write": {
-        "path": ".project/issues.json",
+        "path": "<substrate-dir>/issues.json",
         "merge": "append",
         "array_field": "issues",
         "template": {
@@ -475,7 +475,7 @@ acknowledgment support:
 **fragility** (`message_end`, `when: has_tool_results`)
 Watches for unaddressed fragilities after tool use — errors, warnings, or broken state the
 agent noticed but chose not to fix. Steers with "Fix the issue you left behind." Writes
-findings to `.project/issues.json` under `category: "fragility"`. Excludes: none. Ceiling: 5.
+findings to `<substrate-dir>/issues.json` under `category: "fragility"`. Excludes: none. Ceiling: 5.
 12 bundled patterns across categories: avoidance (dismiss-preexisting, not-my-change,
 blame-environment, workaround-over-root-cause, elaborate-workaround-for-fixable),
 error-handling (empty-catch, happy-path-only, early-return-on-unexpected,
@@ -493,7 +493,7 @@ deflection (ask-permission, qualify-yesno, counter-question).
 
 **work-quality** (`command`, `when: always`)
 On-demand work quality analysis invoked via `/work-quality`. Analyzes user request, tool
-calls, and assistant response for quality issues. Writes findings to `.project/issues.json`
+calls, and assistant response for quality issues. Writes findings to `<substrate-dir>/issues.json`
 under `category: "work-quality"`. Ceiling: 3.
 11 bundled patterns across categories: methodology (trial-and-error, symptom-fix,
 double-edit, edit-without-read, insanity-retry, no-plan), verification (no-verify),

package/skills/pi-behavior-monitors/references/bundled-resources.md

@@ -8,8 +8,10 @@
 - `agents/unauthorized-action-classifier.agent.yaml`
 - `agents/work-quality-classifier.agent.yaml`
 
-## schemas/ (3 files)
+## schemas/ (5 files)
 
+- `schemas/monitor-instruction-list.schema.json`
+- `schemas/monitor-pattern-list.schema.json`
 - `schemas/monitor-pattern.schema.json`
 - `schemas/monitor.schema.json`
 - `schemas/verdict.schema.json`

package/skills/pi-project-workflows/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pi-project-workflows
 description: >
-  Meta-package re-exporting pi-project (schema-driven project state),
+  Meta-package re-exporting pi-context (schema-driven project state),
   pi-workflows (workflow orchestration), and pi-behavior-monitors (autonomous
   behavior monitoring). Install once to get all three extensions.
 ---
@@ -15,17 +15,17 @@ pi install npm:@davidorex/pi-project-workflows
 </objective>
 
 <included_extensions>
-<extension name="@davidorex/pi-project">
+<extension name="@davidorex/pi-context">
 Schema-driven project state management for Pi
 
-**Tools:** `append-block-item`, `update-block-item`, `read-block`, `write-block`, `project-status`, `project-validate`, `project-init`, `complete-task`
-**Commands:** `/project`
+**Tools:** `append-block-item`, `update-block-item`, `append-relation`, `promote-item`, `append-block-nested-item`, `update-block-nested-item`, `remove-block-item`, `remove-block-nested-item`, `read-block-dir`, `read-block`, `write-block`, `context-status`, `context-validate`, `read-config`, `list-tools`, `read-samples-catalog`, `context-current-state`, `context-bootstrap-state`, `rename-canonical-id`, `amend-config`, `read-schema`, `write-schema`, `write-schema-migration`, `context-init`, `context-accept-all`, `context-switch`, `context-list`, `context-archive`, `filter-block-items`, `resolve-item-by-id`, `read-block-item`, `read-block-page`, `join-blocks`, `resolve-items-by-id`, `complete-task`, `context-validate-relations`, `context-edges-for-lens`, `context-walk-descendants`, `walk-ancestors`, `find-references`, `gather-execution-context`, `context-roadmap-load`, `context-roadmap-render`, `context-roadmap-validate`, `context-roadmap-list`
+**Commands:** `/context`
 </extension>
 
 <extension name="@davidorex/pi-workflows">
 Workflow orchestration extension for Pi
 
-**Tools:** `workflow`, `workflow-list`, `workflow-agents`, `workflow-validate`, `workflow-status`, `workflow-init`
+**Tools:** `workflow-execute`, `workflow-resume`, `workflow-list`, `workflow-agents`, `workflow-validate`, `workflow-status`, `workflow-init`, `render-item-by-id`, `enforce-budget`
 **Commands:** `/workflow`
 **Shortcuts:** ctrl+h (Pause running workflow), ctrl+j (Resume paused workflow)
 </extension>
@@ -37,6 +37,12 @@ Behavior monitors for pi that watch agent activity and steer corrections
 **Commands:** `/work-quality`, `/monitors`
 </extension>
 
+<extension name="@davidorex/pi-agent-dispatch">
+In-pi agent-as-tool dispatch + capability composition extension
+
+**Tools:** `author-agent-spec`, `call-agent`, `run-real-checks`, `commit-attested`, `author-tool-grant`, `run-work-order-loop`
+</extension>
+
 </included_extensions>
 
 *Generated from source by `scripts/generate-skills.js` — do not edit by hand.*

package/skills/pi-workflows/SKILL.md

@@ -8,10 +8,10 @@ description: >
 ---
 
 <tools_reference>
-<tool name="workflow">
-Run a named workflow with typed input. Discovers workflows from .workflows/ and ~/.pi/agent/workflows/.
+<tool name="workflow-execute">
+Execute a named workflow with typed input. Discovers workflows from .workflows/ and ~/.pi/agent/workflows/. Auto-resumes the most recent compatible incomplete run unless fresh='true'. Use workflow-resume for explicit-only resume by runId.
 
-*Run a multi-step workflow with typed data flow between agents*
+*Execute a multi-step workflow with typed data flow (auto-resumes compatible incomplete runs)*
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
@@ -20,6 +20,18 @@ Run a named workflow with typed input. Discovers workflows from .workflows/ and
 | `fresh` | string | no | Set to 'true' to start a fresh run, ignoring any incomplete prior runs |
 </tool>
 
+<tool name="workflow-resume">
+Explicitly resume an incomplete workflow run by name + runId. Rejects when no incomplete run exists for the workflow OR when runId does not match the most recent incomplete run. Use workflow-execute for default auto-resume; this surface is for explicit-only scenarios where the caller wants to fail loudly if the run is gone or has been superseded.
+
+*Explicitly resume an incomplete workflow run by name + runId (rejects on no-match)*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `workflow` | string | yes | Workflow name |
+| `runId` | string | yes | Incomplete run ID — required, no auto-detect |
+| `input` | unknown | no | Optional input override; defaults to the original run's input |
+</tool>
+
 <tool name="workflow-list">
 List available workflows with names, descriptions, and sources.
 
@@ -61,6 +73,29 @@ Initialize .workflows/ directory for workflow run state.
 
 </tool>
 
+<tool name="render-item-by-id">
+Render a project block item by ID through its registered per-item macro. Resolves the item via the cross-block resolver, looks up the macro via the renderer registry, and renders with the supplied depth and depth-aware cross-reference recursion. Returns `[not-found: <id>]` on resolver miss and `[unrendered: <kind>/<id>]` on registry miss — same fallback markers `render_recursive` emits inside agent prompts.
+
+*Render a project block item as prompt text via its per-item macro (with depth-controlled cross-ref recursion)*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | yes | Kind-prefixed ID, e.g., DEC-NNNN / FEAT-NNN |
+| `depth` | number | no | 0 = bare-ID refs (default), 1 = inline direct cross-references, 2+ = recurse further |
+</tool>
+
+<tool name="enforce-budget">
+Check rendered text against an `x-prompt-budget` annotation on a schema field. Returns `{ output, warning }` — `output` is the original text passed through when under budget, or tail-truncated text with `[…truncated to budget]` marker when over; `warning` is null when no truncation occurred or a structured BudgetWarning record otherwise. Annotation absence is pass-through (no error). Mirrors the behaviour of the `enforceBudget` Nunjucks global registered by compileAgent.
+
+*Validate rendered text against a schema field's prompt budget — returns truncated output and warning*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `rendered` | string | yes | Rendered text to check against the field's prompt budget |
+| `blockName` | string | yes | Block schema name (without .schema.json suffix), e.g. 'decisions' or 'features' |
+| `fieldPath` | string | yes | JSON-pointer-style path to the field, e.g. '/properties/decisions/items/properties/context' |
+</tool>
+
 </tools_reference>
 
 <commands_reference>
@@ -78,7 +113,7 @@ Subcommands: `init`, `list`, `run`, `resume`, `validate`, `status`, `help`
 </keyboard_shortcuts>
 
 <bundled_resources>
-26 agents, 15 schemas, 15 workflows, 33 templates bundled.
+26 agents, 15 schemas, 15 workflows bundled.
 See references/bundled-resources.md for full inventory.
 </bundled_resources>
 
@@ -127,7 +162,7 @@ See references/bundled-resources.md for full inventory.
 </agent_input>
 
 <agent_input name="handoff-writer">
-- `project_state` [required] — Current project state (from projectState() or /project status — includes phases, blocks, gaps, decisions, recent commits)
+- `project_state` [required] — Current project state (from contextState() or /context status — includes phases, blocks, gaps, decisions, recent commits)
 - `path` string [required] — Root path of the project
 </agent_input>
 
@@ -212,7 +247,7 @@ See references/bundled-resources.md for full inventory.
 | `filter-names` | warning | Expression filters are recognized |
 | `steptype-metadata` | error | retry/input/output declarations match step type capabilities |
 | `inputschema-required` | error | Agent required input keys are provided by step |
-| `contextblocks-existence` | warning | Declared context blocks exist in .project/ |
+| `contextblocks-existence` | warning | Declared context blocks exist in the substrate dir |
 | `template-alignment` | error | Template variables match step inputs and source schemas |
 
 </validation_vocabulary>
@@ -239,7 +274,9 @@ Workflows are discovered from three locations (first match wins):
 | loop | `loop: { maxAttempts, steps }` | Repeat sub-steps until gate breaks or max reached |
 | parallel | `parallel: { a: ..., b: ... }` | Run named sub-steps concurrently |
 | pause | `pause: true` or `pause: "message"` | Pause execution, resumable later |
-| forEach | `forEach: "${{ expr }}"` | Iterate over an array, executing the step per element |
+| block | `block: { op: read\|write\|append\|update\|remove\|… }` | Validated in-process substrate block I/O via the block API — no LLM, no subprocess |
+
+`forEach: "${{ expr }}"` (iterate the step per array element) and `as:` are step MODIFIERS, not step types — they combine with any type above.
 </step_types>
 
 <expression_syntax>
@@ -275,7 +312,7 @@ Incomplete runs (failed or paused) are detected on next invocation. If the workf
 <output_validation>
 Steps with `output.schema` validate the agent's JSON output against a JSON Schema file. Validation failure marks the step as failed.
 
-Use `block:<name>` to reference project block schemas portably: `output.schema: block:project` resolves to `.project/schemas/project.schema.json` from cwd. Works across monorepo, npm install, and user-customized schemas. Combined with `retry: { maxAttempts: 2 }`, the agent gets the schema validation error injected into its retry prompt and can self-correct.
+Use `block:<name>` to reference project block schemas portably: `output.schema: block:project` resolves to `<substrate-dir>/schemas/project.schema.json` from cwd. Works across monorepo, npm install, and user-customized schemas. Combined with `retry: { maxAttempts: 2 }`, the agent gets the schema validation error injected into its retry prompt and can self-correct.
 </output_validation>
 
 <retry>
@@ -290,7 +327,7 @@ After execution, the workflow result is injected into the main LLM conversation.
 </completion_messages>
 
 <artifacts>
-Workflows can write post-completion files via the `artifacts` field. Paths may contain `${{ }}` expressions. Artifacts targeting `.project/*.json` are routed through `writeBlock()` for schema validation.
+Workflows can write post-completion files via the `artifacts` field. Paths may contain `${{ }}` expressions. Artifacts targeting `<substrate-dir>/*.json` are routed through `writeBlock()` for schema validation.
 
 Block artifact write failures are fatal — if the data doesn't conform to the block's schema, the workflow fails. Non-block artifact failures remain non-fatal (warning). On resume, all steps are preserved; only artifact processing re-runs, so fixing the schema issue or agent output and resuming avoids re-running expensive LLM steps.
 </artifacts>

package/skills/pi-workflows/references/bundled-resources.md

@@ -64,39 +64,3 @@
 - `workflows/resumable-analysis.workflow.yaml`
 - `workflows/self-implement.workflow.yaml`
 - `workflows/typed-analysis.workflow.yaml`
-
-## templates/ (33 files)
-
-- `templates/analyzers/base-analyzer.md`
-- `templates/analyzers/patterns-task.md`
-- `templates/analyzers/patterns.md`
-- `templates/analyzers/quality-task.md`
-- `templates/analyzers/quality.md`
-- `templates/analyzers/structure-task.md`
-- `templates/analyzers/structure.md`
-- `templates/architecture-designer/task.md`
-- `templates/architecture-inferrer/task.md`
-- `templates/audit-finding-verifier/task.md`
-- `templates/audit-fixer/task.md`
-- `templates/audit-results-router/task.md`
-- `templates/decomposer/task.md`
-- `templates/explorer/system.md`
-- `templates/explorer/task.md`
-- `templates/gap-identifier/task.md`
-- `templates/gap-resolution-assessor/task.md`
-- `templates/handoff-writer/task.md`
-- `templates/investigator/task.md`
-- `templates/phase-author/task.md`
-- `templates/plan-creator/task.md`
-- `templates/plan-decomposer/task.md`
-- `templates/project-definer/task.md`
-- `templates/project-inferrer/task.md`
-- `templates/requirements-gatherer/task.md`
-- `templates/researcher/task.md`
-- `templates/shared/macros.md`
-- `templates/spec-implementer/task.md`
-- `templates/synthesizer/system.md`
-- `templates/synthesizer/task.md`
-- `templates/task-verifier/task.md`
-- `templates/task-worker/task.md`
-- `templates/verifier/task.md`

package/skills/pi-project/SKILL.md

@@ -1,242 +0,0 @@
----
-name: pi-project
-description: >
-  Schema-driven project state management with typed JSON blocks, schema
-  validation, planning lifecycle, and cross-block referential integrity. Use when
-  managing .project/ blocks, scaffolding project structure, validating project
-  state, or adding work items.
----
-
-<tools_reference>
-<tool name="append-block-item">
-Append an item to an array in a project block file. Schema validation is automatic.
-
-*Append items to project blocks (issues, decisions, or any user-defined block)*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `block` | string | yes | Block name (e.g., 'issues', 'decisions') |
-| `arrayKey` | string | yes | Array key in the block (e.g., 'issues', 'decisions') |
-| `item` | unknown | yes | Item object to append — must conform to block schema |
-</tool>
-
-<tool name="update-block-item">
-Update fields on an item in a project block array. Finds by predicate field match.
-
-*Update items in project blocks — change status, add details, mark resolved*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `block` | string | yes | Block name (e.g., 'issues', 'decisions') |
-| `arrayKey` | string | yes | Array key in the block |
-| `match` | object | yes | Fields to match (e.g., { id: 'issue-123' }) |
-| `updates` | object | yes | Fields to update (e.g., { status: 'resolved' }) |
-</tool>
-
-<tool name="read-block">
-Read a project block file as structured JSON.
-
-*Read a project block as structured JSON*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `block` | string | yes | Block name (e.g., 'issues', 'tasks', 'requirements') |
-</tool>
-
-<tool name="write-block">
-Write or replace an entire project block with schema validation.
-
-*Write or replace a project block with schema validation*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `block` | string | yes | Block name (e.g., 'project', 'architecture') |
-| `data` | unknown | yes | Complete block data — must conform to block schema |
-</tool>
-
-<tool name="project-status">
-Get derived project state — source metrics, block summaries, planning lifecycle status.
-
-*Get project state — source metrics, block summaries, planning lifecycle status*
-
-</tool>
-
-<tool name="project-validate">
-Validate cross-block referential integrity — check that IDs referenced across blocks exist.
-
-*Validate cross-block referential integrity*
-
-</tool>
-
-<tool name="project-init">
-Initialize .project/ directory with default schemas and empty block files.
-
-*Initialize .project/ directory with default schemas and blocks*
-
-</tool>
-
-<tool name="complete-task">
-Complete a task with verification gate — requires a passing verification entry targeting the task.
-
-*Complete a task — gates on passing verification before updating status*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `taskId` | string | yes | Task ID to complete |
-| `verificationId` | string | yes | Verification entry ID (must target this task with status 'passed') |
-</tool>
-
-</tools_reference>
-
-<commands_reference>
-<command name="/project">
-Project state management
-
-Subcommands: `init`, `status`, `add-work`, `validate`, `help`
-</command>
-
-</commands_reference>
-
-<events>
-`session_start`
-</events>
-
-<bundled_resources>
-22 defaults bundled.
-See references/bundled-resources.md for full inventory.
-</bundled_resources>
-
-<planning_vocabulary>
-
-**Block Types:**
-
-| Block | Title | Array Key | Item Fields |
-|-------|-------|-----------|-------------|
-| `architecture` | Architecture | `modules` | name, file, responsibility, dependencies? (array), lines? (integer) |
-| `audit` | Audit | `checks` | id, description, status (string (pass|fail|warn|skip)), category?, details? |
-| `conformance-reference` | Conformance Reference | `principles` | id, name, description?, rules (array) |
-| `decisions` | Decisions | `decisions` | id, decision, rationale, phase? (string|integer), status (string (decided|tentative|revisit|superseded)), context?, task? |
-| `domain` | Domain Knowledge | `entries` | id, title, content, category (string (research|reference|domain-rule|prior-art|constraint)), source?, confidence? (string (high|medium|low)), related_requirements? (array), tags? (array) |
-| `handoff` | Handoff | `current_tasks` |  |
-| `issues` | Issues | `issues` | id, title, body, location, status (string (open|resolved|deferred)), category (string (primitive|issue|cleanup|capability|composition)), priority (string (low|medium|high|critical)), package, source? (string (human|agent|monitor|workflow)), resolved_by? |
-| `phase` | Phase | `success_criteria` | criterion, verify_method (string (command|inspect|test)) |
-| `project` | Project Identity | `target_users` |  |
-| `rationale` | Design Rationale | `rationales` | id, title, narrative, related_decisions? (array), phase? (string|integer), context? |
-| `requirements` | Requirements | `requirements` | id, description, type (string (functional|non-functional|constraint|integration)), status (string (proposed|accepted|deferred|implemented|verified)), priority (string (must|should|could|wont)), acceptance_criteria? (array), source? (string (human|agent|analysis)), traces_to? (array), depends_on? (array) |
-| `tasks` | Tasks | `tasks` | id, description, status (string (planned|in-progress|completed|blocked|cancelled)), phase? (string|integer), files? (array), acceptance_criteria? (array), depends_on? (array), assigned_agent?, verification?, notes? |
-| `verification` | Verification | `verifications` | id, target, target_type (string (task|phase|requirement)), status (string (passed|failed|partial|skipped)), method (string (command|inspect|test)), evidence?, timestamp?, criteria_results? (array) |
-
-**Status Enums:**
-
-| Block | Field | Values |
-|-------|-------|--------|
-| `audit` | `status` | pass, fail, warn, skip |
-| `audit` | `severity` | error, warning, info |
-| `decisions` | `status` | decided, tentative, revisit, superseded |
-| `domain` | `category` | research, reference, domain-rule, prior-art, constraint |
-| `domain` | `confidence` | high, medium, low |
-| `issues` | `status` | open, resolved, deferred |
-| `issues` | `category` | primitive, issue, cleanup, capability, composition |
-| `issues` | `priority` | low, medium, high, critical |
-| `issues` | `source` | human, agent, monitor, workflow |
-| `phase` | `status` | planned, in-progress, completed |
-| `phase` | `verify_method` | command, inspect, test |
-| `phase` | `status` | planned, in-progress, completed |
-| `project` | `status` | inception, planning, development, maintenance, complete |
-| `requirements` | `type` | functional, non-functional, constraint, integration |
-| `requirements` | `status` | proposed, accepted, deferred, implemented, verified |
-| `requirements` | `priority` | must, should, could, wont |
-| `requirements` | `source` | human, agent, analysis |
-| `tasks` | `status` | planned, in-progress, completed, blocked, cancelled |
-| `verification` | `target_type` | task, phase, requirement |
-| `verification` | `status` | passed, failed, partial, skipped |
-| `verification` | `method` | command, inspect, test |
-
-</planning_vocabulary>
-
-<objective>
-pi-project manages structured project state in `.project/` — a directory of JSON block files validated against schemas.
-</objective>
-
-<block_files>
-Blocks are JSON files in `.project/` (e.g., `gaps.json`, `decisions.json`). Each block has a corresponding schema in `.project/schemas/`. When you write to a block via the tools, the data is validated against its schema before persisting. Writes are atomic (tmp file + rename).
-</block_files>
-
-<schema_validation>
-Every block write validates against `.project/schemas/<blockname>.schema.json`. If the schema file doesn't exist, writes proceed without validation. Validation errors include the specific JSON Schema violations.
-</schema_validation>
-
-<project_init>
-`/project init` scaffolds the `.project/` directory with default schemas and empty block files from the package's `defaults/` directory. Idempotent — skips files that already exist.
-</project_init>
-
-<project_status>
-`/project status` derives project state dynamically from the filesystem:
-- Source file count and line count (`.ts` files excluding tests)
-- Test count and test file count
-- Schema count, block count, phase count
-- Block summaries with array item counts and status distributions
-- Requirements summary (total, by status, by priority) — from requirements.json
-- Tasks summary (total, by status) — from tasks.json
-- Domain entry count — from domain.json
-- Verification summary (total, passed, failed) — from verification.json
-- Handoff presence — whether handoff.json exists
-- Recent git commits
-- Current phase detection
-</project_status>
-
-<project_add_work>
-`/project add-work` discovers appendable blocks (blocks with array schemas), reads their schemas, and sends a structured instruction to the LLM to extract items from the conversation into the typed blocks. This is a follow-up message that triggers the LLM to use the `append-block-item` tool.
-</project_add_work>
-
-<duplicate_detection>
-`append-block-item` checks for duplicate items by `id` field before appending. If an item with the same `id` already exists in the target array, it returns a message instead of appending.
-</duplicate_detection>
-
-<project_validate>
-`/project validate` checks cross-block referential integrity:
-- task.phase references a valid phase
-- task.depends_on references valid task IDs
-- decision.phase references a valid phase
-- gap.resolved_by references a valid ID
-- requirement.traces_to references valid phase/task IDs
-- requirement.depends_on references valid requirement IDs
-- verification.target references a valid target ID
-- rationale.related_decisions references valid decision IDs
-
-Returns errors (broken dependency references) and warnings (unresolved cross-references).
-</project_validate>
-
-<planning_lifecycle>
-The default schemas support a full planning lifecycle:
-- **project.json** — identity, vision, goals, constraints, scope, status
-- **domain.json** — research findings, reference material, domain rules
-- **requirements.json** — functional/non-functional requirements with MoSCoW priority and lifecycle states
-- **architecture.json** — modules, patterns, boundaries
-- **phases/** — ordered delivery units with goals, success criteria, inputs/outputs
-- **tasks.json** — standalone task registry with status lifecycle and phase linkage
-- **decisions.json** — choices with rationale and phase association
-- **gaps.json** — open items with priority, category, and resolution tracking
-- **rationale.json** — design rationale with decision cross-references
-- **handoff.json** — session context snapshot (created on-demand, not by /project init)
-- **verification.json** — completion evidence per task/phase/requirement
-- **conformance-reference.json** — executable code conventions with principles, rules, check methods (grep/command/ast/inspect), and check patterns. Ships empty, populated per-project by agents or users.
-- **audit** (schema only, no default block) — structured audit results produced by running conformance checks.
-
-All schemas are user-customizable. Edit `.project/schemas/*.schema.json` to add fields, change enums, or restructure blocks without modifying code.
-</planning_lifecycle>
-
-<update_check>
-On `session_start`, checks npm registry for newer versions of `@davidorex/pi-project-workflows` and notifies via UI if an update is available. Non-blocking — failures are silently ignored.
-</update_check>
-
-<success_criteria>
-- `.project/` directory exists with schemas and block files after `/project init`
-- Block writes validate against schemas — invalid data rejected with specific error
-- `/project status` returns current derived state without errors
-- `/project validate` returns no errors for well-formed cross-block references
-- `append-block-item` rejects duplicate IDs
-- Schema customizations (field additions, enum changes) take effect on next write
-</success_criteria>
-
-*Generated from source by `scripts/generate-skills.js` — do not edit by hand.*

package/skills/pi-project/references/bundled-resources.md

@@ -1,26 +0,0 @@
-# Bundled Resources
-
-## defaults/ (22 files)
-
-- `defaults/blocks/conformance-reference.json`
-- `defaults/blocks/decisions.json`
-- `defaults/blocks/domain.json`
-- `defaults/blocks/issues.json`
-- `defaults/blocks/project.json`
-- `defaults/blocks/rationale.json`
-- `defaults/blocks/requirements.json`
-- `defaults/blocks/tasks.json`
-- `defaults/blocks/verification.json`
-- `defaults/schemas/architecture.schema.json`
-- `defaults/schemas/audit.schema.json`
-- `defaults/schemas/conformance-reference.schema.json`
-- `defaults/schemas/decisions.schema.json`
-- `defaults/schemas/domain.schema.json`
-- `defaults/schemas/handoff.schema.json`
-- `defaults/schemas/issues.schema.json`
-- `defaults/schemas/phase.schema.json`
-- `defaults/schemas/project.schema.json`
-- `defaults/schemas/rationale.schema.json`
-- `defaults/schemas/requirements.schema.json`
-- `defaults/schemas/tasks.schema.json`
-- `defaults/schemas/verification.schema.json`