@techgoblin/gobstack 0.0.0-stage → 0.4.4-beta.2

package/skills/goblin-mode/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: goblin-mode
+description: Route a request to one goblin-stack playbook, seed the todos, and keep the two reply habits.
+---
+
+# goblin-mode
+
+The router. Load this first in any repo that has goblin-stack installed. It turns a request
+into exactly one playbook, and it refuses to invent machinery that does not exist here.
+
+## The index — one request, one playbook
+
+| request | playbook | skill |
+|---|---|---|
+| a read-only question, or "why is this happening" | P1 | `goblin-investigation` |
+| a reported defect | P2 | `goblin-bugfix` |
+| new behaviour | P3 | `goblin-feature` |
+| a behaviour-preserving reshape | P4 | `goblin-refactor` |
+| a defect where a regression test is cheap | P5 | `goblin-tdd-repro` |
+| a project has no live lane, or its gates drift | P6 | `goblin-verify-author` |
+| a feature map is missing, or its entry points have drifted | P6 | `goblin-verify-author` + `goblin-feature-map` |
+| anything that should be reviewed before it lands | P7 | `goblin-pr-gate` |
+| adopting goblin-stack in a repo, or starting one | P8 | `goblin-bootstrap` |
+| ending a session, or picking up another's | P9 | `goblin-handoff` |
+| an unattended run over a predicate | P10 | `goblin-overnight` |
+| the same change or question across projects | P11 | `goblin-sweep` |
+| a skill or prompt changed, and you want to know if it did anything | P12 | `goblin-eval` |
+| an event delivered a report (a bug report, a chat message, a webhook) | P13 | `goblin-bugreporter` |
+| a recorded claim disagrees with the artifact (drift) | P14 | `goblin-drift-audit` |
+
+If a request matches none of these, say so and ask — do not stretch a playbook to fit.
+
+## The two reply habits
+
+1. **Lead with the answer, evidence after.** The first line is the outcome; the command and
+   its output follow. Never open with what you are about to do.
+2. **Say what is NOT verified.** Every report ends with the surface the checks did not reach.
+   A claim you cannot source is marked `[unverified]`; it is never quietly implied.
+
+## Todo seeding
+
+Before the first tool call of a non-trivial task, seed the todo list from the playbook's
+required steps — one todo per step, in order, with the verification step last. A todo is
+closed only by the measurement it names, never by "looks right". If a step turns out to be
+unnecessary, close it with the reason rather than deleting it: the list is the record.
+
+## The read-vs-write fan-out rule
+
+The axis that decides fan-out is **read versus write**, not difficulty.
+
+- **Read-only work** (P1, P12, a P11 sweep) may fan out: independent readers cannot corrupt
+  each other, and the cost is bounded by the number of targets.
+- **Write work** (P2, P3, P4, P5) does not fan out by default. Parallel writers to one tree
+  cost about N times the tokens and produce conflicts a single careful pass would not.
+
+**Role-pinned fan-out goes through the kanban.** A bare subagent spawn has no model or
+provider parameter, so it cannot honour a role: it would silently run every lane on one
+model, which is exactly the review failure the panel exists to prevent. Use a board card per
+lane — each carrying the resolved provider/model, the pinned SHA, the diff and one focus —
+never a subagent spawn. `docs/ROLES.md` states this as a rule.
+
+## Forbidden code
+
+`.goblin/bin/goblin-bans` runs the ban table `.goblin/manifest/bans.tsv`; the bans this repo
+turns on are named by `bans:` in `.goblin/goblin.yaml`. Run it before you write the line —
+`goblin-verify` only reports a ban once the code already exists.
+
+## What this cannot see
+
+Whether the request was the right one to make. It routes; it does not judge intent.

package/skills/goblin-overnight/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: goblin-overnight
+description: P10: an unattended run over a checkable predicate written before iteration 1.
+---
+
+# goblin-overnight (P10)
+
+1. **The exit condition is a checkable predicate written before iteration 1**, and it is a
+   command — in the card body, or in `.goblin/loop/predicate`. Run it once before starting, so
+   you know it is runnable; record that run as `exit=<n> ts=<ISO8601>` in `.goblin/loop/first-run`
+   and pin the predicate (`LP-01`, `LP-02`).
+2. **It never gets relaxed.** If the predicate turns out to be wrong, stop and write up why; do
+   not edit the predicate to fit the result. Relaxing it is closing this loop and opening
+   another, with the old predicate archived under `.goblin/loop/closed-<date>/`.
+3. **An escape hatch.** A genuine dead end writes up why and stops: `.goblin/loop/stuck.md`, at
+   least three non-blank lines naming the predicate, committed. The exit a worker can actually
+   reach is **`kanban_block`** (naming the predicate) — there is no `kanban_edit` tool in a
+   worker's toolset. An unattended run that cannot stop is a runaway.
+4. **The morning audit reads the `Attention` section first**, then the record's rows whose
+   `result` is not `predicate:green`, in order.
+
+## Verification
+
+- The predicate is one command, and its first run is recorded at or before the first log row
+  (`LP-01`).
+- The predicate is pinned by digest and the pin has not moved (`LP-02`).
+- `goal_max_turns` is set, at or under `loop_max_turns_ceiling`, and the record never exceeds it
+  (`LP-03`).
+- No three consecutive verdict rows share an evidence pointer without reaching
+  `predicate:green` (`LP-04`).
+- A run whose last row is not `predicate:green` carries `.goblin/loop/stuck.md` naming the
+  predicate (`LP-05`).
+- Every landed change has a P7 verdict row, and any verdict that says `done` cites a handle the
+  repo resolves (`JG-01`).
+- The four record artifacts — `predicate`, `predicate.sha256`, `first-run`, `decisions.tsv` —
+  are committed, so tomorrow's reader can re-derive every decision.
+
+## What this cannot see
+
+Whether the predicate was the right one. It measures only what it was told to measure — and a
+predicate that was **vacuously true from the start** runs green on nothing, which is why the
+run-once rule exists and why a human reads the predicate.

package/skills/goblin-pr-gate/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: goblin-pr-gate
+description: P7: classify stakes S0-S4, run the gate at the candidate SHA, write a SHA-named verdict.
+---
+
+# goblin-pr-gate (P7)
+
+Use for anything that should be reviewed before it lands.
+
+1. **Classify the stakes S0-S4.** The gate is chosen by the *change*, not by the repo.
+   - S0: no review. A typo in a comment.
+   - S1: self-review. A local edit with no shared surface.
+   - S2: one reviewer, gate set run at the candidate SHA.
+   - S3: a panel of two or more independent lanes, each its own card and its own model.
+   - S4: a panel plus a human decision before landing.
+2. **Run the gate set at the candidate SHA and record the numbers.**
+3. **Write `reviews/<slug>-<head7>.md`** with `head:`, `base:`, `patch-id:`, `stakes:`,
+   `checks-run:`, `lanes:`. The file is the artifact; a board card is only the routing record.
+   At S2+, add a `security:` line naming three things the checks cannot tell a reader: the audit
+   record's date, the number of matched waivers, and the perf number with its baseline commit.
+   It is prose on purpose — a review prompt, not a check (`SC-07`, `PF-01`).
+4. **Evaluate the panel rule for S3+.** One lane is not a panel. Lanes go through the kanban
+   (see `goblin-mode`), each carrying the resolved provider/model.
+5. **At S3+, the foreman is `role-judge`.** N lane verdicts are **opinions**; the foreman turns
+   them into one **decision**, and it is a lane disjoint from the author's — a panel that grades
+   its own author is the author. A vote count is not a decision.
+6. **Re-check the patch-id before landing.**
+
+## Verification
+
+- `patch-id:` of `base..head` still matches. A new head voids the verdict — a matching commit
+  message does not restore it, and a green check from an older SHA is not a substitute.
+- The named `head:` exists in `git rev-list --all`.
+- For S2+, a check actually ran on that SHA.
+- At S3+, the deciding lane is disjoint from the author's (`JG-02`).
+
+## What this cannot see
+
+A required check that self-skips (it reports Success), and a protected branch whose only
+admin is the person pushing (it protects nothing). Nor can it see *which* lane produced a
+verdict: the review note names the declared lanes, and no file in the repo observes the profile
+that actually ran (`MD-03`).

package/skills/goblin-re-mobile/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: goblin-re-mobile
+description: P15: understand one shipped Android build as facts for study - triage, carve, manifest, dossier.
+---
+
+# goblin-re-mobile (P15)
+
+Use when one shipped Android build must be understood as facts for study, with a
+reproducible, hash-manifested corpus. The full procedure is `docs/RE-PLAYBOOK.md`; the
+steps:
+
+1. **S0 preflight.** The dedicated sandbox exists and is the one the fences describe - a
+   disposable LXC/VM, never the host.
+2. **S1 acquire.** Owned or free builds only, from a store listing with a published hash.
+   A cracked or pirated APK is a hard fence - a stop, not a judgment call.
+3. **S2 provenance.** Verify the download against the store's published md5/sha256 before
+   anything else touches it; record it in the acquisition record.
+4. **S3 triage.** The engine verdict, cheapest test first: `.so` markers
+   (`lib/*/libunity.so` + `global-metadata.dat` = Unity IL2CPP, `libue4.so` = Unreal,
+   `libcocos2d*.so` = Cocos, `libgodot*` = Godot); no `.so` plus packed assets = custom
+   Java engine.
+5. **S4 static decompile.** apktool/jadx into the quarantine, never into any repo.
+6. **S5 carve.** A carver written from decompiled evidence, never guessed - find the
+   loader, recover the transform, reimplement, cross-check against the container's own
+   size tables (the Kairosoft `.dat` precedent).
+7. **S6 manifest.** sha256 of every extracted payload into `manifests/*.sha256`, header
+   naming target + version + source store + anchor, plus the apk row itself.
+8. **S7 dossier.** Facts and numbers, never expression: measurements, counts,
+   class/method citations. No extracted art, no copied text.
+9. **S8 runtime analysis.** Deferred by design: frida hooking needs a device/emulator and
+   an owned build; static facts first.
+10. **S9 retention/teardown.** The corpus lives only in the sandbox quarantine; the lab
+    repo keeps scripts, notes and hashes only. Delete or keep is a recorded decision.
+
+## Verification
+
+- The corpus manifest verifies `sha256sum -c` where the corpus lives.
+- `goblin-verify` against the lab repo needs the harness installed there first: one
+  `goblin-install --target <lab-repo> --class A`, after which `--only RC-03` / `RC-04` run
+  (without the install, goblin-verify exits 2 `not installed`).
+- `goblin-verify --only RC-01` / `RC-02` / `RC-03` / `RC-04` return the exits their rows
+  define - an exact hash inside the build output, a weak manifest and a tracked payload
+  each fail the build.
+- Every negative control NC-1..NC-6 was shown RED and then restored.
+
+## What this cannot see
+
+- A re-encoded or resized asset passes `RC-01`'s exact-hash gate (level 2); copied text
+  inside a shipped string is level 3.
+- A weak manifest authored by hand is `RC-02`'s problem only if malformed.
+- Nothing here proves a fact is CORRECT - only that it is traceable to the corpus.

package/skills/goblin-refactor/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: goblin-refactor
+description: P4: pin the contract first, reshape, delete the legacy path in the same change.
+---
+
+# goblin-refactor (P4)
+
+1. **Pin the contract first** — a characterization test, a snapshot, or an equivalence
+   harness that asserts the *current* behaviour. A type check and lint are not a pin: they
+   say the code still compiles, not that it still does the same thing.
+2. **Shape only, no behaviour.** If the pin changes, this is not a refactor; stop and treat it
+   as a feature (P3) or a bug fix (P2).
+3. **Delete the legacy path in the same change.** A refactor that leaves the old path behind
+   has doubled the surface, not reshaped it.
+
+## Verification
+
+- The pin is a real assertion, run before and after, with both results captured.
+- The legacy path is gone: the pin no longer references it and `grep` for it returns nothing.
+
+## What this cannot see
+
+Performance characteristics a functional pin does not cover.

package/skills/goblin-sweep/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: goblin-sweep
+description: P11: the same change or question across projects - one card each, one line back.
+---
+
+# goblin-sweep (P11)
+
+1. **Enumerate targets with a shell glob, not a memory.** A list typed from memory is a list
+   that is already wrong.
+2. **Classify each target A-F.** An `archive` project is **skipped, not processed** — say so.
+3. **One card per project, parented to the sweep card.**
+4. **Collect one line per project**: what changed / what was refused / what is unfindable.
+
+## Verification
+
+- The per-project line carries the command it ran.
+- The sweep report states its own coverage: `n of m projects`, and names the ones it skipped.
+- A refusal is a result. Report it as one.
+
+## What this cannot see
+
+Projects that exist but were not enumerated by the glob — a sweep can only report on the set
+it looked at, which is why it must state that set.

package/skills/goblin-tdd-repro/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: goblin-tdd-repro
+description: P5: write the failing test, confirm it fails for the intended reason, fix, replay RED.
+---
+
+# goblin-tdd-repro (P5)
+
+Use when a defect is reproducible and a regression test is cheap.
+
+1. **Write the failing test.**
+2. **Confirm it fails for the intended reason** — not a typo, not a missing import. Paste the
+   failure and say why it is the right failure.
+3. **Smallest production fix.** No drive-by edits.
+4. **Revert the fix -> the test MUST fail -> restore.** This is the negative control; without
+   it the test is decoration.
+
+## Verification
+
+- The RED-again step is captured, with the command and the failure.
+- Prefer no new test over a bad test. A test that asserts an implementation detail pins the
+  bug in place.
+- If you skip this playbook because a regression test is not cheap, say so explicitly. The
+  skip path is never silent.
+
+## What this cannot see
+
+Defects that need a device, a network, or a human to trigger.

package/skills/goblin-verify-author/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: goblin-verify-author
+description: P6: author a project's gate set, harness and feature map, then execute them once end to end.
+---
+
+# goblin-verify-author (P6)
+
+Use when a project has no live lane, or its gates have drifted from what it actually does.
+
+1. **Read the repo, not the user, for entry points.** The declared gate must be a command the
+   repo can actually run. One inferred command is wrong for a repo with no runner, a repo that
+   cannot run its own typecheck read-only, and a repo whose runner lives elsewhere — all at
+   once.
+2. **Write the gate/check set into the harness dir**, in the house harness shape: a
+   `failures` counter, an `assert(name, ok, detail)` printer, a non-zero exit on failure, and
+   a REPLAY block at the bottom.
+3. **Execute it once end to end.** A generated skill that was never executed is a draft, not
+   a deliverable.
+4. **Add the REPLAY block.** Run each assertion against the pinned pre-change commit and
+   require it to be RED there. Pin the pre-change commit, never `HEAD`.
+5. **Seed the feature map.** The harness needs a list of what there is to drive, and the map is
+   that list (`goblin-feature-map`): one file per user-facing feature, each with its entry points
+   and the exact command that drives it. Declare `feature_map:` and `source_root:` in
+   `.goblin/goblin.yaml`. An **empty `feature_map:` is the honest state of a project with no map
+   yet** (`FM-01`/`FM-02` then skip with that reason); a declared path that names no map is a hole
+   and is reported as one.
+6. **Hand the generated skill to P12 before calling it verified.** goblin-stack installs
+   agent-authored skills, and a generated skill accepted after a skim is a different proposition
+   from a written one — the record P12 produces (`evals/<slug>/`) is what makes "verified" a
+   measurement rather than a date. **`verified:` does not advance until that record exists.** The
+   row that checks a record's shape is not shipped yet, so this is a stated requirement here and
+   in `goblin-eval`, not a claim that a command enforces it.
+
+## Verification
+
+- The harness prints `PASS`/`FAIL` per assertion and exits non-zero on any failure.
+- The REPLAY shows RED pre-change, with the commit named.
+- The gate set is declared in `.goblin/goblin.yaml`, never inferred.
+- The map's index and four-H2 entry contract hold (`FM-01`), every declared entry path still
+  resolves under `source_root:` and none changed after its `verified:` date (`FM-02`), and the
+  declared `verify_doctor:` exits 0 (`VA-01`).
+- A `verified:` date advances only for a feature that was actually driven, and only after the P12
+  record for the generated skill itself exists.
+
+## What this cannot see
+
+Whether an assertion tests the right path rather than merely passing. That needs a human read
+of the diff, and `goblin-verify` says so on every run. Neither does this skill know whether the
+map lists **every** feature: `FM-01` checks the index against the files that exist, so a feature
+nobody wrote down is invisible to it.

package/skills/practice/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: practice
+description: The composition hook: read the referenced standard at the path pinned in .goblin/goblin.yaml.
+---
+
+# practice
+
+goblin-stack owns the **mechanism**: which rule is enforced by what, how it is installed, how
+it is verified, which class a project is, which flow applies, which role runs it.
+
+The **house style** — the HANDOFF shape and the stale-sentence rule, the SPEC lifecycle, the
+harness house style and the pinned-commit REPLAY, the gate vocabulary, commit discipline, the
+delegation tiers, data safety, the documentation duty, adopt-don't-replace — belongs to the
+standard this repo references. goblin-stack carries **no copy of it**.
+
+## Mandate
+
+1. Read `.goblin/goblin.yaml` and take `practice:`.
+2. If that path exists, **read the standard before starting work** in this repo. Its hash is
+   pinned in `practice_sha256:`; `goblin-verify` re-checks it, so a silently edited standard
+   is visible rather than assumed. If the standard has been edited **deliberately**, re-record
+   the pin deliberately: `goblin-install --target <repo> --re-pin` rewrites that one line and
+   prints the old and new hash. Nothing re-pins on its own — not `goblin-verify`, not
+   `--upgrade` (`docs/CONTRACTS.md`).
+3. If the path is absent or unset, **say so** and continue with the goblin-stack rules alone.
+   Absent is not an error: goblin-stack is portable, and another machine has no such file.
+
+## Why it is a pointer and not a copy
+
+Two living copies of the same rule with no equality check is the rot goblin-stack exists to
+remove. One copy plus a recorded hash is not. Do not paste the standard's text into any file
+here, and do not supersede it: split by kind, not by ownership.
+
+## What this cannot see
+
+Whether the standard itself is still right. That is a human's edit, and this skill can only
+notice that it changed.

package/templates/AGENTS.md.tmpl

@@ -0,0 +1,23 @@
+# AGENTS.md
+
+This repository uses **goblin-stack** (class `{{CLASS}}`, installed {{DATE}}). It is a pointer,
+not a rule dump — the rules live in one executable place, and facts beat requirements.
+
+- **Rules and their checks:** `.goblin/manifest/enforcement.tsv` (one row per rule; every row
+  carries a runnable check or the literal `advisory`).
+- **Forbidden code (the ban list):** `.goblin/bin/goblin-bans` runs the bans named by `bans:` in
+  `.goblin/goblin.yaml`; each ban's mechanism lives in `.goblin/manifest/bans.tsv`. Run it before
+  you write the line, not after — a ban is a gate, and `goblin-verify` only reports it once the
+  code exists.
+- **Verify:** `.goblin/bin/goblin-verify` — exit 0 pass, 1 a check failed, 2 could not run,
+  3 the manifest is broken.
+- **Procedures:** the skills installed at `.hermes/skills/` (Hermes project tier — highest
+  precedence, repo-owned). Start with `goblin-mode`, which routes a request to a playbook.
+- **Session state:** `HANDOFF.md` at the repo root. Read it before touching anything.
+- **Project config:** `.goblin/goblin.yaml` (class, branch, gates, ratchet, runtime data,
+  replay, opt-outs). Edit it in place; the installer never overwrites it.
+- **The referenced standard**, if configured, is named by `practice:` in `.goblin/goblin.yaml`.
+  Read it before starting work; this repo carries no copy of it.
+
+Two things this repo does not do: it does not choose models (a role resolves through the
+mapping file named by `models_file:`), and it does not write outside its own tree.

package/templates/HANDOFF.md.tmpl

@@ -0,0 +1,43 @@
+# HANDOFF — the session-boundary contract. A new worker reads this FIRST.
+
+> Template. Written once by goblin-install and never overwritten. Update it every round:
+> every gate number carries `measured <date>`, the State line names the current HEAD, and the
+> NOT verified section is non-empty or says "nothing outstanding".
+
+## ▶ START HERE (new session)
+
+- Working dir: the repo root.
+- Gate set: `{{GATE_NAME}}` — `{{GATE_CMD}}`, plus whatever you add in `.goblin/goblin.yaml`.
+- Run the gates and the manifest checks: `.goblin/bin/goblin-verify`
+- One line of measured numbers for the round: `.goblin/bin/goblin-verify --only GT-02` writes `.goblin/last-gate-line`.
+- Read before working: the referenced standard, if `.goblin/goblin.yaml` declares `practice:`.
+
+## State
+
+- Branch: `{{BRANCH}}` · class: `{{CLASS}}` · goblin-stack installed {{DATE}}.
+- HEAD when this file was written: `{{HEAD}}`
+- In flight: nothing yet.
+- Done: the harness is installed.
+- Pushed: not yet.
+
+## Gates
+
+Every number here is a measurement with a date, never a copy from a previous round.
+
+- `{{GATE_NAME}}` = 0 · measured {{DATE}}
+- ratchet — declared in `.goblin/goblin.yaml`; re-measure it, do not copy it.
+- Example of the required form: `typecheck=0 · build=0 · ratchet <n> (ceiling <c>) · <n>/<n> harnesses green · measured {{DATE}}`
+
+## Next steps
+
+- Replace the default gate with this project's real commands (playbook P8 step 3).
+- Write the first round's SPEC (`*-SPEC.md`) before any code moves (playbook P3).
+- Write the first asserting harness in the harness dir, and pin its pre-change commit so
+  `replay.commit` can be set (playbook P6, then HS-02).
+
+## NOT verified
+
+- Nothing in this project has been proven by a human yet: the harness exists, its assertions
+  do not. Every gate number above is the value the declared command printed, and nothing more.
+- A stale sentence in this file is corrected in place with a dated parenthetical, never
+  silently deleted: deleting it erases the fact that it was once believed true.

package/templates/SPEC.md.tmpl

@@ -0,0 +1,34 @@
+# ROUND-000-SPEC — <one line: what this round changes>
+
+> Template. Written once by goblin-install for classes that require a SPEC, then never
+> overwritten. Write one per round BEFORE implementation, and commit it with — or before —
+> the code it describes: an untracked `*-SPEC.md` is lost by a run that dies.
+
+Class: {{CLASS}} · written {{DATE}}
+
+## Measured root cause
+
+State *why*, backed by a command whose output is pasted here. A report of "X is broken" is
+not a root cause; a screenshot or a complaint is a hint for what to measure, never the
+measurement.
+
+    <the command>
+    <its real output>
+
+## What changes
+
+<the smallest change that removes the measured cause, and the data shape it introduces>
+
+## AC: acceptance criteria (each checkable without a human)
+
+- AC1: `<a command>` prints `<the expected value>` — i.e. the criterion is a comparison, not a feeling.
+- AC2: the same command exits 0 before the change and non-zero after it (the negative control).
+- AC3: `git status --short` is empty after the round's commit.
+
+## Device-test items (not checkable here)
+
+<the things only a human can judge, listed separately so they are never mistaken for the ACs>
+
+## What this spec cannot see
+
+<the surface the checks above do not reach>

package/templates/audit-waiver.tsv.tmpl

@@ -0,0 +1,10 @@
+# .goblin/audit-waiver.tsv — one line per accepted dependency advisory (SC-07).
+#
+# package	severity	id	date	reason
+#
+# The date is the day the decision was taken, and SC-07 refuses a waiver older than
+# security.waiver_max_age_days: a waiver with no expiry is a permanent blind spot. A
+# high|critical line in .goblin/audit.tsv with no matching row here is a RED.
+#
+# example:
+# next	high	GHSA-xxxx-yyyy-zzzz	2026-09-24	no fixed release yet; the vulnerable path is the dev server only

package/templates/boundary-waivers.tmpl

@@ -0,0 +1,8 @@
+# .goblin/boundary-waivers — write routes that deliberately do NOT validate input (SC-05).
+#
+# One repo-relative path per line, with the reason after a '#'. A waiver is a DECISION recorded
+# where the row can read it; it is not a silence. SC-05 prints the waiver count on its gate line
+# so the debt is visible on every run.
+#
+# example:
+# src/app/api/webhook/route.ts   # signed by the provider's HMAC, verified in lib/hmac.ts

package/templates/checks/assert.mjs.tmpl

@@ -0,0 +1,60 @@
+// checks/assert.mjs — the house assertion harness (PROJECT-PRACTICE section 3 shape).
+//
+// Rename it to checks/<round>-<slug>.mjs and write real assertions. This file ships the
+// SHAPE, not the checks: it currently asserts one thing that is true by construction, so it
+// is a scaffold, not a deliverable. P6: "a generated skill that was never executed is a
+// draft, not a deliverable."
+//
+// WHAT THIS CANNOT SEE: anything that needs a browser, a device, a network service or a
+// human. Say so at the top of every harness you write here.
+
+import { readFileSync } from 'node:fs';
+
+const failures = [];
+let checked = 0;
+
+function assert(name, ok, detail = '') {
+  checked += 1;
+  if (ok) {
+    console.log(`PASS  ${name}${detail ? ' - ' + detail : ''}`);
+  } else {
+    console.log(`FAIL  ${name}${detail ? ' - ' + detail : ''}`);
+    failures.push(name);
+  }
+}
+
+// Source probes read text with comments BLANKED first, not stripped: blanking keeps line
+// numbers and byte offsets true, and stops a comment that quotes a removed control from
+// reading as the control still being present.
+function blankComments(src) {
+  return src
+    .replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '))
+    .replace(/(^|[^:])\/\/[^\n]*/g, (m, p1) => p1 + ' '.repeat(m.length - p1.length));
+}
+
+// ---- REPLAY ------------------------------------------------------------------
+// A check green on both trees proves NOTHING. Before this harness is trusted, run it against
+// the pinned pre-change commit and require it to be RED there:
+//
+//   git worktree add --detach /tmp/pre <commit>
+//   GOBLIN_PRE_COMMIT=<commit> node /tmp/pre/checks/<this-file>.mjs   # must exit non-zero
+//
+// goblin-verify does exactly this for every harness when replay.commit is set (rule HS-02).
+// Pin the pre-change commit, never HEAD: once the round is committed, HEAD IS the fixed tree.
+const REPLAY = Boolean(process.env.GOBLIN_PRE_COMMIT);
+
+// ---- probes ------------------------------------------------------------------
+// Replace this block. Each assertion must be RED on the pre-change tree, or it is not a
+// check - it is a description.
+const self = readFileSync(new URL(import.meta.url), 'utf8');
+assert('harness reads its own source with comments blanked',
+  blankComments(self).includes('function assert('),
+  `blanked ${blankComments(self).length} bytes`);
+
+// ---- verdict -----------------------------------------------------------------
+if (failures.length > 0) {
+  console.log(`${checked - failures.length}/${checked} passed${REPLAY ? ' (replay: this tree is pre-change)' : ''}`);
+  process.exit(1);
+}
+console.log(`${checked}/${checked} passed${REPLAY ? ' (replay: this tree is pre-change)' : ''}`);
+process.exit(0);

package/templates/checks/gate.sh.tmpl

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# checks/gate.sh — run the declared gate set and print ONE line of measured numbers.
+# Convenience wrapper around the same declarations goblin-verify uses (GT-02/GT-05).
+# Rename or replace it; it is a starting point, not a requirement.
+set -uo pipefail
+ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+# shellcheck source=/dev/null
+. "$ROOT/.goblin/bin/goblin-lib.sh"
+CONFIG="$ROOT/.goblin/goblin.yaml"
+
+line=""
+bad=0
+while IFS=$'\t' read -r name cmd; do
+  [ -n "$name" ] || continue
+  ( cd "$ROOT" && bash -c "$cmd" ) >/dev/null 2>&1
+  rc=$?
+  line="$line $name=$rc"
+  [ "$rc" -eq 0 ] || bad=1
+done < <(g_yaml_gates "$CONFIG")
+
+rname=$(g_yaml_block_scalar "$CONFIG" ratchet name)
+rcmd=$(g_yaml_block_scalar "$CONFIG" ratchet cmd)
+if [ -n "$rname" ] && [ -n "$rcmd" ]; then
+  rval=$( cd "$ROOT" && bash -c "$rcmd" 2>/dev/null | tr -d '[:space:]' )
+  line="$line · $rname $rval (ceiling $(g_yaml_block_scalar "$CONFIG" ratchet ceiling))"
+fi
+
+printf '%s · measured %s\n' "${line# }" "$(date +%F)"
+exit $bad

package/templates/ci/goblin-gate.yml.tmpl

@@ -0,0 +1,46 @@
+# .github/workflows/goblin-gate.yml — written once by goblin-stack for class {{CLASS}}.
+#
+# WHAT THIS IS. One job that runs the gate set this project DECLARES in `.goblin/goblin.yaml`.
+# `.goblin/bin/goblin-verify` executes every declared gate (GT-02) and every rule that carries a
+# command, so CI and a local verify cannot report two different truths about one SHA (PG-06).
+# The job carries NO `if:` at any level, on purpose: GitHub reports a SKIPPED job as Success even
+# when it is a required check, so a conditional here would be a green light with no bulb (PG-05).
+#
+# A WORKFLOW FILE IS NOT A GATE. Four things make it one, and all four are yours to do:
+#   1. REQUIRED CHECK — mark the `gate` job required for this branch (Settings -> Branches, or a
+#      ruleset). Until then the job runs and nothing waits for it.
+#   2. NO BYPASS — tick "Do not allow bypassing the above settings". Without it the restriction
+#      does not apply to admins, and an admin push skips the check entirely.
+#   3. A PUSH IDENTITY — a required check binds nobody while the only committer is the repo's
+#      sole admin. Push from a non-admin account or token, or accept that the gate is advisory
+#      for your own pushes. This is a forge change, not a file change: that is why PG-04 is the
+#      row that records it, and why PG-04 is advisory rather than a gate.
+#   4. NEVER CONDITIONAL — keep every job and step unconditional (PG-05 enforces it).
+#
+# WHAT IT CANNOT SEE. It runs on a runner you do not own, from a checkout of your repo. Any gate
+# that needs a display, a licence, a GPU or a signed-in session is a HOST gate: declare it in the
+# HANDOFF's measured numbers, do not try to run it here. On a private repo the minutes are billed
+# to your account, so a long job is not free.
+#
+# For a zizmor-clean workflow, pin `uses:` to a commit SHA instead of a tag:
+#   gh api repos/actions/checkout/git/refs/tags/v4 --jq .object.sha
+# (left as a tag here so the file is readable; nothing in goblin-stack reads a workflow's SHA).
+name: goblin-gate
+on:
+  push:
+    branches: [{{BRANCH}}]
+  pull_request:
+permissions:
+  contents: read
+concurrency:
+  group: goblin-gate-{{BRANCH}}
+  cancel-in-progress: true
+jobs:
+  gate:
+    name: the declared gate set
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+      - name: run the declared gate set
+        run: bash .goblin/bin/goblin-verify