@open-tomato/rafa 0.45.0 → 0.46.0

package/dist/core/output/text.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The `text` Output adapter: a command's output as lines a person reads.
+ *
+ * Copied from `createTextOutput` in open-tomato's
+ * `packages/shared/cli-core/src/output.ts` at commit
+ * `18f94c843fff1bce65ed2245f8712ed9b64a2d51` (2026-06-25), and retyped
+ * against rafa's `Output` port, which `packages/rafa/src/ports/index.ts` copies from
+ * the same file's `CliOutput`.
+ *
+ * ## What the copy changes
+ *
+ * `info` is written at every verbosity, with no prefix. The source writes
+ * it at verbosity 1 and above, as `info: <message>`. The loop prints its
+ * progress lines at every verbosity, so under the source's threshold
+ * each would vanish at verbosity 0, and under its prefix each one left
+ * would change. `info(message)` writes `message`
+ * and a newline, the bytes `console.log(message)` writes for a single
+ * string: `text.test.ts` holds the two equal in a child process, over
+ * messages holding `%s`, `%%`, `%d`, `%o`, `%c` and `%j`, none of which
+ * `console.log` formats when it is handed one string.
+ *
+ * The rendering is otherwise the source's. `debug` is written at
+ * verbosity 2 and above as `debug: <message>`, `warn` and `error` at
+ * every verbosity as `warn: ` and `error: `, and `result` as `result: `
+ * followed by a string payload as it is or any other payload as JSON.
+ * `emit` renders a `log` event through the function of its level, a
+ * named `event` as nothing, and each other kind on a line of its own. The stream's `write` is a
+ * property, as `stream.ts` says, and the output answered is frozen.
+ *
+ * ## One stream
+ *
+ * Every line goes to the one stream the adapter is made with, `warn` and
+ * `error` included, as in the source. A `console.warn` or `console.error`
+ * line goes to stderr and carries no prefix, so the same message written
+ * through `warn` or `error` differs from it in both. `emit` also writes a
+ * line for a `start` event and a `result` event, `start: <command>` and
+ * `result: ok`, whatever the verbosity.
+ */
+import type { OutputStream } from './stream.js';
+import type { Output } from '../../ports/index.js';
+/** What {@link createTextOutput} makes an adapter with. */
+export interface CreateTextOutputOptions {
+    /** How much is written: `debug` lines from 2, every other line at any verbosity. */
+    verbosity: number;
+    /** Where every line is written. */
+    stream: OutputStream;
+}
+/**
+ * Makes a `text` Output writing each line to `stream`.
+ *
+ * The output answered is frozen, so no caller replaces one of its
+ * functions on an output `packages/rafa/src/core/output/active.ts` may be handing
+ * every module of the process.
+ */
+export declare function createTextOutput({ verbosity, stream }: CreateTextOutputOptions): Output;

package/dist/core/plan/block-reader.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The barrel over the block reader: every name `blocks.ts` exports, and
+ * nothing else.
+ *
+ * A file outside `packages/rafa/src/core/` imports this file and never the one behind
+ * it (`scripts/survey/core-barrels.ts` measures that, and
+ * `src/tests/core-barrels.sweep.test.ts` holds it against the tree). A
+ * file inside `packages/rafa/src/core/` imports `blocks.ts` directly and never this
+ * file.
+ *
+ * ## Why one file has a barrel of its own
+ *
+ * `packages/rafa/src/core/plan/` has two barrels, both listed under `CORE_BARRELS` in
+ * `scripts/survey/core-moves.ts`. `index.ts` holds the plan parser and
+ * the plan-file helpers. This one holds `blocks.ts` alone, because
+ * `index.ts` cannot take it.
+ *
+ * A barrel that groups a file with a file outside `packages/rafa/src/core/` that
+ * imports the barrel back by value is a runtime cycle.
+ * `src/utils/tracker.ts` imports `readRafaBlocks` by value, and
+ * `parse.ts`, behind `index.ts`, imported that file by value when the
+ * split was made. So `blocks.ts` behind `index.ts` closed a cycle
+ * through the tracker. `blocks.ts` imports no file, so a barrel that
+ * holds it alone is imported back by nothing it reaches.
+ *
+ * `parse.ts` now reads the blocker comment from `blocker-comment.ts`,
+ * and no file of `packages/rafa/src/core/` imports the tracker, so that cycle is
+ * gone. The split stands as it was made.
+ *
+ * `index.ts` records the measurement: six cycles before the move and
+ * the same six after it, and a seventh in the control that puts all
+ * three files behind one barrel.
+ *
+ * ## What it exports
+ *
+ * Each name is spelled, types apart from values, as the other core
+ * barrels spell theirs. `src/plan/index.ts`, the `./plan` entry,
+ * re-exports all six, so this barrel is exactly as wide as the published
+ * surface it feeds.
+ *
+ * `block-reader.test.ts` holds the list to the file: every name
+ * `blocks.ts` exports is here once, as the same binding, no other name
+ * is here, and no name here is on the other plan barrel.
+ */
+export type { LineSpan, RafaBlock, RafaBlockKind } from './blocks.js';
+export { isRafaBlockKind, RAFA_BLOCK_KINDS, readRafaBlocks } from './blocks.js';

package/dist/core/plan/blocks.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Reading fenced `rafa:*` blocks out of a markdown document.
+ *
+ * A plan stays markdown a person can read, and the parts the loop acts
+ * on are fenced code blocks whose info string opens with `rafa:`:
+ *
+ * ````markdown
+ * ```rafa:plan
+ * stub: my-feature
+ * ```
+ * ````
+ *
+ * The rest of that first word is the block's KIND, `plan` above. This
+ * module answers every such block in source order with its kind, its
+ * body and the lines it spans, and nothing more: which kinds to act on,
+ * and what a body means, belong to whoever reads the document.
+ * {@link RAFA_BLOCK_KINDS} names the four kinds this phase defines.
+ *
+ * ## Fences are read the way a renderer shows them
+ *
+ * The checklist grammar is line-anchored and fence-blind: `findNextTask`
+ * dispatches a `- [ ] ` at column 0 inside a code fence, skipping one
+ * only inside a closed block this module answers. This reader is
+ * deliberately the opposite. A document
+ * that ILLUSTRATES the format puts its example inside a longer fence of
+ * its own, as the one above does, and a reader taking every line that
+ * opens with a `rafa:` fence for a block would hand the illustration to
+ * every task. So every fence is tracked, whatever its info string, and
+ * a `rafa:` line inside one is body text.
+ *
+ * The fence rules are CommonMark's, from its fenced code block section:
+ *
+ *   - An opening fence is three or more backticks or tildes after at
+ *     most three spaces. Four spaces, or a tab anywhere before it, and
+ *     the line opens no fence; nor does a fence that does not open its
+ *     line, which is prose quoting the syntax.
+ *   - A backtick fence's info string holds no backtick, so a line such
+ *     as ` ```rafa:plan``` ` is an inline code span and opens nothing.
+ *   - A closing fence is the SAME character, at least as many of it,
+ *     after at most three spaces, with nothing after it but spaces and
+ *     tabs. It carries no info string, so ` ```ts ` inside a block is
+ *     body; a block that holds a fence of its own opens with a longer
+ *     one, as the illustration above does.
+ *   - A fence never closed runs to the end of the document. The block
+ *     is still answered, with {@link RafaBlock.closed} false: a session
+ *     cut off mid-report leaves exactly that, and only the caller can
+ *     judge whether a truncated body is usable.
+ *   - Each body line loses up to as many leading spaces as the opening
+ *     fence carried.
+ *
+ * What is NOT parsed is container structure. Measured against micromark
+ * (the CommonMark parser `@eslint/markdown` lints this repo's prose
+ * with), that costs three shapes: a fence inside a block quote, and one
+ * inside a list item indented four columns or more, are fences to a
+ * renderer and not here; a fence inside a multi-line HTML comment is
+ * raw HTML to a renderer and a block here. Outside those shapes the two
+ * agree: with every info string in 499 markdown files (this repo's, its
+ * sibling's and a skill library, on 2026-09-11) rewritten to open with
+ * `rafa:`, they answered the same kind, body and span for all 2,177
+ * fences. A plan puts its blocks at the top level.
+ *
+ * ## Lines
+ *
+ * A line is what `split('\n')` yields, the split `utils/tracker.ts`
+ * reads a tracker with, less one trailing carriage return, so a CRLF
+ * document reads exactly like its LF twin. A final newline ends the
+ * last line rather than opening an empty one. A LONE carriage return
+ * breaks no line here, where CommonMark breaks one on it; that is the
+ * fourth shape the measurement above found.
+ *
+ * {@link LineSpan} numbers lines from ONE, fences included, the way an
+ * editor and `grep -n` number them, so `sed -n '<first>,<last>p'`
+ * prints a block whole. `TaskInfo.lineNum` counts from ZERO: the line
+ * at index `i` of that split is line `i + 1` here.
+ *
+ * ## Unknown kinds
+ *
+ * A `rafa:` fence whose kind is none of {@link RAFA_BLOCK_KINDS} is
+ * answered like any other, never refused and never dropped. That is the
+ * rule `core/plan/declaration.ts` applies to an unrecognised key, for the
+ * same reason: a plan written for a later phase names kinds this one has
+ * never heard of, and refusing them would make every new kind a
+ * breaking change for older installs.
+ *
+ * The kind is the first word of the info string less its `rafa:`
+ * prefix, taken as written: `rafa:` alone answers the empty kind, and
+ * `rafa:Plan` answers `Plan`, which is unknown. The prefix is matched
+ * case-sensitively, as the declaration keys are, so `RAFA:plan` is an
+ * ordinary code block and no rafa block at all.
+ *
+ * Nothing here throws. A document with no block — empty, prose only, or
+ * fenced only in other languages — answers an empty list.
+ */
+/**
+ * The kinds this phase defines. `plan`, `context` and `stage-context`
+ * are a plan's; `report` ends a task session's final message.
+ *
+ * Each document's reader acts on its own kinds and ignores the rest.
+ * {@link readRafaBlocks} answers every kind; see the module note.
+ */
+export declare const RAFA_BLOCK_KINDS: readonly ["plan", "context", "stage-context", "report"];
+/** One of the four kinds this phase defines. */
+export type RafaBlockKind = (typeof RAFA_BLOCK_KINDS)[number];
+/** The lines one block covers: from one, inclusive, fences included. */
+export interface LineSpan {
+    /** The opening fence's line. */
+    readonly first: number;
+    /**
+     * The closing fence's line, or the document's last line when the
+     * block was never closed.
+     */
+    readonly last: number;
+}
+/** One fenced `rafa:*` block, as the document wrote it. */
+export interface RafaBlock {
+    /** The info string's first word less `rafa:`, as written. */
+    readonly kind: string;
+    /**
+     * Every line between the fences, each less the opening fence's
+     * indentation, joined with `\n` and carrying no final newline. Empty
+     * for a block with no line between its fences.
+     */
+    readonly body: string;
+    /** Where the block sits in the document. */
+    readonly span: LineSpan;
+    /** False when the document ended before a closing fence. */
+    readonly closed: boolean;
+}
+/** True when `kind` is one of the four kinds this phase defines. */
+export declare function isRafaBlockKind(kind: string): kind is RafaBlockKind;
+/**
+ * Every `rafa:*` block in a markdown document, in source order.
+ *
+ * Takes any string and answers a new list, empty when the document
+ * holds no rafa block. An unknown kind is answered like a known one and
+ * an unclosed block is answered with `closed` false; see the module
+ * note for what counts as a fence and how lines are numbered.
+ */
+export declare function readRafaBlocks(markdown: string): readonly RafaBlock[];

package/dist/core/plan/declaration.d.ts

@@ -0,0 +1,366 @@
+/**
+ * Reading a task's routing declaration off the end of its own line.
+ *
+ * A plan's task lines may carry a trailing brace block naming what the
+ * loop should dispatch the task WITH:
+ *
+ * ```text
+ * - [ ] Update the skill's cap sentence  {agent=doc-updater effort=low}
+ * ```
+ *
+ * The block is the planner's half of a decision the loop otherwise has
+ * no way to make. A task carrying none is dispatched exactly as every
+ * task was before this module existed — one model, one effort, every
+ * tool — so a prose task and a schema migration cost the same, and
+ * the only place that knows they should not is the document that
+ * wrote them. `start/dispatch.ts` reads the block off each task on its
+ * way to the prompt, which is what makes a declared task the one that
+ * runs differently.
+ *
+ * Two parsers were never told about the block and both had to keep
+ * working unchanged, which is what shapes the grammar. `findNextTask`
+ * matches `^- \[ \] (.+)` and trims the capture, so the block arrives
+ * inside `taskInfo.task` and would otherwise reach the injected prompt
+ * verbatim; `updateTrackerLine` rewrites the checkbox prefix and
+ * nothing before a blocker comment, so the block survives a tick
+ * byte-identical. Neither needed a change for the block — the
+ * stripping happens here, at the point the text is used. Both halves
+ * are driven over real trackers in `tests/tracker-declarations.test.ts`,
+ * which is where that claim is measured rather than stated.
+ *
+ * A blocker comment is the one thing a line may trail after the block,
+ * and it comes off in `findNextTask` rather than here
+ * (`utils/tracker.ts`). It has to come off first: the block is anchored
+ * at end of text, so with the comment still on it would read as task
+ * text.
+ *
+ * The strip rule reaches every `rafa:*` block too, but not from here.
+ * A declaration sits ON a task line, so the text alone says where it
+ * starts; a block sits AROUND lines, and only a reader holding the
+ * document can tell that a line is its body. `findNextTask` is that
+ * reader, and every site quoting a task back quotes what it answered,
+ * so a task line inside a closed block is skipped there and reaches
+ * neither this module nor the prompt, the log or the commit.
+ *
+ * Four rules keep a brace that a task WROTE ABOUT from being read as a
+ * declaration, and each one is a shape that occurs in this repo's own
+ * plans:
+ *
+ *   - The block is anchored at END OF TEXT. A task naming `{}` or a
+ *     JSON literal mid-sentence has something after it.
+ *   - It carries NO NESTED BRACES, so a task ending on a code span
+ *     holding an object literal does not match.
+ *   - It holds AT LEAST ONE RECOGNISED key, which is the rule the
+ *     scoped grammar turns on. `{ ... }` prose, an empty block and a
+ *     block of keys nobody here answers to are all task text.
+ *   - It is not the WHOLE text. A line that is only a declaration
+ *     leaves no task to dispatch, and stripping it would hand the loop
+ *     an empty prompt — the one failure that reads as the loop having
+ *     silently lost the task.
+ *
+ * When none of that holds the answer is today's behaviour exactly:
+ * `text` is the input string unchanged and `declaration` is null.
+ * Nothing is stripped and no flag is resolved.
+ *
+ * Priority inside a block is duplicated ON PURPOSE. With `agent`
+ * present the loop never passes `--model` or `--tools`, because an
+ * agent definition carries its own model and tool set and a flag beside
+ * it would be two authorities for one decision. `--effort` joins
+ * `--agent` unless the agent's definition declares an effort of its
+ * own, which the caller answers through an {@link AgentEffortLookup}
+ * (`utils/agent-definition.ts` reads it off the definition's
+ * frontmatter): effort is the cost lever a plan most needs to reach the
+ * session, and a definition silent on it leaves the plan's level the
+ * only one there is. `budget` is outranked by nothing: an agent
+ * definition supplies no budget, so `--max-budget-usd` joins whatever
+ * else the block resolved to, agent or none. Every key is still PARSED
+ * and still sits on the record whether or not it became a flag, and
+ * {@link ResolvedFlags.suppressed} names exactly the granular ones an
+ * agent took.
+ *
+ * `skills`, `tests` and `docs` are the three recognised keys that map to
+ * no flag under any block. There is no CLI flag for a skill, and what a
+ * plan names there is a hint for whoever reads the dispatch record rather
+ * than something the spawn can pass on. `tests` is read by the RUNNER,
+ * not the session: it names how much of the suite the loop runs after
+ * the task commits (`affected`, `module` or `full`, {@link TEST_SCOPES}),
+ * and {@link readTestScope} answers it with the `affected` default when
+ * the block is absent or its value unusable. `docs` marks the task's ROLE
+ * in its plan: its one value, `repair` ({@link DOCS_ROLES}), names the
+ * closing task that repairs the docs of what the plan changed, and
+ * {@link readDocsRole} answers it, with null for every other task. All
+ * three are recognised all the same, because that is what makes
+ * `{skills=bun-testing}`, `{tests=full}` or `{docs=repair}` a declaration
+ * on its own and what gets a misspelled value into
+ * {@link TaskDeclaration.issues} instead of through to the agent's prompt
+ * as task text. None is ever named in {@link ResolvedFlags.suppressed},
+ * which says what an AGENT outranked, and nothing outranks a key that
+ * was never a flag.
+ *
+ * Nothing here throws. A recognised key whose value this module cannot
+ * use lands in {@link TaskDeclaration.issues} and maps to no flag, so
+ * the task runs at the loop's defaults instead of stalling on a CLI
+ * that refuses `--effort medum`. An unrecognised KEY is not an issue at
+ * all: it is retained in {@link TaskDeclaration.extras} for telemetry,
+ * which is what lets a grammar grow without every older plan going red.
+ *
+ * `EFFORT_LEVELS` and `EffortLevel` are core's
+ * (`packages/rafa/src/effort/store/effort-levels.ts`), where the store's dispatch writer
+ * types a declared effort; this file re-exports them under the same names.
+ */
+import type { EffortLevel } from '../../effort/store/effort-levels.js';
+export type { EffortLevel } from '../../effort/store/effort-levels.js';
+export { EFFORT_LEVELS } from '../../effort/store/effort-levels.js';
+/**
+ * Keys this module answers to, in the order flags are emitted. `budget`
+ * sits ahead of `tools` because `--tools` is variadic and has to end the
+ * argument list (`core/loop/claude.ts`). `skills`, `tests` and `docs` come
+ * last because they emit no flag at all: each is recognised so that its value
+ * is PARSED and lands on the record, and a value the parser cannot use
+ * lands in {@link TaskDeclaration.issues} rather than passing silently.
+ */
+export declare const DECLARATION_KEYS: readonly ["agent", "model", "effort", "budget", "tools", "skills", "tests", "docs"];
+/** One of the keys the grammar recognises. */
+export type DeclarationKey = (typeof DECLARATION_KEYS)[number];
+/**
+ * The granular keys, each mapping to a flag of its own with no agent, and
+ * each one an agent can outrank. `budget` maps to a flag of its own too,
+ * and is not one of them: nothing outranks it.
+ */
+export declare const GRANULAR_KEYS: readonly ["model", "effort", "tools"];
+/** A key that maps to a flag of its own when no agent is named. */
+export type GranularKey = (typeof GRANULAR_KEYS)[number];
+/**
+ * The granular keys an `agent` outranks whenever it is named, its
+ * definition supplying a model and a tool set. `effort` is outranked
+ * only by a definition declaring one ({@link resolveDeclarationFlags}).
+ */
+export declare const AGENT_OWNED_KEYS: readonly ["model", "tools"];
+/**
+ * Model aliases the CLI documents, which is what a plan should spell.
+ *
+ * A FULL model name is accepted as well ({@link FULL_MODEL_NAME}) —
+ * `--model` takes either — but an alias is what survives a model
+ * generation changing underneath the plan.
+ */
+export declare const MODEL_ALIASES: readonly ["opus", "sonnet", "haiku", "fable"];
+/**
+ * How much of the suite the runner runs after a task commits, as a
+ * `tests=` value spells it: `affected` runs the test files the task's
+ * diff reaches, `module` the tests of every module the diff touches,
+ * and `full` the whole suite. Ordered narrowest first.
+ */
+export declare const TEST_SCOPES: readonly ["affected", "module", "full"];
+/** One of the three scopes a `tests=` value names. */
+export type TestScope = (typeof TEST_SCOPES)[number];
+/**
+ * The scope a task runs under when it declares none, or declares one
+ * {@link isTestScope} refuses: the narrowest, since a task that needs
+ * more is the one its plan marks.
+ */
+export declare const DEFAULT_TEST_SCOPE: TestScope;
+/**
+ * The roles a `docs=` value names. There is one: `repair` marks the task
+ * that repairs the docs of what its plan changed. A task declaring none
+ * has no docs role, so the key has no default value.
+ */
+export declare const DOCS_ROLES: readonly ["repair"];
+/** The one role a `docs=` value names. */
+export type DocsRole = (typeof DOCS_ROLES)[number];
+/**
+ * True when `value` is an agent name this module passes on: a bare
+ * file stem, so no name can reach a path outside `.claude/agents/`.
+ */
+export declare function isAgentName(value: string): boolean;
+/** The flag a declared budget is passed as, in the CLI's own spelling. */
+export declare const BUDGET_FLAG = "--max-budget-usd";
+/**
+ * Reads a `budget=` value as US dollars, or answers null when it is not
+ * one this module passes on: a shape {@link BUDGET_VALUE} refuses, or
+ * zero, which no session could run under.
+ */
+export declare function parseBudgetUsd(value: string): number | null;
+/** One `key=value` pair, exactly as it was written. */
+export interface DeclarationEntry {
+    /** Key as written. Matched case-sensitively against the grammar. */
+    key: string;
+    /** Value as written, with no unescaping of any kind. */
+    value: string;
+}
+/** Why a token could not be used. */
+export type DeclarationIssueReason = 
+/** A recognised key appearing twice. The first occurrence wins. */
+'duplicate-key'
+/** A recognised key whose value this module cannot pass on. */
+ | 'unusable-value'
+/** A token inside the block carrying no `=` at all. */
+ | 'stray-token';
+/** One thing the block said that did not become a flag. */
+export interface DeclarationIssue {
+    reason: DeclarationIssueReason;
+    /** Key it concerns, or the empty string for a stray token. */
+    key: string;
+    /** The token as written, so a log line can quote it. */
+    text: string;
+}
+/** What one block declared. */
+export interface TaskDeclaration {
+    /** The block as it appeared, braces included. */
+    raw: string;
+    /** Every `key=value` token, in source order, recognised or not. */
+    entries: readonly DeclarationEntry[];
+    /** Entries whose key is none of {@link DECLARATION_KEYS}. */
+    extras: readonly DeclarationEntry[];
+    /** What was dropped, and why. Empty on a clean block. */
+    issues: readonly DeclarationIssue[];
+    /** Agent to dispatch under, or null. */
+    agent: string | null;
+    /** Model alias or full name, or null. */
+    model: string | null;
+    /** Effort level, or null. */
+    effort: EffortLevel | null;
+    /** Budget in US dollars, above zero, or null. */
+    budget: number | null;
+    /** Tool names, deduped in first-seen order, or null. */
+    tools: readonly string[] | null;
+    /**
+     * Skill names, deduped in first-seen order, or null. Maps to no flag:
+     * the key is recognised so a plan's skill hint is parsed and kept,
+     * and a reader takes it off the record rather than off the CLI.
+     */
+    skills: readonly string[] | null;
+    /**
+     * Test scope the runner runs after the task commits, or null when the
+     * block names none or names one outside {@link TEST_SCOPES}. Maps to
+     * no flag; {@link readTestScope} answers the default for null.
+     */
+    tests: TestScope | null;
+    /**
+     * The task's docs role, or null when the block names none or names one
+     * outside {@link DOCS_ROLES}. Maps to no flag; {@link readDocsRole}
+     * answers it.
+     */
+    docs: DocsRole | null;
+}
+/** A task text split from the declaration it carried. */
+export interface ParsedTask {
+    /**
+     * The text the loop should dispatch. The input unchanged when no
+     * declaration was found, and the text before the block otherwise.
+     */
+    text: string;
+    /** What the block declared, or null when there was no block. */
+    declaration: TaskDeclaration | null;
+}
+/** What a declaration resolves to on the command line. */
+export interface ResolvedFlags {
+    /** CLI arguments, in {@link DECLARATION_KEYS} order. */
+    args: readonly string[];
+    /**
+     * Keys present on the record that deliberately map to no flag.
+     * Non-empty only when an `agent` outranked them.
+     */
+    suppressed: readonly GranularKey[];
+}
+/** True when `value` is one of the five effort levels. */
+export declare function isEffortLevel(value: string): value is EffortLevel;
+/** True when `value` is one of the three {@link TEST_SCOPES}. */
+export declare function isTestScope(value: string): value is TestScope;
+/**
+ * The test scope a task's declaration yields: the one it declared, or
+ * {@link DEFAULT_TEST_SCOPE} when there is no block, the block carries
+ * no `tests=`, or its value was unusable (and so recorded in
+ * {@link TaskDeclaration.issues} rather than on the record).
+ */
+export declare function readTestScope(declaration: TaskDeclaration | null): TestScope;
+/** True when `value` is one of the {@link DOCS_ROLES}. */
+export declare function isDocsRole(value: string): value is DocsRole;
+/**
+ * The docs role a task's declaration yields: the one it declared, or null
+ * when there is no block, the block carries no `docs=`, or its value was
+ * unusable (and so recorded in {@link TaskDeclaration.issues} rather than
+ * on the record).
+ */
+export declare function readDocsRole(declaration: TaskDeclaration | null): DocsRole | null;
+/**
+ * True when `value` is a model this module will pass on: one of the
+ * documented aliases, or a full name spelled the way the CLI's own
+ * help spells one.
+ */
+export declare function isModelValue(value: string): boolean;
+/**
+ * Splits a `tools=` value into names, or answers null when it is not
+ * usable.
+ *
+ * Membership is deliberately NOT checked against a list of tool names.
+ * The built-in set lives in the CLI and moves with it, so a list kept
+ * here would eventually refuse a tool that exists — a failure that
+ * reads as a broken declaration rather than as a stale constant. The
+ * SHAPE is checked instead, which catches the mistakes a plan actually
+ * makes: an empty value, a doubled comma, a stray quote.
+ */
+export declare function parseToolList(value: string): readonly string[] | null;
+/**
+ * Splits a `skills=` value into names, or answers null when it is not
+ * usable.
+ *
+ * Membership is NOT checked here against the skills installed, for the
+ * reason {@link parseToolList} gives: the set moves with the machine,
+ * and this reads one declaration and no tier. `agents/roster.ts` checks
+ * it where the tiers are read, and `rafa plan validate` and `loop
+ * start`'s preflight refuse a name no loaded tier resolves. The SHAPE is
+ * checked here instead — a bare directory
+ * stem, so no name reaches a path outside `.claude/skills/` — which
+ * catches an empty value, a doubled comma and a stray quote.
+ */
+export declare function parseSkillList(value: string): readonly string[] | null;
+/**
+ * Splits a task's text from the declaration block it may carry.
+ *
+ * Takes the TEXT of a task rather than a whole tracker line, which is
+ * what `findNextTask` hands its caller. The anchor is therefore end of
+ * text, and a trailing space is tolerated because the tracker's own
+ * spelling puts two before the block.
+ */
+export declare function parseTaskDeclaration(taskText: string): ParsedTask;
+/** The task text alone, for a caller with no use for the record. */
+export declare function stripTaskDeclaration(taskText: string): string;
+/**
+ * Answers whether the named agent's definition declares an effort of
+ * its own. The loop's answer comes from the definition's frontmatter
+ * (`utils/agent-definition.ts`); a test hands in whatever its case is
+ * about.
+ */
+export type AgentEffortLookup = (agent: string) => boolean;
+/**
+ * Maps a declaration onto the flags the loop spawns Claude with.
+ *
+ * An `agent` outranks `model` and `tools` whenever it is named: the
+ * agent definition already names a model and a tool set, and passing
+ * a flag beside it would leave two authorities for one decision with
+ * no way to tell which won. `effort` is the exception. It joins
+ * `--agent` as `--effort` unless `agentDeclaresEffort` answers that
+ * the named agent's definition declares an effort of its own, because
+ * a definition silent on effort leaves the plan's level the only one
+ * there is. The lookup is asked only about a block carrying both keys,
+ * so every other block resolves without reading a definition. A name
+ * no definition answers for is the lookup's `false` and still passes
+ * `--effort`, leaving the CLI to refuse the name before any model
+ * call.
+ *
+ * Granular keys an agent outranked are named in
+ * {@link ResolvedFlags.suppressed} rather than dropped, which is what
+ * lets the dispatch say what it left to the agent. `skills`, `tests`
+ * and `docs` are not among them: they map to no flag under any block,
+ * so no agent ever took them.
+ *
+ * `budget` passes {@link BUDGET_FLAG} whatever else the block holds, an
+ * agent included, since a definition supplies no budget, and is never
+ * named as suppressed. It goes after `--effort` and ahead of `--tools`,
+ * whose variadic value has to end the list.
+ *
+ * A key whose value did not parse is absent from the record and so
+ * emits nothing here — the task runs at the loop's defaults, which is
+ * the failure worth having.
+ */
+export declare function resolveDeclarationFlags(declaration: TaskDeclaration | null, agentDeclaresEffort: AgentEffortLookup): ResolvedFlags;