@open-agent-toolkit/cli 0.2.53 → 0.2.55

package/assets/skills/recon/SKILL.md

@@ -0,0 +1,298 @@
+---
+name: recon
+version: 1.1.0
+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.
+argument-hint: '<question-or-target> [--profile quick|standard|thorough] [--scope description] [--context path] [--output directory] [--strict]'
+disable-model-invocation: true
+user-invocable: true
+allowed-tools: Read, Write, Glob, Grep, Bash, AskUserQuestion, Agent, mcp__*
+---
+
+# Recon
+
+Compile a bounded investigation into a durable, validated evidence-packet
+directory. `recon` is a provider-neutral controller: it owns decomposition,
+artifact boundaries, assurance, and user interaction while installed dispatch
+dependencies own live catalogs, target selection, and launch mechanics.
+
+## When to Use
+
+Use `recon` when a downstream agent needs precise evidence, source locators,
+contradictions, and gaps without loading every reconnaissance transcript.
+
+Do not use it to make the final product or architecture decision, modify the
+investigated system, perform an unbounded survey, or maintain a persistent
+research workspace.
+
+## Arguments
+
+Parse from `$ARGUMENTS`:
+
+- **question-or-target**: bounded objective or target (required).
+- **--profile**: `quick`, `standard`, or `thorough`; default `standard`.
+- **--scope**: included and excluded investigation boundaries.
+- **--context**: stable caller-provided context path or resource identifier.
+- **--output**: explicit packet parent or run directory.
+- **--strict**: require provider-enforced read and write authority for every
+  lane; default false.
+
+Ask only for missing information required to make the objective, authority, or
+destination safe. A calling skill may supply a fully resolved request.
+
+## Progress Indicators (User-Facing)
+
+Report these compact stage transitions:
+
+- `[1/8] Resolving request and destination…`
+- `[2/8] Preflighting sources and authority…`
+- `[3/8] Planning profile and worker lanes…`
+- `[4/8] Preparing exact dispatch manifest…`
+- `[5/8] Awaiting approval…`
+- `[6/8] Running approved artifact pipeline…`
+- `[7/8] Validating and publishing packet…`
+- `[8/8] Returning packet directory…`
+
+Do not print worker transcripts or raw dossier content.
+
+When a run stops early or publishes a partial, label every failure with one of
+these categories so a controller problem is never reported as a worker
+problem:
+
+- `worker`: an accepted lane failed, was cancelled, or wrote an invalid
+  artifact;
+- `provider/dispatch`: the launch surface could not satisfy the approved
+  envelope, or a launched axis drifted from approval;
+- `contract validation`: artifacts were produced but the packet or a
+  candidate failed deterministic validation;
+- `source availability`: a declared source was unavailable, stale, or lacked
+  a read-only boundary.
+
+State whether every accepted lane reached a terminal result.
+
+## Workflow
+
+### Step 1: Complete the Request
+
+Normalize the objective, explicit questions, included and excluded scope,
+caller context references, requested profile, strictness, and destination.
+Refuse requests whose read-only evidence boundary cannot be stated.
+
+Resolve the destination in this precedence order:
+
+1. explicit output override;
+2. active project `references/evidence/` directory when supplied by a caller;
+3. repository `.oat/repo/reference/evidence/` directory;
+4. a caller-approved fallback.
+
+Create a new topic-and-run directory. Never escape the confirmed parent or
+overwrite an existing run. Create only the packet directory and its artifacts.
+
+### Step 2: Preflight Sources and Authority
+
+Inventory repository, file, URL, read-only command-output, and connected-system
+sources that are actually available. Record unavailable or excluded sources as
+gaps. Pin stable identities, observations, captures, revisions, and hashes
+before dispatch.
+
+Give every lane an explicit authority envelope containing:
+
+- allowed inputs and excluded inputs;
+- `readSources` and approved read-only tools;
+- exactly one worker-owned output path; and
+- enforcement level: `provider-enforced`, `contract-enforced`, or
+  `unavailable`.
+
+Mutation-capable source access is unavailable unless the interface enforces a
+read-only operation. In strict mode, stop unless every lane is
+provider-enforced. Otherwise, contract-enforced local reads are permitted only
+with the audited leaf-worker contract. Never broaden authority silently.
+
+Initialize `manifest.json` and the directory skeleton, but do not create
+`packet.md`.
+
+### Step 3: Expand the Profile
+
+Read `references/profiles.md`. Partition the scope into non-overlapping,
+adaptive lanes within the profile's hard caps. Classify every required and
+conditionally allowed wave before selection. Record each wave's task class and
+floor, then compute the run-wide maximum model-class floor.
+
+All lanes within a launch are a homogeneous wave. All waves use the same
+approved model and effort. Profiles change topology, redundancy, and
+concurrency—not the target tier.
+
+### Step 4: Prepare One Exact Dispatch Manifest
+
+Before reading either installed dispatch dependency, resolve one shared utility
+skills root. Probe these candidate roots in order: from this loaded skill use
+`${SKILL_DIR}/..`, then `${HOME}/.agents/skills` at user scope, then
+`<repo-root>/.agents/skills` at project scope. The first candidate containing
+both `oat-dispatch-subagents/SKILL.md` and
+`subagent-orchestration/SKILL.md` becomes `${UTILITY_SKILLS_ROOT}`; bind every
+dependency read to that same scope. Never resolve the dependencies
+independently or mix different scopes.
+
+If no candidate contains both dependencies, name the missing dependency and
+stop before preparing or launching workers. Give the recovery command for the
+intended scope: `oat tools install utility --scope <user|project>` or, when the
+pack is already installed, `oat tools update --pack utility --scope
+<user|project>`.
+
+Read `${UTILITY_SKILLS_ROOT}/oat-dispatch-subagents/SKILL.md` and perform
+only the selection steps of its Full-Information Selection: observe the
+catalog, resolve one exact target, and record the selection. Stop before its
+launch step; nothing launches until Step 5 runs after approval. From the same
+root, read
+`subagent-orchestration/references/model-selection-principles.md`, exactly one
+active-provider selection reference, and the matching
+`oat-dispatch-subagents` provider mechanics reference. Do not copy provider
+catalogs or exact launch construction into this skill.
+
+Resolve every planned and conditional wave against one exact target satisfying
+the run-wide floor. Prefer the canonical `recon-worker` role. If that role is
+unavailable, plan the generic role with the complete worker contract as a
+visible generic role fallback before approval. A fallback after approval is
+forbidden.
+
+Write the approval envelope into `manifest.execution`. It binds:
+
+- provider, route, role, model, effort, reasoning mode, and service tier;
+- authority level, maximum concurrency, per-lane deadline, and retry limit; and
+- every wave with its mode, task class, and conditional flag, and every lane
+  with its identity, read scope, and worker-owned write root.
+
+Its canonical fingerprint covers every field above.
+
+Present the exact provider, model and effort for explicit approval before any
+worker launch, together with the full topology and hard execution limits. Named model examples are
+illustrative and non-normative; never route from an example. Declining approval
+leaves the run at `awaiting-approval` and launches nothing. Approval records
+`explicit-user-approval`, the approval time, and the fingerprint.
+
+**Deadlines.** Choose the per-lane deadline from the expected task class and
+scope, and show it in the approval envelope; it is an approved execution limit,
+not a short watchdog. A deadline authorizes the provider to end a lane and
+report a terminal timeout. It never authorizes the controller to interrupt an
+accepted lane by hand: elapsed display time is not a failure. If the provider
+cannot enforce the deadline, wait or poll and report elapsed time, or obtain
+renewed approval before any cancellation.
+
+### Step 5: Preflight the Launch Surface, Then Execute
+
+Before any worker launch, confirm that the live launch surface can run the
+approved role, model, effort, and authority level, and can return each lane's
+result. If any approved axis cannot be satisfied, stop with a
+`provider/dispatch` diagnostic, leave the run at `awaiting-approval`, and
+launch nothing. Never substitute a different axis to make the launch fit.
+
+Launch each wave through the dispatch dependency with exactly the approved
+axes. Immediately before each launch, compare the axes that will actually run
+against the approval fingerprint. Any drift returns the complete manifest for
+renewed approval. Launch acceptance is distinct from worker completion. After
+acceptance there is no replacement child, alternate route, target
+substitution, or no silent retry. If an accepted lane fails, is cancelled, or
+times out, record that pass as failed with a material `PASS_FAILED` gap
+naming the pass.
+
+Run the passes in this order:
+
+1. `map` and `gather` workers write unique dossiers under `raw/dossiers/`.
+2. `compile` writes a candidate canonical claim ledger.
+3. Source preflight: run `scripts/validate-artifact.mjs` on the candidate
+   manifest and ledger, then reopen every declared source and evidence locator
+   with the checks in `scripts/validate-packet.mjs`. Resolve source roots to
+   canonical realpaths, pin one observation time per source, capture URLs or
+   mark them unavailable, and add a material gap for every ineligible source
+   and each affected claim. Do not create review briefs until the candidate
+   manifest and ledger pair validates.
+4. profile-required `verify`, `adversary`, and `coverage` workers consume only
+   immutable selectively blind briefs created by
+   `scripts/create-review-brief.mjs` at unique paths.
+5. `reconcile` writes a new candidate ledger without mutating the prior ledger.
+
+Use `references/worker-contract.md` for every assignment. Never allow two
+workers to share a write path. Every dossier records its approved wave and lane;
+every review result records its approved lane.
+
+Read `references/packet-contract.md` before creating any packet artifact. Run
+`scripts/validate-artifact.mjs` on each candidate and record its canonical
+digest before the next stage consumes it.
+
+### Step 6: Preserve the Context Firewall
+
+Treat `raw/` as worker-facing audit material, not normal consumer input. A
+verification brief may contain only claim statements, display excerpts, typed
+locators, and required source descriptors. An adversarial brief may contain
+only declared scope, questions, and provisional statements.
+
+Raw dossier content, dossier paths, compiler reasoning, synthesis prose,
+provenance artifact references, prior review identifiers, and worker
+transcripts must not enter review briefs, `packet.md`, or the parent handoff.
+This selective blindness and context firewall are mandatory even when one
+approved model performs every pass.
+
+### Step 7: Validate and Publish
+
+Run `scripts/validate-artifact.mjs` on every candidate, then
+`scripts/validate-packet.mjs` on the complete directory. Quarantine invalid
+candidates under `raw/`; never promote shared artifacts in place and never
+overwrite the last valid ledger. Candidate packet validation is
+non-destructive for the canonical diagnostic artifacts: when it fails, do not
+invoke the renderer, withdraw any existing `packet.md`, and report the
+candidate failure separately. Only a publishable candidate proceeds to
+`scripts/render-packet.mjs`; failure leaves no consumer entry point that could
+refer to a different canonical generation.
+
+Derive the achieved profile from complete, typed, digest-bound same-run
+artifacts written by approved lanes. Do not accept a worker or manifest
+assertion of achievement. A `quick` run can reach `supported` but never `verified`.
+`verified` claims require unique complete semantic, adversarial, and coverage
+results bound to immutable briefs and correct claim dispositions. Unresolved
+material challenge prevents verification. A run with contested claims may
+publish as `complete` when all declared questions and claims are resolved or
+characterized; contested claims are rendered under "Contradictions and
+Qualifications". If an unresolved challenge represents an unanswered question
+or missing source evidence that leaves investigation incomplete, it must be
+recorded as a material gap in `manifest.gaps` and the run published as
+`partial`.
+
+Render `packet.md` with `scripts/render-packet.mjs` only from the final validated
+manifest and ledger. Publish through a symlink-safe temporary sibling followed
+by atomic promotion. A complete run meets the requested profile and has no
+material gap. An honest partial records requested profile, achieved profile,
+failed or omitted passes, material coverage gaps, and claim downgrades; a
+same-profile partial is valid when a material gap remains. Structural failure
+leaves no `packet.md`. Renderer promotion failure also withdraws that consumer
+entry point. Both retain the canonical manifest, ledger, reviews, raw
+diagnostics, and safe failure record for diagnosis.
+
+### Step 8: Return the Directory-Only Handoff
+
+Return only the packet directory path plus a compact summary containing status,
+requested and achieved profile, claim-state counts, unresolved gaps, failed or
+omitted passes, and each failure's category from the list above. Do not inline
+raw dossiers, source bodies, or worker reasoning. The consumer may open `packet.md` and selectively follow compact
+references.
+
+## Examples
+
+### Basic Usage
+
+```text
+/recon "How is provider sync materialized?" --profile standard --scope packages/cli/src/providers
+```
+
+### Conversational
+
+```text
+Build a quick recon packet for the current repository's release version gates.
+```
+
+## Success Criteria
+
+- No worker launches before exact manifest approval.
+- Every worker reads only declared inputs and writes one unique artifact.
+- Every published locator is independently validated against a pinned source.
+- Stronger claim states require their recorded profile passes.
+- Partial and failed runs never overstate assurance.
+- The normal handoff contains a packet directory and compact status only.

package/assets/skills/recon/references/packet-contract.md

@@ -0,0 +1,340 @@
+# Recon Packet Contract v1
+
+Every JSON artifact carries a `kind` discriminator and integer
+`schemaVersion`. Version 1 rejects unknown versions; extend the contract through
+a new version rather than accepting untyped fields.
+
+## Directory
+
+```text
+<topic>-<run-id>/
+├── packet.md
+├── manifest.json
+├── claims.json
+├── reviews/
+│   ├── briefs/
+│   ├── semantic/
+│   ├── adversarial/
+│   ├── coverage/
+│   └── reconciliation.json
+└── raw/
+    ├── dossiers/
+    ├── drafts/
+    ├── quarantine/
+    └── failure.json
+```
+
+`manifest.json` and `claims.json` are canonical. `packet.md` is a generated
+consumer view. Each worker owns one unique path; candidates are immutable and
+never promoted over the last valid canonical artifact in place.
+
+## Artifact References and Canonical JSON
+
+An artifact reference is `{ "path": "packet-relative/path", "digest":
+"sha256:<64 lowercase hex>" }`. Paths must remain inside the packet directory.
+Digests cover the exact bytes on disk.
+
+Fingerprints use canonical JSON: UTF-8, object keys sorted lexicographically,
+array order preserved, no insignificant whitespace, and SHA-256 with the
+`sha256:` prefix.
+
+## One Validation Boundary
+
+Version 1 compiles persisted packet inputs exactly once into one non-persisted,
+deeply immutable `ValidatedRun`. This value is an internal normalized graph,
+not an artifact kind, schema version, file, cache, or caller-selectable profile.
+Assurance derivation and rendering accept only `ValidatedRun`; they never
+reopen or independently reinterpret raw manifest, ledger, review, or
+reconciliation artifacts.
+
+Construction is all-or-nothing. A valid graph contains:
+
+- one approved execution envelope whose canonical fingerprint matches the
+  recorded explicit user approval;
+- complete typed same-run artifacts, each written by an approved wave and lane,
+  from which the achieved profile is derived;
+- exactly one terminal reconciliation for standard or thorough runs and one
+  immutable canonical prior-ledger identity used by all review, transition,
+  addition, and removal checks;
+- exact byte digests for `manifest.json`, `claims.json`, and every validated
+  referenced packet artifact, retained from the same reads that constructed
+  the normalized graph;
+- canonical absolute realpaths for the packet, repository, file, capture,
+  command-output, and publication trust roots, rechecked before use;
+- only secret-safe persisted evidence and diagnostics, including ineligible
+  audit evidence;
+- material gaps derived from stale, invalid, or unavailable canonical sources,
+  with exact affected-claim coverage and legal assurance downgrades; and
+- derived claim assurance, achieved profile, material gaps, and publication
+  status.
+
+Reject approval fingerprint drift, unknown execution fields, artifacts from
+unapproved lanes, duplicate or shadow reconciliation results, symlink root
+aliases, retargeted roots, raw secret-bearing stale excerpts, and
+caller-downgraded gap materiality. Equivalent-looking inputs do not excuse a
+failed invariant.
+
+## Manifest
+
+`recon.packet-manifest` version 1 contains:
+
+- `run`: stable ID, topic, status, requested and achieved profile, timestamps;
+- `request`: objective, questions, included/excluded scope, stable context
+  references, confirmed output path;
+- discriminated `sources`;
+- `execution`: the approved execution envelope described below;
+- `artifacts`: direct references; and
+- `gaps`: categorical omitted, unavailable, stale, or failed work, each with an
+  explicit boolean `material` classification and affected source, claim, and
+  coverage-finding IDs when applicable.
+
+### Execution Envelope
+
+`execution` is a closed object binding exactly what the user approved:
+
+- `provider`, `route`, `role`, `model`, `effort`: non-empty strings;
+- `reasoningMode`, `serviceTier`: string or `null`;
+- `authority`: `provider-enforced` or `contract-enforced`;
+- `maxConcurrency`, `deadlineSeconds`: integers of at least 1; `retryLimit`:
+  integer of at least 0;
+- `waves`: closed `{ waveId, mode, taskClass, lanes, conditional }` records
+  with a unique wave identity, a mode from the wave-mode set, a task class from
+  the durable task-class order, and at least one closed
+  `{ laneId, scope, writeRoot }` lane whose identity is unique across the run
+  and whose write root is a packet-relative path; and
+- `approval`: `{ type: "explicit-user-approval", approvedAt, fingerprint }`.
+
+The fingerprint is the canonical SHA-256 of `execution` with `approval`
+removed. Validation recomputes it; any difference is
+`APPROVAL_FINGERPRINT_MISMATCH`. The envelope records what will run, not proof
+that a launcher ran it. Launch acceptance and per-lane terminal outcomes are
+reported in the controller's status and as `PASS_FAILED` gaps, not as packet
+artifacts.
+
+Wave modes are `map`, `gather`, `compile`, `semantic-verification`,
+`adversarial`, `coverage`, `reconciliation`, `redundant-gather`,
+`redundant-verification`, and `contradiction-resolution`.
+
+### Passes and Achieved Profile
+
+Run status is `preparing`, `awaiting-approval`, `running`, `complete`, `partial`,
+or `failed`. The validator, not a worker, derives the achieved profile from
+complete typed artifacts of the same run:
+
+| Pass                       | Complete artifact                                            |
+| -------------------------- | ------------------------------------------------------------ |
+| `map`                      | a `recon.raw-dossier` with mode `map`                        |
+| `gather`                   | a `recon.raw-dossier` with mode `gather`                     |
+| `semantic-verification`    | a `recon.review-result` with kind `semantic`                 |
+| `adversarial`              | a `recon.review-result` with kind `adversarial`              |
+| `coverage`                 | a `recon.review-result` with kind `coverage`                 |
+| `reconciliation`           | a `recon.review-result` with kind `reconciliation`           |
+| `redundant-gather`         | complete `gather` dossiers from at least two distinct lanes  |
+| `redundant-verification`   | a `recon.review-result` with kind `redundant-verification`   |
+| `contradiction-resolution` | a `recon.review-result` with kind `contradiction-resolution` |
+
+`quick` requires `map` and `gather`; the canonical ledger itself is the
+compile result, so an approved `compile` lane needs no separate artifact, and
+locator validation is performed by the validator.
+`standard` adds `semantic-verification`, `adversarial`, `coverage`, and
+`reconciliation`. `thorough` adds `redundant-gather`,
+`redundant-verification`, and `contradiction-resolution`.
+
+Every dossier records the approved `waveId` and `laneId` that wrote it; every
+review result records its approved `reviewerLane`. The lane must belong to a
+wave whose mode matches the artifact (a semantic result to a
+`semantic-verification` wave, a gather dossier to a `gather` or
+`redundant-gather` wave, and so on); otherwise the artifact is
+`UNAPPROVED_LANE`. The artifact path must equal or sit under the lane's
+approved `writeRoot`; otherwise it is `LANE_WRITE_PATH_VIOLATION`. Every
+non-conditional approved lane must either have written an artifact or be
+covered by a material `PASS_FAILED` or `PASS_OMITTED` gap naming its wave
+mode; otherwise the packet fails with `MISSING_LANE_OUTCOME`. Each required
+pass of the requested profile that has no complete artifact must likewise be
+named by such a gap, or the packet fails with
+`MISSING_PASS_OUTCOME_EVIDENCE`.
+
+## Source Descriptors and Locators
+
+All source descriptors carry `kind`, stable `id`, `available`, `authority`,
+`observedAt`, and `validationState`. Every declared path trust root must be an
+absolute canonical realpath, not a symlink alias, and its filesystem identity is
+rechecked before reads, hashes, or publication.
+
+Validation state is closed to `pinned`, `unpinned`, `stale`, `invalid`, or
+`unavailable`. Only an available `pinned` source is assurance-eligible;
+everything else requires an explicit affected-source/claim gap. A stale,
+invalid, or unavailable source used by the canonical ledger deterministically
+creates a material gap and forces `partial`. It may remain as auditable
+non-exact evidence only when that gap names the source and every affected claim,
+all affected claims are below `supported`, and every persisted excerpt and
+diagnostic is secret-safe. Caller-declared non-materiality, missing coverage,
+or a stronger claim state is invalid.
+
+- `repository`: canonical `root`, revision, dirty state, and per-path content
+  hashes. Locator: relative path, matching revision, line start/end.
+- `file`: canonical path and content hash. Locator: path and optional line
+  start/end.
+- `url`: canonical URL plus persisted capture path/digest or explicit validator
+  state containing an ETag or last-modified value and a pinned validation
+  snapshot path/digest. Locator: URL, retrieval time, optional fragment, and
+  the canonical validator-state token when that alternative is used.
+- `command-output`: canonical argv, cwd, exit status, output path/digest, and
+  names-only environment metadata. Locator: output path, line range, command
+  digest.
+- `connected-resource`: system, resource ID, resource version or retrieval
+  token, and capture path/digest. Locator: matching system/resource/version,
+  retrieval time, and optional field or section.
+
+Missing minimum provenance makes evidence ineligible for `supported` or
+`verified`. Path escape, digest change, version drift, shifted lines, or excerpt
+mismatch invalidates the locator. Only `exact` and `redacted-exact` states are
+assurance-eligible. Managed packet, capture, repository, and output paths reject
+both ancestor and final-component symlinks before reads, hashes, or writes.
+
+Source preflight runs these checks on the candidate manifest and ledger before
+any review brief is created, so ineligible sources and broken locators are
+found before the expensive review passes rather than at publication.
+
+## Claim Ledger
+
+`recon.claim-ledger` version 1 contains run ID, monotonic revision, direct input
+references, synthesis, evidence, claims, unresolved questions, and explicit
+claim transitions.
+
+Every claim evidence link is a closed `{ evidenceId, relation }` object whose
+`evidenceId` resolves to an evidence record in the same ledger and whose
+`relation` is `supports`, `contradicts`, `qualifies`, or `context`. A claim
+links each evidence record at most once. String links, open objects, unknown
+relations, unresolved IDs, and duplicates fail `validate-artifact.mjs` before
+any review brief can consume the ledger.
+
+Claim states are categorical:
+
+- `provisional`: compiled, not mechanically validated;
+- `supported`: supporting evidence and exact locators validate;
+- `verified`: independent semantic review affirmed the claim without unresolved
+  material challenge;
+- `contested`: credible counterevidence or incompatible interpretations remain;
+- `unresolved`: available evidence cannot settle the claim; and
+- `unsupported`: no valid support remains.
+
+A revision-one claim may honestly begin as `provisional`: that genesis is
+represented by the claim itself and has no transition entry. Revision one
+rejects any incoming or self-transition used to manufacture provisional
+genesis. In later revisions, `provisional` must result from an explicit legal
+incoming transition; the genesis exception cannot be reused.
+
+Quick packets never contain `verified` claims. Standard and thorough claims need
+recorded independent semantic, adversarial, and coverage reviews. Every review
+ID resolves to a unique, complete, typed, hashed result from an approved lane,
+bound to the exact immutable brief digest and the claim's required disposition.
+An incomplete or unapproved result cannot contribute assurance or
+reconciliation. A material unresolved challenge or coverage finding prevents
+verification. A run with contested claims may publish as `complete` when all
+declared questions and claims are resolved or characterized; contested claims
+are rendered under "Contradictions and Qualifications". If an unresolved
+challenge represents an unanswered question or missing source evidence that
+leaves investigation incomplete, it must be recorded as a material gap in
+`manifest.gaps` and the run published as `partial`. Review workers propose;
+only a reconciler writes a new ledger candidate. Reconciliation binds the prior
+ledger reference and revision, the next revision, the exact complete
+assurance-review set, and the exact canonical claim transitions. Standard and
+thorough output is exactly the next revision of the bound prior ledger;
+revision one cannot bypass reconciliation. It also binds additions, removals,
+and every prior/current state change; preserves statement, evidence-link, and
+qualification continuity; accepts new evidence only when an incorporated review
+supplied the exact record plus a closed `{ evidenceId, claimId, relation }`
+association to one of that review's disposition claims; preserves every
+unaffected evidence link byte-for-byte; and requires a typed rejection
+disposition from a complete review before removing a prior claim.
+
+## Evidence and Secret Redaction
+
+Evidence records bind a stable ID and source ID to one typed locator, a minimal
+display excerpt, observation time, locator-validation state, and provenance
+reference. States are `exact`, `redacted-exact`, `stale`, or `invalid`.
+
+Validate a sensitive source span transiently, redact before persistence, and
+store `redaction.applied: true`, categories, and
+`redaction.originalPersisted: false`. `redacted-exact` stores neither the secret
+nor a digest of the sensitive span. Diagnostics must never echo the span.
+Secret scanning precedes every assurance, ineligible-audit, gap, and render
+branch; source ineligibility never bypasses persistence safety.
+
+## Other Artifacts
+
+- `recon.raw-dossier`: assignment identity, approved wave and lane, mode,
+  inputs/exclusions, findings, uncertainty, contradictions, gaps, and outcome.
+- `recon.review-brief`: immutable selective-blind projection and digest.
+- `recon.review-result`: review kind, approved lane, exact brief reference,
+  permitted/excluded inputs, dispositions, new evidence, closed typed
+  claim/evidence associations, coverage findings, unresolved issues, and
+  completion status. Every new evidence record has at least one exact
+  association, and an association cannot name evidence absent from that result
+  or a claim without a disposition in that result. Reconciliation results
+  replace the brief reference with prior-ledger/revision, additions/removals,
+  exact transitions, and coverage-disposition bindings. Coverage findings are
+  closed records bound to affected claims and exact manifest gaps. Accepted
+  material gaps require a legal downgrade for every affected claim; a resolved
+  finding instead names exact typed evidence. Non-material coverage gaps
+  downgrade verified claims and transition provisional claims to unresolved,
+  while existing supported claims remain supported without verified promotion.
+  Thorough redundant verification and contradiction resolution are
+  claim-bearing typed review results, not raw dossiers: they bind immutable
+  briefs, claim dispositions, and explicit affected-contradiction dispositions.
+
+Create immutable mode-specific review projections with
+`scripts/create-review-brief.mjs`. Verification briefs expose only claim
+statements, display excerpts, typed locators, and required source descriptors.
+Adversarial briefs expose only scope, questions, and provisional statements.
+Coverage briefs expose only scope, questions, and claim ID/statement pairs.
+All reject dossier paths, compiler reasoning, synthesis prose, provenance
+references, and prior review IDs.
+
+## Validation and Publication
+
+Run `scripts/validate-artifact.mjs` on every candidate. Use
+`--quarantine-root <packet-dir>` to move an invalid candidate and a safe failure
+record under `raw/quarantine/`. Never promote invalid output.
+
+Run `scripts/validate-packet.mjs <packet-dir>` before rendering or publication.
+It delegates to the single validation boundary, which validates schemas, IDs,
+references, containment, hashes, source reopening, locators, the approval
+fingerprint, approved lanes, pass outcomes, the one terminal reconciliation,
+legal transitions, secret-safe persistence, derived gaps, assurance, and
+requested vs achieved profile. Candidate validation is non-destructive for
+canonical diagnostic artifacts, but a non-publishable candidate withdraws any
+existing `packet.md` and does not authorize rendering. Only a valid `complete`
+or honest `partial` candidate is publishable, so a rejected canonical
+generation cannot retain a consumer entry point from another generation.
+
+`complete` requires the requested profile and no material gap. `partial` is
+valid when either a lower profile was achieved or at least one material gap is
+declared, including honest same-profile partials.
+
+Use `scripts/render-packet.mjs <packet-dir>` to generate the deterministic
+consumer view. Its public path entry point first obtains `ValidatedRun`; the
+render core accepts only that graph. It writes an exclusive unpredictable
+temporary sibling, retains that file's identity through hashing and atomic
+promotion, and verifies the promoted digest. Immediately before and after
+promotion it also verifies that the canonical manifest, ledger, and validated
+referenced artifacts still match the byte digests retained by `ValidatedRun`.
+A mismatch is a categorical integrity failure and withdraws `packet.md`.
+Withdrawal first proves the retained packet-root identity; if the root changed,
+the renderer preserves that identity failure and does not follow or unlink the
+replacement path. Rendering or promotion failure on an unchanged root likewise
+withdraws `packet.md` while leaving canonical diagnostics available. Its result
+is the directory path plus a compact status summary and digest, never raw
+dossier content.
+
+## Version 1 Non-Goals
+
+This boundary does not add another schema version, review pass, persisted
+intermediate, generalized plugin artifact kind, saved validation profile,
+provider behavior, or integration surface. It does not require launcher-emitted
+dispatch receipts; reintroduce those only when a launcher exists that produces
+them itself. It does not change research-pack distribution, documentation,
+backlog integrations, `quick`/`standard`/`thorough`, selective blindness,
+categorical claim states, honest partial publication, or directory-only
+handoff.