@assuredloop/orca-bot-kit 0.6.0 → 0.8.0

package/README.md

@@ -340,7 +340,7 @@ with why that one ended and when
 
 The book stays true to the harness through a hook `obk up` puts in the bot's own
 folder — `.claude/settings.json` or `.codex/hooks.json`, never your user-level
-settings ([ADR 0020](docs/adr/0020-kit-hooks-live-in-the-bot-folder.md)). Your own
+settings ([ADR 0022](docs/adr/0022-kit-hooks-live-in-the-bot-folder.md)). Your own
 settings in those files are kept. Codex asks you to trust a hooks file the first
 time it sees one; answer its question in the tab.
 
@@ -431,6 +431,31 @@ retiring it again finishes the job. Bot
 Father itself, and its management session `daily`, are never paused or
 retired; its other sessions are like any bot's.
 
+## Daily grooming
+
+Grooming is an optional daily pass over the fleet: what each bot did, what it
+cost, and what to improve, sent as one short report to Bot Father's management
+session. It runs in a session of Bot Father's called `grooming`, on Claude
+Code's own scheduler, at the model and effort you give that session.
+
+```sh
+obk session add --bots /path/to/my-bots --bot bot-father --name grooming --model sonnet --effort medium
+obk up --bots /path/to/my-bots --bot bot-father
+obk groom --bots /path/to/my-bots --now           # run it once, by hand, and read it
+obk groom --bots /path/to/my-bots --on --at 04:00 # then schedule it
+obk groom --bots /path/to/my-bots                 # what is scheduled
+```
+
+It starts off, and Bot Father asks you before it turns it on, because it spends
+tokens every day. It fires only while its tab is open in Orca and Claude Code is
+idle there, up to half an hour after its time, and a day it misses is not made
+up. Each run renews its own schedule, which Claude Code would otherwise end
+after a week, and `--on --at` puts it back if it lapses. A `/clear` in its tab
+leaves it running until the session is next restarted; after that, `--on --at`
+puts it back.
+`obk groom --compact` compacts its conversation between runs. Grooming on Codex
+comes later: on a Codex Bot Father, add the session with `--harness claude`.
+
 ## When something is wrong
 
 ```sh
@@ -545,6 +570,7 @@ failing quietly.
 npm test                      # the whole suite, in a few minutes
 npm run test:system           # what the system tests would drive, and nothing else
 npm run test:system -- --yes  # drive them, on this machine, for real
+npm run test:system -- --yes test/system/groom.test.js  # only the ones you name
 npm run mutate                # the mutation audit, on what your branch changed
 ```
 
@@ -570,7 +596,9 @@ which Orca, which files, and what they will do to it — and then stops without
 driving any of it, answering non-zero so that a run which did not run them
 cannot be read as one that passed. `-- --yes` is how you say you meant it. When
 Orca is not answering, the command says which Orca it asked and skips, rather
-than report a kit that is not broken.
+than report a kit that is not broken. Name files after it to run only those;
+each must be one of the `*.test.js` files under `test/system/`, links followed,
+and a name that is not is refused before anything runs.
 
 `npm run mutate` runs [StrykerJS](https://stryker-mutator.io) over the
 JavaScript this branch changed against `main` — committed, still in the working

package/SETUP.md

@@ -102,8 +102,9 @@ Ask both in one message, then wait.
 
 **Where the bots folder goes.** An absolute path. It becomes a git repository of
 theirs holding every bot's configuration: charters, rules, session settings, the
-book of sessions. It holds none of the kit's code. They may push it somewhere
-later; the kit never commits for them.
+book of sessions. It holds none of the kit's code. The bots commit their own
+changes to it; the kit's commands never commit, and pushing it somewhere is
+theirs to decide.
 
 **Which harness Bot Father runs on**, `claude` or `codex`. There is no default
 and the kit will not guess. It is Bot Father's own harness only; each bot they

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assuredloop/orca-bot-kit",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/rules/commit.md

@@ -0,0 +1,18 @@
+---
+name: commit
+title: Commit your changes
+applies: all
+---
+
+Commit your own changes to the bots repo often, as each piece of work there is
+done: what you changed, in whatever folder it is, and what the kit wrote in
+your own bot's folder (its files there and your book of sessions). Stage each
+file by name and name them in the commit too (`git commit -- <files>`), so
+nothing another session staged goes in with yours. What no bot owns (init's
+files, the defaults, the user's rules and skill lists) is Bot Father's to
+commit. Commit yours even when the repo has no commit yet or holds files that
+are not yours; leave those to their owner.
+
+Committing is not pushing: pushing is the user's call. A clone in your work dir
+follows its own repo's rules. When a commit fails, for example on another
+session's index lock, try again, and say so if it still fails.

package/skills/obk-bot-building/SKILL.md

@@ -214,8 +214,12 @@ index load at every start. Codex's memories belong to the user and are shared
 by every Codex session, so a Codex bot cannot have its own; say so before
 turning them on for one. It is a hand edit, and say that you made it.
 
-After each change, commit what it changed in the bots folder; the kit never
-commits by itself.
+After each change, commit what it changed in the bots folder, naming each
+file when you stage it and again in the commit. Commit with it what no bot
+owns and nobody has committed yet: `init`'s files, `defaults.yaml`,
+`skills.yaml`, and the user's `rules/` and `skills/`. What it changed
+includes the folder of a bot it made or changed. The kit never commits by
+itself.
 
 Do the reversible part and stop at the line. Making a bot, adding a session
 and linking skills add things and are safe to run again; closing a tab,

package/skills/obk-fleet-review/SKILL.md

@@ -251,6 +251,7 @@ identifiers, counts and paths that only show the work; where evidence matters,
 say where it is.
 
 Say what you did not look at. Where you changed anything in the bots folder,
-commit it; the kit never commits by itself.
+commit it, naming each file when you stage it and again in the commit; the
+kit never commits by itself.
 
 Sources and licences: [NOTICE.md](NOTICE.md).

package/skills/obk-grooming/NOTICE.md

@@ -50,11 +50,13 @@ profile notes and that any bot may read them; and the routing, where something
 the kit does wrong is filed as an issue in one step and something a bot does
 wrong goes back to that bot's session as feedback.
 
-That grooming is the automation's own session rather than a tab in the book,
-and that what it must remember therefore lives in files, follows from a fact
-measured for this slice: an Orca automation cannot reuse a session it did not
-start, so it cannot be pointed at a tab the kit made. It is written down in
-the tech notes.
+Grooming runs in a session in the book, on Claude Code's own scheduler,
+because the owner decided on 2026-09-24 (#223) that scheduled work does not use
+an Orca automation: an automation cannot carry a model or an effort of its
+own. Its runs share one long conversation, which the owner accepted in the
+same decision ("just do /compact when needed, add to the skill"). What a run
+must remember still lives in files, because a compacted conversation keeps
+only a summary. The facts about Claude Code's scheduler are in the tech notes.
 
 ## Ideas taken from material with no licence
 
@@ -109,3 +111,17 @@ Sources and licences in full: [LICENSES.md](LICENSES.md).
   expected). The load limit and where the memory lives are the tech notes'
   facts, verified live on Claude Code 2.1.280; Codex's store is the user's and
   is left alone.
+
+## What moving to Claude Code's scheduler changed (#237)
+
+- Where it remembers: the runs share one conversation now, so the files are
+  kept because a compact leaves a summary and a `/clear` leaves nothing, rather
+  than because each run starts fresh.
+- Turning it on: a `grooming` session in the book with its own model and
+  effort, a run by hand with `obk groom --now`, then `--on --at` after the yes.
+  That it fires only while its tab is up, the week-long limit each run renews,
+  and what a `/clear` does are Claude Code's documented behaviour, in the tech
+  notes.
+- Compacting is new, from the owner's decision on #223. Who types `/compact`
+  (the management session, through the kit) is the architect's reading of it on
+  #237.

package/skills/obk-grooming/SKILL.md

@@ -53,17 +53,20 @@ say what was and was not looked at rather than taking the report's word for it.
 
 ## Where it remembers
 
-Each run is a fresh conversation, so everything it knows from the last one is
-in files in the bots folder: the window and the open findings in a `grooming/`
-folder unless the project already keeps them elsewhere, and the profile notes
-in `profiles/`, where the fleet's rules tell every bot to look. Say at the top
-of each what it is. A run that cannot find
+The runs share one long conversation, and a compacted conversation keeps a
+summary of the earlier runs, not their detail; a `/clear` keeps nothing. So
+everything a run needs from the last one is in files in the bots folder: the
+window and the open findings in a `grooming/` folder unless the project already
+keeps them elsewhere, and the profile notes in `profiles/`, where the fleet's
+rules tell every bot to look. Say at the top of each what it is. Trust the
+files over what the conversation seems to remember. A run that cannot find
 them says so and reads less, not everything.
 
 The open findings are what stops the same thing being reported every day:
 before filing an issue or sending feedback, look there, and where it is already
 open, add to it rather than raising it again. Take a finding off when it is
-fixed or no longer true. Commit these once a day, at the end of the run.
+fixed or no longer true. Commit these at the end of each run, naming each
+file when you stage it and again in the commit.
 
 ## Keep the run bounded
 
@@ -212,11 +215,45 @@ places and sending one to the other loses it.
 
 ## Turning it on
 
-Do not schedule a pass nobody has watched. Run it by hand once, read what it
-produced, and fix the run rather than the report. So `obk groom --at <HH:MM>`
-creates it off, and `obk groom --on` turns it on after one explicit yes from
-the user who has read a run. Tell them what it will cost them each day before
-they say it. Make it through that command rather than by hand, so there is only
-ever one.
+The pass runs in a session of Bot Father's own, `grooming`, on Claude Code's
+own scheduler. Add it like any session, with the model and effort it is to run
+at: `obk session add --bots <folder> --bot bot-father --name grooming --model
+<m> --effort <e>`, with `--harness claude` where Bot Father runs on Codex, then
+`obk up`. Its launch line carries them, so they are what every run uses.
+
+Do not schedule a pass nobody has watched. `obk groom --now` runs it once in its
+tab; read what it produced, and fix the run rather than the report. Then, after
+one explicit yes from the user who has read a run, `obk groom --on --at <HH:MM>`
+schedules it. Tell them what it will cost them each day before they say it.
+Schedule it through that command rather than by hand, so there is one job and
+the kit can see it. `obk groom` says what is scheduled, and says so plainly
+when there is none or more than one.
+
+It fires only while its tab is open in Orca and Claude Code is idle in it, up to
+half an hour after its time, and a day it misses is not made up. Tell the user
+that before they rely on it. Claude Code ends a recurring job a week after it
+was made, so each run renews its own; a week with no run ends it, and then
+`obk groom --on --at <HH:MM>` puts back what the user agreed to. A `/clear` in
+its tab leaves it running: the job belongs to the running Claude Code, not to
+one conversation. It keeps running until the session is next restarted or
+Orca restores its tab: a resume brings back only the jobs of the conversation
+it resumes, so after a `/clear` and then a restart the job is gone. `obk groom`
+says so, and `--on --at` puts it back.
+
+## Compacting
+
+The runs share one conversation and each adds to it, so each run carries more
+than the last and costs more. A compact shrinks it to a summary. The run cannot
+do it: a scheduled run cannot type a built-in command, and a session cannot
+compact itself. So the report says when one is due, and the management session
+does it between runs with `obk groom --compact`.
+
+One is due when the run's calls carry about half the model's context window.
+`obk usage --bots <folder> --bot bot-father --session grooming --since <this
+run's start>` gives the run's calls and tokens: input, cache read and cache
+write together, divided by the calls, is roughly what each call carried.
+Claude Code also compacts on its own near the limit. That is the backstop, not
+the plan: it comes when the conversation is full, most likely in the middle of
+a run.
 
 Sources and licences: [NOTICE.md](NOTICE.md).

package/src/book.js

@@ -122,9 +122,7 @@ export async function updateBook(home, change) {
 /**
  * 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.
+ * the book.
  *
  * 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
@@ -142,7 +140,7 @@ export async function updateBook(home, change) {
  * 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) {
+function takeLock(home) {
   const file = lockFile(home);
   mkdirSync(path.dirname(file), { recursive: true });
 

package/src/bot.js

@@ -59,7 +59,7 @@ export function botNames(bots) {
  * link the user made takes it out of that folder; undefined when it stays in.
  *
  * The kit writes only in the bot folder, never in user-level settings (PRD 6.3,
- * ADR 0020), and a link would make the one the other without a word. So the
+ * ADR 0022), and a link would make the one the other without a word. So the
  * answer is the file system's, not the spelling's: see `whereItLeads`.
  */
 export function leadsOutside(home, target) {

package/src/cli.js

@@ -13,7 +13,7 @@ import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 
 import { addSession, changeBot, changeSession, createBot, leadsOutside, readBot, SESSION_FIELDS } from './bot.js';
-import { grooming } from './groom.js';
+import { addCommand, groomCommand, grooming, upCommand } from './groom.js';
 import { checkHealth, orcaSettingFindings } from './health.js';
 import { initBots } from './init.js';
 import { APPROVALS, HARNESSES, ownCli, shellWord, workDirOf } from './launch.js';
@@ -164,13 +164,18 @@ Usage:
                             with its settings, its tab and the conversation it
                             is in. It reads your files and reports them as they
                             stand; what to make of them is yours.
-  obk groom --bots <path> [--at <HH:MM>] [--on | --off]
-                            Say whether the daily grooming exists, when it runs
-                            and whether it is on, and set it up or change it
-                            when you ask. --at makes one, in Bot Father's Orca
-                            project. It is made off, because it spends tokens
-                            every day: run it by hand once, read what it gives
-                            you, then --on.
+  obk groom --bots <path> [--on [--at <HH:MM>] | --at <HH:MM> | --off | --now | --compact]
+                            Say what the daily grooming is: Bot Father's session
+                            grooming, and the job scheduled in it on Claude
+                            Code's own scheduler. Add that session like any
+                            other, with the model and effort each run is to use.
+                            --now asks it to run the grooming once. --on --at
+                            asks it to schedule it daily, and each run renews
+                            it; it starts off, because it spends tokens every
+                            day, so run it by hand once and read it first. --at
+                            moves it, --off unschedules it, and --compact
+                            compacts its conversation between runs. It fires
+                            only while its tab is up in Orca.
   obk usage --bots <path> [--bot <bot>] [--session <name>] [--since <time>] [--until <time>]
                             Say what your sessions have used: the conversations
                             each one had, their calls and tokens, the models and
@@ -281,6 +286,8 @@ async function run(argv) {
       at: { type: 'string' },
       on: { type: 'boolean' },
       off: { type: 'boolean' },
+      now: { type: 'boolean' },
+      compact: { type: 'boolean' },
       skill: { type: 'string' },
       repo: { type: 'string' },
       ref: { type: 'string' },
@@ -355,7 +362,7 @@ async function run(argv) {
 /**
  * The bots folder as the file system knows it. A folder reached through a
  * symlink is the same fleet: the harnesses file their transcripts under the real
- * path, Orca records an automation's workspace by it, and what the kit keeps
+ * path, and what the kit keeps
  * beside the folder (the skill sources, the start prompts, the messages) is
  * named after it. Asked by one spelling and then another, a fleet would
  * otherwise have two of each, and a pin set through one is undone through the
@@ -414,7 +421,7 @@ const RECORD = 'session record';
  * A hook runs inside the user's own session, so this one stays out of the way:
  * it writes on standard output only what the harness is to read as JSON, and
  * whatever goes wrong, it goes wrong quietly. A book left stale is a thing the
- * health check finds later; a session disturbed is the user's work (ADR 0020).
+ * health check finds later; a session disturbed is the user's work (ADR 0022).
  */
 async function record(bots, bot) {
   try {
@@ -658,11 +665,16 @@ const commands = {
 
   groom(bots, values) {
     refuseWhenOrcaIsDown();
-    if (values.on === true && values.off === true) {
-      throw new Error('groom takes --on or --off, and got both. Say which one you want.');
+    const asks = ['on', 'off', 'now', 'compact'].filter((flag) => values[flag] === true);
+    if (asks.length > 1) {
+      throw new Error(`groom asks for one thing at a time, and got ${asks.map((flag) => `--${flag}`).join(' and ')}. Say which one you want.`);
     }
-    const on = values.on === true ? true : (values.off === true ? false : undefined);
-    const groom = grooming(bots, { at: values.at, on });
+    if (values.at !== undefined && asks.length === 1 && asks[0] !== 'on') {
+      throw new Error(`--at is the time grooming runs at, and goes with --on, not with --${asks[0]}.`);
+    }
+    // --at on its own moves grooming that is on to another time.
+    const ask = asks[0] ?? (values.at === undefined ? undefined : 'move');
+    const groom = grooming(bots, { at: values.at, ask });
     return { answer: { bots, groom }, lines: groomLines(groom, bots) };
   },
 
@@ -1023,26 +1035,81 @@ function conversationLine(one) {
 }
 
 /**
- * What there is to say about the daily grooming: whether it exists, when it
- * runs, and whether it is on. A grooming that is off is not a fault, so this
- * says what is there and what the next step would be rather than warning.
+ * What there is to say about the daily grooming: the session it runs in, the
+ * jobs scheduled there, and what this run asked of it. Grooming that is off is
+ * not a fault, so this says what is there and what the next step would be;
+ * no job where one was expected, or more than one, is said plainly, because
+ * either means the fleet is groomed a different number of times a day than
+ * anyone decided.
  */
-function groomLines(groom, bots) {
-  if (!groom.exists) {
+function groomLines({ session, jobs, asked }, bots) {
+  const head = 'groom'.padEnd(9);
+  const more = ' '.repeat(11);
+  const said = asked === null ? [] : [ASKED[asked]];
+
+  if (session === null) {
+    return [
+      ...said,
+      `${head}  off: Bot Father has no session called grooming, which is where it runs`,
+      `${more}It runs in that session, on Claude Code's own scheduler. Give the session`,
+      `${more}--model and --effort for what each run is to use.`,
+      `Add it:    ${addCommand(bots)}`,
+      `Then:      ${upCommand(bots)}`,
+    ];
+  }
+  if (session.harness !== 'claude') {
     return [
-      `${'groom'.padEnd(9)}  there is no daily grooming yet`,
-      `Make one:  ${shellWord(ownCli())} groom --bots ${shellWord(bots)} --at 04:00`,
+      ...said,
+      `${head}  off: Bot Father's grooming session runs on ${session.harness}, and grooming runs`,
+      `${more}on Claude Code's own scheduler, so it has to be a Claude Code session: retire`,
+      `${more}it and add it again with --harness claude.`,
     ];
   }
 
+  const lines = [...said];
+  if (!session.up) {
+    lines.push(`${head}  Bot Father's grooming session is not up, so nothing fires`);
+    lines.push(`Bring it up:  ${upCommand(bots)}`);
+  }
+  if (asked === null) lines.push(...jobLines(jobs, bots, session.up ? head : more));
+  lines.push(`${more}It fires only while its tab is up in Orca and Claude Code is idle there, up to`);
+  lines.push(`${more}half an hour after its time, and a run it misses is not made up.`);
+  return lines;
+}
+
+/** What is scheduled in the grooming session's conversation. */
+function jobLines(jobs, bots, head) {
+  const more = ' '.repeat(11);
+  if (jobs.length === 0) {
+    return [
+      `${head}  off: its conversation has no grooming job`,
+      `${more}It spends tokens every day. Run it by hand first:  ${groomCommand(bots)} --now`,
+      `Turn it on, once the user has read a run and said yes:  ${groomCommand(bots)} --on --at 04:00`,
+    ];
+  }
+  if (jobs.length === 1) {
+    const [job] = jobs;
+    return [
+      `${head}  on, daily at ${job.at ?? job.cron}  job ${job.id}`,
+      `${more}Each run renews it; with no run, Claude Code ends it at ${job.expires}.`,
+      `Turn it off:  ${groomCommand(bots)} --off`,
+    ];
+  }
+  const times = [...new Set(jobs.map((job) => job.at))];
   return [
-    `${'groom'.padEnd(9)}  daily at ${groom.at}  ${groom.enabled ? 'on' : 'off'}`,
-    groom.enabled
-      ? `It runs every day at ${groom.at} and spends tokens each time. Turn it off with:  ${shellWord(ownCli())} groom --bots ${shellWord(bots)} --off`
-      : `It is not running yet. Try it by hand, read what it gives you, then:  ${shellWord(ownCli())} groom --bots ${shellWord(bots)} --on`,
+    `${head}  ${jobs.length} grooming jobs, so the fleet is groomed ${jobs.length} times a day: ${jobs.map((job) => `${job.id} at ${job.at ?? job.cron}`).join(', ')}`,
+    `Back to one:  ${groomCommand(bots)} --on${times.length === 1 && times[0] !== undefined ? '' : ' --at <HH:MM>'}`,
   ];
 }
 
+/** What each ask typed into the grooming tab, as the line that says so. */
+const ASKED = {
+  on: `${'asked'.padEnd(9)}  the grooming session to schedule the grooming, in a line typed into its tab. It is listed once the session has done it.`,
+  off: `${'asked'.padEnd(9)}  the grooming session to delete its grooming jobs, in a line typed into its tab.`,
+  now: `${'asked'.padEnd(9)}  the grooming session to run the grooming once, now. Its report goes to Bot Father's management session.`,
+  compact: `${'asked'.padEnd(9)}  the grooming session to compact its conversation: /compact was typed into its tab.`,
+};
+
 /** The settings a session carries, in the order a session is written down. */
 const SHOWN = SESSION_FIELDS.filter((field) => field !== 'name' && field !== 'harness');
 

package/src/conversations.js

@@ -49,10 +49,16 @@ export function conversationsIn(harness, home, since) {
  * is opened, however many conversations the machine has.
  */
 export function hasConversation(harness, home, id) {
-  if (harness === 'claude') return existsSync(path.join(claudeDir(home), `${id}.jsonl`));
+  if (harness === 'claude') return existsSync(claudeTranscript(home, id));
   return rollouts(codexDir()).some((file) => path.basename(file).endsWith(`-${id}.jsonl`));
 }
 
+/**
+ * Where Claude Code keeps the conversation `id` of this bot home, whether or
+ * not it has written it yet.
+ */
+export const claudeTranscript = (home, id) => path.join(claudeDir(home), `${id}.jsonl`);
+
 /**
  * The same conversations, each with the file the harness keeps it in, for a
  * caller that has to read what is inside one rather than only know it is there,