@onlooker-community/ecosystem 0.34.0 → 0.43.0

package/docs/superpowers/specs/2026-08-10-lesson-confirmation-design.md

@@ -0,0 +1,213 @@
+# Lesson Confirmation — Design
+
+**Status:** Approved, not started.
+**Tracked by:** `ecosystem-4z8.2`, under epic `ecosystem-4z8`.
+**Upstream:** `docs/superpowers/specs/2026-08-09-lesson-transform-design.md` (stage 5,
+shipped in `librarian-v0.7.1`).
+**Parent design:** `docs/superpowers/specs/2026-08-08-promotion-pipeline-design.md` in the
+[onlooker](https://github.com/onlooker-community/onlooker) repo, Sections 2–3.
+
+---
+
+## What this stage is
+
+The human picks which lesson candidates go to the jury, and their intended
+visibility, before any Opus tokens are spent.
+
+This splits the pipeline's two filters along their natural lines. The human
+judges **intent** — "do I want to share anything about this?" — which is cheap
+and which only they can do. The jury judges **quality**, which is expensive and
+which only it can do. Cost then scales with intent rather than artifact volume.
+
+It also keeps promotion propose-only, consistent with librarian's ADR-001.
+
+## Where it lives
+
+`/librarian lessons`, dispatched through a nested `librarian_cli lessons <verb>`.
+
+Librarian already has a review surface for memory promotions: a SessionStart
+surfacer that injects a one-line pointer, a `/librarian` skill that walks the
+queue one entry at a time, and a CLI with `list` / `show` / `accept` / `reject`
+/ `defer`. Lessons reuse that plumbing but keep a separate queue, separate
+verbs, and a separate walk.
+
+Sharing the *machinery* while separating the *surface* is the point. The two
+decisions look alike and are not: accepting a memory writes a file on your
+machine, while confirming a lesson commits it toward being shared beyond your
+machine, irreversibly once synced. ADR-001's argument — that a wrong promotion
+is silent, slow to detect, and keeps acting on you afterward — applies harder
+here, not softer. A lesson confirmation should never sit one keystroke away
+from a memory accept in the same list.
+
+The verb sets differ anyway. Memory review is a binary plus a punt. Every
+lesson confirmation carries a third axis, visibility, that has no counterpart
+on the memory side.
+
+### Verbs
+
+| Command | Effect |
+|---|---|
+| `librarian_cli lessons list` | pending lessons, one row each |
+| `librarian_cli lessons show <id>` | full candidate for one proposal |
+| `librarian_cli lessons confirm <id> --visibility <v>` | `status: "confirmed"`, records `visibility` |
+| `librarian_cli lessons pass <id> [reason]` | `status: "passed"`, appends to `passed.jsonl` |
+| `librarian_cli lessons defer <id>` | no-op on state; leaves it `pending` |
+| `librarian_cli lessons status` | one-line counts |
+
+`confirm` also accepts `--version-independent <justification>`, which rewrites
+`applies_to.scope` to that branch and is subject to constraint 2 below.
+
+The walk shows, per candidate: `claim`, `rationale`, `evidence.resolution`, the
+inferred `applies_to.stack` and `scope.versions`, and the source `artifact_id`.
+Resolution is shown because it is the field that distinguishes a lesson from a
+warning, and it is the one a human is best placed to sanity-check.
+
+## State model
+
+All three states live on the proposal file the transform already writes at
+`~/.onlooker/librarian/<project-key>/lessons/proposals/<ulid>.json`.
+
+| `status` | Meaning | Written by |
+|---|---|---|
+| `pending` | transform wrote it; nobody has looked | stage 5 (ships today) |
+| `confirmed` + `visibility` | human wants it shared; awaiting the jury | this stage |
+| `passed` | human declined to share it | this stage |
+
+The file already carries `status: "pending"` and nothing reads it yet, so this
+stage gives an existing field its purpose rather than introducing a parallel
+one.
+
+**A passed candidate keeps its file.** `librarian_lesson_seen` scans
+`proposals/` by `artifact_id`, so leaving the file in place is what stops a
+declined artifact being re-proposed on the next scan. Deleting it would make
+the pipeline re-transform and re-ask every session, re-paying Haiku each time
+for an answer the human already gave.
+
+### Two ledgers, deliberately not one
+
+```
+lessons/proposals/<ulid>.json   pending | confirmed | passed
+lessons/declined.jsonl          machine verdicts   (stage 5)
+lessons/passed.jsonl            human intent       (this stage)
+```
+
+`declined.jsonl` exists to make expensive drops auditable and to produce the
+data that tunes the rubric later. A human declining to share is a statement
+about intent, not about quality. Mixing "I didn't want to share this" into the
+same file as "the model emitted malformed JSON" would corrupt exactly the
+signal that file exists to carry.
+
+Keeping them apart also makes each readable on its own: what does the model get
+wrong, versus what do I not want to share.
+
+`passed.jsonl` records `artifact_id`, `lesson_id`, `passed_at`, and an optional
+free-text reason. Append-only, like its sibling.
+
+## The three constraints
+
+These are the acceptance criteria expressed as properties of the code rather
+than as promises.
+
+**1. `confirm` requires an explicit visibility.** There is no default and no
+bare `confirm`. A candidate cannot reach `confirmed` without someone naming
+`private`, `org`, or `public`.
+
+**2. `version_independent` forces `org` or `public`.** Combining it with
+`private` is refused, with the reason stated.
+
+The transform can only emit `versioned` scope — that is what stops it minting
+lessons that never expire. This stage hands that branch to a human, who has the
+context to write a real justification. But private lessons run no jury, so a
+private `version_independent` claim would reach the pool with nothing checking
+it: the same hole, reached by a different door, with a person instead of Haiku
+writing the unchecked claim.
+
+Requiring org or public means the claim gets judged. `scope_accuracy` is the
+criterion that asks whether the justification is actually true, and the
+disclosure lens applies on top at the public tier. The schema stops the
+accident; the jury stops the lazy excuse; this constraint is what guarantees
+the jury is present to do so.
+
+**3. This stage never calls a model.** No Haiku, no Opus, no network. That is
+what makes "no tokens spent on unselected candidates" checkable rather than
+merely intended.
+
+## Two validators, on purpose
+
+`librarian_lesson_validate_candidate` hard-requires
+`.applies_to.scope.kind == "versioned"`. A human-converted `version_independent`
+candidate therefore fails it.
+
+This stage gets its own: `librarian_lesson_validate_confirmed`, which permits
+either branch, requires a non-empty `justification` when the branch is
+`version_independent`, and otherwise enforces exactly what the transform's
+validator enforces — including the provenance rules and the version-range
+pattern.
+
+The two are not redundant and the difference is not stylistic. They encode
+different trust: one bounds what a model may assert unsupervised, the other
+bounds what a human may assert *and a jury will then check*. The versioned-only
+rule stays on the transform path, where nothing downstream would catch a bad
+claim.
+
+State this in the code. A future reader who finds two validators and assumes
+one is dead will delete the wrong one.
+
+## Surfacing
+
+The SessionStart surfacer gains a second count: a distinct one-line pointer when
+lesson proposals are pending, alongside the existing memory-proposal line.
+
+Bodies stay out of SessionStart. That follows the surfacer's own stated reason —
+session-start context is precious, and a queue of unreviewed entries is not
+where it should go. The walk is where candidates get read.
+
+## Events
+
+Deferred, for the same reason stage 5 deferred its own.
+
+`librarian.lesson.confirmed` and `librarian.lesson.passed` would be as
+unregistered in `@onlooker-community/schema` as `.proposed` and `.declined`
+still are — verified against 2.11.0, which carries no `librarian.lesson.*`
+types at all. With a validator resolvable, the emitter rejects an unknown
+`event_type` and exits 1.
+
+Nothing is lost by waiting: `4z8.3` reads the proposal files, not the bus. When
+the schema package publishes all four types, one follow-up wires them together.
+
+## Testing
+
+bats, isolated temp home, per the repo's `writing-tests` skill — including its
+rule that non-final `[[ ]]` assertions need `|| return 1`, and its habit of
+breaking each new assertion once to confirm it discriminates.
+
+The cases that matter are the three constraints, because each is a guarantee:
+
+- `confirm` with no visibility is refused and leaves `status: "pending"`
+- `version_independent` + `private` is refused, with the reason
+- confirming invokes no model — asserted with a `claude` stub on `PATH` that
+  fails loudly if called, the same technique that proved the transform's
+  `unavailable` path
+
+Plus:
+
+- a passed candidate keeps its file, and `librarian_lesson_seen` still reports
+  its artifact handled
+- this stage never writes to `declined.jsonl`
+- a confirmed candidate carries both `status: "confirmed"` and its `visibility`
+- `librarian_lesson_validate_confirmed` accepts a well-formed
+  `version_independent` candidate and rejects one whose justification is empty,
+  while still rejecting everything the transform's validator rejects
+
+## Boundary to the next stage
+
+`4z8.3` selects proposals where `status == "confirmed"` and reads `visibility`
+from the same file to choose its gate: no jury for `private`, the
+`lesson-promotion` rubric for `org`, rubric plus disclosure lens for `public`.
+
+Nothing else crosses between the stages.
+
+## Out of scope
+
+The jury itself, the approved pool, `author_key` derivation, and any sync. This
+stage ends when a candidate is marked confirmed.

package/docs/superpowers/specs/2026-08-11-lesson-judging-design.md

@@ -0,0 +1,267 @@
+# Lesson Judging — Design
+
+**Status:** Approved, not started.
+**Tracked by:** `ecosystem-4z8.3`, under epic `ecosystem-4z8`.
+**Upstream:** `docs/superpowers/specs/2026-08-10-lesson-confirmation-design.md` (stage 6,
+shipped in PR #137) and `docs/superpowers/specs/2026-08-11-lesson-unconfirm-design.md`
+(`si6`, shipped in PR #139).
+**Blocks:** `ecosystem-4z8.4` (approved pool and declined ledger).
+
+---
+
+## What this stage is
+
+The jury. A human has already said which lesson candidates they want shared and
+at what visibility; this stage decides whether each one is good enough to go.
+
+It is the first stage in the pipeline that spends Opus tokens, which shapes
+nearly every decision below.
+
+## Where it lives
+
+`/librarian lessons judge`, a new route on the existing librarian skill.
+Human-invoked — never a hook.
+
+The agent orchestrates and bash does file I/O, the same split stage 6
+established. That split is what lets the jury be real judge subagents rather
+than headless `claude -p` calls: tribunal's actual jury runs in its skill via
+the Task tool, and only its Stop hook uses the single-prompt shape.
+
+Per candidate, the skill reads the confirmed proposal, spawns the judge
+subagents with the candidate and the rubric, parses their verdicts, aggregates
+and gates, and **writes the verdict back before moving to the next lesson**.
+A new lib function `librarian_lesson_record_verdict <key> <lesson_id>
+<verdict_json>` owns that write, surfaced as `librarian_cli lessons
+record-verdict <id> <verdict-json> [cwd]`.
+
+The batch comes from `librarian_cli lessons list --confirmed`, which `si6`
+shipped precisely because a confirmed lesson was otherwise unfindable.
+
+Before spending anything, the skill reports that batch — how many candidates are
+confirmed and how many are public — and asks. A jury is the most expensive thing
+in the pipeline, and stage 6 established that the human sees what is about to
+happen before it happens. Declining the prompt spends nothing and writes
+nothing; every candidate stays `confirmed`.
+
+### There is no Actor
+
+Tribunal's loop is Actor → Jury → Meta-Judge → Gate, built around a producer
+that gets retried with critique. A lesson candidate already exists and nothing
+rewrites it, so this stage uses only Jury → aggregate → gate.
+
+That makes `max_iterations` vestigial. The bead specified `max_iterations: 1` to
+mean *drop, don't repair* — but with no producer, that is simply what happens.
+**The knob is omitted rather than carried**, because a setting that reads as if
+retry were possible invites someone to raise it later and wonder why nothing
+changes.
+
+## Why librarian owns this
+
+CLAUDE.md states that plugins do not call each other directly. This stage
+couples librarian and tribunal in some direction no matter how it is arranged:
+either librarian reaches for tribunal's rubric and judges, or tribunal reaches
+into librarian's project-keyed proposal files and writes verdicts back.
+
+**Librarian owns the verb, the rubrics, and the gate decision, and dispatches
+tribunal's judge agents by name.** The invariant is read as forbidding
+hook-to-hook runtime calls — the coupling that would make one plugin's failure
+another's — not reuse of published agent definitions, which are declarative
+assets with no runtime surface. An ADR records that reading.
+
+Keeping it in librarian also keeps the whole lesson lifecycle in one plugin, so
+`4z8.4` does not have to split its pool and ledger across two.
+
+## The rubrics
+
+Two builtins in **librarian's** `config.json`, mirroring tribunal's
+`rubric.builtins` shape so they stay legible to anyone who knows tribunal, and
+so the two could merge later.
+
+| criterion | `lesson-promotion` | `lesson-promotion-public` | asks |
+|---|---|---|---|
+| grounding | 0.45 / 0.7 | 0.32 / 0.7 | does the claim follow from evidence and resolution? |
+| scope_accuracy | 0.35 / 0.7 | 0.24 / 0.7 | does `applies_to` correctly bound the claim? |
+| generality | 0.20 / 0.6 | 0.14 / 0.6 | is this a lesson, or a session-scoped fact? |
+| disclosure | — | 0.30 / 0.9 | does the text leak a credential, internal name, or proprietary detail? |
+
+*(weight / min_pass.)* Both sum to 1.00. The public rubric is the org rubric
+scaled to 70%, with disclosure taking the remaining 30%.
+
+The public weights are rounded **to preserve that sum**, not by rounding each
+value independently: `0.35 × 0.7 = 0.245` is written as `0.24`, because rounding
+it up to `0.25` totals 1.01. Use the values in the table verbatim rather than
+recomputing them.
+
+The sum matters even though nothing reads it today: tribunal validates each
+weight in `[0,1]` but never checks their total, so an unnormalized 1.30 would
+silently mis-score the moment real `weighted_mean` lands.
+
+`score_threshold` 0.75 and `judge_types` `[standard, adversarial]` for both.
+
+### scope_accuracy is the point of the whole pipeline
+
+Stage 5 was deliberately restricted to emitting `versioned` scope, because a
+model minting `version_independent` lessons produces claims that never expire.
+Stage 6 handed that branch to a human, who has the context to write a real
+justification, and refused it at `private` because that tier runs no jury.
+
+`scope_accuracy` is where the loop closes. The schema guarantees a
+`version_independent` lesson **carries** a justification; this criterion asks
+whether it is **true**. Schema stops the accident; the jury stops the lazy
+excuse.
+
+### The weights and floors are inert today
+
+`tribunal_aggregate` takes the rubric as a parameter and explicitly discards it;
+`weighted_mean` falls through to the same plain average as `mean`. And
+`min_pass` is enforced nowhere — `TribunalVerdictPayload` carries one scalar
+`score`, one boolean `passed`, and `criteria_evaluated` as a list of *names*
+with no scores, so the orchestrator never learns what a judge scored on any
+individual criterion. Per the judge contract, `passed` is the judge's own
+self-assessment against the thresholds: prompt-level, not machine-enforced.
+
+The weights and floors are declared anyway, because they are the honest
+statement of intent and they go live unchanged the moment `ecosystem-pht`
+implements threading. But no part of this design may depend on them.
+
+## Gating by visibility
+
+| Visibility | Jury | Rubric | Gate policy |
+|---|---|---|---|
+| `private` | none — no model call at all | — | — |
+| `org` | standard + adversarial | `lesson-promotion` | majority |
+| `public` | standard + adversarial | `lesson-promotion-public` | unanimous |
+
+`private` skipping the jury entirely is what makes "cost scales with intent
+rather than artifact volume" true end to end, and it is why stage 6 refuses
+`version_independent` at `private` — that is the tier with nothing checking the
+claim.
+
+`org` gets the rubric alone because the org boundary already implies trust.
+
+`public` gets **`unanimous` instead of `majority`**, and this is a deliberate
+substitution for a mechanism that does not exist. The intent was a disclosure
+floor at `min_pass` 0.9 — a near-veto, on the reasoning that correctness rots
+and `applies_to` retires it, but harm does not; a leaked credential never
+expires on its own. Since `min_pass` cannot be enforced, `unanimous` delivers
+the property that actually mattered: **a single judge's objection cannot be
+outvoted.**
+
+The trade-off is stated plainly: it is not disclosure-specific. A judge unhappy
+about `generality` also blocks a public lesson. That is accepted for the tier
+that leaves the machine and draws the disclosure lens. When `pht` lands, this
+can narrow to a true per-criterion floor.
+
+**Correction (2026-08-14).** This section described `unanimous` as delivering
+"a single judge's objection cannot be outvoted." It never did. Both rubrics
+declare `judge_types: ["standard", "adversarial"]` — a panel of two — and at
+panel size two `unanimous` (`passed == count`) and `majority`
+(`passed * 2 > count`) return the same answer for all three possible pass
+counts. They diverge only at three judges or more, and `librarian_lesson_judge`
+refuses any panel whose judge-type multiset does not match the rubric's, so a
+third judge never reaches the gate.
+
+The public tier was never stricter than the org tier. `ecosystem-pht` replaced
+the stand-in with `disclosure`'s real `min_pass` floor and the policy is now
+`majority`. Tracked as `ecosystem-j74`.
+
+### No new judge agent
+
+The bead proposed reusing `tribunal-judge-security` as the disclosure lens. On
+inspection that does not work: it is built for code review — injection, auth
+bypass, path traversal, SSRF, TOCTOU — and is instructed to *read the changed
+files*, with `Read, Grep, Glob` as its tools. A lesson candidate is prose and
+has no files.
+
+Disclosure is therefore a **criterion** scored by the judges already empaneled,
+not a judge type. If generalist judges prove weak at it, a purpose-built
+disclosure judge is the follow-up — but writing one now is machinery ahead of
+evidence.
+
+## Verdict is not the same as "could not judge"
+
+`4z8.4` draws this distinction; this stage has to produce it.
+
+Tribunal's own skill tells the orchestrator that an unparseable judge response
+becomes `score: 0, passed: false` and lets the gate decide. **For lessons that is
+inverted deliberately.** A flaky judge would permanently decline a good lesson,
+and the watermark has already advanced past its artifact — so one transient
+outage would bury it for good.
+
+**Every empaneled judge must return a parseable verdict, or the candidate is
+unjudged.** Same for `claude` being unavailable, a judge timing out, or an empty
+panel. There is no quorum rule to tune: with a two-judge panel under `unanimous`
+or `majority`, losing one verdict means the gate cannot be decided at all, so
+"all of them" is the only honest threshold.
+
+**"Unjudged" is expressed as the absence of a write.** The proposal stays
+`confirmed`, nothing lands on disk, and the next run retries it. There is no
+failure state to clean up. The skill reports which candidates it skipped so the
+human knows to re-run.
+
+## State model
+
+`confirmed` → `approved` | `rejected`, written atomically per lesson.
+
+Committing per lesson rather than per batch is what makes a crash cheap: each
+candidate transitions the moment its own verdict lands, so an interrupted run
+costs at most one re-judgment and strands nothing.
+
+**No `judging` status.** `si6` deferred that decision here, and the answer is no.
+A mid-flight status would recreate exactly the trap `si6` was filed to fix — a
+lesson stuck in a state with no verb to free it, needing its own recovery
+escape hatch. Per-lesson commit gets crash-safety without one.
+
+Alongside `status`, the write records `judged_at` and a `verdict` object: rubric
+id, gate policy, aggregate score, threshold, the per-judge verdicts, and a
+reason when blocked.
+
+**A rejected proposal keeps its file**, exactly as a passed one does. That is
+what stops the artifact being re-proposed on the next scan and re-paying tokens
+for an answer already given.
+
+### `unconfirm` needs no change
+
+Its catch-all refuses any status it does not recognize, naming it — so
+`approved` and `rejected` are refused automatically, with no coordination
+between the stages. This is the forward-safety promise `si6` made to this stage,
+and collecting it costs nothing. It is asserted with a test rather than trusted.
+
+Undoing a rejection is **out of scope**, for the same reason undoing a `pass`
+was: it is a real decision with its own record, and inventing a reversal verb
+for it now would repeat the mistake `si6` avoided.
+
+## Events
+
+None, consistent with the two stages before it. `@onlooker-community/schema`
+2.11.0 registers only `meridian.lesson.curated` — no `librarian.lesson.*` and no
+`tribunal.lesson.judged` — and the runtime emitter exits 1 on an unknown
+`event_type`. `4z8.4` reads proposal files, not the bus.
+
+## Testing
+
+bats, isolated temp home, per the repo's `writing-tests` skill — single-bracket
+assertions or `|| return 1` on non-final ones, and every new assertion broken
+once to confirm it discriminates.
+
+- **A `private` candidate reaches `approved` with no model call**, asserted with
+  a `claude` stub on `PATH` that fails loudly if invoked — the technique that
+  already proved stage 5's `unavailable` path and stage 6's no-model guarantee.
+- `org` uses `lesson-promotion` with majority; `public` uses
+  `lesson-promotion-public` with unanimous.
+- **A public candidate that one judge blocks is rejected even when the aggregate
+  clears `score_threshold`** — the unanimous property, and the reason this tier
+  differs at all.
+- One judge returning unparseable output leaves the candidate `confirmed` with
+  nothing written, and the skipped id is reported.
+- A below-threshold candidate is rejected and keeps its file.
+- `unconfirm` refuses `approved` and refuses `rejected`, naming the status.
+- Re-running skips candidates that are not `confirmed`.
+- Both rubrics' weights sum to 1.00 — a guard for when `pht` makes them live.
+
+## Out of scope
+
+The approved pool and `declined.jsonl` writes (both `4z8.4`), `author_key`
+derivation (`4z8.5`), any sync, and re-judging a rejection. Per-criterion score
+threading and real `min_pass` enforcement are `ecosystem-pht`, filed against
+tribunal.

package/docs/superpowers/specs/2026-08-11-lesson-unconfirm-design.md

@@ -0,0 +1,152 @@
+# Lesson Unconfirm — Design
+
+**Status:** Approved, not started.
+**Tracked by:** `ecosystem-si6`, wired as a blocker on `ecosystem-4z8.3`.
+**Upstream:** `docs/superpowers/specs/2026-08-10-lesson-confirmation-design.md`
+(shipped in PR #137).
+
+---
+
+## What this is
+
+A way back from a confirmed lesson, before the jury has seen it.
+
+`confirmed` is currently terminal. `librarian_lesson_confirm` treats a repeat as
+idempotent only when visibility and candidate match exactly and refuses anything
+else; `librarian_lesson_pass` refuses a confirmed lesson outright; nothing else
+writes the proposal file. So a human who confirms at `public` meaning `private`
+has no path back — and that is the direction most worth correcting, since
+`public` is the tier that leaves the machine and draws the disclosure lens.
+
+Those guards are not the problem and should not be loosened. They are what keeps
+`lessons/passed.jsonl` from contradicting the proposal it describes, and they
+exist because pass-then-confirm once left the ledger asserting a human had
+declined something the proposal said was confirmed and bound for the jury. The
+guards closed the write path correctly. They just left no recovery path.
+
+## Why a verb rather than a relaxed guard
+
+The alternative was letting `confirm` overwrite a prior confirm with a different
+visibility. Rejected on two grounds.
+
+It would delete the guard that makes repeats safe — the same guard added in
+response to a real contradiction bug. And it would make a typo'd repeat silently
+change visibility on the verb that commits a lesson toward leaving the machine.
+
+An explicit "I take that back" matches how this design has treated every other
+irreversibility: make the consequential thing deliberate rather than incidental.
+
+## The state rule
+
+`librarian_lesson_unconfirm <key> <lesson_id>`, surfaced as
+`librarian_cli lessons unconfirm <id> [cwd]`.
+
+| Current status | Behavior |
+|---|---|
+| `confirmed` | → `pending`; clear `visibility` and `confirmed_at`; restore the candidate snapshot |
+| `pending` | no-op success — already there |
+| `passed` | refuse |
+| anything else | refuse, naming the status |
+
+`pending` as an idempotent no-op mirrors how `pass` treats an already-passed
+lesson, so repeat invocations are safe.
+
+Refusing `passed` keeps the ledger authoritative. Silently moving a passed
+lesson back to `pending` would leave `passed.jsonl` asserting a decision the
+proposal contradicts — precisely the bug the status guards were added for.
+Passing is a different decision from confirming, and it has its own durable
+record; undoing it is not this verb's job.
+
+## The candidate snapshot
+
+`confirm` writes four things: `status`, `visibility`, `confirmed_at`, and
+`.candidate`. That last one is why returning to `pending` is not enough on its
+own — a `--justification` rewrites the candidate's scope to
+`version_independent`, and nothing records what the transform originally
+inferred.
+
+Without a snapshot, unconfirming a justification-confirm leaves the proposal
+carrying `version_independent` scope with no route back to its `versioned`
+form. The confirmation stage's own guard would then correctly refuse it at
+`private` — so the user escapes one dead end into another, for exactly the
+mistake most worth undoing.
+
+**`confirm` stores the pre-rewrite candidate as `candidate_before_confirm`, and
+only when it actually rewrites scope.** `unconfirm` restores it and deletes the
+field.
+
+Deleting it is load-bearing. A stale snapshot left on a `pending` proposal is
+indistinguishable from a live one at the next confirm, and would silently revert
+a later legitimate rewrite. Absence of the field means the candidate was never
+mutated and there is nothing to restore — which is the common case, since a
+plain confirm does not touch it.
+
+## Surfaces
+
+`librarian_cli lessons unconfirm <id> [cwd]`, carrying the same `--*` flag
+rejection the other lesson verbs have. An unrecognized flag must not be absorbed
+as a `cwd` candidate; that hazard is already fixed twice in this pipeline and
+the contract should be consistent across the verb set.
+
+The `/librarian lessons` skill gains it in the verb table and in the walk,
+described as taking back a confirmation before the jury sees it.
+
+`librarian_cli lessons list` gains a `--confirmed` flag, and
+`lessons show` gains a `visibility` line. Neither was in the original design,
+and without them the verb has no discovery path: `list` prints only pending
+lessons, `unconfirm` operates only on `confirmed` ones, and nothing rendered
+the visibility a lesson sits at. The user story is inherently cross-session — a
+human who confirms at `public` meaning `private` comes back later with the claim
+in mind and no id — so a recovery verb with no way to find its subject is a
+verb nobody can reach. Bare `list` still shows pending; the flag carries the
+same `unknown option:` rejection as the sibling verbs.
+
+## Events
+
+None, consistent with the rest of this stage. `librarian.lesson.*` is
+unregistered in `@onlooker-community/schema` 2.11.0 and the emitter exits 1 on
+an unknown `event_type`. The next stage reads proposal files, not the bus.
+
+## The seam to the jury
+
+This is a promise to code that does not exist yet, so state it plainly.
+
+`unconfirm` proceeds **only** from `confirmed`. Every other status falls to the
+catch-all and is refused with the status named. When `4z8.3` introduces a status
+of its own — `judging`, `judged`, whatever it picks — `unconfirm` refuses it
+automatically, with no change here and no coordination between the two stages.
+
+That is what "must not preclude a jury-consumption state" means in practice: the
+existing convention of refusing unrecognized statuses loudly already handles a
+consumer that has not been written.
+
+**This design deliberately does not add a `judging` status now.** Inventing a
+state machine for an unwritten consumer produces a status nothing sets and every
+verb must handle. `4z8.3` owns that decision; this verb is forward-safe without
+it.
+
+## Testing
+
+bats, isolated temp home, per the repo's `writing-tests` skill — single-bracket
+assertions or `|| return 1` on non-final ones, and every new assertion broken
+once to confirm it discriminates.
+
+- **Round trip.** Confirm at `public` with a justification, then unconfirm: the
+  proposal is byte-identical to its pre-confirm state, scope back to
+  `versioned`, and no `candidate_before_confirm` left behind.
+- Unconfirm from `pending` is a no-op success.
+- Unconfirm from `passed` is refused, and `passed.jsonl` is untouched.
+- An unrecognized status is refused with the status named.
+- **After unconfirm, a fresh confirm at a different visibility succeeds** — the
+  user story this verb exists for.
+- Unconfirm invokes no model, asserted with a `claude` stub that fails loudly if
+  called.
+- A plain confirm (no justification) writes no snapshot, and unconfirming it
+  still returns the proposal to `pending` cleanly.
+
+## Out of scope
+
+The jury, the approved pool, `author_key`, and any sync. Undoing a `pass` is
+also out of scope — that decision has its own ledger and its own reasoning, and
+conflating the two undos is how the ledger starts disagreeing with the proposal
+again.