create-agent-rig 0.2.0 → 0.3.1

package/templates/agent-os/universal/.claude/skills/loop/SKILL.md

@@ -1,45 +1,302 @@
 ---
 name: loop
-description: The unattended work driver. Runs the Agent queue from PLAN.md task by task under the autonomy rules, journals progress, and ends the session when the queue is empty — never inventing work.
+description: The unattended work driver. Picks the next queue item through the queue adapter, runs it under the autonomy rules, journals at checkpoints, and ends the session on a stated stop condition — never inventing work. Use at the start of every autonomous run and between tasks.
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash, Task
 argument-hint: [max-tasks]
 ---
 
-You drive an unattended session. Work comes from one place only: the **Agent
-queue** in `PLAN.md`. The autonomy tiers and stop rules
-(`.claude/rules/autonomy.md`) govern every step; this skill adds the
-loop-level protocol around them.
-
-## The loop
-
-1. **Read `PLAN.md`.** If the Agent queue is empty → write a journal line
-   ("queue empty, session ended") and **end the session. Do not invent work:**
-   no unbidden refactors, no speculative polish, no "improvements". An empty
-   queue is a completed state, not a vacuum to fill.
-2. **Take the top task.** Judge its tier first: Tier 2 territory → move it to
-   the **Operator queue** with a short plan (what, why, risk, rollback) and
-   take the next task instead.
-3. **Do the work** under the standing rules: failing test first, gates before
-   any PR (`pr-ship`), boundaries enforced by the hooks.
-4. **Close the task:** remove it from the queue, add one journal line (what
-   moved, what it touched, any follow-up created — follow-ups go into a
-   queue, never into ad-hoc scope creep).
-5. Repeat from 1, within `max-tasks` if given.
-
-## Loop-level stop conditions (distinct from per-task ones)
-
-Stop the session — with the journal updated and a short diagnosis — when:
-
-- the Agent queue is empty (the normal, successful end);
-- **two consecutive tasks** ended in a per-task stop (N-strike, invariant
-  conflict, surprise scope) — the queue itself is probably mis-scoped; that
-  is operator information, not something to push through;
-- your context has degraded or files changed under you (the session-staleness
-  rule): write the summary, end, let a fresh session continue;
-- `max-tasks` is reached.
-
-## Journal discipline
-
-One line per event in the `Journal` section of `PLAN.md`, newest first,
-**stateless in form** (no timestamps needed — order carries the sequence).
-Prune freely: the journal is operational memory, not an archive that only
-grows.
+You drive an unattended session. `.claude/rules/autonomy.md` sets the behaviour
+boundaries; the **queue** holds the work; `PLAN.md` holds state, standing
+decisions and the journal. This skill is the driver in between: what gets picked,
+what keeps the loop going, what stops it, and where the report goes.
+
+Per-task procedure is unchanged: (worktree if another session may run) → failing
+test first → implement → `pr-ship` → merge on the named criterion → verify the
+deployed surface if one changed.
+
+## 0. The queue is behind an adapter
+
+Selection never reads a tracker directly. It goes through
+`.claude/scripts/queue/index.mjs`, which resolves the adapter named in
+`.claude/queue.json`:
+
+```bash
+node .claude/scripts/queue/index.mjs next      # the item to take, and why the rest were skipped
+node .claude/scripts/queue/index.mjs next --json
+node .claude/scripts/queue/index.mjs hygiene   # stale labels, link anomalies
+```
+
+- **`plan-md`** (default) — the Agent queue in `PLAN.md`. The only adapter that
+  works in a freshly generated project. Its limit is real and stated in the
+  adapter: a flat list carries **no dependency links**, so the blocker filter is
+  absent rather than satisfied.
+- **`github-issues`** — the upgrade once the project has a remote. Per-item state,
+  a comment thread, and dependencies written as `Blocked by #7` in the body.
+- **`jira`** — for a team that already lives there. Native issue links, so the
+  dependency needs no convention. Credentials come from the environment
+  (`JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN`) and never from a file in the
+  repo; the project or the JQL goes in `.claude/queue.json`.
+
+Adding a fourth is an adapter, not a rewrite: `core.mjs` holds every selection
+decision and each adapter only maps its tracker's records onto the neutral shape.
+
+🔴 **If the queue cannot be read, stop the run and say so.** Never fall back to
+memory, to a stale copy, or to "what I remember was next". A remembered queue is
+how a loop works items that no longer exist, and it is exactly the rot the
+state-vs-queue split exists to prevent.
+
+## 1. Preflight — once, before the first task
+
+```bash
+node .claude/scripts/preflight.mjs
+```
+
+Three items are scripted (kill switch absent · local default branch matches the
+remote · the last deploy concluded successfully) and the script **prints the ones
+it did not check, every time**. Paste the block into the journal: a checklist that
+leaves no record cannot tell you it was skipped.
+
+Verdicts: **STOP** → do not start, deal with the cause. **CAUTION** → start,
+knowing which ground is soft. **GO** → the scripted three are clean; the rest are
+still yours.
+
+**An `unknown` never becomes a `pass`.** A probe that could not run tells you
+nothing.
+
+**First-ever run: attended and short** — one normal item, owner watching. Go
+unattended only after the escalation path and the post-deploy verdict have each
+been seen working at least once.
+
+## 2. Selection — filters in order, then the sort
+
+The queue is queried **fresh before every task**, never from a cached list: the
+loop itself closes items and unblocks their dependents, so a list read at the
+start of the run is wrong by the second task. Re-resolve after every close.
+
+The filters, in order, are implemented in `.claude/scripts/queue/core.mjs` — read
+them there rather than re-deriving them here. Two of them are load-bearing enough
+to restate:
+
+🔴 **Blockers resolve from links, never from labels.** A `ready`/`blocked` label is
+a hand-maintained snapshot; the links are the dependency. Nothing updates a
+dependent's label when its blocker lands — and in continuous mode the loop is what
+landed it. A label-driven loop stalls on work it just unblocked itself, and takes
+work whose blocker is still open. Both directions happen. Stale labels are
+**reported as queue hygiene, never silently corrected**: quietly fixing the
+metadata destroys the evidence that the metadata is unreliable.
+
+🔴 **A missing trigger marker means unconditional, not missing data.** Work that is
+genuinely conditional says so. A `trigger-human` item — a "security pass", a
+"window", "user demand" without a named metric — is **never self-taken**; the human
+hands it over explicitly. A `trigger-auto` item needs its trigger verified *this
+run*: unverified is not fired, and rationalising a trigger into firing builds for
+scale that does not exist.
+
+**The elevated tier is rationed by spacing, not by counting** — a per-run count is
+meaningless when the run has no end. Never two elevated items back to back: land a
+normal item on a healthy runtime in between. One unreviewed permissions or schema
+change is recoverable; a chain of them compounding overnight is not.
+
+**The tier marker is a pre-filter, not the authority.** If an item passed as normal
+and the work turns out to touch an elevated path (`CLAUDE.md` →
+`elevated-paths`), run the gate anyway, record the verdict on the PR, and treat it
+as this run's elevated item for spacing.
+
+## 3. What keeps the loop running, and what stops it
+
+Per-task stops (three strikes, attempt budget, invariant conflict, a blocking
+reviewer verdict) **do not end the run**: escalate that item (§5) and take the
+next one.
+
+The run-level conditions are in `stopConditionOf` in `core.mjs`, checked in
+severity order: **queue unreadable** · **runtime regression** · **kill switch** ·
+**two escalations in a row** · **budget** · **queue empty**.
+
+Three of them deserve their reasons repeated:
+
+- **Runtime regression** → deploy the revert first, diagnose second, start no new
+  work on top. A regression compounds into everything built above it.
+- **Two escalations in a row** → stop. If two consecutive tasks hit walls, the
+  third likely will too: the wall is systemic, not task-local. This is the main
+  guard against grinding a broken assumption for hours.
+- **Queue empty after the filters** → **stop; do not invent work.** No refactoring
+  sprees, no polish, no pre-emptive optimisation. An empty filtered queue is a
+  legitimate, successful end of session; refilling it is the owner's job.
+  **Expect this to be the most common ending** — the queue is finite and the loop
+  drains it. That is the system working.
+
+🔴 **The kill switch is a real file, not an intention:**
+
+```bash
+touch ~/.claude/__PROJECT_NAME__-loop-STOP     # brake on
+rm    ~/.claude/__PROJECT_NAME__-loop-STOP     # brake off
+```
+
+While it exists, `guard-bash.mjs` **denies the merge at the tool layer**, so
+nothing lands even if this file is never read. Everything else stays allowed on
+purpose: finish the current task, push the branch, open the PR, write the journal,
+stop. Losing in-flight work is not what stopping cleanly means. Check for the flag
+between tasks rather than waiting to be denied.
+
+## 4. Budget — a rate, not a task count
+
+There is no "max N tasks" ceiling by default; the bound is **cost per run or per
+rolling day**, declared at the start. Meter it **before** picking the next task,
+not after. If the remaining allowance cannot plausibly fit the next task's size,
+stop now rather than starting something that will be abandoned half-done.
+
+The journal's `cost` block carries only what the session **observes**: reviewer
+subagents run, CI runs consumed (re-runs included — the cheapest signal that a task
+fought its tests), deploys triggered.
+
+⚠ **There is deliberately no token or currency column.** The harness does not
+reliably expose per-subagent accounting to the agent, and a plausible number in a
+cost column **will be believed** — by the next reader, and by the next run
+reasoning about its own budget. A field the loop cannot observe stays **visibly
+empty, never estimated.**
+
+## 5. Every task carries an outcome state
+
+The stop conditions say why the loop stopped. None of them says whether what it
+produced is trustworthy, and those are different questions — a run can stop for a
+perfectly good reason having produced something nobody should build on.
+
+| State | Means |
+| --- | --- |
+| `clean-pass` | every stage produced its artifact from its **documented inputs**; checks green; the deployed surface healthy where one changed |
+| `documented-stall` | it stopped at a real wall, and the diagnosis names **which stage needed what, and which upstream stage should have supplied it** |
+| `incomplete` | it stopped and the record does not explain where or why |
+
+🔴 **`documented-stall` is a success, and reading it as a failure is how this stops
+working.** A stall that names its under-supply is the most useful thing an
+unattended run produces: it converts a vague gap into a located, fixable defect.
+`incomplete` is the only failing state — and it fails on the **record**, not the
+outcome. A task that shipped nothing but explained exactly where it hit the wall
+did better work than one that shipped something nobody can retrace.
+
+### 5.1 The no-hand-feeding rule
+
+> **When a stage asks for context an earlier stage should have supplied, do not
+> answer it with new facts.** Record what it needed and which stage should have
+> carried it, then either continue from the documented inputs plus a **labelled
+> assumption**, or stop. **The stall is the finding.**
+
+An unattended run is structurally biased the other way: a later stage asks for
+something nobody supplied, the driver answers from its own head because it happens
+to know, and the line keeps moving. The output looks clean and is fiction —
+assembled from context no documented input contains and no reader can retrace.
+
+Two corollaries, because they are the ones rationalised away mid-run:
+
+- **A stage that finishes without producing its named artifact is an under-supply
+  finding, not a retry.** Never rerun it until the output looks clean — that is
+  re-running CI until it goes green, one level up.
+- **"I already know this" is the signal, not the exemption.** The question is not
+  whether the fact is true; it is whether the pipeline supplied it. A true fact
+  injected by hand still leaves the next run starving in the same place.
+
+⚠ **Known limit, documented rather than trusted:** both halves rely on the run
+reporting on itself, and hand-feeding is ordinary helpful completion rather than a
+deliberate act a model catches itself performing. A stated rule still shifts
+behaviour and costs nothing per run — but it is precisely why the one status that
+mechanises fully (`missed`, `.claude/rules/autonomy.md`) needs no self-report.
+
+## 6. Escalation — two channels, by scope
+
+**Task-scoped — the item is the home, and the loop continues.** Three strikes, the
+attempt budget, an invariant conflict, or a blocking reviewer verdict:
+
+1. Comment the diagnosis on the queue item: what fails, what was tried, the
+   current hypothesis, links to the PR and the failing run. **Name the outcome
+   state in the same comment** — `incomplete` if the diagnosis cannot say which
+   stage needed what. Writing `incomplete` on your own task is uncomfortable and
+   is the point: the run that produced it is the only witness.
+2. Mark it `escalated` and leave it claimed — **not** back to a selectable state,
+   or the next query picks it up and works it twice.
+3. Journal it. 4. **Take the next item.** One stuck task does not end a run; two
+   in a row does (§3).
+
+**Run-scoped — the run itself is broken, and it ends.** A runtime regression, two
+escalations in a row, a systemic wall, a queue-data anomaly: open an escalation
+issue with the diagnosis and links, notify the owner if the harness can, and write
+the journal entry. In continuous mode the notification matters more than it does
+in a bounded run — nobody is watching, so a silent stop is indistinguishable from
+a run still working.
+
+## 7. The journal, and closing the loop
+
+Write a checkpoint entry **every few completed items and at every stop**, not only
+at the end: a run that dies unexpectedly must not take its history with it. The
+field list is in `PLAN.md` under `## Journal`.
+
+At every **stop** — not at a checkpoint — turn the run's findings into **at most
+three** improvement proposals. **The cap is the mechanism, not a budget:** an
+unbounded improvement list is another diary, and three forces a choice. Each names
+four things, and a proposal missing any of them is not ready to file:
+
+1. the finding it came from, cited as the journal line it appears on;
+2. the part to change — a skill, an agent spec, a hook, a rule file, `CLAUDE.md`,
+   the CI workflow;
+3. the change, concretely enough to diff;
+4. how the next run would prove it worked — the observation that would differ.
+
+Filing is the adapter's `proposeTriage`, which the CLI deliberately does **not**
+expose — `index.mjs` is read-only (`next`, `list`, `hygiene`) so that no accidental
+invocation can write to the queue. Call it directly:
+
+```bash
+node --input-type=module -e '
+  const a = await import("./.claude/scripts/queue/plan-md.mjs");   // or github-issues / jira
+  console.log(await a.proposeTriage({
+    finding: "<the journal line it came from>",
+    part:    "<skill | agent | hook | rule | CLAUDE.md | workflow>",
+    change:  "<concretely enough to diff>",
+    proof:   "<the observation that would differ next run>",
+  }));
+'
+```
+
+A proposal missing any of the four parts is refused rather than filed half-formed.
+
+🔴 **The loop proposes; the owner patches.** Self-applying a change to its own
+rulebook is how an unattended run drifts irreversibly, and it collides head-on
+with the rule that the agent authors no work for itself.
+
+🔴 **Proposals land in `triage`, never in the queue the loop selects from.** A
+triage item is unselectable twice over — no ready marker, and `triage` is excluded
+outright. **Deduplicate by fingerprint:** twenty "queue empty" stops must produce
+one proposal with a count of twenty, not twenty proposals. **A stop with nothing
+worth proposing files nothing** — zero is a legitimate number, and padding to
+three poisons the only channel by which this project learns.
+
+## 8. What the loop does NOT do
+
+| Does not | Why |
+| --- | --- |
+| **Create its own work items** | The queue is human-filled. Self-authored work drifts scope, and unattended it drifts unwatched |
+| Take items needing a human decision | It cannot unblock itself; those wait in the Operator queue |
+| Take a `trigger-human` item | It would build for scale that does not exist |
+| Take two elevated items back to back | One unreviewed schema/permissions change is recoverable; a chain overnight is not |
+| Merge past a blocking reviewer verdict | The reviewer gate is what replaced the human merge |
+| Trust a `blocked` label over the links | The label is a snapshot; the links are the dependency |
+| "Improve" on an empty queue | An empty filtered queue is the end of the run, not an invitation |
+| Start new work on an unhealthy runtime | The regression compounds into everything above it |
+| Act on the "Never" tier | A hard stop, enforced by hooks |
+
+## 9. State updates bracket the task, they are not a follow-up
+
+- **Opening:** claim the item **before the first file is edited** — the same turn
+  that creates the branch or worktree. Not when the PR opens. An item being worked
+  while it still reads as available is invisible to the human and re-selectable by
+  the very next query.
+- **Closing:** close it with the merged PR linked, immediately after the
+  post-merge verdict — not in a cleanup pass.
+
+Between those two moments the item keeps absorbing what happens **as it happens** —
+a decision, a deviation, a defect found in passing, a tier discovered mid-work. A
+run that dies mid-task leaves its whole trail on the item; a run that batches its
+comments to the end leaves nothing.
+
+If the task changed a **fact** in `PLAN.md` — a state row, a standing decision, an
+Operator-queue item it unblocked — that edit lands **in the same PR that changed
+the fact**, never a docs-only follow-up.

package/templates/agent-os/universal/.claude/skills/new-invariant/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: new-invariant
+description: Turn a project rule into a mechanically enforced invariant — one stated rule, one PreToolUse hook that blocks its violation, one test for the hook. Use when a rule keeps being broken, when a review finding recurs, or when a post-mortem ends in "nothing stopped us doing that".
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash
+argument-hint: [the invariant, in one sentence]
+---
+
+You add **one** invariant to this project's enforced set, using the pattern in
+`.claude/rules/invariants.md`: a stated rule, a hook that blocks its violation,
+and a test for the hook. All three land in the same change.
+
+## Step 0 — get the invariant from the project, not from your own judgement
+
+🔴 **Do not invent the invariant.** If the argument did not name one, ask. The
+whole point of this layer is that the project chooses what is load-bearing; an
+agent that supplies its own answer has handed the project a rule nobody agreed
+to, and that rule will be obeyed without thought.
+
+Ask for, or find, three things:
+
+1. **The rule, in one sentence**, in the form "X never happens in Y".
+2. **What it cost the last time it was broken.** If nobody can finish that
+   sentence, stop and say so: an invariant with no incident behind it is a guess,
+   and a guessed invariant fires on honest work.
+3. **The compliant form.** What the code should look like instead — you need it
+   for the allow case, and a rule with no stated alternative is a dead end.
+
+Then check the fit against the table in `.claude/rules/invariants.md`. If it
+cannot be decided from a single edit fragment — "this is too complex", "the
+naming is off" — say so and stop: it belongs to `code-reviewer`, a lint rule or a
+type, and forcing it into a hook produces a guard people fight.
+
+Also check it is not already enforced. `grep` the existing hooks first; a second
+guard for the same rule is two places to keep in step.
+
+## Step 1 — write the failing test
+
+TDD is not suspended here (`.claude/rules/workflow.md`). Copy
+`guard-invariant.example.test.mjs` from this skill's directory as the shape, and
+write the cases **before** the hook exists:
+
+- **blocks** the violation — exit code 2, and the reason names the rule;
+- **allows** the compliant form — exit code 0;
+- **allows** a file outside the guarded scope — a guard that polices the whole
+  repo will be disabled by lunchtime;
+- **allows** prose that merely mentions the violation. This case is not optional.
+  A guard that fires on a commit message, a doc line or a test fixture *about* the
+  rule produces **false positives**, and false positives are how guards get
+  switched off. Every real hook in this project strips or scopes text before
+  matching for exactly this reason.
+
+Run it. Watch it fail for the right reason (the hook does not exist yet).
+
+## Step 2 — write the hook
+
+Copy `guard-invariant.example.mjs` from this skill's directory to
+`.claude/hooks/guard-<invariant-name>.mjs` and replace the parts the comments
+mark. Name the file after **the invariant**, never after the tool it intercepts —
+`guard-core-purity`, not `guard-write`.
+
+Hold the contract:
+
+- JSON payload on stdin; **exit 0 = allow, exit 2 = block**; stderr is the reason
+  the agent reads, so write it as an instruction — what to do instead, and where
+  the rule is stated.
+- **Scope first, match second.** Return 0 immediately for files the invariant does
+  not cover.
+- **Fail open** on a malformed payload or any internal error. A crashed guard that
+  blocks everything gets deleted within the hour.
+- Zero dependencies, `node:` builtins only.
+
+Run the test. Make it pass. Do not weaken a case to get there.
+
+## Step 3 — wire it, or it enforces nothing
+
+Add the hook to `.claude/settings.json` under `PreToolUse`, in the block whose
+`matcher` covers the tools the invariant needs (`Write|Edit` for file content,
+`Bash` for commands). An unwired hook is a file that passes its own test and
+guards nothing — verify by triggering the violation once, for real, and watching
+it be refused.
+
+## Step 4 — state the rule where a reader will look
+
+Add the sentence to the relevant file in `.claude/rules/` (or
+`.claude/rules/invariants.md` if it fits nowhere else), next to a line saying
+which hook enforces it and what the hook cannot see. A check with no stated rule
+is a booby trap: someone will hit it, not understand it, and route around it.
+
+## Done when
+
+- [ ] The test failed before the hook existed, and passes now
+- [ ] The violation is refused in a real session, not only in the test
+- [ ] The hook is wired in `settings.json`
+- [ ] The rule is written down, with the hook named next to it
+- [ ] The hook guards **one** invariant, and its scope is as narrow as the rule
+
+## A candidate that is already sitting there
+
+The stack rules say service code logs through the shared structured logger, never
+`console.log` — and nothing enforces it. That is the invariant the shipped example
+encodes, so if the rule matters in your project, promoting the example into a real
+hook is a copy, a rename and a wiring line.

package/templates/agent-os/universal/.claude/skills/new-invariant/guard-invariant.example.mjs

@@ -0,0 +1,78 @@
+// TEMPLATE — copy to .claude/hooks/guard-<invariant-name>.mjs and edit the three
+// marked parts. It is real, working code, not a sketch: the `new-invariant` skill
+// tests it, so what you copy is known to work before you change anything.
+//
+// The invariant it encodes as the example:
+//
+//   Service code logs through the shared structured logger, never `console.log`.
+//
+// That one is a genuine candidate — the stack rules state it and nothing enforces
+// it — but it is here to show the SHAPE. Replace it with your project's invariant.
+//
+// Contract (Claude Code): JSON payload on stdin; exit 0 = allow, exit 2 = block,
+// and stderr is shown to the agent as the reason. Zero dependencies.
+import { readFileSync } from 'node:fs';
+
+// ── PART 1: the scope ────────────────────────────────────────────────────────
+// Which files the invariant covers. Scope FIRST, match second: a guard that
+// polices the whole repo fires on honest work and gets switched off by lunchtime.
+const inScope = (filePath) => /^services\/[^/]+\/src\//.test(filePath);
+
+// ── PART 2: the violation ────────────────────────────────────────────────────
+// What the invariant forbids, decided from the text of THIS edit alone.
+// Return a reason string, or null to allow.
+const violation = (text) => {
+  // Strip line comments and string literals before matching: a doc line or a
+  // fixture that merely MENTIONS the forbidden form is prose, not a violation.
+  // Skipping this step is the single most common way a guard earns false
+  // positives — and false positives are how guards get disabled.
+  const code = text
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')
+    .replace(/(^|[^:])\/\/.*$/gm, '$1')
+    .replace(/`(?:[^`\\]|\\.)*`|"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'/g, '""');
+
+  const match = /\bconsole\.(log|info|warn|error|debug)\s*\(/.exec(code);
+  if (!match) return null;
+  return (
+    `BLOCKED — service code logs through the shared structured logger, never ` +
+    `console.${match[1]}(). Structured JSON lines are what makes a production ` +
+    `incident searchable; a bare console call is invisible the moment it matters. ` +
+    `Import the logger from the shared package instead. See .claude/rules/ for the rule.`
+  );
+};
+
+// ── PART 3: nothing below here normally changes ──────────────────────────────
+
+/** The text an edit is about to introduce, across the tool shapes that carry one. */
+const incomingText = (toolInput) =>
+  [toolInput?.content, toolInput?.new_string, toolInput?.new_str]
+    .filter((value) => typeof value === 'string')
+    .join('\n');
+
+function main() {
+  let input;
+  try {
+    input = JSON.parse(readFileSync(0, 'utf8'));
+  } catch {
+    return 0; // malformed payload → fail open, never make the session unusable
+  }
+
+  const filePath = String(input?.tool_input?.file_path ?? '').replaceAll('\\', '/');
+  if (!filePath || !inScope(filePath)) return 0;
+
+  const text = incomingText(input?.tool_input);
+  if (!text) return 0;
+
+  try {
+    const reason = violation(text);
+    if (reason) {
+      process.stderr.write(`${reason}\n`);
+      return 2;
+    }
+  } catch {
+    return 0; // a guard that crashes must not block the work
+  }
+  return 0;
+}
+
+process.exit(main());

package/templates/agent-os/universal/.claude/skills/new-invariant/guard-invariant.example.test.mjs

@@ -0,0 +1,89 @@
+// TEMPLATE — the third of the three parts (.claude/rules/invariants.md).
+//
+// Copy alongside your hook and rewrite the cases for your invariant. Run with:
+//
+//   node --test .claude/hooks/guard-<invariant-name>.test.mjs
+//
+// The four cases below are not a suggestion — they are the minimum set. The last
+// two are the ones people skip, and they are exactly the ones that decide whether
+// the guard survives contact with real work: a guard that polices out-of-scope
+// files, or that fires on prose about its own rule, gets switched off.
+import assert from 'node:assert/strict';
+import { execFile } from 'node:child_process';
+import { describe, it } from 'node:test';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const hook = join(dirname(fileURLToPath(import.meta.url)), 'guard-invariant.example.mjs');
+
+/** Feed a synthetic PreToolUse payload to the hook, exactly as Claude Code does. */
+const runHook = (filePath, content) =>
+  new Promise((resolve, reject) => {
+    const child = execFile(process.execPath, [hook], (error, stdout, stderr) => {
+      resolve({ code: error ? (error.code ?? 1) : 0, stderr });
+    });
+    if (!child.stdin) return reject(new Error('no stdin'));
+    child.stdin.write(
+      JSON.stringify({
+        hook_event_name: 'PreToolUse',
+        tool_name: 'Write',
+        tool_input: { file_path: filePath, content },
+      }),
+    );
+    child.stdin.end();
+  });
+
+const IN_SCOPE = 'services/api/src/handlers/create-note.ts';
+
+describe('the example invariant: service code logs through the shared logger', () => {
+  it('blocks the violation, and the reason names what to do instead', async () => {
+    const result = await runHook(IN_SCOPE, 'console.log("created", id);');
+    assert.equal(result.code, 2);
+    assert.match(result.stderr, /logger/i);
+  });
+
+  it('blocks the other console methods too, not just log', async () => {
+    for (const method of ['info', 'warn', 'error', 'debug']) {
+      const result = await runHook(IN_SCOPE, `console.${method}("x");`);
+      assert.equal(result.code, 2, method);
+    }
+  });
+
+  it('allows the compliant form', async () => {
+    const result = await runHook(IN_SCOPE, 'logger.info({ msg: "created", id });');
+    assert.equal(result.code, 0);
+  });
+
+  it('allows files outside the guarded scope', async () => {
+    // A guard with repo-wide reach fires on honest work and gets disabled.
+    for (const path of ['scripts/one-off.mjs', 'apps/web/src/app/page.tsx', 'README.md']) {
+      const result = await runHook(path, 'console.log("fine here");');
+      assert.equal(result.code, 0, path);
+    }
+  });
+
+  it('allows prose that merely mentions the violation', async () => {
+    // The false-positive case. Skipping it is how a guard ends up switched off.
+    for (const content of [
+      '// never use console.log here — use the logger',
+      '/* console.error is banned in service code */',
+      'const banned = "console.log(";',
+      'const help = `do not call console.warn(...)`;',
+    ]) {
+      const result = await runHook(IN_SCOPE, content);
+      assert.equal(result.code, 0, content);
+    }
+  });
+
+  it('fails open on a payload it does not understand', async () => {
+    const result = await new Promise((resolve, reject) => {
+      const child = execFile(process.execPath, [hook], (error) => {
+        resolve({ code: error ? (error.code ?? 1) : 0 });
+      });
+      if (!child.stdin) return reject(new Error('no stdin'));
+      child.stdin.write('{not json');
+      child.stdin.end();
+    });
+    assert.equal(result.code, 0);
+  });
+});