sibyl-system 1.2.2 → 1.3.1

package/README.md

@@ -5,7 +5,8 @@
 A standalone [opencode](https://opencode.ai) plugin:
 
 - **`sibyl_consult`** — a three-voter review council (MELCHIOR / BALTHASAR / CASPER)
-  that audits an artifact against a goal and returns a **fail-closed 2/3 verdict**.
+  that audits an artifact against a goal and returns a **fail-closed verdict**
+  (`APPROVE` / `REJECT` / `CANNOT_ANSWER`).
 - **`sibyl_swarm`** — a lightweight workflow swarm: an ARCHITECT persona plans a
   dependency-ordered task graph, deterministic workers execute it in waves, and
   the result is aggregated into a verdict.
@@ -24,8 +25,10 @@ Council voters, swarm workers and the swarm judge run as **child sessions of the
 calling session** (`parentID` from the tool context): the TUI session picker
 lists root sessions only, so no sibyl ballot ever clutters your top-level
 session list. Transcripts stay in the DB, reachable from the parent session and
-mirrored into the run's sealed reply files. An empty caller session falls back
-to top-level creation. `sibyl_review` roles run fully isolated under /tmp with
+mirrored into the run's sealed reply files. A seatless (CLI/headless) caller
+falls back to top-level creation, and its voter rows are **garbage-collected
+on success** (the reply files are the durable record; failed votes keep their
+DB rows for salvage). `sibyl_review` roles run fully isolated under /tmp with
 their own HOME/DB (`src/lane/isolated.ts`), never touching yours.
 
 ## v1.1 — the review chamber (民主集中制)
@@ -44,6 +47,7 @@ Laws: docs/isolation-laws.md. Mechanism: docs/democratic-centralism.md.
 node dist/cli.js run --target doc.md --goal "Is this sound?" --model your-provider/your-model
 node dist/cli.js status --tail 5
 node dist/cli.js spotcheck <runId>
+node dist/cli.js run --target - --profile exam --scenario scenarios/<id>.json ...  # behavioral exam venue (bell preflight mandatory)
 ```
 
 ## Install
@@ -94,7 +98,7 @@ stderr, registers nothing, and returns empty hooks.
 | Tool | Arguments | Behavior |
 |------|-----------|----------|
 | `sibyl_consult` | `{ artifact, goal }` | `artifact` is a file path or inline multi-line text (≤ 256 KiB). The three councilors audit it in parallel; each reply is parsed into a verdict (one in-session JSON-only repair shot per voter). Returns the tally, merged reasons/must-fix, run id, and per-voter reply file paths. |
-| `sibyl_swarm` | `{ artifact, goal, judge? }` | ARCHITECT decomposes goal + artifact into a strict-JSON workflow schema; workers are minted deterministically and dispatched in dependency waves; drafts land in the run's space dir. Verdict: `APPROVE` / `REJECT` / `EXHAUSTED`. With `judge: true`, one extra judge pass may replace the derived verdict — an unrecognized or failed judge reply keeps the derived one. |
+| `sibyl_swarm` | `{ artifact, goal, judge? }` | ARCHITECT decomposes goal + artifact into a strict-JSON workflow schema; workers are minted deterministically and dispatched in dependency waves; drafts land in the run's space dir. Verdict: `APPROVE` / `REJECT` / `EXHAUSTED`, forced to `CANNOT_ANSWER` when a declared worker left no terminal row (W2) or zero drafts were produced. With `judge: true`, one extra judge pass may replace the derived verdict — an unrecognized or failed judge reply keeps the derived one. |
 | `sibyl_status` | `{ runId? }` | Read-only. Lists all recorded runs (newest last) + the last chamber-ledger rows, or shows one run's full record and space dir. |
 | `sibyl_review` | `{ target, goal, seed?, maxRounds? }` | v1.1 general democratic-centralism chamber: launches the isolated evidence→clash→judge pipeline detached and returns a receipt (explicitly NOT a verdict); the single voice lands in the run record at terminal state. CLI twin: `sibyl-chamber`. |
 | `sibyl_anchor_check` | `{ sessionId, index?, body?, expectSha256?, label? }` | Read-only verifier for "human anchor" claims (an order/approval message the owner says they sent): re-checks the claim against the engine's own session store instead of trusting a transcribed string. Closed 4-state verdict `MATCH` / `MISMATCH` / `ABSENT` / `ERROR`; the receipt carries a hash of the canonical view read, so later store mutation shows up as a view-hash difference. No `expectSha256` claim → non-verdict. |
@@ -119,7 +123,7 @@ defaults.
 | `timeoutMs` | `240000` | Per-child-session timeout (create + prompt share the budget). Integer ≥ 1. |
 | `concurrencyK` | `4` | Cap on parallel workers per wave (also capped by the schema's own `concurrency`). Integer 1–8. |
 | `staggerMs` | `2000` | Delay between worker launches within a wave, to avoid rate-limit bursts. Integer ≥ 0. |
-| `lane` | see below | v1.1 isolated-lane mechanics for `sibyl_review` / `sibyl-chamber` (`src/lane/isolated.ts`). Sub-keys: `runRoot` (string, default `"/tmp"`) — parent dir for run dirs; `opencodeBin` (non-empty string; discovery order: `$OPENCODE_BIN` → `~/.local/bin/opencode` → `/usr/local/bin/opencode` → `/usr/bin/opencode` → bare PATH name `"opencode"`; never empty, a wrong guess fails loud at spawn naming the bin) — the binary launched for each isolated role; `configSource` (default `~/.config/opencode/opencode.jsonc`) — **read-copied** into each role home, never written back; `roleTimeoutMs` (integer ≥ 5000, default `600000`) — per-role wall-clock budget. |
+| `lane` | see below | v1.1 isolated-lane mechanics for `sibyl_review` / `sibyl-chamber` (`src/lane/isolated.ts`). Sub-keys: `runRoot` (string, default `"/tmp"`) — parent dir for run dirs; `opencodeBin` (non-empty string; discovery order: `$OPENCODE_BIN` → `~/.local/bin/opencode` → `/usr/local/bin/opencode` → `/usr/bin/opencode` → bare PATH name `"opencode"`; never empty, a wrong guess fails loud at spawn naming the bin) — the binary launched for each isolated role; `configSource` (default `~/.config/opencode/opencode.jsonc`) — **read-copied** into each role home, never written back; `roleTimeoutMs` (integer ≥ 5000, default `600000`) — per-role wall-clock budget; `examMaskDirs` (array of absolute paths, default `[]`) — dirs tmpfs-masked from exam candidates (grader files, other runs); empty = an unsandboxed venue that says so plainly on the voice face. |
 | `modelPolicy` | `{ allowedPrefixes: ["local-"] }` | v1.1 E4/F1 seating allow-list: only pool models whose `providerID/modelID` starts with one of these prefixes may take a seat; everything else is denied at launch. Array of non-empty strings, **at least 1 entry** (an empty list is rejected as a deny-everything typo). Set this to your own machine's providers — the shipped default is a prefix pattern, not a specific model. |
 | `chamber` | see below | v1.1 review-chamber seats and rounds. Sub-keys: `maxRounds` (integer 1–8, default `3`) — clash/cross-critique round cap; `roles` (`{ evidence, pro, con, judge }` → pool slot names, each default `"default"`); `judgePool` (non-empty array of slot names, default `["default"]`) — the slots the independent judge may be drawn from (E2 pool+seed committed before launch). |
 
@@ -140,6 +144,8 @@ fails the release if any vendor model id reappears on a shipped surface.
 
 ## State layout
 
+- **Chamber ledger**: `~/.sibyl/chamber-ledger.jsonl` — append-only, one JSON
+  record per line, serial-stamped at append (A5); `sibyl_status` reads its tail.
 - **Runs file**: `~/.sibyl/runs.json` (Windows: `%USERPROFILE%\.sibyl\runs.json`) —
   one record per run (id, kind, status, verdict tally, operator notes), co-located
   with `spaces/` under the one `~/.sibyl` state root, so npm upgrades (which ship a
@@ -158,16 +164,45 @@ fails the release if any vendor model id reappears on a shipped surface.
 Plainly stated:
 
 - Approval needs **≥ 2 of 3 approvals and zero error/missing votes**.
-  Anything else — including 2A + 1 error or 2A + 1 missing — is **REJECT**.
+- When the council genuinely spoke (all three ballots substantive, or ≥ 2
+  substantive rejects) and approval was not reached, the verdict is **REJECT**.
+- When error/missing seats leave no decision (2A + 1 error, 2A + 1 missing,
+  a tie with an error seat), the verdict is **CANNOT_ANSWER** — a wounded
+  instrument, NOT a substantive reject, and it can never approve. Repair the
+  infra and re-run (since v1.2; pinned by `test/council.test.ts`).
 - Error votes, missing votes, and malformed verdicts all count against approval.
 - A reply that still doesn't parse after its single repair shot becomes a
   0-confidence REJECT ballot with reason `verdict-unparseable: …`.
 - There is no lenient mode, by design.
 
+## Ballot-integrity laws (W1–W4, drafted 2026-10-04/05 after the campaign postmortems; shipped in v1.3.0)
+
+- **Convener recusal (W1).** Every consult/swarm/review run resolves the
+  convening execution chain through the engine's own session store
+  (`session.get` parent links — never a self-report) and scans it for drafting
+  evidence of the artifact (write/edit parts targeting it, or content matches).
+  A kinship hit stamps the run `independence=NOT-INDEPENDENT`: the ballot is
+  preserved as data but is not in any effective path. A chain that cannot be
+  read stamps `UNVERIFIABLE` — unreadable is never silently clean.
+- **Absence is a disability (W2).** Before any tally is honored, every declared
+  voter/worker must have left a terminal row (`ok|error|timeout` + detail) in
+  the run's `TERMINALS.txt`. A declared seat without its row is counted
+  `dead-without-record=N` on the first receipt line and forces `CANNOT_ANSWER` —
+  never folded into an approve or a reject. A worker session ending with empty
+  content is a failure, not a done ballot.
+- **The ruler rides the ballot (W3).** Each terminal record embeds
+  `instrument: {rulesHash, components}` — the sha256 of every persona prompt /
+  criteria text the build actually sends (councilors, architect, judge, repair
+  grammar, chamber roles). `rulesHash` flips with any ruler edit, so
+  "re-evaluate under the new rules" is reproducible and comparable; the
+  `rules=<12hex>` label rides the receipt face and `sibyl_status` lines.
+
 ## Security notes
 
 - Consult/swarm send the artifact text to your configured model pool providers.
-- The plugin writes only under its state paths: the runs file and the per-run space.
+- The plugin writes under its state paths (the runs file and the per-run space) and,
+  for chamber/exam lanes, sealed run directories under `lane.runRoot`
+  (default `/tmp`) — role homes, transcripts, pidfiles, CHECKSUMS.
 - Voter/worker turns run with `bash`, `edit`, and `write` disabled per prompt.
 
 ## Architecture (`src/`)
@@ -184,7 +219,9 @@ index.ts            plugin entry: parse options → share one RunStore + client
 │                   validation → exactly one repair → fail-closed REJECT
 ├── council/        councilor personas + tallyVotes (majority2of3 default,
 │                   unanimous exported); pure aggregation, zero IO
-├── state/          RunStore: atomic RMW runs.json, per-run space dirs
+├── state/          RunStore: atomic RMW runs.json, per-run space dirs;
+│                   v1.1 chamber records: EOF-append ledger (A5), face-last
+│                   regeneration, CHECKSUMS + spotcheck (A4)
 ├── swarm/          planner (ARCHITECT schema) → minter (deterministic worker
 │                   roster) → dispatcher (dependency waves, stagger,
 │                   suspend-on-rate-limit, resume) → aggregate (report +
@@ -196,9 +233,15 @@ index.ts            plugin entry: parse options → share one RunStore + client
 │                   fail-closed, dissent sealed by path+hash)
 ├── exam/           v1.1 E3: scenario-as-data behavioral exams, mechanical
 │                   transcript/disk signal grading, canary veto
-├── state/          RunStore + v1.1 chamber records: EOF-append ledger (A5),
-│                   face-last regeneration, CHECKSUMS + spotcheck (A4)
-├── personas.ts     registry: 3 councilors + ARCHITECT, model slots
+├── personas.ts     registry: 3 councilors + ARCHITECT + judge/repair texts,
+│                   model slots — the single source the W3 face hashes
+├── terminal.ts     W2 terminal-row grammar (ok|error|timeout), parse + the
+│                   dead-without-record declared-minus-recorded diff
+├── instrument.ts   W3 ruler face: sha256 set of the live prompt/criteria
+│                   texts + deterministic rulesHash fold
+├── independence.ts W1 convener-recusal: engine-store chain walk +
+│                   drafting-evidence scan (INDEPENDENT / NOT-INDEPENDENT /
+│                   UNVERIFIABLE, fail-closed on unreadable)
 ├── options.ts      zod v4 schema + parseOptions (never throws)
 ├── cli.ts          v1.1 sibyl-chamber bin: run | status | spotcheck | kill
 └── tools/          sibyl_consult / sibyl_swarm / sibyl_status / sibyl_review
@@ -210,7 +253,7 @@ index.ts            plugin entry: parse options → share one RunStore + client
 
 This is **not** the oh-my-openagent swarm. It has no `team_*` tools, no
 cross-agent message bus, and no fleet-orchestration dependency of any kind —
-it is a clean-room implementation (~3.5K lines of product code, comments excluded) that happens to
+it is a clean-room implementation (~5K lines of product code, comments excluded) that happens to
 share the problem space. `sibyl_swarm` is a single tool call driving a
 PLAN→MINT→DISPATCH→AGGREGATE pipeline over ordinary child sessions.
 
@@ -218,7 +261,7 @@ PLAN→MINT→DISPATCH→AGGREGATE pipeline over ordinary child sessions.
 
 ```bash
 npm run typecheck   # tsc --noEmit, strict + noUncheckedIndexedAccess + exactOptionalPropertyTypes
-npm test            # 346 unit tests, fully offline (no network, no LLM)
+npm test            # full unit suite, fully offline (no network, no LLM; ~420 at v1.3.0 — the run prints the exact count)
 npm run build       # esbuild bundle → dist/index.js + dist/cli.js (ESM)
 node smoke/run-smoke.mjs   # offline smoke of the shipped surface (see smoke/README.md)
 ./ship.sh           # the full release gate: all of the above + portability scan of the packed tarball
@@ -250,4 +293,4 @@ MIT
 
 ## Release wheel
 
-Tags v* require a packet receipt (docs/release/<ver>.md with a real `gate: PASS` line) and a lease; after cloning run `scripts/install-hooks.sh` — hooks are per-clone and ship empty.
+Tags v* require a packet receipt (docs/release/<ver>.md with a real `gate: PASS` line) and a lease; after cloning run `scripts/install-hooks.sh` — hooks are per-clone and ship empty. **W4 (2026-10-05):** the hook reads the receipt AND `package.json`'s version exclusively from the pushed tag's **object body** (`git show <oid>:<path>`); working-tree reads are forbidden — the tag must carry its own paperwork, and the in-tag version must equal the tag name (ghost-version class killed). Regression-locked in `test/hook-prepush.test.ts` (ref lines fed via stdin).