@bompus/house-rules 0.0.0-stage → 0.11.0

package/skills/hr-navigation-retro/scripts/transcripts.py

@@ -0,0 +1,205 @@
+"""Selected-file adapters for OpenCode exports, Cursor streams and ACP v1 logs.
+
+No store discovery or recorded-command execution. Adapters emit the same events
+as retro.py. ACP state is folded in a first pass so later input/name updates do
+not change tool numbering or multiply a single call's results.
+"""
+import json
+
+
+def records(path):
+    with open(path, errors="replace") as source:
+        first = source.readline()
+        try:
+            record = json.loads(first)
+        except ValueError:
+            # Pretty-printed session exports are one JSON object, not JSONL.
+            if first.strip() == '{':
+                source.seek(0)
+                record = json.load(source)
+                if isinstance(record, dict):
+                    yield record
+                return
+            record = None
+        if isinstance(record, dict):
+            yield record
+        for line in source:
+            try:
+                record = json.loads(line)
+            except ValueError:
+                continue
+            if isinstance(record, dict):
+                yield record
+
+
+def text(value):
+    if isinstance(value, str):
+        return value
+    if isinstance(value, list):
+        return '\n'.join(text(v) for v in value)
+    if isinstance(value, dict):
+        for key in ('text', 'content', 'output'):
+            if key in value:
+                return text(value[key])
+        return json.dumps(value)
+    return '' if value is None else json.dumps(value)
+
+
+def tool(name, value, kind=None, locations=None):
+    """Normalize documented names/inputs; unknown names remain ordinary tools."""
+    names = {'read': 'Read', 'read_file': 'Read', 'grep': 'Grep', 'glob': 'Glob',
+             'list': 'LS', 'bash': 'exec_command', 'Bash': 'exec_command',
+             'write': 'Write', 'edit': 'Edit'}
+    if not isinstance(name, str):
+        name = None
+    if not isinstance(kind, str):
+        kind = None
+    name = names.get(name, {'read': 'Read', 'search': 'Grep',
+                           'edit': 'Edit', 'execute': 'exec_command'}.get(kind, name or 'unknown'))
+    if name == 'Read' and not isinstance(value, (dict, str)):
+        value = {}
+    if not isinstance(value, dict):
+        value = value if isinstance(value, str) else json.dumps(value or {})
+        return name, value
+    if name == 'Read':
+        path = value.get('file_path') or value.get('filePath') or value.get('path')
+        if not path and isinstance(locations, list) and len(locations) == 1:
+            path = locations[0].get('path') if isinstance(locations[0], dict) else None
+        return name, path if isinstance(path, str) else ''
+    if name in ('Grep', 'Glob'):
+        return name, str(value.get('pattern') or json.dumps(value))
+    return name, json.dumps(value)
+
+
+def opencode(record, timestamp):
+    info = record.get('info')
+    if not isinstance(info, dict) or not isinstance(record.get('messages'), list):
+        return
+    time = info.get('time') if isinstance(info.get('time'), dict) else {}
+    title = info.get('title') if isinstance(info.get('title'), str) else ''
+    directory = info.get('directory') if isinstance(info.get('directory'), str) else None
+    yield ('meta', directory, title, bool(info.get('parentID')), timestamp(time.get('created')))
+    for message in record['messages']:
+        if not isinstance(message, dict) or not isinstance(message.get('info'), dict):
+            continue
+        meta = message['info']
+        time = meta.get('time') if isinstance(meta.get('time'), dict) else {}
+        stamp = timestamp(time.get('created'))
+        path = meta.get('path')
+        if isinstance(path, dict) and isinstance(path.get('cwd'), str):
+            yield ('context', path['cwd'], stamp)
+        role = meta.get('role')
+        for part in message.get('parts') if isinstance(message.get('parts'), list) else []:
+            if not isinstance(part, dict):
+                continue
+            if part.get('type') == 'text' and role in ('user', 'assistant'):
+                yield (role, text(part.get('text')), stamp)
+            elif part.get('type') == 'tool' and role == 'assistant':
+                state = part.get('state')
+                if not isinstance(state, dict):
+                    continue
+                times = state.get('time') if isinstance(state.get('time'), dict) else {}
+                name, arg = tool(part.get('tool'), state.get('input'))
+                call_id = part.get('callID') or part.get('id')
+                if not isinstance(call_id, str):
+                    continue
+                yield ('call', name, arg, call_id, timestamp(times.get('start')) or stamp)
+                if state.get('status') in ('completed', 'error'):
+                    yield ('result', call_id, text(state.get('output') or state.get('error')),
+                           state['status'] == 'error', timestamp(times.get('end')) or stamp)
+
+
+def acp_update(record):
+    params = record.get('params')
+    if isinstance(params, dict) and record.get('method') == 'session/update':
+        return params.get('sessionId', ''), params.get('update')
+    update = record.get('update')
+    if isinstance(update, dict):
+        return record.get('sessionId', ''), update
+    if 'sessionUpdate' in record:
+        return record.get('sessionId', ''), record
+    return None, None
+
+
+def acp_calls(path):
+    calls = {}
+    for record in records(path):
+        session, update = acp_update(record)
+        if not isinstance(update, dict) or update.get('sessionUpdate') not in ('tool_call', 'tool_call_update'):
+            continue
+        call_id = update.get('toolCallId')
+        if not isinstance(call_id, str):
+            continue
+        if not isinstance(session, str):
+            continue
+        state = calls.setdefault((session, call_id), {})
+        for key, value in update.items():
+            if value is not None:  # ACP v1 null/omission leaves the prior value.
+                state[key] = value
+    return calls
+
+
+def acp(record, calls, seen, finished, timestamp):
+    session, update = acp_update(record)
+    if not isinstance(update, dict) or not isinstance(session, str):
+        return
+    stamp = timestamp(record.get('timestamp'))
+    kind = update.get('sessionUpdate')
+    if kind in ('user_message_chunk', 'agent_message_chunk'):
+        yield ('user_chunk' if kind.startswith('user') else 'assistant_chunk', text(update.get('content')), stamp)
+    elif kind in ('tool_call', 'tool_call_update'):
+        call_id = update.get('toolCallId')
+        if not isinstance(call_id, str):
+            return
+        key = (session, call_id)
+        state = calls[key]
+        if key not in seen:
+            seen.add(key)
+            name, arg = tool(state.get('name'), state.get('rawInput'), state.get('kind'), state.get('locations'))
+            yield ('call', name, arg, call_id, stamp)
+        if update.get('status') in ('completed', 'failed') and key not in finished:
+            finished.add(key)
+            output = state.get('rawOutput')
+            content = state.get('content')
+            if output is None and isinstance(content, list):
+                output = [item.get('content') for item in content if isinstance(item, dict)
+                          and item.get('type') == 'content' and isinstance(item.get('content'), dict)
+                          and item['content'].get('type') == 'text']
+            yield ('result', call_id, text(output),
+                   update['status'] == 'failed', stamp)
+
+
+def cursor(record, seen, timestamp):
+    stamp = timestamp(record.get('timestamp_ms')) or timestamp(record.get('timestamp'))
+    outer = record.get('tool_call')
+    if not isinstance(outer, dict):
+        return
+    name, args, result = 'unknown', {}, None
+    for key, canonical in (('readToolCall', 'Read'), ('writeToolCall', 'Write')):
+        value = outer.get(key)
+        if isinstance(value, dict):
+            name, args, result = canonical, value.get('args'), value.get('result')
+            break
+    else:
+        function = outer.get('function')
+        if isinstance(function, dict):
+            name, args = function.get('name'), function.get('arguments')
+            if isinstance(args, str):
+                try:
+                    args = json.loads(args)
+                except ValueError:
+                    pass
+            result = outer.get('result')
+    name, arg = tool(name, args)
+    call_id = record.get('call_id')
+    if not isinstance(call_id, str):
+        return
+    if ('call', call_id) not in seen:
+        seen.add(('call', call_id))
+        yield ('call', name, arg, call_id, stamp)
+    if record.get('subtype') == 'completed' and ('result', call_id) not in seen:
+        seen.add(('result', call_id))
+        error = isinstance(result, dict) and 'error' in result
+        if isinstance(result, dict):
+            result = result.get('error') if error else result.get('success', result)
+        yield ('result', call_id, text(result), error, stamp)

package/skills/hr-ordering-tests/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: hr-ordering-tests
+description: "Enumerate event orderings in ordinary unit tests. Use when a bug or change depends on the order of events between actors (tabs, workers, polling loops, storage writers, retries), or when code merges writes from more than one source. Not for pure functions of a single input."
+---
+
+# Ordering tests
+
+A hand-written test covers an ordering someone thought of. This technique
+generates every ordering of a small set of events up to a fixed length and runs
+each one through the real code, so it also finds the orderings nobody listed.
+That is a model checker's job, done in the project's own test runner against
+the implementation instead of a separate model that can drift from it.
+
+## Steps
+
+1. **Name the invariants.** State what must hold after any sequence, such as
+   "a completed record never reopens" or "the stored timestamp never goes
+   back". Done when each one is a yes/no check on observable state.
+2. **List the events.** Include each distinct write, message, restart or reset
+   an actor can produce, with the variants that take different code paths:
+   an older, equal and newer timestamp; a field left out; another identity
+   (session, tenant, league); two events delivered in one batch. Aim for 6 to
+   10 events, and merge variants that exercise the same path.
+3. **Enumerate.** Walk every sequence up to length N depth-first. At each node,
+   restore the state its prefix left, apply one event through the real entry
+   point (listener, handler, reducer), then check every invariant. The cost is
+   events^N applications. N of 3 or 4 is usually enough, since ordering bugs
+   rarely need more than three events, and the test should finish within a
+   few seconds under full-suite load.
+4. **Report sequences.** Record each violation as the invariant plus the
+   sequence, such as `a completed record reopened after A → B → C`, and
+   assert the list is empty, so one run shows several failures.
+5. **Prove it discriminates.** Break one guard an invariant depends on,
+   confirm the test fails and names a sequence, then revert.
+6. **Act on what it finds.** Pin each sequence the search finds as one named
+   regression test next to the enumeration, its owning boundary, and fix it. When the bug is out
+   of the change's scope, record it as a follow-up and exclude that invariant
+   with the reason until the fix lands.
+
+## Keeping it deterministic
+
+Drive asynchronous boundaries with fake timers, barriers or a synchronous
+flush; never sleep or use real time. Clone event payloads per application so
+one sequence cannot leak state into the next. For sequences too long to
+enumerate, a seeded random walk over the same events is the fallback; print
+the seed with the failing sequence.
+
+## Maintenance
+
+When the code gains a new kind of event, add it to the list in the same
+change. Reviewers check for this.

package/skills/hr-ordering-tests/agents/openai.yaml

@@ -0,0 +1,2 @@
+interface:
+  display_name: "HR: Ordering tests"

package/skills/hr-plain-prose/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: hr-plain-prose
+description: Revise text a person will read (commit messages, PR descriptions, docs, code comments, replies, the final report on a task) so it is plain, specific and free of AI tells, the habits that mark machine-written prose. Use when drafting or revising human-facing text, even a short message or reply, or when asked to "unslop" text or make it sound less generated.
+---
+
+# Plain prose
+
+Readers spot generated text by its habits, not by any one word: vague claims,
+inflated vocabulary, the same sentence shapes over and over, decoration in
+place of content. This skill removes those habits while keeping every fact the
+author meant. Apply it to your own drafts before they ship, and to text the
+user hands you. For pull request structure, use `hr-writing-pr`; for text an agent
+reads, use `hr-writing-for-agents`.
+
+## Before editing
+
+Mark what must survive unchanged: code, identifiers, commands, paths, version
+numbers, error messages, quoted material, links and any technical claim. You
+may rephrase around these, never inside them. Note the author's deliberate
+choices too, such as a project's house terms, a required template or a
+consistent "we". Those stay.
+
+A passage the author has flagged to keep, by telling you so or with a
+comment such as `plain-prose: keep`, stays exactly as written, whatever the
+checks below say about it.
+
+## Say the specific thing
+
+A sentence that could appear unchanged in any other project carries no
+information. Replace it with the mechanism, the number, the file or the source,
+or cut it.
+
+- "Improves performance significantly" becomes "Cuts cold start from 2.1 s to
+  0.8 s by caching the parsed config."
+- "Various edge cases are handled" becomes "Empty input and a missing trailing
+  newline no longer crash the parser."
+
+If the specific is not known, say what is unknown ("not measured", "untested on
+Windows"). Never invent a figure, an example or a source to fill the gap. The
+same goes for thresholds and norms. A judgment word such as "normal", "on
+target", "reasonable" or "on track" needs the baseline it is measured against
+("RSS of 1.4 GB, under the 2 GB container limit"). If nothing defines the
+expected value, write that it is undefined rather than passing judgment.
+
+- **Unnamed authorities.** "Research suggests", "it is widely accepted" and
+  "most developers prefer" with no source behind them present an opinion as
+  consensus. Name the study, the survey or the person, or delete the
+  sentence.
+- **Fake ranges.** "Handles everything from SQLite files to billing disputes"
+  joins two ends that sit on no shared scale, so nothing lies between them.
+  List the things it handles.
+
+## Choose plain words
+
+- Prefer the short common word: "use" over "leverage", "help" over
+  "facilitate", "start" over "commence".
+- Let "is" and "has" do their job. "The cache serves as a buffer" is "The cache
+  is a buffer."
+- Drop intensifiers and padding: "very", "truly", "it is worth noting that",
+  "in order to", "at the end of the day".
+- Keep one hedge where doubt is real and drop the rest. "This might possibly
+  help in some cases" becomes "This may help when the queue is full."
+- An adverb attached to a weak verb signals that a stronger verb or a
+  measurement belongs there. "Loads really fast" becomes "Loads in 180 ms";
+  "sharply reduces errors" becomes "Cuts failed uploads from 4% to 0.3%".
+
+The words below are cues to reread a sentence, not proof of anything. When
+one turns up, check whether it says more than its plain replacement would, and
+look harder where several cluster in one paragraph. The checker script under
+"Check the result" reads this table and the one under "Name the actual
+thing", so keep each row as `| term | replacement |`.
+
+| Word                  | Write instead                              |
+| --------------------- | ------------------------------------------ |
+| delve into            | look at, read, test                        |
+| pivotal, crucial      | say what breaks without it                 |
+| robust                | name the failure it survives               |
+| seamless              | name the step that no longer fails, or cut |
+| comprehensive         | name what is covered                       |
+| streamline            | name the step removed                      |
+| showcase              | show                                       |
+| underscore            | show, or cut                               |
+| foster                | help, build                                |
+| elevate               | improve, raise                             |
+| tapestry              | cut                                        |
+| realm                 | area, or cut                               |
+| testament to          | evidence of, or cut                        |
+| moreover, furthermore | also, or cut                               |
+| notably               | cut                                        |
+
+## Name the actual thing
+
+Some nouns sound technical but describe a problem as terrain or a physical
+force when an ordinary word for it is available. Name the actual thing.
+
+| Stand-in          | Plain word                                   |
+| ----------------- | -------------------------------------------- |
+| landscape         | the tools or vendors, listed                 |
+| ecosystem         | the packages, plugins or companies meant     |
+| friction          | the extra step, prompt or wait               |
+| traction          | users, downloads or revenue, with the number |
+| momentum          | what shipped, and when                       |
+| headwinds         | the specific problems                        |
+| fault line        | the boundary where the two designs disagree  |
+| center of gravity | the module or team that decides              |
+| bandwidth         | time                                         |
+| lens              | the criterion                                |
+| pillars           | parts, goals                                 |
+| erosion           | the drop, with before and after figures      |
+
+Write figurative language literally too. That covers metaphors, figurative
+verbs, code or documents described as if they had wishes, and slogan-like
+one-liners.
+
+- "The parser chokes on tabs" becomes "The parser rejects tab characters."
+- "The README wants you to start with the setup section" becomes "Read the
+  setup section first."
+
+## Break the sentence habits
+
+- **Reflexive threes.** Lists of three adjectives or three parallel clauses
+  appear because the rhythm feels finished, not because there are three things.
+  Keep the items that are true and distinct.
+- **Contrast framing.** "Not only X, but also Y" and "This isn't about X, it's
+  about Y" set up a contrast nobody raised. State Y.
+- **Tacked-on significance.** A trailing participle that announces importance
+  ("..., highlighting the need for better tests") adds a claim without support.
+  Cut it, or make it its own sentence with evidence.
+- **Closing summaries.** A last paragraph that restates the ones above it, or an
+  "Overall, ..." line, adds length only. End on the last new fact.
+- **Rotating synonyms.** Calling the same thing "the worker", "the process" and
+  "the job" in three sentences makes the reader wonder whether there are three.
+  Pick one name and keep it.
+
+## Fix the punctuation
+
+- **Em dashes.** Leave them out of any prose a person reads. At the spot
+  where one would sit, end the sentence and start another, or use a comma. No
+  other mark may take its role, which rules out en dashes, spaced hyphens,
+  ellipses, colons inside a sentence and parenthetical asides. Do not contort
+  the sentence to avoid the missing dash either. Hyphenated words keep their
+  hyphens, and code, quotations and numeric ranges such as 10-20 keep their
+  dashes.
+- **Colons.** Colons introduce a list, a sample or a block quotation. A
+  colon between two clauses in running prose usually sets up a reveal ("The
+  cause was simple: a stale cache."). Write the point directly ("A stale cache
+  caused the failure.").
+- **Quotes.** Anything headed for source files, commit messages, a shell or a
+  Markdown file gets straight quotes and apostrophes. Typographic (curly)
+  quotes break shell commands and exact-match searches.
+
+## Strip the formatting habits
+
+- Bold only what a skimming reader must not miss, at most a few times per page.
+- Avoid bullets that open with a bold label and a colon and then repeat the
+  label in the sentence. Write the sentence, or use a heading. Opening a bullet
+  with a bolded name and a period, then giving information the name does not
+  already say, is fine.
+- No emoji as decoration or as bullet markers.
+- Use sentence case for headings unless the project's style says otherwise.
+- Prefer a paragraph to a bullet list when the points depend on each other.
+
+## Remove chat leftovers
+
+Text that leaves the conversation should not carry its manners. Delete
+praise for the question ("Great question!"), offers of further help ("Let me
+know if you'd like..."), announcements of what comes next ("Here's a breakdown
+of..."), self-congratulation on a discovery ("Bingo!", "That did it!") and
+self-reference ("As an AI..."). Start with the content.
+
+## Make it easy to read
+
+- Keep spaces between prose words, counts and units, including agent messages.
+  Write "has 12 unfinished cases" and "64 MiB process peak", never
+  "has12unfinished" or "64MiBprocesspeak". Preserve literal identifiers and
+  filenames byte-for-byte in code spans. Run the checker on outgoing drafts;
+  correct its missing-space cues before sending. It cannot detect every joined word.
+- One idea per sentence. Split a sentence that joins two claims with "and".
+- Use active voice with a named actor: "The scheduler drops the job", not "The
+  job is dropped".
+- Write replies as complete sentences about the actual work. Translate plan
+  labels and internal shorthand into words the user already knows. Explain a
+  needed technical term when first used. Keep exact identifiers where the
+  reader needs them to find or verify something.
+- Cap sentence length. Keep a step the reader carries out near 20 words and a
+  descriptive sentence near 25. A longer one usually holds two ideas. Vary the
+  length below the cap.
+- Write each step as a command with one action, and put its condition first:
+  "If the build fails, rerun it with `--verbose`." Two actions share a step
+  only when they happen at the same time.
+- Before sending a reply, read it without the task notes. Then read only its
+  first and last lines. The opening should state the answer or result. The
+  ending should make any required next action or decision clear. When none
+  remains, end without inventing another task or repeating the answer.
+  Rewrite sentences that depend on unexplained labels, abbreviations or
+  knowledge of the agent's workflow. State permission limits plainly when
+  they affect the proposed action; routine updates do not need the unchanged list.
+- In a report or a note to the user, make each heading or bold lead state the
+  takeaway ("Multi-turn ask is switched off"), not only the topic ("Prompt
+  caching and multi-turn ask"). Reference pages keep topic headings.
+
+## Do not overcorrect
+
+- Judge by density. One "robust" or one list of three is fine; a paragraph built
+  from them is not. No single word proves the text was generated.
+- Do not swap stiffness for forced casualness: no slang, jokes or "Honestly,"
+  openers the author did not write.
+- Vary sentence length. Uniform short sentences are as mechanical as uniform
+  long ones.
+- Let emphasis be uneven. A piece can hold one or two quiet, ordinary
+  sentences that make no point of their own. Do not fake this with misspellings,
+  padding or put-on informality.
+- Editing out old habits can breed new, equally regular ones. Look for a short
+  moral at the close of each paragraph ("Small fixes add up."), a denial
+  followed at once by its correction ("The bug was not in the parser. It was
+  in the cache."), and openers that tease an answer ("So why did it fail?").
+  Once in a whole piece reads as voice; once per paragraph reads as a
+  template.
+- When a stock phrase goes, delete it rather than swapping in another. A
+  replacement that keeps appearing across edits becomes a habit of its own.
+- Leave text alone when it is already plain. A light edit beats a rewrite.
+
+## Check the result
+
+Run `bun <this skill's directory>/scripts/check.mjs <file>` (Node 22+ also
+works; with no file it reads standard input). It lists each of these with its
+line and column, and exits 1 when it finds any:
+
+- an em dash or other dash stand-in
+- a colon between two clauses
+- a curly quote or a filler phrase
+- counts or measurement units joined to prose without spaces
+- a word from the two tables above
+- a sentence over 30 words
+
+Each is a cue to reread, not a verdict, because the script cannot tell a
+deliberate word from a habit. It skips code, URLs, block quotations and text
+in straight double quotes, also when the quote wraps a line. It also skips
+word-table rows like the ones above, a table cell holding only a dash and the
+paragraph after a `plain-prose: keep` comment. A colon that ends the label
+opening a list item is not counted. It does not compare the revision with the
+original; the steps below do.
+
+Compare the revision against the original, sentence by sentence:
+
+1. Every fact, number, condition and caveat from the original is still there,
+   with the same meaning and strength.
+2. Every item you marked in "Before editing" is byte-for-byte unchanged.
+3. Nothing new was claimed that the original or the evidence does not support.
+4. Read it once start to finish. If a sentence still sounds like it could
+   belong to any project, fix it or cut it.
+5. Read the opening sentence of every paragraph and nothing else, top to
+   bottom. When that sequence reads like a neat abstract of the whole text,
+   the paragraphs follow a template. Combine some, change their order or begin
+   a section with something other than its summary, without changing what it
+   says. Specs, runbooks and reference pages are meant to be skimmed this way,
+   so skip the step for them.
+
+When revising someone else's text, return the edited version and, if any
+meaning was unclear, list the spots where you had to guess rather than guess
+silently.

package/skills/hr-plain-prose/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "HR: Plain prose"
+  short_description: "Make human-facing text plain and specific"