@unbrained/pm-cli 2026.8.19 → 2026.8.21
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +2 -2
- package/CHANGELOG.md +41 -0
- package/dist/cli/error-guidance.d.ts +20 -0
- package/dist/cli/error-guidance.js +29 -30
- package/dist/cli/register-list-query.js +12 -10
- package/dist/cli/register-structured-mutation.d.ts +2 -0
- package/dist/cli/register-structured-mutation.js +29 -6
- package/dist/cli-bundle/bundle-manifest.json +156 -148
- package/dist/cli-bundle/chunks/chunk-2MA6ZQVZ.js +197 -0
- package/dist/cli-bundle/chunks/{chunk-4NRRH7AM.js → chunk-3AFAUHUE.js} +2 -2
- package/dist/cli-bundle/chunks/chunk-7VHZS727.js +5 -0
- package/dist/cli-bundle/chunks/chunk-BKYB45NQ.js +2092 -0
- package/dist/cli-bundle/chunks/{chunk-BHYMXLAE.js → chunk-BUNIEJNE.js} +2 -2
- package/dist/cli-bundle/chunks/{chunk-QXSH7BLM.js → chunk-JSLOFXGA.js} +3 -3
- package/dist/cli-bundle/chunks/chunk-LARJJ3RK.js +3 -0
- package/dist/cli-bundle/chunks/{chunk-TOXJM4WA.js → chunk-LOVTQ52Z.js} +2 -2
- package/dist/cli-bundle/chunks/chunk-N3DSV4CH.js +77 -0
- package/dist/cli-bundle/chunks/chunk-OCLPLFAY.js +35 -0
- package/dist/cli-bundle/chunks/chunk-S4IRYKBU.js +13 -0
- package/dist/cli-bundle/chunks/register-list-query-F57EWDEF.js +11 -0
- package/dist/cli-bundle/chunks/{register-mutation-AUWVCW4M.js → register-mutation-7IY2D5KO.js} +20 -20
- package/dist/cli-bundle/chunks/{register-operations-PZQPHXW5.js → register-operations-FALL3YTU.js} +2 -2
- package/dist/cli-bundle/chunks/{register-setup-I4LUHGVW.js → register-setup-HXU7IZZD.js} +2 -2
- package/dist/cli-bundle/focused-chunks/chunk-2NIY5NKG.js +18 -0
- package/dist/cli-bundle/focused-chunks/{chunk-US7VEYZG.js → chunk-4ERLO7QD.js} +2 -2
- package/dist/cli-bundle/focused-chunks/chunk-7WZRLCYF.js +50 -0
- package/dist/cli-bundle/focused-chunks/{chunk-MCZXYZAF.js → chunk-CKKQSJNN.js} +2 -2
- package/dist/cli-bundle/focused-chunks/chunk-EEFKYMDR.js +16 -0
- package/dist/cli-bundle/focused-chunks/{chunk-ZBIQQYMI.js → chunk-F2A56DHV.js} +2 -2
- package/dist/cli-bundle/focused-chunks/{chunk-ESISGDAY.js → chunk-F4YEW5I2.js} +2 -2
- package/dist/cli-bundle/focused-chunks/{chunk-ODHQEECS.js → chunk-FH6DYED3.js} +2 -2
- package/dist/cli-bundle/focused-chunks/chunk-FJ22HNRP.js +2 -0
- package/dist/cli-bundle/focused-chunks/chunk-FV5ACOK7.js +2 -0
- package/dist/cli-bundle/focused-chunks/chunk-JEAVFOWM.js +2 -0
- package/dist/cli-bundle/focused-chunks/{chunk-EXBCLIBU.js → chunk-KDNG7TKQ.js} +2 -2
- package/dist/cli-bundle/focused-chunks/chunk-NJ63LOP6.js +155 -0
- package/dist/cli-bundle/focused-chunks/chunk-NXRTQ7HI.js +2 -0
- package/dist/cli-bundle/focused-chunks/{chunk-JDOMQ7VQ.js → chunk-TJ7EMJ46.js} +3 -3
- package/dist/cli-bundle/focused-chunks/chunk-UZE7XUZK.js +2 -0
- package/dist/cli-bundle/focused-chunks/{chunk-DKPLYW3L.js → chunk-YKBKIEAJ.js} +2 -2
- package/dist/cli-bundle/focused-chunks/{chunk-VXDSU5MC.js → chunk-ZOSEELYJ.js} +2 -2
- package/dist/cli-bundle/main.js +12 -12
- package/dist/cli-bundle/sdk-authoring.js +1 -1
- package/dist/cli-bundle/sdk-contracts.js +2 -2
- package/dist/cli-bundle/sdk-core.js +41 -41
- package/dist/cli-bundle/sdk-governance.js +1 -1
- package/dist/cli-bundle/sdk-graph.js +1 -1
- package/dist/cli-bundle/sdk-merge.js +32 -32
- package/dist/cli-bundle/sdk-query.js +1 -1
- package/dist/cli-bundle/sdk-runtime.js +1 -1
- package/dist/cli-bundle/sdk-testing.js +1 -1
- package/dist/cli-bundle/sdk.js +5 -5
- package/dist/core/output/mutation-projection.js +26 -2
- package/dist/core/shared/constants.d.ts +1 -5
- package/dist/core/shared/constants.js +3 -81
- package/dist/core/shared/errors.d.ts +16 -0
- package/dist/core/shared/errors.js +2 -2
- package/dist/core/shared/item-metadata-contract.d.ts +14 -0
- package/dist/core/shared/item-metadata-contract.js +90 -0
- package/dist/core/store/item-store.d.ts +60 -0
- package/dist/core/store/item-store.js +26 -94
- package/dist/core/store/tracker-preflight.d.ts +7 -0
- package/dist/core/store/tracker-preflight.js +142 -0
- package/dist/sdk/agent/closed-domain-contracts.d.ts +25 -0
- package/dist/sdk/agent/closed-domain-contracts.js +140 -0
- package/dist/sdk/agent/refusal-closure.d.ts +13 -1
- package/dist/sdk/agent/refusal-closure.js +45 -3
- package/dist/sdk/agent/refusal-reachability.d.ts +26 -0
- package/dist/sdk/agent/refusal-reachability.js +26 -2
- package/dist/sdk/agent/tracker-preflight-contracts.d.ts +63 -0
- package/dist/sdk/agent/tracker-preflight-contracts.js +127 -0
- package/dist/sdk/agent-capability-contracts.js +6 -11
- package/dist/sdk/annotations.js +6 -7
- package/dist/sdk/cli-contracts/completeness.js +8 -2
- package/dist/sdk/cli-contracts/enum-contracts.d.ts +4 -2
- package/dist/sdk/cli-contracts/enum-contracts.js +16 -6
- package/dist/sdk/cli-contracts/flag-contracts.d.ts +2 -0
- package/dist/sdk/cli-contracts/flag-contracts.js +11 -2
- package/dist/sdk/cli-contracts/flag-lexicon-contracts.d.ts +19 -2
- package/dist/sdk/cli-contracts/flag-lexicon-contracts.js +105 -5
- package/dist/sdk/cli-contracts/grammar-contracts.d.ts +2 -2
- package/dist/sdk/cli-contracts/grammar-contracts.js +5 -2
- package/dist/sdk/cli-contracts/runtime-contracts.js +7 -3
- package/dist/sdk/cli-contracts/tool-schema.js +7 -2
- package/dist/sdk/cli-contracts.d.ts +2 -2
- package/dist/sdk/cli-contracts.js +4 -4
- package/dist/sdk/config.d.ts +5 -0
- package/dist/sdk/config.js +5 -5
- package/dist/sdk/context-intent-runtime.js +7 -4
- package/dist/sdk/contracts.d.ts +2 -0
- package/dist/sdk/contracts.js +4 -2
- package/dist/sdk/core.d.ts +1 -1
- package/dist/sdk/core.js +3 -3
- package/dist/sdk/dependencies.js +5 -7
- package/dist/sdk/dependency-flag-validation.d.ts +1 -1
- package/dist/sdk/dependency-flag-validation.js +10 -4
- package/dist/sdk/environment/tracker-preflight.d.ts +6 -0
- package/dist/sdk/environment/tracker-preflight.js +10 -0
- package/dist/sdk/eval.js +5 -7
- package/dist/sdk/files.js +6 -10
- package/dist/sdk/generated/generated-error-code-catalog-part-1.js +110 -2
- package/dist/sdk/generated/generated-error-code-catalog-part-2.js +179 -46
- package/dist/sdk/governance/assurance.d.ts +36 -2
- package/dist/sdk/governance/assurance.js +184 -10
- package/dist/sdk/governance/gc.js +5 -6
- package/dist/sdk/governance/health.js +5 -6
- package/dist/sdk/governance/reindex.js +5 -6
- package/dist/sdk/governance/validate.d.ts +1 -2
- package/dist/sdk/governance/validate.js +6 -12
- package/dist/sdk/graph/governance.d.ts +7 -5
- package/dist/sdk/graph/governance.js +32 -16
- package/dist/sdk/graph/run.js +5 -7
- package/dist/sdk/graph/traversal.js +14 -5
- package/dist/sdk/history-compact.js +6 -9
- package/dist/sdk/history-read.js +5 -7
- package/dist/sdk/history-redact.js +5 -6
- package/dist/sdk/history-repair.js +6 -9
- package/dist/sdk/improvement-ledger.js +7 -10
- package/dist/sdk/index.d.ts +7 -3
- package/dist/sdk/index.js +8 -4
- package/dist/sdk/init-agent-guidance.d.ts +5 -3
- package/dist/sdk/init-agent-guidance.js +69 -9
- package/dist/sdk/lifecycle/append.d.ts +0 -5
- package/dist/sdk/lifecycle/append.js +5 -6
- package/dist/sdk/lifecycle/claim.d.ts +0 -5
- package/dist/sdk/lifecycle/claim.js +6 -9
- package/dist/sdk/lifecycle/close-many.d.ts +0 -5
- package/dist/sdk/lifecycle/close-many.js +5 -6
- package/dist/sdk/lifecycle/close.d.ts +0 -5
- package/dist/sdk/lifecycle/close.js +5 -6
- package/dist/sdk/lifecycle/copy.d.ts +0 -5
- package/dist/sdk/lifecycle/copy.js +5 -6
- package/dist/sdk/lifecycle/create.d.ts +0 -5
- package/dist/sdk/lifecycle/create.js +5 -9
- package/dist/sdk/lifecycle/delete.js +5 -6
- package/dist/sdk/lifecycle/focus.d.ts +0 -5
- package/dist/sdk/lifecycle/focus.js +5 -6
- package/dist/sdk/lifecycle/mcp-actions.d.ts +18 -0
- package/dist/sdk/lifecycle/mcp-actions.js +52 -0
- package/dist/sdk/lifecycle/plan.d.ts +0 -5
- package/dist/sdk/lifecycle/plan.js +5 -6
- package/dist/sdk/lifecycle/reopen.d.ts +44 -0
- package/dist/sdk/lifecycle/reopen.js +69 -0
- package/dist/sdk/lifecycle/restore.js +5 -6
- package/dist/sdk/lifecycle/update-many.d.ts +0 -5
- package/dist/sdk/lifecycle/update-many.js +5 -6
- package/dist/sdk/lifecycle/update.d.ts +31 -5
- package/dist/sdk/lifecycle/update.js +140 -19
- package/dist/sdk/linked-artifacts.js +6 -7
- package/dist/sdk/merge/install.js +5 -6
- package/dist/sdk/mutation-events.js +5 -7
- package/dist/sdk/package-import-adapters.js +6 -8
- package/dist/sdk/profile.js +6 -7
- package/dist/sdk/query/activity.js +5 -6
- package/dist/sdk/query/calendar.js +5 -6
- package/dist/sdk/query/get.d.ts +1 -6
- package/dist/sdk/query/get.js +20 -55
- package/dist/sdk/query/history.d.ts +0 -5
- package/dist/sdk/query/history.js +5 -6
- package/dist/sdk/query/list.d.ts +7 -21
- package/dist/sdk/query/list.js +38 -54
- package/dist/sdk/query/projection-contracts.d.ts +33 -0
- package/dist/sdk/query/projection-contracts.js +185 -0
- package/dist/sdk/query/search-contracts.d.ts +2 -1
- package/dist/sdk/query/search-contracts.js +18 -87
- package/dist/sdk/query/search.d.ts +15 -0
- package/dist/sdk/query/search.js +34 -10
- package/dist/sdk/relationship-kinds/contract.d.ts +8 -0
- package/dist/sdk/relationship-kinds/contract.js +13 -13
- package/dist/sdk/relationships.d.ts +1 -1
- package/dist/sdk/relationships.js +20 -2
- package/dist/sdk/runtime-primitives.d.ts +1 -1
- package/dist/sdk/runtime-primitives.js +3 -3
- package/dist/sdk/runtime.d.ts +6 -0
- package/dist/sdk/runtime.js +18 -14
- package/dist/sdk/schema-migration.js +6 -7
- package/dist/sdk/schema.js +5 -6
- package/dist/sdk/similarity.d.ts +13 -0
- package/dist/sdk/similarity.js +32 -6
- package/dist/sdk/stats.js +5 -8
- package/dist/sdk/templates.js +5 -6
- package/dist/sdk/test/batch.js +5 -7
- package/dist/sdk/test/execution.js +4 -5
- package/dist/sdk/test/runs.js +5 -7
- package/docs/AGENT_UX_CONTRACTS.md +8 -1
- package/docs/COMMANDS.md +13 -1
- package/docs/DEPENDENCY_KIND_CONTRACT.md +12 -1
- package/docs/README.md +1 -0
- package/docs/RECURRENCE_RECOVERY_CONTRACTS.md +151 -0
- package/docs/RELATIONSHIP_GRAPH.md +92 -10
- package/docs/SDK.md +10 -2
- package/docs/SDK_CONTEXT_INTEGRITY.md +45 -0
- package/docs/SDK_PRIMITIVE_INVENTORY.md +15 -1
- package/docs/generated/AGENT_COMMAND_SURFACE.md +1 -1
- package/docs/performance/sdk-entrypoint-import-costs.md +14 -21
- package/marketplace.json +2 -2
- package/package.json +5 -5
- package/packages/pm-beads/package.json +1 -1
- package/packages/pm-calendar/package.json +1 -1
- package/packages/pm-command-kit/package.json +1 -1
- package/packages/pm-digital-twin/package.json +1 -1
- package/packages/pm-governance-audit/package.json +1 -1
- package/packages/pm-guide-shell/package.json +1 -1
- package/packages/pm-kanban/package.json +1 -1
- package/packages/pm-lifecycle-hooks/package.json +1 -1
- package/packages/pm-linked-test-adapters/package.json +1 -1
- package/packages/pm-search-advanced/package.json +1 -1
- package/packages/pm-templates/package.json +1 -1
- package/packages/pm-todos/package.json +1 -1
- package/packages/pm-vcs/package.json +1 -1
- package/plugins/pm-claude/.claude-plugin/plugin.json +1 -1
- package/plugins/pm-codex/.codex-plugin/plugin.json +1 -1
- package/sdk/public-surface.json +640 -44
- package/dist/cli-bundle/chunks/chunk-4THEB6PD.js +0 -13
- package/dist/cli-bundle/chunks/chunk-GWMXAQOD.js +0 -197
- package/dist/cli-bundle/chunks/chunk-HVFQTLYM.js +0 -35
- package/dist/cli-bundle/chunks/chunk-OI4XI562.js +0 -5
- package/dist/cli-bundle/chunks/chunk-OIOKV6NO.js +0 -2092
- package/dist/cli-bundle/chunks/chunk-SARFF5H5.js +0 -3
- package/dist/cli-bundle/chunks/chunk-YBMRWW4E.js +0 -77
- package/dist/cli-bundle/chunks/register-list-query-Y56KINDU.js +0 -11
- package/dist/cli-bundle/focused-chunks/chunk-34QBIYZI.js +0 -155
- package/dist/cli-bundle/focused-chunks/chunk-BJRYFVSH.js +0 -2
- package/dist/cli-bundle/focused-chunks/chunk-EF6ZS5GH.js +0 -50
- package/dist/cli-bundle/focused-chunks/chunk-L623ZPNK.js +0 -2
- package/dist/cli-bundle/focused-chunks/chunk-PRHY2IMX.js +0 -18
- package/dist/cli-bundle/focused-chunks/chunk-RZU5U6Q7.js +0 -2
- package/dist/cli-bundle/focused-chunks/chunk-YBMGXBFV.js +0 -16
- package/dist/cli-bundle/focused-chunks/chunk-YLVBJ6GF.js +0 -2
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Relationship graph semantics
|
|
2
2
|
|
|
3
|
-
Tracked by [pm-4jqm](../.agents/pm/decisions/pm-4jqm.toon), [pm-dwj33e](../.agents/pm/decisions/pm-dwj33e.toon), [pm-ju83](../.agents/pm/features/pm-ju83.toon), [pm-8xr8](../.agents/pm/stories/pm-8xr8.toon), [pm-m2il](../.agents/pm/chores/pm-m2il.toon), [pm-jiusod](../.agents/pm/issues/pm-jiusod.toon), [pm-mfvsng](../.agents/pm/issues/pm-mfvsng.toon), [pm-9gzr4r](../.agents/pm/issues/pm-9gzr4r.toon), [pm-xvt7ps](../.agents/pm/issues/pm-xvt7ps.toon),
|
|
3
|
+
Tracked by [pm-4jqm](../.agents/pm/decisions/pm-4jqm.toon), [pm-dwj33e](../.agents/pm/decisions/pm-dwj33e.toon), [pm-ju83](../.agents/pm/features/pm-ju83.toon), [pm-8xr8](../.agents/pm/stories/pm-8xr8.toon), [pm-m2il](../.agents/pm/chores/pm-m2il.toon), [pm-jiusod](../.agents/pm/issues/pm-jiusod.toon), [pm-mfvsng](../.agents/pm/issues/pm-mfvsng.toon), [pm-9gzr4r](../.agents/pm/issues/pm-9gzr4r.toon), [pm-xvt7ps](../.agents/pm/issues/pm-xvt7ps.toon), [pm-ouyq3n](../.agents/pm/issues/pm-ouyq3n.toon), [pm-ayg31c](../.agents/pm/issues/pm-ayg31c.toon), [pm-3dyec2](../.agents/pm/issues/pm-3dyec2.toon), [pm-c90tfh](../.agents/pm/issues/pm-c90tfh.toon), and [pm-ob9z4y](../.agents/pm/features/pm-ob9z4y.toon).
|
|
4
4
|
|
|
5
5
|
## Decision
|
|
6
6
|
|
|
@@ -10,7 +10,17 @@ The alternatives were rejected as follows: a closed enum cannot model applicatio
|
|
|
10
10
|
|
|
11
11
|
## Contract
|
|
12
12
|
|
|
13
|
-
Each relationship kind declares direction, inverse,
|
|
13
|
+
Each relationship kind declares direction, inverse, a traversal family,
|
|
14
|
+
optional typed-outcome traversal direction, ordering and hierarchy
|
|
15
|
+
participation, optional temporal order, incoming and outgoing cardinality,
|
|
16
|
+
lifecycle, aliases, payload schema, self-edge policy, and compatibility version.
|
|
17
|
+
Built-ins normalize legacy `related_to`, `depends_on`, `child_of`,
|
|
18
|
+
`parent_child`, `epic`, and `task` spellings. Unknown custom kinds remain
|
|
19
|
+
importable only after their definitions are registered, preventing algorithms
|
|
20
|
+
from guessing their meaning. Omitted custom traversal metadata remains
|
|
21
|
+
compatible: hierarchy and ordering declarations select their corresponding
|
|
22
|
+
families, undirected kinds are associative, and other directed kinds are
|
|
23
|
+
semantic.
|
|
14
24
|
|
|
15
25
|
`recurs_from` is the canonical recurrence relation: `new --recurs_from--> old`
|
|
16
26
|
means the source is a later event with the same observable failure identity as
|
|
@@ -153,10 +163,9 @@ await assertRelationshipGraphAdapterConformance(adapter, {
|
|
|
153
163
|
workspace: "isolated-conformance-workspace",
|
|
154
164
|
});
|
|
155
165
|
|
|
156
|
-
const portfolio = federateRelationshipGraphSnapshots(
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
);
|
|
166
|
+
const portfolio = federateRelationshipGraphSnapshots([productA, productB], {
|
|
167
|
+
createdAt: new Date().toISOString(),
|
|
168
|
+
});
|
|
160
169
|
```
|
|
161
170
|
|
|
162
171
|
`createRelationshipGraphScaleFixture` supplies reiterable lazy `nodes` and
|
|
@@ -251,6 +260,14 @@ for domain packages that need more than generic adjacency:
|
|
|
251
260
|
- `enumerateRelationshipPaths` returns bounded simple paths with edge evidence,
|
|
252
261
|
cost metadata, cancellation, direction/kind filters, and explicit truncation.
|
|
253
262
|
|
|
263
|
+
An explicit kind filter may include `traversal: "semantic"` kinds on either
|
|
264
|
+
hierarchy or ordering walks, giving package-defined lineage edges a bounded
|
|
265
|
+
semantic traversal surface without pretending that they are structural or
|
|
266
|
+
scheduling edges. Default walks remain family-strict when no kind filter is
|
|
267
|
+
provided. Association kinds refuse these walks with an `impact --direction
|
|
268
|
+
both` recovery route; selecting the other structural family points to the
|
|
269
|
+
matching hierarchy or ordering commands.
|
|
270
|
+
|
|
254
271
|
All semantic walks are breadth-first and deterministic. `limit`, `maxDepth`,
|
|
255
272
|
and `after` provide bounded continuation for hierarchy and ordering walks;
|
|
256
273
|
path enumeration separately bounds returned paths and expanded partial paths.
|
|
@@ -281,8 +298,17 @@ identities and structured rows proven to contradict scalar blocker precedence.
|
|
|
281
298
|
censuses so repair can tighten their ceilings without weakening the
|
|
282
299
|
information-bearing floor. `articulation_points` and `bridge_edges` reuse the exact cut-structure
|
|
283
300
|
algorithm; outcome metrics count explicit `Milestone` titles beginning with
|
|
284
|
-
`Outcome milestone:` and follow
|
|
285
|
-
|
|
301
|
+
`Outcome milestone:` and follow the registry's declared
|
|
302
|
+
`outcomeTraversal` directions toward them. The audit publishes that exact
|
|
303
|
+
`outcome_reachability_basis` direction groups beside the rates, using sorted
|
|
304
|
+
comma-separated kind names so consumers never infer lineage meaning from
|
|
305
|
+
labels while repeated direction labels stay out of the token surface. Built-in
|
|
306
|
+
hierarchy, implementation, verification,
|
|
307
|
+
discovery, incident, recurrence, and supersession edges opt in explicitly;
|
|
308
|
+
`supersedes` traverses both directions so an archived predecessor remains
|
|
309
|
+
connected to the replacement outcome lineage. Generic `related` and ordering
|
|
310
|
+
edges declare no outcome traversal and cannot satisfy the metric. Active and
|
|
311
|
+
terminal populations are reported separately, with integer
|
|
286
312
|
basis-point rates and all-status reachable/unreachable totals; the explicit
|
|
287
313
|
outcome milestones are roots, not work subjects, and are excluded from those
|
|
288
314
|
populations. Rate or
|
|
@@ -290,8 +316,7 @@ all-status floors are lifecycle-stable; an absolute active-population floor is
|
|
|
290
316
|
invalid because completing reachable work legitimately moves it into the
|
|
291
317
|
terminal population. `finding_subjects_by_code` includes every known finding
|
|
292
318
|
code even when its population is zero, so assurance selectors never confuse a
|
|
293
|
-
clean class with a missing contract field.
|
|
294
|
-
satisfy outcome reachability.
|
|
319
|
+
clean class with a missing contract field.
|
|
295
320
|
|
|
296
321
|
```ts
|
|
297
322
|
import {
|
|
@@ -318,6 +343,63 @@ policy findings. A VCS, company operating model, digital twin, or other
|
|
|
318
343
|
non-project domain can replace the assembly adapter while reusing the same
|
|
319
344
|
registry, traversal, event, context, and audit contracts.
|
|
320
345
|
|
|
346
|
+
### Relationship assurance sources
|
|
347
|
+
|
|
348
|
+
Repository assurance can ratchet graph quality without baking one project's
|
|
349
|
+
policy into the graph kernel. A `dependency_kind` measurement may partition a
|
|
350
|
+
canonical dependency kind by exact `source_kind`, by `source_kind_prefix`, or
|
|
351
|
+
by whether provenance is present or missing. These filters are mutually
|
|
352
|
+
exclusive and preserve the unfiltered measurement contract. This supports
|
|
353
|
+
independent evidence-backed and uncited-edge floors or ceilings while keeping
|
|
354
|
+
the dependency vocabulary extensible.
|
|
355
|
+
|
|
356
|
+
The `prose_edge_gap` source measures distinct holder-target pairs where item
|
|
357
|
+
descriptions, bodies, comments, notes, or learnings mention another canonical
|
|
358
|
+
item but no structured relationship exists in either direction. It performs one
|
|
359
|
+
bounded pass over the supplied items, resolves the collected mentions after the
|
|
360
|
+
canonical id set is complete, reports the exact gap count, partitions the result
|
|
361
|
+
into `explicit_subject` and `implicit_subject` pairs, and caps contributor
|
|
362
|
+
diagnostics with `sample_limit`. Reasoned exemptions may name a whole holder,
|
|
363
|
+
one holder-target pair, or a text fragment within one holder; an exemption
|
|
364
|
+
without a non-empty reason is invalid. This makes roadmap ledgers, negative
|
|
365
|
+
statements, and analysis subjects explicit policy rather than hidden
|
|
366
|
+
false-positive suppression.
|
|
367
|
+
|
|
368
|
+
```ts
|
|
369
|
+
const evidenceBlocks = {
|
|
370
|
+
kind: "dependency_kind" as const,
|
|
371
|
+
dependency_kind: "blocks",
|
|
372
|
+
source_kind_prefix: "evidence:",
|
|
373
|
+
};
|
|
374
|
+
|
|
375
|
+
const unlinkedMentions = {
|
|
376
|
+
kind: "prose_edge_gap" as const,
|
|
377
|
+
sample_limit: 25,
|
|
378
|
+
exemptions: [
|
|
379
|
+
{
|
|
380
|
+
holder_id: "roadmap-ledger",
|
|
381
|
+
reason: "The ledger inventories work without asserting pairwise edges.",
|
|
382
|
+
},
|
|
383
|
+
],
|
|
384
|
+
};
|
|
385
|
+
```
|
|
386
|
+
|
|
387
|
+
Assurance assertions should pin these measurements to observed repository
|
|
388
|
+
baselines: an evidence partition uses a non-regression floor, while uncited
|
|
389
|
+
edges and prose gaps use ceilings. Negative controls must prove the observed
|
|
390
|
+
value passes and a one-unit regression fails before the assertions join the
|
|
391
|
+
repository's graph-composition gate.
|
|
392
|
+
|
|
393
|
+
The scale acceptance runs the public SDK over one million items whose 999,999
|
|
394
|
+
prose mentions each have a corresponding structured edge. It verifies an exact
|
|
395
|
+
zero-gap result, bounded empty diagnostics, a 2,999,998-unit cost receipt, and
|
|
396
|
+
the real item scan count:
|
|
397
|
+
|
|
398
|
+
```bash
|
|
399
|
+
pnpm build
|
|
400
|
+
node --max-old-space-size=4096 scripts/benchmarks/prose-edge-gap-scale.mjs
|
|
401
|
+
```
|
|
402
|
+
|
|
321
403
|
The native workspace adapter is `pm graph <subcommand>`, also available as
|
|
322
404
|
`PmClient.graph`, `runAction({ action: "graph" })`, and the MCP `pm_graph`
|
|
323
405
|
tool. `ancestors`/`descendants`/`predecessors`/`successors` expose the
|
package/docs/SDK.md
CHANGED
|
@@ -54,6 +54,11 @@ Positional command signatures, action-scoped discovery, and MCP/CLI option
|
|
|
54
54
|
parity are tracked by [pm-ya7x55](../.agents/pm/tasks/pm-ya7x55.toon),
|
|
55
55
|
[pm-2tan](../.agents/pm/issues/pm-2tan.toon), and
|
|
56
56
|
[pm-y0htkd](../.agents/pm/issues/pm-y0htkd.toon).
|
|
57
|
+
Terminal recurrence and executable recovery are tracked by
|
|
58
|
+
[pm-83cz0o](../.agents/pm/features/pm-83cz0o.toon),
|
|
59
|
+
[pm-qljv](../.agents/pm/issues/pm-qljv.toon), and
|
|
60
|
+
[pm-surv](../.agents/pm/issues/pm-surv.toon); see
|
|
61
|
+
[Recurrence and Executable Recovery Contracts](RECURRENCE_RECOVERY_CONTRACTS.md).
|
|
57
62
|
|
|
58
63
|
Use it for extension authoring, package authoring, command/action contract discovery, and deterministic app or CI automation. Do not import private `src/core/...` modules from external integrations or packages.
|
|
59
64
|
|
|
@@ -1127,10 +1132,13 @@ filters, and bound the race-loss candidate walk with `maxAttempts` (1 through
|
|
|
1127
1132
|
tools do not need to reproduce CLI concurrency policy.
|
|
1128
1133
|
|
|
1129
1134
|
Lifecycle convenience methods and the matching top-level functions (`create`,
|
|
1130
|
-
`update`, `close`, `claim`, `release`, `copy`, `deleteItem`, `restore`,
|
|
1135
|
+
`update`, `reopen`, `close`, `claim`, `release`, `copy`, `deleteItem`, `restore`,
|
|
1131
1136
|
`focus`, `startTask`, `pauseTask`, and `closeTask`) use the same mutation paths
|
|
1132
1137
|
as the CLI and MCP dispatcher. They are the baseline primitives for custom PM
|
|
1133
|
-
tools that need to own item state without spawning `pm`.
|
|
1138
|
+
tools that need to own item state without spawning `pm`. `reopen` requires a
|
|
1139
|
+
recurrence reason, accepts only the workspace open or in-progress target, and
|
|
1140
|
+
returns the terminal evidence captured atomically before the update path clears
|
|
1141
|
+
it from active metadata.
|
|
1134
1142
|
|
|
1135
1143
|
### Atomic workspace transactions
|
|
1136
1144
|
|
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
Tracker: [pm-0k19l7](../.agents/pm/issues/pm-0k19l7.toon), [pm-9stazf](../.agents/pm/issues/pm-9stazf.toon), [pm-tu71](../.agents/pm/issues/pm-tu71.toon), [pm-0xmajx](../.agents/pm/issues/pm-0xmajx.toon), [pm-7rrqsk](../.agents/pm/issues/pm-7rrqsk.toon), [pm-ety1qc](../.agents/pm/issues/pm-ety1qc.toon), [pm-lu6sca](../.agents/pm/features/pm-lu6sca.toon), [pm-5y05kq](../.agents/pm/issues/pm-5y05kq.toon), [pm-gjjurs](../.agents/pm/issues/pm-gjjurs.toon), [pm-h97qxd](../.agents/pm/issues/pm-h97qxd.toon), [pm-h06944](../.agents/pm/issues/pm-h06944.toon), [pm-5t33or](../.agents/pm/features/pm-5t33or.toon), [pm-in23qu](../.agents/pm/issues/pm-in23qu.toon), [pm-h8tpeh](../.agents/pm/features/pm-h8tpeh.toon), [pm-okgxwa](../.agents/pm/issues/pm-okgxwa.toon), [pm-22rzjp](../.agents/pm/issues/pm-22rzjp.toon), [pm-76fkpp](../.agents/pm/issues/pm-76fkpp.toon), [pm-igdvfq](../.agents/pm/issues/pm-igdvfq.toon), [pm-643e0k](../.agents/pm/issues/pm-643e0k.toon), [pm-larv4r](../.agents/pm/issues/pm-larv4r.toon), [pm-mcxk8v](../.agents/pm/issues/pm-mcxk8v.toon), and [pm-2zkvxm](../.agents/pm/issues/pm-2zkvxm.toon).
|
|
4
4
|
|
|
5
|
+
Current closure tranche: [pm-fs8q9x](../.agents/pm/tasks/pm-fs8q9x.toon), [pm-gy885b](../.agents/pm/issues/pm-gy885b.toon), and [pm-f05lsg](../.agents/pm/features/pm-f05lsg.toon).
|
|
6
|
+
|
|
5
7
|
## Agent Quick Context
|
|
6
8
|
|
|
7
9
|
These contracts keep project management equal to context management: reads say what they omit, writes return only newly useful context, diagnostics do not unexpectedly call remote providers, and every transport delegates domain validation to the same SDK primitive. Package authors can use the same primitives without reproducing CLI parsing rules.
|
|
@@ -74,6 +76,39 @@ The structured `option_scope` is `declared_on_path`, `declared_elsewhere`, or
|
|
|
74
76
|
case, while the third names the nearest current-path spellings and explicitly
|
|
75
77
|
terminates the otherwise-unbounded command search.
|
|
76
78
|
|
|
79
|
+
## Semantic flag and spelling contracts
|
|
80
|
+
|
|
81
|
+
`listPmFlagLexicon()` classifies flags by meaning rather than spelling alone.
|
|
82
|
+
For example, `--limit` is the shared `result-row-limit` concept, while
|
|
83
|
+
`--node-limit`, `--edge-limit`, `--output-limit`, `--output-budget`, and
|
|
84
|
+
`--token-budget` retain distinct graph, serialization, and intent-budget
|
|
85
|
+
semantics. Command-local overloads such as `--file` are explicitly separated
|
|
86
|
+
into linked-file, annotation-input, and plan-definition concepts.
|
|
87
|
+
|
|
88
|
+
`listPmFlagSpellingInventory()` publishes every canonical spelling and every
|
|
89
|
+
accepted compatibility alias. The repository gate compares it with
|
|
90
|
+
`scripts/release/flag-spelling-baseline.json`; removing either a canonical flag
|
|
91
|
+
or an established alias fails closed. A separate generated help baseline
|
|
92
|
+
records UTF-8 size, estimated tokens, and per-command deltas, so a vocabulary
|
|
93
|
+
change cannot silently expand the agent discovery surface. Refreshing either
|
|
94
|
+
baseline is an explicit reviewed operation through
|
|
95
|
+
`node scripts/release/flag-lexicon-gate.mjs --update-inventory`.
|
|
96
|
+
|
|
97
|
+
## Closed-domain refusal contracts
|
|
98
|
+
|
|
99
|
+
`listCoreClosedDomainContracts()` is the SDK-owned registry for every built-in
|
|
100
|
+
`--for` intent and `--fields` projection refusal. It derives projection values
|
|
101
|
+
from the list, get, and search query modules and covers all eight list-family
|
|
102
|
+
entrypoints. CLI help uses the same registry, representing `item.<field>` and
|
|
103
|
+
runtime-schema extensions with compact generative notation instead of
|
|
104
|
+
repeating every alias.
|
|
105
|
+
|
|
106
|
+
The executable gate derives its refusal corpus from this registry, requires
|
|
107
|
+
the exact error code, complete `allowed_values`, shell-free
|
|
108
|
+
`suggested_retry_args`, and a successful retry, then compares probe identities
|
|
109
|
+
with `scripts/release/refusal-closure-baseline.json`. Adding a new core domain
|
|
110
|
+
without a probe or removing historical coverage therefore fails CI.
|
|
111
|
+
|
|
77
112
|
## Executable recovery-reference coverage
|
|
78
113
|
|
|
79
114
|
Structured refusal guidance is a forward-reference contract, not decorative
|
|
@@ -89,6 +124,16 @@ family. Each obligation declares `recovery`, `replacement`, or
|
|
|
89
124
|
`behavior_preserving` semantics and its proof must demonstrate the same
|
|
90
125
|
promise.
|
|
91
126
|
|
|
127
|
+
`verifyPmRecoveryKindRuntimeCoverage` joins the syntax-aware complete source
|
|
128
|
+
census to distinct emitted values for every typed kind. Its receipt retains
|
|
129
|
+
both denominators and fails when a kind has source producers but no runtime
|
|
130
|
+
evidence, preventing a representative recovery example from masking an
|
|
131
|
+
entirely unexecuted producer family. This is explicitly kind-level assurance:
|
|
132
|
+
it does not claim that every individual source location or every distinct value
|
|
133
|
+
was executed. The former `verifyPmRecoveryProducerRuntimeCoverage` export
|
|
134
|
+
remains as a deprecated compatibility alias with those same kind-level
|
|
135
|
+
semantics.
|
|
136
|
+
|
|
92
137
|
The repository integration corpus drives real CLI refusals, executes the
|
|
93
138
|
emitted retry in a temporary tracker, compares candidate commands with the
|
|
94
139
|
unbounded runtime contract enumeration, and binds examples and next steps to
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# SDK Primitive Inventory
|
|
2
2
|
|
|
3
|
-
Tracked work: [pm-lodl](../.agents/pm/tasks/pm-lodl.toon), [pm-8778](../.agents/pm/tasks/pm-8778.toon), [pm-rjqr](../.agents/pm/features/pm-rjqr.toon), [pm-oslr](../.agents/pm/features/pm-oslr.toon), capstone [pm-9x6e](../.agents/pm/tasks/pm-9x6e.toon), parent [pm-usfg](../.agents/pm/epics/pm-usfg.toon).
|
|
3
|
+
Tracked work: [pm-lodl](../.agents/pm/tasks/pm-lodl.toon), [pm-8778](../.agents/pm/tasks/pm-8778.toon), [pm-rjqr](../.agents/pm/features/pm-rjqr.toon), [pm-oslr](../.agents/pm/features/pm-oslr.toon), [pm-6qiwan](../.agents/pm/chores/pm-6qiwan.toon), capstone [pm-9x6e](../.agents/pm/tasks/pm-9x6e.toon), parent [pm-usfg](../.agents/pm/epics/pm-usfg.toon).
|
|
4
4
|
|
|
5
5
|
This inventory records the completed SDK-first migration for the principle `project management = context management`.
|
|
6
6
|
CLI and MCP modules now import shared host services through `src/sdk/runtime-primitives.ts`; direct `src/core` imports, type-only edges, re-exports, and computed dynamic imports are unconditionally rejected by the static quality gate. There is no allowance file or ratchet escape hatch.
|
|
@@ -18,6 +18,20 @@ CLI and MCP modules now import shared host services through `src/sdk/runtime-pri
|
|
|
18
18
|
|
|
19
19
|
`src/sdk/runtime-primitives.ts` is the curated low-level seam for presentation hosts. It exposes filesystem, schema, history, extension-runtime, telemetry, search, output, and storage services needed to compose the shipped CLI and MCP adapters. External integrations should still prefer typed `PmClient` and top-level SDK operations; runtime primitives exist for embedded hosts that need to build an equivalent presentation layer without private imports.
|
|
20
20
|
|
|
21
|
+
## Tracker Preflight Primitive
|
|
22
|
+
|
|
23
|
+
`assertInitializedTracker` is the shared SDK boundary for commands that require
|
|
24
|
+
an initialized project, while `assertReadableTrackerRoot` supports low-level
|
|
25
|
+
metadata enumeration that intentionally accepts an empty directory. The former
|
|
26
|
+
replaced 50 literal checks across 45 SDK modules. It preserves one structured
|
|
27
|
+
error vocabulary and one exact recovery contract for CLI, MCP dispatch through
|
|
28
|
+
the SDK runtime, first-party packages, and external SDK consumers.
|
|
29
|
+
|
|
30
|
+
The preflight is public from the aggregate SDK; its four-state static recovery
|
|
31
|
+
corpus is also public from `@unbrained/pm-cli/sdk/contracts`. A source-derived
|
|
32
|
+
ratchet prevents the adoption count from falling below 50 and refuses the old
|
|
33
|
+
inline tracker-not-initialized message anywhere under `src/sdk`.
|
|
34
|
+
|
|
21
35
|
## Promotion Partition
|
|
22
36
|
|
|
23
37
|
| Promotion item | Primitive family | Primary private domains to promote |
|
|
@@ -12,7 +12,7 @@ This file is generated from `PM_COMMAND_CAPABILITY_CONTRACTS`. Do not edit it ma
|
|
|
12
12
|
| `install` | full | extensions |
|
|
13
13
|
| `upgrade` | full | extensions |
|
|
14
14
|
| `create` | core | intake |
|
|
15
|
-
| `item` | full |
|
|
15
|
+
| `item-reopen` | full | lifecycle |
|
|
16
16
|
| `copy` | full | intake |
|
|
17
17
|
| `focus` | standard | intake |
|
|
18
18
|
| `list` | core | context |
|
|
@@ -1,13 +1,11 @@
|
|
|
1
1
|
# SDK entrypoint import costs
|
|
2
2
|
|
|
3
3
|
Tracked by [pm-38bskj](../../.agents/pm/tasks/pm-38bskj.toon) and
|
|
4
|
-
[pm-cg1sjb](../../.agents/pm/issues/pm-cg1sjb.toon).
|
|
5
|
-
topology is tracked by
|
|
6
|
-
[pm-m9gu9r](../../.agents/pm/chores/pm-m9gu9r.toon).
|
|
4
|
+
[pm-cg1sjb](../../.agents/pm/issues/pm-cg1sjb.toon).
|
|
7
5
|
|
|
8
6
|
This table measures fresh-process ESM import and module evaluation. The bare
|
|
9
7
|
Node v26.5.0 process floor on linux/x64
|
|
10
|
-
was
|
|
8
|
+
was 44 ms p50 (56 ms p95) across
|
|
11
9
|
5 measured runs after one warm-up. Focused entrypoints are
|
|
12
10
|
compared with the compatibility aggregate; negative reduction means the focused
|
|
13
11
|
entrypoint was slower in this sample. The gate admits the median measured run
|
|
@@ -15,25 +13,20 @@ against the unchanged upper-bound budget and 30 ms scheduler margin. A single
|
|
|
15
13
|
cold or descheduled process therefore cannot fail the gate, while a majority of
|
|
16
14
|
over-budget samples still does; p95 remains visible as diagnostic evidence.
|
|
17
15
|
|
|
18
|
-
| Package export
|
|
19
|
-
|
|
20
|
-
| `./sdk`
|
|
21
|
-
| `./sdk/authoring`
|
|
22
|
-
| `./sdk/contracts`
|
|
23
|
-
| `./sdk/core`
|
|
24
|
-
| `./sdk/governance` |
|
|
25
|
-
| `./sdk/graph`
|
|
26
|
-
| `./sdk/merge`
|
|
27
|
-
| `./sdk/query`
|
|
28
|
-
| `./sdk/runtime`
|
|
29
|
-
| `./sdk/testing`
|
|
16
|
+
| Package export | p50 | p95 | p50 above Node | Reduction vs aggregate overhead |
|
|
17
|
+
|---|---:|---:|---:|---:|
|
|
18
|
+
| `./sdk` | 320 ms | 348 ms | 276 ms | 0% |
|
|
19
|
+
| `./sdk/authoring` | 91 ms | 99 ms | 47 ms | 83% |
|
|
20
|
+
| `./sdk/contracts` | 152 ms | 156 ms | 108 ms | 60.9% |
|
|
21
|
+
| `./sdk/core` | 285 ms | 291 ms | 241 ms | 12.7% |
|
|
22
|
+
| `./sdk/governance` | 211 ms | 220 ms | 167 ms | 39.5% |
|
|
23
|
+
| `./sdk/graph` | 92 ms | 105 ms | 48 ms | 82.6% |
|
|
24
|
+
| `./sdk/merge` | 130 ms | 145 ms | 86 ms | 68.8% |
|
|
25
|
+
| `./sdk/query` | 132 ms | 156 ms | 88 ms | 68.1% |
|
|
26
|
+
| `./sdk/runtime` | 283 ms | 312 ms | 239 ms | 13.4% |
|
|
27
|
+
| `./sdk/testing` | 274 ms | 319 ms | 230 ms | 16.7% |
|
|
30
28
|
|
|
31
29
|
The aggregate `@unbrained/pm-cli/sdk` remains supported for compatibility.
|
|
32
30
|
New packages should import the narrowest subpath that owns their capability.
|
|
33
|
-
The build emits `./sdk/merge` as a standalone no-splitting bundle because its
|
|
34
|
-
dependency closure overlaps with several broader focused entrypoints. Keeping
|
|
35
|
-
that surface in the shared focused chunk graph made a merge-only import traverse
|
|
36
|
-
unrelated chunks; the isolated output preserves the same public exports while
|
|
37
|
-
keeping its runtime loading cost proportional to the capability requested.
|
|
38
31
|
The committed budget file is an upper-bound ratchet and must not be weakened to
|
|
39
32
|
hide a regression.
|
package/marketplace.json
CHANGED
|
@@ -6,14 +6,14 @@
|
|
|
6
6
|
},
|
|
7
7
|
"metadata": {
|
|
8
8
|
"description": "Official marketplace for pm CLI — native git-based project management for Claude Code and AI coding agents.",
|
|
9
|
-
"version": "2026.8.
|
|
9
|
+
"version": "2026.8.21"
|
|
10
10
|
},
|
|
11
11
|
"plugins": [
|
|
12
12
|
{
|
|
13
13
|
"name": "pm-claude",
|
|
14
14
|
"source": "./plugins/pm-claude",
|
|
15
15
|
"description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents, hybrid TUI task tracking, session context injection, and coordination subagents for git-based project management without leaving Claude Code.",
|
|
16
|
-
"version": "2026.8.
|
|
16
|
+
"version": "2026.8.21",
|
|
17
17
|
"author": {
|
|
18
18
|
"name": "unbrained",
|
|
19
19
|
"url": "https://github.com/unbraind/pm-cli"
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@unbrained/pm-cli",
|
|
3
|
-
"version": "2026.8.
|
|
3
|
+
"version": "2026.8.21",
|
|
4
4
|
"description": "Git-native project management CLI for humans and agents.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"packageManager": "pnpm@11.10.0",
|
|
@@ -218,18 +218,18 @@
|
|
|
218
218
|
"@sentry/cli": "^3.6.2",
|
|
219
219
|
"@types/node": "^26.2.0",
|
|
220
220
|
"@types/npm-package-arg": "^6.1.4",
|
|
221
|
-
"@vitest/coverage-v8": "^4.1.
|
|
221
|
+
"@vitest/coverage-v8": "^4.1.11",
|
|
222
222
|
"esbuild": "0.28.2",
|
|
223
223
|
"eslint": "^10.8.1",
|
|
224
224
|
"eslint-plugin-sonarjs": "^4.2.0",
|
|
225
225
|
"eslint-plugin-unicorn": "^73.0.0",
|
|
226
226
|
"fast-check": "^4.9.0",
|
|
227
|
-
"greptile": "^3.4.
|
|
228
|
-
"jscpd": "^5.0.
|
|
227
|
+
"greptile": "^3.4.1",
|
|
228
|
+
"jscpd": "^5.0.16",
|
|
229
229
|
"tsx": "^4.23.12",
|
|
230
230
|
"typescript": "^6.0.3",
|
|
231
231
|
"typescript-eslint": "^8.67.0",
|
|
232
|
-
"vitest": "^4.1.
|
|
232
|
+
"vitest": "^4.1.11",
|
|
233
233
|
"yaml": "^2.9.0"
|
|
234
234
|
}
|
|
235
235
|
}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@unbrained/pm-digital-twin",
|
|
3
|
-
"version": "2026.8.
|
|
3
|
+
"version": "2026.8.21",
|
|
4
4
|
"private": true,
|
|
5
5
|
"type": "module",
|
|
6
6
|
"description": "Beyond-PM exemplar: a temporal production-facility digital twin built entirely on public pm SDK and extension primitives.",
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pm-claude",
|
|
3
3
|
"description": "Native pm CLI integration for Claude Code — 28 MCP tools, 5 workflow skills, 14 slash commands, 4 subagents (coordinator, delivery-chain, triage, verification), hybrid TUI task tracking (pm as persistent store + Claude Code task panel as live view), session context injection, and full git-based project management without leaving Claude Code.",
|
|
4
|
-
"version": "2026.8.
|
|
4
|
+
"version": "2026.8.21",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "unbrained",
|
|
7
7
|
"url": "https://github.com/unbraind/pm-cli"
|