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

package/skills/goblin-bootstrap/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: goblin-bootstrap
+description: P8: adopt goblin-stack in a repo - classify, install, verify, then the first round.
+---
+
+# goblin-bootstrap (P8)
+
+Use when adopting goblin-stack in a repo, or starting one.
+
+1. **Classify the project A-F.** The class selects which parts are required, optional or off;
+   it is not a stringency level. F is a desktop shell: it adds the electron bans and a host gate.
+2. **`goblin-install --target <dir> --class <x>`**
+3. **`goblin-verify`** — a class-A install verifies 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 `HP-05`'s one expected day-one red (`42 passed, 1 failed`).
+   Twenty-eight rows skip with a reason, and the reason matters: `HS-02`
+   (no pinned pre-change commit yet, so the REPLAY is not provable), `AU-02`/`AU-03` (no report
+   has been filed in this repo), `SC-06`/`SC-07`/`SC-08` (no dependency manifest, no lockfile, no
+   audit record), `PF-01` (no perf baseline measured yet), `BN-01`/`BN-02`/`BN-05` (the ban table is
+   installed but this fresh repo has no `src/` for a ban to read) and `BN-03` with the four electron
+   bans `BN-06`..`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 there is no lab
+   `manifests/`), and `JG-01` with
+   `LP-01`..`LP-05` (no `.goblin/loop/` record, because no loop has run in this repo yet). Each is
+   a *not yet*, not a pass.
+   The class's required parts
+   that only a round can produce (a first review, a real gate) pass *vacuously*, and that list
+   is the repo's first-step list, not a defect.
+4. **Fix `.gitignore` BEFORE any `git init`.** A credentials file already in the tree is
+   committed by the first `git add -A` and is then in history forever.
+5. **First HANDOFF, first SPEC, first check script** — in that order, each independently
+   useful.
+6. **Record the first perf number, and the commit you measured it on.** Run `ratchet.cmd` on a
+   pinned commit, write the value into `ratchet.ceiling` and the same number into
+   `perf.baseline_value`/`perf.baseline_commit`/`perf.measured`. Until you do, `PF-01` skips with
+   "no perf baseline recorded yet" — a green run that proves nothing about the number you ship.
+
+## Verification
+
+- `goblin-verify` exit 0, and the created-file list matches `.goblin/installed.json`.
+- A repo with no gate declares one and records its first measured numbers.
+- `.gitignore` is verified before the first commit, not after.
+- The perf baseline exists, and it names a commit that exists (`PF-01`), rather than the ratchet
+  ceiling having been raised by hand.
+
+## What this cannot see
+
+Whether the class you chose matches how the project actually ships. Re-classify when it does
+not; the installer records the class and `CL-01` checks the parts against it.

package/skills/goblin-bugfix/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: goblin-bugfix
+description: P2: reproduce a defect, fix its measured root cause, prove absence with a control.
+---
+
+# goblin-bugfix (P2)
+
+1. **Reproduce it yourself**, with the exact command, before touching anything. A bug you did
+   not reproduce is a bug you will not fix.
+2. **State the root cause with a measurement.** Never "should be" and never "probably". Paste
+   the command and its output that shows the cause.
+3. **Fix the root, not the symptom.** A guard added at the call site of a wrong value is a
+   symptom fix; the wrong value is the bug.
+4. **Prove absence on the same surface, with a negative control.** The repro command fails
+   before and passes after. Then revert the fix, confirm the repro fails again, restore.
+
+## Verification
+
+- The repro fails before and passes after, on the *same* command.
+- A unit test shows branch behaviour, not bug absence. Do not report a green suite as proof
+  the bug is gone; report the repro.
+- If the defect also exists in a sibling project, say so and do not silently fix it there.
+
+## What this cannot see
+
+Bugs whose only symptom is a human noticing something looks wrong.

package/skills/goblin-bugreporter/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: goblin-bugreporter
+description: P13: intake a bug report, reproduce it at a named revision, and hand off a fix card only on proof.
+---
+
+# goblin-bugreporter (P13)
+
+Use when a report has arrived as an **event** — a report file under `reports/<slug>/`, a chat
+message turned into one, or a webhook payload. You are the reporter. You never fix.
+
+1. **Validate the intake.** `reports/<slug>/report.yaml` must carry the six required keys
+   (`repo`, `symptom`, `expected`, `observed`, `repro_steps`, `revision`) and its `dedup_key`.
+   Run the validator rather than eyeballing the file:
+
+       bash .goblin/automations/bugreporter-intake.sh <slug>
+
+   A missing key is a **refusal**, not a guess: create the same card with **no `--assignee`**,
+   so the dispatcher buckets it `skipped_unassigned` and no agent acts on it, and name the
+   missing field in a comment. The human sees it; nothing is silently lost or invented.
+2. **Freeze the coordinates.** `repo` and `revision` are immutable for the run. If `revision`
+   is not a commit that resolves (`git rev-parse --verify <rev>^{commit}`), the report is a
+   refusal: a repro at a revision nobody can check is not a repro.
+3. **Reproduce, in this order.**
+   - **R1** — a failing command with its output, at the named revision. The best form.
+   - **R2** — the REPLAY form: `git show <revision>:<file>` into a temp dir, run the probe
+     against it, require RED. Never a probe that is green on both trees.
+   - **R3** — a real-UI drive with captured evidence. Admissible only with a configured
+     control adapter, and **never** accepted as harness proof; it is evidence for a human.
+4. **Write `reports/<slug>/repro.md`** as a two-row table, not a story: `command:`/`revision:`,
+   a `pre:` row that is RED with the pasted output, and the `post:` row. The `pre` row is the
+   negative control and it is not optional — a single green run reproduces nothing.
+5. **Create the fix card only on `reproduced`.** `--assignee coder`, `--skill goblin-bugfix`,
+   `--parent <this card>`, the report's dedup key. The child waits in `todo` until this card is
+   `done`, so the gate is a dispatcher-enforced dependency rather than a promise.
+6. **Complete your own card with the verdict** in the completion metadata:
+   `reproduced` | `could-not-reproduce` | `blocked`. `could-not-reproduce` is a complete,
+   successful run — not a failure to work around. `blocked` names the missing capability.
+
+## Write surface
+
+`reports/**`, and the card this lineage owns (`kanban_create` for the fix card). Nothing else:
+no `git commit`, no source edit, no edit under the harness dir, no vault write. `AU-03` asserts
+the working tree is clean after a run, so a reporter that edited the tree fails its own gate.
+
+## What this cannot see
+
+Whether the report is *true*. The gate proves the symptom reproduces at a revision; it cannot
+prove the reporter's description of intent, severity or cause is right, and it cannot see a fix
+that fixed the wrong thing. It cannot see a defect whose only detector is a human eye, anything
+needing a device, a network or a running production instance, or a defect that reproduces only
+on a revision that no longer builds. In those cases the verdict is `could-not-reproduce`, and
+that is the whole answer.

package/skills/goblin-drift-audit/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: goblin-drift-audit
+description: P14: repair a recorded claim that no longer agrees with the artifact, one card per drifting repo.
+---
+
+# goblin-drift-audit (P14)
+
+Use when a drift card exists. The producer (`automations/drift-audit.sh`) compared a recorded
+claim against an artifact, disagreed, and filed **one card per drifting repo**. You repair the
+disagreement; you do not re-derive it from memory.
+
+1. **Read the record, not your memory.** The card body carries the repo, the check id and the
+   detail line the producer computed. Re-run that exact check yourself and confirm it is still
+   RED:
+
+       <repo>/.goblin/bin/goblin-verify --only <check-id>
+
+   A drift that is no longer reproducible is a stale card, and closing it with that fact is a
+   complete run.
+2. **Classify it.** A **real regression** (the artifact changed and the claim did not) | a
+   **stale-by-design claim** (the claim is historical, and `PROJECT-PRACTICE` section 1 requires
+   it kept, so it gets a dated parenthetical) | **fixture drift** (the recorded value is right
+   and the check is wrong).
+3. **Repair the right one.** A hash drift after an intended edit of the referenced standard is
+   a deliberate `--re-pin`, never a hand-edited hash. A missing installed file is a re-install.
+   An absent gate line is a gate run. **Never edit a harness to make a number green** — that is
+   the one repair that must never happen from here, and it is the repair an automated actor is
+   most likely to reach for.
+4. **Prove it.** Re-run the same `--only <check-id>` and show GREEN, and name the command and
+   the revision in the completion metadata.
+
+## Write surface
+
+Only the drifting repo named by the card, only the repair the card names — the config, the
+ignore file, the pin, or the install. No harness edit, no vault write, no push.
+
+## What this cannot see
+
+Whether the *claim* is the right one to keep. It compares a recorded value with an artifact, so
+it cannot detect drift in something nobody recorded: an unwritten assumption, a stale sentence
+with no number in it, or a document that was never generated from the artifact. It also cannot
+see whether the producer's ceiling stopped a real finding from being filed — that is why a
+capped run prints its own line.

package/skills/goblin-eval/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: goblin-eval
+description: P12: measure whether a skill or prompt change did anything, blinded.
+---
+
+# goblin-eval (P12)
+
+Use when a skill or prompt changed and you want to know if it did anything — including when the
+thing that changed is a **generated verification skill** (P6's output). This is the only mechanism
+goblin-stack has for that question, and it has never been run — treat its output as a first
+measurement, not a verdict. The runner is **not shipped**: every step below is a procedure an
+operator executes, and no row in `manifest/enforcement.tsv` reads a lane yet.
+
+1. **Candidate and control run in sanitized directories.** Same task, same starting tree, one
+   difference. Sanitized means a **clean workspace with nothing borrowed**: no prior chats, no
+   prior artifacts, no prior executions. An agent that can reach a previous run can produce the
+   answer without using the skill, and then the eval measures nothing but the leak.
+2. **No condition token anywhere the candidate can see.** The ban is eleven tokens — `eval`,
+   `test`, `judge`, `experiment`, `rubric`, `score`, `compare`, `benchmark`, `candidate`,
+   `arena`, `control` — not only the four this skill used to name, and it covers the directory
+   names, the file names and the prompt. A candidate that knows it is being graded changes
+   behaviour.
+3. **Grade the chain from the transcript** — which files it actually opened, which commands it
+   ran — never the self-report.
+4. **The judge runs as `role-judge`, on a lane disjoint from the candidate's.** A model grading its
+   own family's output is grading itself; the lane that decides must not be the lane that wrote.
+   `JG-02` checks the declared lanes are disjoint, and reports an unresolved judge lane as `ADV`
+   rather than failing a repo for the fleet's routing. What the judge receives, what it must
+   refuse and how its verdict is recorded is `docs/LOOP.md` — the short form is: **a predicate and
+   a handle the repo can resolve, never a self-report.**
+5. **Write the record where the next reader looks.** One directory per eval, `evals/<slug>/`:
+   `prompt.md` (the one organic prompt, identical across lanes), `rubric.md` (3–6 criteria, for
+   the judge only), `manifest.tsv` (`lane · condition · label · profile · provider · model ·
+   family · workspace · card_id · session_id · transcript`), `transcripts/<label>.jsonl` (the
+   exported session, one file per lane) and `verdict.md` (the judge's per-criterion scores, each
+   with an `evidence:` line naming the lane and the location). The **family** is recorded, never
+   only the model slug — and **no model slug belongs under `skills/ manifest/ bin/ templates/
+   presets/ .goblin/ .hermes/`**; `evals/` sits outside that scope on purpose, because a slug is
+   run data, not content for a rule.
+6. **A change must improve the evaluated cases or add new evaluations.** That is the merge rule,
+   and it is this repo's "a check must be able to go RED" applied to skill prose: changing
+   instructions requires evidence about the resulting behaviour, not a judgement that the new
+   wording sounds better. **When the subject is a generated verification skill, the pass condition
+   is a number**: every seeded defect must make the harness RED, the control (the same defects
+   against a harness carrying no assertions) must detect **zero**, and every correction must be
+   RED before it is GREEN. A skill that misses a seeded defect has a hole; a sensitivity below
+   1.0 is reported with the number beside it, never rounded up to a pass.
+7. **Cheap checks first; the judge last.** Regex and script assertions for what is concrete (the
+   right SDK, the right method, the absence of an obsolete pattern); an LLM judge with an explicit
+   rubric only for what needs interpretation. **Triggering is a diagnostic, not the objective** —
+   loading the skill on the fifth turn can be fine and completing the task without loading it can
+   be fine too, so the trigger result stays visible without defining pass/fail.
+
+## Verification
+
+- The judge's verdict is reproducible from the transcripts alone.
+- Candidates never learn that other candidates exist.
+- Every lane named in `manifest.tsv` has a transcript file that exists.
+- A generated verification skill is not "verified" until a record exists for it: its declared
+  doctor exits 0 (`VA-01` is the executable half), and the record carries the sensitivity.
+
+## What this cannot see
+
+Small effects. With a handful of runs, a difference smaller than the run-to-run variance is
+noise, and no amount of prose makes it a signal. It also cannot see **its own blinding**: on a
+machine where a candidate holds terminal access, sibling workspaces, sibling cards and other
+sessions are readable, so blinding is a discipline with a detector rather than a property. And
+the runner is not shipped — with no record, this skill is a procedure, not a measurement.

package/skills/goblin-feature/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: goblin-feature
+description: P3: SPEC first, then land the feature in units that each end checkable.
+---
+
+# goblin-feature (P3)
+
+1. **SPEC first.** A `*-SPEC.md` with a measured root cause and an `AC:` list, committed with
+   or before the code. No code moves until it exists.
+2. **Name the data shape before the code.** The shape decided late is the shape that gets
+   rewritten.
+3. **Land it in units that each end checkable.** Each unit ends with a measurement, not with
+   "and now the next part".
+4. **Write the SHA it landed at into the review note** (`goblin-pr-gate`, P7). "The reviewer
+   approved this" is a claim about a moment until it names a commit.
+
+## Verification
+
+- Every `AC:` item has a checkable assertion: a backticked command, or a comparison operator.
+- The round reports one line of measured numbers.
+- The commit SHA is named.
+
+## What this cannot see
+
+Whether the feature was the right thing to build. That is the SPEC's job, and it is a human's
+decision.

package/skills/goblin-feature-map/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: goblin-feature-map
+description: The feature map - a per-project inventory of every user-facing feature, its entry points and the exact command that drives each one. Use when a project needs a map an agent can read cold, when a map's index or entry paths have drifted from the app, or when a verification skill must state which features it covers (P6 authors the map; FM-01/FM-02 keep it honest).
+---
+
+# goblin-feature-map
+
+A **feature map** is a directory of small files, one per user-facing feature, written for the
+next agent rather than for a human: it is read cold, mid-task, by an agent that has never seen
+the app. It answers "how do I reach this behaviour, with what command, and what should I see" —
+without re-deriving entry points from source every session.
+
+**It is an inventory, not a proof.** A complete map with every feature driven proves the features
+behave *as described*; it proves nothing about whether the app is correct.
+
+## Where it lives, and who declares it
+
+The map's location is **declared, never inferred**: `.goblin/goblin.yaml` holds
+
+```
+feature_map: <path to the map README, relative to the repo>   # empty -> FM-01/FM-02 SKIP
+source_root: .                                                # entry paths resolve against this
+verify_doctor: ""                                             # empty -> VA-01 SKIP
+```
+
+An **empty `feature_map:` is the honest state of a project with no map yet** — `FM-01` and
+`FM-02` then SKIP with that reason instead of failing a fresh install. Declaring a path and not
+writing the map is a hole, and is reported as one.
+
+## The README — the index
+
+`features/README.md`, four H2 sections, in this order, and no more:
+
+```
+## Baseline preconditions     how to launch, isolate, seed, health-check
+## Driving conventions         stable-handle rule, literal-command rule, restore rule
+## Proof and skip reporting    what counts as proof; how a skip is reported
+## Features                    one line per feature file: - [Name](./<slug>.md) covers ...
+```
+
+The `## Features` list is the index. **Every `features/*.md` file must appear in it, in the
+`](./<slug>.md)` form, and every relative link must resolve** (`FM-01`). The README's own
+sections are prose: no check reads them, so nothing here pretends they are enforced.
+
+## Each feature file — the entry contract
+
+`features/<slug>.md`: frontmatter, then **exactly four H2s, in this order**.
+
+```
+---
+feature: <slug>            # must equal the filename stem
+entry_paths:               # >=1 single-token strings; each must still occur under source_root
+  - <route-or-path-token>
+verified: <YYYY-MM-DD>     # the date a human or an audit last drove this feature
+---
+# <Feature name>
+<one paragraph, user-visible behaviour, no implementation detail>
+
+## Sub-features
+- `<id>` <one line>
+
+## How to get to it (user POV)
+- one bullet per entry point
+
+## Driving it with <harness>
+Preconditions: <what must be true first>
+**<action>.** Run `<exact command>`. <observable result>
+
+## Gotchas
+- traps that waste or invalidate a run
+```
+
+`<harness>` is this project's own — a browser driver, a CLI, a test runner. Keep an entry path a
+**single token** (a route, a file path, a CLI flag) that occurs verbatim under `source_root`,
+because that is what `FM-02` greps for. Pair every user action with an **exact command** and an
+**observable result**, or the entry is not drivable and belongs in `## Gotchas`.
+
+## What makes it rot, and what keeps it honest
+
+| rot | what it looks like | what catches it |
+|---|---|---|
+| index rot | a feature file added or deleted, README not updated | `FM-01`: every feature file linked, every link resolves |
+| contract rot | a section renamed, a fifth H2 added, the four reordered | `FM-01`: the four H2s, in order, exactly |
+| entry-point rot | a route renamed, a flag changed — the recipe drives a dead path | `FM-02`: every `entry_paths:` token still occurs under `source_root:` |
+| staleness | the app changed after the map was written; the recipe "works" by luck | `FM-02`: no entry path's file may have a commit newer than the feature's `verified:` date |
+| coverage rot | a proof drives one convenient entry point while the map lists three | **not mechanically checkable** — see "what this cannot see" |
+| implementation creep | the map freezes internals meant to be runtime discoveries | contract only; resist it in review |
+
+**`FM-02` is a tripwire, not a proof.** `git log` sees a *file* change, not a *behaviour* change:
+a refactor touching the file without changing the route reports stale-and-wrong, and a behaviour
+change in a file the token does not appear in is missed. It can be RED-when-stale; it can never
+mean "verified fresh". A `verified:` date is a **claim**, and nothing distinguishes "driven
+yesterday" from "dated yesterday".
+
+## Upkeep — the pass that keeps a map alive
+
+A map rots the moment the app changes, so it needs a periodic pass, not a one-time write. One
+person (or one agent) per pass, in this order, with an edit scope limited to the map's own
+directory:
+
+1. **Index hygiene.** Run `goblin-verify --only FM-01` and fix the index and the four-H2
+   contract.
+2. **Source wave.** One read-only subagent (or one focused read) per feature file, launched
+   concurrently: it reads the app and reports what the file now gets wrong. **Children never
+   drive and never edit.**
+3. **Reconcile.** Apply only the corrections the source wave proved; a correction the subagent
+   could not evidence is left alone and named.
+4. **Live pass.** Drive every feature at least once, with the command in the file. Run the
+   project's declared doctor (`verify_doctor:`, enforced by `VA-01`) before the first drive and
+   after any failed one. A feature that cannot be reached is *verified-unreachable* only with the
+   concrete prerequisite and the route attempted — never reported as verified through another
+   path.
+5. **Triage.** Sort findings into **doc drift** (the map was wrong), **harness gap** (the map was
+   right and the check did not exist) and **product gap** (the app is wrong). Doc drift and
+   harness gaps ship; a product gap is reported and kept out of the map's change.
+6. **One pull request of proven corrections**, re-reading every changed file first, and advance
+   `verified:` only for features actually driven. The outcome is one of `clean` / `changed` /
+   `blocked`, stated in writing.
+
+## The commands
+
+```
+goblin-verify --only FM-01     # the index and the four-H2 entry contract
+goblin-verify --only FM-02     # every entry path still resolves; no entry path changed after verified:
+goblin-verify --only VA-01     # the declared verify_doctor: exits 0
+```
+
+## What this cannot see
+
+- **A feature nobody listed.** The map is a list; whether the list is complete needs semantic
+  judgement over the app, and no command in this repo answers it. That is why it is a note here
+  and not a row.
+- **Whether a recipe drives the *right* path rather than a convenient one.** The map lists entry
+  points; the driver still chooses.
+- **Whether a `verified:` date means anything.** The row proves the entry path still exists; it
+  cannot tell a feature driven yesterday from a date typed yesterday.
+- **A defect the project's own assertions do not cover.** That is the mutation pass's job, not the
+  map's.
+- **Behaviour changes that leave the file alone.** `FM-02` watches files, and a behaviour can
+  change without one.

package/skills/goblin-handoff/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: goblin-handoff
+description: P9: write or pick up a HANDOFF - state, gates, next steps, and what is NOT verified.
+---
+
+# goblin-handoff (P9)
+
+Use when ending a session, or picking up another's.
+
+1. **Commit uncommitted edits** as one internally consistent `wip:` commit. A run that dies
+   must lose nothing.
+2. **Write intent / verified state / next steps / what is NOT verified.** The last one is the
+   most important and the most often skipped.
+3. **Stale sentences get a dated parenthetical, never deletion.** Deleting erases the fact
+   that it was once believed true; leaving it undated re-arms the trap.
+4. **On pickup, verify inherited claims against the artifact.** A passing prior self-report is
+   not the proof. Re-run the gate, check the file exists, grep the vault.
+
+## Verification
+
+- Every gate number in the HANDOFF carries `measured <date>`.
+- The named HEAD matches `git rev-parse --short HEAD`.
+- The NOT-verified section is non-empty, or explicitly says "nothing outstanding".
+
+## What this cannot see
+
+Whether the prose is true. A HANDOFF's own top blocks drift out of sync with its body — grep
+the whole file for a status before planning from the first hit.

package/skills/goblin-investigation/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: goblin-investigation
+description: P1: answer a read-only question with cited evidence, or mark it unverified.
+---
+
+# goblin-investigation (P1)
+
+For a read-only question, or "why is this happening". **No code changes.**
+
+1. **Name the question as a falsifiable claim.** "The board writes to the wrong path" is a
+   claim; "the board is broken" is not.
+2. **Read the code paths and cite `file:line`.** A claim with no anchor is a rumour.
+3. **If the answer is observable by running something, run it instead of asking.** A question
+   whose answer is a fact a command can print is not the human's to answer. This is the whole
+   classifier: *observable by running* -> run it; *a preference or a decision* -> ask.
+4. **Write the answer with its evidence.** Command and real output, or `file:line`.
+
+## Verification
+
+- Every claim carries a `file:line` or a command plus its output.
+- No file is modified. Prove it: `git status --short` is unchanged from before the pass.
+- Anything you could not source is marked `[unverified]`. There is no third state.
+
+## What this cannot see
+
+Intent, and anything outside the repo — a service that is down, a decision not written down.

package/skills/goblin-judge/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: goblin-judge
+description: role-judge: decide whether a process met its own predicate, from a command's output and a pointer it can resolve - never from a report.
+---
+
+# goblin-judge (role-judge)
+
+A **reviewer inspects an artifact**. A **judge decides whether a process met its own predicate**.
+Different input, different output, different failure mode, which is why the judge is a role of its
+own and not a sentence inside another playbook.
+
+| | reviewer (`role-review-panel`) | judge (`role-judge`) |
+|---|---|---|
+| input | an artifact: a diff at a SHA, a file, a spec | a **predicate** plus the evidence the predicate produced |
+| question | "is this artifact right?" | "did the process meet the condition it declared?" |
+| output | findings, categorised (act / consider / noted / dismissed) | a verdict from a **closed enum**, plus the handle it rests on |
+| may accept | the artifact itself, at a named revision | only what the verdict can be re-derived from |
+| failure mode | misses a defect, or bikesheds | **says yes** - a judge that has never returned "not done" |
+| retry | re-review, possibly by another lane | re-run the *same* predicate on the recorded evidence |
+| relation to the author | may be a sibling lane | **not the author, and not the author's profile** |
+
+A reviewer's verdict is an opinion attached to a SHA, and a new head voids it. A judge's verdict
+is a decision about a **process**, so it is honest only when it is reproducible from a record and
+useful only when it can say **no**.
+
+## What it receives
+
+- **A predicate** - one shell command, the loop's declared exit condition. Never a rubric.
+- **Evidence** - a pointer the repo can resolve: `sha:<hex>` (a commit), `file:<path>`, or
+  `sha256:<hex>` (a file's digest). **Never the author's prose.** The single most common failure
+  of a judging loop is that its only input is the worker's own summary; the prompt can demand
+  evidence and still be handed a self-report.
+- The **budget** and the iteration rows, so it can see what the loop has already tried.
+
+## What it outputs
+
+One verdict, from a closed enum: **`done` | `blocked` | `continue` | wait** - plus, in this repo's
+record, the **handle** the verdict rests on. `done` may only cite a handle the repo resolves.
+Anything else is a claim.
+
+## What it must refuse
+
+- **A self-report as evidence.** A summary is not a handle. If the only thing offered is prose,
+  the verdict is `continue`, not `done`.
+- **Grading its own family.** The judge's profile set must be disjoint from the author's
+  (`JG-02`). A judge drawn from the same lane as the author is the author.
+- **Ruling a goal done to unblock itself.** `blocked` blocks; it is never a completion. A
+  judged-done-but-unfinalised loop gets one nudge, then a block - never a completion.
+
+## Where the judge is called
+
+1. **P10 `goblin-overnight`** - the exit predicate.
+2. **P12 `goblin-eval`** - the rubric, graded from the transcript chain.
+3. **P7 `goblin-pr-gate` at S3+** - the panel's *foreman*: N lane verdicts are opinions, one
+   judge turns them into a decision. A panel is N opinions; a judge is one decision.
+4. **The terminal handoff gate** - the card is judged *before* it is marked done.
+5. **An automation's "did the fix land"** - the repro fails before, passes after, twice.
+
+## How a verdict is recorded
+
+One row per iteration in `.goblin/loop/decisions.tsv` (the decision-log shape pstack already
+uses): `ts · phase · decision · why · evidence · result`, where `decision` is `verdict:<one of the
+enum>` and `evidence` is a handle. `JG-01` reads it; `JG-03` counts it. On the board, the same
+turn also leaves one line in the worker log, which is a UI surface - the committed row is what a
+later reader can re-derive from.
+
+## What this cannot see
+
+- Whether a **resolvable handle supports the verdict** it is attached to. `JG-01` proves a commit
+  or a file exists; a judge may cite a real commit that has nothing to do with the claim.
+- **Which lane actually produced a verdict.** No repo-local file observes which profile ran;
+  `JG-02` checks that the *declared* lanes are disjoint, not that a judge ran on one.
+- Whether a lane that has always said yes is **bad**, from one repo's rows (`JG-03`, counted).
+- Whether the predicate was the **right** one. The judge measures what it was told to measure.

package/skills/goblin-loop/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: goblin-loop
+description: Arm, pin, run and close one unattended loop whose exit condition is a command - and stop when it stops making progress.
+---
+
+# goblin-loop (the loop contract)
+
+A **loop** is an unattended run whose exit condition is a **command**. One run, one record:
+`.goblin/loop/`, committed, so a reader tomorrow can re-derive every decision. An unrecorded loop
+is a story.
+
+## 1. Arm it: the predicate comes first
+
+Write the exit condition as **one** shell command in `.goblin/loop/predicate`, and **run it once
+before iteration 1**:
+
+    .goblin/loop/predicate       # one command; exits 0 == the loop is finished
+    .goblin/loop/predicate.sha256  # its digest, recorded at loop start
+    .goblin/loop/first-run       # exit=<n> ts=<ISO8601>, from that first run
+    .goblin/loop/budget          # the turn budget this run declares
+
+A **duration is not a finish condition.** Neither is a description of one. The run-once rule is
+not ceremony: it is the only way to know the command is runnable *and currently red*, which is
+what makes a later green mean anything.
+
+`.goblin/loop/budget` is capped by `loop_max_turns_ceiling` in `.goblin/goblin.yaml` (default
+**20**). The number is not invented: 20 is the engine's own default turn budget for a kanban goal
+loop, and a ceiling that disagreed with the engine would be a number someone made up.
+
+## 2. Pin it: never relax
+
+The predicate's digest is recorded at loop start (`LP-02`). Changing it mid-loop is **not an
+edit** - it is closing this loop and opening another:
+
+    .goblin/loop/closed-<date>/   # the relaxed predicate AND its pin go here, committed
+    # then re-record predicate.sha256 with a `previous: <archived digest>` line beside the new one
+
+The chain is what the row checks: a silent relaxation fails, a recorded re-scope costs one line.
+Whether the new predicate is *weaker* is not decidable from a digest and is recorded in
+`docs/LIMITS.md` #39 rather than claimed.
+
+The pin never updates itself, for the same reason `practice_sha256:` never re-pins itself: a
+self-updating pin is the silent edit it exists to catch. The remedy is printed when the row fails
+and is never automatic.
+
+## 3. Log every iteration
+
+One row per iteration, appended to `.goblin/loop/decisions.tsv` - the decision-log shape, unchanged
+from the template:
+
+    ts · phase · decision · why · evidence · result
+    decision = "verdict:<done|blocked|continue|wait>"
+    evidence = a pointer that resolves: sha:<hex> | file:<path> | sha256:<hex>
+    result   = "predicate:red" | "predicate:green" | "parked" | "stuck"
+
+`evidence` is the thing a judge's verdict rests on. A `verdict:done` row that cites nothing
+resolvable is refused by `JG-01`: the verdict may only rest on a handle the repo can re-derive.
+
+## 4. Guard rails - what stops a night being burned
+
+- **No progress stops the loop.** Three consecutive verdict rows with an **unchanged evidence
+  pointer** and a result that is not `predicate:green` is a failure (`LP-04`). What it measures
+  is a *changed pointer*, a proxy for progress, not progress itself - a loop that edits a file
+  each turn to keep the pointer moving is not caught.
+- **The check cannot be weakened.** The predicate is pinned by digest (`LP-02`); the budget is
+  declared and capped (`LP-03`); and a card's own predicate cannot be edited by its worker at all,
+  which is why the file predicate needs the pin and the card predicate does not.
+- **A stuck loop writes up and stops.** A run whose last row is not `predicate:green` carries
+  `.goblin/loop/stuck.md`: at least three non-blank lines naming the predicate it failed
+  (`LP-05`). The exit a worker can actually reach is `kanban_block` - naming the predicate - plus
+  the write-up. Thrashing is not an option the record allows.
+
+## 5. The morning audit
+
+Read the rows whose `result` is not `predicate:green`, **in order**, then the last five rows for
+context. That is the same discipline as P10's "read the Attention section first": the interesting
+rows are the ones that did not reach the goal, and a green summary line is not one of them.
+
+## What this cannot see
+
+- **Whether the predicate was the right one.** Every `LP-` row checks the process; a loop can run
+  perfectly against a predicate that measures the wrong thing - and a predicate that was
+  **vacuously true from the start** (a `grep -c` against a renamed directory exits 1, passes
+  `LP-01` and `LP-02`, and ends green on nothing) is the failure mode the run-once rule exists to
+  make visible to a human, not one a row can catch.
+- **Whether the recorded `exit=` was measured or typed**, and whether the loop really ran - the
+  record proves a date and a code exist, not that a command produced them.
+- **Cost.** A turn budget bounds turns, not tokens, and the record prices nothing.