pm-brief 2026.10.26 → 2026.10.29
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/CHANGELOG.md +39 -34
- package/README.md +168 -1
- package/dist/action.d.ts +105 -0
- package/dist/action.d.ts.map +1 -0
- package/dist/action.js +308 -0
- package/dist/action.js.map +1 -0
- package/dist/follow-through.d.ts +118 -0
- package/dist/follow-through.d.ts.map +1 -0
- package/dist/follow-through.js +266 -0
- package/dist/follow-through.js.map +1 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +7 -1
- package/dist/index.js.map +1 -1
- package/docs/examples/action.md +65 -0
- package/docs/examples/follow-through.md +55 -0
- package/manifest.json +1 -1
- package/package.json +10 -6
package/CHANGELOG.md
CHANGED
|
@@ -27,14 +27,14 @@
|
|
|
27
27
|
- Record acknowledged handoff contracts against item revisions ([pm-brief-cjxn](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/features/pm-brief-cjxn.toon))
|
|
28
28
|
- Compare recorded decision alternatives with cited evidence ([pm-brief-ktjl](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/features/pm-brief-ktjl.toon))
|
|
29
29
|
|
|
30
|
-
### Fixed
|
|
31
|
-
|
|
32
|
-
- Daily Release workflow is failing ([pm-brief-github-7e06b2eb1b44-170](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-github-7e06b2eb1b44-170.toon))
|
|
33
|
-
|
|
34
30
|
### Other
|
|
35
31
|
|
|
36
32
|
- Verify evidence for tracker reconciliation review ([pm-brief-review165](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/chores/pm-brief-review165.toon))
|
|
37
33
|
|
|
34
|
+
### Closed
|
|
35
|
+
|
|
36
|
+
- Closed: Daily Release workflow is failing ([pm-brief-github-7e06b2eb1b44-170](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-github-7e06b2eb1b44-170.toon))
|
|
37
|
+
|
|
38
38
|
## 2026.10.23 - 2026-10-23
|
|
39
39
|
|
|
40
40
|
### Changed
|
|
@@ -70,9 +70,9 @@
|
|
|
70
70
|
|
|
71
71
|
- Enforce the chosen rendered brief token ceiling ([pm-brief-k8no](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/features/pm-brief-k8no.toon))
|
|
72
72
|
|
|
73
|
-
###
|
|
73
|
+
### Closed
|
|
74
74
|
|
|
75
|
-
- Enforce the requested brief budget after the final compaction step ([pm-brief-github-7e06b2eb1b44-135](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-github-7e06b2eb1b44-135.toon))
|
|
75
|
+
- Closed: Enforce the requested brief budget after the final compaction step ([pm-brief-github-7e06b2eb1b44-135](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-github-7e06b2eb1b44-135.toon))
|
|
76
76
|
|
|
77
77
|
## 2026.10.5 - 2026-10-05
|
|
78
78
|
|
|
@@ -122,22 +122,25 @@
|
|
|
122
122
|
|
|
123
123
|
## 2026.9.1 - 2026-09-01
|
|
124
124
|
|
|
125
|
-
### Fixed
|
|
126
|
-
|
|
127
|
-
- Daily Release workflow is failing ([pm-brief-github-7e06b2eb1b44-84](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-github-7e06b2eb1b44-84.toon))
|
|
128
|
-
- Adopt pm CLI 2026.8.30 and stop pinning which way the SDK handles an incomplete merge receipt ([pm-brief-00tc](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-00tc.toon))
|
|
129
|
-
|
|
130
125
|
### Other
|
|
131
126
|
|
|
132
127
|
- Reconcile the corrupt-receipt fixture comment with what the pinned SDK now does ([pm-brief-vc49](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/chores/pm-brief-vc49.toon))
|
|
133
128
|
|
|
129
|
+
### Closed
|
|
130
|
+
|
|
131
|
+
- Closed: Daily Release workflow is failing ([pm-brief-github-7e06b2eb1b44-84](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-github-7e06b2eb1b44-84.toon))
|
|
132
|
+
- Closed: Adopt pm CLI 2026.8.30 and stop pinning which way the SDK handles an incomplete merge receipt ([pm-brief-00tc](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-00tc.toon))
|
|
133
|
+
|
|
134
134
|
## 2026.8.31 - 2026-08-31
|
|
135
135
|
|
|
136
136
|
### Fixed
|
|
137
137
|
|
|
138
|
-
- Pin pm-changelog 2026.8.30 before the next release ([pm-brief-m4pi](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-m4pi.toon))
|
|
139
138
|
- CodeQL action updates split into mutually blocking pull requests ([pm-brief-eba7](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-eba7.toon))
|
|
140
139
|
|
|
140
|
+
### Closed
|
|
141
|
+
|
|
142
|
+
- Closed: Pin pm-changelog 2026.8.30 before the next release ([pm-brief-m4pi](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-m4pi.toon))
|
|
143
|
+
|
|
141
144
|
## 2026.8.29 - 2026-08-29
|
|
142
145
|
|
|
143
146
|
### Fixed
|
|
@@ -152,15 +155,15 @@
|
|
|
152
155
|
- Checkout release alert script from the default branch ([pm-brief-l5lh](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-l5lh.toon))
|
|
153
156
|
- Canonicalize the complete-corpus reader and adopt the current pm host contract ([pm-brief-v2ts](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-v2ts.toon))
|
|
154
157
|
|
|
155
|
-
### Security
|
|
156
|
-
|
|
157
|
-
- The identity gate deadlocks the one remediation its own failure message prescribes ([pm-brief-4yx9](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-4yx9.toon))
|
|
158
|
-
|
|
159
158
|
### Other
|
|
160
159
|
|
|
161
160
|
- Resolve PR \#79 review threads: hermetic release-alert evidence and audit timestamp correction ([pm-brief-zrpv](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/tasks/pm-brief-zrpv.toon))
|
|
162
161
|
- Alert on daily release failure and require merge drivers in CI ([pm-brief-javk](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/chores/pm-brief-javk.toon))
|
|
163
162
|
|
|
163
|
+
### Closed
|
|
164
|
+
|
|
165
|
+
- Closed: The identity gate deadlocks the one remediation its own failure message prescribes ([pm-brief-4yx9](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-4yx9.toon))
|
|
166
|
+
|
|
164
167
|
## 2026.8.17 - 2026-08-17
|
|
165
168
|
|
|
166
169
|
### Fixed
|
|
@@ -169,9 +172,9 @@
|
|
|
169
172
|
|
|
170
173
|
## 2026.8.16 - 2026-08-16
|
|
171
174
|
|
|
172
|
-
###
|
|
175
|
+
### Closed
|
|
173
176
|
|
|
174
|
-
- pm-brief consumes a truncated `pm list-all` answer as if it were complete ([pm-brief-g6ko](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-g6ko.toon))
|
|
177
|
+
- Closed: pm-brief consumes a truncated `pm list-all` answer as if it were complete ([pm-brief-g6ko](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-g6ko.toon))
|
|
175
178
|
|
|
176
179
|
## 2026.8.14 - 2026-08-14
|
|
177
180
|
|
|
@@ -233,13 +236,16 @@
|
|
|
233
236
|
|
|
234
237
|
### Fixed
|
|
235
238
|
|
|
236
|
-
- Merge-receipt display cap silently drops item warning markers past the tenth receipt ([pm-brief-8up0](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-8up0.toon))
|
|
237
239
|
- Merge-receipt read failures hard-fail every brief command ([pm-brief-a007](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-a007.toon))
|
|
238
240
|
|
|
239
241
|
### Other
|
|
240
242
|
|
|
241
243
|
- Adopt pm-cli 2026.7.28 ([pm-brief-owcy](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/chores/pm-brief-owcy.toon))
|
|
242
244
|
|
|
245
|
+
### Closed
|
|
246
|
+
|
|
247
|
+
- Closed: Merge-receipt display cap silently drops item warning markers past the tenth receipt ([pm-brief-8up0](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-8up0.toon))
|
|
248
|
+
|
|
243
249
|
## 2026.7.27 - 2026-07-27
|
|
244
250
|
|
|
245
251
|
### Added
|
|
@@ -260,42 +266,42 @@
|
|
|
260
266
|
|
|
261
267
|
- Add pm brief duplicates post-merge near-duplicate sweep ([pm-brief-58en](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/features/pm-brief-58en.toon))
|
|
262
268
|
|
|
263
|
-
### Fixed
|
|
264
|
-
|
|
265
|
-
- Documented install command fails: pm install github.com/unbraind/pm-brief cannot resolve an entry file ([pm-brief-xd8z](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-xd8z.toon))
|
|
266
|
-
|
|
267
269
|
### Other
|
|
268
270
|
|
|
269
271
|
- Enable governance duplicate-detection advisory mode and restore parent_reference=warn ([pm-brief-k39x](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/chores/pm-brief-k39x.toon))
|
|
270
272
|
|
|
273
|
+
### Closed
|
|
274
|
+
|
|
275
|
+
- Closed: Documented install command fails: pm install github.com/unbraind/pm-brief cannot resolve an entry file ([pm-brief-xd8z](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-xd8z.toon))
|
|
276
|
+
|
|
271
277
|
## 2026.7.25 - 2026-07-25
|
|
272
278
|
|
|
273
279
|
### Added
|
|
274
280
|
|
|
275
281
|
- pm brief diverge: pre-merge multi-agent item collision preview ([pm-brief-vj2y](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/features/pm-brief-vj2y.toon))
|
|
276
282
|
|
|
277
|
-
### Fixed
|
|
278
|
-
|
|
279
|
-
- CHANGELOG mislabels shipped 2026.7.23 work as Unreleased, leaving changelog:check red ([pm-brief-edam](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-edam.toon))
|
|
280
|
-
|
|
281
283
|
### Other
|
|
282
284
|
|
|
283
285
|
- Adopt --respect-item-release so release attribution matches the rest of the fleet ([pm-brief-ce55](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/chores/pm-brief-ce55.toon))
|
|
284
286
|
|
|
287
|
+
### Closed
|
|
288
|
+
|
|
289
|
+
- Closed: CHANGELOG mislabels shipped 2026.7.23 work as Unreleased, leaving changelog:check red ([pm-brief-edam](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-edam.toon))
|
|
290
|
+
|
|
285
291
|
## 2026.7.23 - 2026-07-23
|
|
286
292
|
|
|
287
293
|
### Added
|
|
288
294
|
|
|
289
295
|
- Add pm brief since delta command for agent re-orientation after parallel/merge work ([pm-brief-da2c](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/features/pm-brief-da2c.toon))
|
|
290
296
|
|
|
291
|
-
### Fixed
|
|
292
|
-
|
|
293
|
-
- Recommend pm merge reconcile (2026.7.22) over raw history-repair in Multi-agent merge safety docs ([pm-brief-lizi](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-lizi.toon))
|
|
294
|
-
|
|
295
297
|
### Other
|
|
296
298
|
|
|
297
299
|
- Adopt pm field-aware merge driver for multi-agent branch-merge safety ([pm-brief-m2gp](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/chores/pm-brief-m2gp.toon))
|
|
298
300
|
|
|
301
|
+
### Closed
|
|
302
|
+
|
|
303
|
+
- Closed: Recommend pm merge reconcile (2026.7.22) over raw history-repair in Multi-agent merge safety docs ([pm-brief-lizi](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-lizi.toon))
|
|
304
|
+
|
|
299
305
|
## 2026.7.14-1 - 2026-07-14
|
|
300
306
|
|
|
301
307
|
### Other
|
|
@@ -304,9 +310,9 @@
|
|
|
304
310
|
|
|
305
311
|
## 2026.7.14 - 2026-07-14
|
|
306
312
|
|
|
307
|
-
###
|
|
313
|
+
### Closed
|
|
308
314
|
|
|
309
|
-
- brief: blocked_by edges doubled in blockers/risks (dependencies + blocked_by both parsed) ([pm-brief-o4s9](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-o4s9.toon))
|
|
315
|
+
- Closed: brief: blocked_by edges doubled in blockers/risks (dependencies + blocked_by both parsed) ([pm-brief-o4s9](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/issues/pm-brief-o4s9.toon))
|
|
310
316
|
|
|
311
317
|
## 2026.7.11-2 - 2026-07-11
|
|
312
318
|
|
|
@@ -331,7 +337,6 @@
|
|
|
331
337
|
|
|
332
338
|
- Adversarial review pass 2026-07-10 ([pm-brief-kk7m](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/chores/pm-brief-kk7m.toon))
|
|
333
339
|
- Full-cycle hardening wave: pm-brief ([pm-brief-0dru](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/tasks/pm-brief-0dru.toon))
|
|
334
|
-
- Align pm-brief with pm CLI 2026.6.12 release readiness ([pm-brief-352i](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/tasks/pm-brief-352i.toon))
|
|
335
340
|
- Harden release bun-verify so registry-mirror lag cannot block the GitHub release ([pm-brief-93z7](https://github.com/unbraind/pm-brief/blob/main/.agents/pm/chores/pm-brief-93z7.toon))
|
|
336
341
|
|
|
337
342
|
## 2026.7.6 - 2026-07-06
|
package/README.md
CHANGED
|
@@ -591,6 +591,86 @@ final verified read appears on the next repair read. See the
|
|
|
591
591
|
[complete example](docs/examples/handoff-repair.md) and
|
|
592
592
|
[validation evidence](docs/handoff-repair-validation.md).
|
|
593
593
|
|
|
594
|
+
## Decision follow-through briefs
|
|
595
|
+
|
|
596
|
+
```bash
|
|
597
|
+
pm brief observation measurement-id --json
|
|
598
|
+
pm brief follow-through decision-id
|
|
599
|
+
pm brief follow-through decision-id --json --token-budget 1500
|
|
600
|
+
```
|
|
601
|
+
|
|
602
|
+
Follow declared consequences after a choice has been explicitly adopted. Store a
|
|
603
|
+
version 1 `brief_follow_through` object on a native `Decision`, using native
|
|
604
|
+
`pm update --field brief_follow_through='<json>'` (or the SDK custom-field
|
|
605
|
+
options). The extension registers this optional field. The object contains an
|
|
606
|
+
explicit `adopted` boolean and 1–128 outcomes, each with a unique `id`, `expected`
|
|
607
|
+
text, `observations` and `actions`. See the [complete example](docs/examples/follow-through.md).
|
|
608
|
+
|
|
609
|
+
An observation is an explicit `{item, revision, verdict}` judgement: `observed`
|
|
610
|
+
or `contradicted`. Read its revision with `brief observation`, review that item's
|
|
611
|
+
native `actual_result`, then record the judgement on the associated outcome.
|
|
612
|
+
Revisions hash the complete SDK-read native item and its verified append-only
|
|
613
|
+
history; an edit, relationship change or replay invalidates earlier judgements,
|
|
614
|
+
including an edit that restores old text. Empty or missing observations provide
|
|
615
|
+
no support. The brief never interprets prose, opens linked files or runs tests.
|
|
616
|
+
|
|
617
|
+
Every outcome retains its own `unsupported`, `observed`, `contradicted` or
|
|
618
|
+
`conflicted` state. Conflicted means current observations contain both explicit
|
|
619
|
+
verdicts; neither disappears. A changed observation invalidates only outcomes
|
|
620
|
+
citing it. Unrelated outcomes retain their evidence. `unsupported` identifies
|
|
621
|
+
what remains untested by current observations. Action states use the tracker's
|
|
622
|
+
configured SDK status roles (`pending`, `blocked`, `done`, `canceled`, `terminal`
|
|
623
|
+
or `missing`), and completing work never supplies an outcome judgement. Closing
|
|
624
|
+
a Decision does not adopt it. Malformed outcome records are isolated with an
|
|
625
|
+
`invalid_outcome` remedy while other outcomes remain readable.
|
|
626
|
+
|
|
627
|
+
The default 1500-token ceiling (integer 1–64000) preserves every outcome id and
|
|
628
|
+
state. Optional expected text, observations and actions are included as whole
|
|
629
|
+
detail groups. Each row's `omitted` counts absent details: one for expected text,
|
|
630
|
+
one per observation and one per action. `restore` reads the original declaration;
|
|
631
|
+
use native `pm get <observation-id> --full` for source measurements. The SDK UTF-8
|
|
632
|
+
estimator covers twice the complete pretty JSON size plus 256 framing bytes,
|
|
633
|
+
including the estimate and omissions. It bounds normal native JSON/TOON, not a
|
|
634
|
+
model tokenizer or extra host accounting receipts. For larger briefs also use
|
|
635
|
+
`--output-budget unbounded --output-limit unbounded`. If mandatory summaries
|
|
636
|
+
cannot fit, the command refuses instead of silently removing outcomes.
|
|
637
|
+
|
|
638
|
+
```ts
|
|
639
|
+
import {
|
|
640
|
+
buildDecisionFollowThroughBrief, readFollowThroughObservation,
|
|
641
|
+
parseFollowThroughDeclaration, FollowThroughError,
|
|
642
|
+
} from "pm-brief";
|
|
643
|
+
|
|
644
|
+
const options = { pmRoot: ".agents/pm" }; // Pass the host-bound client when available.
|
|
645
|
+
const source = await readFollowThroughObservation("measurement-id", options);
|
|
646
|
+
const declaration = parseFollowThroughDeclaration({
|
|
647
|
+
version: 1, adopted: true,
|
|
648
|
+
outcomes: [{ id: "latency", expected: "Lower latency", observations: [
|
|
649
|
+
{ ...source, verdict: "observed" },
|
|
650
|
+
], actions: ["next-experiment-id"] }],
|
|
651
|
+
});
|
|
652
|
+
// Persist declaration with native pm mutation APIs, then read current state:
|
|
653
|
+
try {
|
|
654
|
+
const brief = await buildDecisionFollowThroughBrief({ decision: "decision-id" }, options);
|
|
655
|
+
console.log(brief.outcomes);
|
|
656
|
+
} catch (error) {
|
|
657
|
+
if (error instanceof FollowThroughError) console.error(error.code, error.remedy);
|
|
658
|
+
else throw error;
|
|
659
|
+
}
|
|
660
|
+
```
|
|
661
|
+
|
|
662
|
+
`parseFollowThroughDeclaration` is the strict producer validator, preserving
|
|
663
|
+
recorded whitespace and CRLF. Readers reuse its per-outcome rules but isolate
|
|
664
|
+
bad rows. Sparse arrays, accessors/proxies, unknown keys, duplicate ids,
|
|
665
|
+
unbounded collections and nonfinite budgets refuse. Refusal codes are `invalid`,
|
|
666
|
+
`missing`, `not_adopted`, `tracker`, `changed` and `budget`, always with a remedy
|
|
667
|
+
(CLI exit 2). The reader revalidates native state and history before returning;
|
|
668
|
+
retry recomputes from current SDK data. It creates no plan, journal, lease,
|
|
669
|
+
importer, sync engine or remote side effect. History is accessed through the
|
|
670
|
+
public SDK; a backend must expose that native history at the supplied tracker
|
|
671
|
+
root to certify a revision. Alternatives digests explain choices before
|
|
672
|
+
adoption; pm-review owns review judgments; pm-evidence owns source citations.
|
|
673
|
+
|
|
594
674
|
## Decision alternatives digest
|
|
595
675
|
|
|
596
676
|
```bash
|
|
@@ -726,10 +806,97 @@ source), or `budget` (increase the ceiling or supply a smaller brief). CLI
|
|
|
726
806
|
refusals exit 2 with `disclosure_<code>` and a remedy, without source text or
|
|
727
807
|
nested error details. See the [worked example and public-tracker replay](docs/examples/disclosure.md).
|
|
728
808
|
|
|
809
|
+
## Action prerequisite briefs
|
|
810
|
+
|
|
811
|
+
Ask for one intended native action and one exact item before attempting it:
|
|
812
|
+
|
|
813
|
+
```sh
|
|
814
|
+
pm brief action close project-123
|
|
815
|
+
pm --json brief action close project-123 --request '{"input":{"reason":"Verified delivery"},"requiredEvidence":[{"kind":"docs","ref":"docs/results.md"}]}'
|
|
816
|
+
pm brief action start-task project-123 --request '{"actor":"delivery-agent"}'
|
|
817
|
+
```
|
|
818
|
+
|
|
819
|
+
One call combines native command availability, SDK readiness and blocker
|
|
820
|
+
resolution, close evidence fields (`resolution`, `expected_result`,
|
|
821
|
+
`actual_result`), reason governance, workflow rules and explicitly declared
|
|
822
|
+
native evidence links. Satisfied fields are JSON Pointer references; their
|
|
823
|
+
bodies are never repeated. Link presence records linkage, not successful tests
|
|
824
|
+
or artifact verification. This composes core admission facts; pm-lint remains
|
|
825
|
+
the item quality diagnostic, and this command never chooses work.
|
|
826
|
+
|
|
827
|
+
Readiness is scoped to the action: explicit starting composes native claim and
|
|
828
|
+
update admission, including SDK-resolved type `command_option_policies`.
|
|
829
|
+
Dispatch roles, unfinished children and nonterminal status classifications do
|
|
830
|
+
not veto an explicit start. Closing uses native terminal-state and direct-child
|
|
831
|
+
facts. A decision, outcome gate, draft or blocked status alone does not prevent
|
|
832
|
+
an evidenced close. A claim principal without an assignee is historical metadata,
|
|
833
|
+
not live ownership; both actions check current assignee state.
|
|
834
|
+
|
|
835
|
+
Policy entries expose the SDK's effective `effect`. Advisory and warning findings
|
|
836
|
+
have `blocking: false`: their `missing`/`unresolved` states stay visible while
|
|
837
|
+
`ready` remains true if all mandatory prerequisites are satisfied. An omitted
|
|
838
|
+
`blocking` means the entry is mandatory. Workspace refusal requires both a
|
|
839
|
+
refusing rule and workspace enforcement; warning-only type transitions never
|
|
840
|
+
become required inputs. Type workflows govern the native start update, not a
|
|
841
|
+
direct close. Close evidence fields and unfinished children follow the native
|
|
842
|
+
`close_validation_default`: strict gates them, while warn/off retain non-blocking
|
|
843
|
+
diagnostics. Explicitly requested evidence and mandatory close reasons still gate.
|
|
844
|
+
|
|
845
|
+
Required update options are invocation inputs, even when the corresponding item
|
|
846
|
+
field already has a value. Start supplies its native status automatically;
|
|
847
|
+
`actor` supplies the author option. Other required start flags appear as missing
|
|
848
|
+
`option:<key>` entries with typed `unsupported` refusals and native remedies,
|
|
849
|
+
because this request does not accept arbitrary mutation options. Disabled
|
|
850
|
+
generated options and inconsistent policies also prevent readiness. Satisfied
|
|
851
|
+
generated status references use `native:start-task#/update/status`.
|
|
852
|
+
|
|
853
|
+
The typed SDK entry point is `buildActionPrerequisiteBrief(request, { pmRoot,
|
|
854
|
+
client })`. Pass the host's injected client when embedding. A standalone caller
|
|
855
|
+
can omit it to construct a tracker-bound public SDK client lazily after request
|
|
856
|
+
validation. No executable-path or symlink discovery is involved.
|
|
857
|
+
|
|
858
|
+
`parseActionPrerequisiteRequest` applies `ACTION_PREREQUISITE_SCHEMA` to both
|
|
859
|
+
SDK and CLI requests. Unknown keys, sparse arrays, nonfinite/fractional budgets,
|
|
860
|
+
duplicate evidence declarations and oversized input refuse before tracker IO.
|
|
861
|
+
Records must be plain JSON data: proxies, accessors and inherited/sparse array
|
|
862
|
+
entries are rejected without executing caller-provided callbacks.
|
|
863
|
+
`requiredEvidence` accepts at most 64 exact `{kind, ref}` pairs for `docs`,
|
|
864
|
+
`files` and `tests`; strings are bounded (reference 1024, input field 16000,
|
|
865
|
+
actor 128 characters). The complete TOON/JSON estimate defaults to 4000 tokens
|
|
866
|
+
and accepts integer ceilings 1..64000. Requirements are never silently truncated.
|
|
867
|
+
|
|
868
|
+
The result has `preview: true`, `ready`, `checklist` and typed `refusals`.
|
|
869
|
+
Close and start-task previews are supported. Other commands, approval-history
|
|
870
|
+
certification, matching workspace field/writer policies and composed claim-stage
|
|
871
|
+
policies return `unsupported` when their effective response can refuse the action,
|
|
872
|
+
with a remedy alongside known facts. Advisory certification gaps remain
|
|
873
|
+
non-blocking checklist entries. Policy
|
|
874
|
+
field references describe current/proposed input availability; native actions
|
|
875
|
+
can generate or clear other metadata, so those references never certify the
|
|
876
|
+
complete post-action record. Use native semantic validation for those policies.
|
|
877
|
+
Operational failures throw `ActionPrerequisiteError` with `code` and `remedy`:
|
|
878
|
+
`invalid`, `missing`, `tracker`, `changed` or `budget`. CLI usage failures exit 2
|
|
879
|
+
with `action_<code>` (missing positionals use the native argument refusal); a successfully produced preview exits 0 even when its
|
|
880
|
+
checklist is incomplete. Inspect `ready` and `refusals` before continuing.
|
|
881
|
+
|
|
882
|
+
No native mutation is invoked: items, histories, claims, policies and session
|
|
883
|
+
focus are preserved. Native reads can initialize rebuildable runtime metadata
|
|
884
|
+
caches on a writable cold tracker. On a physically read-only tracker, the same
|
|
885
|
+
preview works without changing any bytes. Two certified SDK reads reject
|
|
886
|
+
observed concurrent changes; this is an observation, never a lease or a plan
|
|
887
|
+
to replay. Native actions must revalidate current state, actor permissions and
|
|
888
|
+
execution-time hooks themselves. There is no new import, export, sync, journal,
|
|
889
|
+
checkpoint, idempotency-key or shared writer path.
|
|
890
|
+
|
|
891
|
+
See the [worked example](docs/examples/action.md) and
|
|
892
|
+
[validation evidence](docs/action-validation.md).
|
|
893
|
+
|
|
729
894
|
## Without git
|
|
730
895
|
|
|
731
896
|
Briefs, prompts, ranking, history deltas, governance, duplicate checks and all
|
|
732
|
-
handoff, decision alternatives
|
|
897
|
+
handoff, decision alternatives, decision follow-through, observation revision,
|
|
898
|
+
stakeholder disclosure and action prerequisite commands work in plain initialized
|
|
899
|
+
trackers without a git executable.
|
|
733
900
|
Handoff storage uses the native SDK dispatcher and can reuse a host client.
|
|
734
901
|
`brief diverge` needs a git repository and git refs. Handoff receipts have no
|
|
735
902
|
branch, commit or repository dependency.
|
package/dist/action.d.ts
ADDED
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
import { PmClient } from "@unbrained/pm-cli/sdk";
|
|
2
|
+
import type { WorkflowPolicyEffect } from "@unbrained/pm-cli/sdk";
|
|
3
|
+
import type { ExtensionApi } from "@unbrained/pm-cli/sdk/authoring";
|
|
4
|
+
/** Exact native linkage requirement; presence never claims the artifact passed validation. */
|
|
5
|
+
export interface ActionEvidence {
|
|
6
|
+
kind: "docs" | "files" | "tests";
|
|
7
|
+
ref: string;
|
|
8
|
+
}
|
|
9
|
+
/** One explicit action, with prospective close inputs and optional declared evidence. */
|
|
10
|
+
export interface ActionPrerequisiteRequest {
|
|
11
|
+
command: string;
|
|
12
|
+
item: string;
|
|
13
|
+
actor?: string;
|
|
14
|
+
input?: {
|
|
15
|
+
reason?: string;
|
|
16
|
+
resolution?: string;
|
|
17
|
+
expectedResult?: string;
|
|
18
|
+
actualResult?: string;
|
|
19
|
+
};
|
|
20
|
+
requiredEvidence?: ActionEvidence[];
|
|
21
|
+
tokenBudget?: number;
|
|
22
|
+
}
|
|
23
|
+
/** Tracker-bound SDK context, acquired only when a valid request needs data. */
|
|
24
|
+
export interface ActionPrerequisiteOptions {
|
|
25
|
+
pmRoot: string;
|
|
26
|
+
client?: PmClient;
|
|
27
|
+
}
|
|
28
|
+
/** Stable machine refusal vocabulary with actionable recovery. */
|
|
29
|
+
export type ActionRefusalCode = "invalid" | "missing" | "tracker" | "unsupported" | "budget" | "changed";
|
|
30
|
+
/** Expected failures retain recovery without echoing untrusted inputs or item bodies. */
|
|
31
|
+
export declare class ActionPrerequisiteError extends Error {
|
|
32
|
+
/** Category independent of human wording. */
|
|
33
|
+
readonly code: ActionRefusalCode;
|
|
34
|
+
/** Concrete next action for the caller. */
|
|
35
|
+
readonly remedy: string;
|
|
36
|
+
/** Preserve a safe diagnostic and a separate machine-readable remedy. */
|
|
37
|
+
constructor(code: ActionRefusalCode, message: string, remedy: string);
|
|
38
|
+
}
|
|
39
|
+
/** A content-free checklist entry; satisfied values are recoverable references. */
|
|
40
|
+
export interface ActionPrerequisiteEntry {
|
|
41
|
+
kind: "input" | "prerequisite" | "readiness" | "evidence" | "policy";
|
|
42
|
+
key: string;
|
|
43
|
+
state: "missing" | "satisfied" | "unresolved";
|
|
44
|
+
ref?: string;
|
|
45
|
+
remedy?: string;
|
|
46
|
+
/** Advisory findings remain visible and never become mandatory input gates. */
|
|
47
|
+
blocking?: false;
|
|
48
|
+
/** Effective native response after workspace enforcement has been applied. */
|
|
49
|
+
effect?: WorkflowPolicyEffect;
|
|
50
|
+
}
|
|
51
|
+
/** Bounded read-only result; ready describes mandatory inputs, never authorizes a future mutation. */
|
|
52
|
+
export interface ActionPrerequisiteBrief {
|
|
53
|
+
protocol: "pm-brief.action/v1";
|
|
54
|
+
preview: true;
|
|
55
|
+
command: string;
|
|
56
|
+
item: {
|
|
57
|
+
id: string;
|
|
58
|
+
revision: string;
|
|
59
|
+
status: string;
|
|
60
|
+
roles: string[];
|
|
61
|
+
};
|
|
62
|
+
ready: boolean;
|
|
63
|
+
checklist: ActionPrerequisiteEntry[];
|
|
64
|
+
refusals: {
|
|
65
|
+
code: "unsupported";
|
|
66
|
+
capability: string;
|
|
67
|
+
remedy: string;
|
|
68
|
+
}[];
|
|
69
|
+
estimatedTokenCeiling: number;
|
|
70
|
+
}
|
|
71
|
+
/** The single strict boundary schema used by SDK and CLI, including dense bounded arrays. */
|
|
72
|
+
export declare const ACTION_PREREQUISITE_SCHEMA: {
|
|
73
|
+
readonly command: {
|
|
74
|
+
readonly max: 80;
|
|
75
|
+
readonly pattern: RegExp;
|
|
76
|
+
};
|
|
77
|
+
readonly item: {
|
|
78
|
+
readonly max: 200;
|
|
79
|
+
readonly pattern: RegExp;
|
|
80
|
+
};
|
|
81
|
+
readonly actor: {
|
|
82
|
+
readonly max: 128;
|
|
83
|
+
};
|
|
84
|
+
readonly input: {
|
|
85
|
+
readonly keys: readonly ["reason", "resolution", "expectedResult", "actualResult"];
|
|
86
|
+
readonly max: 16000;
|
|
87
|
+
};
|
|
88
|
+
readonly requiredEvidence: {
|
|
89
|
+
readonly max: 64;
|
|
90
|
+
readonly kinds: readonly ["docs", "files", "tests"];
|
|
91
|
+
readonly refMax: 1024;
|
|
92
|
+
};
|
|
93
|
+
readonly tokenBudget: {
|
|
94
|
+
readonly min: 1;
|
|
95
|
+
readonly max: 64000;
|
|
96
|
+
readonly default: 4000;
|
|
97
|
+
};
|
|
98
|
+
};
|
|
99
|
+
/** Parse, detach and normalize defaults once using the same boundary for every producer. */
|
|
100
|
+
export declare function parseActionPrerequisiteRequest(value: unknown): ActionPrerequisiteRequest;
|
|
101
|
+
/** Compose native facts for one intended close or start action, without calling any writer. */
|
|
102
|
+
export declare function buildActionPrerequisiteBrief(value: ActionPrerequisiteRequest, options: ActionPrerequisiteOptions): Promise<ActionPrerequisiteBrief>;
|
|
103
|
+
/** Register the read-only native TOON/JSON command using the same SDK request parser. */
|
|
104
|
+
export declare function registerActionPrerequisiteCommand(api: ExtensionApi): void;
|
|
105
|
+
//# sourceMappingURL=action.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"action.d.ts","sourceRoot":"","sources":["../action.ts"],"names":[],"mappings":"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"}
|