@open-agent-toolkit/cli 0.2.54 → 0.2.56
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/assets/bundle-metadata.json +1 -1
- package/assets/docs/cli-utilities/configuration.md +12 -2
- package/assets/docs/docs-tooling/commands.md +36 -5
- package/assets/docs/reference/oat-directory-structure.md +56 -4
- package/assets/docs/workflows/skills/recon.md +28 -12
- package/assets/public-package-versions.json +4 -4
- package/assets/skills/oat-dispatch-subagents/SKILL.md +4 -105
- package/assets/skills/oat-dispatch-subagents/references/record-schema.md +0 -226
- package/assets/skills/oat-project-autonomous/references/gate-inventory.md +2 -2
- package/assets/skills/oat-project-document/references/docs/autonomy-contract.md +2 -2
- package/assets/skills/oat-project-implement/references/docs/autonomy-contract.md +2 -2
- package/assets/skills/oat-project-pr-final/references/docs/autonomy-contract.md +2 -2
- package/assets/skills/oat-project-quick-start/references/docs/autonomy-contract.md +2 -2
- package/assets/skills/recon/SKILL.md +76 -38
- package/assets/skills/recon/references/packet-contract.md +138 -105
- package/assets/skills/recon/scripts/lib/contracts.mjs +181 -674
- package/assets/skills/recon/scripts/lib/validated-run.mjs +10 -16
- package/assets/skills/recon/scripts/render-packet.mjs +7 -20
- package/assets/skills/recon/scripts/validate-packet.mjs +177 -344
- package/dist/commands/config/index.d.ts +1 -0
- package/dist/commands/config/index.d.ts.map +1 -1
- package/dist/commands/config/index.js +51 -4
- package/dist/commands/docs/index-generate/generator.d.ts +43 -1
- package/dist/commands/docs/index-generate/generator.d.ts.map +1 -1
- package/dist/commands/docs/index-generate/generator.js +169 -3
- package/dist/commands/docs/index-generate/index.d.ts +8 -3
- package/dist/commands/docs/index-generate/index.d.ts.map +1 -1
- package/dist/commands/docs/index-generate/index.js +340 -24
- package/dist/commands/docs/init/scaffold.d.ts +11 -1
- package/dist/commands/docs/init/scaffold.d.ts.map +1 -1
- package/dist/commands/docs/init/scaffold.js +11 -2
- package/dist/config/oat-config.d.ts +14 -0
- package/dist/config/oat-config.d.ts.map +1 -1
- package/dist/config/oat-config.js +61 -0
- package/dist/fs/assets.d.ts +33 -4
- package/dist/fs/assets.d.ts.map +1 -1
- package/dist/fs/assets.js +127 -12
- package/package.json +2 -2
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: recon
|
|
3
|
-
version: 1.0
|
|
3
|
+
version: 1.1.0
|
|
4
4
|
description: Use when a bounded investigation needs source-grounded evidence before analysis or implementation. Produces a validated evidence-packet directory through approved provider-neutral worker waves.
|
|
5
5
|
argument-hint: '<question-or-target> [--profile quick|standard|thorough] [--scope description] [--context path] [--output directory] [--strict]'
|
|
6
6
|
disable-model-invocation: true
|
|
@@ -54,6 +54,21 @@ Report these compact stage transitions:
|
|
|
54
54
|
|
|
55
55
|
Do not print worker transcripts or raw dossier content.
|
|
56
56
|
|
|
57
|
+
When a run stops early or publishes a partial, label every failure with one of
|
|
58
|
+
these categories so a controller problem is never reported as a worker
|
|
59
|
+
problem:
|
|
60
|
+
|
|
61
|
+
- `worker`: an accepted lane failed, was cancelled, or wrote an invalid
|
|
62
|
+
artifact;
|
|
63
|
+
- `provider/dispatch`: the launch surface could not satisfy the approved
|
|
64
|
+
envelope, or a launched axis drifted from approval;
|
|
65
|
+
- `contract validation`: artifacts were produced but the packet or a
|
|
66
|
+
candidate failed deterministic validation;
|
|
67
|
+
- `source availability`: a declared source was unavailable, stale, or lacked
|
|
68
|
+
a read-only boundary.
|
|
69
|
+
|
|
70
|
+
State whether every accepted lane reached a terminal result.
|
|
71
|
+
|
|
57
72
|
## Workflow
|
|
58
73
|
|
|
59
74
|
### Step 1: Complete the Request
|
|
@@ -123,58 +138,81 @@ intended scope: `oat tools install utility --scope <user|project>` or, when the
|
|
|
123
138
|
pack is already installed, `oat tools update --pack utility --scope
|
|
124
139
|
<user|project>`.
|
|
125
140
|
|
|
126
|
-
Read `${UTILITY_SKILLS_ROOT}/oat-dispatch-subagents/SKILL.md` and
|
|
127
|
-
|
|
141
|
+
Read `${UTILITY_SKILLS_ROOT}/oat-dispatch-subagents/SKILL.md` and perform
|
|
142
|
+
only the selection steps of its Full-Information Selection: observe the
|
|
143
|
+
catalog, resolve one exact target, and record the selection. Stop before its
|
|
144
|
+
launch step; nothing launches until Step 5 runs after approval. From the same
|
|
145
|
+
root, read
|
|
128
146
|
`subagent-orchestration/references/model-selection-principles.md`, exactly one
|
|
129
147
|
active-provider selection reference, and the matching
|
|
130
148
|
`oat-dispatch-subagents` provider mechanics reference. Do not copy provider
|
|
131
149
|
catalogs or exact launch construction into this skill.
|
|
132
150
|
|
|
133
|
-
|
|
151
|
+
Resolve every planned and conditional wave against one exact target satisfying
|
|
134
152
|
the run-wide floor. Prefer the canonical `recon-worker` role. If that role is
|
|
135
|
-
unavailable,
|
|
153
|
+
unavailable, plan the generic role with the complete worker contract as a
|
|
136
154
|
visible generic role fallback before approval. A fallback after approval is
|
|
137
155
|
forbidden.
|
|
138
156
|
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
- provider, route, role selector, model, effort, reasoning mode, and service
|
|
142
|
-
tier;
|
|
143
|
-
- profile, wave classes and floors, lane identities, lane scopes, conditional
|
|
144
|
-
lane caps, and concurrency;
|
|
145
|
-
- per-lane authority, writable path, deadlines, and retry limits; and
|
|
146
|
-
- live catalog observation identity and canonical approval fingerprint.
|
|
157
|
+
Write the approval envelope into `manifest.execution`. It binds:
|
|
147
158
|
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
### Step 5: Execute the Approved Waves
|
|
159
|
+
- provider, route, role, model, effort, reasoning mode, and service tier;
|
|
160
|
+
- authority level, maximum concurrency, per-lane deadline, and retry limit; and
|
|
161
|
+
- every wave with its mode, task class, and conditional flag, and every lane
|
|
162
|
+
with its identity, read scope, and worker-owned write root.
|
|
154
163
|
|
|
155
|
-
|
|
156
|
-
`execute` operation. Before each launch, compare every approved selection and
|
|
157
|
-
execution axis plus relevant catalog identity. Any drift returns the complete
|
|
158
|
-
manifest for renewed approval.
|
|
164
|
+
Its canonical fingerprint covers every field above.
|
|
159
165
|
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
166
|
+
Present the exact provider, model and effort for explicit approval before any
|
|
167
|
+
worker launch, together with the full topology and hard execution limits. Named model examples are
|
|
168
|
+
illustrative and non-normative; never route from an example. Declining approval
|
|
169
|
+
leaves the run at `awaiting-approval` and launches nothing. Approval records
|
|
170
|
+
`explicit-user-approval`, the approval time, and the fingerprint.
|
|
171
|
+
|
|
172
|
+
**Deadlines.** Choose the per-lane deadline from the expected task class and
|
|
173
|
+
scope, and show it in the approval envelope; it is an approved execution limit,
|
|
174
|
+
not a short watchdog. A deadline authorizes the provider to end a lane and
|
|
175
|
+
report a terminal timeout. It never authorizes the controller to interrupt an
|
|
176
|
+
accepted lane by hand: elapsed display time is not a failure. If the provider
|
|
177
|
+
cannot enforce the deadline, wait or poll and report elapsed time, or obtain
|
|
178
|
+
renewed approval before any cancellation.
|
|
179
|
+
|
|
180
|
+
### Step 5: Preflight the Launch Surface, Then Execute
|
|
181
|
+
|
|
182
|
+
Before any worker launch, confirm that the live launch surface can run the
|
|
183
|
+
approved role, model, effort, and authority level, and can return each lane's
|
|
184
|
+
result. If any approved axis cannot be satisfied, stop with a
|
|
185
|
+
`provider/dispatch` diagnostic, leave the run at `awaiting-approval`, and
|
|
186
|
+
launch nothing. Never substitute a different axis to make the launch fit.
|
|
187
|
+
|
|
188
|
+
Launch each wave through the dispatch dependency with exactly the approved
|
|
189
|
+
axes. Immediately before each launch, compare the axes that will actually run
|
|
190
|
+
against the approval fingerprint. Any drift returns the complete manifest for
|
|
191
|
+
renewed approval. Launch acceptance is distinct from worker completion. After
|
|
192
|
+
acceptance there is no replacement child, alternate route, target
|
|
193
|
+
substitution, or no silent retry. If an accepted lane fails, is cancelled, or
|
|
194
|
+
times out, record that pass as failed with a material `PASS_FAILED` gap
|
|
195
|
+
naming the pass.
|
|
196
|
+
|
|
197
|
+
Run the passes in this order:
|
|
167
198
|
|
|
168
199
|
1. `map` and `gather` workers write unique dossiers under `raw/dossiers/`.
|
|
169
200
|
2. `compile` writes a candidate canonical claim ledger.
|
|
170
|
-
3.
|
|
201
|
+
3. Source preflight: run `scripts/validate-artifact.mjs` on the candidate
|
|
202
|
+
manifest and ledger, then reopen every declared source and evidence locator
|
|
203
|
+
with the checks in `scripts/validate-packet.mjs`. Resolve source roots to
|
|
204
|
+
canonical realpaths, pin one observation time per source, capture URLs or
|
|
205
|
+
mark them unavailable, and add a material gap for every ineligible source
|
|
206
|
+
and each affected claim. Do not create review briefs until the candidate
|
|
207
|
+
manifest and ledger pair validates.
|
|
171
208
|
4. profile-required `verify`, `adversary`, and `coverage` workers consume only
|
|
172
209
|
immutable selectively blind briefs created by
|
|
173
210
|
`scripts/create-review-brief.mjs` at unique paths.
|
|
174
211
|
5. `reconcile` writes a new candidate ledger without mutating the prior ledger.
|
|
175
212
|
|
|
176
213
|
Use `references/worker-contract.md` for every assignment. Never allow two
|
|
177
|
-
workers to share a write path.
|
|
214
|
+
workers to share a write path. Every dossier records its approved wave and lane;
|
|
215
|
+
every review result records its approved lane.
|
|
178
216
|
|
|
179
217
|
Read `references/packet-contract.md` before creating any packet artifact. Run
|
|
180
218
|
`scripts/validate-artifact.mjs` on each candidate and record its canonical
|
|
@@ -205,9 +243,9 @@ candidate failure separately. Only a publishable candidate proceeds to
|
|
|
205
243
|
`scripts/render-packet.mjs`; failure leaves no consumer entry point that could
|
|
206
244
|
refer to a different canonical generation.
|
|
207
245
|
|
|
208
|
-
Derive the achieved profile from
|
|
209
|
-
|
|
210
|
-
of achievement. A `quick` run can reach `supported` but never `verified`.
|
|
246
|
+
Derive the achieved profile from complete, typed, digest-bound same-run
|
|
247
|
+
artifacts written by approved lanes. Do not accept a worker or manifest
|
|
248
|
+
assertion of achievement. A `quick` run can reach `supported` but never `verified`.
|
|
211
249
|
`verified` claims require unique complete semantic, adversarial, and coverage
|
|
212
250
|
results bound to immutable briefs and correct claim dispositions. Unresolved
|
|
213
251
|
material challenge prevents verification. A run with contested claims may
|
|
@@ -231,9 +269,9 @@ diagnostics, and safe failure record for diagnosis.
|
|
|
231
269
|
### Step 8: Return the Directory-Only Handoff
|
|
232
270
|
|
|
233
271
|
Return only the packet directory path plus a compact summary containing status,
|
|
234
|
-
requested and achieved profile, claim-state counts, unresolved gaps,
|
|
235
|
-
|
|
236
|
-
reasoning. The consumer may open `packet.md` and selectively follow compact
|
|
272
|
+
requested and achieved profile, claim-state counts, unresolved gaps, failed or
|
|
273
|
+
omitted passes, and each failure's category from the list above. Do not inline
|
|
274
|
+
raw dossiers, source bodies, or worker reasoning. The consumer may open `packet.md` and selectively follow compact
|
|
237
275
|
references.
|
|
238
276
|
|
|
239
277
|
## Examples
|
|
@@ -13,7 +13,6 @@ a new version rather than accepting untyped fields.
|
|
|
13
13
|
├── claims.json
|
|
14
14
|
├── reviews/
|
|
15
15
|
│ ├── briefs/
|
|
16
|
-
│ ├── locator-validation.json
|
|
17
16
|
│ ├── semantic/
|
|
18
17
|
│ ├── adversarial/
|
|
19
18
|
│ ├── coverage/
|
|
@@ -21,7 +20,6 @@ a new version rather than accepting untyped fields.
|
|
|
21
20
|
└── raw/
|
|
22
21
|
├── dossiers/
|
|
23
22
|
├── drafts/
|
|
24
|
-
├── dispatch/
|
|
25
23
|
├── quarantine/
|
|
26
24
|
└── failure.json
|
|
27
25
|
```
|
|
@@ -36,16 +34,9 @@ An artifact reference is `{ "path": "packet-relative/path", "digest":
|
|
|
36
34
|
"sha256:<64 lowercase hex>" }`. Paths must remain inside the packet directory.
|
|
37
35
|
Digests cover the exact bytes on disk.
|
|
38
36
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
preserved, no insignificant whitespace, and SHA-256 with the `sha256:` prefix.
|
|
43
|
-
The stored canonical JSON text and fingerprint cover the whole projection.
|
|
44
|
-
Every `writable_roots`, `escalate_when`, and `candidates_considered` member is a
|
|
45
|
-
non-empty string. These arrays use stable sorted-set form: entries are unique
|
|
46
|
-
and lexicographically ordered before approval, and packet validation rejects
|
|
47
|
-
nulls, empty strings, duplicates, or unstable ordering rather than normalizing
|
|
48
|
-
them after approval.
|
|
37
|
+
Fingerprints use canonical JSON: UTF-8, object keys sorted lexicographically,
|
|
38
|
+
array order preserved, no insignificant whitespace, and SHA-256 with the
|
|
39
|
+
`sha256:` prefix.
|
|
49
40
|
|
|
50
41
|
## One Validation Boundary
|
|
51
42
|
|
|
@@ -53,18 +44,15 @@ Version 1 compiles persisted packet inputs exactly once into one non-persisted,
|
|
|
53
44
|
deeply immutable `ValidatedRun`. This value is an internal normalized graph,
|
|
54
45
|
not an artifact kind, schema version, file, cache, or caller-selectable profile.
|
|
55
46
|
Assurance derivation and rendering accept only `ValidatedRun`; they never
|
|
56
|
-
reopen or independently reinterpret raw manifest, ledger, review,
|
|
47
|
+
reopen or independently reinterpret raw manifest, ledger, review, or
|
|
57
48
|
reconciliation artifacts.
|
|
58
49
|
|
|
59
50
|
Construction is all-or-nothing. A valid graph contains:
|
|
60
51
|
|
|
61
|
-
- one
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
target, and original live catalog identity;
|
|
66
|
-
- one exact approved wave/lane topology, with one terminal stage and matching
|
|
67
|
-
accepted/completed receipt resolution for every required lane;
|
|
52
|
+
- one approved execution envelope whose canonical fingerprint matches the
|
|
53
|
+
recorded explicit user approval;
|
|
54
|
+
- complete typed same-run artifacts, each written by an approved wave and lane,
|
|
55
|
+
from which the achieved profile is derived;
|
|
68
56
|
- exactly one terminal reconciliation for standard or thorough runs and one
|
|
69
57
|
immutable canonical prior-ledger identity used by all review, transition,
|
|
70
58
|
addition, and removal checks;
|
|
@@ -80,22 +68,11 @@ Construction is all-or-nothing. A valid graph contains:
|
|
|
80
68
|
- derived claim assurance, achieved profile, material gaps, and publication
|
|
81
69
|
status.
|
|
82
70
|
|
|
83
|
-
Reject
|
|
84
|
-
|
|
85
|
-
retargeted roots, raw secret-bearing stale excerpts, and
|
|
86
|
-
materiality. Equivalent-looking inputs do not excuse a
|
|
87
|
-
|
|
88
|
-
The approved, accepted, and completed receipts carry the manifest's exact
|
|
89
|
-
`approvedAt` value. The accepted and completed receipts also carry one
|
|
90
|
-
identical launch-acceptance record, including the accepted child handle; a
|
|
91
|
-
different terminal handle is a replacement and fails validation. The catalog
|
|
92
|
-
recheck is a distinct observation from the projection's original catalog
|
|
93
|
-
observation, occurs strictly after approval and strictly before launch
|
|
94
|
-
acceptance, and retains the approved catalog source, context, and relevant
|
|
95
|
-
fingerprint. The completed receipt's terminal timestamp is parseable and cannot
|
|
96
|
-
precede launch acceptance; equality is valid at the contract's millisecond
|
|
97
|
-
precision. Copied, non-fresh, or causally impossible receipt evidence cannot
|
|
98
|
-
support publication.
|
|
71
|
+
Reject approval fingerprint drift, unknown execution fields, artifacts from
|
|
72
|
+
unapproved lanes, duplicate or shadow reconciliation results, symlink root
|
|
73
|
+
aliases, retargeted roots, raw secret-bearing stale excerpts, and
|
|
74
|
+
caller-downgraded gap materiality. Equivalent-looking inputs do not excuse a
|
|
75
|
+
failed invariant.
|
|
99
76
|
|
|
100
77
|
## Manifest
|
|
101
78
|
|
|
@@ -105,24 +82,77 @@ support publication.
|
|
|
105
82
|
- `request`: objective, questions, included/excluded scope, stable context
|
|
106
83
|
references, confirmed output path;
|
|
107
84
|
- discriminated `sources`;
|
|
108
|
-
- `execution`:
|
|
109
|
-
explicit-user approval evidence, approval timestamp, and fresh catalog
|
|
110
|
-
recheck. The projection is identical to the dispatch dependency's canonical
|
|
111
|
-
v1 object rather than a packet-local summary;
|
|
112
|
-
- `stages`: `recon.stage-result` records whose single artifact ID, lane, and
|
|
113
|
-
exact `waveId` plus prepared/approved/accepted/completed receipt IDs bind
|
|
114
|
-
every completed pass to one hashed same-run artifact of the required kind;
|
|
85
|
+
- `execution`: the approved execution envelope described below;
|
|
115
86
|
- `artifacts`: direct references; and
|
|
116
87
|
- `gaps`: categorical omitted, unavailable, stale, or failed work, each with an
|
|
117
88
|
explicit boolean `material` classification and affected source, claim, and
|
|
118
89
|
coverage-finding IDs when applicable.
|
|
119
90
|
|
|
91
|
+
### Execution Envelope
|
|
92
|
+
|
|
93
|
+
`execution` is a closed object binding exactly what the user approved:
|
|
94
|
+
|
|
95
|
+
- `provider`, `route`, `role`, `model`, `effort`: non-empty strings;
|
|
96
|
+
- `reasoningMode`, `serviceTier`: string or `null`;
|
|
97
|
+
- `authority`: `provider-enforced` or `contract-enforced`;
|
|
98
|
+
- `maxConcurrency`, `deadlineSeconds`: integers of at least 1; `retryLimit`:
|
|
99
|
+
integer of at least 0;
|
|
100
|
+
- `waves`: closed `{ waveId, mode, taskClass, lanes, conditional }` records
|
|
101
|
+
with a unique wave identity, a mode from the wave-mode set, a task class from
|
|
102
|
+
the durable task-class order, and at least one closed
|
|
103
|
+
`{ laneId, scope, writeRoot }` lane whose identity is unique across the run
|
|
104
|
+
and whose write root is a packet-relative path; and
|
|
105
|
+
- `approval`: `{ type: "explicit-user-approval", approvedAt, fingerprint }`.
|
|
106
|
+
|
|
107
|
+
The fingerprint is the canonical SHA-256 of `execution` with `approval`
|
|
108
|
+
removed. Validation recomputes it; any difference is
|
|
109
|
+
`APPROVAL_FINGERPRINT_MISMATCH`. The envelope records what will run, not proof
|
|
110
|
+
that a launcher ran it. Launch acceptance and per-lane terminal outcomes are
|
|
111
|
+
reported in the controller's status and as `PASS_FAILED` gaps, not as packet
|
|
112
|
+
artifacts.
|
|
113
|
+
|
|
114
|
+
Wave modes are `map`, `gather`, `compile`, `semantic-verification`,
|
|
115
|
+
`adversarial`, `coverage`, `reconciliation`, `redundant-gather`,
|
|
116
|
+
`redundant-verification`, and `contradiction-resolution`.
|
|
117
|
+
|
|
118
|
+
### Passes and Achieved Profile
|
|
119
|
+
|
|
120
120
|
Run status is `preparing`, `awaiting-approval`, `running`, `complete`, `partial`,
|
|
121
|
-
or `failed`. The validator
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
121
|
+
or `failed`. The validator, not a worker, derives the achieved profile from
|
|
122
|
+
complete typed artifacts of the same run:
|
|
123
|
+
|
|
124
|
+
| Pass | Complete artifact |
|
|
125
|
+
| -------------------------- | ------------------------------------------------------------ |
|
|
126
|
+
| `map` | a `recon.raw-dossier` with mode `map` |
|
|
127
|
+
| `gather` | a `recon.raw-dossier` with mode `gather` |
|
|
128
|
+
| `semantic-verification` | a `recon.review-result` with kind `semantic` |
|
|
129
|
+
| `adversarial` | a `recon.review-result` with kind `adversarial` |
|
|
130
|
+
| `coverage` | a `recon.review-result` with kind `coverage` |
|
|
131
|
+
| `reconciliation` | a `recon.review-result` with kind `reconciliation` |
|
|
132
|
+
| `redundant-gather` | complete `gather` dossiers from at least two distinct lanes |
|
|
133
|
+
| `redundant-verification` | a `recon.review-result` with kind `redundant-verification` |
|
|
134
|
+
| `contradiction-resolution` | a `recon.review-result` with kind `contradiction-resolution` |
|
|
135
|
+
|
|
136
|
+
`quick` requires `map` and `gather`; the canonical ledger itself is the
|
|
137
|
+
compile result, so an approved `compile` lane needs no separate artifact, and
|
|
138
|
+
locator validation is performed by the validator.
|
|
139
|
+
`standard` adds `semantic-verification`, `adversarial`, `coverage`, and
|
|
140
|
+
`reconciliation`. `thorough` adds `redundant-gather`,
|
|
141
|
+
`redundant-verification`, and `contradiction-resolution`.
|
|
142
|
+
|
|
143
|
+
Every dossier records the approved `waveId` and `laneId` that wrote it; every
|
|
144
|
+
review result records its approved `reviewerLane`. The lane must belong to a
|
|
145
|
+
wave whose mode matches the artifact (a semantic result to a
|
|
146
|
+
`semantic-verification` wave, a gather dossier to a `gather` or
|
|
147
|
+
`redundant-gather` wave, and so on); otherwise the artifact is
|
|
148
|
+
`UNAPPROVED_LANE`. The artifact path must equal or sit under the lane's
|
|
149
|
+
approved `writeRoot`; otherwise it is `LANE_WRITE_PATH_VIOLATION`. Every
|
|
150
|
+
non-conditional approved lane must either have written an artifact or be
|
|
151
|
+
covered by a material `PASS_FAILED` or `PASS_OMITTED` gap naming its wave
|
|
152
|
+
mode; otherwise the packet fails with `MISSING_LANE_OUTCOME`. Each required
|
|
153
|
+
pass of the requested profile that has no complete artifact must likewise be
|
|
154
|
+
named by such a gap, or the packet fails with
|
|
155
|
+
`MISSING_PASS_OUTCOME_EVIDENCE`.
|
|
126
156
|
|
|
127
157
|
## Source Descriptors and Locators
|
|
128
158
|
|
|
@@ -162,12 +192,23 @@ mismatch invalidates the locator. Only `exact` and `redacted-exact` states are
|
|
|
162
192
|
assurance-eligible. Managed packet, capture, repository, and output paths reject
|
|
163
193
|
both ancestor and final-component symlinks before reads, hashes, or writes.
|
|
164
194
|
|
|
195
|
+
Source preflight runs these checks on the candidate manifest and ledger before
|
|
196
|
+
any review brief is created, so ineligible sources and broken locators are
|
|
197
|
+
found before the expensive review passes rather than at publication.
|
|
198
|
+
|
|
165
199
|
## Claim Ledger
|
|
166
200
|
|
|
167
201
|
`recon.claim-ledger` version 1 contains run ID, monotonic revision, direct input
|
|
168
202
|
references, synthesis, evidence, claims, unresolved questions, and explicit
|
|
169
203
|
claim transitions.
|
|
170
204
|
|
|
205
|
+
Every claim evidence link is a closed `{ evidenceId, relation }` object whose
|
|
206
|
+
`evidenceId` resolves to an evidence record in the same ledger and whose
|
|
207
|
+
`relation` is `supports`, `contradicts`, `qualifies`, or `context`. A claim
|
|
208
|
+
links each evidence record at most once. String links, open objects, unknown
|
|
209
|
+
relations, unresolved IDs, and duplicates fail `validate-artifact.mjs` before
|
|
210
|
+
any review brief can consume the ledger.
|
|
211
|
+
|
|
171
212
|
Claim states are categorical:
|
|
172
213
|
|
|
173
214
|
- `provisional`: compiled, not mechanically validated;
|
|
@@ -186,27 +227,27 @@ incoming transition; the genesis exception cannot be reused.
|
|
|
186
227
|
|
|
187
228
|
Quick packets never contain `verified` claims. Standard and thorough claims need
|
|
188
229
|
recorded independent semantic, adversarial, and coverage reviews. Every review
|
|
189
|
-
ID resolves to a unique, complete, typed, hashed result
|
|
190
|
-
immutable brief digest
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
revision
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
230
|
+
ID resolves to a unique, complete, typed, hashed result from an approved lane,
|
|
231
|
+
bound to the exact immutable brief digest and the claim's required disposition.
|
|
232
|
+
An incomplete or unapproved result cannot contribute assurance or
|
|
233
|
+
reconciliation. A material unresolved challenge or coverage finding prevents
|
|
234
|
+
verification. A run with contested claims may publish as `complete` when all
|
|
235
|
+
declared questions and claims are resolved or characterized; contested claims
|
|
236
|
+
are rendered under "Contradictions and Qualifications". If an unresolved
|
|
237
|
+
challenge represents an unanswered question or missing source evidence that
|
|
238
|
+
leaves investigation incomplete, it must be recorded as a material gap in
|
|
239
|
+
`manifest.gaps` and the run published as `partial`. Review workers propose;
|
|
240
|
+
only a reconciler writes a new ledger candidate. Reconciliation binds the prior
|
|
241
|
+
ledger reference and revision, the next revision, the exact complete
|
|
242
|
+
assurance-review set, and the exact canonical claim transitions. Standard and
|
|
243
|
+
thorough output is exactly the next revision of the bound prior ledger;
|
|
244
|
+
revision one cannot bypass reconciliation. It also binds additions, removals,
|
|
245
|
+
and every prior/current state change; preserves statement, evidence-link, and
|
|
246
|
+
qualification continuity; accepts new evidence only when an incorporated review
|
|
247
|
+
supplied the exact record plus a closed `{ evidenceId, claimId, relation }`
|
|
248
|
+
association to one of that review's disposition claims; preserves every
|
|
249
|
+
unaffected evidence link byte-for-byte; and requires a typed rejection
|
|
250
|
+
disposition from a complete review before removing a prior claim.
|
|
210
251
|
|
|
211
252
|
## Evidence and Secret Redaction
|
|
212
253
|
|
|
@@ -223,34 +264,25 @@ branch; source ineligibility never bypasses persistence safety.
|
|
|
223
264
|
|
|
224
265
|
## Other Artifacts
|
|
225
266
|
|
|
226
|
-
- `recon.raw-dossier`: assignment identity,
|
|
227
|
-
uncertainty, contradictions, gaps, and outcome.
|
|
267
|
+
- `recon.raw-dossier`: assignment identity, approved wave and lane, mode,
|
|
268
|
+
inputs/exclusions, findings, uncertainty, contradictions, gaps, and outcome.
|
|
228
269
|
- `recon.review-brief`: immutable selective-blind projection and digest.
|
|
229
|
-
- `recon.review-result`: review kind, lane, exact brief reference,
|
|
270
|
+
- `recon.review-result`: review kind, approved lane, exact brief reference,
|
|
230
271
|
permitted/excluded inputs, dispositions, new evidence, closed typed
|
|
231
272
|
claim/evidence associations, coverage findings, unresolved issues, and
|
|
232
273
|
completion status. Every new evidence record has at least one exact
|
|
233
274
|
association, and an association cannot name evidence absent from that result
|
|
234
|
-
or a claim without a disposition in that result. Reconciliation results
|
|
235
|
-
brief reference with prior-ledger/revision, additions/removals,
|
|
236
|
-
transitions, and coverage-disposition bindings. Coverage findings are
|
|
237
|
-
records bound to affected claims and exact manifest gaps. Accepted
|
|
238
|
-
gaps require a legal downgrade for every affected claim; a resolved
|
|
239
|
-
instead names exact typed evidence. Non-material coverage gaps
|
|
240
|
-
verified claims and transition provisional claims to unresolved,
|
|
241
|
-
existing supported claims remain supported without verified promotion.
|
|
242
|
-
Thorough redundant verification and
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
affected-contradiction dispositions.
|
|
246
|
-
- `recon.stage-result`: stable stage ID, mode, lane, status, exactly one output
|
|
247
|
-
artifact ID, accepted/completed receipt IDs, and safe diagnostics.
|
|
248
|
-
- `recon.dispatch-receipt`: immutable prepared, approved, accepted, or
|
|
249
|
-
completed evidence. Every state repeats the exact canonical projection,
|
|
250
|
-
canonical JSON, and fingerprint. Approved and later states bind the same
|
|
251
|
-
explicit approval evidence; accepted and completed states bind the fresh
|
|
252
|
-
catalog recheck and launch acceptance; completed binds the terminal outcome
|
|
253
|
-
and artifact IDs.
|
|
275
|
+
or a claim without a disposition in that result. Reconciliation results
|
|
276
|
+
replace the brief reference with prior-ledger/revision, additions/removals,
|
|
277
|
+
exact transitions, and coverage-disposition bindings. Coverage findings are
|
|
278
|
+
closed records bound to affected claims and exact manifest gaps. Accepted
|
|
279
|
+
material gaps require a legal downgrade for every affected claim; a resolved
|
|
280
|
+
finding instead names exact typed evidence. Non-material coverage gaps
|
|
281
|
+
downgrade verified claims and transition provisional claims to unresolved,
|
|
282
|
+
while existing supported claims remain supported without verified promotion.
|
|
283
|
+
Thorough redundant verification and contradiction resolution are
|
|
284
|
+
claim-bearing typed review results, not raw dossiers: they bind immutable
|
|
285
|
+
briefs, claim dispositions, and explicit affected-contradiction dispositions.
|
|
254
286
|
|
|
255
287
|
Create immutable mode-specific review projections with
|
|
256
288
|
`scripts/create-review-brief.mjs`. Verification briefs expose only claim
|
|
@@ -268,15 +300,14 @@ record under `raw/quarantine/`. Never promote invalid output.
|
|
|
268
300
|
|
|
269
301
|
Run `scripts/validate-packet.mjs <packet-dir>` before rendering or publication.
|
|
270
302
|
It delegates to the single validation boundary, which validates schemas, IDs,
|
|
271
|
-
references, containment, hashes, source reopening, locators, the
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
generation.
|
|
303
|
+
references, containment, hashes, source reopening, locators, the approval
|
|
304
|
+
fingerprint, approved lanes, pass outcomes, the one terminal reconciliation,
|
|
305
|
+
legal transitions, secret-safe persistence, derived gaps, assurance, and
|
|
306
|
+
requested vs achieved profile. Candidate validation is non-destructive for
|
|
307
|
+
canonical diagnostic artifacts, but a non-publishable candidate withdraws any
|
|
308
|
+
existing `packet.md` and does not authorize rendering. Only a valid `complete`
|
|
309
|
+
or honest `partial` candidate is publishable, so a rejected canonical
|
|
310
|
+
generation cannot retain a consumer entry point from another generation.
|
|
280
311
|
|
|
281
312
|
`complete` requires the requested profile and no material gap. `partial` is
|
|
282
313
|
valid when either a lower profile was achieved or at least one material gap is
|
|
@@ -301,7 +332,9 @@ dossier content.
|
|
|
301
332
|
|
|
302
333
|
This boundary does not add another schema version, review pass, persisted
|
|
303
334
|
intermediate, generalized plugin artifact kind, saved validation profile,
|
|
304
|
-
provider behavior, or integration surface. It does not
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
335
|
+
provider behavior, or integration surface. It does not require launcher-emitted
|
|
336
|
+
dispatch receipts; reintroduce those only when a launcher exists that produces
|
|
337
|
+
them itself. It does not change research-pack distribution, documentation,
|
|
338
|
+
backlog integrations, `quick`/`standard`/`thorough`, selective blindness,
|
|
339
|
+
categorical claim states, honest partial publication, or directory-only
|
|
340
|
+
handoff.
|