wicked-vault 0.2.0

package/skills/wicked-vault/cross-check-evidence/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: wicked-vault:cross-check-evidence
+description: Declare a consumer-authored contract and get a mechanical PASS/REJECT verdict for a scope+phase by re-deriving every required artifact. Use when answering "is this claim actually backed by evidence that still holds?" — gate logic, release readiness, or merge checks. Fail-closed when no contract is declared.
+---
+
+# wicked-vault:cross-check-evidence
+
+Evaluate a whole **contract** — the set of evidence a scope+phase requires — and
+return a single mechanical verdict. Cross-check re-derives every required
+artifact (it does not trust cached statuses) and reports `PASS` only when all of
+them hold.
+
+This is the "is the work *backed*?" question. The contract is **consumer-
+authored**; the vault only decides *whether* it's satisfied, never *what* it
+should require (G9). The vault has no gate logic of its own to leak.
+
+## When to use
+
+- A gate / release-readiness / merge check that aggregates several claims.
+- Answering: "is this claim actually backed by evidence that still holds?"
+- Any time a stored "ready to merge" / "tests pass" must be re-proven, not
+  asserted.
+
+For a single artifact, use `wicked-vault:verify-evidence` instead.
+
+## Step 1 — Declare the contract
+
+Write a JSON spec listing the required evidence, then declare it for a
+scope+phase. A claim with a `verifier` pin also constrains how its evidence may
+be recorded (G8 — see `wicked-vault:record-evidence`).
+
+```jsonc
+// contract.json
+{
+  "required_evidence": [
+    { "claim_id": "tests-pass",  "kind": "test-run", "criteria": "all unit tests pass (exit 0)", "verifier": { "kind": "exit_code_eq" } },
+    { "claim_id": "no-secrets",  "kind": "test-run", "criteria": "no secrets in the diff", "verifier": { "kind": "not_contains" } },
+    { "claim_id": "design-ok",   "kind": "review-verdict", "criteria": "the change adequately addresses the documented failure modes", "require_attestation": true },
+    { "claim_id": "changelog",   "kind": "file",     "required": false }
+  ]
+}
+```
+
+```bash
+npx wicked-vault declare-contract --scope checkout --phase release --spec contract.json
+# -> { "contract_version": "<16-char hash>" }
+```
+
+- `required: false` makes a claim optional — its absence is `PASS`, not `MISSING`.
+- **`criteria`** pins the acceptance criteria for the claim. This is the
+  **trusted path** — criteria authored in the contract (separately from the
+  worker), so a recorded artifact must match it (`criteria_authored_by:
+  contract`). Strongly preferred over worker-supplied criteria.
+- **`require_attestation: true`** marks a claim that needs an independent
+  judgment (the judgment tier) — see Step 4. Use it for free-form criteria a
+  deterministic verifier can't express ("adequately addresses the failure
+  modes").
+- The `contract_version` is a hash of the required-evidence set (G8 pinning).
+
+## Step 2 — Record the evidence
+
+Record one artifact per required claim (`wicked-vault:record-evidence`). Each `claim_id`
+must match the contract, and `--criteria` must match the contract's pin. The
+**latest active** artifact for a claim wins.
+
+## Step 3 — Cross-check (integrity tier — the default, CI-safe)
+
+```bash
+npx wicked-vault cross-check --scope checkout --phase release
+```
+
+This is **`--integrity-only`** by default: deterministic, offline, no model
+calls — safe to put on a CI gate. It evaluates hash integrity + any
+deterministic verifier per claim.
+
+```json
+{
+  "scope": "checkout", "phase": "release",
+  "contract_version": "...",
+  "overall": "PASS",
+  "claims": [
+    { "claim_id": "tests-pass", "artifact_id": "...", "hash_ok": true, "verifier_status": "pass", "result": "PASS", "detail": "exit_code=0" },
+    { "claim_id": "no-secrets", "artifact_id": "...", "hash_ok": true, "verifier_status": "pass", "result": "PASS", "detail": "/(?i)secret/ absent" }
+  ],
+  "evaluated_at": "..."
+}
+```
+
+## Verdicts and exit code
+
+Exit `0` **iff** `overall === "PASS"`. Per-claim `result` is one of:
+
+| result | meaning |
+|---|---|
+| `PASS` | required artifact present, hash intact, verifier passed (and — in `--with-attestations` — an independent `pass` opinion when `require_attestation`) |
+| `MISSING` | a required claim has no active artifact |
+| `FAIL` | artifact present but tamper or verifier failed |
+| `UNATTESTED` | `require_attestation` claim has no independent opinion recorded |
+| `REJECT` | `require_attestation` claim has a non-pass / stale independent opinion |
+| `ERROR` | verifier-kind pin mismatch against the contract |
+
+`overall` is `PASS` only if every claim is `PASS`; `ERROR` if any claim errored;
+otherwise `REJECT`.
+
+## Step 4 — Judgment tier (opt-in, NOT for the default CI gate)
+
+```bash
+npx wicked-vault cross-check --scope checkout --phase release --with-attestations
+```
+
+`--with-attestations` consults the latest independent opinion per claim (the
+attestations recorded by `wicked-vault:analyze-evidence`). For a claim with
+`require_attestation: true`, it `PASS`es only when integrity passes **and** a
+non-stale, independent `pass` opinion exists; otherwise `UNATTESTED` / `REJECT`.
+For other claims the opinion is advisory (surfaced, doesn't change the result).
+
+This mode is **not deterministic and not for the default gate** — opinions come
+from a model and are point-in-time. Run `wicked-vault:analyze-evidence` first to
+produce the attestations, then use this mode for a release sign-off that
+requires a third-party judgment. Keep `--integrity-only` on the fast CI path.
+
+## Fail-closed (G5)
+
+If **no contract is declared** for the scope+phase, cross-check returns
+`overall: "ERROR"` and a non-zero exit — it never reports PASS by default. An
+undeclared expectation can't be silently satisfied.
+
+## wicked-bus event
+
+If wicked-bus is installed, `cross-check` publishes `wicked.contract.checked`
+(domain `wicked-vault`, subdomain `vault.cross_check`) carrying the `overall`
+verdict — this is the signal a gate consumer subscribes to. A detected tamper
+also publishes `wicked.evidence.tampered`. `declare-contract` publishes
+`wicked.contract.declared`. Emission is fire-and-forget and a no-op when the bus
+is absent or `WICKED_VAULT_NO_BUS=1`.
+
+## Inspecting what's recorded
+
+```bash
+npx wicked-vault list --scope checkout --phase release   # all entries (active + superseded)
+```

package/skills/wicked-vault/init/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: wicked-vault:init
+description: Initialize a wicked-vault in a repository so claims can be backed by re-derivable evidence. Use when setting up the vault for the first time, when a vault command reports "no .wicked-vault/ found", or before the first record/cross-check in a project.
+---
+
+# wicked-vault:init
+
+Set up the local-first **evidence primitive** in the current repository. The
+vault records claim-backing artifacts, hashes them tamper-evidently, and
+*re-derives* their verdict on demand — it never trusts a stored status.
+
+## When to use
+
+- First time using the vault in a repo.
+- A command failed with `no .wicked-vault/ found; run \`wicked-vault init\``.
+- Before the first `record` or `declare-contract` in a project.
+
+## Initialize
+
+```bash
+npx wicked-vault init
+```
+
+This creates `.wicked-vault/` at the repo root with:
+
+```
+.wicked-vault/
+  vault.json     # schema_version, store_mode: in-repo, payload_max_bytes
+  entries/       # one JSON envelope per recorded artifact (append-only)
+  payloads/      # content-addressed payload blobs (sha256-named, deduped)
+  contracts/     # consumer-authored contracts, per scope/phase
+```
+
+`record`, `declare-contract`, and `supersede` auto-create the vault if one
+isn't found, so explicit `init` is mostly for clarity. `verify`, `cross-check`,
+and `list` do **not** auto-create — they fail-closed when no vault exists.
+
+The vault is discovered by walking up from the current directory, so any
+subdirectory of the repo can run vault commands.
+
+## Should this be committed?
+
+`store_mode` defaults to `in-repo` — the vault lives inside the working tree
+and git becomes the audit chain. Decide per project whether `.wicked-vault/` is
+committed (shared, auditable evidence) or git-ignored (local-only scratch). The
+repo's own `.gitignore` ignores `.wicked-vault/` by default; remove that line to
+commit evidence.
+
+## Next steps
+
+- `wicked-vault:record-evidence` — capture an artifact and attach a verifier.
+- `wicked-vault:cross-check-evidence` — declare a contract and get a mechanical verdict.
+
+## Output
+
+Every command emits JSON to stdout and uses the **exit code as the gate
+signal** (`0` = PASS / success). `init` returns the absolute path of the
+created `.wicked-vault/` directory.

package/skills/wicked-vault/record-evidence/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: wicked-vault:record-evidence
+description: Record a claim-backing artifact in the vault and attach a deterministic verifier. Use when capturing evidence that "tests pass", "build clean", a commit exists, or a file's contents back a claim — and when replacing stale evidence via supersede. Covers --run vs --artifact, verifier syntax, and contract pinning.
+---
+
+# wicked-vault:record-evidence
+
+Capture an artifact, hash it tamper-evidently, and attach a verifier that can
+**re-derive** its verdict later. The vault does the capture itself — it never
+trusts a claimed status (G4).
+
+## When to use
+
+- Backing a claim with evidence: "tests pass", "build clean", "no secrets",
+  "commit landed", "config has the required field".
+- Replacing stale evidence with a fresh artifact (use **supersede**, below).
+
+## Two ways to capture
+
+### 1. Run a command and capture its result (`--run`)
+
+The vault executes the source command and stores `{command, exit_code, stdout,
+stderr, captured_at}` as the payload.
+
+```bash
+npx wicked-vault record \
+  --scope checkout --phase build --claim tests-pass --kind test-run \
+  --source "npm test" --criteria "all unit tests pass (exit 0)" \
+  --verifier "exit_code_eq:0" --run
+```
+
+### 2. Hash an existing file (`--artifact`)
+
+The vault reads the file and stores its bytes as the payload.
+
+```bash
+npx wicked-vault record \
+  --scope checkout --phase build --claim coverage-report --kind file \
+  --source "coverage/summary.json" --artifact coverage/summary.json \
+  --criteria "line coverage is at least 80%" \
+  --verifier "jq_pred:.total.lines.pct >= 80"
+```
+
+`record` requires **either** `--run` **or** `--artifact`, and **always**
+`--criteria`.
+
+## Required fields
+
+| Flag | Meaning |
+|---|---|
+| `--scope` | the unit the claim is about (e.g. a service, module, PR) |
+| `--phase` | lifecycle phase (e.g. `build`, `review`, `release`) |
+| `--claim` | claim id this artifact backs (e.g. `tests-pass`) |
+| `--kind` | artifact kind (e.g. `test-run`, `file`, `commit`) |
+| `--source` | the command (`--run`) or path/description (`--artifact`) |
+| `--criteria` | **mandatory** — the acceptance criteria this evidence claims to clear; inline text or `@file`. Hashed into the envelope and frozen to the evidence (G10) |
+| `--verifier` | *optional* deterministic sub-check (see below) — a composable signal an independent evaluator can cite |
+
+## Acceptance criteria are mandatory (G10/D1)
+
+Every artifact must state the bar it claims to clear — `record` rejects evidence
+with no `--criteria`. The criteria are hashed into the envelope, so the bar is
+**frozen to the evidence**: the same evidence can never later be judged against
+weaker criteria (anti-downgrade).
+
+The **trusted path** is contract-pinned criteria: when `declare-contract` pins
+`criteria` for the claim, a matching `--criteria` is stamped
+`criteria_authored_by: contract`. Worker-supplied criteria are stamped
+`record` (a weaker provenance class — see `wicked-vault:analyze-evidence`'s
+threat model). A `--criteria` that contradicts a contract pin is a G8 downgrade
+and is rejected.
+
+The independent judgment of *whether the evidence meets these criteria* is the
+job of `wicked-vault:analyze-evidence` (the judgment tier), not `record`.
+
+## Verifier syntax
+
+`--verifier "kind:arg"` (or a JSON object for advanced params). The v1 core
+verifiers are **deterministic and pure** (G7):
+
+| Verifier | Example | Passes when |
+|---|---|---|
+| `exit_code_eq` | `exit_code_eq:0` | captured exit code equals N (requires `--run`) |
+| `regex_match` | `regex_match:[0-9a-f]{40}` | pattern matches stdout+stderr / file text |
+| `not_contains` | `not_contains:(?i)error` | pattern is **absent** |
+| `jq_pred` | `jq_pred:.ok == true` | `jq -e` on the JSON payload is truthy (needs `jq`) |
+| `commit_exists` | `commit_exists:<sha>` | the git commit exists in the repo |
+
+`llm_eval` is intentionally **not** a verifier kind — a nondeterministic judge
+would falsify the purity guarantee (G7).
+
+## Output
+
+```json
+{ "id": "...", "envelope_hash": "...", "status_at_record": "pass", "status_detail": "exit_code=0" }
+```
+
+`status_at_record` is **informational only** — `verify` and `cross-check` never
+read it; they re-run the verifier (G3). The exit code is `0` on a successful
+record (the recording succeeded), regardless of the verdict — to gate on the
+verdict, use `verify` or `cross-check`.
+
+## wicked-bus event
+
+If wicked-bus is installed, `record` publishes `wicked.evidence.recorded`
+(domain `wicked-vault`, subdomain `vault.record`) fire-and-forget. `supersede`
+publishes `wicked.evidence.superseded`. Emission is a silent no-op when the bus
+is absent or `WICKED_VAULT_NO_BUS=1` — it never affects the output or exit code.
+
+## Replacing evidence (supersede)
+
+Evidence is append-only (G6). To replace a stale artifact, record a replacement
+and link it — the old entry is flipped to `superseded`, never deleted:
+
+```bash
+npx wicked-vault supersede <old-id> \
+  --scope checkout --phase build --claim tests-pass --kind test-run \
+  --source "npm test" --verifier "exit_code_eq:0" --run
+```
+
+Crash-safe ordering: the replacement is written and confirmed on disk before
+the old entry is flipped, so there is always an active artifact for the claim.
+
+## Contract pinning (G8)
+
+If a contract pins this claim (see `wicked-vault:cross-check-evidence`), `record` rejects
+a downgrade — a `kind`, `source`, or `verifier` that differs from the pin throws
+a `G8 pin violation`. This stops a weaker verifier from being swapped in to make
+a claim pass.

package/skills/wicked-vault/verify-evidence/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: wicked-vault:verify-evidence
+description: Deterministically re-derive a single recorded artifact's integrity — recompute the payload/criteria/envelope hashes and re-run its pure verifier. Model-free, reproducible, CI-gate-safe. Use to confirm a piece of evidence is still intact and its deterministic check passes, or to detect tamper. Never trusts the cached status. For an INDEPENDENT judgment of whether the evidence MEETS its criteria, use wicked-vault:analyze-evidence.
+---
+
+# wicked-vault:verify-evidence
+
+The **integrity tier** (G1–G9). Re-derive the verdict for **one** recorded
+artifact by id: recompute the payload, criteria, and envelope hashes from the
+stored bytes and **re-run the pure verifier** — never reading the status stored
+at record time (G3). Deterministic, offline, no model — safe on a CI gate.
+
+**This is not the judgment tier.** It answers *"is this artifact intact and does
+its deterministic check still pass?"* — not *"does this evidence actually meet
+its acceptance criteria?"* For the latter (an independent model analysis of
+evidence-vs-criteria), use **`wicked-vault:analyze-evidence`**.
+
+## When to use
+
+- Confirming a specific artifact still holds *right now* (cheap, reproducible).
+- Detecting tamper: a payload, criteria, or envelope field modified after
+  recording.
+- The integrity precheck before an independent analysis or a gate.
+
+To check a whole contract at once, use `wicked-vault:cross-check-evidence`.
+
+## Verify
+
+```bash
+npx wicked-vault verify <artifact-id>
+```
+
+Get artifact ids from `record` output or `npx wicked-vault list --scope <S>`.
+
+## Output
+
+```json
+{
+  "id": "...",
+  "hash_ok": true,
+  "payload_ok": true,
+  "criteria_ok": true,
+  "envelope_ok": true,
+  "status": "pass",
+  "rederived": true,
+  "detail": "exit_code=0",
+  "ignored_cached_status": "pass",
+  "latest_attestation": { "opinion": "pass", "evaluator": "gemini-reviewer", "stale": false }
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `hash_ok` | payload, criteria, and envelope hashes all match what was stored |
+| `payload_ok` / `criteria_ok` / `envelope_ok` | which part of the tamper check passed |
+| `status` | re-derived integrity verdict: `pass` / `fail` / `error` |
+| `rederived` | always `true` — proves the check was actually re-run |
+| `ignored_cached_status` | the stored status the vault refused to trust |
+| `latest_attestation` | the most recent **independent opinion** (from `analyze-evidence`), shown **for reference only** — not re-derived, not trusted as reproducible; `stale: true` if it judged different bytes |
+
+## Exit code is the gate
+
+Exit `0` **iff** `hash_ok && status === "pass"`. Any tamper or a failing
+verifier exits non-zero — script against the exit code:
+
+```bash
+if npx wicked-vault verify "$id" >/dev/null; then echo "still intact"; fi
+```
+
+## Fail-closed (G5)
+
+A pass requires an intact hash **and** (if the artifact carries a verifier) a
+passing verifier. If any hash diverges, `status` is forced to `fail` with a
+`TAMPER:` detail. A missing entry or payload blob returns `status: "error"` —
+never a silent pass. The `latest_attestation` is informational and never affects
+this exit code (an independent opinion is a separate, non-reproducible tier).

package/src/bus.mjs

@@ -0,0 +1,75 @@
+// Optional, fire-and-forget wicked-bus integration.
+//
+// The vault is a zero-dependency, local-first primitive. wicked-bus is a
+// *sibling* primitive, never a hard dependency: this module dynamic-imports it
+// at runtime and degrades to a silent no-op when it is absent or disabled.
+// Emission NEVER blocks or breaks a vault command — by the time we publish, the
+// evidence write has already happened (G6 append-only), and a bus problem must
+// not change a verdict, the stdout JSON, or an exit code.
+//
+// Opt out entirely with WICKED_VAULT_NO_BUS=1.
+
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { join } from 'node:path';
+
+const DOMAIN = 'wicked-vault';
+
+// Resolve the wicked-bus module namespace, or null. Two layers, in order:
+//   1. bare specifier — works when wicked-bus is installed globally or hoisted
+//      alongside the vault.
+//   2. the consumer project's node_modules (anchored at cwd) — the common case,
+//      since sibling tools live in the same repo the vault is invoked from, and
+//      the vault itself ships no node_modules.
+async function resolveBus(cwd) {
+  try {
+    return await import('wicked-bus');
+  } catch {
+    /* fall through to layer 2 */
+  }
+  try {
+    const require = createRequire(join(cwd, '__vault_bus_anchor__.js'));
+    const entry = require.resolve('wicked-bus');
+    return await import(pathToFileURL(entry).href);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build the bus publisher.
+ *
+ * @param {string} [cwd] directory to anchor module resolution from.
+ * @returns {Promise<(event_type: string, subdomain: string, payload: object) => void>}
+ *   a synchronous publish closure, or a no-op when the bus is unavailable or
+ *   disabled. The returned function never throws.
+ */
+export async function initBus(cwd = process.cwd()) {
+  const NOOP = () => {};
+  if (process.env.WICKED_VAULT_NO_BUS === '1') return NOOP;
+
+  const bus = await resolveBus(cwd);
+  if (!bus || typeof bus.emit !== 'function' || typeof bus.openDb !== 'function') {
+    return NOOP;
+  }
+
+  let db;
+  let config;
+  try {
+    config = typeof bus.loadConfig === 'function' ? bus.loadConfig() : {};
+    // openDb opens (and idempotently initializes) the local bus db — this is
+    // wicked-bus's own auto-init model, the same path the wicked-brain
+    // installer uses.
+    db = bus.openDb(config);
+  } catch {
+    return NOOP;
+  }
+
+  return (event_type, subdomain, payload) => {
+    try {
+      bus.emit(db, config, { event_type, domain: DOMAIN, subdomain, payload });
+    } catch {
+      // swallow — a bus error must never break a vault command
+    }
+  };
+}

package/src/hash.mjs

@@ -0,0 +1,40 @@
+import { createHash } from 'node:crypto';
+
+export function sha256(buf) {
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+// Deterministic canonical JSON (recursively key-sorted, no whitespace) so a
+// hash over a structure is stable regardless of key order.
+function sortKeys(o) {
+  if (o === null || typeof o !== 'object') return o;
+  if (Array.isArray(o)) return o.map(sortKeys);
+  const out = {};
+  for (const k of Object.keys(o).sort()) out[k] = sortKeys(o[k]);
+  return out;
+}
+
+export function canonical(obj) {
+  return JSON.stringify(sortKeys(obj));
+}
+
+// G2 — the envelope hash binds the identifying tuple (now including the
+// acceptance-criteria hash) to the payload hash. Mutating ANY of these fields,
+// the criteria, or the payload changes the envelope, so a later `verify`
+// recomputation will diverge from the stored value. The verifier is optional
+// (ADR-0002: it became a composable sub-check, not the whole story).
+export function envelopeHash(fields) {
+  const tuple = {
+    scope: fields.scope,
+    phase: fields.phase,
+    claim_id: fields.claim_id,
+    kind: fields.kind,
+    source: fields.source,
+    verifier: fields.verifier
+      ? { kind: fields.verifier.kind, params: fields.verifier.params || {} }
+      : null,
+    criteria_sha256: fields.criteria_sha256,
+    payload_sha256: fields.payload_sha256,
+  };
+  return sha256(Buffer.from(canonical(tuple), 'utf8'));
+}

package/src/id.mjs

@@ -0,0 +1,9 @@
+import { randomBytes } from 'node:crypto';
+
+// G1 — server-minted id. Time-prefixed hex so ids sort by creation order
+// (ULID-grade ordering; not strict ULID encoding). Callers cannot supply it.
+export function newId() {
+  const t = Date.now().toString(16).padStart(12, '0');
+  const r = randomBytes(8).toString('hex');
+  return (t + r).toUpperCase();
+}