@bompus/house-rules 0.0.0-stage → 0.13.0

package/skills/hr-handoff/SKILL.md

@@ -0,0 +1,114 @@
+---
+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. Name each predecessor plan as a source, so every open or deferred
+line in its ledger carries over as an item. 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.
+
+When a handoff unrelated to quota moves work to another thread, also move what
+the host binds to the outgoing thread:
+
+1. Inventory it: scheduled or recurring tasks, linked pull requests and PR
+   watches, and any agent-mail or messaging registration and its subscriptions.
+   Use the host's own list or status commands for each.
+2. Move or record each item. Where the host lets the receiving thread bind it,
+   the handoff names the exact call the receiver makes; some hosts let a thread
+   bind a task only to itself, so the outgoing thread cannot move it. Otherwise
+   record why it stays. Read each item back after the move; a move without a
+   read-back is unfinished. Retire the outgoing copy of a task only after the
+   receiver's read-back confirms its replacement, so the work neither runs twice nor is lost.
+3. Follow any thread-switch checklist the owning repository or the user's
+   guidance names, and list it in the handoff.
+4. Keep the outgoing registration until the user closes the old thread, then
+   retire it.
+5. Give each bound item a row in the receipt, with owner, state and next action.
+
+When the new thread replaces this one as its successor, also follow
+[successor-thread.md](references/successor-thread.md) for when a replacement is
+warranted, its safe boundary, the title and the successor record.
+
+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,124 @@
+# 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, pending decisions, owned
+Git work and what the host binds to the outgoing thread (scheduled tasks, PR
+watches, mail or messaging registration and subscriptions), as listed in the skill's
+thread-move step. 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.
+
+A predecessor plan needs no conversion. Name its `plan.md` as the source
+`file`; the checker reads each item line of its `## Ledger` section (`- [ ]`,
+`- [~]`, `- [x]`, `- [-]`) as a record named `L<line>` (`L12`). Other text in
+the section is not read, so turn any follow-up written there into an item line
+before the handoff. Take a copy of the plan as it stood at the handoff,
+because later edits renumber the lines. Each open or deferred line must map to
+an item; a context-only reason such as "the rest, reopen only if asked" is
+rejected. When one item absorbs several open or deferred lines, give the item
+a `merges` field saying how one next action and one piece of completion evidence
+satisfy every line. A ledger kept as a table is not read; normalize it to JSON
+records instead.
+
+When a record settles an item's state, 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`, plus
+  `merges` when it carries over more than one open or deferred plan line.
+  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.
+- Thread-bound state (scheduled or recurring tasks, PR watches, any mail or
+  messaging registration and subscriptions) is an `items` entry like any other. `next`
+  names the receiver's exact call to bind it and how to read it back, or why it
+  stays with the outgoing thread until the user closes it.
+- `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.

package/skills/hr-handoff/references/successor-thread.md

@@ -0,0 +1,76 @@
+# Replace a session with a successor thread
+
+Follow this when a handoff moves work to a fresh thread that takes over from
+the current one. It decides when replacing a session is warranted, when it is
+safe and what the handoff and the successor record. It does not authorize
+starting a thread. The house rules' § Repository work still requires the
+user's direction, a standing spin-off preference or a rule that requires the
+handoff. The host's own guidance owns the tool calls that create, rename and
+rebind a thread.
+
+## When stale guidance warrants a new session
+
+Replace a session because its injected guidance went stale only when the change
+is session-critical:
+
+- an always-on rule, or a safety rule
+- the catalog entry (name and description) of a skill the session uses
+- a subagent definition the session uses
+
+A change to a skill body or a doc does not warrant a new session. The session
+rereads it with `hr-agent-guidance-refresh` at its next boundary, and the body
+is read when the skill runs. That skill notes that a reread does not prove the
+injected context changed, so use the list above, not the reread, to decide
+whether a replacement is needed.
+
+## Boundary
+
+Never replace a session mid-turn, in the middle of an evaluation that fixed its
+guidance, or while an external action is pending. An action is pending when it
+has started without a recorded result. Replace it only when the session is
+idle, nothing is running and the ledger is reconciled under the house rules'
+§ Finishing work.
+
+## Successor title
+
+A successor keeps the base title and ends it with ` v<N>`. The first thread
+counts as `v1` and is renamed at the handoff.
+
+1. If the title ends in ` v` followed by digits, the base is the title without
+   that ending and N is that number. Otherwise the base is the whole title and
+   N is 1.
+2. Rename the outgoing thread to `<base> v<N>` when its title does not already
+   end that way.
+3. Give the successor `<base> v<N+1>`, writing N+1 as a plain number without
+   leading zeros.
+
+A title is a label for people. Never look a thread up by its title. Use the
+registry row, the project and the thread id.
+
+## What the handoff records
+
+- The outgoing thread's id and the successor's id, so each points to the other.
+- Each open offer by the offer ID the ledger recorded for it, with its
+  question, options and recommendation. The house rules' § Offers records an ID
+  for every offer, including a text-only one that never displayed it. The
+  successor treats an offer as open only if the handoff lists it and the latest
+  ledger or source record still shows it open. An offer answered, completed,
+  deferred or superseded since the handoff was written authorizes nothing. A
+  bare code or `go` in the successor selects an offer only when one listed offer
+  is open. With several, it asks which one, as § Offers requires.
+- The inventory and read-backs from the skill's thread-move step. The
+  receiving thread re-points to itself each item the host lets it bind:
+  registry rows, scheduled tasks, pull request watches and the messaging name
+  the work was known by. For an item it cannot bind, the handoff keeps the
+  recorded reason it stays with the outgoing thread. Where the host does not let
+  the successor take over the name, the handoff says which name the successor
+  registers and who needs to be told.
+
+## Successor record
+
+- Mark the outgoing thread settled and record a pointer to the successor where
+  the host keeps such notes. Do this last, after the successor confirms it has
+  read the handoff.
+- The successor starts by reading the handoff in full. It re-points each item
+  it can bind, with a read-back, and records every result in the receipt,
+  including the items that stay behind. Only then does it take new work.