@davidorex/pi-project-workflows 0.26.0 → 0.28.1

package/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.28.1] - 2026-06-03
+
+## [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 three [Pi](https://github.com/badlogic/pi-mono) extensions plus a shared agent-runtime library — structured project state, workflow orchestration, behavior monitoring, and agent spec compilation — 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,16 +8,17 @@ Convenience meta-package that re-exports three [Pi](https://github.com/badlogic/
 pi install npm:@davidorex/pi-project-workflows
 ```
 
-This installs the four constituent packages:
+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
 
 ```
-/context 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
 /context status   # see derived project state
 /workflow list    # discover and run workflows
@@ -31,3 +32,4 @@ See the package READMEs for full API docs, source maps, and LLM guidance:
 - [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.26.0",
+	"version": "0.28.1",
+	"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-context": "^0.26.0",
-		"@davidorex/pi-workflows": "^0.26.0",
-		"@davidorex/pi-behavior-monitors": "^0.26.0"
+		"@davidorex/pi-context": "^0.28.1",
+		"@davidorex/pi-workflows": "^0.28.1",
+		"@davidorex/pi-behavior-monitors": "^0.28.1",
+		"@davidorex/pi-agent-dispatch": "^0.28.1"
 	}
 }

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

@@ -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-project-workflows/SKILL.md

@@ -18,7 +18,7 @@ pi install npm:@davidorex/pi-project-workflows
 <extension name="@davidorex/pi-context">
 Schema-driven project state management for Pi
 
-**Tools:** `append-block-item`, `update-block-item`, `append-relation`, `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`, `context-init`, `context-accept-all`, `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`
+**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>
 
@@ -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

@@ -80,7 +80,7 @@ Render a project block item by ID through its registered per-item macro. Resolve
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `id` | string | yes | Kind-prefixed ID, e.g., DEC-0001 / FEAT-001 |
+| `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>
 
@@ -113,7 +113,7 @@ Subcommands: `init`, `list`, `run`, `resume`, `validate`, `status`, `help`
 </keyboard_shortcuts>
 
 <bundled_resources>
-26 agents, 15 schemas, 15 workflows, 48 templates bundled.
+26 agents, 15 schemas, 15 workflows bundled.
 See references/bundled-resources.md for full inventory.
 </bundled_resources>
 
@@ -247,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>
@@ -274,7 +274,7 @@ 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 |
-| block | `block: { op: read\|write\|append\|update\|remove\|… }` | Validated in-process `.project` block I/O via the block API — no LLM, no subprocess |
+| 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>
@@ -312,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>
@@ -327,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,54 +64,3 @@
 - `workflows/resumable-analysis.workflow.yaml`
 - `workflows/self-implement.workflow.yaml`
 - `workflows/typed-analysis.workflow.yaml`
-
-## templates/ (48 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/items/architecture.md`
-- `templates/items/conformance.md`
-- `templates/items/conventions.md`
-- `templates/items/decisions.md`
-- `templates/items/domain.md`
-- `templates/items/features.md`
-- `templates/items/framework-gaps.md`
-- `templates/items/issues.md`
-- `templates/items/layer-plans.md`
-- `templates/items/project.md`
-- `templates/items/requirements.md`
-- `templates/items/research.md`
-- `templates/items/spec-reviews.md`
-- `templates/items/tasks.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/shared/render-helpers.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-context/SKILL.md

@@ -1,684 +0,0 @@
----
-name: pi-context
-description: >
-  Schema-driven project state management with typed JSON blocks, schema
-  validation, substrate config, lens views, closure-table relations, and
-  cross-block referential integrity. Use when managing .project/ blocks,
-  scaffolding project structure, installing block kinds from the packaged samples
-  catalog, validating project state, rendering lens views, 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. Set autoId:true to allocate the next id from the block's id pattern when the item has no id.
-
-*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 |
-| `autoId` | boolean | no | When true and the item has no id, allocate the next id from the block's id pattern |
-</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="append-relation">
-Append a closure-table relation (edge: parent, child, relation_type, optional ordinal) to relations.json. Shape is AJV-validated; an exact-duplicate edge (same parent+child+relation_type) is a no-op. Reference integrity (endpoints resolve, relation_type registered, no cycle) is NOT checked here — run context-validate after. Creates relations.json if absent.
-
-*Create a relation/edge between two items (parent→child under a relation_type)*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `parent` | string | yes | Canonical id (or lens bin name) of the parent endpoint |
-| `child` | string | yes | Canonical id of the child endpoint |
-| `relation_type` | string | yes | Registered relation_type canonical_id / hierarchy edge type / lens id |
-| `ordinal` | integer | no | Optional sibling-ordering within (parent, relation_type) |
-</tool>
-
-<tool name="append-block-nested-item">
-Append an item to a nested array on a parent-array item in a project block. Schema validation is automatic.
-
-*Append items to nested arrays inside parent items (e.g., findings inside a review)*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `block` | string | yes | Block name (e.g., 'spec-reviews') |
-| `arrayKey` | string | yes | Parent array key (e.g., 'reviews') |
-| `match` | object | yes | Fields to match the parent item (e.g., { id: 'REVIEW-001' }) |
-| `nestedKey` | string | yes | Nested array key on the matched parent (e.g., 'findings') |
-| `item` | unknown | yes | Item object to append to the nested array — must conform to schema |
-</tool>
-
-<tool name="update-block-nested-item">
-Update fields on a nested-array item inside a parent-array item in a project block. Finds parent and nested by predicate field match. Throws on parent or nested miss (mirrors update-block-item semantics).
-
-*Update items inside nested arrays — change finding state, mark resolved*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `block` | string | yes | Block name (e.g., 'spec-reviews') |
-| `arrayKey` | string | yes | Parent array key (e.g., 'reviews') |
-| `match` | object | yes | Fields to match the parent item (e.g., { id: 'REVIEW-001' }) |
-| `nestedKey` | string | yes | Nested array key on the matched parent (e.g., 'findings') |
-| `nestedMatch` | object | yes | Fields to match the nested item (e.g., { id: 'F-001' }) |
-| `updates` | object | yes | Fields to update on the nested item (e.g., { state: 'resolved' }) |
-</tool>
-
-<tool name="remove-block-item">
-Remove items matching a predicate from a top-level array in a project block. Idempotent — returns { removed: 0 } on no match without throwing. Schema validation runs after removal.
-
-*Remove items from project blocks — prune retracted issues, dedupe entries*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `block` | string | yes | Block name (e.g., 'issues') |
-| `arrayKey` | string | yes | Top-level array key (e.g., 'issues') |
-| `match` | object | yes | Fields to match (e.g., { id: 'issue-123' }) |
-</tool>
-
-<tool name="remove-block-nested-item">
-Remove items matching a predicate from a nested array on a parent-array item in a project block. Throws on parent miss; returns { removed: 0 } on nested miss without throwing.
-
-*Remove nested items — drop rejected findings, retract nested references*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `block` | string | yes | Block name (e.g., 'spec-reviews') |
-| `arrayKey` | string | yes | Parent array key (e.g., 'reviews') |
-| `match` | object | yes | Fields to match the parent item (e.g., { id: 'REVIEW-001' }) |
-| `nestedKey` | string | yes | Nested array key on the matched parent (e.g., 'findings') |
-| `nestedMatch` | object | yes | Fields to match the nested items to remove (e.g., { id: 'F-001' }) |
-</tool>
-
-<tool name="read-block-dir">
-Enumerate and parse all .json files in a .project/<subdir>/ directory, returned as a sorted array. Missing directories return [].
-
-*Enumerate project block subdirectories (phases, schemas, etc.) as parsed JSON*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `subdir` | string | yes | Subdirectory under .project/ (e.g., 'phases', 'schemas') |
-</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="context-status">
-Get derived context state — source metrics, block summaries, planning lifecycle status.
-
-*Get context state — source metrics, block summaries, planning lifecycle status*
-
-</tool>
-
-<tool name="context-validate">
-Validate cross-block referential integrity — check that IDs referenced across blocks exist.
-
-*Validate cross-block referential integrity*
-
-</tool>
-
-<tool name="read-config">
-Read the substrate config.json as structured JSON — vocabulary, lenses, relation_types, status_buckets, display_strings, layers, block_kinds, installed_schemas, installed_blocks.
-
-*Read project config — vocabulary, lenses, relation_types, status_buckets*
-
-</tool>
-
-<tool name="list-tools">
-List every tool bound into the current Pi session — name, description, parameter JSON-schema, and source extension — plus which tools are currently active. Self-introspection of the agent's own tool surface (all loaded extensions + builtins).
-
-*Discover available tools — names, params, descriptions, active set*
-
-</tool>
-
-<tool name="read-samples-catalog">
-Enumerate installable sample block kinds (DEC-0037 packaged view): per kind — title, description, item shape, applicable relation_types (as source/target), invariants, lenses — plus top-level relation_type/lens/invariant/layer/status_bucket registries. Package-intrinsic: reads the extension's bundled samples catalog, independent of any project. Optional `kind` returns one packaged kind.
-
-*Discover installable sample block kinds — title, shape, relation_types, invariants, lenses*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `kind` | string | no | Filter to one block_kind canonical_id (e.g. 'tasks') |
-</tool>
-
-<tool name="context-current-state">
-Derive 'where are we + what's next' purely from .project substrate — focus, in-flight tasks, ranked atomic-next actions (open framework-gaps then unblocked planned tasks), and blocked tasks. No writes; nothing hand-stored.
-
-*Derive current project state — focus, in-flight, next actions, blocked*
-
-</tool>
-
-<tool name="context-bootstrap-state">
-Derive the substrate bootstrap state for the cwd, purely from the filesystem (DEC-0040): 'no-pointer' | 'no-config' | 'not-installed' | 'ready', plus the resolved contextDir and any declared-but-unmaterialized installed assets. Unlike every other tool, this NEVER throws on an un-bootstrapped substrate — it returns 'no-pointer' so you can detect a fresh substrate and tell the human to run /context start (bootstrap is human-only). No writes.
-
-*Derive substrate bootstrap state — no-pointer | no-config | not-installed | ready (never throws pre-bootstrap)*
-
-</tool>
-
-<tool name="rename-canonical-id">
-Rename a canonical_id (kind: item | relation_type | lens | layer) from oldId to newId across all substrate surfaces that carry it as DATA — item home block + relations.json edges, or the relevant config registries. Out-of-substrate occurrences (analysis MDs, git history) are REPORTED, never rewritten. block_kind renames are unsupported (filesystem cascade). Use dryRun to preview the would-change counts without writing.
-
-*Rename a canonical_id (item/relation_type/lens/layer) across substrate; dryRun to preview*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `kind` | string | yes | One of: item | relation_type | lens | layer |
-| `oldId` | string | yes | Current canonical_id to rename from |
-| `newId` | string | yes | New canonical_id to rename to |
-| `dryRun` | boolean | no | Compute would-change counts without writing |
-</tool>
-
-<tool name="amend-config">
-Scoped add / replace / remove of ONE entry in ONE config.json registry (block_kinds, relation_types, lenses, layers, invariants, status_buckets, display_strings, naming, installed_schemas, installed_blocks, hierarchy). The whole resulting config is AJV-validated (SHAPE) and op-correctness is enforced (add ⇒ key absent, replace/remove ⇒ key present). Cross-registry referential integrity (removing a still-referenced relation_type / lens / layer / block_kind) is NOT checked here — run context-validate after. dryRun previews without writing.
-
-*Add/replace/remove one entry in a config.json registry (vocabulary, lenses, invariants, status_buckets)*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `registry` | string | yes | One of: block_kinds | relation_types | lenses | layers | invariants | status_buckets | display_strings | naming | installed_schemas | installed_blocks | hierarchy |
-| `operation` | string | yes | add | replace | remove |
-| `key` | string | yes | Entry key: id for keyed-array (block_kinds/relation_types/lenses/layers/invariants), map key for map (status_buckets/display_strings/naming), the string value for string-array (installed_schemas/installed_blocks), or a JSON {parent_block, child_block, relation_type} for hierarchy |
-| `entry` | unknown | no | Entry payload: object for keyed-array/hierarchy, string for map value; omit for remove. For keyed-array its id field must equal key; for string-array (when given) it must equal key |
-| `dryRun` | boolean | no | Preview the op without writing config.json |
-</tool>
-
-<tool name="read-schema">
-Read a substrate schema by name as parsed JSON. Returns null when the schema file is absent.
-
-*Read a block schema as structured JSON*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `schemaName` | string | yes | Schema name without extension (e.g., 'tasks', 'decisions', 'issues') |
-</tool>
-
-<tool name="write-schema">
-Create or replace a substrate block-kind JSON Schema. operation 'create' requires the schema absent; 'replace' requires it present. The body is AJV draft-07 meta-validated before an atomic write. CAVEAT: a 'replace' that changes the schema's version does NOT migrate existing block items — read-time validateBlockWithMigration throws a version mismatch until a code-level MigrationFn is registered (no tool surface for that). Registering the block_kind that points at this schema is a separate step (amend-config block_kinds).
-
-*Create or replace a block-kind JSON Schema (meta-validated, atomic)*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `operation` | string | yes | create | replace |
-| `schemaName` | string | yes | Schema name without extension (e.g., 'tasks') |
-| `schema` | unknown | yes | The whole JSON Schema object (draft-07). Accepts a JSON string. |
-| `dryRun` | boolean | no | Meta-validate without writing |
-</tool>
-
-<tool name="context-init">
-Initialize the substrate dir (bootstrap pointer + dirs only; run accept-all + install to populate).
-
-*Initialize the substrate dir (bootstrap pointer + dirs only; run accept-all + install to populate)*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `contextDir` | string | yes | Substrate dir name (e.g. .project). Required per DEC-0015 — no default. |
-</tool>
-
-<tool name="context-accept-all">
-Adopt the canonical packaged conception (samples/conception.json) as this substrate's config.json (accept-all). Writes config only — run install after. Idempotent: never overwrites an existing config.
-
-*Adopt the canonical conception as config (accept-all)*
-
-</tool>
-
-<tool name="filter-block-items">
-Filter the array items of a block by a single-field predicate (eq / neq / in / matches). Discovers the single top-level array property in the block; items missing the predicate field are never matched. Wraps the canonical readBlock + caller-side filter into one queryable surface; never mutates the block.
-
-*Filter a block's items by a predicate — eq / neq / in / matches against a single field*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `block` | string | yes | Block name (e.g., 'tasks', 'decisions', 'framework-gaps', 'context-contracts') |
-| `field` | string | yes | Item field to test (e.g., 'status', 'priority', 'id') |
-| `op` | unknown | yes | Comparison operator: eq (===), neq (!==), in (value is array, item[field] in it), matches (regexp test on string) |
-| `value` | unknown | yes | Comparison value — scalar for eq/neq, array for in, regexp pattern string for matches |
-</tool>
-
-<tool name="resolve-item-by-id">
-Look up the block, array key, and item payload for a given ID across all .project/ blocks. Returns null when no item matches. Mirrors the resolveItemById SDK function and shares its prefix-vs-block invariant — IDs whose prefix maps to a known block but live elsewhere throw at index-build time.
-
-*Resolve a kind-prefixed ID (DEC-/FEAT-/FGAP-/issue-/REQ-/TASK-/etc.) to its owning block and item*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `id` | string | yes | Kind-prefixed ID, e.g., DEC-0001 / FEAT-001 / FGAP-003 / issue-064 |
-</tool>
-
-<tool name="read-block-item">
-Read a single item from a named block by its id — returns the item or null. Block-scoped (unlike resolve-item-by-id, which searches all blocks by kind-prefixed id). Avoids fetching a whole large block to get one item.
-
-*Read one item from a block by id (block-scoped; null if absent)*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `block` | string | yes | Block name (e.g., 'tasks', 'decisions', 'framework-gaps') |
-| `id` | string | yes | Item id within the block (e.g., 'TASK-001') |
-</tool>
-
-<tool name="read-block-page">
-Paginate a block's items: returns { items, total, hasMore }. offset default 0, limit default 50. Use for blocks too large to fetch whole (past the 50KB read-block cap). total is the full item count; hasMore signals another page.
-
-*Paginate a block's items — offset + limit; returns {items,total,hasMore}*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `block` | string | yes | Block name (e.g., 'framework-gaps', 'decisions', 'issues') |
-| `offset` | integer | no | Start index (default 0) |
-| `limit` | integer | no | Max items to return (default 50) |
-</tool>
-
-<tool name="join-blocks">
-Join two blocks in one call (FGAP-043). EDGE mode: pass `relationType` — pairs left items with right-block items connected by that relations.json edge (`leftEndpoint` parent|child, default parent). FIELD mode: pass `leftField`+`rightField` — pairs where left[leftField] === right[rightField]. Optional left pre-filter via where{Field,Op,Value}. Returns [{left, right:[]}] (right always an array; one-to-many). Use instead of N+1 read-block + resolve calls.
-
-*Join two blocks in one call — by relation edge or shared field; returns {left,right[]} pairs*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `leftBlock` | string | yes | Left block name (e.g., 'tasks') |
-| `rightBlock` | string | yes | Right block name (e.g., 'verification') |
-| `relationType` | string | no | Edge mode: relations.json relation_type |
-| `leftField` | string | no | Field mode: left item field |
-| `rightField` | string | no | Field mode: right item field |
-| `leftEndpoint` | unknown | no | Edge mode: is the left item the edge parent (default) or child |
-| `whereField` | string | no | Optional left pre-filter field |
-| `whereOp` | unknown | no |  |
-| `whereValue` | unknown | no | Optional left pre-filter value |
-</tool>
-
-<tool name="resolve-items-by-id">
-Bulk variant of resolve-item-by-id — resolve N kind-prefixed ids against a single buildIdIndex traversal. Returns an object mapping each input id to its ItemLocation (block / arrayKey / item) or null when not found. Coexists with the singular resolve-item-by-id tool; bulk collapses the N×singular-call pattern for callers resolving multiple ids in one render pass.
-
-*Resolve a batch of kind-prefixed ids (DEC-/FGAP-/TASK-/issue-/REQ-/...) in one call*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `ids` | array | yes | Array of kind-prefixed ids (DEC-/FGAP-/TASK-/issue-/REQ-/...) to resolve in one call |
-</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>
-
-<tool name="context-validate-relations">
-Validate substrate relations.json edges against config-declared lenses + hierarchy + relation_types and the cross-block id index. Returns SubstrateValidationResult with status (clean/warnings/invalid) and per-issue diagnostics.
-
-*Validate substrate relations against config + items*
-
-</tool>
-
-<tool name="context-edges-for-lens">
-Materialize the Edge[] for a named lens — synthetic edges from derived_from_field for auto-derived lenses; authored edges filtered by relation_type for hand-curated lenses; unioned items from composition members for kind=composition lenses.
-
-*Materialize edges for a named lens (auto-derived or hand-curated)*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `lensId` | string | yes | Lens id from config.lenses[].id |
-</tool>
-
-<tool name="context-walk-descendants">
-Walk closure-table descendants of a parent id under a given relation_type. Returns string[] of descendant ids (may be empty if no children or relations.json absent).
-
-*Walk closure-table descendants under a relation_type*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `parentId` | string | yes | Parent id (canonical id or lens bin name) |
-| `relationType` | string | yes | Relation type from config.relation_types[].canonical_id |
-</tool>
-
-<tool name="walk-ancestors">
-Walk closure-table ancestors of an item id under a given relation_type — reverse-direction counterpart to context-walk-descendants. Returns string[] of ancestor ids (may be empty if no parents or relations.json absent).
-
-*Walk closure-table ancestors under a relation_type*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `itemId` | string | yes | Child item id whose ancestors are sought |
-| `relationType` | string | yes | Relation type from config.relation_types[].canonical_id |
-</tool>
-
-<tool name="find-references">
-Find all closure-table edges incident on an item id (inbound, outbound, or both). Returns Edge[] preserving relation_type + ordinal per record — edge-level view, not the id-chain projection that walk-ancestors / context-walk-descendants emit.
-
-*Find closure-table edges incident on an item id*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `itemId` | string | yes | Item id whose incident edges are sought |
-| `direction` | unknown | no | inbound: edges where child === itemId; outbound: edges where parent === itemId; both: union (default). |
-</tool>
-
-<tool name="gather-execution-context">
-Compose a ContextBundle for a work-unit by reading its context-contract (by unit_kind) and walking declared relation_types bidirectionally per direction semantic. Returns unit + perRelationType buckets of resolved items + traversal_depth + scoped_at. Per DEC-0017 substrate primitive serving harness-confined dispatch.
-
-*Compose ContextBundle for unit + context-contract-declared bundle_relation_types*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `unitId` | string | yes | Work-unit id (e.g. TASK-NNN / DEC-NNNN / FGAP-NNN) |
-| `kind` | string | yes | Unit-kind type tag (e.g. 'task', 'decision', 'verification') matching a context-contract entry's unit_kind |
-| `maxDepth` | integer | no | Override per-relation-type max_depth via Math.min against each spec.max_depth |
-</tool>
-
-<tool name="context-roadmap-load">
-Load a roadmap by id and return the materialized RoadmapView (phases, lens-views, status rollup, milestone resolution, scoped phase_depends_on edges, topo-ordered phaseOrder + cycles). Per DEC-0012 phase ordering lives in relations.json with relation_type='phase_depends_on'.
-
-*Load a roadmap by id*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `roadmapId` | string | yes | ROADMAP-NNN id from <config.root>/roadmap.json |
-</tool>
-
-<tool name="context-roadmap-render">
-Render a roadmap by id as pure-textual markdown — phase order list, per-phase adjacency lines (sourced from view.edges, alphabetically sorted), status rollup counts, milestone resolution, exit criteria. NO mermaid / graph syntax: per-phase **Depends on:** lines come strictly from authored phase_depends_on edges scoped to in-roadmap phases.
-
-*Render a roadmap as markdown*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `roadmapId` | string | yes | ROADMAP-NNN id from <config.root>/roadmap.json |
-</tool>
-
-<tool name="context-roadmap-validate">
-Validate every roadmap × phase × milestone in <config.root>/roadmap.json. Codes: roadmap_lens_missing, roadmap_phase_dep_missing, roadmap_phase_cycle, roadmap_composition_cycle, roadmap_milestone_evidence_block_missing, roadmap_milestone_query_invalid, roadmap_status_unknown_value. Display strings flow through config.display_strings (pi-context divergence). Optional roadmapId filter restricts issue list to a single roadmap.
-
-*Validate roadmaps*
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `roadmapId` | string | no | Filter to issues matching this roadmap_id (omit for full-project validation) |
-</tool>
-
-<tool name="context-roadmap-list">
-List every roadmap in <config.root>/roadmap.json with id, title, optional status, and phase count. Returns [] when roadmap.json absent (opt-in block; absence is the truthful answer).
-
-*List roadmaps*
-
-</tool>
-
-</tools_reference>
-
-<commands_reference>
-<command name="/context">
-Context state management
-
-Subcommands: `init`, `install`, `accept-all`, `view`, `lens-curate`, `roadmap-list`, `roadmap-view`, `roadmap-validate`, `status`, `add-work`, `validate`, `help`
-</command>
-
-</commands_reference>
-
-<events>
-`session_start`
-</events>
-
-<bundled_resources>
-9 schemas, 31 samples bundled.
-See references/bundled-resources.md for full inventory.
-</bundled_resources>
-
-<installable_blocks>
-
-Names valid for the `installed_blocks` array in `.project/config.json`. Install with `/context install <block>`.
-
-| Block | Source File |
-|-------|-------------|
-| `decisions` | `samples/blocks/decisions.json` |
-| `framework-gaps` | `samples/blocks/framework-gaps.json` |
-| `tasks` | `samples/blocks/tasks.json` |
-| `verification` | `samples/blocks/verification.json` |
-| `issues` | `samples/blocks/issues.json` |
-| `features` | `samples/blocks/features.json` |
-| `research` | `samples/blocks/research.json` |
-| `rationale` | `samples/blocks/rationale.json` |
-| `spec-reviews` | `samples/blocks/spec-reviews.json` |
-| `layer-plans` | `samples/blocks/layer-plans.json` |
-| `requirements` | `samples/blocks/requirements.json` |
-| `conventions` | `samples/blocks/conventions.json` |
-| `context-contracts` | `samples/blocks/context-contracts.json` |
-| `phase` | `samples/blocks/phase.json` |
-| `story` | `samples/blocks/story.json` |
-
-</installable_blocks>
-
-<installable_schemas>
-
-Names valid for the `installed_schemas` array in `.project/config.json`. Schemas back block validation; install with `/context install <schema>`.
-
-| Schema | Source File |
-|--------|-------------|
-| `decisions` | `samples/schemas/decisions.schema.json` |
-| `framework-gaps` | `samples/schemas/framework-gaps.schema.json` |
-| `tasks` | `samples/schemas/tasks.schema.json` |
-| `verification` | `samples/schemas/verification.schema.json` |
-| `issues` | `samples/schemas/issues.schema.json` |
-| `features` | `samples/schemas/features.schema.json` |
-| `research` | `samples/schemas/research.schema.json` |
-| `rationale` | `samples/schemas/rationale.schema.json` |
-| `spec-reviews` | `samples/schemas/spec-reviews.schema.json` |
-| `layer-plans` | `samples/schemas/layer-plans.schema.json` |
-| `requirements` | `samples/schemas/requirements.schema.json` |
-| `conventions` | `samples/schemas/conventions.schema.json` |
-| `context-contracts` | `samples/schemas/context-contracts.schema.json` |
-| `phase` | `samples/schemas/phase.schema.json` |
-| `story` | `samples/schemas/story.schema.json` |
-
-</installable_schemas>
-
-<planning_vocabulary>
-
-**Block Types:**
-
-| Block | Title | Array Key | Item Fields |
-|-------|-------|-----------|-------------|
-| `decisions` | Decisions | `decisions` | id, title, status (string (open|enacted|superseded)), context, decision, options_considered? (array), consequences (array), references? (array), created_by, created_at, enacted_by?, enacted_at? |
-| `framework-gaps` | Framework Gaps | `gaps` | id, title, status (string (identified|accepted|in-progress|closed|wontfix)), priority? (string (P0|P1|P2|P3)), package, layer? (string (L1|L2|L3|L4|L5)), description, evidence (array), impact, canonical_vocabulary?, proposed_resolution, created_by, created_at, closed_by?, closed_at? |
-| `tasks` | Tasks | `tasks` | id, description, status (string (planned|in-progress|completed|blocked|cancelled)), files? (array), acceptance_criteria? (array), assigned_agent?, notes? |
-| `verification` | Verification | `verifications` | id, status (string (passed|failed|partial|skipped)), method (string (command|inspect|test)), evidence?, timestamp?, criteria_results? (array) |
-| `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? |
-| `features` | Features | `features` | id, title, status (string (proposed|approved|in-progress|in-review|complete|blocked|cancelled)), layer (string (L1|L2|L3|L4|L5)), description, motivation?, acceptance_criteria (array), created_by, created_at, modified_by?, modified_at?, approved_by?, approved_at? |
-| `research` | Research | `research` | id, title, status (string (planned|in-progress|complete|stale|superseded|revised)), layer (string (L1|L2|L3|L4|L5)), type (string (investigative|comparative|empirical|historical|audit|landscape|feasibility|curation)), question, method, scope? (array), findings_summary, findings_document?, grounding? (object), grounded_at?, stale_conditions? (array), citations? (array), conducted_by?, conducted_at?, created_by, created_at, modified_by?, modified_at? |
-| `rationale` | Design Rationale | `rationales` | id, title, narrative, phase? (integer) |
-| `spec-reviews` | Spec Reviews | `reviews` | id, target, target_revision?, reviewer?, status (string (not-started|in-progress|complete|abandoned)), scope? (array), method?, clean? (boolean), created_by, created_at, completed_at? |
-| `layer-plans` | Layer Restructure Plans | `plans` | id, title, status (string (draft|proposed|decided|in-progress|complete|abandoned)), model, description?, layers (array), migration_phases (array), created_by, created_at |
-| `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)) |
-| `conventions` | Conventions | `rules` | id, description, enforcement (string (lint|test|review|manual)), severity (string (error|warning|info)) |
-| `context-contracts` | Context contracts | `contracts` | id, unit_kind, bundle_relation_types (array), description?, notes?, created_by, created_at, modified_by?, modified_at? |
-| `phase` | Phases | `phases` | id, name, intent, goal?, status (string (planned|in-progress|completed)), success_criteria? (array), specs? (array), artifacts_produced? (array) |
-| `story` | Stories | `stories` | id, title, status (string (proposed|ready|in-progress|in-review|complete|blocked)), description?, acceptance_criteria? (array), created_by?, created_at?, modified_by?, modified_at? |
-
-**Status Enums:**
-
-| Block | Field | Values |
-|-------|-------|--------|
-| `decisions` | `status` | open, enacted, superseded |
-| `framework-gaps` | `status` | identified, accepted, in-progress, closed, wontfix |
-| `framework-gaps` | `priority` | P0, P1, P2, P3 |
-| `framework-gaps` | `layer` | L1, L2, L3, L4, L5 |
-| `tasks` | `status` | planned, in-progress, completed, blocked, cancelled |
-| `verification` | `status` | passed, failed, partial, skipped |
-| `verification` | `method` | command, inspect, test |
-| `issues` | `status` | open, resolved, deferred |
-| `issues` | `category` | primitive, issue, cleanup, capability, composition |
-| `issues` | `priority` | low, medium, high, critical |
-| `issues` | `source` | human, agent, monitor, workflow |
-| `features` | `status` | proposed, approved, in-progress, in-review, complete, blocked, cancelled |
-| `features` | `layer` | L1, L2, L3, L4, L5 |
-| `research` | `status` | planned, in-progress, complete, stale, superseded, revised |
-| `research` | `layer` | L1, L2, L3, L4, L5 |
-| `research` | `type` | investigative, comparative, empirical, historical, audit, landscape, feasibility, curation |
-| `spec-reviews` | `status` | not-started, in-progress, complete, abandoned |
-| `layer-plans` | `status` | draft, proposed, decided, in-progress, complete, abandoned |
-| `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 |
-| `conventions` | `enforcement` | lint, test, review, manual |
-| `conventions` | `severity` | error, warning, info |
-| `phase` | `status` | planned, in-progress, completed |
-| `story` | `status` | proposed, ready, in-progress, in-review, complete, blocked |
-
-</planning_vocabulary>
-
-<objective>
-pi-context manages structured project state in `.project/` — a directory of JSON block files validated against schemas. The substrate (config + lenses + closure-table relations) is degree-zero state that defines where the rest lives and how items group into views.
-</objective>
-
-<block_files>
-Blocks are JSON files under the substrate root (e.g., `gaps.json`, `decisions.json`). Each block has a corresponding schema in `<root>/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) and serialised per block via `withBlockLock`. The substrate root is the dir chosen at init (recorded in the `.pi-context.json` bootstrap pointer) and written to `config.json`'s `root` field by `/context accept-all`; the framework ships no default (DEC-0015). block-api routes through `resolveContextDir(cwd)` — which resolves `config.root` when set and otherwise falls back to the pointer — so a relocated root reaches every read/write site.
-</block_files>
-
-<schema_validation>
-Every block write validates against `<root>/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>
-
-<context_init>
-`/context init <dir>` creates the substrate skeleton: the `.pi-context.json` bootstrap pointer (declaring the substrate-dir name per DEC-0015) plus the substrate root and its `schemas/` directory. Nothing is imposed — no `config.json`, no schemas, and no starter blocks are written (DEC-0011 ship-no-defaults). Idempotent: re-running preserves existing dirs. Populate the substrate next with `/context accept-all` (adopt the canonical conception) followed by `/context install`.
-</context_init>
-
-<context_accept_all>
-`/context accept-all` adopts the package's canonical packaged conception (`samples/conception.json`) as the substrate's `config.json` — the full vocabulary (`block_kinds`, `relation_types`, `lenses`, `invariants`) plus the `installed_schemas` / `installed_blocks` manifest — with `root` set to the actual substrate dir. It writes `config.json` only (run `/context install` after to materialize the schemas + starter blocks) and is idempotent: it never overwrites an existing `config.json` (offer, don't impose). This is the accept-all path; per-entry step-through curation is a separate surface.
-</context_accept_all>
-
-<context_install>
-`/context install` reconciles the substrate against the `installed_schemas` and `installed_blocks` lists declared in `config.json`. For each declared name it copies the matching asset from the package-shipped samples catalog (`samples/schemas/` for schemas, `samples/blocks/` for starter blocks) into the substrate. Default behavior is skip-if-exists (preserves user edits); pass `--update` to overwrite and report the asset as `updated`. Sources missing from the catalog are reported as `notFound`. Empty install lists are not an error — the result is a clean no-op message instructing the user to edit `config.json`.
-
-The installable catalog IS the packaged conception (`samples/conception.json`): its `block_kinds` enumerate the available kinds, each carrying its schema (`samples/schemas/`) and starter block (`samples/blocks/`). The generated installable-catalog table below lists the authoritative names — declare any subset in `installed_*` and run `/context install`, or take the whole conception via `/context accept-all`.
-</context_install>
-
-<substrate_config>
-`.project/config.json` is the substrate bootstrap. Its `root` field declares where every other block, schema, agent, and template lives — closing the GitHub #3 surface where downstream consumers had to assume `.project/`. `naming` aliases canonical block ids to display names (used by `/context view` rendering). `hierarchy` declares legal closure-table edges (parent block → child block via relation_type). `lenses` declares named projections over a target block. `installed_schemas` / `installed_blocks` are the install manifest consumed by `/context install`.
-
-`config.json` and `relations.json` are exempt from `root` redirection — they always live at `.project/` because they are the substrate that defines `root`. All other state lives under `<config.root>/...` per `resolveContextDir(cwd)`. The package ships their schemas in `schemas/` (config.schema.json, relations.schema.json) and resolves them via three-tier search: project override > user override > package-shipped.
-
-The `loadContext(cwd)` SDK returns an mtime-keyed cached snapshot of `{ config, relations, configMtime, relationsMtime }` for one cwd. Consumers must not mutate.
-</substrate_config>
-
-<lens_views>
-Lenses are named projections over a target block. A lens declares `id`, `target` (block name), `relation_type`, `derived_from_field` (optional — synthesizes edges from a per-item field instead of requiring authored edges), `bins` (named groupings), and `render_uncategorized`.
-
-Edges live in `.project/relations.json` as a closure table — each row is `{ parent, child, relation_type }`. `parent` is either a canonical id (hierarchy edges) or a lens.bins value (lens edges); disambiguation lives in `validateRelations`.
-
-The lens-view algorithm: `edgesForLens(lens, items, authoredEdges)` returns synthetic edges (when `derived_from_field` is set) or filtered authored edges (otherwise). `groupByLens(items, lens, lensEdges)` produces a `Map<binName, ItemRecord[]>`. `walkDescendants(parentId, relationType, edges)` traverses the closure table from any parent.
-
-`/context view <lensId>` loads the lens via `loadLensView(cwd, lensId)`, runs `groupByLens`, and renders the result as markdown headings + bullet lines (id + status + title) into the conversation via `renderLensView`. `lens.render_uncategorized: false` omits the uncategorized bucket.
-</lens_views>
-
-<context_lens_curate>
-`/context lens-curate <lensId>` walks items in the lens's target block that have no edge in any declared bin and surfaces bin-assignment suggestions (would-be `relations.json` edge appends) as a follow-up turn. The LLM reads the suggestions and persists the chosen edges via `append-block-item` against `relations.json`. The command itself does not write — curation is a follow-up-turn pattern so the model decides which suggestions to enact.
-</context_lens_curate>
-
-<context_view>
-`/context view <lensId>` renders a configured lens as markdown into the conversation. Bins become headings, items become bullet lines (id + status + title where present). `naming` aliases from config.json are honored for the target block name. Errors (missing config, unknown lens, unreadable target block, no array property in target) surface via `ctx.ui.notify` with severity `error`.
-</context_view>
-
-<substrate_validation>
-`validateRelations(cwd)` (exposed as the `context-validate-relations` tool) checks the closure-table edges in `relations.json` against the config + per-block item snapshots. Diagnostics codes: `edge_unknown_relation_type`, `edge_parent_not_in_bins`, `edge_unresolved_parent`, `edge_unresolved_child`, `edge_parent_wrong_block`, `edge_child_wrong_block`, `edge_cycle_detected`. Returns `{ status: "clean" | "warnings" | "invalid", issues[] }` where each issue carries the offending edge or cycle path.
-
-Two derived substrate tools complement validation: `context-edges-for-lens` returns the materialized `Edge[]` for a named lens (synthetic from `derived_from_field` or filtered authored edges); `context-walk-descendants` returns the transitive descendant id list from a parent under a given relation_type.
-</substrate_validation>
-
-<block_item_reads>
-Item-level reads complement whole-block `read-block` (which is all-or-nothing and caps at the 50KB read limit): `read-block-item` returns one item from a named block by its id (block-scoped — null if absent; distinct from `resolve-item-by-id`, which searches every block by kind-prefixed id). `read-block-page` paginates a block too large to fetch whole — `{ items, total, hasMore }` where `total` is the full item count and pagination uses `offset`/`limit` (defaults 0/50).
-`join-blocks` — one-call cross-block join, EDGE mode (relations.json relation_type, leftEndpoint parent|child) or FIELD mode (shared field value), optional left pre-filter; returns {left, right[]} pairs; replaces N+1 read+resolve.
-</block_item_reads>
-
-<context_status>
-`/context 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 (if installed)
-- Tasks summary (total, by status) — from tasks.json (if installed)
-- Domain entry count — from domain.json (if installed)
-- Verification summary (total, passed, failed) — from verification.json (if installed)
-- Handoff presence — whether handoff.json exists
-- Recent git commits
-- Current phase detection
-</context_status>
-
-<context_add_work>
-`/context 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.
-</context_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>
-
-<context_validate>
-Two separate validators address two concerns:
-
-`/context validate` (the `context-validate` tool) 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).
-
-The `context-validate-relations` tool (see `<substrate_validation>`) validates closure-table edges in `relations.json` — a separate concern from cross-block ID resolution.
-</context_validate>
-
-<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/`, `.project/schemas/`, `.project/phases/`, and `.project/config.json` exist after `/context init`
-- `installed_schemas` / `installed_blocks` declared in `config.json` are reified by `/context install`; `--update` overwrites
-- Block writes validate against schemas — invalid data rejected with specific error
-- `/context status` returns current derived state without errors
-- `/context validate` returns no errors for well-formed cross-block references
-- `context-validate-relations` returns no errors for a well-formed `relations.json`
-- `/context view <lensId>` renders the configured projection; `/context lens-curate <lensId>` surfaces suggestions for uncategorized items
-- `append-block-item` rejects duplicate IDs
-- Schema customizations (field additions, enum changes) take effect on next write
-- A relocated `config.root` reaches every read/write because all path construction routes through `resolveContextDir(cwd)`
-</success_criteria>
-
-*Generated from source by `scripts/generate-skills.js` — do not edit by hand.*

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

@@ -1,47 +0,0 @@
-# Bundled Resources
-
-## schemas/ (9 files)
-
-- `schemas/bootstrap.schema.json`
-- `schemas/config.schema.json`
-- `schemas/layer.schema.json`
-- `schemas/priority.schema.json`
-- `schemas/relations.schema.json`
-- `schemas/severity.schema.json`
-- `schemas/source.schema.json`
-- `schemas/status.schema.json`
-- `schemas/verification-method.schema.json`
-
-## samples/ (31 files)
-
-- `samples/blocks/context-contracts.json`
-- `samples/blocks/conventions.json`
-- `samples/blocks/decisions.json`
-- `samples/blocks/features.json`
-- `samples/blocks/framework-gaps.json`
-- `samples/blocks/issues.json`
-- `samples/blocks/layer-plans.json`
-- `samples/blocks/phase.json`
-- `samples/blocks/rationale.json`
-- `samples/blocks/requirements.json`
-- `samples/blocks/research.json`
-- `samples/blocks/spec-reviews.json`
-- `samples/blocks/story.json`
-- `samples/blocks/tasks.json`
-- `samples/blocks/verification.json`
-- `samples/conception.json`
-- `samples/schemas/context-contracts.schema.json`
-- `samples/schemas/conventions.schema.json`
-- `samples/schemas/decisions.schema.json`
-- `samples/schemas/features.schema.json`
-- `samples/schemas/framework-gaps.schema.json`
-- `samples/schemas/issues.schema.json`
-- `samples/schemas/layer-plans.schema.json`
-- `samples/schemas/phase.schema.json`
-- `samples/schemas/rationale.schema.json`
-- `samples/schemas/requirements.schema.json`
-- `samples/schemas/research.schema.json`
-- `samples/schemas/spec-reviews.schema.json`
-- `samples/schemas/story.schema.json`
-- `samples/schemas/tasks.schema.json`
-- `samples/schemas/verification.schema.json`