pm-graph 2026.10.20 → 2026.10.23

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 2026.10.23 - 2026-10-23
+
+### Changed
+
+- Adopt pm-github 2026.10.16: default-branch-safe gated sync and daily gated closeout PRs ([pm-graph-mupl](https://github.com/unbraind/pm-graph/blob/main/.agents/pm/chores/pm-graph-mupl.toon))
+- Enable the gated GitHub issue sync and drop the braces chain ([pm-graph-maint1014](https://github.com/unbraind/pm-graph/blob/main/.agents/pm/chores/pm-graph-maint1014.toon))
+
+### Fixed
+
+- A release run bumped and committed a new version every night while publishing was impossible, because the only externally-failable step runs last ([pm-graph-wos1](https://github.com/unbraind/pm-graph/blob/main/.agents/pm/issues/pm-graph-wos1.toon))
+- Fix release publish ordering ahead of protected main push ([pm-graph-ihhe](https://github.com/unbraind/pm-graph/blob/main/.agents/pm/issues/pm-graph-ihhe.toon))
+- Committed CHANGELOG.md drifts from deterministic regeneration after the pm-graph-3svp type classification change, breaking changelog:check on every PR ([pm-graph-brgk](https://github.com/unbraind/pm-graph/blob/main/.agents/pm/issues/pm-graph-brgk.toon))
+- Refresh managed pm-github extension for project-local PM CLI 2026.9.27 ([pm-graph-ipvn](https://github.com/unbraind/pm-graph/blob/main/.agents/pm/issues/pm-graph-ipvn.toon))
+- Graph export uses quadratic item and edge scans on large trackers ([pm-graph-3a1p](https://github.com/unbraind/pm-graph/blob/main/.agents/pm/issues/pm-graph-3a1p.toon))
+- Remove vulnerable braces dependency from certification toolchain ([pm-graph-g8uc](https://github.com/unbraind/pm-graph/blob/main/.agents/pm/issues/pm-graph-g8uc.toon))
+- The publish-attestation gate misses a publish routed through an unquoted shell variable ([pm-graph-ifqz](https://github.com/unbraind/pm-graph/blob/main/.agents/pm/issues/pm-graph-ifqz.toon))
+- The changelog gate stamps an untagged version with the current date, so its verdict flips every midnight with no commit ([pm-graph-4glq](https://github.com/unbraind/pm-graph/blob/main/.agents/pm/issues/pm-graph-4glq.toon))
+- The release job authenticated with a stored npm token that expired, so publishing stopped while every other gate stayed green ([pm-graph-ybzl](https://github.com/unbraind/pm-graph/blob/main/.agents/pm/issues/pm-graph-ybzl.toon))
+
+### Other
+
+- Cover the output_format decline contract with real SDK harness tests instead of a registration-only assertion ([pm-graph-vgj0](https://github.com/unbraind/pm-graph/blob/main/.agents/pm/tasks/pm-graph-vgj0.toon))
+- Bring pm-graph to real 100% line/branch/function coverage and raise the gate to 100 ([pm-graph-6zil](https://github.com/unbraind/pm-graph/blob/main/.agents/pm/tasks/pm-graph-6zil.toon))
+- Render package visuals with build-time Triplicate tokens ([pm-graph-triplicate](https://github.com/unbraind/pm-graph/blob/main/.agents/pm/tasks/pm-graph-triplicate.toon))
+- Certify pm-graph on PM CLI/SDK 2026.10.4 and consolidate pending dependency updates ([pm-graph-lcmc](https://github.com/unbraind/pm-graph/blob/main/.agents/pm/chores/pm-graph-lcmc.toon))
+
 ## 2026.10.14 - 2026-10-14
 
 ### Added

package/README.md

@@ -304,11 +304,103 @@ Example output:
 }
 ```
 
+## Without git
+
+All offline graph commands, including `blocker-cuts`, and the graph exporter
+work in plain initialized trackers without Git. Neo4j commands need their
+documented database configuration and connectivity; they also do not need a
+Git repository.
+
 ## Offline Analytics
 
-These commands analyze the workspace dependency graph **entirely offline** — no Neo4j required. They operate on **structural edges only** (`BLOCKED_BY`, `CHILD_OF`, and dependency edges such as `BLOCKS`/`RELATED`) between real items; facet edges (type/status/assignee/sprint/release) and tag edges are deliberately excluded so cycle, path, and centrality results stay meaningful.
+### `pm pm-graph blocker-cuts <goal>`
 
-Closed/canceled items are excluded by default; pass `--include-closed` to keep them. `analyze`, `cycles`, `critical-path`, and `topo-sort` also accept `--root <id>` / `--depth <n>` to scope the analysis to a neighborhood. All analytics commands accept `--filter type=...|status=...` to keep only items matching the given type/status (same-key values are ORed; distinct keys are ANDed); non-item nodes (facets/tags) are always kept. `cycles` and `critical-path` additionally accept `--format <text|mermaid|graphml|dot>` (default `text`) to render the relevant subgraph as a diagram for docs — `dot` emits a Graphviz `digraph` consumable by `dot`, `neato`, etc.
+Return alternative **inclusion-minimal blocker frontiers**, smallest cardinality
+first, with separate source, graph and search completeness receipts. This is a
+graph-view data operation; it complements core dominators/articulation/plan/impact
+and this package's path/critical-path commands.
+
+```bash
+pm pm-graph blocker-cuts goal-id
+pm pm-graph blocker-cuts goal-id --max-cuts 16 --max-states 20000 --json
+```
+
+Every upstream unresolved prerequisite path must meet a returned cut. All
+prerequisites are conjunctive: for `goal -> a -> {b,c}`, the alternatives are
+`[a]` and `[b,c]`. These are **plans**: resolving `b,c` clears the upstream
+frontier, but `a` still needs completion. Each cut's `immediatelyUnblocked` is
+true only when that set includes every immediate unresolved prerequisite. This
+does not predict effort, duration, automatic task completion, or approvals.
+
+The command uses an extension-free, strict, full, unbounded SDK read (including
+terminal items), and exact goal ids. `BLOCKED_BY`, `DEPENDS_ON`, `REQUIRES` and
+reversed `BLOCKS` are prerequisites; hierarchy, related links and facets are
+excluded. Terminal statuses from the tracker registry stop traversal. A resolved
+goal or a goal with no active blockers returns the empty cut `[[]]`.
+
+`source` certifies the read, while `receipt.graph` describes the active goal cone
+in that supplied snapshot. It cannot prove that missing real-world relationships
+were recorded, nor provide transaction isolation from concurrent tracker edits.
+Unknown referenced items/statuses refuse with `INCOMPLETE_GRAPH`; a relevant
+cycle refuses with `CYCLE` and one closed cycle witness. Unrelated cycles and
+missing references outside the active cone do not prevent a goal proof.
+Missing-data receipts include total counts and at most 32 example ids per kind.
+
+`receipt.search.complete` means **all** inclusion-minimal cuts were enumerated.
+`completeThroughSize` certifies fully searched cardinalities;
+`minimumCardinality` is the proven smallest size, or `null` if no cut was found.
+Partial results remain individually minimal. Never interpret an empty partial
+list as "unblocked". To act on displayed rows, also inspect the host's
+`read_output` receipt: output compaction is independent of search completeness.
+
+| Budget | Default | Hard maximum |
+| --- | ---: | ---: |
+| `--max-states` (candidate subsets) | 20000 | 1000000 |
+| `--max-work` (search visits, edges, subset comparisons) | 2000000 | 20000000 |
+| `--max-cuts` (returned alternatives) | 32 | 256 |
+| `--max-size` (frontier cardinality) | 8 | 64 |
+
+Enumeration stops deterministically at the first cap and reports its name;
+raising that budget and rerunning restarts the search. Preflight scans are
+input-capped at 100000 nodes / 500000 relationships and 512 active unresolved
+vertices. Oversized snapshots refuse with `GRAPH_LIMIT` and a scoping remedy.
+`INVALID_OPTIONS`, `INVALID_GRAPH`, `UNKNOWN_GOAL`, and `SOURCE_INCOMPLETE` also
+include remedies. CLI refusals exit 2 (unknown goals exit 3); successful bounded
+searches exit 0, with partiality explicit in the receipt.
+
+The typed SDK has no filesystem, Git or Neo4j dependency:
+
+```ts
+import { minimalBlockerCuts } from "pm-graph";
+import type { BlockerCutResult } from "pm-graph";
+
+const result: BlockerCutResult = minimalBlockerCuts(snapshot, "goal-id", {
+  maxCuts: 16,
+  // For custom workflows, pass disjoint resolvedStatuses/unresolvedStatuses.
+});
+if (!result.ok) console.error(result.refusal.code, result.refusal.remedy);
+else renderFrontiers(result.cuts, result.receipt);
+```
+
+SDK callers must certify their own complete source read; the pure function only
+certifies the supplied goal cone. Successful results contain ids and receipts,
+excluding item bodies, titles and local paths. `SOURCE_INCOMPLETE` remedies retain
+the original source error message to distinguish invalid roots, strict-read
+failures and bad settings; these diagnostics can include tracker paths.
+See [the worked example](docs/blocker-cuts-example.md).
+
+### Other offline analytics
+
+The following commands analyze the workspace dependency graph **entirely offline** — no Neo4j required. They operate on **structural edges only** (`BLOCKED_BY`, `CHILD_OF`, and dependency edges such as `BLOCKS`/`RELATED`) between real items; facet edges (type/status/assignee/sprint/release) and tag edges are deliberately excluded so cycle, path, and centrality results stay meaningful.
+
+Closed/canceled items are excluded by default; pass `--include-closed` to keep them. `analyze`, `cycles`, `critical-path`, and `topo-sort` also accept `--root <id>` / `--depth <n>` to scope the analysis to a neighborhood. `analyze`, `cycles`, `critical-path`, `topo-sort`, `path`, `impact`, and `explain` accept `--filter type=...|status=...` to keep only items matching the given type/status (same-key values are ORed; distinct keys are ANDed); non-item nodes (facets/tags) are always kept. `cycles` and `critical-path` additionally accept `--format <text|mermaid|graphml|dot>` (default `text`) to render the relevant subgraph as a diagram for docs — `dot` emits a Graphviz `digraph` consumable by `dot`, `neato`, etc.
+
+The host dependency contract stores `A --blocked_by--> B` and `B --blocks--> A`
+as the same prerequisite: A waits for B. Offline analytics normalize `BLOCKS`
+to item → blocker direction before computing paths, cycles, execution order,
+impact, depth, and explanations. Graph exports and diagram relationships retain
+their original stored endpoints and relation types. The edge-array SDK helpers
+(such as `topoSort`) expect this normalized item → blocker direction.
 
 ### `pm pm-graph analyze`
 
@@ -458,6 +550,76 @@ pm pm-graph impact pm-vc4q --json
 { "ok": true, "id": "pm-vc4q", "count": 3, "impacted": ["pm-0wtl", "pm-8k1m", "pm-yol1"] }
 ```
 
+## Snapshot graph change impact
+
+`compareGraphSnapshots(before, after, goal, options?)` compares two explicit
+`Graph` SDK values. The CLI accepts regular JSON files containing those values
+or the existing export command's `{ graph: ... }` envelope:
+
+```bash
+pm pm-graph snapshot-impact before.json after.json goal-id --limit 16 --json
+pm pm-graph snapshot-impact before.json after.json goal-id --limit 16 --offset 16
+```
+
+The result reports gained/lost upstream prerequisites and downstream dependents,
+added/removed minimal blocker frontiers, and explicit `SUPPORTS`/`EVIDENCE_FOR`
+links into the goal or its upstream prerequisites. Removed facts carry the
+earlier node title and status, even if that node was deleted. A deleted goal is
+valid when it exists in the earlier snapshot. Reordering inputs, duplicate
+edges and nonsemantic title/capture metadata edits produce no changes.
+
+The gating policy is `BLOCKED_BY`, `DEPENDS_ON`, `REQUIRES`, and reversed
+`BLOCKS`; hierarchy, facets and other relationships do not imply prerequisites.
+Reachability is structural, including terminal items. Blocker frontiers stop
+at terminal items and require all upstream paths to intersect a cut. Resolving
+a frontier still leaves intermediate work; `immediatelyUnblocked` identifies
+cuts containing every direct prerequisite. Both cut searches must finish before
+differences are reported. Cycles, missing cone endpoints, unknown active statuses
+and exhausted cut searches return typed refusals with remedies. A dangling
+reference to a deleted node retains its earlier explanation in `missingNode`
+while refusing to infer cut differences from incomplete input. For custom
+workflows, pass `cutOptions.resolvedStatuses`/`unresolvedStatuses` in the SDK or
+`--resolved-statuses done,canceled --unresolved-statuses ready,working` in the CLI.
+
+`receipt.output` exposes the exact total, returned/omitted counts and
+`nextOffset`. Keep both input files immutable while recovering pages.
+Defaults are 32 rows and 2,000,000 traversal work units; `--limit` accepts
+1..256 and `--max-work` accepts 1..20,000,000. Cut budgets have separate
+`--cut-max-states`, `--cut-max-work`, `--cut-max-cuts` and `--cut-max-size` flags
+(defaults: 20,000 / 2,000,000 / 32 / 8). Each snapshot is limited to 10,000 nodes,
+50,000 relationships and, for CLI files, 16 MiB. The active blocker cone is
+limited to 512 unresolved items including the goal; this is a preflight cap,
+not a completion guarantee. Completion requires `--cut-max-size` (default 8,
+hard cap 64) to be at least the number of unresolved prerequisites in the
+active cone, excluding the goal. A chain of 9 unresolved prerequisites therefore
+returns `CUT_SEARCH_INCOMPLETE` with defaults; more than 64 cannot complete
+under the current search. Other cut budgets can stop even smaller searches.
+Explanation titles/statuses are clipped to
+160/64 Unicode code points with `textClipped: true`; ids are limited to 256
+characters. The host's JSON/TOON projection and token budgets also apply to the
+declared `changes` rows. Refusals exit 2 (unknown goal: 3) and preserve
+`refusal.code`, `refusal.remedy` and the failing side.
+
+This is a comparison over the supplied snapshots. Core owns snapshot capture
+and storage; pm-context owns resume packets. Certify backend reads separately
+(for example with `listAllComplete`) before `graphFromItems` projection. The
+projection includes item relationships and facets; evidence nodes and support
+edges must be supplied explicitly by the caller's backend. Support is a linked
+structural assertion, not verification of a document, file, test run or URL.
+The comparison never accesses those resources or either live backend.
+
+See the [SDK and CLI example](docs/snapshot-impact-example.md) and the
+[public tracker validation](docs/snapshot-impact-validation.md).
+
+## Without git
+
+Graph projection, 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
+git repository; the no-git regression runs the installed CLI with git absent
+from PATH.
+
 ## Graph Model
 
 - **`PmItem`** nodes for real pm items, labelled with item type (e.g. `task`, `bug`).

package/dist/blocker-cuts-command.d.ts

@@ -0,0 +1,21 @@
+import { listAllComplete } from "@unbrained/pm-cli/sdk";
+import type { PmCompleteListCertificate } from "@unbrained/pm-cli/sdk";
+import type { BlockerCutReceipt, BlockerCutRefusalCode } from "./blocker-cuts.ts";
+import type { CommandContext, ExtensionApi, Graph } from "./index.ts";
+/** Structured CLI refusal; the host honors exit_code while retaining the full result. */
+export type BlockerCutCommandRefusal = {
+    ok: false;
+    exit_code: number;
+    code: BlockerCutRefusalCode | "SOURCE_INCOMPLETE";
+    remediation: string;
+    refusal: {
+        code: BlockerCutCommandRefusal["code"];
+        remedy: string;
+    };
+    /** Declared row collection is present even when the host delivers a refusal. */
+    cuts: [];
+    receipt?: BlockerCutReceipt;
+    source?: PmCompleteListCertificate;
+};
+/** Register the offline command; source reads are strict, complete, and extension-free. */
+export declare function registerBlockerCuts(api: ExtensionApi, resolveRoot: (context: CommandContext) => string, project: (items: Awaited<ReturnType<typeof listAllComplete>>["items"], root: string) => Graph): void;

package/dist/blocker-cuts-command.js

@@ -0,0 +1,74 @@
+import { 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) {
+    return { ok: false, code, remediation: remedy, refusal: { code, remedy }, cuts: [],
+        exit_code: code === "UNKNOWN_GOAL" ? 3 : 2, receipt, source };
+}
+/** Register the offline command; source reads are strict, complete, and extension-free. */
+export function registerBlockerCuts(api, resolveRoot, project) {
+    api.registerCommand({
+        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" }],
+        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 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")
+                    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.`);
+                }
+                else
+                    positionals.push(arg);
+            }
+            if (positionals.length !== 1)
+                return commandRefusal("INVALID_OPTIONS", "Use pm pm-graph blocker-cuts <exact-goal-id>; see --help for budgets.");
+            let source;
+            let snapshot;
+            let root;
+            try {
+                root = resolveRoot(context);
+                snapshot = await listAllComplete({}, { pmRoot: root, noExtensions: true });
+                source = snapshot.complete_list;
+                const registry = resolveRuntimeStatusRegistry((await readSettings(root)).schema);
+                options.resolvedStatuses = [...registry.terminal_statuses];
+                options.unresolvedStatuses = [...registry.by_id.keys()].filter((status) => !registry.terminal_statuses.has(status));
+            }
+            catch (error) {
+                const cause = error instanceof Error ? error.message : String(error);
+                return commandRefusal("SOURCE_INCOMPLETE", `Restore a readable complete tracker; run pm list --all --full --strict-read --output-limit unbounded --output-budget unbounded, then retry. Cause: ${cause}`);
+            }
+            const graph = project(snapshot.items, root);
+            const result = minimalBlockerCuts(graph, positionals[0], options);
+            if (!result.ok)
+                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

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

package/dist/blocker-cuts.d.ts

@@ -0,0 +1,87 @@
+import type { Graph } from "./index.ts";
+/** Deterministic limits; input size is capped and enumeration is work-budgeted. */
+export type BlockerCutOptions = {
+    maxStates?: number;
+    maxWork?: number;
+    maxCuts?: number;
+    maxSize?: number;
+    /** Terminal statuses stop traversal; custom registries can supply their own sets. */
+    resolvedStatuses?: readonly string[];
+    /** Missing/unrecognized statuses refuse a proof instead of guessing actionability. */
+    unresolvedStatuses?: readonly string[];
+};
+/** One inclusion-minimal vertex separator, sorted by id. */
+export type BlockerCut = {
+    blockers: string[];
+    /** True only if resolving this set also satisfies every immediate prerequisite. */
+    immediatelyUnblocked: boolean;
+};
+/** Independent receipts for the supplied graph and the bounded enumeration. */
+export type BlockerCutReceipt = {
+    graph: {
+        scope: "supplied-snapshot";
+        edgePolicy: "BLOCKED_BY|DEPENDS_ON|REQUIRES|reverse:BLOCKS";
+        nodes: number;
+        relationships: number;
+        reachableUnresolved: number;
+        complete: boolean;
+        unknownNodes: string[];
+        unknownNodeCount: number;
+        unknownStatuses: string[];
+        unknownStatusCount: number;
+        cycle: string[];
+    };
+    search: {
+        complete: boolean;
+        reason: "exhausted" | "maxStates" | "maxWork" | "maxCuts" | "maxSize" | "refused";
+        states: number;
+        work: number;
+        completeThroughSize: number;
+        minimumCardinality: number | null;
+        limits: {
+            maxStates: number;
+            maxWork: number;
+            maxCuts: number;
+            maxSize: number;
+        };
+    };
+};
+/** Stable refusal codes with actionable remedies, usable by a graph view without parsing text. */
+export type BlockerCutRefusalCode = "INVALID_OPTIONS" | "GRAPH_LIMIT" | "INVALID_GRAPH" | "UNKNOWN_GOAL" | "INCOMPLETE_GRAPH" | "CYCLE";
+/** Compact result: frontier cuts describe plans, not automatic completion of intervening work. */
+export type BlockerCutResult = {
+    ok: true;
+    goal: string;
+    semantics: "upstream-frontier";
+    goalResolved: boolean;
+    immediateBlockers: string[];
+    cuts: BlockerCut[];
+    receipt: BlockerCutReceipt;
+} | {
+    ok: false;
+    goal: string;
+    refusal: {
+        code: BlockerCutRefusalCode;
+        remedy: string;
+    };
+    receipt: BlockerCutReceipt;
+};
+/**
+ * Enumerate inclusion-minimal unresolved vertex cuts between a goal and its
+ * upstream unresolved leaves. Every prerequisite is conjunctive. Resolving a
+ * frontier clears all upstream blocking paths; intermediate work still needs
+ * completion. `immediatelyUnblocked` distinguishes direct eligibility.
+ *
+ * Only BLOCKED_BY, DEPENDS_ON, REQUIRES and reversed BLOCKS edges are gating;
+ * hierarchy, facets and RELATED edges never imply prerequisites. Resolved
+ * nodes stop traversal. Cycles, dangling prerequisites and unknown statuses in
+ * the active goal cone refuse a proof. Completeness covers the supplied
+ * snapshot only; callers must separately certify their source read.
+ *
+ * Cardinality-ordered combination search proves minimality before emitting a
+ * cut, including when truncated. Work counts visited vertices/edges and subset
+ * comparisons; hard caps bound both output and exponential search. Preflight
+ * scans at most 100,000 nodes and 500,000 relationships; the active cone is
+ * limited to 512 unresolved vertices. No filesystem, git or service access.
+ */
+export declare function minimalBlockerCuts(graph: Graph, goal: string, options?: BlockerCutOptions): BlockerCutResult;

package/dist/blocker-cuts.js

@@ -0,0 +1,227 @@
+const DEFAULT_LIMITS = { maxStates: 20_000, maxWork: 2_000_000, maxCuts: 32, maxSize: 8 };
+const HARD_LIMITS = { maxStates: 1_000_000, maxWork: 20_000_000, maxCuts: 256, maxSize: 64 };
+const FORWARD = new Set(["BLOCKED_BY", "DEPENDS_ON", "REQUIRES"]);
+/** Find one closed directed cycle iteratively, without enumerating exponentially many paths. */
+function cycleWitness(adjacency, root) {
+    const color = new Map();
+    const stack = [{ id: root, next: 0 }];
+    color.set(root, 1);
+    while (stack.length) {
+        const frame = stack[stack.length - 1];
+        const neighbors = adjacency.get(frame.id);
+        if (frame.next === neighbors.length) {
+            color.set(frame.id, 2);
+            stack.pop();
+            continue;
+        }
+        const id = neighbors[frame.next++];
+        if (color.get(id) === 1) {
+            return [...stack.slice(stack.findIndex((entry) => entry.id === id)).map((entry) => entry.id), id];
+        }
+        if (!color.has(id)) {
+            color.set(id, 1);
+            stack.push({ id, next: 0 });
+        }
+    }
+    return [];
+}
+/**
+ * Enumerate inclusion-minimal unresolved vertex cuts between a goal and its
+ * upstream unresolved leaves. Every prerequisite is conjunctive. Resolving a
+ * frontier clears all upstream blocking paths; intermediate work still needs
+ * completion. `immediatelyUnblocked` distinguishes direct eligibility.
+ *
+ * Only BLOCKED_BY, DEPENDS_ON, REQUIRES and reversed BLOCKS edges are gating;
+ * hierarchy, facets and RELATED edges never imply prerequisites. Resolved
+ * nodes stop traversal. Cycles, dangling prerequisites and unknown statuses in
+ * the active goal cone refuse a proof. Completeness covers the supplied
+ * snapshot only; callers must separately certify their source read.
+ *
+ * Cardinality-ordered combination search proves minimality before emitting a
+ * cut, including when truncated. Work counts visited vertices/edges and subset
+ * comparisons; hard caps bound both output and exponential search. Preflight
+ * scans at most 100,000 nodes and 500,000 relationships; the active cone is
+ * limited to 512 unresolved vertices. No filesystem, git or service access.
+ */
+export function minimalBlockerCuts(graph, goal, options = {}) {
+    const limits = { ...DEFAULT_LIMITS };
+    const receipt = {
+        graph: { scope: "supplied-snapshot", edgePolicy: "BLOCKED_BY|DEPENDS_ON|REQUIRES|reverse:BLOCKS",
+            nodes: graph.nodes.length, relationships: graph.relationships.length,
+            reachableUnresolved: 0, complete: false, unknownNodes: [], unknownNodeCount: 0,
+            unknownStatuses: [], unknownStatusCount: 0, cycle: [] },
+        search: { complete: false, reason: "refused", states: 0, work: 0, completeThroughSize: 0,
+            minimumCardinality: null, limits },
+    };
+    const refuse = (code, remedy) => ({ ok: false, goal, refusal: { code, remedy }, receipt });
+    for (const key of Object.keys(limits)) {
+        const value = options[key] ?? limits[key];
+        if (!Number.isSafeInteger(value) || value < 1 || value > HARD_LIMITS[key]) {
+            return refuse("INVALID_OPTIONS", `Set ${key} to an integer in 1..${HARD_LIMITS[key]}.`);
+        }
+        limits[key] = value;
+    }
+    const resolved = new Set(options.resolvedStatuses ?? ["closed", "canceled"]);
+    const unresolved = new Set(options.unresolvedStatuses ?? ["open", "in_progress", "blocked"]);
+    if ([...resolved].some((status) => unresolved.has(status))) {
+        return refuse("INVALID_OPTIONS", "Supply disjoint resolvedStatuses and unresolvedStatuses.");
+    }
+    if (graph.nodes.length > 100_000 || graph.relationships.length > 500_000) {
+        return refuse("GRAPH_LIMIT", "Supply a certified goal-scoped snapshot below 100000 nodes and 500000 relationships, retaining every prerequisite.");
+    }
+    const nodes = new Map();
+    for (const node of graph.nodes) {
+        if (nodes.has(node.id))
+            return refuse("INVALID_GRAPH", "Supply unique node ids; reload the complete tracker snapshot.");
+        nodes.set(node.id, node);
+    }
+    if (!nodes.get(goal)?.labels.includes("PmItem")) {
+        return refuse("UNKNOWN_GOAL", "Select an exact PmItem id from the complete tracker snapshot.");
+    }
+    const allEdges = new Map();
+    for (const rel of graph.relationships) {
+        if (!FORWARD.has(rel.type) && rel.type !== "BLOCKS")
+            continue;
+        const from = rel.type === "BLOCKS" ? rel.to : rel.from;
+        const to = rel.type === "BLOCKS" ? rel.from : rel.to;
+        if (!allEdges.has(from))
+            allEdges.set(from, new Set());
+        allEdges.get(from).add(to);
+    }
+    const adjacency = new Map();
+    const pending = [goal];
+    const seen = new Set();
+    while (pending.length) {
+        const id = pending.pop();
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        const node = nodes.get(id);
+        if (!node?.labels.includes("PmItem")) {
+            receipt.graph.unknownNodeCount++;
+            if (receipt.graph.unknownNodes.length < 32)
+                receipt.graph.unknownNodes.push(id);
+            continue;
+        }
+        const status = String(node.properties.status);
+        if (resolved.has(status))
+            continue;
+        if (!unresolved.has(status)) {
+            receipt.graph.unknownStatusCount++;
+            if (receipt.graph.unknownStatuses.length < 32)
+                receipt.graph.unknownStatuses.push(id);
+        }
+        adjacency.set(id, []);
+        receipt.graph.reachableUnresolved = adjacency.size;
+        if (adjacency.size > 512)
+            return refuse("GRAPH_LIMIT", "Reduce the active goal cone below 513 unresolved items, retaining every prerequisite; inspect immediate blockers first.");
+        for (const next of allEdges.get(id) ?? []) {
+            const target = nodes.get(next);
+            if (target?.labels.includes("PmItem") && resolved.has(String(target.properties.status)))
+                continue;
+            adjacency.get(id).push(next);
+        }
+        adjacency.get(id).sort();
+        for (const next of adjacency.get(id))
+            pending.push(next);
+    }
+    receipt.graph.reachableUnresolved = adjacency.size;
+    receipt.graph.unknownNodes.sort();
+    receipt.graph.unknownStatuses.sort();
+    if (receipt.graph.unknownNodeCount || receipt.graph.unknownStatusCount) {
+        return refuse("INCOMPLETE_GRAPH", "Reload all referenced items with statuses; supply registry status sets for custom workflows. Do not filter or truncate the goal cone.");
+    }
+    const goalResolved = resolved.has(String(nodes.get(goal).properties.status));
+    if (!goalResolved)
+        receipt.graph.cycle = cycleWitness(adjacency, goal);
+    receipt.graph.complete = true;
+    if (receipt.graph.cycle.length)
+        return refuse("CYCLE", "Break or explicitly resolve the reported dependency cycle, then reload and retry.");
+    const immediateBlockers = adjacency.get(goal) ?? [];
+    const cuts = [];
+    const finish = (reason) => {
+        receipt.search.reason = reason;
+        receipt.search.complete = reason === "exhausted";
+        return { ok: true, goal, semantics: "upstream-frontier", goalResolved, immediateBlockers, cuts, receipt };
+    };
+    if (!immediateBlockers.length) {
+        cuts.push({ blockers: [], immediatelyUnblocked: true });
+        receipt.search.minimumCardinality = 0;
+        return finish("exhausted");
+    }
+    const candidates = [...adjacency.keys()].filter((id) => id !== goal).sort();
+    const leaves = new Set(candidates.filter((id) => adjacency.get(id).length === 0));
+    const spend = () => {
+        if (receipt.search.work === limits.maxWork)
+            return false;
+        receipt.search.work++;
+        return true;
+    };
+    for (let size = 1; size <= Math.min(limits.maxSize, candidates.length); size++) {
+        const indices = Array.from({ length: size }, (_, i) => i);
+        let more = true;
+        while (more) {
+            if (receipt.search.states === limits.maxStates)
+                return finish("maxStates");
+            receipt.search.states++;
+            const selected = indices.map((i) => candidates[i]);
+            const selectedSet = new Set(selected);
+            let redundant = false;
+            for (const cut of cuts) {
+                let contains = true;
+                for (const id of cut.blockers) {
+                    if (!spend())
+                        return finish("maxWork");
+                    if (!selectedSet.has(id)) {
+                        contains = false;
+                        break;
+                    }
+                }
+                if (contains) {
+                    redundant = true;
+                    break;
+                }
+            }
+            if (!redundant) {
+                const visit = [goal];
+                const visited = new Set();
+                let separated = true;
+                while (visit.length) {
+                    if (!spend())
+                        return finish("maxWork");
+                    const id = visit.pop();
+                    if (selectedSet.has(id) || visited.has(id))
+                        continue;
+                    visited.add(id);
+                    if (leaves.has(id)) {
+                        separated = false;
+                        break;
+                    }
+                    for (const next of adjacency.get(id)) {
+                        if (!spend())
+                            return finish("maxWork");
+                        visit.push(next);
+                    }
+                }
+                if (separated) {
+                    cuts.push({ blockers: selected, immediatelyUnblocked: immediateBlockers.every((id) => selectedSet.has(id)) });
+                    receipt.search.minimumCardinality ??= size;
+                    if (cuts.length === limits.maxCuts)
+                        return finish("maxCuts");
+                }
+            }
+            let position = size - 1;
+            while (position >= 0 && indices[position] === candidates.length - size + position)
+                position--;
+            more = position >= 0;
+            if (more) {
+                indices[position]++;
+                for (let next = position + 1; next < size; next++)
+                    indices[next] = indices[next - 1] + 1;
+            }
+        }
+        receipt.search.completeThroughSize = size;
+    }
+    return finish(limits.maxSize < candidates.length ? "maxSize" : "exhausted");
+}
+//# sourceMappingURL=blocker-cuts.js.map