@soleur/opencode 0.0.0-stage → 1.0.0

package/skills/invoice/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: invoice
+description: "This skill should be used when the founder wants to get paid through their own Stripe account: list who owes them, create and send an invoice behind a human-approval preview, or chase an overdue one. Test-mode only in v1."
+allowed-tools:
+  - mcp__plugin_soleur_stripe__get_stripe_account_info
+  - mcp__plugin_soleur_stripe__stripe_api_read
+  - mcp__plugin_soleur_stripe__stripe_api_write
+  - mcp__plugin_soleur_stripe__stripe_api_search
+  - mcp__plugin_soleur_stripe__stripe_api_details
+disallowed-tools: Bash Read Write Edit
+preconditions:
+  - Stripe MCP server is authenticated (mcp__plugin_soleur_stripe__authenticate has been run for this session)
+  - The authenticated account is in TEST mode (v1 hard-refuses livemode — see S2)
+---
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+# Invoice — get paid via your own Stripe
+
+This skill is the Finance domain's get-paid workflow. It drives the **hosted Stripe MCP**
+(`mcp.stripe.com`, OAuth) to see who owes the founder money, create + send an invoice behind a
+human-approval preview, and chase overdue ones. It acts on the founder's **own** Stripe account —
+whichever account completed the OAuth — and **must never** touch Soleur's product billing credential
+(`STRIPE_SECRET_KEY`). See [ADR-107](../../../../knowledge-base/engineering/architecture/decisions/ADR-107-stripe-mcp-oauth-plane-vs-product-billing-key.md)
+for the credential-plane boundary and its enforcement model.
+
+**Credential isolation is defense-in-depth, NOT a tool sandbox.** A skill's `allowed-tools` is
+*pre-approval only* — per the Claude Code spec it does **not** remove `Bash`/`Read`/`Write` from the
+pool, so a prompt-injection payload in a Stripe-returned field (a customer name/memo) could try to
+`Read('.env')` or `Bash('cat lib/stripe.ts')`. The boundary is three partial layers: (1) `allowed-tools`
+lists only the 5 Stripe MCP tools (minimal declared scope); (2) `disallowed-tools: Bash Read Write Edit`
+removes the exfiltration tools for the duration of each operator turn (the injection window); (3) a
+committed `.claude/settings.json` `Read` deny on `**/.env*` + `**/lib/stripe.ts` covers the cross-turn
+`Read` vector. Residual: a `Bash`-mediated secret read, reachable only if the operator approves a
+permission prompt. Full model + rejected alternatives (`context: fork`) in ADR-107.
+
+**v1 scope: TEST mode only.** Livemode invoicing is blocked in v1 (S2 hard-stop) pending the legal
+lockstep tracked in [#6264](https://github.com/jikig-ai/soleur/issues/6264). Building and test-mode
+use are **not** gated on that.
+
+## Tool surface (generic, runtime-discovered)
+
+The hosted MCP exposes **generic** tools, not named ones (`create_invoice` does not exist). Bind each
+verb to a generic call (op-ids confirmed via `stripe_api_details` / `stripe_api_search` at run time):
+
+| Verb | MCP tool | Stripe op-id |
+|---|---|---|
+| account info | `get_stripe_account_info` | — |
+| mode probe (livemode, zero-PII) | `stripe_api_read` | `GetBalance` |
+| list customers | `stripe_api_read` | `GetCustomers` |
+| list invoices (open/overdue) | `stripe_api_read` | `GetInvoices` (filter `status=open`) |
+| retrieve invoice | `stripe_api_read` | `GetInvoicesInvoice` |
+| create draft | `stripe_api_write` | `PostInvoices` (body: `customer`, `collection_method=send_invoice`, `days_until_due`, `automatic_tax`, `currency`, `metadata`) |
+| add line item | `stripe_api_write` | `PostInvoiceitems` |
+| finalize | `stripe_api_write` | `PostInvoicesInvoiceFinalize` |
+| send | `stripe_api_write` | `PostInvoicesInvoiceSend` |
+| void | `stripe_api_write` | `PostInvoicesInvoiceVoid` |
+
+**Anti-duplicate mechanism = DETERMINISTIC metadata reconciliation, NOT idempotency keys.** The generic
+`stripe_api_write` tool accepts path/query/body params only — it has **no HTTP header slot**, and
+Stripe's `Idempotency-Key` is a header, so it cannot be passed through. Instead, stamp a **deterministic**
+marker in the invoice `metadata` on every create: `metadata[soleur_invoice_key]` = a hash of the invoice's
+**stable inputs** (customer id + currency + total amount + line-item descriptions/amounts + a coarse
+date/period bucket), computed the SAME way on every attempt so a retry regenerates the **byte-identical**
+value. **Never put raw customer PII in the marker — hash it.** Then **list-and-check that exact marker
+before every create/finalize**: if a prior attempt's marker already exists, reconcile to that invoice
+instead of minting a second one. A non-deterministic (per-attempt-random) marker would defeat this — a
+lost-response create followed by a retry would generate a new marker, match nothing, and mint a duplicate.
+
+**Two confirmation gates layer — by AUTHORITY (do not conflate them).** `stripe_api_write` may return a
+Stripe-side `human_confirmation` request (an approval id + URL; the human approves at the URL; re-call
+with `approval_token`, which the agent **cannot** self-satisfy). When it fires, **the Stripe URL approval
+is the final authorization that actually executes the write.** State this plainly to the operator and
+**re-display the skill's own computed total inside that instruction**, so the founder approves the Stripe
+page against the same number the skill previewed. The skill's founder-legible preview + typed-`yes`
+(S2/S4/S5) runs first and remains required; do **not** describe the native Stripe gate as subordinate —
+surface both without conflating them, and make explicit which action actually sends.
+
+## Re-entrant MCP error table
+
+This table applies at **every** MCP call, not just S1. The skill holds **no checkpoint state**, so
+there is never a false "resume" — on a mid-flow failure, re-run from the last **un-sent** step (the
+deterministic `soleur_invoice_key` marker is what makes that re-run safe against duplicates).
+
+| Condition | Meaning | Action |
+|---|---|---|
+| `MCP tool not found` | Stripe MCP not registered this session | Emit: run `mcp__plugin_soleur_stripe__authenticate`; **fail-closed** (stop). |
+| `Token expired` (can fire mid-flow) | OAuth token rotated | Re-authenticate, then **re-run from the last un-sent step** (re-read state from Stripe; reconcile the marker before any re-create). |
+| `403 Forbidden` | Token lacks access to this account/object | Confirm the OAuth account is the intended one; stop. |
+| `429 rate-limit` | Too many requests | Retry a read, or a write **only after** re-checking the `soleur_invoice_key` marker (reconcile-then-retry). **Never** a naive write retry. |
+| Mode indeterminate | The `GetBalance` probe returned no usable `livemode` boolean | **STOP** — never assume test mode (S2 fail-closed). |
+| `finalize-ok / send-failed` | Invoice finalized but `send` failed | Go to **S4.8 recovery**: surface the finalized id + `hosted_invoice_url`; offer resend-same-id or `void`. Never re-create. |
+| `already-finalized` | Finalize called on a finalized invoice | Go to S4.8 recovery (treat as finalized; do not re-create). |
+| Network error | Transient connectivity | Retry a read; for a write, reconcile the `soleur_invoice_key` marker first, else abort. |
+| `requires_location_inputs` (tax) | Customer address missing | **STOP** at S4.4 — do not preview an incomplete total; route to a customer-address fix (S6). |
+| Finalize rejected (tax/currency/entity) | Missing invoice fact | Route to **S6** (refuse-to-fabricate). "Customer has no email" routes to a customer-fix step. |
+
+## Workflow
+
+### S1 — Auth precondition
+
+If the Stripe MCP is not authenticated, emit the instruction to run
+`mcp__plugin_soleur_stripe__authenticate` and **fail-closed** (stop). Do not proceed to any read or
+write. The error table above is re-entrant: a `Token expired` later in the flow returns here.
+
+### S2 — Account + mode gate (runs BEFORE any customer read)
+
+This gate runs **before S3**, so a live account is refused before any customer PII is surfaced. It is
+a **hard precondition for S3, S4, and S5**; the ack is **session-scoped** (once per session).
+
+1. Call `get_stripe_account_info` for the account id + display name (the account echo).
+2. **Determine `livemode` deterministically from a ZERO-PII read**, not from customer data: call
+   `stripe_api_read` op-id `GetBalance`. The Balance object carries a `livemode` boolean and contains
+   **no customer PII**, so mode can be established before any `GetCustomers`/`GetInvoices` read. **Fail
+   closed:** if the probe returns no usable `livemode` boolean (error, empty, unexpected shape), **STOP**
+   — never assume test mode.
+3. Echo the **account id** and a **founder-legible plain-language mode line** — NOT the raw `livemode`
+   field:
+   - TEST: *"TEST mode — nothing real is sent; no customer is emailed and no money moves."*
+   - LIVE: *"LIVE mode — real invoices to real customers."*
+4. **If `livemode == true`: STOP.** Emit a plain message that live invoicing is **not enabled yet** and
+   point to [#6264](https://github.com/jikig-ai/soleur/issues/6264) (the legal lockstep). Offer **no**
+   proceed path — there is no `understood`/`--force`/`--yes` live-send branch in v1.
+5. In **TEST** mode, proceed only after the operator types a single literal `yes`. **Any non-exact
+   token** (e.g. `y`, `Yes`, `yes please`) → re-echo the mode line **once**, then abort. No
+   `--force`/`--yes` flags.
+
+### S3 — Read "who owes you" (test mode only)
+
+List customers and open/overdue invoices (`stripe_api_read` → `GetCustomers`, `GetInvoices` with
+`status=open`). Present a scannable table with the minimum the operator needs to act — customer name,
+amount, due date, invoice id (per S7, do not dump full email/address here).
+**Empty-state:** if no customers exist, say so plainly and route to S4's create-customer path rather
+than dead-ending.
+
+### S4 — Guarded create + send
+
+Ordered to avoid the orphaned-invoice window. **S2 must have passed this session.**
+
+1. **Resolve customer.** If none supplied or not found: offer a guarded create-customer step, or emit
+   "no customer resolved — create one in Stripe first." **Never finalize with no target.**
+2. **Duplicate guard.** List the customer's existing open/draft invoices AND list-and-check the
+   deterministic `metadata[soleur_invoice_key]` marker. If a same-amount / recent match or an existing
+   marker match exists, surface it and require an explicit **"not a duplicate"** confirm (or reconcile
+   to the existing invoice) before continuing.
+3. **Build draft** (`PostInvoices` + `PostInvoiceitems` for operator-supplied line items). Stamp
+   `metadata[soleur_invoice_key]` with the **deterministic** marker (hash of customer id + currency +
+   total + line-items + coarse date bucket — byte-identical across retries so a lost-response retry
+   reconciles instead of minting a duplicate). Do **not** put raw customer PII in metadata.
+4. **Compute-then-preview (pre-finalize) — ALWAYS.** Re-read the DRAFT (`GetInvoicesInvoice`) to get
+   Stripe's authoritative totals, and present a founder-legible preview of the **real total** (line-item
+   sum + tax + currency) before finalizing. This applies to **both** the `automatic_tax` path (Stripe
+   computes tax) **and** the manual-tax path (operator-supplied rate) — the founder always sees the
+   actual total feeding the money-demand before the irreversible finalize. **If `automatic_tax` is
+   enabled and tax status is `requires_location_inputs` (missing address): STOP** and route to a
+   customer-address fix (S6) — do not preview an incomplete total.
+5. **Typed-`yes`** on that preview. Decline → **abort** (nothing is finalized).
+6. **`finalize`** (`PostInvoicesInvoiceFinalize`) — Stripe mints the invoice `number` (never
+   agent-minted). Reconcile the `soleur_invoice_key` marker first if retrying.
+7. **`send`** (`PostInvoicesInvoiceSend`). The **guaranteed deliverable is the `hosted_invoice_url`**
+   minted at finalize — always surface it to the operator. In **test mode Stripe does not email the
+   customer**, so `send` is **best-effort**; the hosted link is the honest v1 output.
+8. **Recovery.** Finalize mints `hosted_invoice_url` immediately, so a failed `send` is **not** an
+   orphan. Surface the finalized invoice id + hosted link and offer **resend the same id** or
+   **`void`** (`PostInvoicesInvoiceVoid`) to retire it. **Never re-run create as recovery** — it mints
+   a duplicate.
+
+### S5 — Chase an overdue invoice
+
+For an existing open/overdue invoice, re-trigger `send` (`PostInvoicesInvoiceSend`).
+**S5 MUST run the S2 mode gate + a per-send preview + literal-`yes`** — including when the operator
+opens directly with "chase my overdue." It **inherits the S2 livemode hard-stop**: no dunning against
+a live account in v1.
+
+### S6 — Refuse to fabricate
+
+If tax rate, currency, or legal entity is unspecified, **STOP** and require an operator fact or
+`automatic_tax` (Stripe Tax) — never guess. **Never mint an invoice number** (finalize does that).
+A finalize rejected for a tax/currency/entity cause routes here; "customer has no email" routes to a
+customer-fix step.
+
+### S7 — PII discipline
+
+Never write plaintext customer PII (name, address, email, amount tied to an identity) to any committed
+repo artifact or application log. **Note:** the Claude Code conversation transcript persists to local
+disk (`~/.claude/projects/…`), so anything surfaced in-session **is** written to that local file — the
+plan's earlier "not persisted" framing is inaccurate. Therefore surface only the **minimum** the
+operator needs to act: customer name + amount + due date + invoice id for the "who owes you" table;
+email/address only at the moment they are needed to resolve or create a customer, never a full PII dump.
+This mirrors the `recipient_hash` HMAC discipline. The `allowed-tools`/`disallowed-tools` scope prevents
+the skill from itself authoring a committed artifact, but does not change transcript persistence.
+
+## Sharp edges
+
+- **The credential boundary is defense-in-depth, not a sandbox.** Do NOT re-describe `allowed-tools` as
+  isolation, and never introduce `Bash`/secret-`Read`/Doppler into this skill's frontmatter or a blanket
+  `Bash`/`Read` allow into `.claude/settings.json` — either re-opens the exfiltration residual (ADR-107).
+- **Do not hardcode Stripe MCP tool names from memory** beyond the binding table — the hosted MCP is
+  runtime-discovered; confirm op-ids with `stripe_api_details` / `stripe_api_search` at run time.
+- `stripe_api_write` is a **generic dispatcher for the founder's entire Stripe write surface** (refunds,
+  payouts, account updates — not just invoicing). The binding table is a convention, not a limit; bounded
+  in v1 only by the S2 test-mode hard-STOP + the typed-`yes` gate (ADR-107 §Consequences).
+- Autonomous/cron sending is **out of v1 scope** — interactive browser OAuth cannot run headless. The
+  multi-tenant path (Stripe Connect) and a `context: fork` by-construction tool boundary are deferred to #6264.

package/skills/kb-glossary/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: kb-glossary
+description: "This skill should be used when a session settles, sharpens, or disputes the meaning of an internal term: write it into knowledge-base/project/glossary.md as a pointer to its definer."
+---
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+<!-- Inspired by mattpocock/skills/skills/engineering/domain-modeling/SKILL.md (MIT, Copyright (c) 2026 Matt Pocock). -->
+
+# KB Glossary — the write side of the vocabulary
+
+Reading `knowledge-base/project/glossary.md` is a one-line habit that several skills already carry.
+This skill is the other half: the discipline that **changes** the glossary at the moment a session
+works out what a word means, so the next session inherits the answer instead of re-deriving it.
+
+The format contract is [glossary-format.md](./references/glossary-format.md) — entry shape, the four
+admission tests, the pointer-not-restatement rule, and the miss path. Read it before writing an
+entry; do not re-derive the rules from the entries already in the file.
+
+## When to self-invoke
+
+Invoke this skill in the same turn, without being asked by name, when any of these happens:
+
+- A term the session is using **conflicts with an existing entry**. Say so immediately, quote both
+  readings, and ask which one holds.
+- A term is **fuzzy or overloaded** and the work is about to commit it to a file. Propose one precise
+  term and name what the others would have meant.
+- The code and the conversation **disagree** about a word. Surface the contradiction rather than
+  picking the reading that makes the sentence work.
+- A session **settles** a word — in a brainstorm, a plan review, a compound pass, an ADR argument.
+  That is the moment the entry gets written.
+- An artifact had to **hedge** on an ambiguous term because the glossary had no entry (the miss path).
+  The hedge stays in the artifact; the candidate entry comes here.
+
+Do **not** invoke it to look a word up, to restate a definition that already exists elsewhere, or to
+record a word that only one skill uses. Reading is the consumers' pointer, not this skill.
+
+## The write discipline
+
+1. **Write inline, not later.** Update the glossary in the turn the word is settled. A batched entry
+   is an entry that never lands, and the reasoning that justified it is gone by then.
+2. **Point, never paraphrase.** Find the file that owns the meaning and give its path with an anchor.
+   If nothing owns it, the fix is a definer in the file that owns the behaviour — then an entry
+   pointing at it.
+3. **Apply all four admission tests** from the format contract. Three of four is a candidate; record
+   the hedge in the artifact and leave the glossary alone.
+4. **Disambiguate rather than choose** when a word genuinely carries several senses here. One body per
+   sense, each with its own path. A single-sense entry for an overloaded word reads as settled and
+   sends the next reader to the wrong file.
+5. **Steer with `_Avoid_`.** When two words compete for one concept, pick one and list the loser. A
+   name that shortens in speech back into the banned word has not solved anything.
+6. **Move `last_reviewed`** whenever the review happens, even when it changed nothing — otherwise an
+   old date cannot be told apart from an unread file.
+
+## Scope — it is a glossary and nothing else
+
+The artifact holds terms and the paths that settle them. It is not a spec, not a design note, not an
+implementation record, and not scratch space for anything that fitted nowhere else. Every one of
+those grows the file an agent loads at decision time and none of them makes a word mean more.
+
+Two neighbours it is explicitly not, and the glossary itself says so by path: the public marketing
+glossary page, and the founder-facing register in `knowledge-base/marketing/brand-guide.md` §Voice. Never add an internal machinery noun to either.
+
+## Siblings
+
+- A **rejected concept** is not a term. Its record is the no-list, and the write contract for that is
+  [rejected-request-register.md](./references/rejected-request-register.md).
+- `soleur:operator-rephrase` reads the same entries in the opposite direction — as the stop-list of
+  internal words that must be translated before the founder sees them.

package/skills/kb-glossary/references/glossary-format.md

@@ -0,0 +1,111 @@
+<!-- Inspired by mattpocock/skills/skills/engineering/domain-modeling/CONTEXT-FORMAT.md (MIT, Copyright (c) 2026 Matt Pocock). -->
+
+# Glossary format
+
+The contract for `knowledge-base/project/glossary.md`: what an entry looks like, what earns one, and
+what a reader does when the word they need is not there. The artifact is written to this file, not
+the other way round.
+
+## Entry shape
+
+```markdown
+**Term**:
+One or two lines saying which file settles this word, and the path to it.
+_Avoid_: word, word
+```
+
+Three parts, in this order:
+
+- **The term**, in bold, in the singular, spelled the way the repository already spells it.
+- **The body**, which names the file that settles the meaning and gives its repo-relative path. An
+  anchor (`path/to/file.md` §Heading) beats a bare path, because the reader lands on the sentence
+  rather than on a 1,500-line document.
+- **`_Avoid_`**, listing the words that are not to be used for this concept. Omit the line when
+  there is nothing to steer away from; never leave it empty.
+
+When a word carries more than one legitimate meaning here, the entry is one body per sense, each
+with its own definer path, each sense labelled. A single-sense entry for a genuinely overloaded word
+is worse than no entry: it looks settled and points a reader at the wrong file.
+
+## An entry is a pointer, never a restatement
+
+If any file in the repository already contains the sentence that settles a term, the entry's job is
+to hand over the path and stop. A second wording of the same definition is a second thing to keep
+true, and the copy that drifts is always the one nobody reads on the way to the code.
+
+So: no entry paraphrases its own definer, no entry carries implementation detail, and a term with no
+definer anywhere does not get one invented here — it gets a definer written in the file that owns
+the behaviour, and then an entry pointing at it.
+
+## What earns an entry
+
+All four must hold. Three of four is a candidate, not an entry.
+
+1. **Load-bearing breadth** — the word appears in at least three skill or agent definitions that an
+   agent reads while deciding what to do. Below that, the one file it lives in defines it well
+   enough.
+2. **No existing definer, or a definer worth pointing at** — if an "an X is …" sentence exists, the
+   entry is that path. If nothing anywhere settles the word, fix that first.
+3. **A divergence you can name** — two honest readings send an agent down different paths, and the
+   difference ends up in a file that gets committed. "It's a bit ambiguous" does not qualify: name
+   the wrong commit the wrong reading produces.
+4. **Not founder-facing** — if the founder should ever read the word, it belongs in the brand guide's
+   `## Voice` section instead, which is where the founder-facing register and the audience voice
+   profiles live. (There is no section literally called "lexicon" — an earlier revision of this line
+   pointed at one, and a pointer whose target does not exist is precisely the defect this file exists
+   to prevent.) This glossary is machinery vocabulary, written for the agent that loads it at
+   decision time.
+
+A term also has to be shared traffic: it belongs here only when two or more skills or agents hand it
+to each other. A word one skill uses privately is that skill's business.
+
+## The consumer pointer (defined once, here)
+
+Five consumers carry a one-line read-pointer at `knowledge-base/project/glossary.md`: `brainstorm`,
+`plan`, `spec-templates`, `architecture` and `operator-digest`. The instruction those lines cite is
+this one, and it is stated only here so that five copies cannot drift apart:
+
+> Before you commit a word that names a concept — in a brainstorm, a plan, a spec, an ADR or a
+> digest — check it against `knowledge-base/project/glossary.md`. If the word has an entry, follow
+> its pointer and use the sense that file settles; if the entry lists the word you were about to
+> write under `_Avoid_`, use the entry's term instead. If the word is materially ambiguous and has
+> no entry, take the miss path below.
+
+`knowledge-base/project/constitution.md` carries the same pointer once, so a skill that reads the
+constitution inherits it without a per-file edit.
+
+**The founder-facing direction.** `operator-digest` and `operator-rephrase` read the same entries as
+a **stop-list**: an entry's term is a word the founder must not be shown, and the plain clause that
+opens the entry — or each of its senses — is what to say instead. The path in the body is for the
+agent and never reaches the founder. This does not make the glossary a source of approved founder
+words; plain words are chosen, not looked up.
+
+## The miss path
+
+A term that is materially ambiguous and absent from the glossary is a **candidate entry**, and the
+absence is never a reason to guess quietly.
+
+Do all three:
+
+1. **Pick a reading and say which one.** Write the artifact in one sense, and state in the artifact
+   which sense you took. A committed document that silently chose is the failure this whole
+   mechanism exists to prevent.
+2. **Name the ambiguity where the work lands**, in the committed artifact itself — not in the
+   session, which nobody re-reads. One sentence: the word, the two readings, and which one this
+   document uses.
+3. **Propose the entry** if the four tests above pass, by invoking `soleur:kb-glossary` in the same
+   session. If they do not all pass, the hedge in the artifact is the whole fix; do not grow the
+   glossary to record a one-off.
+
+A missing entry is cheap. A confident entry for a word nobody had settled is expensive, because
+every later reader treats it as decided.
+
+## Housekeeping
+
+- The file's frontmatter carries `review_cadence` and `last_reviewed`. A review that changes nothing
+  still moves `last_reviewed`, so an old date means unreviewed rather than unchanged.
+- Entries are written inline as soon as a session settles a word. Batching them to the end of the
+  work is how they get dropped.
+- The glossary is a glossary. It is not a spec, not a design note, not a place to park anything that
+  did not fit elsewhere. A rejected *concept* is not a term and does not belong in it; that record
+  lives in the no-list, whose write contract is [rejected-request-register.md](./rejected-request-register.md).

package/skills/kb-glossary/references/rejected-request-register.md

@@ -0,0 +1,115 @@
+---
+title: The no-list — write discipline
+applies_to: knowledge-base/project/rejected/
+---
+
+<!-- Inspired by mattpocock/skills/skills/engineering/triage/OUT-OF-SCOPE.md (MIT, Copyright (c) 2026 Matt Pocock). -->
+
+# The no-list — write discipline
+
+`knowledge-base/project/rejected/` holds the **rejected-concepts record**, called **the no-list** in
+conversation. It exists so that a refusal survives the issue it was written on: the issue closes, the
+thread scrolls away, and the reasoning would otherwise have to be rebuilt from memory the next time
+the same ask arrives.
+
+The founder-facing convention — the full field table, the naming rule, the write procedure — is
+`knowledge-base/project/rejected/README.md`. This file is the discipline an agent applies when
+writing to it. Read the README before the first write; read this before every write.
+
+## One file per concept
+
+The unit is a **concept**, not an issue and not a request. Three people asking for the same thing
+produce one file with three entries in `prior_requests`, not three files. Two people asking for
+adjacent things produce two files only if the refusals are genuinely different — and if they are,
+each `scope` has to say where the line between them falls, because a later lookup will land on
+whichever it matches first.
+
+The corollary is the one that gets forgotten: a **mechanism** that lost a design comparison is not a
+concept. "We chose SQS over a custom queue" is an architecture decision and belongs in the ADR that
+made it. Filing it here converts "we picked the other tool" into "we don't do queues", which is a
+far wider refusal than anybody agreed to.
+
+## Match on the concept, never on the words
+
+Requests arrive in the founder's vocabulary, and the vocabulary moves. *Night theme*, *dark theme*,
+*low-light mode* and *stop burning my eyes* are one concept. The `aliases` field is what carries
+that: it is required, and an entry whose alias list holds only a restatement of its own title is a
+matching failure waiting to happen.
+
+Write aliases in the words people actually use, including the imprecise ones. An alias is not a
+synonym dictionary; it is a record of how the ask has already been phrased.
+
+## The reason has to be durable
+
+Before writing, test the reason against time. A refusal that turns on a circumstance is not a
+refusal:
+
+- "The architecture puts this outside the product's boundary" — durable. Write it.
+- "Counsel identified liability we cannot carry in this shape" — durable. Write it.
+- "This costs more than the segment it serves is worth" — durable if the arithmetic is in the entry.
+- "Nobody has time this quarter" — **not durable.** That is a deferral, and the roadmap owns it.
+- "The current library cannot do it" — **not durable** unless the library choice is itself the
+  boundary. Otherwise it expires the day the library does.
+
+Every durable refusal has an `instead`. If nothing goes in that field, stop: either the concept is a
+rare category-level never — which is worth saying out loud, in `why` — or what is really being
+refused is a mechanism, and this is the wrong record for it.
+
+The `why`/`public_note` split is about AUDIENCE, not secrecy — and the distinction matters because
+this repository is public, so `why` is world-readable the moment it is committed and its history is
+permanent. Nothing here "stays internal". Write `why` for the team, at whatever length the reasoning
+needs, and write it as something you would be content to have quoted. Write `public_note` as one
+sentence that could be pasted into a reply without editing. An agent quotes `public_note` and never
+`why` — not because `why` is hidden, but because it is addressed to a reader who already has the
+context, and pasting it at someone who does not is how a refusal reads as contempt.
+
+## Never write a built feature into the no-list
+
+This is the prohibition that protects every future lookup. When a request is declined **because the
+capability already exists**, nothing goes in this directory. The record of that decision is the
+closing comment naming where the implementation lives — which is exactly what the redundancy
+pre-check already produced, so there is nothing new to write.
+
+The failure is not cosmetic. An entry claiming a shipped capability is absent seeds the duplicate
+check with a refusal that never happened, and every later match against that entry inherits the
+error and compounds it. The guard cannot catch it either:
+`scripts/lint-rejected-register.sh` proves an entry is internally consistent, not that it is true.
+`redundancy_check: not-implemented` is the only compliant value precisely so that the claim is
+explicit and a reviewer can re-run the `searched` lines against it.
+
+`knowledge-base/project/rejected/2026-09-20-server-side-browser-automation.md` is the worked example,
+and it is a near miss on purpose: browser automation ships, the server-side variant was refused, and
+the entry's `scope` names the implemented paths so that a lookup for the broad concept reads the yes
+as readily as the no.
+
+## The redundancy pre-check is specified elsewhere
+
+How to search for an existing implementation is **not restated here.** It is
+`plugins/soleur/skills/brainstorm/SKILL.md` `#### 1.1 Research (Context Gathering)`, which already
+mandates the functional-noun re-sweep and the report-where-you-looked discipline in sharper terms
+than a summary would. A second copy drifts from the first, and the drifted copy is the one somebody
+follows.
+
+## An entry advises; it never acts
+
+A match is a finding to hand a human, with the entry named and the doubt stated. It is never grounds
+on its own to close, label or dispose of anything, and `deferred-scope-out` must never be applied
+because a lookup matched. The README carries the two automated hops that make this the strictest
+rule in the record.
+
+Where a match is uncertain, **fail open**: surface it, say why it is uncertain, and let the human
+decide. A near-match reported is cheap. A near-match acted on is a closed door nobody chose.
+
+## Order of gates
+
+The machine gate runs before the human gate, always:
+
+1. Both pre-checks — is it built, has it been refused before.
+2. Draft the file.
+3. `bash scripts/lint-rejected-register.sh <path>`.
+4. Confirmation from the founder, given by **typing the concept** rather than `y`. A single keystroke
+   is a reflex; spelling out the concept is a decision.
+5. Write.
+
+Nothing about a person goes in the file at any step. A role where a role is needed, never a name:
+this repository is public, and git history does not forget.