@open-agent-toolkit/cli 0.2.52 → 0.2.54

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.
Files changed (94) hide show
  1. package/assets/agents/recon-worker.md +105 -0
  2. package/assets/bundle-metadata.json +1 -1
  3. package/assets/docs/cli-utilities/tool-packs.md +62 -8
  4. package/assets/docs/contributing/skills.md +26 -0
  5. package/assets/docs/workflows/skills/index.md +3 -0
  6. package/assets/docs/workflows/skills/recon.md +194 -0
  7. package/assets/public-package-versions.json +4 -4
  8. package/assets/skills/oat-dispatch-subagents/SKILL.md +105 -4
  9. package/assets/skills/oat-dispatch-subagents/references/record-schema.md +226 -0
  10. package/assets/skills/oat-project-autonomous/references/gate-inventory.md +2 -2
  11. package/assets/skills/oat-project-document/references/docs/autonomy-contract.md +2 -2
  12. package/assets/skills/oat-project-implement/references/docs/autonomy-contract.md +2 -2
  13. package/assets/skills/oat-project-pr-final/references/docs/autonomy-contract.md +2 -2
  14. package/assets/skills/oat-project-quick-start/references/docs/autonomy-contract.md +2 -2
  15. package/assets/skills/recon/SKILL.md +260 -0
  16. package/assets/skills/recon/references/packet-contract.md +307 -0
  17. package/assets/skills/recon/references/profiles.md +58 -0
  18. package/assets/skills/recon/references/worker-contract.md +71 -0
  19. package/assets/skills/recon/scripts/create-review-brief.mjs +452 -0
  20. package/assets/skills/recon/scripts/lib/canonical-json.mjs +55 -0
  21. package/assets/skills/recon/scripts/lib/contracts.mjs +2462 -0
  22. package/assets/skills/recon/scripts/lib/safe-path.mjs +120 -0
  23. package/assets/skills/recon/scripts/lib/validated-run.mjs +86 -0
  24. package/assets/skills/recon/scripts/reconcile-ledger.mjs +360 -0
  25. package/assets/skills/recon/scripts/render-packet.mjs +392 -0
  26. package/assets/skills/recon/scripts/validate-artifact.mjs +96 -0
  27. package/assets/skills/recon/scripts/validate-packet.mjs +2359 -0
  28. package/dist/commands/doctor/index.js +5 -5
  29. package/dist/commands/init/index.d.ts.map +1 -1
  30. package/dist/commands/init/index.js +7 -8
  31. package/dist/commands/status/index.d.ts +2 -2
  32. package/dist/commands/status/index.d.ts.map +1 -1
  33. package/dist/commands/status/index.js +8 -8
  34. package/dist/commands/sync/index.d.ts.map +1 -1
  35. package/dist/commands/sync/index.js +25 -9
  36. package/dist/commands/sync/sync.types.d.ts +2 -2
  37. package/dist/commands/sync/sync.types.d.ts.map +1 -1
  38. package/dist/commands/tools/migrate/index.d.ts.map +1 -1
  39. package/dist/commands/tools/migrate/index.js +25 -1
  40. package/dist/commands/tools/migrate/migrate-pack.d.ts +5 -0
  41. package/dist/commands/tools/migrate/migrate-pack.d.ts.map +1 -1
  42. package/dist/commands/tools/migrate/migrate-pack.js +66 -7
  43. package/dist/commands/tools/remove/index.js +1 -1
  44. package/dist/commands/tools/remove/remove-tools.d.ts +5 -1
  45. package/dist/commands/tools/remove/remove-tools.d.ts.map +1 -1
  46. package/dist/commands/tools/remove/remove-tools.js +81 -1
  47. package/dist/commands/tools/shared/apply-pack-reconcile.d.ts +3 -0
  48. package/dist/commands/tools/shared/apply-pack-reconcile.d.ts.map +1 -1
  49. package/dist/commands/tools/shared/apply-pack-reconcile.js +40 -9
  50. package/dist/commands/tools/shared/format-pack-inventory.d.ts.map +1 -1
  51. package/dist/commands/tools/shared/format-pack-inventory.js +3 -0
  52. package/dist/commands/tools/shared/install-sync-context.d.ts +2 -1
  53. package/dist/commands/tools/shared/install-sync-context.d.ts.map +1 -1
  54. package/dist/commands/tools/shared/install-sync-context.js +14 -3
  55. package/dist/commands/tools/shared/pack-dependencies.d.ts +14 -0
  56. package/dist/commands/tools/shared/pack-dependencies.d.ts.map +1 -0
  57. package/dist/commands/tools/shared/pack-dependencies.js +54 -0
  58. package/dist/commands/tools/shared/pack-inventory.d.ts.map +1 -1
  59. package/dist/commands/tools/shared/pack-inventory.js +9 -9
  60. package/dist/commands/tools/shared/pack-lifecycle.d.ts +9 -1
  61. package/dist/commands/tools/shared/pack-lifecycle.d.ts.map +1 -1
  62. package/dist/commands/tools/shared/pack-lifecycle.js +102 -9
  63. package/dist/commands/tools/shared/pack-manifest.d.ts +2 -2
  64. package/dist/commands/tools/shared/pack-manifest.d.ts.map +1 -1
  65. package/dist/commands/tools/shared/pack-manifest.js +91 -2
  66. package/dist/commands/tools/shared/pack-reconcile.d.ts +15 -1
  67. package/dist/commands/tools/shared/pack-reconcile.d.ts.map +1 -1
  68. package/dist/commands/tools/shared/pack-reconcile.js +75 -13
  69. package/dist/commands/tools/shared/scoped-pack-intent.d.ts +8 -0
  70. package/dist/commands/tools/shared/scoped-pack-intent.d.ts.map +1 -1
  71. package/dist/commands/tools/shared/scoped-pack-intent.js +61 -15
  72. package/dist/commands/tools/shared/types.d.ts +7 -0
  73. package/dist/commands/tools/shared/types.d.ts.map +1 -1
  74. package/dist/commands/tools/update/update-tools.d.ts.map +1 -1
  75. package/dist/commands/tools/update/update-tools.js +7 -1
  76. package/dist/config/oat-config.d.ts +5 -1
  77. package/dist/config/oat-config.d.ts.map +1 -1
  78. package/dist/config/oat-config.js +19 -0
  79. package/dist/engine/index.d.ts +2 -2
  80. package/dist/engine/index.d.ts.map +1 -1
  81. package/dist/engine/index.js +1 -1
  82. package/dist/engine/scanner.d.ts +16 -1
  83. package/dist/engine/scanner.d.ts.map +1 -1
  84. package/dist/engine/scanner.js +98 -4
  85. package/dist/providers/codex/codec/sync-extension.d.ts +1 -1
  86. package/dist/providers/codex/codec/sync-extension.d.ts.map +1 -1
  87. package/dist/providers/codex/codec/sync-extension.js +7 -7
  88. package/dist/providers/cursor/codec/sync-extension.d.ts +1 -1
  89. package/dist/providers/cursor/codec/sync-extension.d.ts.map +1 -1
  90. package/dist/providers/cursor/codec/sync-extension.js +11 -13
  91. package/dist/shared/types.d.ts +1 -0
  92. package/dist/shared/types.d.ts.map +1 -1
  93. package/dist/shared/types.js +3 -0
  94. package/package.json +2 -2
package/assets/skills/oat-project-pr-final/references/docs/autonomy-contract.md CHANGED
@@ -252,11 +252,11 @@ remains immutable baseline evidence for the original p01-t01 verification.
252
252
  | `oat-project-implement/references/phase-execution.md` | `b31a9a4e6f75 -> NG` |
253
253
  | `oat-dispatch-subagents/SKILL.md` | `49987359dc09 -> NG` |
254
254
  | `oat-dispatch-subagents/references/provider-claude.md` | `06f64bd01ba6 -> NG` |
255
- | `oat-dispatch-subagents/SKILL.md` | `cb4f86157fd6 -> DISPATCH-01`; `f165b1626192 -> DISPATCH-01`; `7ed5e2b1eb71 -> PDISPATCH-01`; `11c72bcdebad -> DISPATCH-02`; `0834ee701e12 -> DISPATCH-02`; `7fda54e1d519 -> PDISPATCH-01` |
255
+ | `oat-dispatch-subagents/SKILL.md` | `cb4f86157fd6 -> DISPATCH-01`; `f165b1626192 -> DISPATCH-01`; `7ed5e2b1eb71 -> PDISPATCH-01`; `11c72bcdebad -> DISPATCH-02`; `0834ee701e12 -> DISPATCH-02`; `7fda54e1d519 -> PDISPATCH-01`; `061f76074399 -> NG`; `5ae9e0e4ac47 -> NG`; `a2664ca9acf1 -> DISPATCH-01`; `12793022a2a4 -> DISPATCH-01`; `4a31444d4369 -> NG`; `68abaecc3e94 -> NG`; `7053910e10ef -> NG`; `a25ba09f5945 -> DISPATCH-01`; `9cdb9a679938 -> NG`; `2bc7c4717fd3 -> NG`; `0c7341966904 -> NG`; `e17d0f753630 -> NG`; `9fb0dd804b14 -> NG`; `2bab3a57a985 -> DISPATCH-01`; `63bdef0459e0 -> NG`; `e1936c17fece -> NG`; `e8e18fc1154a -> NG` |
256
256
  | `oat-dispatch-subagents/references/provider-claude.md` | `fbe3a21e9533 -> NG` |
257
257
  | `oat-dispatch-subagents/references/provider-codex.md` | `95b0f82018c7 -> NG` |
258
258
  | `oat-dispatch-subagents/references/provider-cursor.md` | `f781555295a9 -> NG`; `55ccfef14fd6 -> NG` |
259
- | `oat-dispatch-subagents/references/record-schema.md` | `78f8069274a8 -> NG`; `1c9a84c4d1e0 -> NG`; `2a63da6e3a96 -> NG`; `30762d53b043 -> NG` |
259
+ | `oat-dispatch-subagents/references/record-schema.md` | `78f8069274a8 -> NG`; `1c9a84c4d1e0 -> NG`; `12cdc1878e52 -> NG`; `af49d3dd297a -> NG`; `b6ec6e06e5b6 -> NG`; `a3a7ab0a05b4 -> NG`; `95820a0aced8 -> NG`; `273f5072954a -> NG`; `c6ab5ab1e06e -> NG`; `eb509ef89f26 -> NG`; `a014397a631c -> NG`; `d07c12e91bd8 -> NG`; `8fa5bb3f4105 -> NG`; `0ca0e55fce05 -> NG`; `f1cab0929f78 -> DISPATCH-01`; `25795e03a05a -> DISPATCH-01`; `c868f3b5ecc5 -> NG`; `f56113f1b003 -> NG`; `fca94abe381d -> DISPATCH-01`; `afc8d0aca7f0 -> NG`; `7119e48819d8 -> NG`; `62c4de81f4a6 -> NG`; `2524fbd4eb09 -> DISPATCH-01`; `af8a7cdd0523 -> NG`; `e22e8a0915e7 -> NG`; `2a63da6e3a96 -> NG`; `30762d53b043 -> NG` |
260
260
  | `oat-project-dispatch-subagents/SKILL.md` | `eca03ad1ca12 -> PDISPATCH-01`; `59fbcdc79cea -> PDISPATCH-01` |
261
261
  | `oat-project-plan/SKILL.md` | `f99e44b39932 -> PLAN-12`; `7e6a9854504b -> NG` |
262
262
  | `oat-project-implement/references/completion-and-closeout.md` | `6909a5a5a1fa -> IMPLEMENT-19`; `a7c02ef670fd -> IMPLEMENT-19`; `9dde56d89a71 -> IMPLEMENT-16`; `13c41b2b2590 -> IMPLEMENT-16` |
package/assets/skills/oat-project-quick-start/references/docs/autonomy-contract.md CHANGED
@@ -252,11 +252,11 @@ remains immutable baseline evidence for the original p01-t01 verification.
252
252
  | `oat-project-implement/references/phase-execution.md` | `b31a9a4e6f75 -> NG` |
253
253
  | `oat-dispatch-subagents/SKILL.md` | `49987359dc09 -> NG` |
254
254
  | `oat-dispatch-subagents/references/provider-claude.md` | `06f64bd01ba6 -> NG` |
255
- | `oat-dispatch-subagents/SKILL.md` | `cb4f86157fd6 -> DISPATCH-01`; `f165b1626192 -> DISPATCH-01`; `7ed5e2b1eb71 -> PDISPATCH-01`; `11c72bcdebad -> DISPATCH-02`; `0834ee701e12 -> DISPATCH-02`; `7fda54e1d519 -> PDISPATCH-01` |
255
+ | `oat-dispatch-subagents/SKILL.md` | `cb4f86157fd6 -> DISPATCH-01`; `f165b1626192 -> DISPATCH-01`; `7ed5e2b1eb71 -> PDISPATCH-01`; `11c72bcdebad -> DISPATCH-02`; `0834ee701e12 -> DISPATCH-02`; `7fda54e1d519 -> PDISPATCH-01`; `061f76074399 -> NG`; `5ae9e0e4ac47 -> NG`; `a2664ca9acf1 -> DISPATCH-01`; `12793022a2a4 -> DISPATCH-01`; `4a31444d4369 -> NG`; `68abaecc3e94 -> NG`; `7053910e10ef -> NG`; `a25ba09f5945 -> DISPATCH-01`; `9cdb9a679938 -> NG`; `2bc7c4717fd3 -> NG`; `0c7341966904 -> NG`; `e17d0f753630 -> NG`; `9fb0dd804b14 -> NG`; `2bab3a57a985 -> DISPATCH-01`; `63bdef0459e0 -> NG`; `e1936c17fece -> NG`; `e8e18fc1154a -> NG` |
256
256
  | `oat-dispatch-subagents/references/provider-claude.md` | `fbe3a21e9533 -> NG` |
257
257
  | `oat-dispatch-subagents/references/provider-codex.md` | `95b0f82018c7 -> NG` |
258
258
  | `oat-dispatch-subagents/references/provider-cursor.md` | `f781555295a9 -> NG`; `55ccfef14fd6 -> NG` |
259
- | `oat-dispatch-subagents/references/record-schema.md` | `78f8069274a8 -> NG`; `1c9a84c4d1e0 -> NG`; `2a63da6e3a96 -> NG`; `30762d53b043 -> NG` |
259
+ | `oat-dispatch-subagents/references/record-schema.md` | `78f8069274a8 -> NG`; `1c9a84c4d1e0 -> NG`; `12cdc1878e52 -> NG`; `af49d3dd297a -> NG`; `b6ec6e06e5b6 -> NG`; `a3a7ab0a05b4 -> NG`; `95820a0aced8 -> NG`; `273f5072954a -> NG`; `c6ab5ab1e06e -> NG`; `eb509ef89f26 -> NG`; `a014397a631c -> NG`; `d07c12e91bd8 -> NG`; `8fa5bb3f4105 -> NG`; `0ca0e55fce05 -> NG`; `f1cab0929f78 -> DISPATCH-01`; `25795e03a05a -> DISPATCH-01`; `c868f3b5ecc5 -> NG`; `f56113f1b003 -> NG`; `fca94abe381d -> DISPATCH-01`; `afc8d0aca7f0 -> NG`; `7119e48819d8 -> NG`; `62c4de81f4a6 -> NG`; `2524fbd4eb09 -> DISPATCH-01`; `af8a7cdd0523 -> NG`; `e22e8a0915e7 -> NG`; `2a63da6e3a96 -> NG`; `30762d53b043 -> NG` |
260
260
  | `oat-project-dispatch-subagents/SKILL.md` | `eca03ad1ca12 -> PDISPATCH-01`; `59fbcdc79cea -> PDISPATCH-01` |
261
261
  | `oat-project-plan/SKILL.md` | `f99e44b39932 -> PLAN-12`; `7e6a9854504b -> NG` |
262
262
  | `oat-project-implement/references/completion-and-closeout.md` | `6909a5a5a1fa -> IMPLEMENT-19`; `a7c02ef670fd -> IMPLEMENT-19`; `9dde56d89a71 -> IMPLEMENT-16`; `13c41b2b2590 -> IMPLEMENT-16` |
package/assets/skills/recon/SKILL.md ADDED
@@ -0,0 +1,260 @@
1
+ ---
2
+ name: recon
3
+ version: 1.0.1
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
+ argument-hint: '<question-or-target> [--profile quick|standard|thorough] [--scope description] [--context path] [--output directory] [--strict]'
6
+ disable-model-invocation: true
7
+ user-invocable: true
8
+ allowed-tools: Read, Write, Glob, Grep, Bash, AskUserQuestion, Agent, mcp__*
9
+ ---
10
+
11
+ # Recon
12
+
13
+ Compile a bounded investigation into a durable, validated evidence-packet
14
+ directory. `recon` is a provider-neutral controller: it owns decomposition,
15
+ artifact boundaries, assurance, and user interaction while installed dispatch
16
+ dependencies own live catalogs, target selection, and launch mechanics.
17
+
18
+ ## When to Use
19
+
20
+ Use `recon` when a downstream agent needs precise evidence, source locators,
21
+ contradictions, and gaps without loading every reconnaissance transcript.
22
+
23
+ Do not use it to make the final product or architecture decision, modify the
24
+ investigated system, perform an unbounded survey, or maintain a persistent
25
+ research workspace.
26
+
27
+ ## Arguments
28
+
29
+ Parse from `$ARGUMENTS`:
30
+
31
+ - **question-or-target**: bounded objective or target (required).
32
+ - **--profile**: `quick`, `standard`, or `thorough`; default `standard`.
33
+ - **--scope**: included and excluded investigation boundaries.
34
+ - **--context**: stable caller-provided context path or resource identifier.
35
+ - **--output**: explicit packet parent or run directory.
36
+ - **--strict**: require provider-enforced read and write authority for every
37
+ lane; default false.
38
+
39
+ Ask only for missing information required to make the objective, authority, or
40
+ destination safe. A calling skill may supply a fully resolved request.
41
+
42
+ ## Progress Indicators (User-Facing)
43
+
44
+ Report these compact stage transitions:
45
+
46
+ - `[1/8] Resolving request and destination…`
47
+ - `[2/8] Preflighting sources and authority…`
48
+ - `[3/8] Planning profile and worker lanes…`
49
+ - `[4/8] Preparing exact dispatch manifest…`
50
+ - `[5/8] Awaiting approval…`
51
+ - `[6/8] Running approved artifact pipeline…`
52
+ - `[7/8] Validating and publishing packet…`
53
+ - `[8/8] Returning packet directory…`
54
+
55
+ Do not print worker transcripts or raw dossier content.
56
+
57
+ ## Workflow
58
+
59
+ ### Step 1: Complete the Request
60
+
61
+ Normalize the objective, explicit questions, included and excluded scope,
62
+ caller context references, requested profile, strictness, and destination.
63
+ Refuse requests whose read-only evidence boundary cannot be stated.
64
+
65
+ Resolve the destination in this precedence order:
66
+
67
+ 1. explicit output override;
68
+ 2. active project `references/evidence/` directory when supplied by a caller;
69
+ 3. repository `.oat/repo/reference/evidence/` directory;
70
+ 4. a caller-approved fallback.
71
+
72
+ Create a new topic-and-run directory. Never escape the confirmed parent or
73
+ overwrite an existing run. Create only the packet directory and its artifacts.
74
+
75
+ ### Step 2: Preflight Sources and Authority
76
+
77
+ Inventory repository, file, URL, read-only command-output, and connected-system
78
+ sources that are actually available. Record unavailable or excluded sources as
79
+ gaps. Pin stable identities, observations, captures, revisions, and hashes
80
+ before dispatch.
81
+
82
+ Give every lane an explicit authority envelope containing:
83
+
84
+ - allowed inputs and excluded inputs;
85
+ - `readSources` and approved read-only tools;
86
+ - exactly one worker-owned output path; and
87
+ - enforcement level: `provider-enforced`, `contract-enforced`, or
88
+ `unavailable`.
89
+
90
+ Mutation-capable source access is unavailable unless the interface enforces a
91
+ read-only operation. In strict mode, stop unless every lane is
92
+ provider-enforced. Otherwise, contract-enforced local reads are permitted only
93
+ with the audited leaf-worker contract. Never broaden authority silently.
94
+
95
+ Initialize `manifest.json` and the directory skeleton, but do not create
96
+ `packet.md`.
97
+
98
+ ### Step 3: Expand the Profile
99
+
100
+ Read `references/profiles.md`. Partition the scope into non-overlapping,
101
+ adaptive lanes within the profile's hard caps. Classify every required and
102
+ conditionally allowed wave before selection. Record each wave's task class and
103
+ floor, then compute the run-wide maximum model-class floor.
104
+
105
+ All lanes within a launch are a homogeneous wave. All waves use the same
106
+ approved model and effort. Profiles change topology, redundancy, and
107
+ concurrency—not the target tier.
108
+
109
+ ### Step 4: Prepare One Exact Dispatch Manifest
110
+
111
+ Before reading either installed dispatch dependency, resolve one shared utility
112
+ skills root. Probe these candidate roots in order: from this loaded skill use
113
+ `${SKILL_DIR}/..`, then `${HOME}/.agents/skills` at user scope, then
114
+ `<repo-root>/.agents/skills` at project scope. The first candidate containing
115
+ both `oat-dispatch-subagents/SKILL.md` and
116
+ `subagent-orchestration/SKILL.md` becomes `${UTILITY_SKILLS_ROOT}`; bind every
117
+ dependency read to that same scope. Never resolve the dependencies
118
+ independently or mix different scopes.
119
+
120
+ If no candidate contains both dependencies, name the missing dependency and
121
+ stop before preparing or launching workers. Give the recovery command for the
122
+ intended scope: `oat tools install utility --scope <user|project>` or, when the
123
+ pack is already installed, `oat tools update --pack utility --scope
124
+ <user|project>`.
125
+
126
+ Read `${UTILITY_SKILLS_ROOT}/oat-dispatch-subagents/SKILL.md` and use its
127
+ selection-only `prepare` operation. From the same root, read
128
+ `subagent-orchestration/references/model-selection-principles.md`, exactly one
129
+ active-provider selection reference, and the matching
130
+ `oat-dispatch-subagents` provider mechanics reference. Do not copy provider
131
+ catalogs or exact launch construction into this skill.
132
+
133
+ Prepare every planned and conditional wave against one exact target satisfying
134
+ the run-wide floor. Prefer the canonical `recon-worker` role. If that role is
135
+ unavailable, prepare the generic role with the complete worker contract as a
136
+ visible generic role fallback before approval. A fallback after approval is
137
+ forbidden.
138
+
139
+ Assemble the exact approval envelope from the prepared records. It must bind:
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.
147
+
148
+ Present the exact provider, model and effort for explicit approval before any
149
+ worker launch. Also present the full topology and hard execution limits. Named
150
+ model examples are illustrative and non-normative; never route from an example.
151
+ Declining approval leaves the run at `awaiting-approval` and launches nothing.
152
+
153
+ ### Step 5: Execute the Approved Waves
154
+
155
+ Submit only the approval-bound prepared records to the dispatch dependency's
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.
159
+
160
+ Store immutable prepared, approval, launch-acceptance, and terminal receipts
161
+ under `raw/dispatch/`. Launch acceptance is distinct from worker completion.
162
+ After acceptance there is no replacement child, alternate route, target
163
+ substitution, or no silent retry. Continue the accepted handle only when the
164
+ dispatch contract authorizes continuation; otherwise record the pass failure.
165
+
166
+ Run the stages in this order:
167
+
168
+ 1. `map` and `gather` workers write unique dossiers under `raw/dossiers/`.
169
+ 2. `compile` writes a candidate canonical claim ledger.
170
+ 3. deterministic validation reopens sources and validates locators.
171
+ 4. profile-required `verify`, `adversary`, and `coverage` workers consume only
172
+ immutable selectively blind briefs created by
173
+ `scripts/create-review-brief.mjs` at unique paths.
174
+ 5. `reconcile` writes a new candidate ledger without mutating the prior ledger.
175
+
176
+ Use `references/worker-contract.md` for every assignment. Never allow two
177
+ workers to share a write path.
178
+
179
+ Read `references/packet-contract.md` before creating any packet artifact. Run
180
+ `scripts/validate-artifact.mjs` on each candidate and record its canonical
181
+ digest before the next stage consumes it.
182
+
183
+ ### Step 6: Preserve the Context Firewall
184
+
185
+ Treat `raw/` as worker-facing audit material, not normal consumer input. A
186
+ verification brief may contain only claim statements, display excerpts, typed
187
+ locators, and required source descriptors. An adversarial brief may contain
188
+ only declared scope, questions, and provisional statements.
189
+
190
+ Raw dossier content, dossier paths, compiler reasoning, synthesis prose,
191
+ provenance artifact references, prior review identifiers, and worker
192
+ transcripts must not enter review briefs, `packet.md`, or the parent handoff.
193
+ This selective blindness and context firewall are mandatory even when one
194
+ approved model performs every pass.
195
+
196
+ ### Step 7: Validate and Publish
197
+
198
+ Run `scripts/validate-artifact.mjs` on every candidate, then
199
+ `scripts/validate-packet.mjs` on the complete directory. Quarantine invalid
200
+ candidates under `raw/`; never promote shared artifacts in place and never
201
+ overwrite the last valid ledger. Candidate packet validation is
202
+ non-destructive for the canonical diagnostic artifacts: when it fails, do not
203
+ invoke the renderer, withdraw any existing `packet.md`, and report the
204
+ candidate failure separately. Only a publishable candidate proceeds to
205
+ `scripts/render-packet.mjs`; failure leaves no consumer entry point that could
206
+ refer to a different canonical generation.
207
+
208
+ Derive the achieved profile from completed stages whose required typed,
209
+ digest-bound artifacts validate. Do not accept a worker or manifest assertion
210
+ of achievement. A `quick` run can reach `supported` but never `verified`.
211
+ `verified` claims require unique complete semantic, adversarial, and coverage
212
+ results bound to immutable briefs and correct claim dispositions. Unresolved
213
+ material challenge prevents verification. A run with contested claims may
214
+ publish as `complete` when all declared questions and claims are resolved or
215
+ characterized; contested claims are rendered under "Contradictions and
216
+ Qualifications". If an unresolved challenge represents an unanswered question
217
+ or missing source evidence that leaves investigation incomplete, it must be
218
+ recorded as a material gap in `manifest.gaps` and the run published as
219
+ `partial`.
220
+
221
+ Render `packet.md` with `scripts/render-packet.mjs` only from the final validated
222
+ manifest and ledger. Publish through a symlink-safe temporary sibling followed
223
+ by atomic promotion. A complete run meets the requested profile and has no
224
+ material gap. An honest partial records requested profile, achieved profile,
225
+ failed or omitted passes, material coverage gaps, and claim downgrades; a
226
+ same-profile partial is valid when a material gap remains. Structural failure
227
+ leaves no `packet.md`. Renderer promotion failure also withdraws that consumer
228
+ entry point. Both retain the canonical manifest, ledger, reviews, raw
229
+ diagnostics, and safe failure record for diagnosis.
230
+
231
+ ### Step 8: Return the Directory-Only Handoff
232
+
233
+ Return only the packet directory path plus a compact summary containing status,
234
+ requested and achieved profile, claim-state counts, unresolved gaps, and failed
235
+ or omitted passes. Do not inline raw dossiers, source bodies, or worker
236
+ reasoning. The consumer may open `packet.md` and selectively follow compact
237
+ references.
238
+
239
+ ## Examples
240
+
241
+ ### Basic Usage
242
+
243
+ ```text
244
+ /recon "How is provider sync materialized?" --profile standard --scope packages/cli/src/providers
245
+ ```
246
+
247
+ ### Conversational
248
+
249
+ ```text
250
+ Build a quick recon packet for the current repository's release version gates.
251
+ ```
252
+
253
+ ## Success Criteria
254
+
255
+ - No worker launches before exact manifest approval.
256
+ - Every worker reads only declared inputs and writes one unique artifact.
257
+ - Every published locator is independently validated against a pinned source.
258
+ - Stronger claim states require their recorded profile passes.
259
+ - Partial and failed runs never overstate assurance.
260
+ - The normal handoff contains a packet directory and compact status only.