wicked-vault 0.2.1 → 0.3.1

package/README.md

@@ -51,18 +51,24 @@ config root (Claude Code, Gemini, Copilot, Codex, Cursor, Kiro, Antigravity):
 npx wicked-vault-install               # detect and install everywhere
 npx wicked-vault-install --cli=claude  # one CLI only (comma-separated for several)
 npx wicked-vault-install --path ~/.claude   # a specific config root
+npx wicked-vault-install --help        # options
 ```
 
 This mirrors the shared wicked-bus / wicked-brain installer: `$CLAUDE_CONFIG_DIR`
 is honored, alt-config layouts are probed, and skills land as
-`wicked-vault-{init,record-evidence,verify-evidence,analyze-evidence,cross-check-evidence}/`
+`wicked-vault-{init,record-evidence,verify-evidence,analyze-evidence,cross-check-evidence,update}/`
 under each CLI's `skills/`. If wicked-bus is installed, the installer also
 registers the vault as a bus provider (see below).
 
+**Updating:** say `wicked-vault:update` to your agent, or run
+`npm install -g wicked-vault@latest && npx wicked-vault-install` — it compares
+your version against npm and refreshes the skills across every CLI. Both
+binaries support `--help`.
+
 ## CLI
 
 ```bash
-wicked-vault init
+wicked-vault init   # optional — record / declare-contract / supersede create .wicked-vault/ automatically
 # record: --criteria is MANDATORY (the bar this evidence claims to clear); --verifier is optional
 wicked-vault record  --scope S --phase build --claim tests-pass --kind test-run \
                      --source "npm test" --criteria "all unit tests pass (exit 0)" \
@@ -177,8 +183,9 @@ bash test/bus-integration.sh  # graceful no-op + schema validity + real-bus emis
 `attestation.sh` and `bus-integration.sh` are the gating proofs and run in CI
 (`.github/workflows/ci.yml`) on ubuntu + macos, with a Windows CLI smoke.
 
-Status: v0.2.1 — deterministic core proven on real repos; criteria-binding +
+Status: v0.3.0 — deterministic core proven on real repos; criteria-binding +
 independent judgment tier (ADR-0002, council 5–0) implemented and proven;
 wicked-bus integration **proven end-to-end against a real bus** (emit → store →
-poll), optional and fire-and-forget. Not yet implemented:
+poll), optional and fire-and-forget; `--help` on both binaries + a
+`wicked-vault:update` skill. Not yet implemented:
 `pr_check_status`/`http_status_eq` and the sqlite query cache.

package/bin/wicked-vault.mjs

@@ -33,7 +33,63 @@ function emit(obj, ok) {
   process.exit(ok ? 0 : 1);
 }
 
+const HELP = `wicked-vault — local-first evidence primitive
+Record evidence with the acceptance criteria it must clear, re-derive integrity
+deterministically, and record independent third-party judgments. Never trusts a
+stored verdict; never lets work self-grade its own "done".
+
+USAGE
+  wicked-vault <command> [options]
+
+COMMANDS
+  init                         Create .wicked-vault/ in the current repo (optional —
+                               record / declare-contract / supersede auto-create it)
+  record                       Capture evidence + the criteria it must clear
+                               --scope S --phase P --claim C --kind K --source "<cmd|file>"
+                               --criteria "<text|@file>" (--run | --artifact <file>) [--verifier "kind:arg"]
+  verify   <artifact-id>       Integrity tier: re-derive hashes + verifier (deterministic,
+                               model-free). Exit 0 iff intact AND pass. Surfaces latest opinion.
+  inspect  <artifact-id>       Frozen criteria + evidence + integrity (what a judge evaluates)
+  attest   <artifact-id>       Record an INDEPENDENT judgment (fail-closed; evaluator != creator)
+                               --opinion <pass|reject|unclear> --rationale "..." --evaluator ID
+                               [--model prov/ver] [--prompt-hash H] [--sampling '<json>']
+  attestations <artifact-id>   Show the append-only opinion log
+  cross-check                  Mechanical contract verdict; exit 0 iff PASS
+                               --scope S --phase P [--integrity-only (default) | --with-attestations]
+  declare-contract             Pin a contract  --scope S --phase P --spec <file>
+  supersede <old-id>           Append-only replacement (same flags as record)
+  list                         --scope S [--phase P]
+
+GLOBAL
+  --cwd <dir>     Operate on a vault rooted at <dir> (default: walk up from cwd)
+  --help, -h      Show this help
+  --version, -v   Print the wicked-vault version
+
+OUTPUT   JSON on stdout; exit code is the gate signal (0 = PASS / success).
+ENV      WICKED_VAULT_NO_BUS=1   Disable optional wicked-bus event emission
+
+Skills (AI CLIs):  wicked-vault:{init,record-evidence,verify-evidence,analyze-evidence,cross-check-evidence,update}
+Install skills:    npx wicked-vault-install        (run with --help for options)
+Docs:              https://github.com/mikeparcewski/wicked-vault
+`;
+
 const [cmd, ...rest] = process.argv.slice(2);
+
+// Help / no-command: print usage to stdout and exit 0 — before any vault or bus
+// work, so `--help` works outside a repo and never errors.
+if (cmd === undefined || cmd === '--help' || cmd === '-h' || cmd === 'help') {
+  process.stdout.write(HELP);
+  process.exit(0);
+}
+
+// Version: like --help, must work outside any repo — resolved from this
+// package's own manifest, never from a vault.
+if (cmd === '--version' || cmd === '-v' || cmd === 'version') {
+  const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+  process.stdout.write(pkg.version + '\n');
+  process.exit(0);
+}
+
 const args = parseArgs(rest);
 const cwd = (typeof args.cwd === 'string' && args.cwd) || process.cwd();
 
@@ -48,7 +104,22 @@ try {
   }
 
   const root = findRoot(cwd, { create: cmd === 'record' || cmd === 'declare-contract' || cmd === 'supersede' });
-  if (!root) emit({ error: 'no .wicked-vault/ found; run `wicked-vault init`' }, false);
+  if (!root) {
+    // "What evidence exists?" in a repo with no vault is a question with a
+    // truthful answer — none — not an infrastructure error.
+    if (cmd === 'list') emit([], true);
+    const notFound = {
+      error: `no .wicked-vault/ found in or above ${cwd}`,
+      code: 'VAULT_NOT_FOUND',
+      hint: 'no evidence has been recorded here — `wicked-vault record` creates the vault automatically; `wicked-vault init` is optional scaffolding',
+    };
+    // Gate consumers (wicked-loom) read `overall` from cross-check JSON:
+    // report a truthful FAIL (no evidence exists) instead of a generic error.
+    if (cmd === 'cross-check') {
+      emit({ scope: args.scope, phase: args.phase, overall: 'FAIL', ...notFound }, false);
+    }
+    emit(notFound, false);
+  }
 
   switch (cmd) {
     case 'record': {

package/install.mjs

@@ -64,10 +64,41 @@ const CLI_TARGETS = [
   { name: "antigravity", dir: join(home, ".antigravity", "skills"), platform: "antigravity" },
 ];
 
-console.log("wicked-vault installer\n");
-
 const args = argv.slice(2);
 
+// Help: print usage and exit 0 before doing any detection or filesystem work.
+if (args.includes("--help") || args.includes("-h")) {
+  process.stdout.write(`wicked-vault-install — install wicked-vault skills into your AI CLIs/IDEs
+
+Copies the wicked-vault skills into every detected CLI config root so your
+agent knows how to use the vault. Also registers wicked-vault as a wicked-bus
+provider when the bus is available.
+
+USAGE
+  npx wicked-vault-install [options]
+
+OPTIONS
+  (no options)        Detect and install into every supported CLI found
+  --cli=<name>        Install into one CLI only (comma-separated for several),
+                      e.g. --cli=claude  or  --cli=claude,cursor
+  --path=<dir>        Install into a specific config root, e.g. --path=~/.claude
+  --help, -h          Show this help
+
+SUPPORTED CLIs       claude, gemini, copilot, codex, cursor, kiro, antigravity
+                     (\$CLAUDE_CONFIG_DIR is honored; alt-config layouts are probed)
+
+INSTALLS (per CLI, under skills/)
+  wicked-vault-init · -record-evidence · -verify-evidence · -analyze-evidence
+  · -cross-check-evidence · -update
+
+To update later:  npm install -g wicked-vault@latest && npx wicked-vault-install
+                  (or just say "wicked-vault:update" to your agent)
+`);
+  process.exit(0);
+}
+
+console.log("wicked-vault installer\n");
+
 // Flag parser supporting both --flag=value and --flag value forms, plus
 // narrow string-boolean coercion ("true" / "false" → booleans). The ad-hoc
 // parser this replaces silently dropped space-separated values — same bug

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-vault",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Local-first evidence primitive — record evidence with its acceptance criteria, re-derive integrity deterministically, and record independent third-party judgments. Never trusts a stored verdict, never lets work self-grade its own \"done\".",
   "type": "module",
   "bin": {

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Initialize a wicked-vault in a repository so claims can be backed by re-derivable evidence. OPTIONAL ceremony — record/declare-contract/supersede create the vault automatically; use init only to scaffold explicitly. A read command reporting code VAULT_NOT_FOUND means no evidence exists yet, which record (not init) fixes.
 ---
 
 # wicked-vault:init
@@ -11,9 +11,13 @@ vault records claim-backing artifacts, hashes them tamper-evidently, and
 
 ## 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.
+- You want the `.wicked-vault/` scaffold to exist before any evidence is
+  recorded (e.g. committing the directory layout, pre-provisioning CI).
+- Otherwise init is **optional**: `record`, `declare-contract`, and
+  `supersede` create the vault automatically on first use.
+- A read command failing with `code: VAULT_NOT_FOUND` means no evidence has
+  been recorded in that repo — recording evidence fixes it; bare init alone
+  does not produce evidence.
 
 ## Initialize
 

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

@@ -0,0 +1,140 @@
+---
+name: wicked-vault:update
+description: |
+  Check for and install wicked-vault updates. Compares the installed version
+  against the npm registry, updates the published CLI, and refreshes the skills
+  across all detected AI CLIs (Claude Code, Gemini, Copilot, Codex, Cursor,
+  Kiro, Antigravity).
+
+  Use when: "update wicked-vault", "check for vault updates", "wicked-vault update",
+  or periodically to stay current.
+---
+
+# wicked-vault:update
+
+Check for and install updates to wicked-vault and its skills.
+
+## Cross-Platform Notes
+
+Commands work on macOS, Linux, and Windows. Prefer agent-native tools
+(Read, Write, Grep, Glob) over shell where possible. JSON parsing uses
+`python3 … || python …` so it runs on macOS, Linux, WSL, and Git Bash.
+
+## When to use
+
+- User asks to update or check for updates.
+- After unexpected behavior that might be fixed in a newer version.
+- Periodically (suggest checking monthly).
+
+## Process
+
+### Step 1 — Check the installed version
+
+Global install:
+
+```bash
+npm list -g wicked-vault --json 2>/dev/null | python3 -c "
+import json, sys
+try:
+    d = json.load(sys.stdin)
+    print(d.get('dependencies', {}).get('wicked-vault', {}).get('version', 'not installed'))
+except Exception:
+    print('not installed')
+" 2>/dev/null || npm list -g wicked-vault --json 2>/dev/null | python -c "
+import json, sys
+try:
+    d = json.load(sys.stdin)
+    print(d.get('dependencies', {}).get('wicked-vault', {}).get('version', 'not installed'))
+except Exception:
+    print('not installed')
+"
+```
+
+Also check a local (project-level) install:
+
+```bash
+npm list wicked-vault --json 2>/dev/null
+```
+
+If neither is installed, the user may be running via `npx wicked-vault@latest`
+(always current) — note that and skip to Step 5 to (re)install skills.
+
+### Step 2 — Check the latest version on npm
+
+```bash
+npm view wicked-vault version 2>/dev/null
+```
+
+### Step 3 — Compare
+
+- Up to date: "wicked-vault is up to date (v{version})."
+- Update available: "wicked-vault v{new} is available (you have v{current}). Update now?"
+
+If the user only wanted to check, stop here and report current vs. available.
+
+### Step 4 — Update the package (if approved)
+
+Global:
+
+```bash
+npm install -g wicked-vault@latest 2>&1
+```
+
+Local (project):
+
+```bash
+npm install wicked-vault@latest 2>&1
+```
+
+If `EACCES` / permission denied:
+- macOS/Linux: `sudo npm install -g wicked-vault@latest`
+- Windows: re-run the shell as Administrator
+- Report the failure — do NOT silently skip.
+
+### Step 5 — Refresh the skills in all CLIs
+
+After updating the package, re-run the installer to copy the updated skills
+into every detected CLI:
+
+```bash
+npx wicked-vault-install
+```
+
+Or target one CLI:
+
+```bash
+npx wicked-vault-install --cli=claude
+```
+
+(The installer is idempotent — re-running overwrites the installed skills with
+the current version and re-registers the wicked-bus provider if the bus is
+present.)
+
+### Step 6 — Verify
+
+Re-run the Step 1 version check and confirm it matches latest. Also confirm the
+CLI runs:
+
+```bash
+npx wicked-vault --help | head -1
+```
+
+If it still shows the old version:
+1. `which wicked-vault` (macOS/Linux) or `where wicked-vault` (Windows).
+2. `npm cache clean --force`.
+3. Check whether nvm / fnm / volta is pinning a stale copy.
+
+### Step 7 — Report
+
+```
+wicked-vault updated: v{old} → v{new}
+Skills refreshed in {N} CLIs: {list}
+```
+
+## Notes
+
+- wicked-vault has **no background server** to update (unlike wicked-brain) —
+  updating is just the package + the skills.
+- The published package is provenance-signed; `npm view wicked-vault --json`
+  shows the attestation under `dist.attestations` if you want to confirm
+  supply-chain integrity after updating.