@open-tomato/rafa 0.44.0 → 0.46.0

package/dist/bugs/record.d.ts

@@ -0,0 +1,145 @@
+/**
+ * The bug record (#951): the fields every bug is filed with, the check
+ * that refuses a record missing one, the body the fields are written as,
+ * and the parser that reads a body back.
+ *
+ * ## Three axes
+ *
+ *   - The title, for a person reading a list: `summary`, rendered through
+ *     the project's template (`./title.ts`) with the boundary fields.
+ *   - The boundary, for knowing where two pieces of work overlap:
+ *     `project`, `module`, `action`.
+ *   - The context, for knowing what the error looked like and where:
+ *     `environment`, `versions`, `errorLine`, `artifact`, and the cause
+ *     (`cause`, `proposed`, `suspected`).
+ *
+ * `reproduce` and `rerun` stand beside them: the steps, or the condition
+ * that revealed the bug, and the one command that shows it again.
+ *
+ * ## The body
+ *
+ * One `## <Heading>` section per field that holds a value, in the order
+ * of {@link BUG_FIELDS}. Two headings are triage's own: the description
+ * is `What` and the error output is `Artifact`, both in the fence
+ * `fenced` writes (`./fenced.ts`). So triage's similarity
+ * step (`issueTextOf`, `../triage/similarity.ts`) reads a record as it
+ * reads a body the loop filed, and a body the loop filed parses as a
+ * record with the other fields missing.
+ *
+ * A value is written plain only when the check holds it to a token:
+ * the cause codes, the module, the action and the place. Every free text
+ * is fenced, so an `@name` or a `#12` inside it never pings or links on
+ * the tracker. The summary has no section: the title holds it.
+ *
+ * {@link parseBugRecord} reads `##` and `###` headings, a value in a
+ * fence or as text, and a heading inside a fence as text. A fence is
+ * three or more backticks or tildes, indented by three spaces at most,
+ * closed by a line of the same mark at least as long. `###` and
+ * `_No response_` are what a GitHub issue form writes
+ * (`.github/ISSUE_TEMPLATE/bug.yml`).
+ *
+ * Nothing a filer wrote is dropped without a word. The text ahead of the
+ * first heading is the description when no `What` section holds one, and
+ * {@link otherSections} answers the rest for the caller to file after
+ * the record's own sections: that text beside a `What` section, a
+ * section that is no field, and the second section under one heading.
+ *
+ * ## The check
+ *
+ * {@link bugProblems} answers every problem at once, each sentence
+ * opening with the field it names, so a filer fixes the line in one go.
+ * `module`, `action` and `environment` may be the word `unknown`;
+ * `reproduce` never is; `cause` is a code of the list, or
+ * `<family>:new-context` with the leaf the filer would have used kept as
+ * `proposed` (`context/error-codes.md`).
+ *
+ * Nothing here redacts: a caller takes local paths and secrets out of
+ * the values before it builds the record.
+ */
+import type { ErrorCodeEntry } from '@open-tomato/rafa/errors/codes';
+/** A bug's fields, each null until something fills it. */
+export interface BugRecord {
+    /** One line saying what is wrong; the title's last part. */
+    readonly summary: string | null;
+    /** The description. The `What` section. */
+    readonly what: string | null;
+    /** The steps, or the condition that revealed the bug. Never `unknown`. */
+    readonly reproduce: string | null;
+    /** One command that shows the bug again. */
+    readonly rerun: string | null;
+    /** The first line of the error output, with what changes between runs taken out. */
+    readonly errorLine: string | null;
+    /** The error output and its stack. The `Artifact` section. */
+    readonly artifact: string | null;
+    /** The cause code: one of the list, or `<family>:new-context`. */
+    readonly cause: string | null;
+    /** The leaf the filer would have used, beside a `new-context` cause. */
+    readonly proposed: string | null;
+    /** What the filer thinks went wrong, in words. */
+    readonly suspected: string | null;
+    /** The module the bug is in, or `unknown`. */
+    readonly module: string | null;
+    /** What was running: a command, a step, a test; or `unknown`. */
+    readonly action: string | null;
+    /** The project, where one tracker holds several. */
+    readonly project: string | null;
+    /** The place it was seen: `local`, `ci`, `prod`, one the project adds, or `unknown`. */
+    readonly environment: string | null;
+    /** The rafa version, the commit and the package, one `name: value` line each. */
+    readonly versions: string | null;
+}
+/** A record nothing has filled. */
+export declare const EMPTY_BUG_RECORD: BugRecord;
+/** How a field's value is written in a body; `unwritten` for one the body never holds. */
+export type BugFieldShape = 'fenced' | 'plain' | 'unwritten';
+/** One field: its key, the heading of its section, and how its value is written. */
+export interface BugFieldSpec {
+    readonly key: keyof BugRecord;
+    readonly heading: string;
+    readonly shape: BugFieldShape;
+}
+/** Every field, in the order a body writes them; see the module note. */
+export declare const BUG_FIELDS: readonly BugFieldSpec[];
+/** What a record is checked against: the project's template, caps, names and codes. */
+export interface BugRules {
+    /** The template the title is rendered with. */
+    readonly template: string;
+    /** The most characters a summary holds. */
+    readonly summaryMax: number;
+    /** The places a bug may name, without `unknown`, which is always one. */
+    readonly environments: readonly string[];
+    /** The module names accepted; empty for any name of the shape. */
+    readonly modules: readonly string[];
+    /** The actions accepted; empty for any of the shape. */
+    readonly actions: readonly string[];
+    /** The cause codes a bug may carry. */
+    readonly codes: readonly ErrorCodeEntry[];
+}
+/** True when `body` holds a section of the record. */
+export declare function hasBugSections(body: string): boolean;
+/**
+ * The record `body` holds: each field from the first section under its
+ * heading. The text ahead of the first heading is the description when
+ * no `What` section holds one, so a paragraph written above the sections
+ * is never dropped. See the module note.
+ */
+export declare function parseBugRecord(body: string): BugRecord;
+/**
+ * What `body` holds that {@link parseBugRecord} does not read, as
+ * written and in order; `''` for nothing. That is the text ahead of the
+ * first heading when a `What` section took its place as the description,
+ * every section whose heading names no field, and a section under a
+ * field's heading used a second time.
+ */
+export declare function otherSections(body: string): string;
+/** The body a record is filed with; `''` for a record holding nothing. See the module note. */
+export declare function renderBugBody(record: BugRecord): string;
+/** The title a record is filed under, rendered through the project's template. */
+export declare function bugTitle(record: BugRecord, rules: Pick<BugRules, 'template'>): string;
+/**
+ * Every problem of `record` under `rules`, in the order of
+ * {@link BUG_FIELDS}, or none. The last, that the title does not read
+ * back, is weighed only once the fields the title prints raised nothing.
+ * See the module note.
+ */
+export declare function bugProblems(record: BugRecord, rules: BugRules): readonly string[];

package/dist/bugs/title.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The title template (#951): one string that renders an issue's title
+ * from its fields and reads a title back into them.
+ *
+ * ## The syntax
+ *
+ *   - `${name}` prints a variable, one of {@link TITLE_VARIABLES}.
+ *   - `?( … )` is an optional group. It prints only when every variable
+ *     DIRECTLY inside it is printable ({@link isPrintable}): a group
+ *     nested in it decides for itself. A separator goes inside its group,
+ *     so a missing value takes its separator with it.
+ *   - Anything else is text. A `)` outside every group is text too.
+ *
+ * `null`, `undefined`, a blank string, the word `unknown` and anything
+ * that is no string are not printable. The issue's id is no variable: a
+ * tracker assigns it after the title is written, and a listing prints it
+ * as a column of its own.
+ *
+ * ## Reading back
+ *
+ * {@link parseTitle} turns the same template into a pattern: text is
+ * matched as written, a group is optional, and each variable is a named
+ * capture. `module` and `action` are read with the shape their values
+ * are held to ({@link MODULE_SHAPE}, {@link ACTION_SHAPE}), and the last
+ * variable reads the rest, so a `: ` inside the summary never splits it.
+ *
+ * One limit stays. Under the default template a summary shaped
+ * `<word>: …`, filed with no module, reads back with that word as its
+ * module. {@link titleRoundTrips} reports it, and the record check
+ * (`./record.ts`) refuses such a bug, naming the title.
+ *
+ * {@link templateProblem} is what a config reader calls: it refuses a
+ * template that cannot be parsed, one whose summary is not the last
+ * variable outside every group, and one whose own titles do not read
+ * back, tried over every way of leaving its other variables out.
+ */
+/** Every variable a template may name. */
+export declare const TITLE_VARIABLES: readonly ["type", "project", "projectType", "module", "action", "summary"];
+/** One variable's name. */
+export type TitleVariable = (typeof TITLE_VARIABLES)[number];
+/** The values a title is rendered from, and the ones read back from it. */
+export type TitleValues = {
+    readonly [K in TitleVariable]?: string | null;
+};
+/** One part of a parsed template. */
+export type TitleNode = {
+    readonly kind: 'text';
+    readonly text: string;
+} | {
+    readonly kind: 'variable';
+    readonly name: TitleVariable;
+} | {
+    readonly kind: 'group';
+    readonly nodes: readonly TitleNode[];
+};
+/** The word a filer writes for a field it cannot tell. Never printed in a title. */
+export declare const UNKNOWN_VALUE = "unknown";
+/** The template a bug's title is rendered with when the config names none. */
+export declare const DEFAULT_BUG_TITLE = "?(${module}?( - ${action}): )${summary}";
+/** What a module name looks like, as a pattern source with no anchors. */
+export declare const MODULE_SHAPE = "[a-z0-9][a-z0-9._-]*";
+/** What an action looks like: a module's shape, spaces allowed. */
+export declare const ACTION_SHAPE = "[a-z0-9][a-z0-9._ -]*";
+/** A template that cannot be parsed; its message says why. */
+export declare class TitleTemplateError extends Error {
+    constructor(message: string);
+}
+/** True for a value a title prints: a string that is not blank and not `unknown`. */
+export declare function isPrintable(value: unknown): value is string;
+/** A template's nodes. Throws a {@link TitleTemplateError} for one that cannot be read. */
+export declare function parseTitleTemplate(template: string): readonly TitleNode[];
+/** The title `template` renders from `values`. Throws for a template that cannot be read. */
+export declare function renderTitle(template: string, values: TitleValues): string;
+/**
+ * The values `title` holds under `template`, or null when it does not
+ * fit. Throws for a template that cannot be read, or that names a
+ * variable twice. See the module note.
+ */
+export declare function parseTitle(template: string, title: string): TitleValues | null;
+/** True when the title rendered from `values` reads back as the values it printed. */
+export declare function titleRoundTrips(template: string, values: TitleValues): boolean;
+/** Why `template` cannot be used, or null when it can. See the module note. */
+export declare function templateProblem(template: string): string | null;

package/dist/bundled/agents/doc-updater.md

@@ -96,9 +96,23 @@ file's wrapped lines before searching.
 
 ## Boundaries
 
-- A sentence your own change falsified is yours to repair in the same
-  commit. A stale sentence your change did not touch is reported, not
-  repaired.
+- A doc line your own change falsified is repaired in the same commit.
+  Any other stale doc line you find goes into the report's `stale_docs`
+  field, with `where` and `what`, and never into `out_of_scope_bugs`.
+- The doc task has two outputs beyond its own repairs. A row it could not
+  settle goes into its own `stale_docs` field. A row it finds to be about
+  code, not prose, goes into `out_of_scope_bugs`, which takes the kind the
+  rule below gives it.
+- **Kind of each out-of-scope entry.** Every entry of `out_of_scope_bugs`
+  carries a `kind`: `bug`, `own-fallout`, `own-gap`, `convention`, `docs`
+  or `machine`. `bug` is for code that does the wrong thing and that this
+  plan did not cause. What an earlier task of this plan broke or left
+  stale is `own-fallout`; what this plan built and left unfinished is
+  `own-gap`. A file too long or a name off the pattern is `convention`,
+  and this machine's fault is `machine`. A stale doc line goes into
+  `stale_docs`; `docs` is the fallback for one written in the wrong field.
+  The loop checks every `own-` claim, so a guess between `bug` and
+  `own-fallout` is written as `bug`.
 - Never commit, never push, never open a pull request, never merge. The
   loop owns all four, and `src/PROMPT.md` states what it does once this
   session exits cleanly. Leave your work in the tree in a state the

package/dist/bundled/agents/loop-implementer.md

@@ -21,8 +21,10 @@ with no `packages/` directory and no workspace boundaries to navigate.
   Where a reading could be a false negative, pair it with a control that
   proves the check could have failed.
 - **Same-commit doc law.** A change that falsifies a sentence in a tracked
-  document fixes that sentence in the same commit. An invariant's register
-  row moves with the artifact that enforces it.
+  document fixes that sentence in the same commit. Any other stale doc line
+  you find goes into the report's `stale_docs` field, with `where` and
+  `what`, and never into `out_of_scope_bugs`. An invariant's register row
+  moves with the artifact that enforces it.
 - **Style is enforced by ESLint and is not obvious.** Single quotes with no
   `avoidEscape`, three-line ternaries, `import type` first in its own
   block, parent and sibling as separate import groups. Write it, run
@@ -31,6 +33,16 @@ with no `packages/` directory and no workspace boundaries to navigate.
   past the width cap.
 - **Never widen scope.** The task is the deliverable. A real problem found
   outside it is reported, not fixed.
+- **Kind of each out-of-scope entry.** Every entry of `out_of_scope_bugs`
+  carries a `kind`: `bug`, `own-fallout`, `own-gap`, `convention`, `docs`
+  or `machine`. `bug` is for code that does the wrong thing and that this
+  plan did not cause. What an earlier task of this plan broke or left
+  stale is `own-fallout`; what this plan built and left unfinished is
+  `own-gap`. A file too long or a name off the pattern is `convention`,
+  and this machine's fault is `machine`. A stale doc line goes into
+  `stale_docs`; `docs` is the fallback for one written in the wrong field.
+  The loop checks every `own-` claim, so a guess between `bug` and
+  `own-fallout` is written as `bug`.
 
 ## Verification
 

package/dist/bundled/operators/skills/rafa-stretch-pit-stop/SKILL.md

@@ -28,7 +28,7 @@ of course, and never a reason to chase one issue down a rabbit hole.
 | Check | Line | What is wrong |
 |---|---|---|
 | Effort | `rafa effort dashboard` | cost per task drifting up against the baseline, not explained by the item's size |
-| Bugs | `rafa issue list --type=bug --limit=200` | the open count rising, or bugs filed during this loop that repeat an open one |
+| Bugs | the `Bugs:` and `Filed since` lines of the item's closing output | the open count rising, or a bug filed during this loop that repeats an open one |
 | Delivery | `rafa loop status`, `rafa pr list` | the run is done with no pull request, or its pull request did not merge |
 | Conflicts | `rafa pr show <pr>` | the pull request conflicts with the integration branch |
 | CI | `rafa ci status --branch=stretch/<n>` | the run failed (use `gh run view <id> --log-failed` to see why), or is still running |
@@ -37,6 +37,12 @@ A CI failure already red in the local runs is inherited and noted in the pit-sto
 A new failure is filed as one bug after a search for an existing one. A run still in progress
 is read at the next pit stop.
 
+The bugs come from the closing output of `rafa stretch item`: `Bugs: <n> open.`,
+then `Filed since <time>: <n>.` with one indented line per bug filed after the
+last item, open or closed since, as `#<n> <title>: <first line>`. `none` is a
+reading, not a failure. A line that says `not read` names its reason; read the
+bugs with `rafa issue list --type=bug --limit=200` when a reading is not read.
+
 A conflict goes to the resolve plans first:
 
 ```bash
@@ -58,8 +64,9 @@ only after reading the run's last `rafa·` lines.
    happens twice, when the hook rule fires, or when the fix would touch
    anything outside the integration branch.
 
-Anything else you find is filed, not fixed: one issue, after a search for
-an existing one, and the stretch goes on.
+A stale doc line you find is added to the release's stale-docs issue as one
+line, and no issue is filed for it. Every other finding is filed, not fixed:
+one issue, after a search for an existing one, and the stretch goes on.
 
 ## The entry
 

package/dist/bundled/operators/skills/rafa-stretch-sweep/SKILL.md

@@ -27,11 +27,16 @@ person's approval.
 ## Read the board
 
 ```bash
+rafa bug recheck --all
 rafa roadmap --full
 rafa issue list --type=bug --limit=200
 rafa effort report --trend
 ```
 
+`rafa bug recheck --all` reruns each open bug's test and prints one
+verdict per bug. A `gone` bug is closed by the sweep as fixed; a `flaky`
+one is grouped as a bug of its own, never read as fixed.
+
 Read the roadmap's "now" epics first: their members are where the
 project already said the work is.
 

package/dist/bundled/skills/dev-planner/SKILL.md

@@ -257,6 +257,18 @@ out_of_scope_bugs:
   - what: "bun:sqlite connection pooling"
     artifact: "SQLITE_MISUSE"
     security: false
+    kind: bug
+    module: "store"
+    action: "appending to an open store"
+    reproduce: "run the store tests against a shared connection"
+    cause: "the handle is shared across calls"
+changes:
+  - level: minor
+    area: "store"
+    summary: "the store reads and writes through one interface"
+stale_docs:
+  - where: "context/effort-store.md:41"
+    what: "says the store has one backend"
 ```
 ````
 
@@ -269,8 +281,9 @@ Report fields:
 | `findings` | list of objects | Findings discovered during the task (see below) |
 | `skills_used` | list of strings | Names of skills referenced or applied |
 | `blockers` | list of objects | What blocked the task. Any entry marks the task `[BLOCKED]` whatever `status` says, so write `[]` when nothing did |
-| `out_of_scope_bugs` | list of objects | Bugs found that are outside this task's scope |
+| `out_of_scope_bugs` | list of objects | Bugs and other leftovers found outside this task's scope, each with a `kind` (see below) |
 | `changes` | list of objects | Release notes for this task's own diff (contributing to the release fragment), one entry per user-visible change (see below). An absent list is empty with no issue; a task whose diff a user would notice nothing of writes one entry at level `none`. The wrap-up collects these from all tasks and writes them to the fragment that `rafa release settle` processes after the branch merges. |
+| `stale_docs` | list of objects | Documentation lines the task saw that no longer match the code and that its own change did not falsify (see below). An absent list is empty with no issue |
 
 Finding entry fields:
 
@@ -293,13 +306,43 @@ Change note entry fields:
 | `area` | string | no | The changelog section the line groups under (e.g., `cli`, `store`) |
 | `summary` | string | yes | One line a user of the project would understand, quoted |
 
-Blocker/bug entry fields:
+Stale doc entry fields:
 
 | Field | Type | Required | Description |
 | --- | --- | --- | --- |
-| `what` | string | yes | Description of the blocker or bug |
+| `where` | string | no | The file, with the line when known, as one string (e.g., `context/triage.md:12`). An entry without one is kept |
+| `what` | string | yes | What no longer matches. An entry without one is reported as an issue and dropped |
+
+Blocker entry fields:
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `what` | string | yes | Description of the blocker |
 | `artifact` | string | no | Error message or diagnostic output |
-| `security` | boolean | yes (bugs only) | Whether this is a security issue; never defaulted when missing |
+
+Out-of-scope bug entry fields:
+
+| Field | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `what` | string | yes | none | Description of the bug |
+| `artifact` | string | no | none | Error message or diagnostic output |
+| `security` | boolean | yes | none | Whether this is a security issue; never defaulted when missing |
+| `kind` | string | no | `bug` | What sort of leftover the entry is, one of the six below. An absent key reads as `bug` with no issue; a value outside the list is reported as an issue and read as `bug`. A different field from a finding's `kind`, with its own list |
+| `module` | string | no | `unknown` | The module the bug is in. Checked against the project's `issues.vocabulary.modules` when that is set, and read as any name of the shape when it is empty. A name outside the set is filed as `unknown`, with the word kept in the bug's record as `Reported module`; triage never refuses a bug over it |
+| `action` | string | no | `unknown` | What was running: a command, a step, a test. Checked against `issues.vocabulary.actions` the same way, the word kept as `Reported action` |
+| `reproduce` | string | no | "seen while running task <task line> of plan <stub>", or "seen while running `<command>`" for a dispatch with no plan stub | The steps, or the condition that revealed it. Double-quote it. A blank value or `unknown` takes the default: the bug record never holds `unknown` here |
+| `cause` | string | no | `unknown:new-context` | A cause code from `rafa bug codes`, or the cause in words. Double-quote it. A code the list lacks is filed as `<family>:new-context`, with the code kept as proposed, or as `unknown:new-context` when its family is unlisted; words that are no code are filed as `unknown:new-context`, with the words kept as the suspected cause |
+
+Out-of-scope entry kinds:
+
+| Kind | When it applies |
+| --- | --- |
+| `bug` | The code does the wrong thing, and this plan did not cause it |
+| `own-fallout` | Something an earlier task of this plan broke or left stale |
+| `own-gap` | Something this plan built and left unfinished |
+| `convention` | A file too long, a name off the pattern |
+| `docs` | A stale doc line |
+| `machine` | This machine's fault |
 
 ---
 
@@ -311,7 +354,7 @@ The block strip rule means:
 - A block in a stage description does not appear in the operator log line
 - A block anywhere in the plan does not appear in a commit subject or commit body
 
-The strip happens where the loop reads the next task, `findNextTask` in `src/utils/tracker.ts`, and it follows fences the way a renderer shows them (`src/plan/blocks.ts`):
+The strip happens where the loop reads the next task, `findNextTask` in `src/utils/tracker.ts`, and it follows fences the way a renderer shows them (`packages/rafa/src/core/plan/blocks.ts`):
 
 - Only a closed, top-level `rafa:*` block hides its lines. Every other fence is transparent, so a `- [ ] ` line at column 0 inside a `markdown` or `text` illustration, or inside a `rafa:` fence nested in one, is dispatched as a task. A plan that illustrates the format indents its example lines.
 - A `rafa:` fence that is never closed hides nothing, because taking the rest of the document as its body would end the plan with its tasks unrun. `parsePlan` reports it as `unclosed-block`, and each open task line after it as `task-in-block`.
@@ -335,11 +378,12 @@ The strip happens where the loop reads the next task, `findNextTask` in `src/uti
   holding no nested braces and at least one recognised key, and it is
   never the whole task text. Two spaces separate it from the text.
   Anything failing one of those rules stays task text — a task ending on
-  a code span carrying `{ "a": 1 }` is not a declaration. The one thing
-  that may follow the block is the loop's own: on a blocked task's
-  tracker line it writes `<!-- blocked: <text> -->` after the block, and
-  takes that comment off before the block is read. The plan itself never
-  holds one.
+  a code span carrying `{ "a": 1 }` is not a declaration. What may
+  follow the block is the loop's own: on a blocked task's tracker line
+  it writes `<!-- blocked: <text> -->` after the block, and on a repair
+  task's line `<!-- repairs: <text> -->` before that, naming the plan
+  task repaired. It takes both comments off before the block is read.
+  The plan itself never holds either.
 * Its tokens are space-separated `key=value` pairs, of the recognised keys
   in the table below; an unrecognised key is kept for telemetry and maps
   to no flag.
@@ -353,6 +397,7 @@ The strip happens where the loop reads the next task, `findNextTask` in `src/uti
 | `tools` | tool names, comma-separated with no spaces | `--tools` | never passed: the definition names its tool set |
 | `skills` | skill names, comma-separated with no spaces | nothing: no flag carries a skill | kept on the record beside the agent |
 | `tests` | `affected`, `module` or `full`; `affected` when absent | nothing: the loop's runner reads it | kept on the record beside the agent |
+| `docs` | `repair`, its one value; any other is recorded as an issue and read as absent | nothing: the loop reads it | kept on the record beside the agent |
 
 * `agent=<name>` outranks `model` and `tools`, and `effort` only when its
   definition declares one, as the last column says. The outranked keys
@@ -377,11 +422,11 @@ The strip happens where the loop reads the next task, `findNextTask` in `src/uti
 
 There is no default agent. A task with no declaration passes no routing flag and runs at the loop's defaults, as does one whose every value failed to parse.
 
-The recognised keys are the `DECLARATION_KEYS` of `src/utils/declaration.ts`, whose `MODEL_ALIASES`, `EFFORT_LEVELS` and `TEST_SCOPES` hold the aliases, levels and test scopes in the table, whose `parseBudgetUsd` reads a budget, whose `parseSkillList` reads a skill list and whose `readTestScope` reads a test scope; that module is the authority for this section, so change the two together.
+The recognised keys are the `DECLARATION_KEYS` of `packages/rafa/src/core/plan/declaration.ts`, whose `MODEL_ALIASES`, `EFFORT_LEVELS` and `TEST_SCOPES` hold the aliases, levels and test scopes in the table, whose `parseBudgetUsd` reads a budget, whose `parseSkillList` reads a skill list, whose `readTestScope` reads a test scope and whose `DOCS_ROLES` and `readDocsRole` hold and read the one `docs` value; that module is the authority for this section, so change the two together.
 
 ### `skills=` declaration
 
-When a task needs help from a skill, name those skills with `skills=`. Skill names must come from the skill index provided in this prompt; naming a skill no tier holds is recorded as an issue. Names are comma-separated with no spaces.
+When a task needs help from a skill, name those skills with `skills=`. Skill names must come from the skill index provided in this prompt. Naming a skill no tier holds is refused, not recorded: `rafa plan validate` exits 1 on the line that names it, and `rafa loop start`'s preflight refuses to start the plan, so nothing is dispatched. Names are comma-separated with no spaces.
 
 `skills` is a recognised key that maps to no flag: there is no CLI flag for a skill, so the names are parsed, kept on the dispatch record and stripped from the task text with the rest of the block. It stands on its own — `{skills=bun-testing}` is a declaration with no other key beside it — and a value that is not a comma-separated list of skill names is recorded as an issue rather than passed on.
 
@@ -411,6 +456,8 @@ The second example above has no `skills=` and is still a valid task declaration.
   - [ ] Move the test preload into `bunfig.toml`  {tests=full}
 ```
 
+A task's text never asks its session for a whole-suite run, or for any command that can outlast one Bash call, since the Bash tool stops a command at 10 minutes. The runner runs the suite through `tests=full` on the task. A task that needs a long run's output reads a file that a `[start]` prerequisite or the runner wrote, such as the `.output.txt` beside a suite run's JUnit file.
+
 ---
 
 ## Task sizing (session economics)
@@ -428,6 +475,10 @@ The second example above has no `skills=` and is still a valid task declaration.
   `src/start.ts`" task grows it enough for its own diff to flag, and phase
   0's six took `src/start.ts` from 798 lines to 960 with no task owning the
   split; only a whole-change-set review caught it.
+* When the project's entry test lists command modules, a task that adds
+  a command module or an import to one updates that list in the same
+  task and names the file in its Description: in rafa, `COMMAND_MODULES`
+  in `src/index.test.ts`.
 * Keep as SEPARATE tasks: cross-cutting verification (fan-out gates,
   invariant sweeps), live-seam runs, migrations, and close-out — these
   preserve resumability where a halt is most likely.
@@ -444,6 +495,46 @@ The second example above has no `skills=` and is still a valid task declaration.
   --write-tree origin/<base> HEAD`) and assemble the body material — the gate
   captures, the test plan, the recorded debt — into the plan's close-out
   notes for that wrap-up session to use.
+* A task's text never asks its session for the whole suite, or for any
+  command that can outlast one Bash call. Declare `tests=full` on the task
+  and the runner runs the suite after the commit; a task that needs a long
+  run's output reads it from the file a `[start]` prerequisite or the
+  runner wrote.
+
+### The closing doc task
+
+* A plan with one task not declared `agent=doc-updater` ends on one task
+  declared `agent=doc-updater docs=repair`. That task is the plan's last
+  task line, and it repairs the docs of what the plan changed: the loop
+  hands it the `stale_docs` rows the plan's tasks reported and the files
+  its commits touched.
+* A plan whose every task is declared `agent=doc-updater` gets no closing
+  doc task: it is prose only, and every task in it is documentation.
+* `rafa plan validate` reports a plan with a code task and no `docs=repair`
+  task on its last line as the warning `missing-doc-task`. The warning never
+  refuses a plan, so a plan written before this rule still runs.
+
+A plan of code tasks ends on the closing task:
+
+````markdown
+  # Stage: Store
+
+  - [ ] Add the `stale_docs` table migration with its unit tests  {agent=loop-implementer effort=high}
+  - [ ] Add the store writer for stale-doc rows with its unit tests  {agent=loop-implementer effort=medium}
+
+  # Stage: Close-out
+
+  - [ ] Repair the docs of what this plan changed  {agent=doc-updater docs=repair effort=medium}
+````
+
+A prose-only plan gets none:
+
+````markdown
+  # Stage: Pages
+
+  - [ ] Rewrite the triage page for four channels  {agent=doc-updater effort=medium}
+  - [ ] Add the doc task to the workflow page  {agent=doc-updater effort=medium}
+````
 
 ---
 
@@ -472,6 +563,8 @@ The wrap-up session always receives `full` regardless of the configured mode.
   - [ ] {Tool} installed: `{tool} --version`
   - [ ] {Service name} answering on port {n}: `curl -sf http://localhost:{n}/health`
   - [ ] {VAR_NAME} set, obtained from {where}: `test -n "${VAR_NAME}"`
+  - [ ] [tasks] {Something only the tasks need}: `{command to verify}`
+  - [ ] [wrap-up] {Something only the wrap-up needs}: `{command to verify}`
 
   ## Credentials [human]
   - [ ] {Credential description}
@@ -488,6 +581,8 @@ How the file is read:
 - An item's tag is the `[auto]`, `[human]`, or `[start]` written right after its box. Without one it takes its section's tag: a heading carrying `[auto]` tags its section `auto`, one carrying `[human]` or naming `manual`, `human`, `sign-off` or `team` tags it `human`, and one carrying `[start]` tags it `start`. A heading's tag reaches the deeper headings under it and ends at the next heading of its own level or shallower. An item under no tagged heading is `human`.
 - An `auto` item's probe is the backticked span that ends it, after its final `: `. The item merges as a required prerequisite, the tier whose failure halts a run.
 - A `start` item's probe is read the same way. The item is probed on first dispatch only (skipped on resume), and failure halts a run on first dispatch.
+- An item's scope is the `[tasks]` or `[wrap-up]` marker written at its opening, after its box and after its tag when it has one (`- [ ] [auto] [tasks] ...`). Without one it takes the marker of the nearest heading above it that carries one, which reaches the deeper headings under it and ends at the next heading of its own level or shallower, as a tag does; an item's own marker outranks its heading's. With no marker anywhere the scope is `both`, and the two markers written together read as `both` too. The marker is dropped from the item's text and is never read as its probe.
+- The scope says which dispatches need an `auto` item: `tasks` the task sessions, `wrap-up` the wrap-up session, `both` every one. A marker on a `start` or `human` item is read and changes nothing: the `start` item is still probed on first dispatch only, and the `human` item is still a reminder.
 - A `human` item is a reminder: named to the operator, never probed, and never halting a run.
 - An `auto` or `start` item that does not end with `: ` and its command — the command first, text after it, or no span at all — is malformed: `rafa loop start` and `rafa doctor` refuse the plan, naming its line, and run nothing.
 
@@ -496,6 +591,7 @@ Rules:
 - An `[auto]` item holds exactly one backticked span, and that span is its command. The preflight runs it as written, so put no package name, path or other command in backticks anywhere in the item.
 - Tag an item `auto` only when a shell command proves it, and end the item with `: ` and that command. The command asks for no input and changes nothing.
 - Tag an item `start` only when a shell command proves it and it should only be checked on the first dispatch of a plan (not on resume). End it with `: ` and the command, one span, as for `auto`.
+- Mark an `auto` item `[tasks]` when only the plan's tasks need it and `[wrap-up]` when only the wrap-up does (pushing, opening the pull request, releasing); leave it unmarked when both do or when unsure, since an unmarked item is always probed. Write the marker bare, at the item's opening or on its heading, never in backticks and never after the command: text after the span makes the item malformed.
 - Make the command complete: it exits 0 when the prerequisite holds. To prove a tool is installed, probe `<tool> --version`, `<tool> --help` or `which <tool>` — never a bare subcommand such as `uvx check-jsonschema`, which exits non-zero for want of arguments.
 - Tag every step for after the plan merges `human`, as the heading above does, so no run ever executes one as a probe.
 - Do not duplicate steps already documented in the repo's contributor docs (README, CONTRIBUTING, and the like).
@@ -506,18 +602,18 @@ Rules:
 
 ## Format validation
 
-The loop parses plan files through `src/plan/parse.ts`:
+The loop parses plan files through `packages/rafa/src/core/plan/parse.ts`:
 
-- **Block parsing** (`src/plan/blocks.ts`): Reads fenced `rafa:*` blocks. Tolerates documents with no blocks. Retains unknown kinds.
-- **Plan parsing** (`src/plan/parse.ts`): Builds the plan model over blocks and the checklist grammar. Each stage captures the tasks under it and the first `rafa:stage-context` block between its heading and the next `# Stage:` heading.
-- **Declaration parsing** (`src/utils/declaration.ts`): Takes a trailing `{...}` block off a task line and reads its `key=value` entries. The block counts only when one of its keys is a recognized key (see Task declarations).
-- **Report parsing** (`src/report/parse.ts`): Reads the last `rafa:report` block from agent output and parses its YAML body. Answers an explicit absence record if no block is present.
+- **Block parsing** (`packages/rafa/src/core/plan/blocks.ts`): Reads fenced `rafa:*` blocks. Tolerates documents with no blocks. Retains unknown kinds.
+- **Plan parsing** (`packages/rafa/src/core/plan/parse.ts`): Builds the plan model over blocks and the checklist grammar. Each stage captures the tasks under it and the first `rafa:stage-context` block between its heading and the next `# Stage:` heading.
+- **Declaration parsing** (`packages/rafa/src/core/plan/declaration.ts`): Takes a trailing `{...}` block off a task line and reads its `key=value` entries. The block counts only when one of its keys is a recognized key (see Task declarations).
+- **Report parsing** (`packages/rafa/src/report/parse.ts`): Reads the last `rafa:report` block from agent output and parses its YAML body. Answers an explicit absence record if no block is present.
 
 The parser is liberal with unknown input: unknown block kinds are kept, unknown declaration keys are kept, unknown YAML keys are kept. A report yields no report only when its last `rafa:report` block is missing, never closed, not valid YAML, or not a mapping. A field that is missing, or holds a value it cannot take (a `findings` that is not a list, a `signal` other than `loud` or `silent`), is reported as an issue and the rest of the report is still read. Quote every string value in a report: an unquoted value that opens with a backtick, `@`, `%` or `[` makes the whole block unreadable, and a `#` after a space starts a comment that silently cuts the value short.
 
 Line numbers count two ways. A block's `span` (`readRafaBlocks`) and a `PlanIssue.line` count from one; `TaskInfo.lineNum` and the stage and task `lineNum` of the plan model count from zero, so compare `lineNum + 1` against either.
 
-The report rules in this skill restate `src/report/parse.ts`, which is the authority: change the two together.
+The report rules in this skill restate `packages/rafa/src/report/parse.ts`, which is the authority: change the two together.
 
 ---
 
@@ -534,11 +630,11 @@ When the spec adds or changes anything in `.rafa/effort/`:
 
 ## Command-development rule: Claude session declaration
 
-When planning work on rafa commands: every command that can start a Claude
-Code session must declare its `spends` field on its `RafaCommand` definition.
-The field tells the help system, `describe` output, and the spawn guard in
-`src/utils/claude.ts` what Claude usage the command declares. It is optional,
-and takes one of four shapes:
+When planning work on rafa commands: every command that can start a Claude Code
+session must declare its `spends` field on its `RafaCommand` definition. The
+field tells the help system, `describe` output, and the spawn guard in
+`packages/rafa/src/core/loop/claude.ts` what Claude usage the command declares.
+It is optional, and takes one of four shapes:
 
 - `{ when: 'always'; what: string }` — the command always starts a session
 - `{ when: 'with'; flag: string; what: string }` — starts a session only when
@@ -626,4 +722,4 @@ Both follow the same structured format. The difference is:
 - **Hand-written plans** (by a planner agent): Prose in the description, stage contexts, and task granularity reflect careful thought about the work.
 - **Generated plans** (by `rafa plan`): Produced from a spec document; structure is the same.
 
-A hand-written plan read by `src/plan/parse.ts` produces the same data model as a generated one. This is the property the structured format enforces.
+A hand-written plan read by `packages/rafa/src/core/plan/parse.ts` produces the same data model as a generated one. This is the property the structured format enforces.

package/dist/bundled/skills/documentation/SKILL.md

@@ -30,7 +30,7 @@ Two kinds of documentation are maintained:
 | **API (Swagger)** | `@asteasolutions/zod-to-openapi` + `swagger-ui-express` | `openapi.json` + served behind `ctx.requireAuth` at `GET /docs/` | `bun run docs:openapi` |
 
 > Both rows are INSTALLED in `@ar/service` — the OpenAPI half is no longer a
-> convention to adopt on some later day, and [`rules/openapi.md`](rules/openapi.md)
+> convention to adopt on some later day, and this skill
 > records what is there rather than a setup to perform. The two scripts are
 > SIBLINGS sharing no output tree, which is worth stating because the pair of
 > names suggests they do: `docs:openapi` writes the gitignored `.docs/swagger/`,
@@ -46,16 +46,6 @@ Auto-generated outputs go in `.docs/` (dotfolder) and are always gitignored.
 
 ---
 
-## Rules index
-
-| Rule file | When to use |
-| --- | --- |
-| [`rules/tsdoc.md`](rules/tsdoc.md) | Writing TSDoc comments on any TypeScript symbol |
-| [`rules/openapi.md`](rules/openapi.md) | Documenting Express routes with OpenAPI/Swagger |
-| [`rules/typedoc-setup.md`](rules/typedoc-setup.md) | Adding TypeDoc infra to the repo (or a project derived from it) |
-
----
-
 ## Workflow
 
 1. **Determine kind before touching**: identify whether documentation is manual or auto-generated before editing. Manual docs live in `docs/`; auto-generated outputs live in `.docs/`.
@@ -72,7 +62,7 @@ Before marking a documentation task done:
 - [ ] Every exported function, class, and interface has a TSDoc block with `@param` and `@returns`.
 - [ ] Every file has a `@packageDocumentation` comment (or is covered by a module-level JSDoc).
 - [ ] Every Express router factory is documented with `@remarks` listing its HTTP endpoints.
-- [ ] `typedoc.json`, `tsconfig.docs.json`, and a `docs:generate` script exist (see [`rules/typedoc-setup.md`](rules/typedoc-setup.md)).
+- [ ] `typedoc.json`, `tsconfig.docs.json`, and a `docs:generate` script exist.
 - [ ] `openapi.ts` exists and every route is registered in it — `openapi-coverage.test.ts` is the gate that says so, and a route added without a binding-table entry reddens it.
 - [ ] `.docs/` is already gitignored twice over and needs no new entry: once at the repo root (`.gitignore`) and again at the package (`packages/service/.gitignore`), both files tracked. Running `git check-ignore -v` on the generated `openapi.json` names the PACKAGE rule, the nearer file winning — take the source off that output rather than predicting it.
 - [ ] `docs/` (manual ADRs) is **not** gitignored.