@assuredloop/orca-bot-kit 0.1.0 → 0.3.0

package/skills/obk-writing/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: obk-writing
+description: >-
+  Writing something a particular person will actually read: finding out who it
+  is for and what it has to do, choosing one kind of piece and staying in it,
+  leading with the point, keeping every sentence to one job and one reading,
+  checking the claims that carry weight, and testing it on someone who was not
+  in the room. Use when the job is to produce writing for people rather than
+  code: a page, a note, an update, an announcement, a summary, a message, or
+  editing a draft that already exists.
+---
+
+# Writing for a reader
+
+Everything here serves one test. A particular person, in a particular place,
+with the amount of attention they actually have, gets what they came for. A
+piece that is accurate and complete and does not survive that test has failed
+at the only thing it was for.
+
+These are defaults for work where nothing says otherwise. A user who asks for
+something else gets what they asked for; say which of these you left and why.
+
+## Find out who it is for
+
+Four things change almost every sentence, so settle them before drafting: who
+reads it, what they should be able to do or decide afterwards, where it will be
+read, and what tone fits. Ask when the answer would change the piece. Where
+asking is not possible, write down the reading you took, so the first correction
+is cheap.
+
+Settling those is not the same as having the facts. Look a missing fact up
+where you can. Where it is simply not to be had (a name, a time, a link), do
+not fill it in and do not stop:
+put a visible marker where the fact belongs, and list what you need at the end
+so one reply closes all of them at once. A piece with its holes marked is a
+useful thing to hand back. A piece with its holes filled in from imagination is
+worse than no piece, because nobody can see which parts to check.
+
+The place it will be read is a constraint, not decoration. Something skimmed on
+a phone between meetings, by people with a little context and no patience, is a
+different piece from the same facts written as a page someone lands on from a
+search. The place sets the length, the register, and how much can be assumed.
+
+Find out what they already know, and what they call things. Writing in the
+reader's vocabulary rather than the system's is most of what makes a piece feel
+written for them. Where the two differ, the reader's word wins, and you say the
+other one once.
+
+## Choose one kind of piece
+
+Decide what the piece is before you write it, because the kinds do not mix
+well:
+
+- Something to **follow**, which walks one person through one path and cares
+  that they arrive.
+- Something to **use**, which assumes competence and gives the steps for a job
+  someone already understands.
+- Something to **look up**, which is complete, dry and accurate, and makes no
+  argument.
+- Something to **understand**, which gives the reasons, the history and the
+  choices, and is allowed a view.
+- Something to **decide on**, which leads with what is being asked, gives the
+  options with honest trade-offs, and says what would change the answer.
+
+Two audiences can need two pieces of the same kind. Where that happens, decide
+what each one gets that the other does not, and say whether they also get the
+other piece, so the second does not repeat the first. Then look for the
+asymmetry: where one group is told something that makes the other group's job
+harder, whoever has to square that needs to know it is coming.
+
+Know which one is the job, because the piece is organised around that. Losing
+it is how a piece gets long and satisfies nobody: an argument in the middle of
+a set of instructions, hand-holding inside something written for experts, a
+reference that keeps stopping to persuade.
+
+This is not a rule against a piece containing more than one thing. A short
+announcement can carry the reason for the change, the dates and what to do, and
+sending three linked pieces instead would serve nobody. What matters is whether
+the extra material helps the same reader do the same job. Split when the blend
+makes it unclear who the piece is for, what they are supposed to do, or whether
+they have been told everything. Otherwise keep it in one thing and keep the
+supporting material in its place.
+
+## Lead with the point
+
+The first thing anyone reads should tell them what this is, why it matters to
+them, and what to do next. Readers skim before they commit, and a piece earns
+the full read by answering those three in the first screen.
+
+Put the most important thing first, then the common case, then the exceptions.
+A conclusion at the bottom is a conclusion most people will not reach.
+
+Importance order and the order things happen in are not the same, and a piece
+that turns on dates or steps needs both. Sorting three dates by how much each
+matters leaves the reader re-sorting them into a sequence themselves. Give them
+the sequence in one place, then take the parts in whatever order serves them.
+
+Headings carry the point rather than the topic. "Gates run in CI" tells a
+skimmer something; "CI integration" only tells them where they are. A heading
+earns its place by being a useful landmark, not by filling a quota.
+
+Shorten by cutting what does not change what the reader does next, never by
+compressing prose into shorthand they have to decode. That is the answer when
+"keep it short" meets a sentence that needs its small words: the sentence keeps
+them, and something else goes entirely. Dropped articles, arrows
+and abbreviations make a page look tight and read slowly. Complete sentences
+with their small words are faster to read, and that is the only speed that
+counts.
+
+## Ground what the piece leans on
+
+Every idea a paragraph rests on was either something the reader walked in with
+or something an earlier paragraph gave them. A paragraph that leans on an idea
+the reader does not have loses them, whether or not there is any jargon in it.
+
+That is the real lever on difficulty. Assume too much at the start and you shut
+people out. Explain too much and the opening drowns before it reaches the
+point. Decide deliberately what the reader is expected to bring, say so, and
+introduce the rest where it is first needed rather than in a block at the
+front.
+
+Gloss a term the first time it appears, even where the reader used it first.
+People use words they have not pinned down.
+
+## One job per sentence
+
+- Say who does what. "The build rejects it" rather than "it is rejected".
+  Passive is for when the actor is genuinely unknown or beside the point.
+- Write instructions as instructions, and put the condition first, so a reader
+  can skip what does not apply to them. "To cancel, press Escape."
+- One instruction per sentence, one thought per sentence everywhere else. Split
+  the sentence carrying two.
+- Keep sentences short. A longer one that carries one idea with its condition
+  is not a fault.
+- Cut any word the sentence survives without. "In order to" is "to". "It is
+  important to note that" is nothing.
+- Use the short everyday word. A long word has to buy its length with
+  precision.
+- Cut the adverb or find the right verb. An adverb propping up a weak verb
+  means the verb is wrong.
+- Give one thing one name and keep it. Cycling through synonyms to avoid
+  repetition teaches the reader that there are three things.
+
+Where a rule makes a sentence worse, fix the sentence another way or leave it.
+A sentence that obeys every rule and sounds like nobody wrote it has failed.
+
+## Leave no sentence open to two readings
+
+- Keep "only" and "not" beside the word they change. "Only fails on growth" and
+  "fails only on growth" are different claims.
+- Make every "it", "they" and "this" point at one obvious thing. Repeat the
+  noun rather than making the reader work it out, and never let "this" stand
+  for a whole preceding clause.
+- Break up stacked nouns. "The import budget check script" becomes "the script
+  that checks the import budget".
+- Say which parts an "and" or an "or" joins where a sentence could group two
+  ways. "Either ... or" and "both ... and" cost nothing.
+- Keep the small words that hold a sentence together, even where a shorter
+  version would scan. Clarity is worth more than the word count.
+- Prefer a full stop. Where a sentence is carrying a second clause on a dash or
+  a semicolon, it is usually two sentences.
+- Skip idioms, metaphors and stock phrases. Someone reading in a second
+  language, and anything translating or summarising the piece, all do better
+  with the plain construction.
+
+## Cut the sentence that asserts nothing
+
+The hardest habit to see in your own draft is the sentence that sounds
+substantial and says nothing. This is about empty sentences and not about
+whether a piece may speak to how someone feels; naming what a reader is feeling
+is a fact about them, and it belongs wherever it is true and useful.
+
+"Designed for performance", "a seamless experience", "robust error handling".
+Ask what the sentence tells the reader to do or know. If you can restate it as
+a fact, a number or an instruction, do that instead. If you cannot, cut it.
+
+One test catches most of them: if the sentence could appear word for word in
+something about a different subject, it says nothing about this one.
+
+Name the source or drop the claim. "Experts agree", "studies show" and "it is
+widely considered" are not attributions, and a reader who wants to check one
+finds nothing to check.
+
+## Check what you are asserting
+
+A piece that describes something is a claim about it, and the claims that carry
+weight get checked before it goes out. What something does, what state it is in
+now, what it works with, and any number at all.
+
+- Check against the thing itself rather than against memory, and where checking
+  is cheap and safe, actually run or open it.
+- Where the only source is the person who asked, say so, and check what you
+  still can: the dates against a calendar, the arithmetic, and whether the
+  piece contradicts itself. A brief is one person's account and it can be
+  wrong, so the questions it raises go back to them rather than into the text
+  as fact.
+- Give the exact string. People under pressure copy what you wrote, so the
+  command, the address, the error text and the name have to be right rather
+  than approximately right.
+- Numbers and versions go stale. Either date the claim, tie it to something
+  that regenerates it, or leave it out. A count that was true when you wrote it
+  becomes a lie without anyone touching it.
+- Distinguish nothing to do from nothing done. A report that says zero in a way
+  that reads like success is a lie made out of layout.
+- Say the limits where the reader makes the decision, not in a section at the
+  end. Where the piece could be read as promising something it does not cover,
+  that belongs beside the promise.
+- Where a fact could not be checked, say so in the text. A hedge that a skimmer
+  reads as confidence is worse than a plain "not verified".
+
+Where you change something, change what describes it in the same breath. A
+description left stale is the same defect as a wrong one, and harder to spot.
+
+## Choose the form deliberately
+
+Prose carries an argument. A list carries things that are genuinely parallel,
+and turning an argument into bullets throws away the connections that were the
+argument. Where items are not parallel, write the paragraph.
+
+Numbers claim that order matters. Use them for a sequence and bullets for
+everything else. Introduce a list with a full sentence and keep the items the
+same shape.
+
+Where the same handful of fields repeats three times or more, that is a table.
+Where the exact words are the point, quote them; otherwise say it in your own
+words and cite where it came from.
+
+Use emphasis for the one phrase a skimmer must not miss. When everything is
+bold, nothing is.
+
+## Test it on someone who was not there
+
+You cannot read your own draft as a stranger, and the gaps that matter are the
+ones you filled in from what you already knew. Worth doing when people who were
+not there will read it and a misreading would cost something; a short reply to
+someone already in the conversation does not need it.
+
+Give them the piece by itself: not the conversation that produced it, not your
+summary, and not what you think of it, since handing over your own reading gets
+your own reading back. Anyone counts who comes to it with only what a real
+reader will have. Ask them to find what is wrong with it, not what they think
+of it.
+
+Read what comes back against the piece rather than deferring to it. A misreading
+usually means the piece does not say it; sometimes the reader lacked context a
+real reader will have, and then it is noise. Stop when a pass brings back only
+small things or the holes you already knew about and have marked, and after
+about three passes at most: a piece still turning up real problems then is not
+ready, and that is worth saying rather than going round again.
+
+Then hand it back. Whoever asked for it owns it and is the one to read it
+through before it goes anywhere.
+
+Sources and licences: [NOTICE.md](NOTICE.md).

package/src/book.js

@@ -0,0 +1,268 @@
+// The book: `sessions.yaml` in a bot's home. It is the authority for what the
+// kit knows about a bot's sessions (ADR 0012) — Orca forgets a tab's resume
+// record the moment the tab is closed, so the kit keeps its own record.
+//
+// It is an ordinary file of the user's bots repo: committed, readable, and
+// theirs. Beside each session's tab it holds the harness session id that
+// session is running under, and every id it ran under before.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { isDeepStrictEqual } from 'node:util';
+import { parse, stringify } from 'yaml';
+
+const HEADER = `# What Orca calls this bot on this machine, and where each of its sessions
+# lives. \`obk up\` writes this file; it is committed with the rest of the repo.
+#
+# A session is its Orca tab id. Titles are set, never read, so renaming a tab
+# in Orca changes nothing here.
+#
+# Each session also carries the harness session it runs as, and the ones it ran
+# as before it: a clear makes a new one, and the old ones are kept.
+#
+# \`mailbox\` is where fleet mail for the session is left — an Orca Run, made once
+# and kept, because an address that is a tab dies with the tab. \`address\` is what
+# a Claude session is called, which is what another Claude session writes to.
+#
+# \`retired\` holds what the book knew about each session \`obk retire\` took off
+# the bot, with when, so the conversations it had are still accounted for.
+`;
+
+export const bookFile = (home) => path.join(home, 'sessions.yaml');
+
+/** How long a writer waits for the one before it to finish. */
+const WAIT_MS = 10_000;
+
+/** What the book says, or an empty book when there is none yet. */
+export function readBook(home) {
+  const file = bookFile(home);
+  if (!existsSync(file)) return { orca: {}, sessions: {} };
+
+  const parsed = parse(readFileSync(file, 'utf8'));
+  // A book someone emptied, or filled with something else, is treated as one
+  // that says nothing: `up` then makes what is missing, which is its job.
+  const book = parsed !== null && typeof parsed === 'object' ? parsed : {};
+  return {
+    ...book,
+    orca: asRecord(book.orca),
+    sessions: Object.fromEntries(Object.entries(asRecord(book.sessions)).map(([name, entry]) => [name, withHistoryListed(entry)])),
+    // A retired session's entry is the same entry, and its history is read the same way.
+    ...(Array.isArray(book.retired) ? { retired: book.retired.map(withHistoryListed) } : {}),
+  };
+}
+
+/**
+ * A session entry whose history a person typed as one id, `history: <id>`,
+ * rather than as the list the kit writes, read as that one earlier
+ * conversation. The book is theirs to edit by hand (README), and one id where a
+ * list goes is the edit a person makes.
+ */
+function withHistoryListed(entry) {
+  const history = entry?.history;
+  if (history === undefined || history === null || Array.isArray(history)) return entry;
+  // One entry written without the list around it.
+  if (typeof history === 'object') return { ...entry, history: [history] };
+  // One id, which YAML reads as a number when it is all digits.
+  const id = String(history).trim();
+  return { ...entry, history: id === '' ? [] : [{ session: id }] };
+}
+
+/**
+ * Write the book in one step. A reader either sees the book as it was or as it
+ * is, never half of it, and a writer that dies leaves the old file in place:
+ * the new text goes to a file of this process's own and is moved over the book,
+ * which is one operation the file system either did or did not do.
+ */
+export function writeBook(home, book) {
+  const file = bookFile(home);
+  const half = `${file}.${process.pid}.part`;
+  writeFileSync(half, `${HEADER}${stringify(book)}`);
+  renameSync(half, file);
+}
+
+/**
+ * Change the book with nothing else changing it at the same time: `up` writing
+ * a tab down and a session's own hook writing its id are two programs on one
+ * file, and either one holding a copy from before would undo the other.
+ *
+ * So every change is made here, and made on what the file says now: the lock is
+ * taken, the book is read, `change` is given it, and what comes back is
+ * written. `change` may return a book or change the one it was handed, and may
+ * be asynchronous — it is awaited under the lock.
+ *
+ * Nothing slow belongs inside it. Orca calls, tabs and prompts are the caller's
+ * work; this holds the lock for one read and one write.
+ */
+export async function updateBook(home, change) {
+  const lock = takeLock(home);
+  try {
+    // Nothing writes the book outside this lock, the first write included. A
+    // missing book used to be written before the lock was taken: two first
+    // writers could both find no book, one take the lock and record its id, and
+    // the other then put the empty book it had read in its place (#161,
+    // reproduced with a real second process).
+    const book = readBook(home);
+    const before = structuredClone(book);
+    // Awaited, because a change that takes time must hold the lock while it
+    // does: an unawaited one would let the next writer in and then write over it.
+    const next = (await change(book)) ?? book;
+    // A run that changes nothing writes nothing: the file keeps its bytes and
+    // its time, and nothing else waiting on the lock has to read it again.
+    if (!isDeepStrictEqual(before, next)) writeBook(home, next);
+    return next;
+  } finally {
+    lock.release();
+  }
+}
+
+/**
+ * The right to change what belongs to one bot, held from before it is read until
+ * after it is written — a SQLite write transaction on a file of its own beside
+ * the book. The book is what it usually guards, and `obk groom` takes it too,
+ * for the one thing Orca will not do for us: look for an automation and make one
+ * if it is missing, without a second run doing the same between the two.
+ *
+ * SQLite is in Node itself and does this with the operating system's own file
+ * locks. That matters for one reason: the lock belongs to the process, so it is
+ * held while that process is stopped — swapped out, suspended, sitting in a
+ * debugger — and it is let go when the process ends, whether it ended well or
+ * not. Nothing has to be refreshed and nothing has to be declared abandoned.
+ *
+ * Three attempts at this have failed, each because the lock could be taken from a
+ * writer that was still going to write: a lease with a fixed timeout, then a
+ * lease kept alive by a timer (which a stopped process cannot run), then a check
+ * of the file just before replacing it (which a pause between the check and the
+ * replace defeats). A lock the kernel holds for the process has none of those
+ * seams, so there is nothing left to enumerate.
+ *
+ * The lock file holds no data — it is opened, locked and closed — so it stays
+ * empty and leaves no journal beside it.
+ */
+export function takeLock(home) {
+  const file = lockFile(home);
+  mkdirSync(path.dirname(file), { recursive: true });
+
+  const db = new DatabaseSync(file);
+  try {
+    // A writer that arrives while another is working waits for it rather than
+    // failing at once, and gives up saying so rather than waiting for ever.
+    db.exec(`PRAGMA busy_timeout = ${WAIT_MS}`);
+    db.exec('BEGIN IMMEDIATE');
+  } catch (error) {
+    db.close();
+    throw waitedTooLong(home, error);
+  }
+
+  return {
+    release() {
+      try {
+        db.exec('COMMIT');
+      } finally {
+        db.close();
+      }
+    },
+  };
+}
+
+/**
+ * Where a writer takes its turn: a folder of the kit's own beside the bots repo,
+ * carrying that folder's own name, the way start-prompt files sit beside it
+ * (PRD 6.3). SQLite keeps the file it locks, so this one stays, and the places it
+ * cannot stay are: the bot home, which is the user's repo and gains nothing a
+ * session did not ask for; and their home directory, where the kit writes
+ * nothing.
+ *
+ * Not the machine's temporary directory either, though it looks like the natural
+ * home for state that lasts as long as a write. A temporary directory is swept.
+ * A lock swept away while a writer holds it does not cost that writer anything —
+ * it costs the next one, which creates the file again and takes a turn on a
+ * different file while the first is still writing. Two writers, two locks,
+ * neither knowing: the failure four rounds of review have been about. A sibling
+ * is nobody's to sweep, and the user can see it and delete it.
+ *
+ * One folder per bots folder, so two bots folders each holding an api-bot cannot
+ * take each other's turn.
+ */
+const lockFile = (home) => path.join(
+  `${path.dirname(path.dirname(home))}.locks`,
+  `${encodeURIComponent(path.basename(home))}.lock`,
+);
+
+/**
+ * Something else has been writing the book for longer than this run is prepared
+ * to wait. Every writer holds its turn for one read and one write, so this is a
+ * writer that is stuck or stopped rather than busy — said in the kit's own words,
+ * because the database's are about a database.
+ */
+const waitedTooLong = (home, why) => new Error(
+  `waited ${WAIT_MS / 1000} seconds for something else to finish writing ${bookFile(home)} and it did not (${why.message}). Nothing was written. Try again; if nothing is running, remove ${lockFile(home)}, which is where writers take their turn.`,
+);
+
+/**
+ * The note of conversations nobody claims, with what a scan has just found added
+ * to it. It only ever grows: a scan can only see conversations since the kit last
+ * started a harness in the tab, so anything found earlier would fall out of range
+ * and be forgotten — which is exactly how an unresolved conversation went missing
+ * across a relaunch (round 3 review, finding 1). Ids leave this note one way
+ * only, in `forgetClaimed`, when a session claims them.
+ */
+export function withUnclaimed(entry, found) {
+  const kept = [...new Set([...(Array.isArray(entry.unclaimed) ? entry.unclaimed : []), ...found])];
+  if (kept.length === 0) {
+    const { unclaimed: none, ...rest } = entry;
+    return rest;
+  }
+  return { ...entry, unclaimed: kept };
+}
+
+/**
+ * Take out of every session's note whatever some session now claims: a note is
+ * only ever about a conversation nobody owns, so an id that has found its owner
+ * has no business in one. This is the only way an id leaves a note.
+ */
+export function forgetClaimed(book) {
+  const claimed = sessionIdsIn(book);
+  for (const [name, entry] of Object.entries(book.sessions)) {
+    if (!Array.isArray(entry?.unclaimed)) continue;
+    const kept = entry.unclaimed.filter((one) => !claimed.has(one));
+    book.sessions[name] = withUnclaimed({ ...entry, unclaimed: [] }, kept);
+  }
+  return book;
+}
+
+/**
+ * Every harness session the book accounts for, the ones running now, the ones
+ * that ran before, and the ones of sessions since retired. A conversation in
+ * here belongs to a session already.
+ */
+export function sessionIdsIn(book) {
+  const retired = Array.isArray(book.retired) ? book.retired : [];
+  const ids = [...Object.values(book.sessions), ...retired].flatMap((entry) => [
+    entry?.session,
+    ...(Array.isArray(entry?.history) ? entry.history.map((old) => old?.session) : []),
+  ]);
+  return new Set(ids.filter((id) => typeof id === 'string'));
+}
+
+/** Every tab id the book holds. What is not in here is not the kit's session. */
+export const tabIdsIn = (book) =>
+  new Set(Object.values(book.sessions).map((session) => session?.tab).filter((tab) => typeof tab === 'string'));
+
+const asRecord = (value) => (value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {});
+
+/**
+ * The session entry to keep once a harness has named the session it is running
+ * as. The id the harness gave replaces the one the book held, and the one it
+ * held goes into the history with the reason it was replaced (ADR 0012): old
+ * ids are what recall, auditing and finops read later.
+ *
+ * The same id come back is a session resumed, not a new one, so nothing moves.
+ */
+export function rememberSession(entry = {}, id, ended) {
+  if (entry.session === id) return entry;
+  if (entry.session === undefined) return { ...entry, session: id };
+
+  const was = { session: entry.session, ended: ended ?? 'replaced', at: new Date().toISOString() };
+  return { ...entry, session: id, history: [...(entry.history ?? []), was] };
+}