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

package/bin/goblin.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+// bin/goblin.js — the node shim over the bash engine (W2, PLAN-V1 §4.3).
+//
+// The shebang is load-bearing: the §4.3 body always calls bash with the payload
+// explicitly, but npm's bin symlink executes THIS file directly (npx ./ --version),
+// and a marketplace packager stripping the executable bit breaks the symlink, not
+// the spawnSync path below.
+//
+//   goblin verify [--only <id,...>] ...   -> bin/goblin-verify
+//   goblin bans   [...]                   -> bin/goblin-bans
+//   goblin audit  [...]                   -> bin/goblin-audit
+//   goblin upgrade [...]                  -> bin/goblin-upgrade (W3)
+//   goblin doctor [...]                   -> bin/goblin-doctor (W4a)
+//   goblin emit   [...]                   -> bin/goblin-emit (W4a)
+//   goblin init   [...]                   -> bin/goblin-init (W6, the first-run wizard)
+//   anything else (install)               -> bin/goblin-install
+//
+// Non-negotiables (§4.3): args are passed as an ARRAY, never a shell string (no
+// injection surface); `bash` is named explicitly (a packager stripping the
+// executable bit must not break every command); the exit status is propagated
+// VERBATIM so the four-value verify contract survives the shim. No dependencies,
+// no async, CommonJS — this repo has no node tooling by design.
+//
+// The payload/ re-point happens with packaging (W3/W5): the npm tarball moves the
+// bash payload under payload/, so this line becomes path.join(__dirname, "..", "payload", "bin", target).
+// Until then the shim runs straight out of the checkout layout.
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+// --version prints the ONE source (VERSION) directly: a shim that routed --version to a
+// subcommand would print a constant's copy of the number, the exact drift V6 exists for.
+const arg0 = process.argv[2];
+if (arg0 === "--version" || arg0 === "-V" || arg0 === "-v") {
+  process.stdout.write(fs.readFileSync(path.join(__dirname, "..", "VERSION"), "utf8"));
+  process.exit(0);
+}
+
+const SCRIPT = { verify: "goblin-verify", bans: "goblin-bans", audit: "goblin-audit", upgrade: "goblin-upgrade", doctor: "goblin-doctor", emit: "goblin-emit", init: "goblin-init" };
+const [cmd, ...rest] = process.argv.slice(2);
+const target = SCRIPT[cmd] ?? "goblin-install"; // install → goblin-install (v1); init is a real subcommand since W6
+const file = path.join(__dirname, "..", "bin", target);
+// execPath-independent: call bash explicitly so Windows-WSL/Git-Bash works and no
+// shebang resolution is needed.
+const r = spawnSync("bash", [file, ...rest], { stdio: "inherit" });
+process.exit(r.status ?? 2);

package/docs/ADOPTION.md

@@ -0,0 +1,168 @@
+# Adoption — classes, presets, and the order
+
+## The six classes
+
+A class is **not** a stringency level. It selects which parts are required, optional or off, and
+it supplies the default gate and ratchet shape. The gate vocabulary differs by class; the
+harness does not.
+
+| Class | What "done" means |
+|---|---|
+| **A. Shipped software** | a gate set reports measured numbers, a round lands, the artifact deploys or publishes |
+| **B. Service / configuration** | a contract (schema, route, API) is unchanged, or the change is intentional and migrated |
+| **C. Game** | a suite green in the Editor **and** a human feel verdict — the verdict is a first-class deliverable |
+| **D. Knowledge / research** | a question is answered with sources and the answer is findable |
+| **E. Agent-fleet config** | a config change is applied, verified against the **artifact**, and versioned |
+| **F. Desktop shell** | the renderer is isolated from Node, the main process is not busy, and the packaged bundle ships no dev dependency |
+
+Two placements worth arguing about:
+
+- A repo whose code is small and lives elsewhere, while the repo holds *output*, belongs in
+  **D**, not A — gating it like an application gates the wrong artifact; its gate is freshness,
+  not compilation.
+- An input directory that is not a build target at all belongs in **D** with **`--archive`**.
+  Without the flag the installer keeps producing HANDOFFs for a directory whose own design
+  folders are empty.
+
+## The preset matrix
+
+`R` = required · `O` = optional (installed, reported) · `—` = off. The same data is in
+`manifest/classes.tsv`, and `CL-01` checks it against the repo.
+
+| Part | A | B | C | D | E | F |
+|---|---|---|---|---|---|---|
+| HANDOFF | R | R | R | R | R | R |
+| SPEC before change | R | R | R | — | R | R |
+| Verification gate | R | R | R | O | R | R |
+| Pinned-commit REPLAY | R | — | R | — | O | R |
+| Ratchet | R | O | O | — | O | R |
+| PR gate | O | — | O | — | O | O |
+| Review panel | O | — | R | — | O | O |
+| Playbooks (the skills) | R | R | R | R | R | R |
+| Design tokens | O | — | — | — | — | O |
+| CI lane | R | — | O | — | O | R |
+
+**F is the desktop shell**, added at W4: it declares the Electron failure surface as bans
+(`BN-06`..`BN-09`) and declares its FPS number as a **host gate** rather than a ratchet, because
+the probe that measures it needs Playwright or Electron plus a display — neither of which a
+shipped rule may depend on. Its ratchet carries `app_bundle_bytes` instead. `docs/CI.md` §3 argues
+that in full, including why frame time is the wrong number (measured flat at 16.70 ms while the
+main thread went from 1.8 % to 54.5 % busy).
+
+**`—` is a real, enforced option.** The installer records every off part in `disabled:`, so its
+rows report `SKIP (opt-out)`; `CL-01` fails if a forbidden part's artifact exists. A repo with
+1,599 test files or 27 research notes is not broken by a forced harness directory — it is
+switched off for that class.
+
+Four consequences that follow from measurement, not taste:
+
+1. A forced harness directory breaks a repo whose tests are not `checks/*.mjs`.
+2. Two gate *kinds* must exist in the schema: hermetic (repo-local) and host (touches paths
+   outside the repo). A host gate reported as hermetic reports environment differences as
+   failures.
+3. **The gate command must be declarable per project, never inferred from the stack.** 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 in a skill — all at once. The shipped gate is a
+   **floor**, and `P8` step 3 is "replace it".
+4. **The default branch is not always `main`.** It is declared in `.goblin/goblin.yaml` and
+   compared against the real branch by `PT-02`; a preset that assumes `main` silently skips a
+   repo on `master`.
+
+## The adoption order
+
+Each step is independently useful and the later ones build on the earlier:
+
+1. **A repo already at the standard, first — to prove the installer, not to improve the
+   project.** The only honest test of an installer is that it is idempotent against a repo that
+   needs nothing. Success = install, then verify reproduces the harness count and the ratchet
+   number with `git status` unchanged.
+2. **The highest-risk gap second.** A large repo with client deliverables and **no version
+   control**: everything else is recoverable from a working tree, that one has no "before".
+   Gate on: `git init` done, `.gitignore` verified against local env and build-info files, first
+   commit exists, HANDOFF exists, the real typecheck recorded.
+3. **The fleet-config repo third — highest value per minute.** A non-code preset that cannot
+   fix its own home is not publishable.
+4. **The cheapest correctness win fourth.** Content types untracked inside a repo that looks
+   protected: commit them, write a HANDOFF, then fix the branch name.
+5. **The small ones fifth** — they exercise the `—` switches. One needs a single commit; another
+   needs its `.gitignore` fixed **before** `git init` because a credentials file sits in-tree.
+6. **The two small repairs sixth** that make a fleet self-consistent: a stale HEAD, a stale
+   number, and the REPLAY added to each.
+7. **The rest seventh — real work, no emergency.** Each is blocked on a *decision* more than on
+   effort.
+8. **An archived input directory — never adopted.** It is the regression test for the off
+   switch.
+
+## What a first install actually gives you
+
+`goblin-install` exits 0 and creates: `.goblin/` (the verifier, the manifest, the config),
+`.hermes/skills/` (the flows), `HANDOFF.md`, `AGENTS.md`, and — for classes that need them —
+`ROUND-000-SPEC.md`, `reviews/`, and the harness scaffold in `checks/`.
+
+Then, in order:
+
+    git add -A && git commit          # the install is a change like any other
+    .goblin/bin/goblin-verify         # 42 passed, 1 failed - HP-05, until HANDOFF names a commit
+    hermes skills trust <target>      # one-time, so the project-tier skills load
+
+A class-A install is **green** — `43 passed, 0 failed, 11 advisory, 28 skipped`, exit 0 — once
+`HANDOFF.md` names a commit that exists; before that edit the scaffold's `0000000` placeholder is
+the one expected red (`42 passed, 1 failed`). Both numbers are measured, not assumed
+(`docs/CONTRACTS.md`; step 2 of `docs/GUIDE.md`). Twenty-eight rows skip with a reason: `HS-02` (no
+pinned pre-change commit yet), `AU-02`/`AU-03` (no report has been filed, so there is nothing to
+dedup and no reporter run to audit), `SC-06`/`SC-07`/`SC-08` (no dependency manifest, no lockfile,
+no audit record), `PF-01` (no measured perf baseline), `BN-01`/`BN-02`/`BN-05` (no `src/` for a ban
+to read) and `BN-03` with the four
+electron bans `BN-06`/`BN-07`/`BN-08`/`BN-09` (not in this class's `bans: [BN-01, BN-02, BN-05]`, so
+they skip as *not enabled* rather than as *unread*), `FM-01`/`FM-02`/`VA-01`
+(no feature map and no declared `verify_doctor:` yet), `RC-01`..`RC-04` (no reference corpus
+declared: `reference_manifest:` ships empty and a fresh repo has no lab `manifests/`) and `JG-01`
+with `LP-01`..`LP-05` (no
+`.goblin/loop/` record, because no loop has run here yet). The class's required parts that only a
+round can produce pass *vacuously* (zero `reviews/*.md` to check; the declared gate is still the
+shipped floor), so the first-step list is a list of work, not a list of FAILs.
+
+## Adopting into a repo that already has a `HANDOFF.md`
+
+The installer never overwrites a `HANDOFF.md` that existed before the install. It prints
+`refused to overwrite: HANDOFF.md` and exits 1. **That exit is correct, and `--force` is not the
+remedy**: `--force` replaces the project's own record with the scaffold, which is the act the
+refusal exists to prevent. `--force` is for a scaffold copy with nothing to keep.
+
+The remedy is a reconciliation. The project's file stays the file of record; nothing is deleted
+(a stale sentence is corrected in place with a dated parenthetical, never removed).
+
+1. **Keep the file.** Do not re-install with `--force`, and do not delete it.
+2. **Give it the five sections it is missing**, each as an H2 or H3 heading whose *first word* is
+   the slot name — a marker or number prefix (`## ▶ START HERE`) is fine:
+
+   | section | accepted first words |
+   |---|---|
+   | orientation | `START HERE` |
+   | current state | `State` · `Status` |
+   | gates | `Gate` · `Gates` |
+   | next steps | `Next steps` · `Next` |
+   | what is not verified | `Not verified` · `Unverified` · `Not proven` · `Unproven` · `Pending <x> device test` |
+
+   `HP-02` is satisfied by the heading, not by the words appearing inside one: a `## BOARD STATE`
+   heading is not a `State` section.
+3. **Put the current gate numbers inside the `Gates` section, each with its date.** Every
+   gate-bearing line in that section must read `measured YYYY-MM-DD`. Gate numbers elsewhere (in
+   `State`, in a round block) are not the current gate line, and historical round gate lines are
+   exempt — they are the record and are kept:
+
+       - `tsc`=0 · `build`=0 · hex **144** (ceiling 160) · 38/38 harnesses green · measured 2026-09-24
+
+4. **Name the HEAD in `State`** (`HEAD when this file was written: <short sha>`) — `HP-05` wants a
+   commit that exists in this repo and is an ancestor of HEAD.
+5. **Commit, then verify:**
+
+       git add -A && git commit
+       .goblin/bin/goblin-verify        # HP-02, HP-03, HP-05 go green
+
+   Success is the class's full green path (`43 passed, 0 failed, 11 advisory, 28 skipped`, exit 0 for
+   class A) with `git status --short` empty.
+
+The edit is additive and small — measured on the model repo (§1's exemplar, 2450 lines): three
+headings plus a `State` block, one dated gate line and a `Not verified` block, 15 lines, no line
+removed.

package/docs/CI.md

@@ -0,0 +1,187 @@
+# The CI lane — what makes a workflow a gate
+
+`goblin-verify` runs on a machine you control, at a moment you choose. A workflow runs on a machine
+you do not, at a moment you do not. The two must not be able to disagree about one SHA: that
+disagreement is the failure mode *"review is a prompt and a report, never a gate"* (R5 §1.1), and one
+level up it is a **required check that goes green while the gate never ran**.
+
+This file is the contract for the three things that close it: the part `ci-gate` (CL-01), the workflow
+the installer writes, and the two rows — `PG-05` and `PG-06` — that read it.
+
+---
+
+## 1. A workflow file is not a gate
+
+Four settings separate the two. None of them lives in the repository, which is why no check in this
+harness can make them true — they are **forge** changes, and `PG-04` is the row that records that.
+
+| # | Setting | Why it is load-bearing |
+|---|---|---|
+| 1 | **Required check** — Settings → Branches (or a ruleset) requires the gate job | A workflow nobody waits on cannot block anything. It reports and is ignored. |
+| 2 | **`Do not allow bypassing the above settings`** | *"By default, the restrictions of a branch protection rule don't apply to people with admin permissions"*, and *"People and apps with admin permissions to a repository are always able to push to a protected branch"*. Without this switch the rule binds everyone except the person who wrote it. It is per-rule, and it applies to a single branch at a time. |
+| 3 | **A push identity that is not the repo's sole admin** | A required check armed under your own identity binds nobody. This is the honest blocker in the estate today: the sole admin of every repo is the only committer to it, so a required check is advisory for exactly the pushes that matter. Changing it is a forge/account change, not a repository change. |
+| 4 | **Never conditional — not the job, not the step** | *"A job that is skipped will report its status as 'Success'. It will not prevent a pull request from merging, even if it is a required check."* GitHub reports a **skipped** job as Success, so a `if:` anywhere above the gate step is a green light for a commit whose gate never ran. `PG-05` enforces this mechanically. |
+
+**Where a private repo's minutes go.** GitHub Free gives 2,000 Actions minutes/month (S12); a
+typecheck + build is 3–5 minutes, so five repos on every push fits comfortably. A Unity job does not
+(30-minute timeout, image-cache churn), which is why the one existing C# workflow is the outlier and
+not the model.
+
+**Ground truth, measured at the W4 revision** — `find ~/projects -maxdepth 6 -type d -name workflows
+-path '*/.github/*'`:
+
+- `~/projects/supreme-unity/.github/workflows/unity-compile-check.yml` — the estate's **only**
+  first-party CI, and it self-skips (6 of its 7 steps are guarded by
+  `if: steps.check.outputs.ready == 'true'`, and the step that sets `ready=false` is not guarded).
+- `~/projects/pstack-upstream/.github/workflows/validate-plugins.yml` — an upstream clone of someone
+  else's project, not part of the estate.
+- Everything else: none. Of the repos with a remote (`goblin-stack`, `goblin-ui`, `open-door`,
+  `tech-goblin/frontend`, `tech-goblin/lab/diagram-studio`, `supreme-unity`) five have no CI at all.
+  A research vault, a notes repo and a no-remote directory are not candidates.
+
+---
+
+## 2. What goblin-stack places, and what it checks
+
+The `ci-gate` part is `R` for classes A and F, `O` for C and E, and `-` for B and D
+(`manifest/classes.tsv`). When it is installed, the installer renders
+`templates/ci/goblin-gate.yml.tmpl` into `.github/workflows/goblin-gate.yml` — one job, no `if:` at
+any level, whose only step runs `.goblin/bin/goblin-verify`. It is `owned`, so a second install is a
+no-op and a hand-edited copy is never overwritten.
+
+Three rows read it:
+
+- **`CL-01`** — the part's presence/absence is a class contract. Its artifact is
+  `.github/workflows/goblin-gate.yml`, **not** the `.github/` directory: a class that forbids
+  `ci-gate` forbids *goblin-stack writing a workflow there*, never the repo having CI of its own.
+- **`PG-05`** — no job-level and no step-level `if:` anywhere in any workflow under
+  `.github/workflows/`, and every job must declare at least one `run:`/`uses:` step. A job that
+  declares nothing, a workflow with no `jobs:`, and the measured real shape (one *unguarded* step
+  deciding whether the guarded gate step runs) all FAIL.
+- **`PG-06`** — the declared gate set is the gate CI runs. The declared set comes from
+  `g_yaml_gates` — the same reader `GT-01` uses, so a gate cannot vanish from the comparison in
+  silence. A workflow satisfies the row when the whole declared set is **run**: the verifier with no
+  `--only` (a full run executes every declared gate through `GT-02`), or every declared gate command
+  appearing verbatim.
+
+Comments are blanked before either row reads the file, so a commented-out verifier call is not a run.
+`#` inside a quoted string is the one reading error this costs: the rest of the line is treated as a
+comment and cannot count toward a pass.
+
+---
+
+## 3. The Electron / desktop-shell class (F)
+
+Class F exists because a desktop shell needs a part no other class has — a **host gate**, a number
+measured on a machine with a display — and forbids a thing the others allow: a **renderer that
+reaches Node or the filesystem directly**. That is a new row-set, not a flag on class A.
+
+### 3.1 The failure surface, and the check for each
+
+| Failure mode | What the harness does | Row |
+|---|---|---|
+| Renderer has Node access (`nodeIntegration: true`) | ban, text probe over the class's globs | `BN-06` |
+| Context isolation / process sandbox off | ban (one rule: Electron's docs make them one property) | `BN-07` |
+| `webSecurity: false`, `allowRunningInsecureContent`, `enableBlinkFeatures`, `allowpopups` | one ban, four one-line patterns | `BN-08` |
+| `sendSync(` / `@electron/remote` in a hot path | ban | `BN-09` |
+| Blocking the main process | **host gate** — see §3.2 | declared, `PF-01` |
+| Renderer idle-CPU spin (`idleWakeupsPerSecond`) | host gate, sampled over a 60 s window | declared |
+| A leak that grows over hours | host gate; an 8-hour property a 30-minute gate cannot see | declared |
+| The bundle ships dev dependencies | `SC-08`/`SC-03` read the manifest and the build output | existing |
+| A renderer importing main (or the reverse) | **not mechanised** — needs a dependency graph; see §4 | — |
+| IPC without `event.senderFrame` validation | **not mechanised** — semantic; see §4 | — |
+| Fuses left at defaults (`runAsNode`) | **not mechanised** — a package-time read of the built binary | — |
+
+### 3.2 The perf lane: one ratchet, and a host gate beside it
+
+There is **one** mechanism, and class F reuses it unchanged: `ratchet: {name, cmd, ceiling}`,
+enforced by `GT-04`/`GT-05` and pinned to a commit by `PF-01`. A second perf mechanism is not
+introduced.
+
+What the ratchet measures here is `app_bundle_bytes` — the packaged bundle's byte count. It is
+hermetic, it needs no browser, no display and no dependency, and a fat bundle is a slow cold start on
+every machine. **The FPS number is declared as a host gate instead** (`perf_host_gate:` in
+`presets/F-electron.yaml`), and carried in the HANDOFF with the date it was measured.
+
+This is a **deviation from G6 §B.3**, which put `main_thread_busy_pct` in the ratchet, and the reason
+is measured: the instrument that produces it — CDP `Performance.getMetrics`, or
+`app.getAppMetrics()[i].cpu.percentCPUUsage` inside a real Electron — needs Playwright or Electron
+plus a GUI, and the dependency contract (`docs/CONTRACTS.md`) allows a shipped rule nothing but
+bash/git/awk/sed/grep/python3. A `ratchet.cmd` that cannot run makes a fresh install **born RED**,
+which is the one thing the install path must not produce. The probe belongs to the project, next to
+the code it measures; a project whose CI needs npm runs it in **its own** workflow, never in
+goblin-stack's shipped contract.
+
+### 3.3 Why the FPS metric is `main_thread_busy_pct` and not frame time
+
+Measured on a real Chromium (Playwright, CDP `Performance.getMetrics`), sweeping the main-thread
+workload from 0 to 32 ms per frame:
+
+```
+burn= 0 (0ms/frame)   frames=194  p50=16.70ms p95=16.80ms p99=16.80ms  >2xp50=0   main-thread-busy= 1.8%
+burn= 1 (2ms/frame)   frames=187  p50=16.70ms p95=16.80ms p99=16.80ms  >2xp50=0   main-thread-busy=13.5%
+burn= 2 (4ms/frame)   frames=188  p50=16.70ms p95=16.70ms p99=16.80ms  >2xp50=0   main-thread-busy=26.0%
+burn= 4 (8ms/frame)   frames=191  p50=16.70ms p95=16.80ms p99=33.40ms  >2xp50=1   main-thread-busy=54.5%
+burn= 6 (12ms/frame)  frames=  7  p50=366.70ms p95=2550.00ms p99=2550ms >2xp50=3   main-thread-busy=76.9%
+burn=10 (20ms/frame)  frames=157  p50=16.70ms p95=33.40ms p99=33.40ms  >2xp50=11  main-thread-busy=99.5%
+burn=16 (32ms/frame)  frames= 92  p50=33.30ms p95=33.50ms p99=50.00ms  >2xp50=0   main-thread-busy=96.6%
+```
+
+- `main_thread_busy` is the **only monotone instrument**: 1.8 → 13.5 → 26.0 → 54.5 → 76.9 → 99.5 %.
+  It moves with the workload across the whole range, and it is a *ratio* (CDP `TaskDuration` ÷ wall
+  time), so it needs no per-run calibration.
+- **`p50` frame time is FLAT at 16.70 ms from burn=0 through burn=4** — while the main thread goes
+  from 1.8 % to 54.5 % busy. A frame-time gate at any threshold near 16.7 ms is **green on the idle
+  tree and green on the loaded tree** — `PROJECT-PRACTICE.md` §3, reproduced live in the exact metric
+  the note proposed.
+- **Dropped frames (`>2×p50`) are non-monotone**: 0, 0, 0, 1, 3, 11, 0. At burn=16, the worst
+  workload in the sweep, the counter reads **0** — at 33.3 ms pacing every frame is equally slow and
+  nothing is 2× anything. A dropped-frame gate would pass the worst case.
+- The sampler **starves** at burn=6 (7 frames in a 3.2 s window): any gate that reports "frames
+  counted" must treat a collapsed sample count as failure, not as data.
+
+The same number exists on both sides of the process boundary. In the renderer it is CDP
+`Performance.getMetrics` (`TaskDuration`/wall). In the main process it is
+`app.getAppMetrics()[i].cpu.percentCPUUsage`, whose own docs note it *"starts a new measurement
+interval"* per call — so the probe's sample window **is** the interval, and two probes in one run
+interfere. `idleWakeupsPerSecond` is the idle-spin half, an Electron-specific field, and it is an
+average over the time since the previous call, which makes a 60-second idle sample the natural unit.
+
+**A perf number measured on one box is not a user's experience.** This box is an LXC with no display
+and no system Chromium, so the numbers above come from a *bundled headless* Chromium with no
+compositor and no vsync. Relative comparisons within one machine are meaningful — which is why
+`main_thread_busy_pct` works as a gate at all — and an absolute FPS claim is not. The gate can catch
+*"this commit made the main thread 3× busier than the SHA we measured"*; it can never answer *"does it
+feel smooth on a laptop"*.
+
+---
+
+## 4. What is not mechanised, and why
+
+Recorded rather than shipped, so a later session does not re-derive them:
+
+- **A dependency-graph run over the renderer/main boundary.** Mechanisable *once the directory
+  convention is declared*, but it needs a graph tool, and no declaration exists yet.
+- **`ipcMain` handler sender validation.** Semantic: proving `event.senderFrame` was checked requires
+  reading a control-flow path, not a line.
+- **Fuses at package time.** The honest form reads the *built binary*, which needs a package step.
+- **A real user's device, GPU, compositor and thermal state.** Not observable from any machine but
+  theirs.
+- **An 8-hour leak.** A gate gets 30 minutes; a slope extrapolated from 30 minutes is a hypothesis.
+- **Packaging, signing, notarisation, installers, auto-update, OS integration.** OS-specific; none of
+  it observable here.
+- **Whether the app is *right*.** As with every gate: green means the declared checks ran.
+
+## 5. What this lane cannot see
+
+The workflow rows read a **file**. They cannot see branch protection, the required-check list, or
+whether the forge ever ran the job (`PG-04` is the row that records that, and it is advisory by
+design). `PG-06` proves a declared gate is **invoked** in a file under `.github/workflows/` — never
+that the forge marks that job required, never that it is the job the forge waits on, and never that
+the workflow *can fail* (`PG-05` is the row for that). A command sitting inside a `name:`, `env:` or
+`with:` value is dropped by the reader, but a command inside a quoted string that happens to match
+the verifier's name is not. And nothing here can arm a check: a workflow file, a required check and a
+push identity are three different things, and only the first one is in the repository.
+
+See `docs/LIMITS.md` #34 for the Electron perf gap, #13 for the `PG-05` reading, and #18 for the
+record every drift check trusts.

package/docs/CONTRACTS.md

@@ -0,0 +1,197 @@
+# Contracts — installer and verifier
+
+Dependencies: **`bash`, `git`, `awk`, `sed`, `grep`, `python3`.** No npm, no jq, no yq, no
+network. `python3` is used for one thing only: reading the two-level model mapping file, the
+same way the fleet's own tool reads it. Everything else is line-oriented shell.
+
+## Install
+
+    goblin-install --target <dir> [options]
+
+    --target <dir>        required; the repo root to install into
+    --class A|B|C|D|E|F  required unless --uninstall or --re-pin
+    --models <path>       model mapping file   (default: $GOBLIN_MODELS -> ~/projects/fleet-model.yaml)
+    --practice <path>     the referenced standard (default: $GOBLIN_PRACTICE -> ~/projects/PROJECT-PRACTICE.md)
+    --parts <list>        comma list to install; default = every part the class requires
+    --archive             mark the project archive: verify requires no HANDOFF and no gates
+    --skills yes|no       install .hermes/skills (default yes; needs the one-time trust step)
+    --dry-run             print the plan; write nothing
+    --upgrade             re-install at the current version; report created/updated/unchanged/skipped
+    --opt-out <part>      record the part in disabled: so its required checks are skipped
+    --uninstall           remove exactly the files in installed.json
+    --re-pin              re-record practice_sha256: for an edited standard; nothing else changes
+    --force               allow overwriting a file goblin-stack did not create
+    --yes                 non-interactive; take the defaults above
+
+Exit codes: `0` success or no-op · `1` a refusal, with the path and the fix · `2` bad input or a
+missing dependency.
+
+### Idempotency
+
+The installer writes only paths it records, and it **hash-compares before writing**, so running
+it twice with the same arguments and the same `VERSION` prints `no-op: N files unchanged` and
+exits 0 **without touching a byte**. A different `VERSION` is an upgrade: it rewrites only the
+files whose hash changed and prints `created C · updated U · unchanged N · skipped S`.
+
+### Three kinds of file, and why the distinction matters
+
+| kind | recorded as | overwritten? | hash-checked? | removed by `--uninstall`? |
+|---|---|---|---|---|
+| installed artifact (bin, manifest, roles, skills, harness scaffold) | `files` | yes, on upgrade | yes — IN-02, SK-02 | yes |
+| created once, then yours (`.goblin/goblin.yaml`, `HANDOFF.md`, `AGENTS.md`, `*-SPEC.md`, `reviews/.gitkeep`) | `owned` | never | no — you are meant to edit them | no, except the config |
+| pre-existing, left alone | `refused` | never | no — IN-04 only proves it was not taken over | no |
+
+A `refused` path is not a dead end. For `HANDOFF.md` the remedy is the reconciliation in
+`docs/ADOPTION.md` ("Adopting into a repo that already has a `HANDOFF.md`"): keep the project's
+file, merge the five required sections and a dated gate line in, then verify. `--force` overwrites
+it and exists for a scaffold copy with nothing to keep.
+
+An **edited standard is not a dead end** either. `practice_sha256:` pins the referenced standard
+and `IN-02` re-checks it, so one intended edit to the standard reds `IN-02` in every installed
+repo. The remedy is the explicit re-pin below — not a hand-edit of the hash, and never an
+automatic one.
+
+`.gitignore` is not a file goblin-stack owns: it appends **one marked block** and never rewrites
+the rest. `.goblin/goblin.yaml` is generated once and is goblin-stack's own config, so
+`--uninstall` removes it; `HANDOFF.md`, `AGENTS.md`, `ROUND-000-SPEC.md` and `reviews/` are the
+project's record, not the harness's, and are left in place.
+
+### An edited standard is not a dead end
+
+`.goblin/goblin.yaml` records `practice:` and `practice_sha256:`, and `IN-02` re-checks that hash.
+The pin has exactly one purpose: to make a **silently** edited standard visible rather than
+assumed. The standard itself is a living document, corrected in place, so an edit that is
+*intended* needs a deliberate way to re-record the pin. That is all `--re-pin` is:
+
+    goblin-install --target <dir> --re-pin
+
+It rewrites one line of the config — nothing else — and prints both hashes:
+
+    practice re-pinned: /path/to/PROJECT-PRACTICE.md
+      recorded 81612b17ac3483b9d613aeb86e236539fc17403e38bf7903af708d369cf7918f
+      now      8334ac24f056c94c35fa97831253e7e12bace68ae5747c81ae3b696c42ddd33a
+
+`.goblin/bin/goblin-verify --only IN-02` then reports `practice pin ok`. Every other line of
+`goblin.yaml`, comments included, is untouched, so the `owned` contract holds for everything
+except the one value you just asked to re-record. Commit the config like any other change.
+`--dry-run` prints the plan and writes nothing; when there is nothing to do it prints
+`practice pin already current` and exits 0.
+
+Four things it deliberately is not:
+
+- **not automatic.** `goblin-verify` never re-pins, and neither does a plain `--upgrade`: a pin
+  that updated itself would be the very silent edit the pin exists to catch. The `practice EDITED`
+  failure detail names this command, so the remedy is printed where the operator meets the problem.
+- **not a hand-edit.** Editing `practice_sha256:` by hand does work, but nothing then checks that
+  you pasted the right hash — which is the one thing this command does for you.
+- **not `--force`.** `--force` is about overwriting a file goblin-stack did not create; it has no
+  opinion about the pin.
+- **not a re-point.** It re-records the hash of the path already in `practice:`. Pointing the repo
+  at a *different* standard is a deliberate config edit, not a re-pin.
+
+Refusals are exit `2`, each naming the path: no `.goblin/goblin.yaml`, no `practice:` recorded, the
+recorded path absent, or no `practice_sha256:` line to rewrite. A failed write is exit `1`, with
+the path — the command never reports a re-pin that did not land. One refusal guards the mode
+itself: `--uninstall --re-pin` is exit `2` with `--uninstall and --re-pin are different jobs; run
+them one at a time` — the two modes run one at a time, and the pair is refused before anything is
+removed.
+
+### Never a half-state
+
+If any write fails the installer prints the file and exits 1. It does not roll back, because
+every created file is either a whole file or absent, and the record is written last.
+
+## Verify
+
+    goblin-verify [--only <id[,id...]>] [--json] [--list] [--source <goblin-stack path>]
+
+Output is one line per executed row, in manifest order, plus a summary line at the end:
+
+    PASS  HP-01  (test -f HANDOFF.md)
+    FAIL  GT-02  gate commit: false -> exit 1
+    ADV   MD-02  code lane and review lane both resolve to the same family
+    SKIP  HS-02  no pinned pre-change commit yet - REPLAY not provable
+
+Those four lines are one row of each marking. The summary line of a green class-A run is:
+
+          43 passed, 0 failed, 11 advisory, 28 skipped
+
+**Exit codes:** `0` every executed check passed (advisories and skips do not fail the run) ·
+`1` at least one check FAILED · `2` verify could not run (not installed, a missing dependency,
+an unparseable config) · `3` the manifest itself is broken (a row with no check and no
+`advisory` label, or a duplicate id).
+
+**What verify asserts, in one sentence:** that the files it installed are the files on disk,
+that every rule in the manifest with a command still passes, and that the untestable remainder
+is counted and capped.
+
+**What it cannot see** (printed at the end of every run): whether a check in the harness dir
+tests the right path rather than merely passing; whether the forge is bound by the workflow
+`CL-01` found; whether a human
+read the diff; whether the model mapping names a family that actually differs; and whether
+`.goblin/installed.json` — the record every drift check trusts — was itself rewritten, since it
+is not signed (`docs/LIMITS.md` #18). The CI lane adds its own, and `docs/CI.md` is where the four
+settings that make a workflow a **gate** are written down.
+
+### A fresh install verifies green
+
+Measured on a fresh class-A install, committed with no hand edit: **`43 passed, 0 failed,
+11 advisory, 28 skipped`, exit 0.** Twenty-eight rows skip with a reason: `HS-02` — no pre-change commit
+is pinned yet, so the REPLAY is not provable (`docs/LIMITS.md` #11) — `AU-02` and `AU-03`, which
+have no report to audit in a repo where no reporter has run — `SC-06`, `SC-07` and `SC-08`, which
+have no dependency manifest, no lockfile and no audit record to read yet — `PF-01`, which has
+no measured perf baseline — `BN-01`/`BN-02`/`BN-05`, which have no `src/` tree for a ban to read,
+and `BN-03` with the four electron bans
+`BN-06`..`BN-09`, which this class does not enable (`bans: [BN-01, BN-02, BN-05]`), so they skip as
+*not enabled* rather than as *unread* — `FM-01`/`FM-02`/`VA-01`, which have no feature map and no declared
+`verify_doctor:` yet (`feature_map:` and `verify_doctor:` ship empty on purpose: a fresh install
+must not be born RED — G1, `docs/LIMITS.md` #30) — `RC-01`..`RC-04`, which read a declared
+reference corpus and a lab `manifests/` directory a fresh install has neither of
+(`reference_manifest:` and `quarantine_root:` ship empty on purpose: a repo with no corpus must
+not be born RED) — and `JG-01` with `LP-01`..`LP-05`, which have
+no `.goblin/loop/` record because no loop has run in this repo: the six judge/loop rows are
+**absent-state** rows, and a fresh install must not be born RED either. **Two** rows do
+**not** skip, both of them the CI lane's: `PG-05` and `PG-06` read the workflow this class installs.
+Two, not four — the four electron bans named in the skip list above do skip here, and a tree without
+a renderer would skip them the same way. Every skip above
+is a *not yet*, not a pass.
+
+Two of the eleven advisories arrive with the same lane. `JG-02` reports that the judge lane
+resolves to **no profile** on this fleet — measured `bash bin/goblin-model judge` →
+`judge unknown unknown unknown` — so the row prints the one-line remedy and reports ADV rather
+than failing the repo for the fleet's routing (`docs/ROLES.md`, "the measured caveat"). `JG-03`
+is the counted advisory row the ceiling had left free for G2 (`docs/ENFORCEMENT.md`).
+
+The class's required parts that only a round can produce do **not** fail on a fresh install; they
+pass **vacuously**, and that is the honest reading: `PG-01`..`PG-03` iterate over `reviews/*.md`
+and there are none, and the declared gate *is* the shipped floor until step 3 replaces it. `P8`
+(`goblin-bootstrap`) walks that first-step list because the work is not done, not because the
+verifier is reporting FAILs.
+
+## Opting out, and uninstalling
+
+- **Per part:** `--opt-out <part>` records the part in `disabled:`. `goblin-verify` then reports
+  the part's rows as `SKIP (opt-out)` in the summary, so the opt-out is **visible rather than
+  absent**. The same mechanism is what makes a class's `-` (off) real.
+- **The opt-out numbers are pinned (V3-3).** A fresh class-A install with `--skills no` verifies
+  `39 passed, 0 failed, 11 advisory, 28 skipped`, exit 0, and `tests/t-install-off-switch.sh`
+  asserts that line: a silent drift in the opt-out path is caught rather than left as a number
+  nobody wrote down (the `--skills no` count moved from `37/0/9/11` at v0.2 to here when the ban
+  rows landed, and no file recorded the shift; **the skipped count moved 15 → 18 on 2026-09-25
+  (G1)** — the three new feature-map rows skip on the same path for the same reason, measured;
+  **and 18 → 24 on 2026-09-25 (W3)** — the six judge/loop rows skip there too, measured).
+- **Whole harness:** `--uninstall` deletes the `files` list plus `.goblin/goblin.yaml`, removes
+  every directory that leaves empty (deepest first, after `installed.json` itself is gone — the
+  order that used to leave `.goblin/` and the sixteen `.hermes/skills/*` directories behind),
+  leaves `HANDOFF.md`, `AGENTS.md`, `ROUND-000-SPEC.md`, `reviews/` and the `.gitignore` block
+  (with a `# goblin-stack uninstalled <date>` marker inside it), and prints what it removed and
+  what it left.
+
+## The two commands, verbatim
+
+    bash bin/goblin-install --target /path/to/repo --class A
+    .goblin/bin/goblin-verify
+
+From a checkout, without installing anything:
+
+    bash tests/run-tests.sh