@davidorex/pi-context 0.26.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## [0.3.0] - 2026-03-18
+
+## [0.2.0] - 2026-03-17
+
+### Added
+- `/project init` command to scaffold `.project/` directory with default schemas and empty block files
+- Update check on session start for `@davidorex/pi-project-workflows` meta-package
+- Monorepo integration as workspace package
+
+## [0.1.0] - 2026-03-14
+
+### Added
+- Block CRUD: `readBlock`, `writeBlock`, `appendToBlock`, `updateItemInBlock` with atomic writes (tmp + rename)
+- Write-time schema validation via AJV against `.project/schemas/*.schema.json`
+- `ValidationError` class with structured error reporting
+- Post-step block validation: `snapshotBlockFiles`, `validateChangedBlocks`, `rollbackBlockFiles`
+- Derived project state: `projectState(cwd)` computes all metrics dynamically (source files, tests, phases, block summaries, agents, workflows, schemas, templates, recent commits)
+- Block discovery: `availableBlocks(cwd)`, `availableSchemas(cwd)`, `findAppendableBlocks(cwd)`
+- Generic block tools: `append-block-item` and `update-block-item` (work with any user-defined block type)
+- `/project` command with `status` and `add-work` subcommands
+- `PROJECT_DIR` and `SCHEMAS_DIR` constants as single source of truth for `.project/` path

package/README.md

@@ -0,0 +1,195 @@
+# pi-context
+
+Schema-driven project state management for [Pi](https://github.com/badlogic/pi-mono).
+
+Schemas are the design language. You define what your project tracks by writing JSON Schemas, and the entire system — tools, validation, derived state, workflow integration — adapts automatically. Drop a new `.schema.json` file into `.project/schemas/` and it instantly becomes an addressable block type with write-time validation, discovery, and generic CRUD tooling. No code changes.
+
+## Install
+
+```bash
+pi install npm:@davidorex/pi-context
+```
+
+## Getting Started
+
+```
+/context init       # create the empty substrate skeleton
+/context install    # reconcile .project/ against installed_* lists in config.json
+```
+
+`init` is intentionally minimal: it writes the bootstrap pointer + substrate/schemas dirs only — no config, no schemas, no starter blocks (DEC-0011 ship-no-defaults). Adopt the packaged conception with `/context accept-all` (writes `config.json` from `samples/conception.json`), or hand-declare `config.json`'s `installed_schemas` / `installed_blocks`, then run `/context install` (opt-in install ceremony, idempotent, `--update` overwrites). The package-shipped samples catalog (`samples/blocks/` and `samples/schemas/`, per DEC-0037) is the source.
+
+## How It Works
+
+Project data lives under the substrate root (the dir chosen at init and recorded in `config.json`'s `root` field by accept-all; no default is shipped — DEC-0015) as typed JSON block files. Each block has a corresponding JSON Schema that defines its shape. All writes — whether from tools, workflows, or agents — are validated against the schema before data hits disk. Invalid data is never persisted.
+
+After `/context init` the substrate skeleton is just the dirs (no config, no schemas, no blocks):
+
+```
+.project/
+  schemas/                    — empty until accept-all + install
+```
+
+After `/context accept-all` (writes `config.json` from the packaged conception) + `/context install` (with declared entries) and any user authoring, the directory typically grows:
+
+```
+.project/
+  config.json                 — substrate bootstrap (always at .project/, exempt from root redirection)
+  relations.json              — closure-table edges (always at .project/, exempt from root redirection)
+  schemas/<name>.schema.json  — installed from samples/schemas/, plus any user-authored schemas
+  <name>.json                 — installed from samples/blocks/, plus any user-authored blocks
+```
+
+The schema is the contract. When pi-workflows agents produce output that writes to project blocks, the schema enforces the shape. When `/context add-work` extracts items from conversation, the schema constrains what gets written. When `contextState()` derives block summaries, it reads the typed data the schemas guarantee.
+
+**Tools registered:** the tool surface grows with the package — read the generated `skills/pi-context/SKILL.md` for the current set, or call the `list-tools` tool at runtime (in-pi) / `grep pi.registerTool packages/pi-context/src/index.ts` (source). Families: block CRUD (read/write/append/update/remove, top-level + nested), item-level read (`read-block-item`, `read-block-page`), query (`filter-block-items`, `resolve-item(s)-by-id`, `find-references`, `walk-ancestors`, `context-walk-descendants`), substrate write (`append-relation`, `amend-config`, `write-schema`, `rename-canonical-id`), discovery/introspection (`read-config`, `read-schema`, `read-samples-catalog`, `list-tools`, `context-current-state`), lifecycle (`context-init`, `context-accept-all`, `context-status`, `context-validate`, `context-validate-relations`, `complete-task`).
+
+**Commands registered:**
+- `/context init <dir>` — bootstrap pointer + substrate/schemas dirs only (no config, no defaults)
+- `/context accept-all` — adopt `samples/conception.json` as `config.json` (idempotent; never overwrites an existing config)
+- `/context install [--update]` — reconcile the substrate against `installed_schemas` / `installed_blocks` in `config.json` by copying assets from the samples catalog (skip-if-exists by default; `--update` overwrites)
+- `/context view <lensId>` — render a configured lens (groupByLens projection) into the conversation as markdown
+- `/context lens-curate <lensId>` — surface bin-assignment suggestions for uncategorized items as a follow-up turn; the LLM persists chosen edges via `append-block-item` against `relations.json`
+- `/context status` — derived project state (source metrics, test counts, block summaries, git state)
+- `/context add-work` — extract structured items from conversation into typed blocks
+- `/context validate` — cross-block referential integrity checks
+
+## Source Files
+
+| File | Purpose |
+|------|---------|
+| `src/index.ts` | Extension entry point — tool and command registration |
+| `src/block-api.ts` | Block CRUD: `readBlock`, `writeBlock`, `appendToBlock`, `updateItemInBlock`, `appendToNestedArray`, `updateNestedArrayItem`, `removeFromBlock`, `removeFromNestedArray`, `readBlockDir` |
+| `src/schema-validator.ts` | AJV wrapper: `validate`, `validateFromFile`, `ValidationError` |
+| `src/block-validation.ts` | Post-step validation: `snapshotBlockFiles`, `validateChangedBlocks`, `rollbackBlockFiles` |
+| `src/context-sdk.ts` | Derived state + cross-block resolver: `contextState`, `availableBlocks`, `availableSchemas`, `findAppendableBlocks`, `validateContext`, `buildIdIndex`, `resolveItemById`, `completeTask`. Re-exports the substrate API from `context.ts` (config/relations loaders, lens algorithms, validators, `resolveContextDir`) so existing consumers get one import surface. |
+| `src/context.ts` | Substrate bootstrap: `loadConfig`, `loadRelations`, `loadContext` (mtime-keyed cache), `resolveContextDir(cwd)` (the `config.root` resolver every path helper routes through), the lens algorithms (`edgesForLens`, `synthesizeFromField`, `walkDescendants`, `groupByLens`, `listUncategorized`, `displayName`), `validateRelations`. Type exports: `ConfigBlock`, `HierarchyDecl`, `LensSpec`, `Edge`, `ItemRecord`, `ContextData`, `SubstrateValidationIssue`, `SubstrateValidationResult`, `CurationSuggestion`. |
+| `src/lens-view.ts` | Lens-view consumption surface — pure functions for `/context view` + `/context lens-curate`: `loadLensView`, `renderLensView`, `buildCurationSuggestions`, `validateContextRelations`, `edgesForLensByName`, `walkLensDescendants`. |
+| `src/context-dir.ts` | Path-builders that route through `resolveContextDir(cwd)`: `schemasDir`, `schemaPath`, `agentsDir`, `contextTemplatesDir`. |
+| `src/update-check.ts` | Checks for updates to `@davidorex/pi-project-workflows` on session start |
+
+## API
+
+### Block I/O (`src/block-api.ts`)
+
+```typescript
+readBlock(cwd: string, blockName: string): unknown
+readBlockDir(cwd: string, subdir: string): unknown[]
+writeBlock(cwd: string, blockName: string, data: unknown): void
+appendToBlock(cwd: string, blockName: string, arrayKey: string, item: unknown): void
+updateItemInBlock(cwd: string, blockName: string, arrayKey: string, predicate, updates): void
+appendToNestedArray(cwd, blockName, parentArrayKey, parentPredicate, nestedArrayKey, item): void
+updateNestedArrayItem(cwd, blockName, parentArrayKey, parentPredicate, nestedArrayKey, nestedPredicate, updates): void
+removeFromBlock(cwd, blockName, arrayKey, predicate): { removed: number }
+removeFromNestedArray(cwd, blockName, parentArrayKey, parentPredicate, nestedArrayKey, nestedPredicate): { removed: number }
+```
+
+All writes are atomic (tmp file + rename) and serialised per block via `withBlockLock`. If a schema exists for the block, validation runs before the write — invalid data is never persisted. `update*` operations throw on no-match; `remove*` operations are idempotent (`{ removed: 0 }` on no-match).
+
+### Schema Validation (`src/schema-validator.ts`)
+
+```typescript
+validate(schema: Record<string, unknown>, data: unknown, label: string): unknown
+validateFromFile(schemaPath: string, data: unknown, label: string): unknown
+```
+
+Throws `ValidationError` with structured AJV error details on failure.
+
+### Derived State + Cross-Block Resolver (`src/context-sdk.ts`)
+
+```typescript
+contextState(cwd: string): ContextState
+availableBlocks(cwd: string): BlockInfo[]
+availableSchemas(cwd: string): string[]
+findAppendableBlocks(cwd: string): Array<{ block, arrayKey, schemaPath }>
+validateContext(cwd: string): { status: "clean" | "warnings" | "invalid"; issues: ValidationIssue[] }
+buildIdIndex(cwd: string): Map<string, ItemLocation>
+resolveItemById(cwd: string, id: string): ItemLocation | null
+completeTask(cwd, taskId, verificationId): CompleteTaskResult
+```
+
+`contextState()` computes everything fresh on each call — no cache, no stale data. `buildIdIndex` / `resolveItemById` enforce kind-prefix consistency (a `DEC-` id found in a non-decisions block throws), so the cross-block-reference plumbing in pi-jit-agents and pi-workflows can rely on the prefix invariant.
+
+### Substrate API (`src/context.ts`, re-exported from `src/context-sdk.ts`)
+
+```typescript
+// Bootstrap loaders
+loadConfig(cwd: string): ConfigBlock | null
+loadRelations(cwd: string): Edge[]
+loadContext(cwd: string): ContextData            // mtime-keyed cached snapshot
+resolveContextDir(cwd: string): string           // resolves config.root, falls back to the bootstrap pointer
+
+// Lens algorithms (pure, callable directly with loaded inputs)
+synthesizeFromField(lens: LensSpec, items: ItemRecord[]): Edge[]
+edgesForLens(lens: LensSpec, items: ItemRecord[], authoredEdges: Edge[]): Edge[]
+walkDescendants(parentId: string, relationType: string, edges: Edge[]): string[]
+groupByLens(items: ItemRecord[], lens: LensSpec, lensEdges: Edge[]): Map<string, ItemRecord[]>
+listUncategorized(lens, grouped): { uncategorized: ItemRecord[]; suggestionTemplate: ... }
+
+// Validation + display
+validateRelations(cwd, options?): SubstrateValidationResult
+displayName(canonicalId: string, naming: Record<string, string> | undefined): string
+```
+
+`config.root` is the substrate's "where do I live" answer — block-api, schemas-discovery, phase-discovery, and every other path consumer route through `resolveContextDir(cwd)` so a relocated root reaches the runtime instead of being trapped in the SDK. `config.json` and `relations.json` themselves are exempt — they always live at `.project/` because they are the substrate that defines `root`.
+
+### Lens View Consumption (`src/lens-view.ts`)
+
+```typescript
+loadLensView(cwd: string, lensId: string): LoadedLensView | { error: string }
+renderLensView(view: LoadedLensView, naming: Record<string, string> | undefined): string
+buildCurationSuggestions(view: LoadedLensView): string
+validateContextRelations(cwd: string): SubstrateValidationResult
+edgesForLensByName(cwd: string, lensId: string): Edge[] | { error: string }
+walkLensDescendants(cwd: string, parentId: string, relationType: string): string[]
+```
+
+Pure functions consumed by the `/context view`, `/context lens-curate`, `context-edges-for-lens`, `context-walk-descendants`, and `context-validate-relations` shells in `index.ts`. Tests call them directly without an `ExtensionCommandContext`.
+
+### Substrate Path Surface (`src/context-dir.ts`)
+
+```typescript
+resolveContextDir(cwd): string          // resolves config.root; falls back to the bootstrap pointer
+schemasDir(cwd): string                 // <cwd>/<resolveContextDir>/schemas
+schemaPath(cwd, blockName): string      // <cwd>/<resolveContextDir>/schemas/<name>.schema.json
+agentsDir(cwd): string                  // <cwd>/<resolveContextDir>/agents
+contextTemplatesDir(cwd): string        // <cwd>/<resolveContextDir>/templates
+```
+
+Canonical builders consumed across pi-jit-agents and pi-workflows for any substrate-root path construction. All path-builders route through `resolveContextDir(cwd)` so a relocated root reaches every consumer. Replace inline `path.join(cwd, ".project", ...)` with these.
+
+### Block Validation (`src/block-validation.ts`)
+
+Used by workflow executors for post-step integrity checks:
+
+```typescript
+snapshotBlockFiles(cwd: string): BlockSnapshot   // Map<string, BlockFileSnapshot>
+validateChangedBlocks(cwd: string, snapshot: BlockSnapshot): void
+rollbackBlockFiles(cwd: string, snapshot: BlockSnapshot): string[]
+```
+
+## For LLMs
+
+When working with this extension:
+
+- **Read `src/context-sdk.ts`** to understand what project state is available and how it's computed
+- **Read `src/block-api.ts`** to understand the CRUD operations and validation behavior
+- **Read `src/index.ts`** to see tool parameter schemas and command handler logic
+- Use the `append-block-item` tool to add items — it handles schema validation, duplicate checking, and atomic writes
+- Use the `update-block-item` tool with a `match` predicate (e.g., `{ id: "gap-123" }`) and `updates` object
+- Block schemas define the contract — consult `.project/schemas/*.schema.json` to understand what fields are required
+- `contextState(cwd)` is the single source of truth for project metrics — prefer it over manual filesystem inspection
+
+## Tests
+
+```bash
+npm test
+```
+
+Runs `tsx --test src/*.test.ts`. Test files: `block-api.test.ts`, `block-tools.test.ts`, `schema-validator.test.ts`, `context-sdk.test.ts`.
+
+## Development
+
+Part of the [`pi-project-workflows`](../../README.md) monorepo. All four packages (pi-context, pi-jit-agents, pi-workflows, pi-behavior-monitors) plus the pi-project-workflows meta-package are versioned in lockstep (current version in each `package.json`).
+
+`npm run build` compiles TypeScript to `dist/` via `tsc`. The package ships `dist/`, not `src/` — the `pi.extensions` entry point is `./dist/index.js`.

package/dist/block-api.d.ts

@@ -0,0 +1,328 @@
+import type { DispatchContext } from "./dispatch-context.js";
+/**
+ * Read and parse a .project/{blockName}.json file.
+ * Throws if the file does not exist or contains invalid JSON.
+ *
+ * Optional filter: when provided, returns a shallow copy of the block with only
+ * matching items in the specified array key. Non-array or missing keys return the
+ * block unchanged. The filter is applied after parsing, before returning.
+ */
+export declare function readBlock(cwd: string, blockName: string, filter?: {
+    arrayKey: string;
+    predicate: (item: Record<string, unknown>) => boolean;
+}): unknown;
+/**
+ * Validated whole-file write to an arbitrary `(filePath, schemaPath)` pair.
+ * The `.project/`-targeting `writeBlock` becomes a thin wrapper over this.
+ * `schemaPath = null` skips AJV validation entirely (matches `writeBlock`'s
+ * "no schema file present" semantic).
+ *
+ * `ctx` (FGAP-004): when provided AND the schema declares author fields at
+ * the top-level envelope (and `data` is object-shaped, NOT array-shaped),
+ * the envelope is stamped before AJV runs. Top-level array files (e.g.
+ * monitor pattern lists) skip envelope-stamping silently — the envelope
+ * lookup returns an empty set for array schemas because their top-level
+ * `properties` is undefined.
+ *
+ * Atomic write via tmp + rename. Does NOT itself acquire a `withBlockLock`
+ * — whole-file overwrite has no read-modify-write race that locking would
+ * protect against. Callers performing read-modify-write (e.g.
+ * `appendToTypedFile`, `appendToBlock`, …) wrap the surrounding critical
+ * section in `withBlockLock` themselves; `writeTypedFile` is then called
+ * from inside that section. This matches the prior `writeBlock` /
+ * `appendToBlock` split exactly — preserves byte-identical lock semantics
+ * for existing callers.
+ */
+export declare function writeTypedFile(filePath: string, schemaPath: string | null, data: unknown, ctx?: DispatchContext, errorLabel?: string): void;
+/**
+ * Validated atomic append to an array within a `(filePath, schemaPath)` pair.
+ * `arrayPath = null` means "the file IS the array" (top-level array shape,
+ * e.g. monitor patterns / instructions); `arrayPath = string` means
+ * "data[arrayPath] is the target array" (object-with-array-field shape, the
+ * `.project/` block convention).
+ *
+ * `ctx` (FGAP-004): when provided AND the schema declares author fields on
+ * the items reached by `arrayPath` (or, for the flat-array case, on the
+ * array's `items.properties.*`), the appended item is stamped via
+ * `stampItem` in create-mode before AJV validation. For the flat-array
+ * case the array key passed to the per-array-key cache lookup is the
+ * arbitrary token `__top__` — `collectArrayItemAuthorDecisions` only
+ * traverses `properties.*` paths and never visits a top-level array
+ * schema, so the lookup will always miss; flat-array stamping is
+ * intentionally a no-op until a schema actually declares author fields
+ * on a top-level array shape (no current consumer does so).
+ */
+export declare function appendToTypedFile(filePath: string, schemaPath: string | null, arrayPath: string | null, item: unknown, ctx?: DispatchContext, errorLabel?: string): void;
+/**
+ * Validated atomic bulk append-if-absent to an array within a
+ * `(filePath, schemaPath)` pair. Each candidate in `items` is appended only
+ * when no element already present (on-disk OR earlier in this same batch)
+ * shares its `matchKey`. Dedup is keyed solely on `matchKey(item)` — the
+ * write surface does no semantic validation beyond the whole-array AJV check
+ * and this exact-duplicate-no-op; richer integrity (referential, etc.) is
+ * deferred to callers / downstream validators.
+ *
+ * `arrayPath` mirrors `appendToTypedFile`: `null` ⇒ the file content IS the
+ * array (flat top-level array shape); `string` ⇒ `data[arrayPath]` is the
+ * target array (object-with-array-field shape, the `.project/` convention).
+ * The branching is identical to `appendToTypedFile`'s.
+ *
+ * The whole read-find-write critical section runs inside `withBlockLock`, so
+ * concurrent batches against the same file serialise. When `appended === 0`
+ * nothing is written (the file is left byte-identical). The first write
+ * against an absent file works: `withBlockLock` skips locking when the file is
+ * absent (no contention possible), and the absent file is treated as an empty
+ * array for the flat-array shape — only that shape is creatable from absence;
+ * the object-with-array-field shape requires an existing envelope and so still
+ * throws via `readTypedFile`.
+ *
+ * `ctx` is threaded to `writeTypedFile` for attestation parity; per the
+ * top-level-array stamping semantics documented above, flat-array shapes with
+ * no declared envelope author fields treat it as a structural no-op.
+ */
+export declare function appendManyToTypedFileIfAbsent(filePath: string, schemaPath: string | null, arrayPath: string | null, items: unknown[], matchKey: (item: unknown) => string, ctx?: DispatchContext, errorLabel?: string): {
+    appended: number;
+    skipped: number;
+};
+/**
+ * Validated atomic find-by-predicate update of one item inside an array
+ * reachable from `(filePath, schemaPath, arrayPath)`. Generalises
+ * `updateItemInBlock` to arbitrary file paths and supports both top-level
+ * array files (`arrayPath === null`) and object-with-array-field files
+ * (`arrayPath === string`). Throws on predicate miss; AJV validates the
+ * whole file after mutation.
+ *
+ * Multi-match warning emits on stderr with the established `[block-api]`
+ * prefix (grep-discoverable across legacy log lines).
+ *
+ * `ctx`: when supplied AND the schema declares author fields on the items
+ * reachable by `arrayPath`, the merged item is stamped in update-mode
+ * before AJV runs. Flat-array stamping is a no-op (see
+ * `maybeStampTypedItem`).
+ */
+export declare function updateItemInTypedFile(filePath: string, schemaPath: string | null, arrayPath: string | null, predicate: (item: Record<string, unknown>) => boolean, updates: Record<string, unknown>, ctx?: DispatchContext, errorLabel?: string): void;
+/**
+ * Validated atomic find-or-append. Generalises `upsertItemInBlock` to
+ * arbitrary `(filePath, schemaPath, arrayPath)` triples, including
+ * top-level array files via `arrayPath === null`.
+ *
+ * FGAP-018 fix lives here (was in `upsertItemInBlock` prior to Step 6.3):
+ * on the update branch, declared create-time attestation fields are
+ * pre-merged from the existing on-disk item onto the supplied item if
+ * absent, so attestation integrity (FGAP-004) holds across replacement.
+ * The wrapper `upsertItemInBlock` inherits the fix structurally.
+ *
+ * For the flat-array case the pre-merge is a structural no-op — the
+ * `declaredAuthorFieldsForArray` lookup keyed by `__top__` returns the
+ * empty set (top-level array schemas are never visited by
+ * `collectArrayItemAuthorDecisions`), so no fields are carried. This is
+ * intentional: no current consumer declares author fields on a top-level
+ * array shape, and the unconditional pre-merge code path simply finds
+ * nothing to merge. If a future consumer lands such a schema, the
+ * stamping cataloguer needs an extension (filed-or-future work) — this
+ * primitive will then start preserving attestation on flat-array upserts
+ * automatically.
+ */
+export declare function upsertItemInTypedFile(filePath: string, schemaPath: string | null, arrayPath: string | null, item: Record<string, unknown>, idField: string, ctx?: DispatchContext, errorLabel?: string): {
+    mode: "appended" | "updated";
+};
+/**
+ * Validated atomic predicate-based remove. Generalises `removeFromBlock`
+ * to arbitrary `(filePath, schemaPath, arrayPath)` triples including
+ * top-level array files. Idempotent on miss (returns `{ removed: 0 }`
+ * without throwing or writing). AJV validates whole file after mutation
+ * (so e.g. a `minItems` violation surfaces).
+ */
+export declare function removeFromTypedFile(filePath: string, schemaPath: string | null, arrayPath: string | null, predicate: (item: Record<string, unknown>) => boolean, ctx?: DispatchContext, errorLabel?: string): {
+    removed: number;
+};
+/**
+ * Validated atomic append to a nested array inside a parent-array item.
+ * Generalises `appendToNestedArray` to arbitrary `(filePath, schemaPath,
+ * parentArrayKey, nestedArrayKey)`. Nesting requires object-with-array-field
+ * shape — a top-level array file cannot host nested arrays at the same
+ * structural level — so `parentArrayKey` is `string` (no `null` form).
+ *
+ * Throws on missing parent key, no parent match, missing nested key, or
+ * AJV failure. Multi-match warning emits at parent level via stderr with
+ * the established `[block-api]` prefix.
+ */
+export declare function appendToNestedTypedFile(filePath: string, schemaPath: string | null, parentArrayKey: string, predicate: (item: Record<string, unknown>) => boolean, nestedArrayKey: string, item: unknown, ctx?: DispatchContext, errorLabel?: string): void;
+/**
+ * Validated atomic update of a single item inside a nested array on a
+ * parent-array item. Generalises `updateNestedArrayItem` to arbitrary
+ * `(filePath, schemaPath, parentArrayKey, nestedArrayKey)`. Object-shape
+ * file required (see `appendToNestedTypedFile` doc).
+ *
+ * Throws on missing parent key, no parent/nested match, missing nested
+ * key, or AJV failure. Multi-match warnings emit at both parent and
+ * nested levels via stderr with the `[block-api]` prefix.
+ */
+export declare function updateNestedItemInTypedFile(filePath: string, schemaPath: string | null, parentArrayKey: string, parentPredicate: (item: Record<string, unknown>) => boolean, nestedArrayKey: string, nestedPredicate: (item: Record<string, unknown>) => boolean, updates: Record<string, unknown>, ctx?: DispatchContext, errorLabel?: string): void;
+/**
+ * Validated atomic remove from a nested array. Generalises
+ * `removeFromNestedArray` to arbitrary `(filePath, schemaPath,
+ * parentArrayKey, nestedArrayKey)`. Object-shape file required (see
+ * `appendToNestedTypedFile` doc). Idempotent on nested-miss (returns
+ * `{ removed: 0 }`); throws on parent-miss to surface a malformed
+ * caller, mirroring the wrapper's prior semantics.
+ */
+export declare function removeFromNestedTypedFile(filePath: string, schemaPath: string | null, parentArrayKey: string, parentPredicate: (item: Record<string, unknown>) => boolean, nestedArrayKey: string, nestedPredicate: (item: Record<string, unknown>) => boolean, ctx?: DispatchContext, errorLabel?: string): {
+    removed: number;
+};
+/**
+ * Validate `data` against its schema (if one exists) and write atomically
+ * to `.project/{blockName}.json`. Throws `ValidationError` on schema failure.
+ * Files without a corresponding schema are written without validation.
+ *
+ * Thin wrapper over `writeTypedFile` — see that function for full semantics.
+ * `ctx` (FGAP-004): whole-block writes are treated as create-mode envelope
+ * stamping; callers wanting per-item attribution should prefer the
+ * array-grained writers.
+ */
+export declare function writeBlock(cwd: string, blockName: string, data: unknown, ctx?: DispatchContext): void;
+/**
+ * Read current file, push item onto data[arrayKey], validate whole file
+ * against schema, write atomically. Throws if file doesn't exist, if
+ * arrayKey is missing or not an array, or if validation fails.
+ *
+ * `ctx` (FGAP-004): when provided AND the schema declares author fields on
+ * `properties.<arrayKey>.items.properties.*`, the appended item is stamped
+ * via `stampItem` in create-mode before AJV validation. Schemas that don't
+ * declare author fields fall through unstamped — guards against
+ * `additionalProperties: false` AJV failures on blocks whose item shape
+ * doesn't carry author markers yet.
+ */
+export declare function appendToBlock(cwd: string, blockName: string, arrayKey: string, item: unknown, ctx?: DispatchContext): void;
+/**
+ * Find an item in data[arrayKey] by predicate, shallow-merge updates onto it,
+ * validate whole file against schema, write atomically. Throws if no item
+ * matches, if arrayKey is missing or not an array, or if validation fails.
+ *
+ * `ctx` (FGAP-004): when provided AND the schema declares author fields on
+ * the array's items, the merged item is run through `stampItem` in
+ * update-mode after the shallow merge — `created_by` / `created_at` are
+ * preserved, `modified_by` / `modified_at` refresh.
+ */
+export declare function updateItemInBlock(cwd: string, blockName: string, arrayKey: string, predicate: (item: Record<string, unknown>) => boolean, updates: Record<string, unknown>, ctx?: DispatchContext): void;
+/**
+ * Atomically find-or-append a single item in `data[arrayKey]` keyed by
+ * `idField`. Acquires the block lock; reads the array; locates the first
+ * existing item where `existingItem[idField] === item[idField]`; if found
+ * the item at that index is REPLACED (not shallow-merged) by the supplied
+ * `item` and stamping runs in `"update"` mode; otherwise `item` is pushed
+ * onto the array and stamping runs in `"create"` mode. AJV validates the
+ * whole file against the schema after mutation, before write.
+ *
+ * Composing existing `updateItemInBlock` + `appendToBlock` from a caller
+ * would release the block lock between the read-check and the mutating
+ * write, which is race-prone for concurrent monitor/LLM writes against the
+ * same block — this primitive holds the lock for both halves of the
+ * find-or-append decision in one atomic critical section.
+ *
+ * Throws when `item[idField]` is missing or empty (defensive — surfaces a
+ * malformed call site early instead of silently appending a duplicate
+ * that would never match on a subsequent upsert). Throws on the usual
+ * block / arrayKey / not-array invariants and on AJV validation failure.
+ *
+ * Replacement semantics (vs. updateItemInBlock's shallow-merge): upsert is
+ * the call surface for monitor write-actions where the template produces
+ * the FULL item shape per classification — there is no prior partial state
+ * to merge against. Callers that need merge-on-update should continue to
+ * use `updateItemInBlock`.
+ */
+export declare function upsertItemInBlock(cwd: string, blockName: string, arrayKey: string, item: Record<string, unknown>, idField: string, ctx?: DispatchContext): {
+    mode: "appended" | "updated";
+};
+/**
+ * Atomically append an item to a nested array inside a parent-array item.
+ *
+ * Read current file, locate parent-array item by predicate, push `item` onto
+ * `data[parentArrayKey][matchedIndex][nestedArrayKey]`, validate whole file
+ * against schema, write atomically. Throws if file doesn't exist; if
+ * parentArrayKey is missing or not an array; if no parent item matches the
+ * predicate; if the matched parent item has no `nestedArrayKey` or it is not
+ * an array; or if validation fails. Mirrors updateItemInBlock's structure:
+ * file lock, predicate findIndex, multi-match warning, clone-before-write so
+ * the original array remains unmodified if writeBlock throws.
+ */
+export declare function appendToNestedArray(cwd: string, blockName: string, parentArrayKey: string, predicate: (item: Record<string, unknown>) => boolean, nestedArrayKey: string, item: unknown, ctx?: DispatchContext): void;
+/**
+ * Atomically update a single item inside a nested array on a parent-array
+ * item: locate parent by parentPredicate, locate nested by nestedPredicate,
+ * shallow-merge `updates` onto the matched nested item, validate the whole
+ * file against schema, write atomically. Throws on missing block / missing
+ * parent key / parent key not array / no parent match / matched parent
+ * missing nestedKey / nested key not array / no nested match / validation
+ * failure. Multi-match warnings emit at both parent and nested levels via
+ * console.error (mirrors the established appendToNestedArray /
+ * updateItemInBlock convention). Clone-then-write keeps the original arrays
+ * unmodified if writeBlock throws.
+ */
+export declare function updateNestedArrayItem(cwd: string, blockName: string, parentArrayKey: string, parentPredicate: (item: Record<string, unknown>) => boolean, nestedArrayKey: string, nestedPredicate: (item: Record<string, unknown>) => boolean, updates: Record<string, unknown>, ctx?: DispatchContext): void;
+/**
+ * Atomically remove all items matching `predicate` from a top-level array
+ * inside `data[arrayKey]`, validate the whole file against schema, write
+ * atomically. Returns `{ removed: <count> }`. Throws on missing block /
+ * missing key / key not array / validation failure (e.g., schema requires
+ * minItems and removal violates it). Returns `{ removed: 0 }` on no match
+ * without throwing — removal of a non-existent item is treated as an
+ * idempotent successful no-op, distinct from update which throws on miss.
+ */
+export declare function removeFromBlock(cwd: string, blockName: string, arrayKey: string, predicate: (item: Record<string, unknown>) => boolean, ctx?: DispatchContext): {
+    removed: number;
+};
+/**
+ * Atomically remove all items matching `nestedPredicate` from a nested array
+ * inside the parent-array item matched by `parentPredicate`. Validates and
+ * writes atomically. Returns `{ removed: <count> }`. Throws on missing block
+ * / missing parent key / parent key not array / no parent match / matched
+ * parent missing nestedKey / nested key not array / validation failure.
+ * Returns `{ removed: 0 }` on no nested match without throwing (idempotent,
+ * mirrors removeFromBlock semantics). Multi-match warning at parent level
+ * via console.error.
+ */
+export declare function removeFromNestedArray(cwd: string, blockName: string, parentArrayKey: string, parentPredicate: (item: Record<string, unknown>) => boolean, nestedArrayKey: string, nestedPredicate: (item: Record<string, unknown>) => boolean, ctx?: DispatchContext): {
+    removed: number;
+};
+/**
+ * Read all `.json` files in a `.project/<subdir>/` directory and return the
+ * parsed contents as a sorted array. Sort order is filesystem-name ascending
+ * (matches Array.sort default on the basename strings). Missing directories
+ * return `[]` — on-demand `.project/` subdirectories are valid and represent
+ * "no items yet". Throws on filesystem read failure of a present file or on
+ * invalid JSON, with file-relative path in the error message. Behavior must
+ * match the previous private `executeReadDir` in pi-workflows step-block.ts
+ * byte-identically; both pi-workflows and the `read-block-dir` registered
+ * tool consume this single export.
+ */
+export declare function readBlockDir(cwd: string, subdir: string): unknown[];
+/**
+ * Resolve the item subschema for a block schema: find the first array property
+ * carrying `items`, dereferencing a single-level `$ref` to `#/definitions/<x>`
+ * or `#/$defs/<x>` (the shape FK-stripped block schemas use, e.g. features /
+ * spec-reviews). Returns the array key + the resolved item schema object (with
+ * its `properties` / `required` / `id`). Throws when no array property is found
+ * or the `$ref` cannot be resolved.
+ *
+ * FGAP-083: callers that read `items.properties.id.pattern` / `items.required`
+ * straight off `props[arrayKey].items` get `undefined` for `$ref` items; this
+ * one dereference is the fix shared by auto-id, author-field auto-stamp, and
+ * whole-file validation.
+ */
+export declare function resolveBlockItemSchema(schema: Record<string, unknown>): {
+    arrayKey: string;
+    itemSchema: Record<string, unknown>;
+};
+/**
+ * Allocate the next id for a block from its schema's id pattern — canonical and
+ * `$ref`-aware (FGAP-084 / FGAP-083). Reads the block schema, resolves the item
+ * subschema, parses the `id` pattern's prefix + minimum digit width
+ * (`^FGAP-\d{3}$` → `FGAP-`/3; `^TASK-\d{3,}$` → `TASK-`/3), scans existing item
+ * ids for the max numeric suffix, and returns `prefix` + zero-padded (maxN+1).
+ * Throws when the schema is missing or the id pattern is absent / not
+ * prefix+width parseable. Orchestrator CLIs + the in-pi append tool route
+ * through this instead of re-implementing allocation.
+ */
+export declare function nextId(cwd: string, blockName: string): string;
+//# sourceMappingURL=block-api.d.ts.map

package/dist/block-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-api.d.ts","sourceRoot":"","sources":["../src/block-api.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAqQ7D;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACxB,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAA;CAAE,GAClF,OAAO,CA0BT;AAkCD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAC7B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,IAAI,EAAE,OAAO,EACb,GAAG,CAAC,EAAE,eAAe,EACrB,UAAU,CAAC,EAAE,MAAM,GACjB,IAAI,CAuCN;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAChC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,IAAI,EAAE,OAAO,EACb,GAAG,CAAC,EAAE,eAAe,EACrB,UAAU,CAAC,EAAE,MAAM,GACjB,IAAI,CAsCN;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,6BAA6B,CAC5C,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,KAAK,EAAE,OAAO,EAAE,EAChB,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,MAAM,EACnC,GAAG,CAAC,EAAE,eAAe,EACrB,UAAU,CAAC,EAAE,MAAM,GACjB;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAgEvC;AA8ED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACpC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,EACrD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,GAAG,CAAC,EAAE,eAAe,EACrB,UAAU,CAAC,EAAE,MAAM,GACjB,IAAI,CAuBN;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,qBAAqB,CACpC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,MAAM,EACf,GAAG,CAAC,EAAE,eAAe,EACrB,UAAU,CAAC,EAAE,MAAM,GACjB;IAAE,IAAI,EAAE,UAAU,GAAG,SAAS,CAAA;CAAE,CA+ClC;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAClC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,EACrD,GAAG,CAAC,EAAE,eAAe,EACrB,UAAU,CAAC,EAAE,MAAM,GACjB;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAoBrB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACtC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,EACrD,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,OAAO,EACb,GAAG,CAAC,EAAE,eAAe,EACrB,UAAU,CAAC,EAAE,MAAM,GACjB,IAAI,CAsCN;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAC1C,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,EAC3D,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,EAC3D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,GAAG,CAAC,EAAE,eAAe,EACrB,UAAU,CAAC,EAAE,MAAM,GACjB,IAAI,CAmDN;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACxC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,EAC3D,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,EAC3D,GAAG,CAAC,EAAE,eAAe,EACrB,UAAU,CAAC,EAAE,MAAM,GACjB;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CA4CrB;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,eAAe,GAAG,IAAI,CAIrG;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC5B,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,EACb,GAAG,CAAC,EAAE,eAAe,GACnB,IAAI,CA4BN;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAChC,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,EACrD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,GAAG,CAAC,EAAE,eAAe,GACnB,IAAI,CAIN;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,CAChC,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,MAAM,EACf,GAAG,CAAC,EAAE,eAAe,GACnB;IAAE,IAAI,EAAE,UAAU,GAAG,SAAS,CAAA;CAAE,CAIlC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAClC,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,EACrD,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,OAAO,EACb,GAAG,CAAC,EAAE,eAAe,GACnB,IAAI,CAaN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACpC,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,EAC3D,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,EAC3D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,GAAG,CAAC,EAAE,eAAe,GACnB,IAAI,CAcN;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC9B,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,EACrD,GAAG,CAAC,EAAE,eAAe,GACnB;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAIrB;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACpC,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,EAC3D,cAAc,EAAE,MAAM,EACtB,eAAe,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,EAC3D,GAAG,CAAC,EAAE,eAAe,GACnB;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAarB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,EAAE,CAgCnE;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IACxE,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CA2BA;AAED;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CA+B7D"}