@open-tomato/rafa 0.44.0 → 0.46.0

package/README.md

@@ -182,9 +182,11 @@ the next one, so you rarely have to remember it.
    stored, one commit. A task that reports `blocked` is marked and the
    run stops with the reason; fix what it names and start again, and the
    blocked task goes first. After the last task a wrap-up session syncs
-   with the base, commits a release fragment when the project has them
-   (the plan's level and notes), pushes, opens the pull request and waits
-   for CI, spending repair sessions on a red one.
+   with the base and rewrites the release fragment's notes into changelog
+   lines, when the project has fragments. The loop writes the fragment
+   (the plan's level and notes) and commits it, pushes, opens the pull
+   request and waits for CI, spending repair sessions on a red one. The
+   version and the changelog are left to `rafa release settle`.
 
    From another terminal: `rafa loop status`, `rafa loop pause` (after the
    running task), `rafa loop stop` (now).
@@ -205,12 +207,12 @@ the next one, so you rarely have to remember it.
 
 ### Release fragments and settling
 
-A branch no longer owns a version number. Instead, the wrap-up commits a
-release fragment (a small markdown file naming the plan, level and notes),
-and `rafa release settle` assigns the version on the base branch after
-merges. This lets several branches merge in any order without a version
-collision: whichever machine settles first releases all waiting fragments
-under one version.
+A branch no longer owns a version number. Instead, the loop's wrap-up
+writes and commits a release fragment (a small markdown file naming the
+plan, level and notes), and `rafa release settle` assigns the version and
+folds the changelog on the base branch after merges. This lets several
+branches merge in any order without a version collision: whichever
+machine settles first releases all waiting fragments under one version.
 
 The pull request shows a forecast of what version the branch would get if
 merged now. The fragment is stored under `release.fragments` (default
@@ -218,10 +220,19 @@ merged now. The fragment is stored under `release.fragments` (default
 waiting and suggests running settle. `rafa pr list` marks forecasts as
 `(base moved)` if the base branch changed since the forecast was written.
 
+A workspace package under `packages/` that is not `private: true` can release
+on its own. A fragment names it with a fourth front-matter line,
+`package: <name>` (the package's manifest `name`); a fragment without the line
+is the root's. Settle then moves that package's version, changelog and tag
+beside the root's, and `rafa release list` prints one row per unit that
+releases: the root, then each publishable package, with its version, waiting
+fragments and newest tag. `context/release.md` has the rules.
+
 Every project starts with fragments settling to the base branch and tagging
 by hand. You can configure settle to open a pending release pull request
 instead (for protected base branches), and have settle tag the commit
-automatically (for CI ownership of releases). Four keys, all optional:
+automatically (for CI ownership of releases). Every key is optional; the
+examples below set `release.settle`, `release.tag` and `pr.versionCollision`:
 
 ```yaml
 # Empty config: fragments in .changes/, semver-by-level, settle pushes, tags by hand
@@ -242,14 +253,74 @@ pr:
   versionCollision: refuse
 ```
 
-The keys are: `release.fragments` (path, default `.changes/`), `release.strategy`
-(fold strategy, default `semver-by-level`), `release.settle` (`push` or `pr`,
-default `push`), `release.tag` (`manual` or `settle`, default `manual`),
-`release.publishCommand` (the publish line `rafa release tag` prints and never
-runs, default `npm publish`). `pr.versionCollision` controls what happens when a merge would collide
-(default `report`). Read `context/release.md` for the full design,
-`docs/ci-release-settle.md` for automating settle in CI, and
-`rafa release settle --help` for the settle command.
+The keys are: `release.fragments` (path, default `.changes/`),
+`release.strategy` (fold strategy, default `semver-by-level`),
+`release.settle` (`push` or `pr`, default `push`), `release.tag` (`manual` or
+`settle`, default `manual`), `release.publish` (`manual` or `ci`, who publishes
+a tagged version, default `manual`), `release.publishCommand` (the publish line
+`rafa release tag` prints and `rafa release publish` runs in each tagged unit's
+folder, default `npm publish`), `release.moveLock` (`true` has settle write
+`rafa.lock` in its release commit, default `false`), and `pr.versionCollision`
+(what happens when a merge would collide, default `report`). Read
+`context/release.md` for the full design, `docs/ci-release-settle.md` for
+automating settle in CI, and `rafa release settle --help` for the settle
+command.
+
+### The release ladder
+
+The release keys step a project up a ladder, one level at a time, from nothing
+on its own (0) to a release on every merge (4):
+
+| Level | `release.settle` | `release.tag` | `release.publish` | Runs on its own |
+|---|---|---|---|---|
+| 0 Manual | any | `manual` | `manual` | nothing |
+| 1 Settle tags | `push` | `settle` | `manual` | version, changelog and tag in one settle |
+| 2 CI publishes | `push` | `manual` | `ci` | a pushed tag runs the gates and publishes with provenance |
+| 3 Release PR | `pr` | `settle` | `ci` | every merge updates one release pull request; merging it tags and publishes |
+| 4 Continuous | `push` | `settle` | `ci` | every push to the default branch settles, then publishes the release it tags |
+
+`rafa doctor` prints the reading of the keys as its `Release ladder:` row, with
+what the level still needs. The row never refuses a setting. The release order
+across packages is parked until two publishable packages depend on each other.
+
+To move to level 2, where a pushed tag publishes, take four steps:
+
+1. Set the key in `.rafa/config.yaml`:
+
+   ```yaml
+   release:
+     publish: ci
+   ```
+
+2. Run `rafa release workflows --write`. It writes
+   `.github/workflows/release-publish.yml` from the shipped template. A file
+   already at that path is left as it is.
+3. On npmjs.com, add a trusted publisher for the package that names this
+   repository and `release-publish.yml`. Trusted publishing needs npm 11.5.1 or
+   newer.
+4. In the repository's GitHub settings, open Settings > Secrets and variables >
+   Actions > Variables, and add the repository variable `RAFA_RELEASE_PUBLISH`
+   with the value `ci`. From a shell, the same is:
+
+   ```bash
+   gh variable set RAFA_RELEASE_PUBLISH --body ci
+   ```
+
+Until the variable is `ci`, the publish job is skipped, and a skipped job is not
+a failed run. Then `rafa release tag --push` tags the release and pushes the
+tag, and the publish workflow runs the gates and publishes it with provenance.
+
+The release commands beyond settle and tag:
+
+```bash
+rafa release publish [--tag=<tag>] [--dry-run]   # publishCommand in each unit tagged at HEAD
+rafa release workflows [--write]                  # the ladder's workflow files
+rafa release fragment --plan=<id> --level=<level> --title=<text>   # a branch with no wrap-up
+```
+
+`rafa release publish` skips a version the registry already holds, so a rerun
+after a publish that stopped halfway publishes only the units the registry
+lacks.
 
 ### Tracking effort and learning from skills
 
@@ -263,8 +334,11 @@ rafa effort import <file>  # merge another device's store into this one
 ```
 
 `rafa effort report` shows the per-plan tables (sessions by status and
-outcome), the task report tallies, and any runs whose preflight halted. To
-see which skills earned their place and which are ignored:
+outcome), the task report tallies, any runs whose preflight halted,
+how many of the filed bugs name only documentation, and per plan its
+out-of-scope entries by the kind the loop routed them under, with the
+share filed. To see which skills earned their place and which are
+ignored:
 
 ```bash
 rafa effort report --skills
@@ -403,7 +477,12 @@ writes it; you can change it.
   `project` pin while a loaded user tier does; pin the tier the refusal
   names, or delete or rename the copy it names. `loop start` refuses a
   plan that names an agent or a skill it cannot resolve before any
-  session is paid for.
+  session is paid for. `rafa plan validate` names a plan whose task edits
+  an agent or a skill rafa bundles, with the pin that item needs, and
+  writes the pin as a `[human]` prerequisite of the plan, so a clone that
+  merges the plan sets the pin itself; that note is never a refusal. The
+  pin is not set at merge, since a pin is per clone and gitignored, and
+  one set unasked would hide the drift `doctor` shows.
 - User-tier items are invisible unless `loop.settingSources` includes
   `user`. `rafa agent list` shows what a run sees, `rafa agent vendor
   <name>` copies one in or updates it, and `rafa skill check .claude/skills
@@ -515,16 +594,121 @@ rafa· no pr            no open pull request for feat/rafa-485
 
 ## Configuration
 
-Settings live in `.rafa/config.yaml` in the project, and in
-`~/.rafa/config.yaml` for every project on the machine; a setting in the
-project's file outranks the same one in yours. `rafa init` writes both
-with every setting commented out at its default, so uncomment a line,
-with its section line, to change it.
+rafa reads its settings from one file per scope. The project scope is
+the repository's root; the user scope is `~/.rafa/`, read under every
+project on the machine. In each scope the lookup takes the first of
+three names that is a file, and the others are not read:
+
+1. `rafa.config.ts`, a TypeScript module
+2. `rafa.config.mjs`, a JavaScript module
+3. `.rafa/config.yaml` in the project, `~/.rafa/config.yaml` for the user
+
+The layers stack: rafa's defaults, under the user scope's file, under the
+project's. A setting the project's file names outranks the same one in
+the user's, key by key; a setting neither file names takes its default.
+`rafa init` writes both YAML files with every setting commented out at
+its default, so uncomment a line, with its section line, to change it.
 
 Tab indentation in `.rafa/config.yaml` is refused with rafa's own error
 on every Bun version, before the parser sees the file. The error names
 the line that carries a tab; use spaces only.
 
+### Which form to use
+
+Pick the lightest form your situation needs:
+
+- **No config at all.** rafa runs on its defaults, as it always has.
+- **An older project on YAML.** Nothing changes; `.rafa/config.yaml` is
+  read as before.
+- **A solo Python repository with rafa installed globally.** Write
+  `rafa.config.mjs` holding a plain list, or `rafa.config.ts` with only
+  an `import type`. The type import is erased before the file runs, so
+  nothing is needed at run time. A module that imports
+  `@open-tomato/rafa` at run time finds no such package here and is
+  refused, naming the file.
+- **A JS or TS project that installs rafa as a dev dependency.** Write
+  `satisfies Config` or `defineConfig`, both from
+  `@open-tomato/rafa/config`, and your editor checks the entries.
+- **A project moving from YAML to TypeScript.** For a while both files
+  sit side by side. The TypeScript file is read, and a warning names the
+  YAML file as not read; `rafa doctor` lists it until its keys have
+  moved, and then it can be removed.
+
+The same setting in each form:
+
+```yaml
+# .rafa/config.yaml
+naming:
+  branch: feat/{stub}
+```
+
+```js
+// rafa.config.mjs
+export default [{ naming: { branch: 'feat/{stub}' } }];
+```
+
+```ts
+// rafa.config.ts
+import type { Config } from '@open-tomato/rafa/config';
+
+export default [{ naming: { branch: 'feat/{stub}' } }] satisfies Config;
+```
+
+```ts
+// rafa.config.ts
+import { defineConfig } from '@open-tomato/rafa/config';
+
+export default defineConfig([{ dangerous: { selfUpdateDuringLoop: true } }]);
+```
+
+The import from `@open-tomato/rafa/config` is the one that needs the
+package installed where the file runs. For this iteration it can be
+solved with something simple attacking the type project specifically,
+but the bigger issue remains.
+
+Some routes were set aside, each for one reason. Merging both files of
+one scope is not done: a scope reads one file, so one answer per key.
+A Bun plugin redirecting the import does not resolve, as measured.
+Setting `NODE_PATH` and starting rafa again is not done: it would start
+a second process to load one file. Requiring a local install, as ESLint
+and Vite do, is not done: it would refuse the global Python case above.
+
+### Shadowed YAML and `rafa config show`
+
+When a scope holds a module file and a YAML file, the YAML file is not
+read, and every load says so:
+
+```text
+rafa config: /repo/.rafa/config.yaml is not read: /repo/rafa.config.ts holds the project scope's config, so move its keys into rafa.config.ts and remove it
+```
+
+`rafa config show` prints every setting with its merged value, nested
+as a config file spells it. `rafa config show --sources` prints one line
+per setting instead: its value, the layer that answered (`project`,
+`user` or `default`) and, for a file, the file and the zero-based entry
+that last set it; a YAML file is entry 0. `--output=json` carries the
+same data for a script. The two views are refused together.
+
+### Changing a key with `config set`
+
+`rafa config set <key>=<value>` edits the project's `.rafa/config.yaml`
+in place and keeps its comments. In a project whose config is
+`rafa.config.ts` or `rafa.config.mjs`, it refuses with exit 1, naming
+that file and writing nothing, because a module is code the command does
+not rewrite. Edit the module by hand until #893 gives the command a file
+to write.
+
+### `dangerous.*` settings
+
+A `dangerous.*` key is a person's consent, so rafa says what is in force:
+once per run, before its work starts, every command that loads the
+config prints one line for each `dangerous.*` key set off its default,
+naming the file and entry that set it, such as:
+
+```text
+dangerous.selfUpdateDuringLoop: true (/repo/rafa.config.ts, entry 0)
+```
+
 ### `effort`
 
 One setting says how long a command waits for another rafa process that
@@ -690,6 +874,52 @@ dangerous:
   selfUpdateDuringLoop: true   # update the binary even while a loop runs
 ```
 
+### `merge`
+
+One setting says what a load does when one key is set twice in a file.
+
+| Key | Default | What it sets |
+|---|---|---|
+| `merge.duplicates` | `warn` | `warn` prints each duplicate, `error` refuses the load with every one, `allow` drops them |
+
+Two entries of one module file setting one key, or a YAML key given
+twice, are duplicates. The project's file decides the level, over the
+user's. `config set` refuses a key written twice in the same file, as
+the same mistake.
+
+```yaml
+merge:
+  duplicates: error
+```
+
+### `naming`
+
+One setting names the branch `rafa loop start` creates for a plan.
+
+| Key | Default | What it sets |
+|---|---|---|
+| `naming.branch` | `feat/{stub}` | the branch name; `{stub}` appears exactly once and stands for the plan's stub |
+
+A template with no `{stub}`, or with it twice, is refused. The value is
+kept as written.
+
+```yaml
+naming:
+  branch: feat/{stub}
+```
+
+### Config code and `pr triage --resolve`
+
+A `rafa.config.ts` or `rafa.config.mjs` is a module rafa imports, so it
+runs with your shell, credentials and remotes. `pr triage --resolve`
+checks a pull request's branch out and starts a loop in it, and that loop
+loads whatever config the branch carries. So under `--resolve`, a head
+carrying a config module that `origin/<base>` does not hold as the same
+file (compared byte for byte) is refused with exit 1, before the worktree
+is added. Passing `--allow-local-config` runs it anyway and prints one
+warning line naming what it let through. A YAML config is data and is not
+checked this way.
+
 ## Specs, issues and the roadmap
 
 You can plan from a local file and never touch a board. When you want
@@ -782,6 +1012,9 @@ The full guide, with the spec template explained, a prompt for drafting
 a spec, epics, boards and every gate in order, is
 [docs/specs-and-roadmap.md](docs/specs-and-roadmap.md).
 
+The version policy, the bump levels, which package publishes and the
+`REFACTOR_NEEDED.md` rule are in [docs/versioning.md](docs/versioning.md).
+
 ## From a checkout
 
 To install dependencies:
@@ -798,7 +1031,7 @@ bun src/rafa.ts loop start --plan=<file>
 
 Every command but `init`, the help and `describe` runs inside a rafa
 project: the nearest directory at or above the working directory holding
-`.rafa/config.yaml`. Outside one it prints the `rafa init` hint and exits
+`rafa.config.ts`, `rafa.config.mjs` or `.rafa/config.yaml`. Outside one it prints the `rafa init` hint and exits
 1; `bun src/rafa.ts init --yes` sets up the git toplevel as one.
 
 `bun run build` writes `dist/`, which the `rafa` bin and the package's
@@ -819,16 +1052,20 @@ install the same way (`src/runtime/install.ts`). The bin is not in
 `~/.bun/bin`, where `bun link` in this checkout re-points `rafa` at the
 checkout's `dist/` with no message, so put `~/.rafa/bin` on `PATH` ahead
 of `~/.bun/bin`; both warn when it is not, and `rafa doctor` checks it.
-Both exit 1 before building anything while a plan tracker in `plan.dir`
-(`.rafa/plans` unless `.rafa/config.yaml` names another) still holds an
-open or blocked task, and name every such tracker. `rafa self-update`
-runs only inside a project, so `rafa init` the checkout first, and it
-also exits 1 while a loop of the project is live, naming each loop's
-branch and pid, unless `dangerous.selfUpdateDuringLoop` is true in the
-config; `--force` does not override that wait. They exit
-2 when they could not run: a `package.json` that is not rafa's or cannot
-be read, a config or tracker they could not read, a loop record
-`rafa self-update` could not read, or a build, copy or link that failed.
+A plan tracker in `plan.dir` (`.rafa/plans` unless `.rafa/config.yaml`
+names another) that still holds an open or blocked task holds an install
+back only while a loop of the checkout is live: both then exit 1 before
+building anything and name every such tracker, unless `--force` is on
+the line. With no loop live they install, one warning naming each such
+tracker, so a plan stopped halfway no longer blocks an update.
+`rafa self-update` runs only inside a project, so `rafa init` the
+checkout first, and it also exits 1 while a loop of the project is live,
+naming each loop's branch and pid, unless
+`dangerous.selfUpdateDuringLoop` is true in the config; `--force` does
+not override that wait. They exit 2 when they could not run: a
+`package.json` that is not rafa's or cannot be read, a config, tracker
+or loop record they could not read, or a build, copy or link that
+failed.
 
 A version is installed once. Both also exit 1, before building, when
 `~/.rafa/runtime/<version>/` is already there, naming that directory and
@@ -862,11 +1099,12 @@ takes `--yes`. The rest of `rafa update` (`self`, `project`, `board`,
 The build targets bun, and `engines` names `bun` alone: there is no
 `engines.node`, because no node version runs the binary. The package
 root, `./cli` and `./store` import `bun:sqlite`, which node's ESM loader
-refuses before any module code runs, so only `./plan`, `./ports` and
-`./learning` load under node at all. `module` points at
-`./dist/index.js`, the same build the root of `exports` names. The package ships no type declarations:
-`exports` names no `types`, and a TypeScript consumer gets TS7016 under
-`strict`.
+refuses before any module code runs, so only `./plan`, `./ports`,
+`./learning` and `./config` load under node at all. `module` points at
+`./dist/index.js`, the same build the root of `exports` names. Only
+`./config` ships type declarations, at `./dist/config/index.d.ts`, which
+its `exports` entry names as `types`. No other entry names `types`, and
+a TypeScript consumer importing one gets TS7016 under `strict`.
 
 ## Roadmap
 

package/dist/PROMPT.md

@@ -4,7 +4,16 @@ Do not stage or commit anything: the loop owns staging and committing, and once
 
 Run every command in the foreground, the full test suite included: never start a background command and never wait on a notification. This session is a single `claude -p` turn, so ending it to wait for something leaves no report and no commit; end the session only after your `rafa:report` block.
 
-End your final message with exactly one `rafa:report` block shaped like the example below, and write nothing after it: the loop stores what it reads there, and a message without the block stores none of your findings. Write all seven fields, `status`, `feedback`, `findings`, `skills_used`, `blockers`, `out_of_scope_bugs` and `changes`, and write a list with nothing in it as `[]` rather than leaving its field out. `status` is `done` or `blocked`. `feedback` says what was done and how it went. `findings` is a list with one entry per distinct observation, never several merged into one; a finding's `kind` is one of `gotcha`, `pattern`, `location` or `skill-suggestion`, its `signal` is `loud` when it surfaced as a failure or `silent` when something passed while wrong, and its `artifact`, when there is one, is the exact string a recurrence would match on, such as an error message. A finding may also carry a `domain`, the area of work its lesson belongs to, one of `code-style`, `testing`, `git`, `debugging`, `workflow`, `security` or `general-best-practices`; leave it out when none fits. `skills_used` names each skill you invoked. `blockers` lists what stopped the task, each entry a `what` and, when there is one, an `artifact`, `out_of_scope_bugs` the bugs you saw outside it, each bug with `security` set to `true` or `false` — a test type error that the task's base already held is part of the measured backlog and is not reported as a bug, and the type step's line names how many errors the base held — and `changes` is the changelog for your diff, each entry holding the required fields `level` (one of patch, minor, major, none) and `summary` (a quoted line the user would understand), plus optional `area` (the changelog section). Write those closed-set words and `security` bare, as the example does, and double-quote every other value on one line: an unquoted value that opens with a backtick, `@`, `%` or `[` makes the whole block unreadable, and a `#` after a space silently cuts a value short.
+End your final message with exactly one `rafa:report` block shaped like the example below, and write nothing after it: the loop stores what it reads there, and a message without the block stores none of your findings. Write all eight fields, `status`, `feedback`, `findings`, `skills_used`, `blockers`, `out_of_scope_bugs`, `changes` and `stale_docs`, and write a list with nothing in it as `[]` rather than leaving its field out. `status` is `done` or `blocked`. `feedback` says what was done and how it went. `findings` is a list with one entry per distinct observation, never several merged into one; a finding's `kind` is one of `gotcha`, `pattern`, `location` or `skill-suggestion`, its `signal` is `loud` when it surfaced as a failure or `silent` when something passed while wrong, and its `artifact`, when there is one, is the exact string a recurrence would match on, such as an error message. A finding may also carry a `domain`, the area of work its lesson belongs to, one of `code-style`, `testing`, `git`, `debugging`, `workflow`, `security` or `general-best-practices`; leave it out when none fits. `skills_used` names each skill you invoked. `blockers` lists what stopped the task, each entry a `what` and, when there is one, an `artifact`, `out_of_scope_bugs` what you saw wrong outside it, each entry a `what`, an `artifact` when there is one, `security` set to `true` or `false`, a `kind` from the six listed after this paragraph, and the optional `module`, `action`, `reproduce` and `cause` keys, which may be left out, with `reproduce` and `cause` always double-quoted — a test type error that the task's base already held is part of the measured backlog and is not reported as a bug, and the type step's line names how many errors the base held — and `changes` is the changelog for your diff, each entry holding the required fields `level` (one of patch, minor, major, none) and `summary` (a quoted line the user would understand), plus optional `area` (the changelog section). `stale_docs` lists the documentation lines you saw that no longer match the code, each entry a `where` (the file, with the line when known, as one string such as "context/triage.md:12") and a `what` (what no longer matches). A doc line your own change falsified is not an entry: repair it in the same commit as the change. Any other stale doc line you come across goes into `stale_docs` and never into `out_of_scope_bugs`. Write those closed-set words, `security` and an entry's `kind` bare, as the example does, and double-quote every other value on one line: an unquoted value that opens with a backtick, `@`, `%` or `[` makes the whole block unreadable, and a `#` after a space silently cuts a value short.
+
+An `out_of_scope_bugs` entry's `kind` is one of six, a different list from a finding's `kind`:
+
+- `bug` applies when the code does the wrong thing and nothing this plan did caused it.
+- `own-fallout` applies when an earlier task of this plan broke something, or left it stale, outside your task.
+- `own-gap` applies when this plan built something and left it unfinished, short of what your task needs or the plan describes.
+- `convention` applies when the code works but breaks a house rule, such as a file over the line ceiling or a name off the pattern.
+- `docs` applies when the leftover is a documentation fault larger than one stale line, since a single stale doc line goes into `stale_docs` instead.
+- `machine` applies when the fault lies in this machine or its setup, such as a missing tool or an unreachable service, rather than in the code.
 
 ```rafa:report
 status: done
@@ -25,7 +34,15 @@ out_of_scope_bugs:
   - what: "..."
     artifact: "..."
     security: false
+    kind: bug
+    module: "src/report"
+    action: "parse the entry"
+    reproduce: "run the report parser on an entry with the four keys"
+    cause: "the parser did not read the optional keys"
 changes:
   - level: patch
     summary: "the loop waits for the running task's commit"
+stale_docs:
+  - where: "context/triage.md:12"
+    what: "says triage has three channels"
 ```

package/dist/adapters/logger/settings.d.ts

@@ -0,0 +1,132 @@
+/**
+ * The logger's settings: what `logger.*` in the config says, held where
+ * every logger of the process can read it (#950).
+ *
+ * The dispatcher builds a command's logger before the project is found,
+ * and a command loads its config later. So the settings cannot be handed
+ * to the logger when it is made: `loadConfig`
+ * (`packages/rafa/src/core/config/config-load.ts`) calls core's load hook once a
+ * config is read, as it sets the effort store's settings, and the hook
+ * `src/config-registry.ts` sets hands the logger section's reading to
+ * this module. A logger reads them at each entry. Until then the default
+ * applies, with the invocation's verbosity beside it.
+ *
+ * This module imports types and `node:async_hooks` alone, so the
+ * registry can import it without pulling an adapter in.
+ *
+ * ## Where they are held
+ *
+ * In two places, and {@link activeLoggerSettings} and
+ * {@link setActiveLoggerSettings} both act on the first that applies:
+ *
+ *   - **A scope.** {@link runWithLoggerSettings} runs a function with
+ *     settings of its own in an async scope, an `AsyncLocalStorage`
+ *     (`node:async_hooks`). Inside that function, and in everything it
+ *     awaits or starts, the reader answers the scope's settings and the
+ *     setter replaces them. Once the function ends, however it ends,
+ *     nothing of them is left. The dispatcher runs every command this
+ *     way, starting from the defaults (`src/cli/dispatch.ts`), so the
+ *     config a command loads sets that invocation's settings alone.
+ *   - **The module-level value.** Outside every scope the reader answers
+ *     one module-level value and the setter replaces it, the defaults
+ *     until something sets another. A config loaded outside every
+ *     command sets it, as the module loader (`src/modules/load.ts`) and
+ *     the command hook (`src/status/hook.ts`) load one around an
+ *     invocation; no command reads it.
+ *
+ * A scope belongs to one run, so runs need not nest to stay apart. Two
+ * that overlap in one process, started together and awaited with
+ * `Promise.all`, each read and set their own whichever ends first. A
+ * scope opened inside another starts from the settings it is given,
+ * never from the outer one's, and the outer one reads its own again
+ * after it. A module-level value set and put back in a `finally` keeps
+ * overlapping runs apart only while they nest (#927).
+ *
+ * ## A set made inside a scope
+ *
+ * It replaces that scope's settings, and never the module-level value.
+ * This is where the settings differ from the active output
+ * (`packages/rafa/src/core/output/active.ts`), whose scope cannot be replaced from
+ * inside it: the config naming the settings is loaded inside the run
+ * that reads them, so the setter has to reach the run it is called in.
+ * The scope therefore holds a cell, and a set swaps the frozen settings
+ * the cell holds.
+ *
+ * ## What reads outside the scope
+ *
+ * A scope follows the awaits and the callbacks started inside it, by
+ * where the code runs and not by where it was written: a function made
+ * in one invocation and called from another reads the caller's. A
+ * callback the runtime calls from elsewhere does not carry it, and reads
+ * and sets the module-level value. Measured under bun 1.3.14, three
+ * listeners registered inside a scope read the module-level settings: a
+ * `process.on` signal listener when the signal arrived, an abort
+ * listener that handler fired, and an abort listener an
+ * `AbortSignal.timeout` fired. A timer, a microtask and the code after
+ * an await read the scope's, and so did a signal listener wrapped with
+ * `AsyncResource.bind` where it was registered.
+ *
+ * ## Which entries are on
+ *
+ * `error`, `warn` and `debug` are ordered, quietest first
+ * ({@link LOG_LEVELS}). An entry is on when its level is at or quieter
+ * than the threshold: the level its module has in `modules`, else
+ * `level`. `debug` is also on from verbosity {@link DEBUG_VERBOSITY}.
+ *
+ * `api` sits outside that order. It is on when `api` is true or from
+ * verbosity {@link API_VERBOSITY}, and nothing else turns it on: a
+ * level of `debug` asks for rafa's own reasoning, never for the traffic
+ * to a service.
+ *
+ * Bun runs every test file in one process and the module-level value is
+ * module state, so a case that sets settings outside a scope sets `null`
+ * after it.
+ */
+import type { LogLevel } from '@open-tomato/rafa/ports/log-level';
+/** How a logger colours its lines. */
+export type LoggerTheme = 'default' | 'plain';
+/** The ordered levels, quietest first. `api` is not one of them. */
+export declare const LOG_LEVELS: readonly LogLevel[];
+/** Every theme, in the order a refusal names them. */
+export declare const LOGGER_THEMES: readonly LoggerTheme[];
+/** The adapter kind core ships. */
+export declare const DEFAULT_LOGGER_KIND = "console";
+/** The verbosity at and above which `debug` entries are on. */
+export declare const DEBUG_VERBOSITY = 2;
+/** The verbosity at and above which `api` entries are on. */
+export declare const API_VERBOSITY = 3;
+/** What a logger reads at each entry. */
+export interface LoggerSettings {
+    /** The adapter kind. `logger.kind`. */
+    readonly kind: string;
+    /** The loudest ordered level written. `logger.level`. */
+    readonly level: LogLevel;
+    /** How lines are coloured. `logger.theme`. */
+    readonly theme: LoggerTheme;
+    /** A level per module, over `level`. `logger.modules.<module>.level`. */
+    readonly modules: ReadonlyMap<string, LogLevel>;
+    /** Whether a `debug` line names the file that wrote it. `logger.callSite`. */
+    readonly callSite: boolean;
+    /** Whether `api` entries are written. `logger.api`. */
+    readonly api: boolean;
+}
+/** The settings until a config is loaded. */
+export declare const DEFAULT_LOGGER_SETTINGS: LoggerSettings;
+/**
+ * Runs `run` with settings of its own in an async scope, starting from
+ * `settings`, the defaults for `null`, and answers what `run` answers.
+ * Inside `run` and whatever it awaits they are what is read and what a
+ * set replaces, and nothing of them is left after it; see the module
+ * note.
+ */
+export declare function runWithLoggerSettings<T>(settings: LoggerSettings | null, run: () => T): T;
+/**
+ * Sets the settings every logger reads from here on: those of the scope
+ * this is called in, else the module-level ones. `null` puts the
+ * defaults back. See the module note.
+ */
+export declare function setActiveLoggerSettings(settings: LoggerSettings | null): void;
+/** The settings a logger reads now: those of the scope this is read in, else the module-level ones. */
+export declare function activeLoggerSettings(): LoggerSettings;
+/** Whether an entry at `level` from `module` is written; see the module note. */
+export declare function levelEnabled(level: LogLevel, module: string | undefined, settings: LoggerSettings, verbosity: number): boolean;

package/dist/bugs/closest.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The names closest to a value a person typed (#951), for a refusal that
+ * says "closest: billing" beside the name it turns down.
+ *
+ * Names here are single words: a module, an action, a place. So the
+ * measure is edits between spellings ({@link editDistance}), never the
+ * shared words `src/errors/match.ts` counts for a cause written as a
+ * sentence. A name further than half the value's length, and further than
+ * {@link MIN_REACH} edits, is no suggestion: it is another word.
+ */
+/** How many names a refusal shows. */
+export declare const CLOSEST_LIMIT = 3;
+/** The single-character inserts, deletes and swaps that turn `a` into `b`. */
+export declare function editDistance(a: string, b: string): number;
+/**
+ * The `names` nearest `value` by edits, nearest first and by name where
+ * two tie, `limit` at most. See the module note for how far is too far.
+ */
+export declare function closestNames(value: string, names: readonly string[], limit?: number): readonly string[];

package/dist/bugs/fenced.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The fence a bug's free text is shown in, shared by the loop's own
+ * filing (`../triage/issue-text.ts`, which re-exports it) and the bug
+ * record (`./record.ts`). A leaf: it imports nothing, so either side
+ * reaches it without importing the other.
+ */
+/** A value in a fence one backtick longer than any run of backticks it holds. */
+export declare function fenced(value: string): string;

package/dist/bugs/places.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The places a bug is seen in (#951): the ones every project has, and
+ * the one rafa suggests.
+ *
+ * A place names WHERE a bug showed: `local`, `ci`, `prod`, or one a
+ * project adds under `issues.environments`. What was running belongs to
+ * the record's `action` and `reproduce`.
+ *
+ * rafa suggests `ci` when the `CI` variable is set to anything but
+ * nothing, `0` or `false`, and `local` otherwise. A filer's `--env` wins
+ * over the suggestion.
+ *
+ * This module imports nothing, so the config schema
+ * (`src/config-schema-issues.ts`) reads the built-in places without
+ * reaching the modules that read the config.
+ */
+/** The places every project has, in the order a refusal lists them. */
+export declare const BUILT_IN_ENVIRONMENTS: readonly ["local", "ci", "prod"];
+/** The place rafa suggests for a run with the environment `env`; see the module note. */
+export declare function suggestedEnvironment(env: Readonly<Record<string, string | undefined>>): 'ci' | 'local';