@bompus/house-rules 0.0.0-stage → 0.11.0

package/skills/hr-explain-code/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: hr-explain-code
+description: "Explain how existing code works by tracing it from trigger to effect, read-only, so the reader can change it with confidence. Use when the user asks how a part of the codebase works, or wants a walkthrough or trace of a flow. Not for designing new code or critiquing existing code."
+disable-model-invocation: true
+---
+
+# Explain code
+
+The goal is a reader who can open the right files and predict what the code
+will do before they touch it. This skill reads and reports. It edits nothing,
+runs nothing that changes state and offers no verdicts on quality.
+
+## Pin down the question
+
+Restate the question in one or two lines before reading far: which behavior,
+which entry point, and where you will stop. "How does login work?" might mean
+the form submit, the token exchange, session storage or all three. Pick the
+reading that best fits what the user said, say which one you picked, and start.
+Do not wait for confirmation; the user can redirect you.
+
+If the question names something that does not exist in the code, say so early
+and offer the nearest real thing.
+
+## Trace the behavior
+
+Start where the behavior starts: a route, a command, an event handler, a
+scheduled job, a public function. Follow calls forward until you reach the
+effects the question cares about, such as a write, a response, a message sent
+or a value returned.
+
+- Use the project's code search or code index when it has one. It follows
+  calls and dispatch that plain text search misses.
+- Read the code that runs. A function name, a config key or a package
+  description says what someone intended, not what happens. Confirm by
+  reading the body, the call site and the value actually passed.
+- Follow indirection to its target: dependency injection, registries, event
+  buses, plugin loading, dynamic imports, overrides. Name the mechanism when
+  it is the reason the path is hard to see.
+- Separate the normal path from code that exists but is not wired in: dead
+  branches, disabled flags, handlers nobody registers, fallbacks that only
+  fire on a specific error. An exported or configured function not called on
+  the normal path is an optional capability, not a step in that flow.
+- Distinguish a configured provider, an injected adapter, a local stub and a
+  durable service. Name only the runtime role the wiring and code support.
+- For a state change, trace to the line that performs the write and the
+  conditions that permit it. Finding a caller alone does not prove a write.
+- Check configuration and environment that change the path, and say which
+  values you assumed.
+- When you cannot close a gap (generated code, a closed dependency, runtime
+  data you cannot see), write the open question right beside the claim it
+  weakens. Do not collect unknowns in a footnote far from what they affect.
+
+The trace is done when every step from trigger to effect is either read in
+the code or marked unverified at that step.
+
+## Split a large area
+
+When the area is too wide for one careful pass and the host can run helper
+agents, divide it into slices that do not overlap, for example one per
+service, layer or entry point. Give each helper a single slice, read-only
+access and the brief in [`references/helper-brief.md`](references/helper-brief.md).
+Run them in parallel.
+
+Merge the results yourself. Where two slices meet, check that one helper's
+outgoing call matches the other's entry point. Re-read the code for any claim
+that surprises you or that the explanation depends on; a helper's summary is
+a lead, not proof.
+
+## Match depth to the question
+
+A narrow question gets a short answer. "Where is the retry count set?" needs
+a file reference and a sentence, not a tour. A request for a walkthrough of a
+subsystem gets the full shape below.
+
+- Cite files and functions as `path/to/file.ext:function` or with line
+  numbers, so the reader can open each one.
+- Quote code only when the exact line carries the point: an off-by-one
+  boundary, an unusual default, a condition that decides the branch.
+- Choose the smallest view that explains the behavior clearly. Use pseudocode
+  for decisions, a call tree for execution order, or a component/file tree for
+  ownership. Use a diagram for interactions or state transitions when it is
+  clearer than prose. Keep the conditions, side effects and unverified links
+  that affect the answer, with source references beside them.
+
+## Shape the answer
+
+Cover these in whatever order and form suits the question. Skip a part only
+when it has nothing to say.
+
+1. **Purpose.** What the code is for and who or what triggers it.
+2. **Terms.** The few names, types or ideas the reader must know to follow
+   the rest. Three to five is usually enough.
+3. **The flow.** The path from trigger to effect, using prose or the selected
+   view, with a source reference for each step. Explain any assumption or
+   omitted branch that changes the reader's understanding.
+4. **Where to start reading.** The two or three files that repay opening
+   first, and in what order.
+5. **Surprises.** Behavior a careful reader would not expect: side effects,
+   ordering dependencies, silent fallbacks, caching, code that looks live but
+   is not, and history that explains why code looks odd.
+6. **Unverified.** What you could not confirm and what would confirm it,
+   if any of it is not already noted next to its claim.
+
+## Stay descriptive
+
+Describe what the code does, not whether it should. If you notice a likely
+bug, mention it once as a fact with its location and move on. For a critique
+of the design, point to `hr-maintainability-review`. For what a planned change
+would affect, point to `hr-change-impact`. For a failure being chased, point to
+`hr-diagnosing-bugs`.

package/skills/hr-explain-code/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "HR: Explain code"
+  short_description: "Trace how existing code works, read-only"
+policy:
+  allow_implicit_invocation: false

package/skills/hr-explain-code/references/helper-brief.md

@@ -0,0 +1,39 @@
+# Helper brief for one slice
+
+Fill in the bracketed parts and send this to each helper agent.
+
+```text
+You are reading code to help answer: [the user's question, as restated].
+
+Your slice: [service, directory, entry point or layer]. Stay inside it.
+Where the code calls out of your slice, note the call and stop there.
+
+Read only. Do not edit files, run migrations, start services or change
+any state.
+
+Trace behavior by reading code bodies and call sites. Do not infer what
+something does from its name, a config key or a package description.
+Use the project's code search or index if it has one.
+
+Distinguish a configured provider, an injected adapter, a local stub and a
+durable service. Name only the runtime role the wiring and code support.
+An exported or configured function not called on the normal path is an
+optional capability, not a step in that flow. For a state change, trace to
+the line that performs the write and the conditions that permit it.
+Finding a caller alone does not prove a write.
+
+Return:
+1. Entry points into your slice that matter to the question, with file
+   and function.
+2. The path through your slice, step by step, each step with a file and
+   function or line reference.
+3. Calls leaving your slice: what is called, with what, and where.
+4. Code that exists but is not on the normal path (disabled, unregistered,
+   error-only), marked as such.
+5. Anything surprising.
+6. Gaps you could not close, each next to the step it affects, and what
+   would close it.
+7. Every file you read.
+
+Facts only, with references. No suggestions for changes.
+```

package/skills/hr-extract-shared-steps/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: hr-extract-shared-steps
+description: Pull operational steps that several workflows repeat into shared functions with explicit inputs and results, leaving each workflow's own decisions with its caller. Use when the same low-level operation (a provider call, a command run, a message sent, a resource provisioned) appears in two or more callers, when a fix landed in one copy but not the others, or when a new feature needs mechanics an existing flow already has. Not for single-caller logic, naming, or general interface design.
+---
+
+# Extract shared steps
+
+Several workflows often perform the same operation with slightly different
+code around it: one checkout path and one renewal job both charge a card, two
+handlers both run the same CLI command. The copies drift, and a fix applied to
+one leaves the others broken. This skill moves the operation into one shared
+function and leaves every decision about when, whether and what next with the
+workflow that owns it.
+
+## Confirm it applies
+
+Extract when at least one of these is true, and you can point to the lines:
+
+- Two or more callers perform the same low-level operation with the same
+  inputs, calls and error handling, give or take naming.
+- A bug fix or provider change landed in one copy and the others still carry
+  the old behavior.
+- A new feature is about to copy mechanics that an existing flow already has.
+
+Stop and leave the code alone when the logic has one caller, when the copies
+only look alike but encode different product rules, or when the real question
+is naming or how a module's interface should look.
+
+## Draw the line between policy and operation
+
+Go through the repeated code line by line and sort each line with this test:
+would a second caller ever want this line to behave differently? If yes, it is
+policy and stays in the caller. If no, it is part of the operation.
+
+Policy, which stays with each caller:
+
+- who may trigger the action, and any permission or plan checks
+- state transitions on the caller's own records (order paid, subscription past due)
+- which failures reach the user, and the wording they see
+- whether to retry, when, and how many times
+- logging or metrics that name the workflow
+
+Operation, which moves into the shared function:
+
+- building the request, calling the provider or command, parsing the response
+- mapping raw provider errors into a small, stable set of failure kinds
+- anything that must be identical everywhere for correctness, such as an
+  idempotency key format or a required header
+
+## Shape the shared function
+
+- Take everything it needs as parameters: clients, identifiers, amounts,
+  timeouts. It does not reach for globals, request context or configuration
+  on its own.
+- Do not read or write application state or the database inside it. The caller
+  loads what the operation needs and stores what comes back.
+- Return a structured result that makes failure explicit: success with its
+  data, or a failure kind plus the raw detail. Never swallow an error or
+  return a bare `false` the caller cannot interpret.
+- Offer several small operations a caller can combine rather than one entry
+  point with flags for each caller's variant. Two callers needing different
+  steps call different functions.
+- Keep argument order, naming and result shape consistent across sibling
+  operations, so a reader who knows one knows the rest.
+
+Extract only what is repeated today and not specific to one product flow. A
+step only one caller needs stays in that caller, even if it sits next to the
+shared part.
+
+## Example
+
+Checkout charges a card while the customer waits; the renewal job charges
+the same card overnight. Both used to build the provider request inline.
+
+```ts
+type ChargeResult =
+  | { ok: true; chargeId: string }
+  | { ok: false; kind: "declined" | "unavailable" | "invalid"; detail: string };
+
+async function chargeCard(
+  client: PaymentClient,
+  input: {
+    customerRef: string;
+    amountCents: number;
+    currency: string;
+    idempotencyKey: string;
+  },
+): Promise<ChargeResult> {
+  /* request, call, map provider errors to kind */
+}
+
+// Checkout: show declines to the customer, never retry.
+const paid = await chargeCard(client, { ...order.charge, idempotencyKey: order.id });
+if (!paid.ok) return showPaymentError(paid.kind);
+await orders.markPaid(order.id, paid.chargeId);
+
+// Renewal job: retry outages later, mark the subscription past due on decline.
+const renewed = await chargeCard(client, { ...sub.charge, idempotencyKey: `${sub.id}:${period}` });
+if (!renewed.ok && renewed.kind === "unavailable") return scheduleRetry(sub.id);
+if (!renewed.ok) return subs.markPastDue(sub.id, renewed.detail);
+await subs.recordPayment(sub.id, renewed.chargeId);
+```
+
+`chargeCard` knows nothing about orders, subscriptions or retries. Each caller
+decides what a decline means for its own records.
+
+## Migrate in steps
+
+1. Write the shared function from the most complete copy, with tests for its
+   success path and each failure kind. Done when those tests pass.
+2. Switch one caller to it. Done when that caller's tests, the type check and
+   the linter pass, and its observable behavior is unchanged.
+3. Switch the remaining callers one at a time with the same checks. Where the
+   copies differed, decide whether the difference was policy (keep it in that
+   caller) or a bug (fix it, and say so in the change description).
+4. Delete the old inline copies. Done when a search for the old request
+   building or provider call finds only the shared function.
+5. Run the project's full required checks before landing.
+
+## Check the result
+
+Revisit the extraction when any of these appear, now or in later changes:
+
+- The shared function grew a parameter or mode flag that exists for one
+  caller. Move that step back to the caller or split the function.
+- It writes domain state, or reads it to decide what to do. That is policy
+  leaking in; return the data and let the caller act.
+- It has a single caller left. Inline it back unless a second caller is
+  already planned in this change.
+- Callers inspect raw provider errors again instead of the failure kind. The
+  result type is missing a case.
+
+Report what was extracted, which callers moved, any behavior difference you
+found between the copies and how you resolved it, and the checks you ran.

package/skills/hr-extract-shared-steps/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "HR: Extract shared steps"
+  short_description: "Move repeated operations into shared functions"

package/skills/hr-handoff/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: hr-handoff
+description: Create a resumable handoff when the user requests one or the low-quota handoff rule triggers. Do not invoke merely because a conversation is long.
+argument-hint: "What will the next session be used for?"
+disable-model-invocation: false
+---
+
+Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save it outside disposable storage and task worktrees, as § Durable notes in the house rules requires.
+
+Default to `handoffs/<project>/<session>.md` in your notes directory (§ Durable notes), expanding `~` and environment variables to an absolute path. Respect a user-selected persistent location. Create parent directories as needed, choose a unique session name, reuse the file for updates, verify its contents, and report the absolute path. Do not default to temporary directories or caches for resumable handoffs.
+
+For a low-quota handoff (trigger defined by the `low-quota-handoff` modifier), do only what
+is necessary to reach a safe boundary. Do not abandon time-critical duty mid-action. Create the essential
+current state, Git ownership
+and next action first so they survive an interrupted write; then fill in the
+remaining context. Record the triggering bucket, reading source/time and reset
+time when known, and unknown quota/reset information as unknown.
+
+Verify the saved handoff, report its absolute path, and end the turn without
+continuing substantive work, even if tasks were previously authorized; this is the stop
+the house rules' § End of every reply allows for a rule you are following. Only an explicit
+user instruction resumes work, limited to its requested scope; update this same
+handoff and stop again afterward while quota remains low. Do not change
+provider, model or effort without authorization.
+
+For a handoff unrelated to quota, follow the user's requested continuation or
+stop boundary.
+
+Before a handoff unrelated to quota, check the docs this session relied on or
+changed against the current code: repository guidance, READMEs and design docs
+that name the files, commands or behavior the session touched. List each claim
+the code contradicts, with the doc's file and line and the code evidence, and
+propose the smallest fix for each. Edit docs only with the user's approval;
+record unapproved contradictions as open items so the next session doesn't
+trust them. Skip this check for a low-quota handoff.
+
+Preserve, stated exactly and complete even at the cost of length: (1) problems that came up and how they were handled; (2) options raised, tried, or set aside, and why; (3) anything asked for, decided, ruled out, or established as a preference, constraint, or boundary; (4) exactly where things stand now, including any external action started without a recorded result; (5) anything still open, promised, or expected next; (6) details that are hard to reconstruct: names, numbers, dates, exact wording, paths, links. Keep what the user said close to their own words; condense your own reasoning to what it concluded or produced. Everything else stays concise.
+
+Close the loop on remaining work: inventory every current and past item as done,
+open, or deferred, each with its owner and next action, and state whether all
+items are addressed. When the handoff spans several threads or scopes, include
+an integrated plan. Preserve an already-selected next action; record unresolved
+decisions and recommendations in priority order.
+
+For a handoff unrelated to quota, follow
+[reconciliation.md](references/reconciliation.md) to compare the current and
+preceding source transcripts, linked ledgers and Git inventory with this
+inventory. Save its receipt and run the offline checker. Report coverage gaps
+and mechanical results separately from the reviewed claim that all items are
+addressed. Include owned unlanded PRs, dependency PRs and own commits without a
+PR; preserve their owners and landing authority.
+
+At a low-quota stop, save essential state first and record partial coverage
+when feasible. An unfinished receipt or failing check never delays that stop.
+
+Ask what to work on next only when an unresolved decision needs the user's
+input and the handoff's stop boundary permits it. Follow the house rules'
+§ Offers and § Finishing work. When stopping for low quota, the saved handoff and recorded next action serve
+as the offer; do not ask a new selection question.
+
+A session resuming from a handoff re-reads the repository's guidance index,
+meaning its `AGENTS.md` (or configured instruction root) and the rules and docs
+it names. It also checks `git log` on those paths plus the house-rules checkout
+for changes since the handoff was written; an installed or composed copy of
+the rules can lag its source. Boot-injected rules are a snapshot, not proof of
+current text.
+
+Include a **Git** section when the handoff involves repo work:
+
+```markdown
+## Git
+
+- Checkout: <absolute path>; branch or detached HEAD: <verified value>
+- Owns: `path/globs`
+- Do not touch: `<paths other chats own>`
+- Last commit: `<sha> <subject>`
+```
+
+If two chats run in parallel on this repo, owns must not overlap. Prefer one implementation chat at a time.
+
+End your report with a ready-to-paste prompt for the resuming agent inside a
+fenced code block, so the user can copy it into a fresh session verbatim. It
+must name the handoff's absolute path, tell the resuming session to read the
+handoff fully before acting (which itself directs the guidance re-read), and
+state the recorded next action plus any provider or host constraint the user
+gave. Keep it under ten lines; the handoff carries the detail, the prompt only
+points at it.
+
+Redact any sensitive information, such as API keys, passwords, or personally identifiable information.
+
+If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.

package/skills/hr-handoff/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "HR: Handoff"
+  short_description: "Create a resumable handoff"
+policy:
+  allow_implicit_invocation: true

package/skills/hr-handoff/assets/ledger.example.json

@@ -0,0 +1,10 @@
+{
+  "records": [
+    {
+      "id": "deferred-1",
+      "text": "User deferred the evaluation. Resume only after explicit selection.",
+      "at": "2025-01-01T09:00:00Z",
+      "outcome": { "item": "evaluation", "state": "deferred" }
+    }
+  ]
+}

package/skills/hr-handoff/assets/receipt.example.json

@@ -0,0 +1,76 @@
+{
+  "version": 1,
+  "owner": "session-example",
+  "coverage": "complete",
+  "sources": [
+    {
+      "id": "current",
+      "file": "source.example.json",
+      "snapshot": "Fictional session records through 2025-01-01T10:01:00Z",
+      "expectedRecords": 3,
+      "gaps": []
+    },
+    {
+      "id": "prior-ledger",
+      "file": "ledger.example.json",
+      "snapshot": "Fictional child ledger at 2025-01-01T09:00:00Z",
+      "expectedRecords": 1,
+      "gaps": []
+    }
+  ],
+  "accounting": [
+    { "source": "current", "record": "request-1", "items": ["parser", "landing"] },
+    { "source": "current", "record": "completion-1", "items": ["parser"] },
+    { "source": "current", "record": "git-1", "items": ["landing"] },
+    { "source": "prior-ledger", "record": "deferred-1", "items": ["evaluation"] }
+  ],
+  "items": [
+    {
+      "id": "parser",
+      "owner": "session-example",
+      "state": "done",
+      "evidence": [{ "source": "current", "record": "completion-1" }],
+      "next": "Implementation complete; landing is tracked separately."
+    },
+    {
+      "id": "landing",
+      "owner": "session-example",
+      "state": "open",
+      "evidence": [{ "source": "current", "record": "git-1" }],
+      "next": "Wait for the user's landing decision; dependency PR9 belongs to its owner."
+    },
+    {
+      "id": "evaluation",
+      "owner": "session-example",
+      "state": "deferred",
+      "evidence": [{ "source": "prior-ledger", "record": "deferred-1" }],
+      "next": "Resume only after explicit user selection."
+    }
+  ],
+  "git": {
+    "scope": "example/widget; no other repository work",
+    "checkedAt": "2025-01-01T10:01:00Z",
+    "evidence": [{ "source": "current", "record": "git-1" }],
+    "ownedPrs": [
+      {
+        "url": "https://github.com/example/widget/pull/8",
+        "owner": "session-example",
+        "state": "open",
+        "checkedAt": "2025-01-01T10:01:00Z",
+        "evidence": [{ "source": "current", "record": "git-1" }],
+        "next": "Wait for the user's landing decision."
+      }
+    ],
+    "dependencyPrs": [
+      {
+        "url": "https://github.com/example/widget/pull/9",
+        "owner": "session-other",
+        "state": "open",
+        "checkedAt": "2025-01-01T10:01:00Z",
+        "evidence": [{ "source": "current", "record": "git-1" }],
+        "next": "Await the owner's adoption receipt; no landing authority transferred."
+      }
+    ],
+    "commitsWithoutPr": []
+  }
+}

package/skills/hr-handoff/assets/source.example.json

@@ -0,0 +1,20 @@
+{
+  "records": [
+    {
+      "id": "request-1",
+      "text": "Implement the parser, then wait for my landing decision."
+    },
+    {
+      "id": "completion-1",
+      "text": "Parser implementation and checks complete; PR8 remains unlanded.",
+      "at": "2025-01-01T10:00:00Z",
+      "outcome": { "item": "parser", "state": "done" }
+    },
+    {
+      "id": "git-1",
+      "text": "Checked example/widget: own PR8 open, dependency PR9 open, no commits without a PR.",
+      "at": "2025-01-01T10:01:00Z",
+      "outcome": { "item": "landing", "state": "open" }
+    }
+  ]
+}

package/skills/hr-handoff/references/reconciliation.md

@@ -0,0 +1,105 @@
+# Reconcile a handoff against its sources
+
+Keep a JSON receipt beside the human-readable handoff. It accounts for the
+source records you reviewed and the candidates you extracted. It does not
+replace reading their content or reviewing context-only classifications.
+
+## Collect independent source snapshots
+
+Review the current transcript and the preceding handoff's source transcript
+when available. Include linked plans, child ledgers, schedules, pending
+decisions and owned Git work. Use the host's existing export and session-search
+tools. Preserve source IDs and text rather than exporting only the items you
+already remembered.
+
+Normalize each source into a JSON object with a `records` array. Each record
+has a unique `id` and its original `text`. Record the original location and
+snapshot or range in the receipt's `snapshot` field. Name records by stable
+message IDs or ledger row IDs. Several records can map to the same item.
+
+When a record establishes a disposition, add an `outcome` with `item` and
+`state`, plus `at` as a UTC ISO timestamp. States are `done`, `open` and
+`deferred`. Use the evidence's time, not the export time. A later request or
+current contradictory evidence that reopens completed work also sets
+`outcome.reopens` to `true`. These annotations are reviewed judgments.
+
+Record each expected count from independent export metadata or ledger
+inventory. Use `null` when the total is unknown. A count is for the declared
+snapshot or range; it does not establish coverage outside that range.
+Describe missing, omitted, truncated or unavailable content in `gaps`.
+Keep sensitive snapshots local and redact secrets before normalization.
+
+## Fill the receipt
+
+Copy the fictional [receipt example](../assets/receipt.example.json) and its
+[session snapshot](../assets/source.example.json) and
+[child ledger](../assets/ledger.example.json) into persistent notes. Replace
+their contents with this session's evidence. Source `file` paths resolve
+relative to the receipt; the checker reads only explicitly named snapshots.
+
+- `version` is `1`; `owner` names this session. `coverage` is `complete` or
+  `partial`. Claim complete only for the declared source ranges with known
+  counts and no known gaps.
+- Each `sources` entry has `id`, `file`, `snapshot`, `expectedRecords` and
+  `gaps`. Include inaccessible sources and their limitations rather than
+  silently dropping them.
+- Every source record gets one `accounting` row with `source` and `record`.
+  Add nonempty `items` containing extracted item IDs, or a `context` reason
+  explaining why the record creates no candidate. Review user requests and
+  assistant commitments and options before assigning context-only status.
+- Each `items` entry has `id`, `owner`, `state`, `evidence` and `next`.
+  Evidence references use `{ "source": "source-id", "record": "record-id" }`.
+  Include the latest declared outcome. For deferred work, `next` gives its
+  trigger; for done work, give its result and any separately tracked follow-up.
+- `git` records `scope`, `checkedAt` and `evidence`, plus explicit `ownedPrs`,
+  `dependencyPrs` and `commitsWithoutPr` arrays. Empty arrays are checked
+  results, not omitted fields. For no repository work, say so in `scope` and
+  reference the evidence for that conclusion.
+- Every PR has `url`, `owner`, `state`, `checkedAt`, `evidence` and `next`.
+  PR states are `open`, `closed` and `merged`. Put every owned unlanded PR in
+  `ownedPrs`; distinguish dependency PRs owned by another session.
+  Owned PRs must match the receipt owner. Dependencies confer no landing
+  authority. Query all touched repositories; host-linked PR lists alone can
+  omit work.
+- Own commits without a PR have `repo`, `branch`, `sha`, `owner`, `evidence`
+  and `next`. Inspect checkout state and remote containment as the repository
+  requires. Do not infer landing from a closed PR alone.
+
+Use UTC ISO timestamps such as `2025-01-01T10:01:00Z`. State the query scope
+and check time; this offline checker does not refresh Git or PR state.
+
+Preserve already-selected work and the latest unanswered offer, including its
+scope. Questions, inbox notices and other owners' messages grant no new
+authorization. Reconcile a stale open row with later completion evidence;
+record a later reopening separately.
+
+## Run the offline check
+
+From this skill's directory, replace the receipt path with its saved location:
+
+```sh
+node scripts/check-reconciliation.mjs <receipt.json>
+```
+
+Bun runs the same script. It prints JSON with status, counts, missing IDs,
+errors, coverage gaps and limits. It does not write files or query hosts.
+Repeating the command on unchanged inputs repeats no external action.
+
+| Exit | Meaning                                                             | Action                                                                                   |
+| ---- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `0`  | Supplied accounting and declared outcomes are mechanically complete | Review the semantic coverage and saved handoff before claiming all items were addressed. |
+| `1`  | Malformed input, missing accounting or contradictory declared state | Resolve the reported fields and IDs within the handoff's stop boundary.                  |
+| `2`  | Valid accounting with partial coverage                              | Save the limitations and known next action; do not label coverage complete.              |
+
+The checker cannot detect a promise hidden behind a context-only annotation,
+an omitted source, a falsely complete export or an omitted PR query scope.
+Its success checks supplied evidence, not every possible task or current
+external state. Report those limits beside the result.
+
+## Low-quota stop
+
+Write essential current state, Git ownership and next action first. Save known
+coverage and missing sources when feasible. Keep the partial handoff even if
+its receipt is unfinished or the checker reports errors. Do not recover a
+transcript, run new evaluations or continue substantive work to make the
+checker pass. The skill's low-quota stop takes precedence over reconciliation.