@open-tomato/rafa 0.44.0 → 0.46.0

package/dist/core/config/config-items.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The two item shapes the schema's lists hold: a prerequisite item and
+ * a module source, each read by one reader of `config-sections.ts`'s
+ * {@link Reader} shape.
+ *
+ * Every other rule about a VALUE is `config-sections.ts`'s, and so are
+ * the rules every reader keeps, items included: a kind key matched with
+ * `===`, a null optional key saying nothing, and a key an item does not
+ * read retained as a {@link ConfigExtra}. The shapes moved here out of
+ * that module to keep it under the size cap of `context/source.md`: it
+ * stood at 792 lines before the move. `config.ts` re-exports the item
+ * types and kind lists, as it did while they lived there.
+ *
+ * The import runs one way. This module reads the reading helpers
+ * `config-sections.ts` exports, and that module imports nothing from
+ * this one, so the two form no cycle.
+ *
+ * ## The item shapes
+ *
+ * A prerequisite item names exactly one of `tool`, `env`, `service` or
+ * `lsp`, may carry a `probe`, and on the optional tier a `reason`. That
+ * is the shape of the block under "Config schema" in
+ * `.rafa/specs/phase-1-installable.md`. A `reason` on a required item is a
+ * key that tier does not read, so it is retained and warned about.
+ *
+ * A module source names exactly one of `npm`, `github` or `path`, and a
+ * `github` source may carry a `ref`: the source shapes of the registry
+ * example in `.rafa/specs/modules-and-addons.md`, which `modules:` lists
+ * "by source". This module accepts all three. Whether a source kind can
+ * be loaded is the module loader's answer, not the config's.
+ */
+import type { Reader } from './config-sections.js';
+/** The keys one of which names a prerequisite item. */
+export declare const PREREQUISITE_KINDS: readonly ["tool", "env", "service", "lsp"];
+/** One of the four prerequisite kinds. */
+export type PrerequisiteKind = (typeof PREREQUISITE_KINDS)[number];
+/**
+ * Which of a run's dispatches need a plan's item: its tasks, its wrap-up,
+ * or both. Read from the `[tasks]` or `[wrap-up]` marker of a
+ * PREREQUISITES file (`src/preflight/prerequisites-md.ts`).
+ */
+export type PrerequisiteScope = 'tasks' | 'wrap-up' | 'both';
+/** One item of `prerequisites.required`. */
+export interface PrerequisiteItem {
+    /** Which of the four keys named it. */
+    kind: PrerequisiteKind;
+    /** What that key named: `bun`, `GITHUB_TOKEN`, a URL, `typescript`. */
+    name: string;
+    /** The command that proves it, or null to check presence alone. */
+    probe: string | null;
+    /**
+     * The scope a plan's PREREQUISITES file gave the item. Left out of an
+     * item the config names, which has no spelling for one.
+     */
+    scope?: PrerequisiteScope;
+}
+/** One item of `prerequisites.optional`. */
+export interface OptionalPrerequisiteItem extends PrerequisiteItem {
+    /** Why the item helps, for the line naming it missing; or null. */
+    reason: string | null;
+}
+/** The keys a required prerequisite item reads. */
+export declare const REQUIRED_ITEM_KEYS: readonly string[];
+/** The keys an optional prerequisite item reads. */
+export declare const OPTIONAL_ITEM_KEYS: readonly string[];
+/** Reads one `prerequisites.required` item. */
+export declare const requiredPrerequisite: Reader<PrerequisiteItem>;
+/** Reads one `prerequisites.optional` item. */
+export declare const optionalPrerequisite: Reader<OptionalPrerequisiteItem>;
+/** The keys one of which names a module source. */
+export declare const MODULE_SOURCE_KINDS: readonly ["npm", "github", "path"];
+/** One of the three module source kinds. */
+export type ModuleSourceKind = (typeof MODULE_SOURCE_KINDS)[number];
+/** One entry of `modules:`: where a module is installed from. */
+export interface ModuleSource {
+    /** Which of the three keys named it. */
+    kind: ModuleSourceKind;
+    /** What that key named: a package name, an `owner/repo`, a path. */
+    location: string;
+    /** The git ref beside a `github` source; null for every other. */
+    ref: string | null;
+}
+/** The keys a module source reads, `ref` on a `github` one alone. */
+export declare const MODULE_SOURCE_KEYS: readonly string[];
+/** Reads one `modules:` entry. */
+export declare const moduleSource: Reader<ModuleSource>;

package/dist/core/config/config-load.d.ts

@@ -0,0 +1,47 @@
+import type { ConfigFile, ConfigOverrides, ResolvedConfig } from './config.js';
+/** The two directories {@link loadConfig} reads a config file under. */
+export interface ConfigRoots {
+    /** The project root: its scope's files sit here and under its `.rafa/`. */
+    readonly root: string;
+    /** The home directory: the user scope's files sit under its `.rafa/`. */
+    readonly home: string;
+}
+/**
+ * Reads `.rafa/config.yaml` under `root`, or answers null when nothing
+ * is at that path. Anything there that cannot be read — a directory,
+ * a file without read permission — is refused with a
+ * {@link ConfigError} rather than read as absent; see the module note.
+ * Reads the YAML file alone: {@link loadConfig} is what looks up a
+ * scope's module files.
+ */
+export declare function readConfigFile(root: string): ConfigFile | null;
+/**
+ * Reads the user scope's file under `roots.home` and the project's
+ * under `roots.root`, ranks both against `cli`, and prints a warning
+ * per shadowed YAML file, per key set twice in one file and per unknown
+ * key through `warn`, the active output's `warn` when none is given.
+ * After them it writes one pass line per `dangerous.*` key set off its
+ * default (`dangerous.ts`), once per invocation: the active output's
+ * when `warn` is the default, the sink's own when one is given.
+ *
+ * The resolved config is handed to the load hook (`activeConfigLoadHook`
+ * in `section.ts`) before any warning is printed. The registry,
+ * `src/config-registry.ts`, sets that hook to hand the logger
+ * (`adapters/logger/settings.ts`) its `logger` settings, so a
+ * `logger.level` of `error` also quiets the warnings of the load that
+ * set it. With no hook set the logger keeps the settings it had.
+ *
+ * The resolved `effort.busyTimeoutMs` is handed to the effort store
+ * (`effort/store/settings.ts`), so every store open after this call
+ * waits that long for a lock.
+ *
+ * The files are read and judged before the command line is looked at,
+ * the user's first, so a run with problems in all three reports the
+ * user file's alone. See the module note for the home, the lookup and
+ * every refusal.
+ *
+ * @returns The resolution, with `provenance` naming the file and entry
+ *   of each setting a file answered, and `shadowed` the YAML files a
+ *   module file left unread.
+ */
+export declare function loadConfig(roots: ConfigRoots, cli?: ConfigOverrides, warn?: (message: string) => void): Promise<ResolvedConfig>;

package/dist/core/config/config-origins.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Where a resolved setting came from, and which file a scope left
+ * unread: the two records `ResolvedConfig` carries beside its values,
+ * `provenance` and `shadowed` (`config.ts`).
+ *
+ * ## An origin
+ *
+ * A {@link SettingOrigin} names the file that answered one setting and
+ * the entry of that file that last set it, zero-based, as
+ * `@open-tomato/define-config` counts a module file's entries. A YAML
+ * file is one entry, so every setting it answers is entry 0. A setting
+ * the command line or a default answered has no origin: no file set it.
+ *
+ * {@link originOf} reads the origin off the layer `resolveConfig`
+ * ranked first, so it follows `sources` exactly: `file` names the
+ * project's file, `user` the user scope's, and `cli` and `default` name
+ * none. A map setting merged across both files names the project's,
+ * the file its source names.
+ *
+ * ## A shadowed file
+ *
+ * A scope is read from one file, the first of `rafa.config.ts`,
+ * `rafa.config.mjs` and its `.rafa/config.yaml` that is a file
+ * (`config-load.ts`). A {@link ShadowedFile} is a YAML file a module
+ * file of its scope left unread, named so the warning and `rafa doctor`
+ * can say which keys stopped applying.
+ */
+import type { ConfigFile, ConfigSetting, ConfigSource } from './config.js';
+/** The two scopes a config file is read in. */
+export type ConfigScopeName = 'user' | 'project';
+/** The file and entry that answered one setting. */
+export interface SettingOrigin {
+    /** The file, as its layer names it. */
+    readonly file: string;
+    /** The zero-based entry of that file that last set the setting. */
+    readonly entry: number;
+}
+/** A YAML file left unread because a module file holds its scope. */
+export interface ShadowedFile {
+    /** The scope both files sit in. */
+    readonly layer: ConfigScopeName;
+    /** The YAML file left unread. */
+    readonly path: string;
+    /** The module file read in its place. */
+    readonly by: string;
+}
+/**
+ * The origin of `setting`, answered by the layer `source` names; see
+ * the module note.
+ *
+ * @param source - The layer that answered the setting.
+ * @param setting - The setting.
+ * @param file - The project's file, or null when there was none.
+ * @param user - The user scope's file, or null when there was none.
+ * @returns The file and entry, or null for the command line or a default.
+ */
+export declare function originOf(source: ConfigSource, setting: ConfigSetting, file: ConfigFile | null, user: ConfigFile | null): SettingOrigin | null;

package/dist/core/config/config-readers.d.ts

@@ -0,0 +1,167 @@
+/**
+ * The readers `core-section.ts` and `config-schema-release.ts` build
+ * their settings from, beyond the value readers `config-sections.ts`
+ * exports whole: {@link mapOf}, and
+ * the named readers the schema's settings are read through, each built
+ * on `mapOf` or on `config-sections.ts`'s `text` or `oneOf`. The readers a single
+ * setting spells inline, such as `oneOf(STORE_BACKENDS)`, stay beside
+ * their key in `core-section.ts`, or in `config-schema-release.ts` for
+ * a `pr` or `release` key.
+ *
+ * They sat in `config-schema.ts` until that module reached the 800-line
+ * cap of `context/source.md`, and moved out before any setting was added
+ * so a new key is not paid for by rewrapping prose. `config-sections.ts`
+ * still holds every rule about a VALUE but the release plan's, below,
+ * and the two item shapes, which `config-items.ts` reads;
+ * {@link mapOf} is here rather than there because what it rules on is a KEY: the names a map
+ * setting's file spells below its own key. Outside `packages/rafa/src/core/config/`
+ * no file imports this one by path: its names are read through the
+ * barrel `sections.ts`, by the release modules for the release plan's
+ * lists and by `tiers/routing.test.ts`, which reads a file's `routing`
+ * through {@link routeTable} as the schema does.
+ *
+ * The closed lists and readers of the release plan's keys —
+ * `release.strategy`, `release.settle`, `release.tag`,
+ * `release.publish`, `pr.versionCollision` and `release.fragments` —
+ * are value rules and
+ * sit here all the same: `config-sections.ts` stood at 781 lines,
+ * measured with `wc -l`, when they joined, and takes no new code under
+ * the 800-line cap of `context/source.md`. Each closed list is read
+ * through that module's `oneOf`, so an unknown value is refused in the
+ * words every other closed list is refused in.
+ *
+ * ## Path settings
+ *
+ * `release.fragments` names the directory a branch's wrap-up writes
+ * its change fragment into, and a fragment is committed data: settle
+ * reads the fragments present in the base branch's tree. So
+ * {@link fragmentsDirectory} refuses two paths `text` would take:
+ *
+ *   - An absolute path. The directory is read off a scratch worktree
+ *     of the base branch as well as off the caller's checkout, and an
+ *     absolute path names one place on one disk rather than a place in
+ *     every checkout.
+ *   - `.rafa` or a path below it, after `normalize` has resolved `./`
+ *     and `..` steps. `.rafa/` is gitignored, so a fragment written
+ *     there would never reach a commit and no fold would ever see it.
+ *
+ * A path is kept as written, as every other path setting keeps one;
+ * a caller joins it under the repository root.
+ *
+ * ## Map settings
+ *
+ * A map setting holds names the schema cannot list — a skill, an agent,
+ * a task shape — each with a value an inner reader checks, and
+ * {@link mapOf} reads one. Three readings are this module's:
+ *
+ *   - A name is a key the FILE spells, not one the schema knows, so it
+ *     is kept in a `Map` and never in a plain object: a skill named
+ *     `constructor` or `__proto__` is an ordinary name, and an object
+ *     would match it against `Object.prototype` or reset the
+ *     prototype. A name, like any string that names something, holds a
+ *     character other than whitespace, and is kept as written.
+ *   - Every entry is read, so a map with two unusable values names both,
+ *     as `listOf` does for a list. An entry's label and key gain its
+ *     name, `tiers.skills.tdd-guide`. A null value is handed to the
+ *     inner reader like any other, which is what a map whose values
+ *     include `false` needs: whether `false`, or null, means anything is
+ *     the inner reader's answer.
+ *   - The answer is a fresh `Map` per read, typed as a `ReadonlyMap`. A
+ *     `Map` cannot be frozen the way a list is — `Object.freeze` leaves
+ *     `set` working — so the promise that no caller edits a value for
+ *     the next is kept by building a new one each time.
+ *
+ * ## The branch template
+ *
+ * `naming.branch` is the template a plan's branch is named from: it
+ * holds {@link BRANCH_STUB} exactly once, and the branch is the template
+ * with that marker replaced by the plan's stub
+ * ({@link branchFromTemplate}). The default,
+ * {@link DEFAULT_BRANCH_TEMPLATE}, names the `feat/<stub>` branch every
+ * run created before the key existed. Exactly once, because a template
+ * without the marker names one branch for every plan, and one holding it
+ * twice leaves a guess which of the two a reader of the branch takes the
+ * stub from. Nothing else is checked: what git takes as a ref name is
+ * git's to refuse when the branch is created, naming the branch.
+ */
+import type { Reader, RouteTarget, TierPin } from './config-sections.js';
+/**
+ * Accepts a mapping of names to values `value` accepts, answered as a
+ * fresh `Map` in the order written; see "Map settings" in the module
+ * note. Every entry is read, so a map with two unusable entries names
+ * both. `expected` names the values, in the refusal of a value that is
+ * not a mapping.
+ */
+export declare function mapOf<T>(value: Reader<T>, expected: string): Reader<ReadonlyMap<string, T>>;
+/** The reader every directory setting, `plan.dir`, `specs.dir` and `loop.worktreeDir`, shares. */
+export declare const directory: Reader<string>;
+/** The reader every tracker kind goes through, alone or in a list. */
+export declare const trackerKind: Reader<string>;
+/** The reader both `release` file settings share. */
+export declare const releaseFile: Reader<string>;
+/** The reader both `tiers` maps, `tiers.skills` and `tiers.agents`, share. */
+export declare const tierPins: Reader<ReadonlyMap<string, TierPin>>;
+/** The reader of `routing`: a task shape to an agent, or `false`. */
+export declare const routeTable: Reader<ReadonlyMap<string, RouteTarget>>;
+/**
+ * The strategies `release.strategy` may name. One today: the fold that
+ * bumps the base branch's version by the highest level among the
+ * fragments it folds.
+ */
+export declare const RELEASE_STRATEGIES: readonly ["semver-by-level"];
+/** One of {@link RELEASE_STRATEGIES}. */
+export type ReleaseStrategy = (typeof RELEASE_STRATEGIES)[number];
+/**
+ * How `rafa release settle` lands a settled version on the base branch:
+ * a push to it, or a pull request into it.
+ */
+export declare const RELEASE_SETTLE_MODES: readonly ["push", "pr"];
+/** One of {@link RELEASE_SETTLE_MODES}. */
+export type ReleaseSettleMode = (typeof RELEASE_SETTLE_MODES)[number];
+/**
+ * Who puts the release tag on a settled version: a person through
+ * `rafa release tag`, or settle itself.
+ */
+export declare const RELEASE_TAG_MODES: readonly ["manual", "settle"];
+/** One of {@link RELEASE_TAG_MODES}. */
+export type ReleaseTagMode = (typeof RELEASE_TAG_MODES)[number];
+/**
+ * Who publishes a tagged version: a person running the publish command
+ * `rafa release tag` names, or the CI workflow a pushed tag starts.
+ */
+export declare const RELEASE_PUBLISH_MODES: readonly ["manual", "ci"];
+/** One of {@link RELEASE_PUBLISH_MODES}. */
+export type ReleasePublishMode = (typeof RELEASE_PUBLISH_MODES)[number];
+/**
+ * How `rafa pr merge` reacts to a branch the release guard reads as
+ * `missing` or `stale`: stay silent, report it, ask, or refuse it.
+ */
+export declare const VERSION_COLLISION_MODES: readonly ["allow", "report", "ask", "refuse"];
+/** One of {@link VERSION_COLLISION_MODES}. */
+export type VersionCollisionMode = (typeof VERSION_COLLISION_MODES)[number];
+/** The reader of `release.strategy`. */
+export declare const releaseStrategy: Reader<ReleaseStrategy>;
+/** The reader of `release.settle`. */
+export declare const releaseSettleMode: Reader<ReleaseSettleMode>;
+/** The reader of `release.tag`. */
+export declare const releaseTagMode: Reader<ReleaseTagMode>;
+/** The reader of `release.publish`. */
+export declare const releasePublishMode: Reader<ReleasePublishMode>;
+/** The reader of `pr.versionCollision`. */
+export declare const versionCollisionMode: Reader<VersionCollisionMode>;
+/**
+ * The reader of `release.fragments`: a directory path relative to the
+ * repository root and not under `.rafa/`, kept as written; see "Path
+ * settings" in the module note.
+ */
+export declare const fragmentsDirectory: Reader<string>;
+/** The marker a branch template holds once, where the plan's stub goes. */
+export declare const BRANCH_STUB = "{stub}";
+/** What `naming.branch` resolves to when no layer names it. */
+export declare const DEFAULT_BRANCH_TEMPLATE: string;
+/** True when `raw` is a string holding {@link BRANCH_STUB} exactly once; see "The branch template". */
+export declare function isBranchTemplate(raw: unknown): raw is string;
+/** The reader of `naming.branch`: a template {@link isBranchTemplate} accepts, kept as written. */
+export declare const branchTemplate: Reader<string>;
+/** The branch `template` names for a plan with this stub. */
+export declare function branchFromTemplate(template: string, stub: string): string;

package/dist/core/config/config-schema.d.ts

@@ -0,0 +1,207 @@
+/**
+ * The type half of rafa's settings: {@link RafaConfig}, the name of a
+ * setting, the settings a command line can name, and what a section
+ * knows about each setting it defines. This module declares types alone
+ * and exports no value: which settings exist at runtime, the file key
+ * each is spelled with, its reader and its default are the sections'
+ * to say.
+ *
+ * {@link RafaConfig} declares core's own fields here, and nothing else.
+ * Their file keys, readers and defaults are `core-section.ts`'s, which
+ * hands them in as `CORE_SECTION`. The other fields are the eleven
+ * section files' (`src/config-schema-*.ts`), each declaring its own
+ * interface and adding it to {@link RafaConfig} by declaration merging,
+ * a `declare module` on this file, so this module names no section file
+ * and {@link ConfigSetting} still names every setting. Nothing merged —
+ * the settings record, the defaults, the key indexes — is exported
+ * here: `src/config-registry.ts` merges the sections into them, and
+ * core reads the registered ones off `section.ts`.
+ *
+ * `config.ts` re-exports {@link RafaConfig}, {@link ConfigSetting} and
+ * {@link CommandLineSetting}, and the config barrel `index.ts` every
+ * name here, so nothing outside `packages/rafa/src/core/config/` imports this file.
+ */
+import type { ModuleSource, OptionalPrerequisiteItem, PrerequisiteItem } from './config-items.js';
+import type { BoardRelationshipMode, ClaimsAhead, ClaimsStaleAfter, ClaudeSettingSource, ConfigVersion, DuplicatesLevel, InjectMode, LessonSwitch, OutputMode, Reader, RouteTarget, SkillResolverName, StoreBackend, SyncStrategy, TierPin, TierSwitch } from './config-sections.js';
+/**
+ * Every setting, resolved. The fields below are core's, each naming the
+ * file key it holds; `core-section.ts` gives each its spec and default.
+ * A section file's fields join them by declaration merging, as the
+ * module note says.
+ */
+export interface RafaConfig {
+    /** The schema version the file was written for. `version`. */
+    version: ConfigVersion;
+    /** The backend the effort store writes through. `store`. */
+    store: StoreBackend;
+    /**
+     * How long an effort store open waits for another process's write
+     * lock, in milliseconds. `effort.busyTimeoutMs`.
+     */
+    effortBusyTimeoutMs: number;
+    /** How the effort store travels between devices. `effort.sync`. */
+    effortSync: SyncStrategy;
+    /** How much of the plan a task prompt receives. `plan.inject`. */
+    inject: InjectMode;
+    /** Where plans are written and read. `plan.dir`. */
+    planDir: string;
+    /** Where specs are read. `specs.dir`. */
+    specsDir: string;
+    /** The tracker kind tried first. `tracker.default`. */
+    trackerDefault: string;
+    /** The tracker kinds tried next, in order. `tracker.fallback`. */
+    trackerFallback: readonly string[];
+    /** The learning adapter kind. `learning.adapter`. */
+    learningAdapter: string;
+    /** The least confidence a lesson tasks may use. `learning.bless.minConfidence`. */
+    learningBlessMinConfidence: number;
+    /** The distinct sources a lesson needs to be promotable. `learning.promote.after`. */
+    learningPromoteAfter: number;
+    /** The least confidence of a promotable lesson. `learning.promote.minConfidence`. */
+    learningPromoteMinConfidence: number;
+    /** How commands write their output. `output.mode`. */
+    outputMode: OutputMode;
+    /** Items whose failure halts a run. `prerequisites.required`. */
+    prerequisitesRequired: readonly PrerequisiteItem[];
+    /** Items whose failure is only named. `prerequisites.optional`. */
+    prerequisitesOptional: readonly OptionalPrerequisiteItem[];
+    /** Whether `.rafa/specs/` is tracked by git. `tracking.specs`. */
+    trackingSpecs: boolean;
+    /** Whether `.rafa/plans/` is tracked by git. `tracking.plans`. */
+    trackingPlans: boolean;
+    /** Whether all of `.rafa/` is tracked by git. `tracking.all`. */
+    trackingAll: boolean;
+    /** Where modules are installed from. `modules`. */
+    modules: readonly ModuleSource[];
+    /** The module names enabled. `allowList`. */
+    allowList: readonly string[];
+    /** What each spawned session loads settings from. `loop.settingSources`. */
+    settingSources: readonly ClaudeSettingSource[];
+    /**
+     * The directory a loop adds its worktrees under, read from the
+     * project root. `loop.worktreeDir`.
+     */
+    loopWorktreeDir: string;
+    /**
+     * The logins trusted with board text besides the repository's own
+     * write-holders. `board.trustedAuthors`.
+     */
+    boardTrustedAuthors: readonly string[];
+    /**
+     * Where the board's epics and blockers are read and written: `labels`
+     * (`epic:` labels, `spec:blocked` and `Blocked by:` lines) or `native`
+     * (GitHub's sub-issue parent and blocked-by links).
+     * `board.relationships`.
+     */
+    boardRelationships: BoardRelationshipMode;
+    /**
+     * The GitHub project `rafa init --board` copies the board's project
+     * from, by URL. `board.project.template`.
+     */
+    boardProjectTemplate: string;
+    /**
+     * The number of the GitHub project the board is mirrored to, under the
+     * repository's owner, or null for a repository with no project.
+     * `board.project.number`.
+     */
+    boardProjectNumber: number | null;
+    /**
+     * The issue whose task list `plan create --next` reads its order off,
+     * or null for the issue titled `Roadmap`. `roadmap.issue`.
+     */
+    roadmapIssue: number | null;
+    /**
+     * How long a `rafa:claimed` claim stands before another device may
+     * take it over, or `disabled`. `claims.staleAfter`.
+     */
+    claimsStaleAfter: ClaimsStaleAfter;
+    /** Whether a claim may reach one issue ahead. `claims.ahead`. */
+    claimsAhead: ClaimsAhead;
+    /**
+     * The age in days past which `rafa cleanup` lists a branch as Stale.
+     * `cleanup.staleDays`.
+     */
+    cleanupStaleDays: number;
+    /**
+     * The idle days past which `rafa cleanup` lists a worktree.
+     * `cleanup.worktreeIdleDays`.
+     */
+    cleanupWorktreeIdleDays: number;
+    /** Glob patterns naming branches `rafa cleanup` never lists. `cleanup.keep`. */
+    cleanupKeep: readonly string[];
+    /**
+     * Whether check 4 of the readiness gate accepts every dangling and
+     * suspect reference of a spec on every run, as `--accept-refs` does
+     * on one. `dangerous.acceptStaleRefs`.
+     */
+    dangerousAcceptStaleRefs: boolean;
+    /**
+     * Whether `rafa self-update` replaces the install while a loop of the
+     * project is live, where it otherwise waits for that loop to finish.
+     * `dangerous.selfUpdateDuringLoop`.
+     */
+    dangerousSelfUpdateDuringLoop: boolean;
+    /**
+     * Whether a command that runs inside a project prints the one-line
+     * since-last-command notice on stderr. `status.notice`.
+     */
+    statusNotice: boolean;
+    /** Whether the tier rafa ships is loaded. `tiers.rafa`. */
+    tiersRafa: TierSwitch;
+    /**
+     * Skills turned off (`false`) or pinned to the tier that serves them,
+     * by name. `tiers.skills`.
+     */
+    tiersSkills: ReadonlyMap<string, TierPin>;
+    /**
+     * Agents turned off (`false`) or pinned to the tier that serves them,
+     * by name. `tiers.agents`.
+     */
+    tiersAgents: ReadonlyMap<string, TierPin>;
+    /**
+     * The agent each task shape is routed to, or `false` for a shape
+     * routed nowhere. `routing`.
+     */
+    routing: ReadonlyMap<string, RouteTarget>;
+    /** The resolver that picks each task's skills at dispatch. `task.skills`. */
+    taskSkills: SkillResolverName;
+    /** Whether blessed lessons join each task's prompt. `task.lessons`. */
+    taskLessons: LessonSwitch;
+    /**
+     * How two entries of one config file setting one key are reported:
+     * `warn`, `error` or `allow`. `merge.duplicates`.
+     */
+    mergeDuplicates: DuplicatesLevel;
+    /**
+     * The template a plan's branch is named from, holding `{stub}` exactly
+     * once; `loop start` creates the branch it names. `naming.branch`.
+     */
+    namingBranch: string;
+}
+/** The name of one setting, as a field of {@link RafaConfig}. */
+export type ConfigSetting = keyof RafaConfig;
+/**
+ * The settings a command line can name. A flag parser hands over
+ * strings, so these are the settings the file spells as one string: a
+ * list, a boolean or a mapping has no command-line spelling this module
+ * would have to invent.
+ */
+export type CommandLineSetting = 'store' | 'inject' | 'planDir' | 'specsDir' | 'trackerDefault' | 'learningAdapter' | 'outputMode' | 'settingSources' | 'taskSkills';
+/** What a section knows about one setting it defines. */
+export interface SettingSpec<K extends ConfigSetting> {
+    /** Where the file spells it, as a dotted path. */
+    key: string;
+    /** The reader deciding which raw values it accepts. */
+    read: Reader<RafaConfig[K]>;
+    /** Whether a command line can name it; checked against the type. */
+    cli: K extends CommandLineSetting ? true : false;
+    /** For a list of mappings, the keys each item reads. */
+    itemKeys?: readonly string[];
+    /**
+     * Whether the value is a map that `resolveConfig` (`config.ts`) merges
+     * by key across the default, the user's file and the project's, the
+     * later layer's entry winning for a key both name. Unset, a layer's
+     * value replaces a lower layer's whole.
+     */
+    map?: true;
+}