@ssheleg/sheleg-dev 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,262 @@ All notable changes to this project are documented here.
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 Versioning: [SemVer](https://semver.org/spec/v2.0.0.html).
 
+## v0.7.0 — 2026-08-19
+
+**The pack that takes money had the weakest controls in the family, and every one of them
+was a sentence.** A conformance audit against the Proof of Done manifesto scored this
+member last on both counts it measured — most requirements absent, fewest mechanically
+enforced — and all three of its enforced rows were the artifact layer, none the money
+layer. The manifesto's own test failed here literally: *a credential that cannot reach
+production is stronger than a sentence saying not to use it there.*
+
+Four changes, in the order they were built: the security document stopped describing a
+different skill, the crypto provider gained a credential boundary, the four manual-gate
+categories became a hook that refuses, and the money invariants became fixtures a reader
+runs.
+
+### The four money invariants were prose, and prose delegates enforcement to the reader
+
+This pack already knew the invariants a generated integration gets wrong in the ways no
+screen shows — the webhook is the payment and the redirect only proves a browser, the same
+`event_id` on both sides or the revenue counts twice, `amount_refunded` arrives cumulative,
+delivery is not ordered — and shipped every one of them as a paragraph. The giveaway was in
+the document whose whole subject is proving a money defect would be caught: *Mutation testing
+— the only proof that counts* (`references/testing-and-local-dev.md:157` at `90e9621`), whose
+method was the sentence **"For every guard, delete it and re-run."** An instruction where a
+test belongs, in the section arguing that tests are what count.
+
+`manifesto.md:200` is that a test is stronger than an instruction, and `:289` that evidence
+proves no more than it observed. So the invariants ship as something a reader runs.
+
+**`stripe-billing/fixtures/` and `ad-tracking/fixtures/`** — copy either directory in and run
+it. Twelve provider webhook bodies shaped the way the provider sends them: the January
+renewal, the same `evt_` re-delivered, a mid-cycle proration invoice with two proration lines,
+the February renewal (delivered *first*, it is the out-of-order pair), a `4000`-then-`9000`
+cumulative refund against a `9000` charge, a bank-debit session that completed `unpaid` and
+the `async_payment_failed` that followed it, a card session that cleared, and the pixel
+arguments plus the Conversions API body one purchase produces. Plus one payload that must
+never exist, kept as a fixture: the CAPI body a thank-you-page-sourced emitter sends for a
+charge that never cleared.
+
+**Eighteen assertions across two packs, and every one has been watched failing.**
+`node assert-money-invariants.mjs --self-test` deletes one rule at a time from the reference
+handler and requires the matching assertion to go red; it fails if the measured set differs
+from the declared one in *either* direction. Nine rules on the Stripe side, five on the
+tracking side, each with a fixture that isolates it.
+
+**Isolating them is the whole engineering, and three masking pairs were found by the tool
+rather than by inspection.** SD-03's mutation sweep reached 10/10 only on its second attempt
+because two mechanisms were each leaning on the other's fixtures; the same shape appeared
+three times here. A redelivery judged by the grant count alone is refused by the event claim
+**or** by the per-period grant marker, so it proves neither — the fixture is kept, declares
+`claim+grant-marker` as a multi-rule mutant, and the claim's real isolator is a **concurrent**
+delivery (the marker reads before it writes, and a read is a round trip) while the marker's is
+the **reconciliation** entry point, which carries no event id at all. A duplicate
+`charge.refunded` is stopped by the claim and by `increment <= 0` alike, so the arithmetic is
+measured by the two-step pair, whose events carry different ids. And in `ad-tracking`, reading
+both sides out of one emitter meant deleting the browser event turned the id *and* name
+assertions red — fixed by comparing the server's output against the shipped pixel fixture, a
+boundary the server does not control.
+
+**The fixtures cannot rot.** `check_money_fixtures()` in `test/validate.py` (15 → 16 checks)
+reads each `fixtures/manifest.json` and requires both directions: every claimed invariant has
+a fixture that exists and an assertion by that name, every fixture is claimed by a row, every
+claiming document still carries its recorded phrase and names both the invariant and a path
+under `fixtures/`, and every `fixtures/…` token in the skill's markdown resolves — the bounded
+widening of the B-79 path guard that B-82 asked for. `test/fixtures_test.js` (13 checks) runs
+both packs as processes in both modes and then neuters three assertions to prove `--self-test`
+notices, because a self-test that cannot fail is the same defect one level up.
+
+Five negative self-tests, 23 → **28**: a claimed invariant whose fixture is gone, a fixture no
+invariant claims, a reference pointing at a fixture that is not there, a claim reworded away
+from its fixture, and an assertion that can no longer fail. The guard's own first run found a
+real orphan — `checkout-session-completed-paid.json`, claimed by nothing — which is why
+`paid-session-grants-once` exists: without a positive control, a handler refusing *every*
+checkout session would have satisfied `unpaid-session-grants-nothing`.
+
+`SECURITY.md` moved with it, including one claim this change **falsified**: *"There is still
+no runtime code inside the six skills"* stopped being true, because two of them now ship
+runnable `.mjs`. It is replaced by what that code does and by the grep that proves the
+boundary — no `child_process`, no `fetch`, no socket, no write, and no `process.env` read at
+all; `readFileSync` of the JSON beside it is the entire I/O surface. Recounted: 30 → **50**
+files in the payload, 4 → **22** non-markdown, 36 → **56** in the tarball.
+
+### `SECURITY.md` described a different skill, in the published tarball
+
+The document was a wholesale copy of `seo-aeo-audit`'s. It opened *"documentation plus one
+small Python script"* and named `scripts/page_audit.py`, a `commands/` directory, a
+`cursor/rules/` directory and `references/threats-and-defense.md` — this repository has
+never contained any of them; there is no runtime code in the skill payload at all. A whole
+section described the network behaviour of that auditor, down to `--url`, `--timeout` and
+`--max-bytes`. It closed with *Verifying for yourself*, three commands of which **two could
+not run**: `python3 test/test_page_audit.py` exits 2, and a `grep` at
+`plugins/sheleg-dev/skills/sheleg-dev/scripts/page_audit.py` exits 2 under a skill
+directory named `sheleg-dev` that has never existed.
+
+`package.json` ships `SECURITY.md` in the tarball, so the pack was inviting an outside
+reader to verify its safety with commands that fail — for a pack whose subject is payment
+credentials and sign-in. **Six dead references** in one document.
+
+Rewritten against what the tree actually returns: 27 files in the skill payload at that
+commit, 26 of them markdown and one a plugin manifest — 30 once the manual gate shipped
+three files beside them, see below; two installers using nothing but Node built-ins and
+coreutils, with no network, no subprocess and no npm lifecycle script; the one destructive
+difference between them (`install.sh` runs `rm -rf` on the destination every time,
+`bin/sheleg-dev.js` skips unless `--force`); credential *names* in examples and no key, with
+the one live-key-shaped line in the payload named and explained; and the five vendor commands
+the advice can lead an agent to run, each with the `file:line` that says it. Every command in
+the new *Verifying for yourself* block was run and its output is what the document claims.
+
+### The guard the B-47 guard was waiting for
+
+B-47 fixed this disease inside one table of `CONTRIBUTING.md` and said, in the guard's own
+docstring, that going wider would flag paths being *discussed* rather than used. This is the
+widening, bounded twice instead of not at all:
+
+- **By corpus** — the documents whose subject is this repository: `README.md`, `SECURITY.md`,
+  `CONTRIBUTING.md`, `.github/PULL_REQUEST_TEMPLATE.md`. A skill reference naming the
+  reader's `next.config.ts` or `src/lib/heleket.ts` is describing their project; 41 such
+  names in the payload would have been false positives, and a guard with 41 of those gets
+  switched off.
+- **By `FOREIGN_BY_DESIGN`** — the cross-repo signposts, enumerated one document at a time
+  with a reason. An exemption the document stops naming **fails**, so the list cannot widen
+  into a blanket.
+
+It reads fenced blocks as well as inline spans, because the worst reference in the old
+document was a fenced command, and it understands `path:line`: an address past the end of the
+file resolves to nothing, which is the same defect one level down.
+
+Watched refusing three plants and the real defect. Turned up two more of its own on the first
+run: `.github/PULL_REQUEST_TEMPLATE.md` asked every contributor to paste output from
+`python3 test/test_page_audit.py` and to avoid relative links in `cursor/rules/*.mdc` — both
+inherited from the same copy. Also `CONTRIBUTING.md` named `agent_sync.py` with no owner; it
+now says the script ships with the `agent-sync` skill.
+
+### `crypto-payments` had no test/live credential boundary, in the skill about taking money
+
+There was one `HELEKET_API_KEY`. It is *also* the webhook signing secret, so it cannot be
+scoped down; the key carries no `test`/`live` marker; there is one host; and "test mode" is a
+**toggle in merchant settings** — a property of the account, over the same key. The document
+handed that key to the reader in a local-development block with no environment declared beside
+it and then pointed at the dashboard toggle, so a dev, CI or agent run held the production
+credential and nothing in the pack said so. Manifesto M-06 — *a credential that cannot reach
+production is stronger than a sentence saying not to use it there, because the last control
+still works after context loss* — failed literally, in the one skill whose subject is money.
+
+**Established the provider's model before designing for it**, and it is worse than the brief
+assumed: Heleket offers no separate test credential at all, so the Stripe-shaped fix of
+reading the environment out of the key prefix does not exist here. The boundary is therefore
+built on the two non-secret things Heleket does expose — the merchant UUID, and a 12-hex
+SHA-256 prefix of the live key — pinned as `HELEKET_LIVE_MERCHANT_ID` and
+`HELEKET_LIVE_KEY_FINGERPRINT`. Same shape as the house pattern in
+`stripe-billing/references/price-integrity.md` (*a declaration separate from the secret, so
+the two can be checked against each other*), different comparand.
+
+Shipped: `HELEKET_ENV` with **no default**, because a default is the control disappearing the
+first time somebody copies a `.env`; `assertHeleketEnv()` as a copy-whole snippet that runs at
+module load rather than in the checkout handler, so a run that merely *holds* the key fails
+too; refusals in **both** directions — a live credential declared test, and the quiet one, a
+test credential declared live, where invoices settle to a merchant nobody reconciles and
+nothing errors until the revenue is missing; a refusal for `SKIP_BILLING=true` under
+`HELEKET_ENV=production`, which is a free-money path rather than a shortcut; and a refusal
+when nothing is pinned and a *test* run therefore cannot prove it is not live, because "could
+not prove it was safe" must never read as "it was safe". Named error codes, not sentences, so
+a rewording cannot silently remove a control and an operator can alert on them.
+
+**And the exposure that remains, written down.** The assertion checks the declaration; it does
+not limit the credential. Unless a second merchant account is available — which this document
+cannot confirm and now says so instead of implying it — a developer following Option B holds a
+production key, the verifier cannot be issued without the invoice-creating power attached, and
+rotation is the only revocation. An unavoidable risk that is named is a different object from
+one that is silent.
+
+The gate went from 13 checks to 14: `check_credential_boundary()` requires that every copyable
+block assigning the secret also assigns the declared environment, that the assertion exists to
+be copied, that both refusal codes are present, and that the residual exposure is written.
+Table-driven, one row, and the empty-corpus case fails rather than passing. Three negative
+self-tests (12 → 15), one per direction plus the original defect restored verbatim. The
+assertion's logic was run over 11 cases, 11/11. `stripe-billing` states the same control at
+`references/price-integrity.md:62-64` and asks for it at `testing-and-local-dev.md:210` while
+shipping no assertion — filed as B-86 rather than fixed here, because a guard added in the
+same breath as the defect it flags turns the gate red for work this change did not do. The
+other three credential-holding skills were not looked at (B-87), and this reference is now
+a 4× size outlier among references, filed as B-88 with a split rather than a trim as the
+remedy — the precedent this repository set at v0.6.0.
+
+### The four manual-gate categories were prose, and prose stops nothing
+
+`pod-manifesto/manifesto.md:204` names money movement, irreversible action, production
+access and destructive operations as the authorised person's to decide: *"The agent
+prepares the decision and its evidence. The authorised person decides."* And `:200`: *"a
+precondition is stronger than a warning."*
+
+This pack named all four and stopped none. `crypto-payments/SKILL.md:310` said **"Never
+auto-refund from the webhook. Route holds and refunds to a queue a human can see"**;
+`stripe-billing/references/webhook-events.md:170` said a dispute is **"money already gone
+plus a fee … route it to a human — evidence has a deadline"**. The plugin shipped no hooks,
+no permission list and no gate, so both were advice to a reader who could skip it and to an
+agent that never saw it. SD-02's boot assertion was the one real control here, and it runs
+*inside the reader's application* — it cannot see a shell that merely **exports** the same
+live merchant credential before any application starts.
+
+**Shipped: a `PreToolUse` hook, `plugins/sheleg-dev/hooks/`.** Eight refusals, unless the
+authorised person has signed the category off for the session: a live-shaped
+`sk_live_…`/`rk_live_…` key reaching a command; an export of `HELEKET_API_KEY` — the one
+credential SD-02 established has no test variant — in a run declaring `test` or declaring
+nothing; `stripe refunds create` or a POST to a `…/v1/refunds` URL or a `create_refund`
+tool; a payout or transfer, including Heleket's `…/v1/payout`; `stripe disputes close`; an
+explicit `--live` flag; a command setting the gate's **own** switch; and `SKIP_BILLING=true`
+in a run declaring production. The last two are never authorisable, and **no** category is
+authorisable in a run that declares a non-production environment — a run that says it is a
+test and then refunds a real card is incoherent whichever half is true.
+
+Three invariants borrowed from the family umbrella, each one enforced by the validator so
+it cannot be quietly collapsed. **The deciding is a pure module** —
+`hooks/lib/moneygate.js`, payload and environment in, verdict out, no `require` of its own
+and no filesystem — and the hook only moves bytes. **The hook fails silent**: it catches
+everything and exits 0, because a guard that throws breaks every turn in every session,
+including sessions of packs that never asked for this one; and every refusal names its
+remedy, because one without a next step teaches an operator to switch the hook off.
+**There is no `if` filter** on the hook entry: the reference calls that filter best-effort
+and says it fails open on a command it cannot parse, and `Bash(stripe refunds*)` is exactly
+the shape a `bash -c '…'` wrapper defeats.
+
+Two defects this program proved elsewhere shaped the reading. Nothing here decides from
+state the command is about to change (the umbrella's own gate asked "is anything staged?"
+at `PreToolUse`, and an add-then-commit line walked through it). And the gate **reads what
+would run**: a heredoc body fed to `cat` is data while a body fed to `bash` is a script; a
+whole-line comment does not run; an assignment-shaped token is only an assignment in
+command-prefix position, so `grep 'HELEKET_API_KEY=' plugins/` searches rather than
+exports; a money endpoint must be a URL rather than a bare path; and a live key is
+recognised by its **shape**, not its prefix, so `SECURITY.md`'s own sweep for
+`sk_live_[A-Za-z0-9]` still runs.
+
+`node test/moneygate_test.js` — **65 fixtures, both directions**, and the allow-plants are
+real commands from this repository: that sweep, a `.env` heredoc fed to `cat`, a
+commented-out `stripe refunds create`, a test-mode `sk_test_` key, and the non-secret
+`HELEKET_LIVE_MERCHANT_ID` pin `assertHeleketEnv()` *requires* in a test run. `npm test`
+now runs the validator and then the fixtures.
+
+The gate went from 14 checks to 15 with `check_manual_gate()`. Eight negative self-tests
+(15 → 23): five plant a defect in the gate's shipped shape and require the validator to
+refuse, three break its decision module and require its own fixtures to go red. **Two of
+those three were written because the first attempt went uncaught** — every `sk_live_`
+allow-plant was leaning on the reader denylist while every reader allow-plant was leaning
+on the key's shape, so neither mechanism was individually proven. A third plant escaped
+because the validator's "the hook must require the pure module" check was satisfied by the
+hook's own doc comment; it now reads the `require` expression.
+
+**Registration, and what enforces it.** As a Claude Code plugin the hook is live when the
+plugin is enabled, and `claude plugin validate --strict` schema-validates
+`hooks/hooks.json`. Installed by `npx @ssheleg/sheleg-dev`, `install.sh` or `npx skills
+add`, only the six skills are copied and **the gate is absent**: `README.md` → *The manual
+gate* carries the settings snippet, the installer now prints the reminder, and **nothing
+enforces it** — filed as B-90. Nothing writes to a person's settings file; that is the one
+thing this repository must never do unasked. `SECURITY.md`'s counts move with the three new
+files: 27 → **30** in the payload, 33 → **36** in the tarball, and the gate's whole reach is
+two `require` calls with no `child_process`, no `fetch` and no `fs` on either path.
+
 ## v0.6.0 — 2026-08-16
 
 ### The file that promised the deduplication contract contained none of it

package/README.md

@@ -20,6 +20,21 @@ Part of the [ssheleg skill family](https://github.com/ssheleg/sshlg-skills).
 
 Each carries its own references and loads them only when the work reaches them.
 
+**Two of them ship a suite rather than a warning.** `stripe-billing` and `ad-tracking`
+carry a `fixtures/` directory — real provider webhook bodies, an assertion pack, and a
+`--self-test` that deletes one rule at a time so you can watch every assertion fail. Copy
+the directory in and run it:
+
+```bash
+node plugins/sheleg-dev/skills/stripe-billing/fixtures/assert-money-invariants.mjs --self-test
+node plugins/sheleg-dev/skills/ad-tracking/fixtures/assert-dedup-contract.mjs --self-test
+```
+
+That covers the invariants whose failure is money rather than an error page: the webhook is
+the payment and the redirect only proves a browser, one `event_id` on both sides or the
+revenue counts twice, a refund total that arrives cumulative, and delivery that is not
+ordered. Each skill's `fixtures/README.md` is the map.
+
 **`stripe-billing`** — Stripe's own agent toolchain first (CLI, `stripe agent
 setup`, a sandbox without an account, the MCP implementation planner), then the
 seam it cannot help with: a pinned API version and SDK retries instead of a loop
@@ -95,6 +110,87 @@ Restart your agent afterwards — skills load at session start.
 
 ---
 
+## The manual gate
+
+Four things this pack tells you to route to a human — a refund, a payout, closing a
+dispute, a live credential — used to be **sentences**. `crypto-payments/SKILL.md` says
+"Never auto-refund from the webhook. Route holds and refunds to a queue a human can
+see"; `stripe-billing/references/webhook-events.md` says a dispute is "money already
+gone plus a fee … route it to a human". An agent reading neither, and a shell nobody
+read, were unaffected by both.
+
+So the plugin ships a `PreToolUse` hook. It refuses eight things unless the authorised
+person has signed the category off **for this session**:
+
+| Category | What it stops |
+|---|---|
+| `live-key` | a live-shaped `sk_live_…` / `rk_live_…` reaching a command |
+| `credential` | exporting a credential whose provider issues no test value — `HELEKET_API_KEY` — in a run that declares `test`, or declares nothing |
+| `refund` | `stripe refunds create`, a POST to a `…/v1/refunds` URL, or a `create_refund` tool |
+| `payout` | `stripe payouts\|transfers create`, a POST to `…/v1/payouts`, `…/v1/transfers` or Heleket's `…/v1/payout` |
+| `dispute` | `stripe disputes close`, or `…/v1/disputes/…/close` — closing one accepts the loss |
+| `live-flag` | an explicit `--live` / `--live-mode` flag |
+| `self-authorisation` | a command that sets this gate's own switch. Never authorisable |
+| `skip-billing` | `SKIP_BILLING=true` in a run declaring production — the free-money path. Never authorisable |
+
+**Authorising one.** The authorised person exports the category — or `all` — in the
+shell that starts the session, and starts a new one:
+
+```bash
+SHELEG_DEV_LIVE_AUTHORISED=refund claude
+```
+
+Two properties of that make it a decision rather than a formality. It is read from the
+environment the **hook** was spawned with, so a value exported inside a tool call never
+reaches it — and a command that tries is refused as `self-authorisation`. And **a run
+declaring a non-production environment can never be authorised**: if `SHELEG_DEV_ENV`,
+`HELEKET_ENV`, `STRIPE_ENV`, `PAYMENTS_ENV`, `APP_ENV` or `NODE_ENV` says anything other
+than production, no variable makes a live operation pass. A run that says it is a test and
+then refunds a real card is incoherent whichever half is true.
+
+`SHELEG_DEV_MONEY_GATE=off` disables it. That is deliberate and documented: a gate with no
+off switch gets deleted instead of disabled.
+
+**Registration, and what enforces it.** Nothing in this repository writes to your
+settings, by design.
+
+- **Installed as a Claude Code plugin** — `plugins/sheleg-dev/hooks/hooks.json` travels
+  with the plugin and the hook is live as soon as the plugin is enabled. Nothing further
+  to do, and no per-hook switch: enablement is the whole control.
+- **Installed by `npx @ssheleg/sheleg-dev`, `install.sh` or `npx skills add`** — those
+  copy the six skills into `~/.claude/skills/` and **carry no hook**. The gate is prose
+  again until you register it yourself, in `~/.claude/settings.json` or a project's
+  `.claude/settings.json`:
+
+  ```json
+  { "hooks": { "PreToolUse": [ { "matcher": "Bash",
+      "hooks": [ { "type": "command",
+        "command": "node \"$HOME/.claude/skills/.sheleg-dev-hooks/money-gate.js\"",
+        "timeout": 15 } ] } ] } }
+  ```
+
+  Copy `plugins/sheleg-dev/hooks/` to that path first. `npx @ssheleg/sheleg-dev` prints
+  this reminder; **nothing enforces it**, which is why the plugin channel is the
+  recommended one.
+
+The deciding is a pure function in
+[`plugins/sheleg-dev/hooks/lib/moneygate.js`](plugins/sheleg-dev/hooks/lib/moneygate.js) —
+payload and environment in, verdict out, no filesystem and no `HOME`.
+[`plugins/sheleg-dev/hooks/money-gate.js`](plugins/sheleg-dev/hooks/money-gate.js) only
+moves bytes, catches everything and exits 0: a hook that throws breaks every turn in
+every session, including sessions of packs that never asked for this one. There is
+deliberately **no `if` filter** on the hook entry — the Claude Code reference calls that
+filter best-effort and says it fails open on a command it cannot parse.
+
+Both directions are fixtured in
+[`test/moneygate_test.js`](test/moneygate_test.js), and the allow-plants are real commands
+from this repository: `SECURITY.md`'s own sweep for `sk_live_[A-Za-z0-9]`, a `.env`
+heredoc fed to `cat`, a commented-out `stripe refunds create`, and the non-secret
+`HELEKET_LIVE_MERCHANT_ID` pin that `assertHeleketEnv()` *requires* in a test run. A guard
+that refuses correct input gets switched off, and then there is no gate at all.
+
+---
+
 ## A note on `crypto-payments`
 
 The skill is provider-neutral on purpose. The reusable engineering — signature
@@ -113,7 +209,7 @@ correctly. It does not tell you which one to trust.
 ## Verify
 
 ```bash
-python3 test/validate.py
+npm test    # the validator, the manual gate's 65 fixtures, the money fixtures' 13 checks
 ```
 
 One version across `package.json`, `plugin.json`, `marketplace.json` and the top
@@ -122,6 +218,10 @@ matter does not error — hosts truncate it silently, which is worse); and
 `SKILL.md` ↔ `references/` agreement in **both** directions, so neither a
 dangling link nor a file nobody loads can ship.
 
+Plus, for the money fixtures, that every assertion has been watched failing and that no
+two rules are covering for each other — `test/fixtures_test.js` neuters three assertions
+and requires each pack's `--self-test` to notice.
+
 CI plants a defect against every one of those guards and requires the validator
 to fail. A green from a check nobody has watched fail is not evidence.