pm-graph 2026.10.23 → 2026.10.24

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 2026.10.24 - 2026-10-24
+
+### Added
+
+- Enumerate minimal blocker frontiers for a goal with bounded completeness receipts ([pm-graph-8z44](https://github.com/unbraind/pm-graph/blob/main/.agents/pm/features/pm-graph-8z44.toon))
+- Compare snapshot graph impact for resuming agents ([pm-graph-snapshot-impact](https://github.com/unbraind/pm-graph/blob/main/.agents/pm/features/pm-graph-snapshot-impact.toon))
+
+### Other
+
+- Correct review evidence in tracker reconciliation PR 155 ([pm-graph-review155](https://github.com/unbraind/pm-graph/blob/main/.agents/pm/chores/pm-graph-review155.toon))
+
 ## 2026.10.23 - 2026-10-23
 
 ### Changed

package/README.md

@@ -613,7 +613,7 @@ See the [SDK and CLI example](docs/snapshot-impact-example.md) and the
 
 ## Without git
 
-Graph projection, export, offline analysis, path/impact/explain and snapshot
+Graph projection, consent-scoped `project`, export, offline analysis, path/impact/explain and snapshot
 comparison work in plain trackers. Snapshot comparison reads only the two
 explicit JSON files and also works without a tracker. Neo4j operations require
 their configured database connection. None of these graph operations needs a
@@ -720,3 +720,15 @@ form paper, carbon ink, ruled item sheets and explicit status fills. Portable fo
 stacks put Archivo, Public Sans and Martian Mono first and fetch no external fonts.
 [Design, themes, token parity and reproducible review renders](docs/triplicate-visuals.md).
 The README banner embeds pm-brand's committed output at an immutable SHA.
+
+## Consent-scoped cross-workspace projection
+
+`pm pm-graph project projection.json --limit 100 --json` reads only explicitly
+consented trackers into a read-only item graph. The typed `projectWorkspaces`
+SDK also accepts database readers bound to existing core authorization. Qualified
+IDs preserve workspace identity; cross-workspace evidence needs separate consent
+and two visible endpoints. Denied or incomplete sources yield opaque boundaries,
+with no hidden node IDs, labels or source exception text. Source completeness
+and output omission receipts remain separate. JSON and compact TOON use the
+host's standard output controls. See the [manifest and SDK example](docs/cross-workspace-example.md)
+for scope, authorization, pagination, refusal remedies and limits.

package/dist/blocker-cuts-command.js

@@ -1,4 +1,4 @@
-import { listAllComplete, readSettings, resolveRuntimeStatusRegistry } from "@unbrained/pm-cli/sdk";
+import { defineCommand, defineFlag, listAllComplete, readSettings, resolveRuntimeStatusRegistry } from "@unbrained/pm-cli/sdk";
 import { minimalBlockerCuts } from "./blocker-cuts.js";
 /** Preserve refusal evidence in CLI JSON/TOON instead of losing it in error formatting. */
 function commandRefusal(code, remedy, receipt, source) {
@@ -7,44 +7,30 @@ function commandRefusal(code, remedy, receipt, source) {
 }
 /** Register the offline command; source reads are strict, complete, and extension-free. */
 export function registerBlockerCuts(api, resolveRoot, project) {
-    api.registerCommand({
+    api.registerCommand(defineCommand({
         name: "pm-graph blocker-cuts",
         description: "Enumerate alternative minimal blocker frontiers for a goal with bounded completeness receipts.",
         read_output: { row_keys: ["cuts"] },
         arguments: [{ name: "goal", required: true, description: "Exact goal item id" }],
+        flags: [
+            defineFlag({ long: "--max-states", value_name: "integer", value_type: "number", description: "Positive integer search-state budget (default 20000)." }),
+            defineFlag({ long: "--max-work", value_name: "integer", value_type: "number", description: "Positive integer work budget (default 2000000)." }),
+            defineFlag({ long: "--max-cuts", value_name: "integer", value_type: "number", description: "Positive integer cut limit (default 32)." }),
+            defineFlag({ long: "--max-size", value_name: "integer", value_type: "number", description: "Positive integer frontier size limit (default 8)." }),
+        ],
         examples: ["pm pm-graph blocker-cuts goal-id --max-cuts 16 --json"],
         failure_hints: ["Reload the full tracker for missing nodes; break cycles; increase search limits only when the receipt is partial."],
         run: async (context) => {
-            const args = context.args ?? [];
-            if (args.includes("--help") || args.includes("-h")) {
-                return {
-                    cuts: [],
-                    usage: "pm pm-graph blocker-cuts <goal> [--max-states 20000] [--max-work 2000000] [--max-cuts 32] [--max-size 8] [--json]",
-                    semantics: "All upstream prerequisite paths must intersect a cut. Intermediate tasks still require completion; immediatelyUnblocked reports direct eligibility.",
-                    completeness: "Graph/source and search receipts are separate. Partial cuts are minimal; a partial list is not exhaustive.",
-                };
-            }
+            const positionals = context.args ?? [];
             const options = {};
-            const positionals = [];
-            const flags = new Map([
-                ["--max-states", "maxStates"], ["--max-work", "maxWork"], ["--max-cuts", "maxCuts"], ["--max-size", "maxSize"],
-            ]);
-            for (let i = 0; i < args.length; i++) {
-                const arg = args[i];
-                if (arg === "--json")
+            for (const key of ["maxStates", "maxWork", "maxCuts", "maxSize"]) {
+                const value = context.options?.[key];
+                if (value === undefined)
                     continue;
-                const key = flags.get(arg);
-                if (key) {
-                    const value = args[++i];
-                    if (!value || !/^\d+$/.test(value))
-                        return commandRefusal("INVALID_OPTIONS", `Supply a positive integer after ${arg}.`);
-                    options[key] = Number(value);
-                }
-                else if (arg.startsWith("-")) {
-                    return commandRefusal("INVALID_OPTIONS", `Remove unsupported flag ${arg}; use blocker-cuts --help.`);
+                if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+                    return commandRefusal("INVALID_OPTIONS", `Supply a positive integer for ${key}.`);
                 }
-                else
-                    positionals.push(arg);
+                options[key] = value;
             }
             if (positionals.length !== 1)
                 return commandRefusal("INVALID_OPTIONS", "Use pm pm-graph blocker-cuts <exact-goal-id>; see --help for budgets.");
@@ -69,6 +55,6 @@ export function registerBlockerCuts(api, resolveRoot, project) {
                 return { ...commandRefusal(result.refusal.code, result.refusal.remedy, result.receipt, source), goal: result.goal };
             return { ...result, source };
         },
-    });
+    }));
 }
 //# sourceMappingURL=blocker-cuts-command.js.map

package/dist/blocker-cuts-command.js.map

@@ -1 +1 @@
-{"version":3,"file":"blocker-cuts-command.js","sourceRoot":"","sources":["../src/blocker-cuts-command.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"blocker-cuts-command.js","sourceRoot":"","sources":["../src/blocker-cuts-command.ts"],"names":[],"mappings":"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"}

package/dist/cross-workspace-command.d.ts

@@ -0,0 +1,3 @@
+import type { ExtensionApi } from "./index.ts";
+/** Register a read-only directory transport; database consumers bind core-authorized SDK readers directly. */
+export declare function registerCrossWorkspace(api: ExtensionApi): void;

package/dist/cross-workspace-command.js

@@ -0,0 +1,96 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import path from "node:path";
+import { projectWorkspaces, projectionRefusal } from "./cross-workspace.js";
+/** Parse an explicit bounded regular manifest without discovering workspaces, git, extensions or credentials. */
+async function readManifest(file) {
+    const handle = await open(file, constants.O_RDONLY | constants.O_NONBLOCK);
+    try {
+        if (!(await handle.stat()).isFile())
+            return null;
+        const buffer = Buffer.alloc(1024 * 1024 + 1);
+        let length = 0;
+        while (length < buffer.length) {
+            const read = await handle.read(buffer, length, buffer.length - length, null);
+            if (read.bytesRead === 0)
+                break;
+            length += read.bytesRead;
+        }
+        return length === buffer.length ? null : JSON.parse(buffer.subarray(0, length).toString("utf8"));
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Validate transport input before constructing private directory reader capabilities. */
+function manifestScopes(value, base) {
+    if (value === null || typeof value !== "object" || !("scopes" in value) || !Array.isArray(value.scopes)
+        || !("consent" in value) || !Array.isArray(value.consent) || !value.consent.every((key) => typeof key === "string"))
+        return null;
+    const scopes = [];
+    for (const scope of value.scopes) {
+        if (scope === null || typeof scope !== "object" || !("key" in scope) || typeof scope.key !== "string"
+            || !("pmRoot" in scope) || typeof scope.pmRoot !== "string" || scope.pmRoot.length === 0)
+            return null;
+        scopes.push({ key: scope.key, source: { kind: "directory", pmRoot: path.resolve(base, scope.pmRoot) } });
+    }
+    const evidence = "evidence" in value ? value.evidence : [];
+    if (!Array.isArray(evidence))
+        return null;
+    // The SDK validates every evidence field before any source capability runs.
+    return { scopes, consent: value.consent, evidence: evidence };
+}
+/** Register a read-only directory transport; database consumers bind core-authorized SDK readers directly. */
+export function registerCrossWorkspace(api) {
+    api.registerCommand({
+        name: "pm-graph project",
+        description: "Project explicitly consented workspaces into a qualified read-only graph with opaque boundary receipts.",
+        arguments: [{ name: "manifest", required: true, description: "Explicit consent manifest JSON" }],
+        read_output: { row_keys: ["rows", "boundaries"] },
+        examples: ["pm pm-graph project projection.json --limit 100 --json"],
+        failure_hints: ["Grant consent only to intended scopes; recover omitted rows with --offset; see boundary remedies for incomplete sources."],
+        run: async (context) => {
+            const args = context.args ?? [];
+            if (args.includes("--help") || args.includes("-h"))
+                return {
+                    rows: [], boundaries: [], usage: "pm pm-graph project <manifest.json> [--limit 100] [--offset 0] [--json]",
+                    manifest: { scopes: [{ key: "public", pmRoot: "tracker/.agents/pm" }], consent: ["public"], evidence: [] },
+                    semantics: "Paths are relative to the manifest. Explicit local consent plus OS/SDK read permissions; hosted callers must bind their current authorization via projectWorkspaces. No traversal of denied scopes. Item nodes and local relationships only; cross-workspace SUPPORTS/EVIDENCE_FOR requires per-edge consent. Read sequentially, not a global atomic snapshot.",
+                };
+            let manifest;
+            let limit = 100;
+            let offset = 0;
+            for (let index = 0; index < args.length; index++) {
+                const arg = args[index];
+                if (arg === "--json")
+                    continue;
+                if (arg === "--limit" || arg === "--offset") {
+                    const raw = args[++index];
+                    if (!raw || !/^\d+$/.test(raw))
+                        return projectionRefusal();
+                    if (arg === "--limit")
+                        limit = Number(raw);
+                    else
+                        offset = Number(raw);
+                }
+                else if (arg.startsWith("-") || manifest !== undefined)
+                    return projectionRefusal();
+                else
+                    manifest = arg;
+            }
+            if (manifest === undefined)
+                return projectionRefusal();
+            const file = path.resolve(context.cwd ?? process.cwd(), manifest);
+            try {
+                const parsed = manifestScopes(await readManifest(file), path.dirname(file));
+                if (!parsed)
+                    return projectionRefusal();
+                return await projectWorkspaces(parsed.scopes, { consent: parsed.consent, evidence: parsed.evidence, authorize: () => true, limit, offset });
+            }
+            catch {
+                return projectionRefusal();
+            }
+        },
+    });
+}
+//# sourceMappingURL=cross-workspace-command.js.map

package/dist/cross-workspace-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-workspace-command.js","sourceRoot":"","sources":["../src/cross-workspace-command.ts"],"names":[],"mappings":"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"}

package/dist/cross-workspace.d.ts

@@ -0,0 +1,91 @@
+import type { PmCompleteListResult } from "@unbrained/pm-cli/sdk";
+/** Explicit source capability. Database readers must be bound to the caller's core-authorized tenant scope. */
+export type ProjectionSource = {
+    kind: "directory";
+    pmRoot: string;
+} | {
+    kind: "database";
+    read: () => Promise<PmCompleteListResult>;
+};
+/** Public alias and private source capability; neither paths nor database identifiers enter output. */
+export type ProjectionScope = {
+    key: string;
+    source: ProjectionSource;
+};
+/** Cross-workspace evidence is opt-in per edge and requires two readable item endpoints. */
+export type ProjectionEvidence = {
+    from: {
+        workspace: string;
+        item: string;
+    };
+    to: {
+        workspace: string;
+        item: string;
+    };
+    type: "SUPPORTS" | "EVIDENCE_FOR";
+    consent: boolean;
+};
+/** Explicit consent plus the host's current authorization policy; consent never overrides denial. */
+export type ProjectionOptions = {
+    consent: readonly string[];
+    authorize: (scope: ProjectionScope) => boolean | Promise<boolean>;
+    evidence?: readonly ProjectionEvidence[];
+    limit?: number;
+    offset?: number;
+};
+/** Compact item-only graph rows, intentionally excluding bodies, raw dependencies and external placeholders. */
+export type ProjectionRow = {
+    kind: "node";
+    id: string;
+    workspace: string;
+    item: string;
+    title: string;
+    type: string;
+    status: string;
+} | {
+    kind: "edge";
+    from: string;
+    to: string;
+    type: string;
+};
+/** Opaque boundary references only the caller's input slot; it carries no source errors or endpoint identities. */
+export type ProjectionBoundary = {
+    slot: number;
+    kind: "scope" | "evidence";
+    code: "CONSENT_REQUIRED" | "UNREADABLE" | "SOURCE_INCOMPLETE" | "ENDPOINT_UNAVAILABLE" | "SOURCE_LIMIT" | "DANGLING_RELATION";
+    remedy: string;
+};
+/** Source completeness and output pagination are independent, explicit receipts. No cross-source atomic snapshot is claimed. */
+export type ProjectionResult = {
+    ok: boolean;
+    exit_code?: number;
+    rows: ProjectionRow[];
+    boundaries: ProjectionBoundary[];
+    complete: boolean;
+    receipt: {
+        scopes: number;
+        readable: number;
+        nodes: number;
+        edges: number;
+        total: number;
+        offset: number;
+        returned: number;
+        omitted: number;
+        nextOffset: number | null;
+    };
+    refusal?: {
+        code: "INVALID_OPTIONS" | "NO_READABLE_SCOPE";
+        remedy: string;
+    };
+};
+/** Encode each tuple component separately so separators and repeated local IDs cannot collide. */
+export declare function qualifyProjectionId(workspace: string, item: string): string;
+/** Produce a stable, path-free refusal that remains machine-readable through the CLI host. */
+export declare function projectionRefusal(): ProjectionResult;
+/**
+ * Project only explicitly consented, currently authorized sources. SDK certificates are
+ * revalidated even for database adapters. Failed reads are atomic per source; no partial
+ * source rows, dangling identities, source errors, or denied endpoint labels are exposed.
+ * Readers run sequentially and without extension hooks; this function performs no writes.
+ */
+export declare function projectWorkspaces(scopes: readonly ProjectionScope[], options: ProjectionOptions): Promise<ProjectionResult>;

package/dist/cross-workspace.js

@@ -0,0 +1,120 @@
+import { certifyCompleteListResult, listAllComplete } from "@unbrained/pm-cli/sdk";
+import { assertPmTracker, graphFromItems } from "./index.js";
+/** Encode each tuple component separately so separators and repeated local IDs cannot collide. */
+export function qualifyProjectionId(workspace, item) {
+    return `${encodeURIComponent(workspace)}::${encodeURIComponent(item)}`;
+}
+/** Produce a stable, path-free refusal that remains machine-readable through the CLI host. */
+export function projectionRefusal() {
+    return { ok: false, exit_code: 2, rows: [], boundaries: [], complete: false,
+        receipt: { scopes: 0, readable: 0, nodes: 0, edges: 0, total: 0, offset: 0, returned: 0, omitted: 0, nextOffset: null },
+        refusal: { code: "INVALID_OPTIONS", remedy: "Supply 1-32 unique nonempty scope aliases and well-formed Unicode identity components, explicit consent and an authorization function; limit 1-1000, offset 0 or greater, and at most 10000 typed evidence edges. See project --help." } };
+}
+/** Accept nonempty UTF-16 identities only when every surrogate belongs to a valid pair. */
+function validIdentityComponent(value) {
+    return typeof value === "string" && value.length > 0 && !/[\uD800-\uDFFF]/u.test(value);
+}
+/** Check caller-controlled edge shapes without inspecting any source or echoing invalid identities. */
+function validEvidence(edge) {
+    return edge !== null && typeof edge === "object" && ["SUPPORTS", "EVIDENCE_FOR"].includes(edge.type)
+        && typeof edge.consent === "boolean" && [edge.from, edge.to].every((end) => end !== null && typeof end === "object"
+        && validIdentityComponent(end.workspace) && validIdentityComponent(end.item));
+}
+/**
+ * Project only explicitly consented, currently authorized sources. SDK certificates are
+ * revalidated even for database adapters. Failed reads are atomic per source; no partial
+ * source rows, dangling identities, source errors, or denied endpoint labels are exposed.
+ * Readers run sequentially and without extension hooks; this function performs no writes.
+ */
+export async function projectWorkspaces(scopes, options) {
+    const limit = options.limit ?? 100;
+    const offset = options.offset ?? 0;
+    const evidence = options.evidence ?? [];
+    if (!Array.isArray(scopes) || scopes.length === 0 || scopes.length > 32 || !Array.isArray(options.consent)
+        || typeof options.authorize !== "function" || !Number.isSafeInteger(limit) || limit < 1 || limit > 1000
+        || !Number.isSafeInteger(offset) || offset < 0 || !Array.isArray(evidence) || evidence.length > 10000
+        || !evidence.every(validEvidence) || !scopes.every((scope) => scope && validIdentityComponent(scope.key) && scope.key.length <= 128
+        && scope.source && (scope.source.kind === "directory" ? typeof scope.source.pmRoot === "string" && scope.source.pmRoot.length > 0 : scope.source.kind === "database" && typeof scope.source.read === "function"))
+        || new Set(scopes.map((scope) => scope.key)).size !== scopes.length
+        || options.consent.some((key) => !scopes.some((scope) => scope.key === key)))
+        return projectionRefusal();
+    const rows = [];
+    const boundaries = [];
+    const visible = new Set();
+    const edgeKeys = new Set();
+    let readable = 0;
+    for (const [slot, scope] of scopes.entries()) {
+        if (!options.consent.includes(scope.key)) {
+            boundaries.push({ slot, kind: "scope", code: "CONSENT_REQUIRED", remedy: "Obtain explicit read consent for this input scope." });
+            continue;
+        }
+        let allowed = false;
+        try {
+            allowed = await options.authorize(scope) === true;
+        }
+        catch { /* Authorization failures are indistinguishable from denial. */ }
+        if (!allowed) {
+            boundaries.push({ slot, kind: "scope", code: "UNREADABLE", remedy: "Ask the source owner to grant read access, then retry with current authorization." });
+            continue;
+        }
+        let snapshot;
+        try {
+            snapshot = certifyCompleteListResult(scope.source.kind === "directory"
+                ? await listAllComplete({}, { pmRoot: assertPmTracker(scope.source.pmRoot), noExtensions: true }) : await scope.source.read());
+        }
+        catch {
+            boundaries.push({ slot, kind: "scope", code: "SOURCE_INCOMPLETE", remedy: "Restore a readable source and use the SDK listAllComplete reader without filters or output limits." });
+            continue;
+        }
+        if (snapshot.items.length > 100000) {
+            boundaries.push({ slot, kind: "scope", code: "SOURCE_LIMIT", remedy: "Project a separately authorized tracker containing at most 100000 items." });
+            continue;
+        }
+        const graph = graphFromItems(snapshot.items, scope.key, new Map(), { includeFacets: false });
+        const local = new Set(snapshot.items.map((item) => item.id));
+        for (const item of snapshot.items) {
+            const id = qualifyProjectionId(scope.key, item.id);
+            visible.add(id);
+            rows.push({ kind: "node", id, workspace: scope.key, item: item.id, title: item.title, type: item.type, status: item.status });
+        }
+        let dangling = false;
+        for (const edge of graph.relationships) {
+            if (!local.has(edge.from) || !local.has(edge.to)) {
+                dangling = true;
+                continue;
+            }
+            const from = qualifyProjectionId(scope.key, edge.from);
+            const to = qualifyProjectionId(scope.key, edge.to);
+            rows.push({ kind: "edge", from, to, type: edge.type });
+            edgeKeys.add(JSON.stringify([from, to, edge.type]));
+        }
+        if (dangling)
+            boundaries.push({ slot, kind: "scope", code: "DANGLING_RELATION", remedy: "Resolve missing local relationships in the source; cross-workspace evidence requires a separate consented edge." });
+        readable++;
+    }
+    for (const [slot, edge] of evidence.entries()) {
+        if (!edge.consent) {
+            boundaries.push({ slot, kind: "evidence", code: "CONSENT_REQUIRED", remedy: "Obtain explicit consent for this evidence edge." });
+            continue;
+        }
+        const from = qualifyProjectionId(edge.from.workspace, edge.from.item);
+        const to = qualifyProjectionId(edge.to.workspace, edge.to.item);
+        if (!visible.has(from) || !visible.has(to)) {
+            boundaries.push({ slot, kind: "evidence", code: "ENDPOINT_UNAVAILABLE", remedy: "Ensure both endpoints are in readable consented sources; no boundary is traversed automatically." });
+            continue;
+        }
+        const key = JSON.stringify([from, to, edge.type]);
+        if (edgeKeys.has(key))
+            continue;
+        edgeKeys.add(key);
+        rows.push({ kind: "edge", from, to, type: edge.type });
+    }
+    const page = rows.slice(offset, offset + limit);
+    const nodes = visible.size;
+    const nextOffset = offset + page.length < rows.length ? offset + page.length : null;
+    return { ok: readable > 0, rows: page, boundaries,
+        complete: boundaries.length === 0,
+        receipt: { scopes: scopes.length, readable, nodes, edges: rows.length - nodes, total: rows.length, offset, returned: page.length, omitted: rows.length - page.length, nextOffset },
+        ...(readable === 0 ? { exit_code: 2, refusal: { code: "NO_READABLE_SCOPE", remedy: "Provide at least one consented source with current read authorization and a certified complete read." } } : {}) };
+}
+//# sourceMappingURL=cross-workspace.js.map

package/dist/cross-workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-workspace.js","sourceRoot":"","sources":["../src/cross-workspace.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,7 +1,9 @@
+export { projectWorkspaces, qualifyProjectionId } from "./cross-workspace.ts";
+export type { ProjectionSource, ProjectionScope, ProjectionOptions, ProjectionEvidence, ProjectionRow, ProjectionBoundary, ProjectionResult } from "./cross-workspace.ts";
 export { compareGraphSnapshots } from "./snapshot-impact.ts";
 export type { SnapshotImpactOptions, SnapshotNodeContext, SnapshotImpactChange, SnapshotImpactRefusalCode, SnapshotImpactRefusal, SnapshotImpactResult } from "./snapshot-impact.ts";
 import type { BrandTheme } from "./brand.ts";
-import { type Exporter, type ItemMetadata } from "@unbrained/pm-cli/sdk";
+import { type FlagDefinition, type Exporter, type GlobalOptions, type ItemMetadata } from "@unbrained/pm-cli/sdk";
 import type { ExtensionCommandReadOutput } from "@unbrained/pm-cli/sdk/authoring";
 export { minimalBlockerCuts } from "./blocker-cuts.ts";
 export type { BlockerCut, BlockerCutOptions, BlockerCutReceipt, BlockerCutRefusalCode, BlockerCutResult } from "./blocker-cuts.ts";
@@ -15,7 +17,7 @@ export type CommandContext = {
     /** Resolved tracker storage path the CLI passes to extension commands (honours --pm-path/--path). */
     pm_root?: string;
     options?: Record<string, unknown>;
-    global?: Record<string, unknown>;
+    global?: Partial<GlobalOptions> | Record<string, unknown>;
 };
 /** Definition of a positional argument accepted by an extension command. */
 export type ExtensionCommandArgumentDefinition = {
@@ -31,6 +33,7 @@ export type RegisterCommand = {
     read_output?: ExtensionCommandReadOutput;
     run: (context: CommandContext) => Promise<unknown>;
     arguments?: ExtensionCommandArgumentDefinition[];
+    flags?: FlagDefinition[];
     intent?: string;
     examples?: string[];
     failure_hints?: string[];
@@ -72,6 +75,31 @@ export type Graph = {
     nodes: GraphNode[];
     relationships: GraphRelationship[];
 };
+/**
+ * Verify that a path is a usable pm tracker root, throwing a `USAGE`
+ * {@link PmCliExpectedError} when it is not.
+ *
+ * This exists because the SDK reader is tolerant where the shell-out it replaced
+ * was strict. `listAllItemMetadata` resolves with an empty array for a path that
+ * does not exist, for a path that is a regular file (swallowing `ENOTDIR`), and
+ * for a directory that is not a tracker — all indistinguishable from a tracker
+ * that legitimately has no items. Without this check a mistyped `--path` /
+ * `--pm-path` would make `analyze`, `cycles`, `critical-path`, `cypher` and the
+ * exporters report a confident empty graph and exit 0, where the previous
+ * `pm list-all` invocation exited non-zero. Reporting an empty answer for a bad
+ * input is worse than failing, because nothing downstream can detect it.
+ *
+ * A tracker is identified by the artefacts `pm init` always writes: `settings.json`
+ * and the `schema/` directory. Requiring either (rather than both) keeps older
+ * trackers readable while still rejecting an arbitrary directory.
+ *
+ * Filed upstream as unbraind/pm-cli#814; this guard restores the previous failure
+ * semantics locally and independently of that fix.
+ *
+ * @param pmRoot Candidate tracker root.
+ * @returns The same path, once validated, so callers can wrap in place.
+ */
+export declare function assertPmTracker(pmRoot: string): string;
 /**
  * Build a workspace graph (nodes + relationships) from pm item metadata.
  *
@@ -87,9 +115,12 @@ export type Graph = {
  * @param items - pm item metadata to project.
  * @param workspace - Workspace path, recorded on the returned graph.
  * @param depsByItem - Extra dependency records keyed by item id.
+ * @param options - Set includeFacets to false for an item-only graph with unambiguous missing-item endpoints.
  * @returns The shaped graph with project metadata.
  */
-export declare function graphFromItems(items: readonly ItemMetadata[], workspace: string, depsByItem: Map<string, Array<Record<string, unknown>>>): Graph;
+export declare function graphFromItems(items: readonly ItemMetadata[], workspace: string, depsByItem: Map<string, Array<Record<string, unknown>>>, options?: {
+    includeFacets?: boolean;
+}): Graph;
 type AnalyticsFlags = {
     json: boolean;
     includeClosed: boolean;
@@ -106,7 +137,7 @@ type AnalyticsFlags = {
 /**
  * Parse the shared analytics flags (--json, --include-closed, --root, --depth,
  * --format, --filter) and collect remaining positional arguments. Throws a USAGE
- * CommandError on a malformed --depth, an invalid --format, a malformed
+ * An expected error on a malformed --depth, an invalid --format, a malformed
  * --filter, or a value-less --root/--depth/--format/--filter.
  */
 export declare function parseAnalyticsFlags(args: string[]): AnalyticsFlags;
@@ -123,7 +154,7 @@ export type NodeFilterEntry = {
 export type NodeFilter = NodeFilterEntry[];
 /**
  * Parse one or more `key=value[,value]` filter terms into a NodeFilter.
- * Throws a USAGE CommandError on a missing `=`, an unsupported key, or an
+ * Throws a USAGE expected error on a missing `=`, an unsupported key, or an
  * empty value list. Values are matched case-insensitively.
  */
 export declare function parseNodeFilter(raw: string[]): NodeFilter;
@@ -259,7 +290,7 @@ export declare function cyclesSubgraph(graph: Graph, cycles: string[][]): Graph;
  * `--direction` value. The canonical engine uses edge-orientation terms:
  * `incoming` = downstream dependents (items that break if <id> changes —
  * exactly the legacy `reverseReachable` semantics), `outgoing` = upstream
- * prerequisites/blockers, `both` = union. Throws a USAGE `CommandError` on an
+ * prerequisites/blockers, `both` = union. Throws a USAGE `PmCliExpectedError` on an
  * unknown logical direction.
  */
 export declare function mapImpactDirection(logical: string): "incoming" | "outgoing" | "both";