@davidorex/pi-context 0.26.0 → 0.28.0

package/skills/pi-context/SKILL.md

@@ -3,7 +3,7 @@ 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,
+  cross-block referential integrity. Use when managing substrate blocks,
   scaffolding project structure, installing block kinds from the packaged samples
   catalog, validating project state, rendering lens views, or adding work items.
 ---
@@ -31,7 +31,7 @@ Update fields on an item in a project block array. Finds by predicate field matc
 |-----------|------|----------|-------------|
 | `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' }) |
+| `match` | object | yes | Fields to match (e.g., { id: 'ISSUE-NNN' }) |
 | `updates` | object | yes | Fields to update (e.g., { status: 'resolved' }) |
 </tool>
 
@@ -48,6 +48,20 @@ Append a closure-table relation (edge: parent, child, relation_type, optional or
 | `ordinal` | integer | no | Optional sibling-ordering within (parent, relation_type) |
 </tool>
 
+<tool name="promote-item">
+Promote a substrate item into another (registered) substrate as a NEW content-addressed item, recording the 'item_derived_from_item' lineage edge in the destination relations.json (parent = the new derived item, child = the source, carrying the source content_hash). The destination write-path mints a fresh oid + content_hash + content object. When the source block's status enum supports it, the source is marked superseded. Preconditions (unresolvable/non-item source, unregistered destination alias, unregistered destination relation_type, refname collision) throw. Pass dryRun to compute the destination without writing.
+
+*Promote an item into another substrate as a derived copy with a lineage edge*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `source` | string | yes | Source item selector (bare refname / <alias>:<refname>) |
+| `destinationSubstrate` | string | yes | Registered destination substrate alias |
+| `newRefname` | string | no | Explicit destination refname (else allocated from the dest block id pattern) |
+| `dryRun` | boolean | no | Compute the destination without writing any channel |
+| `writer` | object | yes | DispatchContext.writer per pi-context/src/dispatch-context.ts. |
+</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.
 
@@ -57,7 +71,7 @@ Append an item to a nested array on a parent-array item in a project block. Sche
 |-----------|------|----------|-------------|
 | `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' }) |
+| `match` | object | yes | Fields to match the parent item (e.g., { id: 'REVIEW-NNN' }) |
 | `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>
@@ -71,7 +85,7 @@ Update fields on a nested-array item inside a parent-array item in a project blo
 |-----------|------|----------|-------------|
 | `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' }) |
+| `match` | object | yes | Fields to match the parent item (e.g., { id: 'REVIEW-NNN' }) |
 | `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' }) |
@@ -86,7 +100,7 @@ Remove items matching a predicate from a top-level array in a project block. Ide
 |-----------|------|----------|-------------|
 | `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' }) |
+| `match` | object | yes | Fields to match (e.g., { id: 'ISSUE-NNN' }) |
 </tool>
 
 <tool name="remove-block-nested-item">
@@ -98,19 +112,19 @@ Remove items matching a predicate from a nested array on a parent-array item in
 |-----------|------|----------|-------------|
 | `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' }) |
+| `match` | object | yes | Fields to match the parent item (e.g., { id: 'REVIEW-NNN' }) |
 | `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 and parse all .json files in a <substrate-dir>/<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') |
+| `subdir` | string | yes | Subdirectory under the substrate dir (e.g., 'phases', 'schemas') |
 </tool>
 
 <tool name="read-block">
@@ -149,21 +163,28 @@ Validate cross-block referential integrity — check that IDs referenced across
 </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 the substrate config.json as structured JSON — vocabulary, lenses, relation_types, status_buckets, display_strings, layers, block_kinds, installed_schemas, installed_blocks. Address ONE registry/map via `registry` (e.g. relation_types) and ONE entry within it via `id` (canonical_id) instead of reading the whole config.
 
 *Read project config — vocabulary, lenses, relation_types, status_buckets*
 
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `registry` | string | no | Address ONE config registry/map by key (e.g. 'relation_types', 'lenses', 'block_kinds', 'status_buckets') |
+| `id` | string | no | With `registry`: address ONE entry within it by canonical_id |
 </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 the agent's own tool surface (all loaded extensions + builtins). Default returns a COMPACT index — one line per tool (name · param-count · one-line description) plus the active set — not the full JSON-schemas. Pass `name` to fetch ONE tool's full descriptor (name + description + parameter JSON-schema + sourceInfo). Index-then-detail pattern.
 
-*Discover available tools — names, params, descriptions, active set*
+*Discover available tools — compact index, or one tool's full descriptor via `name`*
 
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | no | Address ONE tool by name → full descriptor (params schema + sourceInfo) |
 </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.
+Enumerate installable sample block kinds (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*
 
@@ -173,14 +194,14 @@ Enumerate installable sample block kinds (DEC-0037 packaged view): per kind —
 </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 'where are we + what's next' purely from the 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 the substrate bootstrap state for the cwd, purely from the filesystem: '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 user to run /context init <substrate-dir> → /context accept-all → /context install (bootstrap requires user authorization via interactive confirmation). No writes.
 
 *Derive substrate bootstrap state — no-pointer | no-config | not-installed | ready (never throws pre-bootstrap)*
 
@@ -214,17 +235,18 @@ Scoped add / replace / remove of ONE entry in ONE config.json registry (block_ki
 </tool>
 
 <tool name="read-schema">
-Read a substrate schema by name as parsed JSON. Returns null when the schema file is absent.
+Read a substrate schema by name as parsed JSON. Returns null when the schema file is absent. Address ONE property via `path` (dotted/bracket, e.g. properties.tasks.items.properties.status) instead of reading the whole schema.
 
-*Read a block schema as structured JSON*
+*Read a block schema as structured JSON — optionally address one property via `path`*
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `schemaName` | string | yes | Schema name without extension (e.g., 'tasks', 'decisions', 'issues') |
+| `path` | string | no | Address ONE property by dotted/bracket path (e.g. 'properties.tasks.items.properties.status') |
 </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 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. Schema version bumps require a companion migration declaration via write-schema-migration; without one, read/write of items declaring an older schema_version throws version-mismatch. 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)*
 
@@ -236,6 +258,22 @@ Create or replace a substrate block-kind JSON Schema. operation 'create' require
 | `dryRun` | boolean | no | Meta-validate without writing |
 </tool>
 
+<tool name="write-schema-migration">
+Declare a schema version-bump migration into substrate (migrations.json). operation 'create' appends a new declaration; 'replace' overwrites an existing declaration matched by (schemaName, fromVersion); 'remove' drops a declaration. kind='identity' asserts the bump is shape-compatible (no data transform); kind='declarative-transform' carries a TransformSpec of rename/set/delete/coerce operations on dotted JSON paths. The loaded MigrationRegistry resolves the recorded edge at next read/write so block items declaring an older schema_version walk forward without process restart. Requires user authorization via interactive confirmation at the pi-dispatch auth-gate; on confirm, the verified terminal-operator identity is stamped as writer.
+
+*Declare a schema version-bump migration (identity or declarative-transform) into migrations.json*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `operation` | string | yes | create | replace | remove |
+| `schemaName` | string | yes | Schema name without extension (e.g., 'tasks'). |
+| `fromVersion` | string | yes | Source schema semver this migration walks forward FROM. |
+| `toVersion` | string | yes | Destination schema semver this migration produces. Must differ from fromVersion. Ignored for operation=remove. |
+| `kind` | string | no | identity | declarative-transform. Required for operation=create/replace; ignored for remove. |
+| `transform` | unknown | no | TransformSpec body — required when kind='declarative-transform'; forbidden when kind='identity'. Accepts a JSON string. |
+| `writer` | object | yes | DispatchContext.writer per pi-context/src/dispatch-context.ts. |
+</tool>
+
 <tool name="context-init">
 Initialize the substrate dir (bootstrap pointer + dirs only; run accept-all + install to populate).
 
@@ -243,7 +281,7 @@ Initialize the substrate dir (bootstrap pointer + dirs only; run accept-all + in
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `contextDir` | string | yes | Substrate dir name (e.g. .project). Required per DEC-0015 — no default. |
+| `contextDir` | string | yes | Substrate dir name (e.g. .context). Required — no default. |
 </tool>
 
 <tool name="context-accept-all">
@@ -253,6 +291,37 @@ Adopt the canonical packaged conception (samples/conception.json) as this substr
 
 </tool>
 
+<tool name="context-switch">
+Flip the bootstrap pointer to a different substrate dir (parallel to git switch). Default: flip to an existing substrate at target_dir (requires config.json present). create_new=true: bootstrap a fresh substrate at target_dir AND flip in one operation. to_previous=true: flip back to the pointer's previous_contextDir (target_dir ignored).
+
+*Switch the bootstrap pointer to a different substrate dir*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `target_dir` | string | yes | Substrate dir name to switch to (e.g. '.context'). Required for default + create_new modes; ignored for to_previous mode. |
+| `create_new` | boolean | no | When true, bootstrap target_dir as a fresh substrate AND flip the pointer in one operation (parallel to 'git switch -c <branch>'). Default false (flip to existing substrate; fails if target_dir lacks config.json). |
+| `to_previous` | boolean | no | When true, flip the pointer back to its previous_contextDir (parallel to 'git switch -'). Requires the pointer to carry a previous_contextDir (a prior switch must have populated it). When true, target_dir is ignored. |
+| `writer` | object | no | DispatchContext.writer — stamped by auth-gate on operator confirm; in-body trusts the stamped value. |
+</tool>
+
+<tool name="context-list">
+Enumerate top-level dirs under cwd containing a config.json (switchable substrates). Marks the active one with isActive=true. Read-only.
+
+*List switchable substrate dirs under cwd*
+
+</tool>
+
+<tool name="context-archive">
+Move a non-active substrate dir to archive/<dir>/. Refuses to archive the active substrate (the dir the bootstrap pointer currently names) or to clobber an existing archive/<dir>/.
+
+*Archive a non-active substrate dir to archive/<dir>/*
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `target_dir` | string | yes | Substrate dir name to archive (e.g. '.project'). Refused if it is the active substrate. |
+| `writer` | object | no | DispatchContext.writer — stamped by auth-gate on operator confirm. |
+</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.
 
@@ -267,13 +336,13 @@ Filter the array items of a block by a single-field predicate (eq / neq / in / m
 </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.
+Look up the block, array key, and item payload for a given ID across all blocks in the substrate dir. 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 |
+| `id` | string | yes | Kind-prefixed ID, e.g., DEC-NNNN / FEAT-NNN / FGAP-NNN / ISSUE-NNN |
 </tool>
 
 <tool name="read-block-item">
@@ -284,7 +353,7 @@ Read a single item from a named block by its id — returns the item or null. Bl
 | 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') |
+| `id` | string | yes | Item id within the block (e.g., 'TASK-NNN') |
 </tool>
 
 <tool name="read-block-page">
@@ -300,7 +369,7 @@ Paginate a block's items: returns { items, total, hasMore }. offset default 0, l
 </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. 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*
 
@@ -389,7 +458,7 @@ Find all closure-table edges incident on an item id (inbound, outbound, or both)
 </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 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. Substrate primitive serving harness-confined dispatch.
 
 *Compose ContextBundle for unit + context-contract-declared bundle_relation_types*
 
@@ -401,7 +470,7 @@ Compose a ContextBundle for a work-unit by reading its context-contract (by unit
 </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 and return the materialized RoadmapView (phases, lens-views, status rollup, milestone resolution, scoped phase_depends_on edges, topo-ordered phaseOrder + cycles). Phase ordering lives in relations.json with relation_type='phase_depends_on'.
 
 *Load a roadmap by id*
 
@@ -443,23 +512,23 @@ List every roadmap in <config.root>/roadmap.json with id, title, optional status
 <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`
+Subcommands: `init`, `switch`, `list`, `archive`, `install`, `accept-all`, `view`, `lens-curate`, `roadmap-list`, `roadmap-view`, `roadmap-validate`, `status`, `add-work`, `validate`, `help`
 </command>
 
 </commands_reference>
 
 <events>
-`session_start`
+`session_start`, `before_agent_start`, `resources_discover`
 </events>
 
 <bundled_resources>
-9 schemas, 31 samples bundled.
+11 schemas, 34 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>`.
+Names valid for the `installed_blocks` array in `<substrate-dir>/config.json`. Install with `/context install <block>`.
 
 | Block | Source File |
 |-------|-------------|
@@ -478,12 +547,13 @@ Names valid for the `installed_blocks` array in `.project/config.json`. Install
 | `context-contracts` | `samples/blocks/context-contracts.json` |
 | `phase` | `samples/blocks/phase.json` |
 | `story` | `samples/blocks/story.json` |
+| `work-orders` | `samples/blocks/work-orders.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>`.
+Names valid for the `installed_schemas` array in `<substrate-dir>/config.json`. Schemas back block validation; install with `/context install <schema>`.
 
 | Schema | Source File |
 |--------|-------------|
@@ -502,6 +572,7 @@ Names valid for the `installed_schemas` array in `.project/config.json`. Schemas
 | `context-contracts` | `samples/schemas/context-contracts.schema.json` |
 | `phase` | `samples/schemas/phase.schema.json` |
 | `story` | `samples/schemas/story.schema.json` |
+| `work-orders` | `samples/schemas/work-orders.schema.json` |
 
 </installable_schemas>
 
@@ -511,28 +582,29 @@ Names valid for the `installed_schemas` array in `.project/config.json`. Schemas
 
 | 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? |
+| `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?, oid?, content_hash?, content_parent? |
+| `framework-gaps` | Framework Gaps | `gaps` | id, title, status (string (identified|accepted|in-progress|closed|wontfix|superseded_by)), priority? (string (P0|P1|P2|P3)), package, layer? (string (L1|L2|L3|L4|L5)), description, evidence (array), impact, canonical_vocabulary?, proposed_resolution, related_features? (array), related_decisions? (array), related_issues? (array), created_by, created_at, closed_by?, closed_at?, oid?, content_hash?, content_parent? |
+| `tasks` | Tasks | `tasks` | id, description, status (string (planned|in-progress|completed|blocked|cancelled)), files? (array), acceptance_criteria? (array), assigned_agent?, notes?, oid?, content_hash?, content_parent? |
+| `verification` | Verification | `verifications` | id, status (string (passed|failed|partial|skipped)), method (string (command|inspect|test)), evidence?, timestamp?, criteria_results? (array), oid?, content_hash?, content_parent? |
+| `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?, oid?, content_hash?, content_parent? |
+| `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?, oid?, content_hash?, content_parent? |
+| `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?, oid?, content_hash?, content_parent? |
+| `rationale` | Design Rationale | `rationales` | id, title, narrative, phase? (integer), oid?, content_hash?, content_parent? |
+| `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?, oid?, content_hash?, content_parent? |
+| `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, oid?, content_hash?, content_parent? |
+| `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)), oid?, content_hash?, content_parent? |
+| `conventions` | Conventions | `rules` | id, description, enforcement (string (lint|test|review|manual)), severity (string (error|warning|info)), oid?, content_hash?, content_parent? |
+| `context-contracts` | Context contracts | `contracts` | id, unit_kind, bundle_relation_types (array), description?, notes?, created_by, created_at, modified_by?, modified_at?, oid?, content_hash?, content_parent? |
+| `phase` | Phases | `phases` | id, name, intent, goal?, status (string (planned|in-progress|completed)), success_criteria? (array), specs? (array), artifacts_produced? (array), oid?, content_hash?, content_parent? |
+| `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?, oid?, content_hash?, content_parent? |
+| `work-orders` | Work Orders | `work_orders` | id, title, status (string (proposed|in-progress|real-check-passed|real-check-failed|completed|cancelled)), target_agent, input_contract (object), context_blocks (array), output_contract (object), scope (object), real_check_criteria (object), description?, created_by?, created_at?, modified_by?, modified_at?, oid?, content_hash?, content_parent? |
 
 **Status Enums:**
 
 | Block | Field | Values |
 |-------|-------|--------|
 | `decisions` | `status` | open, enacted, superseded |
-| `framework-gaps` | `status` | identified, accepted, in-progress, closed, wontfix |
+| `framework-gaps` | `status` | identified, accepted, in-progress, closed, wontfix, superseded_by |
 | `framework-gaps` | `priority` | P0, P1, P2, P3 |
 | `framework-gaps` | `layer` | L1, L2, L3, L4, L5 |
 | `tasks` | `status` | planned, in-progress, completed, blocked, cancelled |
@@ -557,23 +629,30 @@ Names valid for the `installed_schemas` array in `.project/config.json`. Schemas
 | `conventions` | `severity` | error, warning, info |
 | `phase` | `status` | planned, in-progress, completed |
 | `story` | `status` | proposed, ready, in-progress, in-review, complete, blocked |
+| `work-orders` | `status` | proposed, in-progress, real-check-passed, real-check-failed, completed, cancelled |
 
 </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.
+pi-context manages structured project state in the substrate directory — 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.
+Blocks are JSON files under the substrate root (one per block kind, each an array of items). 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 substrate-dir name. 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.
+
+Each item in an identity-bearing block carries a three-layer identity, not a refname alone: `id` (the mutable human label, e.g. a kind-prefixed refname), `oid` (a content-independent 32-hex identity minted once at the item's birth and immutable thereafter, salted by the substrate's `substrate_id`), `content_hash` (a SHA-256 over the item's content projection — the item minus its metadata fields — so identical content deduplicates), and `content_parent` (the prior version's `content_hash`, forming a per-item version chain that advances only when content actually changed). A write carrying a different incoming `oid` is rejected. Identity stamping is a no-op unless the block's array subschema declares all three identity fields, scoping content-addressing to canonical schemas and leaving bespoke/test schemas untouched.
 </block_files>
 
+<content_addressing>
+On a stamping write the item's content projection (a shallow copy with the metadata fields removed) is persisted to `<substrate-dir>/objects/<content_hash>.json` — a content-addressed object store (idempotent, atomic tmp+rename; identical content yields a byte-identical file). The store is git-tracked: it is the integrity/version store, and gitignoring it would lose pinning. Object persistence is deferred until after the whole block clears schema validation, so a validation failure never orphans an object. The metadata fields excluded from the content hash are the mandatory floor `{id, oid, content_hash, content_parent}` (never hashable, never pullable into the hash by an override) plus a discretionary set (the author fields and `closed_by`/`closed_at`); a schema's item subschema may redefine the discretionary set via `x-identity.metadata_fields`, but the floor is always unioned in.
+</content_addressing>
+
 <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 <substrate-dir>` creates the substrate skeleton: the `.pi-context.json` bootstrap pointer (declaring the chosen substrate-dir name) plus the substrate root and its `schemas/` directory. Nothing is imposed — no `config.json`, no schemas, and no starter blocks are written (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>
@@ -587,17 +666,31 @@ The installable catalog IS the packaged conception (`samples/conception.json`):
 </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`.
+`<substrate-dir>/config.json` is the substrate bootstrap. Its `root` field declares where every other block, schema, agent, and template lives — consumers resolve that dir via the `.pi-context.json` pointer plus `config.root`, never by assuming a fixed directory name. Its `substrate_id` field is the per-substrate root identity (pattern `sub-` followed by 16 hex), minted once and immutable on disk; it salts oid minting and identifies the substrate in the project-root registry. `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.
+`config.json` and `relations.json` are exempt from `config.root` redirection — they always live at the substrate-dir root (the dir chosen at bootstrap, resolved via the `.pi-context.json` pointer, suggested `.context`) because they are the substrate that defines `root`. The substrate-dir root is whatever was chosen at bootstrap, not necessarily `.project`. 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>
 
+<cross_substrate>
+A project can carry multiple substrates. The `.pi-context.json` bootstrap pointer names the single ACTIVE substrate dir; a separate project-root, git-tracked `.pi-context-registry.json` enumerates ALL substrates — a version plus `substrates: { <substrate_id>: { dir, aliases[] } }`. `resolveSubstrateDir(cwd, substrate_id)` and `resolveAlias(cwd, alias)` look up the registry and return null on a clean miss.
+
+`resolveRef(cwd, ref)` classifies any endpoint into one of four statuses: `active` — resolved in the active substrate's index (a bare oid/refname, or any lens_bin endpoint, which is always active without an item lookup); `foreign` — a structured endpoint carrying a `substrate_id`, or an `<alias>:<refname>` string whose alias is registered, resolved in the foreign substrate's index; `dangling` — a locator naming a registered substrate where the oid/refname is absent; `unregistered` — a `substrate_id` or alias the registry does not carry. A string with a NON-leading `:` (the parse gates on `colon > 0`) is first attempted as an `<alias>:<refname>` parse; a leading-colon string is not alias-parsed.
+
+Source-of-truth-drift invariant: `validateContext` requires the active `config.substrate_id` to have a registry entry whose `dir` resolves to the active substrate. A mismatch yields `substrate_id_registry_mismatch`; a missing entry yields `substrate_id_unregistered`.
+</cross_substrate>
+
+<schema_versioning>
+Schemas are draft-07 JSON-Schema, one per block kind, under `<substrate-dir>/schemas/`. Package-shipped substrate-singleton schemas carry a `pi-context://schemas/<name>` `$id` plus a `version`. `<substrate-dir>/migrations.json` is the per-substrate schema-version migration registry. A schema `version` bump REQUIRES a companion migration declared via the `write-schema-migration` tool; without one, reading or writing an item that declares an older `schema_version` throws a version mismatch. Migration kinds are `identity` (shape-compatible, no transform) or `declarative-transform` (a TransformSpec of rename/set/delete/coerce on dotted paths). The loaded registry resolves the migration edge at the next read/write, so items walk forward without a process restart. A `block:<name>` reference resolves to `<contextDir>/schemas/<name>.schema.json`.
+</schema_versioning>
+
 <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`.
+Edges live in `<substrate-dir>/relations.json` as a closure table — each row is `{ parent, child, relation_type, ordinal? }`. `relation_type` is a lens id, a hierarchy edge type, or a registered `relation_types[].canonical_id`; `ordinal` orders siblings within `(parent, relation_type)`. Endpoints (both `parent` and `child`) are dual-form: a legacy string (a canonical id, a lens bin name, or an `<alias>:<refname>` cross-substrate sentinel; disambiguation lives in `validateRelations`), OR a structured item endpoint `{ kind: "item", oid, refname?, substrate_id?, content_hash? }` where a present `substrate_id` marks a foreign endpoint and `content_hash` is carried for drift detection, OR a structured lens-bin endpoint `{ kind: "lens_bin", bin }` — a virtual parent that never resolves to an item.
+
+The single-form rule: ALL inter-item relationships are closure-table edges. Embedded nested id-bearing arrays and FK-as-field are forbidden — a nested id-bearing array in a schema is flagged `nested_id_bearing_array` by `validateContext` with the remediation "promote to a top-level entity + membership edge". Containment is a membership edge carrying `ordinal`; the nested id-bearing array → top-level entity block + ordinal-bearing membership edges promotion is performed by the canonicalizer (the context-dir-migration `canonicalizeSubstrate` machinery, run as a repo-side migration script under `scripts/migration/` — not a packaged pi-context tool). (Distinct from the `promote-item` tool, which is a cross-substrate derivation: it promotes a substrate item INTO another registered substrate as a new content-addressed item, recording an `item_derived_from_item` lineage edge in the destination.)
 
 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.
 
@@ -613,7 +706,9 @@ The lens-view algorithm: `edgesForLens(lens, items, authoredEdges)` returns synt
 </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.
+`validateRelations(cwd)` (exposed as the `context-validate-relations` tool) checks the closure-table edges in `relations.json` against the config + per-block item snapshots, with the `resolveRef` hook classifying foreign endpoints. 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.
+
+`validateContext(cwd)` (the `context-validate` tool) layers the registry/identity invariants over cross-block referential integrity: `substrate_id_unregistered` and `substrate_id_registry_mismatch` (the source-of-truth-drift guard on the active substrate), `edge_endpoint_dangling` and `edge_endpoint_unregistered` (a structured endpoint naming a registered-but-absent or unregistered substrate), and `nested_id_bearing_array` (a schema embedding an id-bearing array instead of using a membership edge). Config-declared `invariants[]` and registered lens-validators are checked in the same pass.
 
 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>
@@ -647,21 +742,20 @@ Item-level reads complement whole-block `read-block` (which is all-or-nothing an
 </duplicate_detection>
 
 <context_validate>
-Two separate validators address two concerns:
+Two surfaces address related concerns. Cross-block referential integrity is EDGE-based: there are no per-block inline-FK field checks (no `task.phase`, `task.depends_on`, `decision.phase`, `gap.resolved_by`, `requirement.traces_to`/`depends_on`, `verification.target`, `rationale.related_decisions` scans) — `relations.json` closure-table edges are the sole reference surface.
 
-`/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
+`/context validate` (the `context-validate` tool → `validateContext`) is the project-wide check. It runs:
+- Source-of-truth drift: when the active `config.substrate_id` is set, the project-root `.pi-context-registry.json` must carry an entry whose dir resolves to the active substrate dir (`substrate_id_unregistered`, `substrate_id_registry_mismatch`).
+- Edge integrity: each edge's `parent`/`child` is classified via the unified id index across substrates — an endpoint naming an unregistered substrate alias/id errors (`edge_endpoint_unregistered`), one that resolves to no item errors (`edge_endpoint_dangling`); a `relation_type` absent from `config.relation_types[]` errors; when a relation_type declares `source_kinds`/`target_kinds`, an endpoint whose resolved block kind is outside the (non-`*`) declared set errors.
+- Cycle detection: delegated to `validateRelations`; only its `edge_cycle_detected` diagnostics are merged in.
+- Config-declared invariants: `requires-edge` and `status-consistency` classes are enforced generically from `config.invariants[]` DATA — no block/status/relation_type vocabulary is hardcoded in source; each invariant's emitted code is its own `inv.id`.
+- Status-vocabulary: an item `status` value with no key in the declared vocabulary is a warning (`status_unknown_value`).
+- Nested id-bearing array: a schema array at nesting depth ≥ 1 whose item shape carries an `id` is a warning to promote it to a top-level entity + membership edge (`nested_id_bearing_array`).
+- Lens validators: every validator registered via `registerLensValidator` is dispatched and its issues merged; a throwing validator surfaces as a warning (`lens_validator_failed:<name>`).
 
-Returns errors (broken dependency references) and warnings (unresolved cross-references).
+Returns issues with `severity` error/warning; status is `invalid` (any error), `warnings`, or `clean`.
 
-The `context-validate-relations` tool (see `<substrate_validation>`) validates closure-table edges in `relations.json` — a separate concern from cross-block ID resolution.
+The lower-level `context-validate-relations` tool (→ `validateRelations`, see `<substrate_validation>`) checks the closure-table edges in `relations.json` in isolation: unregistered relation_type (`edge_unknown_relation_type`), lens-bin parent not among a lens's bins (`edge_parent_not_in_bins`), unresolved/wrong-block parent or child (`edge_unresolved_parent`, `edge_unresolved_child`, `edge_parent_wrong_block`, `edge_child_wrong_block`), and cycles (`edge_cycle_detected`).
 </context_validate>
 
 <update_check>
@@ -669,7 +763,7 @@ On `session_start`, checks npm registry for newer versions of `@davidorex/pi-pro
 </update_check>
 
 <success_criteria>
-- `.project/`, `.project/schemas/`, `.project/phases/`, and `.project/config.json` exist after `/context init`
+- `<substrate-dir>/`, `<substrate-dir>/schemas/`, and the `.pi-context.json` bootstrap pointer exist after `/context init <substrate-dir>` (init is skeleton-only: no `config.json`, no schemas, no blocks until accept-all + install). Phases are not a directory — they live as an in-block array under `phase.json` (plural `phases` key); there is no `phases/` dir.
 - `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

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

@@ -1,10 +1,12 @@
 # Bundled Resources
 
-## schemas/ (9 files)
+## schemas/ (11 files)
 
 - `schemas/bootstrap.schema.json`
 - `schemas/config.schema.json`
+- `schemas/context-registry.schema.json`
 - `schemas/layer.schema.json`
+- `schemas/migrations.schema.json`
 - `schemas/priority.schema.json`
 - `schemas/relations.schema.json`
 - `schemas/severity.schema.json`
@@ -12,7 +14,7 @@
 - `schemas/status.schema.json`
 - `schemas/verification-method.schema.json`
 
-## samples/ (31 files)
+## samples/ (34 files)
 
 - `samples/blocks/context-contracts.json`
 - `samples/blocks/conventions.json`
@@ -29,7 +31,9 @@
 - `samples/blocks/story.json`
 - `samples/blocks/tasks.json`
 - `samples/blocks/verification.json`
+- `samples/blocks/work-orders.json`
 - `samples/conception.json`
+- `samples/migrations.json`
 - `samples/schemas/context-contracts.schema.json`
 - `samples/schemas/conventions.schema.json`
 - `samples/schemas/decisions.schema.json`
@@ -45,3 +49,4 @@
 - `samples/schemas/story.schema.json`
 - `samples/schemas/tasks.schema.json`
 - `samples/schemas/verification.schema.json`
+- `samples/schemas/work-orders.schema.json`