@open-tomato/rafa 0.44.0 → 0.46.0

package/dist/report/parse.d.ts

@@ -0,0 +1,415 @@
+/**
+ * The task report: the `rafa:report` block a task session ends its final
+ * message with, read out of the session's captured output.
+ *
+ * `runClaudeCaptured` answers a session's stdout, which under `claude -p`
+ * is the session's final message. The message ends with one fenced block
+ * the loop acts on:
+ *
+ * ````markdown
+ * ```rafa:report
+ * status: done
+ * feedback: |
+ *   What was done and how it went, one block.
+ * findings:
+ *   - trigger: "when running bun test under a fresh worktree"
+ *     kind: gotcha
+ *     what: "node_modules is absent after fork"
+ *     cause: "worktree creation does not run bun install"
+ *     resolution: "run bun install before the first test"
+ *     artifact: "Cannot find package"
+ *     signal: loud
+ *     domain: testing
+ * skills_used: [git-workflow]
+ * blockers:
+ *   - what: "LINEAR_API_KEY unset"
+ *     artifact: "401 Unauthorized"
+ * out_of_scope_bugs:
+ *   - what: "..."
+ *     artifact: "..."
+ *     security: false
+ *     kind: bug
+ * changes:
+ *   - level: patch
+ *     area: "loop"
+ *     summary: "the loop waits for the running task's commit"
+ * stale_docs:
+ *   - where: "context/triage.md:12"
+ *     what: "says triage has three channels"
+ * ```
+ * ````
+ *
+ * {@link parseReport} is the whole interface. It takes any string, never
+ * throws, and answers either the report or an explicit record of why
+ * there is none. The prompt asks for the block and the loop has to live
+ * without it, so a missing report is an answer here, not an exception.
+ *
+ * ## Which block is read
+ *
+ * Blocks are found by `readRafaBlocks`, so fences follow its rules: a
+ * `rafa:report` fence that does not open its line is prose quoting the
+ * syntax, and a report illustrated inside a longer fence is that fence's
+ * body. Blocks of every other kind are ignored.
+ *
+ * Only the LAST `rafa:report` block counts. Anything earlier is a draft
+ * the final block replaces, or the session quoting the format while it
+ * works. When the last block cannot be read, no earlier one is read in
+ * its place: that would record a report the session had already replaced.
+ *
+ * ## Absence
+ *
+ * {@link ReportAbsent.reason} says why there is no report:
+ *
+ *   - `no-block`: the output holds no `rafa:report` block.
+ *   - `unclosed-block`: the last block is never closed. It is not read,
+ *     because a body cut short can still be valid YAML, just with the
+ *     later findings missing. Reading it would shorten the findings list
+ *     without anyone noticing.
+ *   - `malformed-block`: the last block's body is not valid YAML, or is
+ *     not a mapping. An empty body is not a mapping either.
+ *
+ * Every reason but `no-block` carries the block, so its raw body reaches
+ * whoever records the absence.
+ *
+ * ## Fields
+ *
+ * A readable block answers a {@link TaskReport}, plus
+ * {@link ReportPresent.issues} for whatever it did not read as written.
+ * The rules are the ones `core/plan/parse.ts` applies to a plan header.
+ *
+ *   - An UNKNOWN key, at the top level or inside an entry, is retained in
+ *     that level's `extras` and acts on nothing. This is the rule
+ *     `core/plan/declaration.ts` applies to an unrecognised key, for the same
+ *     reason: a report written for a later phase must not break this one.
+ *   - A known key that is absent, or set to null, says nothing. When the
+ *     field is required, that is a `missing-field` issue.
+ *   - A known key whose value is unusable is left null and reported as
+ *     `unusable-field`. That covers a string field holding something
+ *     other than a string or only whitespace, a closed-set field holding
+ *     a value outside {@link REPORT_STATUSES}, {@link FINDING_KINDS},
+ *     {@link FINDING_SIGNALS}, {@link FINDING_DOMAINS},
+ *     {@link CHANGE_LEVELS} or {@link BUG_KINDS}, and a `security`
+ *     flag that is not a boolean. The sets are closed because stored rows
+ *     are keyed on them. A later phase promotes a `silent` finding on its
+ *     first sighting, for example, so a signal spelled any other way must
+ *     not reach the store looking meaningful.
+ *   - A list field holding something other than a list reads as empty,
+ *     and is reported. A list entry that is not a mapping, or a
+ *     `skills_used` entry that is not a usable string, is dropped and
+ *     reported under its index.
+ *
+ * Required fields: `status`; a finding's `trigger`, `kind`, `what` and
+ * `signal`; a blocker's `what`; an out-of-scope bug's `what` and
+ * `security`; a change note's `level` and `summary`; a stale doc's `what`.
+ * A missing `security` flag stays null rather than defaulting to false,
+ * because this parser does not get to decide that a bug has no security
+ * impact.
+ *
+ * ## An out-of-scope entry's kind
+ *
+ * An `out_of_scope_bugs` entry's `kind` says what sort of leftover it
+ * is, one of {@link BUG_KINDS}. It is a different field from a
+ * finding's `kind`, with its own list.
+ *
+ * It is the one closed-set field that never reads as null. The key was
+ * added after reports of three keys per entry were already being
+ * written, so an entry with no `kind` reads as `bug` with no issue: a
+ * session on an older prompt changes nothing. A value outside the list
+ * is reported as `unusable-field` and also reads as `bug`, the kind an
+ * entry had before the key existed.
+ *
+ * ## An out-of-scope entry's bug fields
+ *
+ * Four more keys of an `out_of_scope_bugs` entry carry what a bug record
+ * needs, each optional and read as a plain string, null when absent:
+ *
+ *   - `module`: the part of the code the bug sits in.
+ *   - `action`: what was being done when it showed.
+ *   - `reproduce`: the command or steps that show it again.
+ *   - `cause`: why it happens, as a cause code or in words.
+ *
+ * Whether `cause` is a code or a sentence is the cause rule's business,
+ * never this parser's: it is kept as written either way. A value holding
+ * `: ` has to be double-quoted, as every string value does. A report on
+ * the prompt before the keys existed, with none of them, reads with no
+ * issue.
+ *
+ * ## Change notes
+ *
+ * `changes` is the list of changelog lines a task returns for its own
+ * diff. A note's `summary` is one line a user of the project would
+ * understand, and its `area` is the short free-text heading the changelog
+ * groups it under. Its `level` says how much of a release the change is
+ * worth, one of {@link CHANGE_LEVELS}: a task whose diff a user would
+ * notice nothing of writes `level: none`, and a task with nothing to say
+ * at all omits the list. An absent list is exactly that — empty, with no
+ * issue — because a note the task did not write is not one to invent.
+ *
+ * {@link CHANGE_LEVELS} is spelled in the order the spec writes it and
+ * carries no ranking. Whatever computes a release level out of a plan's
+ * notes orders them itself; reading precedence off this list's indices
+ * would make `none` the highest of the four.
+ *
+ * ## Stale docs
+ *
+ * `stale_docs` is the list of documentation lines a task saw that no
+ * longer match the code and that its own change did not falsify. An
+ * entry's `where` is the file, with the line when known, as one string
+ * such as `context/triage.md:12`; its `what` says what no longer matches.
+ *
+ * This is the one list whose entry is dropped for a field: an entry with
+ * no usable `what` is reported and left out of {@link TaskReport.staleDocs},
+ * because a place with nothing said about it is not a row anyone can
+ * settle. An entry with no usable `where` is kept, with `where` null.
+ *
+ * The key is the eighth, added after reports of seven were already being
+ * written. A report with no `stale_docs` key reads as an empty list with
+ * no issue, like every other absent list, so a session on an older prompt
+ * is neither failed nor flagged for writing seven fields.
+ *
+ * Strings are kept exactly as written, never trimmed. `artifact` is the
+ * byte string a recurrence is matched on. A blank one is refused, because
+ * every blank artifact would dedupe into one finding.
+ *
+ * Nothing is deduped or summarised. Every usable entry is carried, in
+ * order, duplicates included. Deduping is the findings writer's job: by
+ * `artifact` when present, otherwise by exact `trigger` plus `what`.
+ *
+ * An issue's `field` is a path in the report's own key names
+ * (`findings[2].signal`, `skills_used[0]`), so it can be found in the
+ * block as written. Issues come in the order {@link TaskReport} lists its
+ * fields, with each entry's fields in the order its type lists them.
+ *
+ * ## The parser, measured on bun 1.3.14
+ *
+ * `Bun.YAML.parse` reads the body. A report is written by a model and
+ * quotes error messages, which is where these readings bite:
+ *
+ *   - A `#` after a space opens a comment, so `artifact: error #42 here`
+ *     reads as `"error"`. That loses bytes without an error and cannot be
+ *     detected here. Only quoting prevents it.
+ *   - An unquoted value that opens with a backtick, `@`, `%` or `[`, or
+ *     that holds `: `, throws. One unquoted error message makes the whole
+ *     block `malformed-block`, losing every finding in it.
+ *   - The `SyntaxError` message names no line, so the block's `span` is
+ *     the only location an absence can give.
+ *   - `artifact: 404` and `artifact: 0042` read as numbers (the second as
+ *     42), and `.inf` as `Infinity`. A number is refused rather than
+ *     turned back into a string that may differ from the one written.
+ *   - `security: yes` reads as the string `"yes"`, which is refused, and
+ *     `security: False` reads as the boolean false.
+ *   - A `feedback: |` block keeps one trailing newline. Feedback is kept
+ *     as parsed.
+ *   - A body with a `---` separator reads as a LIST of documents, so it
+ *     is `malformed-block`. A duplicated key keeps its last value and
+ *     leaves no trace, so nothing here can report it.
+ *   - A key spelled `__proto__` or `constructor` is an ordinary own key.
+ *     Keys are matched against a list of names, never looked up by
+ *     object index, so such a key lands in `extras`.
+ */
+import type { RafaBlock } from '../core/plan/block-reader.js';
+/** What a session says of its own task. The loop's outcome is separate. */
+export declare const REPORT_STATUSES: readonly ["done", "blocked"];
+/** One of the two statuses a report can claim. */
+export type ReportStatus = (typeof REPORT_STATUSES)[number];
+/** What a finding is about. */
+export declare const FINDING_KINDS: readonly ["gotcha", "pattern", "location", "skill-suggestion"];
+/** One of the four finding kinds. */
+export type FindingKind = (typeof FINDING_KINDS)[number];
+/** Whether a finding surfaced as a failure, or passed while wrong. */
+export declare const FINDING_SIGNALS: readonly ["loud", "silent"];
+/** One of the two finding signals. */
+export type FindingSignal = (typeof FINDING_SIGNALS)[number];
+/**
+ * What area of work a finding's lesson belongs to. Optional on a
+ * finding; the lesson made from it defaults an absent one.
+ *
+ * continuous-learning-v2's domains: the five its `SKILL.md` names, and
+ * the three its `agents/observer.md` calls global-friendly, measured
+ * on 2026-09-18. Its `instinct-cli.py` defaults an absent domain to
+ * `general`, which is not one of these and is not accepted here; an
+ * importer meeting one has to map it.
+ *
+ * Declared here rather than in `schema/instinct.ts`, which re-exports it
+ * as `INSTINCT_DOMAINS`: that module already imports this one, and this
+ * one importing it back fails at load with `Cannot access
+ * 'FINDING_KINDS' before initialization`.
+ */
+export declare const FINDING_DOMAINS: readonly ["code-style", "testing", "git", "debugging", "workflow", "security", "general-best-practices"];
+/** One of the finding domains. */
+export type FindingDomain = (typeof FINDING_DOMAINS)[number];
+/** How much of a release one change note is worth. */
+export declare const CHANGE_LEVELS: readonly ["patch", "minor", "major", "none"];
+/** One of the four change levels. */
+export type ChangeLevel = (typeof CHANGE_LEVELS)[number];
+/**
+ * What sort of leftover an `out_of_scope_bugs` entry is: `bug`, code
+ * doing the wrong thing that this plan did not cause; `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 or a name off the pattern; `docs`, a stale doc line;
+ * `machine`, this machine's fault.
+ */
+export declare const BUG_KINDS: readonly ["bug", "own-fallout", "own-gap", "convention", "docs", "machine"];
+/** One of the six out-of-scope entry kinds. */
+export type BugKind = (typeof BUG_KINDS)[number];
+/** One key the parser does not know, at whatever level it was written. */
+export interface ReportExtra {
+    /** The key as written. */
+    readonly key: string;
+    /**
+     * The value exactly as the parser returned it. Never serialised here:
+     * a YAML alias can share it with another value.
+     */
+    readonly value: unknown;
+}
+/** One `findings` entry. */
+export interface ReportFinding {
+    /** When the finding surfaced. Required. */
+    readonly trigger: string | null;
+    /** What the finding is about. Required. */
+    readonly kind: FindingKind | null;
+    /** The finding itself. Required. */
+    readonly what: string | null;
+    /** Why it happens. */
+    readonly cause: string | null;
+    /** What resolves it. */
+    readonly resolution: string | null;
+    /** The byte string a recurrence would match on. */
+    readonly artifact: string | null;
+    /** Whether it failed loudly or passed silently. Required. */
+    readonly signal: FindingSignal | null;
+    /** What area of work its lesson belongs to. */
+    readonly domain: FindingDomain | null;
+    /** Every key that names no field. */
+    readonly extras: readonly ReportExtra[];
+}
+/** One `blockers` entry. */
+export interface ReportBlocker {
+    /** What blocked the task. Required. */
+    readonly what: string | null;
+    /** The byte string that showed it. */
+    readonly artifact: string | null;
+    /** Every key that names no field. */
+    readonly extras: readonly ReportExtra[];
+}
+/** One `out_of_scope_bugs` entry. */
+export interface ReportBug {
+    /** The bug. Required. */
+    readonly what: string | null;
+    /** The byte string that showed it. */
+    readonly artifact: string | null;
+    /** Whether the bug has a security impact. Required; never defaulted. */
+    readonly security: boolean | null;
+    /**
+     * What sort of leftover it is. Never null: an absent key reads as
+     * `bug` with no issue, and a value outside {@link BUG_KINDS} as `bug`
+     * with an `unusable-field` issue.
+     */
+    readonly kind: BugKind;
+    /** The part of the code the bug sits in. */
+    readonly module: string | null;
+    /** What was being done when the bug showed. */
+    readonly action: string | null;
+    /** The command or steps that show the bug again. */
+    readonly reproduce: string | null;
+    /** Why the bug happens, a cause code or words, kept as written. */
+    readonly cause: string | null;
+    /** Every key that names no field. */
+    readonly extras: readonly ReportExtra[];
+}
+/** One `changes` entry: a changelog line, as the task wrote it. */
+export interface ReportChange {
+    /** How much of a release the change is worth. Required. */
+    readonly level: ChangeLevel | null;
+    /** The short heading the changelog groups the line under. */
+    readonly area: string | null;
+    /** One line a user of the project would understand. Required. */
+    readonly summary: string | null;
+    /** Every key that names no field. */
+    readonly extras: readonly ReportExtra[];
+}
+/** One `stale_docs` entry: a documentation line that no longer matches. */
+export interface ReportStaleDoc {
+    /** The file, with the line when known: `context/triage.md:12`. */
+    readonly where: string | null;
+    /** What no longer matches. Required; an entry without one is dropped. */
+    readonly what: string;
+    /** Every key that names no field. */
+    readonly extras: readonly ReportExtra[];
+}
+/** A `rafa:report` block, read. */
+export interface TaskReport {
+    /** The session's claim for its task. Required. */
+    readonly status: ReportStatus | null;
+    /** What was done and how it went, as parsed. */
+    readonly feedback: string | null;
+    /** Every usable `findings` entry, in order, none merged. */
+    readonly findings: readonly ReportFinding[];
+    /** Every usable `skills_used` entry, in order. */
+    readonly skillsUsed: readonly string[];
+    /** Every usable `blockers` entry, in order. */
+    readonly blockers: readonly ReportBlocker[];
+    /** Every usable `out_of_scope_bugs` entry, in order. */
+    readonly outOfScopeBugs: readonly ReportBug[];
+    /** Every usable `changes` entry, in order. */
+    readonly changes: readonly ReportChange[];
+    /** Every `stale_docs` entry that says what is stale, in order. */
+    readonly staleDocs: readonly ReportStaleDoc[];
+    /** Every top-level key that names no field. */
+    readonly extras: readonly ReportExtra[];
+}
+/** Why a field was not read as written. */
+export type ReportIssueReason = 
+/** A required field that is absent or null. */
+'missing-field'
+/** A value the field cannot hold. Left null, or dropped from its list. */
+ | 'unusable-field';
+/** One thing the report said that the model does not hold as written. */
+export interface ReportIssue {
+    /** What went unread, and why. */
+    readonly reason: ReportIssueReason;
+    /** Where, in the report's own key names: `findings[2].signal`. */
+    readonly field: string;
+    /** One sentence for an operator to read. */
+    readonly text: string;
+}
+/** Why a session output answers no report. */
+export type ReportAbsenceReason = 
+/** The output holds no `rafa:report` block. */
+'no-block'
+/** The last `rafa:report` block is never closed. */
+ | 'unclosed-block'
+/** The last `rafa:report` block is not YAML, or not a mapping. */
+ | 'malformed-block';
+/** A session output whose last `rafa:report` block was read. */
+export interface ReportPresent {
+    readonly present: true;
+    /** The report. */
+    readonly report: TaskReport;
+    /** The block it was read from: the last `rafa:report` in the output. */
+    readonly block: RafaBlock;
+    /** What was not read as written. Empty for a clean report. */
+    readonly issues: readonly ReportIssue[];
+}
+/** A session output that answers no report, and why. */
+export interface ReportAbsent {
+    readonly present: false;
+    /** Why there is no report. */
+    readonly reason: ReportAbsenceReason;
+    /** The last `rafa:report` block, raw body included, or null for `no-block`. */
+    readonly block: RafaBlock | null;
+    /** One sentence for an operator to read. */
+    readonly text: string;
+}
+/** What {@link parseReport} answers: a report, or why there is none. */
+export type ReportReading = ReportPresent | ReportAbsent;
+/**
+ * Reads the last `rafa:report` block out of a session's captured output.
+ *
+ * Takes any string, normally `CapturedSession.stdout`. Answers the report
+ * with an issue for everything not read as written, or an absence naming
+ * why there is none. Never throws. See the module note for which block
+ * counts and how each field is read.
+ */
+export declare function parseReport(output: string): ReportReading;

package/dist/schema/project-id.d.ts

@@ -0,0 +1,79 @@
+/**
+ * `project_id`: the twelve hex characters an instinct record carries to
+ * say which repository it was learned in, derived from that
+ * repository's `origin` remote.
+ *
+ * This is somebody else's algorithm, reproduced on purpose.
+ * `~/.claude/skills/continuous-learning-v2/scripts/detect-project.sh`
+ * files its own instincts under exactly this hash, so a record rafa
+ * writes and a record that skill writes for the same repository have
+ * to carry the SAME id or the two stores cannot be read together. That
+ * makes the NORMALISATION matter as much as the hash: the same
+ * repository is spelled `git@github.com:o/r.git`,
+ * `https://github.com/O/R.git` and `https://token@github.com/o/r`
+ * by three different checkouts, and all three have to land on one id.
+ *
+ * {@link normalizeRemote} is that script's four `sed -E` lines in
+ * order — strip embedded credentials, strip the scheme, rewrite
+ * `git@host:path` as `host/path`, drop a trailing `.git` and slashes —
+ * followed by its lowercasing of a network URL only. A local path
+ * keeps its case because a case-sensitive filesystem makes
+ * `/Users/Marcos` and `/users/marcos` different directories.
+ *
+ * Six remotes were run through the shell function's own text and
+ * `shasum -a 256` on 2026-09-18, and their normalised forms and
+ * digests are pinned as literals in `project-id.test.ts`. That pinning
+ * is the ONLY thing that can catch this implementation drifting from
+ * the shell one: nothing else in the repository compares them, and a
+ * drift produces two stores that quietly disagree rather than an
+ * error.
+ *
+ * ## What is deliberately not reproduced
+ *
+ * That script has a fallback chain past the remote: it hashes the main
+ * worktree root when a repository has no `origin`, and answers the
+ * literal `global` outside a repository. {@link projectId} answers null
+ * for both, because a path-derived id is machine-specific and a record
+ * carrying one would claim a cross-machine identity it does not have.
+ * `project_id` on a record is optional for exactly this reason.
+ *
+ * Nothing here throws. {@link gitRemoteUrl} answers null for a missing
+ * remote, a directory in no repository and a machine with no git
+ * alike, because the caller's next move is the same in all three: omit
+ * the field.
+ */
+/** Characters of the remote's SHA-256 a `project_id` keeps. */
+export declare const PROJECT_ID_LENGTH = 12;
+/** The shape {@link projectIdFromRemote} produces: lowercase hex. */
+export declare const PROJECT_ID_PATTERN: RegExp;
+/**
+ * `url` as continuous-learning-v2 hashes it: credentials stripped, the
+ * scheme dropped, `git@host:path` rewritten `host/path`, a trailing
+ * `.git` and slashes removed, and a network URL lowercased while a
+ * local path keeps its case. Like `sed` without `g`, each step
+ * replaces only the first match.
+ */
+export declare function normalizeRemote(url: string): string;
+/**
+ * The first {@link PROJECT_ID_LENGTH} hex characters of the SHA-256 of
+ * {@link normalizeRemote}'s answer, or null when `url` says nothing.
+ * The same id `detect-project.sh` derives for the same repository.
+ */
+export declare function projectIdFromRemote(url: string): string | null;
+/**
+ * `origin`'s URL for the repository holding `dir`, or null when there
+ * is no origin, no repository or no git. Never throws: see the module
+ * note on why all three are one answer.
+ */
+export declare function gitRemoteUrl(dir: string): string | null;
+/** What {@link projectId} reads the world through. */
+export interface ProjectIdSeams {
+    /** The remote probe. {@link gitRemoteUrl} when absent. */
+    readonly readRemote?: (dir: string) => string | null;
+}
+/**
+ * The `project_id` a record written for the repository holding `dir`
+ * carries, or null when that repository has no `origin` — which is the
+ * whole reason the field is optional.
+ */
+export declare function projectId(dir: string, seams?: ProjectIdSeams): string | null;

package/dist/schema/tiers.d.ts

@@ -0,0 +1,107 @@
+/** The skill tiers, nearest the work first. */
+export declare const SKILL_TIERS: readonly ["project", "rafa", "user"];
+/** One of {@link SKILL_TIERS}. */
+export type SkillTier = typeof SKILL_TIERS[number];
+/** The instinct scopes, nearest the work first. There is no rafa scope. */
+export declare const INSTINCT_SCOPES: readonly ["project", "user"];
+/** One of {@link INSTINCT_SCOPES}. */
+export type InstinctScope = typeof INSTINCT_SCOPES[number];
+/** The skills directory Claude Code loads, under a project root or the home. */
+export declare const CLAUDE_SKILLS_PATH: string;
+/** The instincts directory a scope holds, under a project root or the home. */
+export declare const RAFA_INSTINCTS_PATH: string;
+/** The directory rafa's own skills sit in, relative to the running `cli.js`. */
+export declare const BUNDLED_SKILLS_DIR: string;
+/** The directory rafa's own programs sit in, relative to the running `cli.js`. */
+export declare const BUNDLED_BIN_DIR: string;
+/** What a tier is resolved against. Each seam is given; none is read from the environment. */
+export interface TierSeams {
+    /** The home directory, an absolute path. */
+    readonly home: string;
+    /** The project root, or null when the caller stands in no project. */
+    readonly projectRoot: string | null;
+    /** This process's entry, which the rafa tier sits beside. Defaults to `Bun.main`. */
+    readonly entry?: string;
+}
+/** One tier and the directory it resolves to. */
+export interface SkillTierLocation {
+    /** Which tier. */
+    readonly tier: SkillTier;
+    /** The directory it resolves to, absolute. */
+    readonly dir: string;
+}
+/** One instinct scope and the directory it resolves to. */
+export interface InstinctScopeLocation {
+    /** Which scope. */
+    readonly scope: InstinctScope;
+    /** The directory it resolves to, absolute. */
+    readonly dir: string;
+}
+/** Whether `value` names a tier, for a `rafa skill list --source` a line typed. */
+export declare function isSkillTier(value: string): value is SkillTier;
+/** Whether `value` names an instinct scope. */
+export declare function isInstinctScope(value: string): value is InstinctScope;
+/** `entry` with its links resolved, or as it was when nothing is there. */
+export declare function realEntry(entry: string): string;
+/**
+ * The directory rafa's own skills sit in: `bundled/skills` beside the
+ * running `cli.js`, links resolved. See the module note.
+ */
+export declare function bundledSkillsDirectory(entry?: string): string;
+/**
+ * The directory rafa's own programs sit in: `bundled/bin` beside the
+ * running `cli.js`, links resolved, as {@link bundledSkillsDirectory}
+ * resolves its skills. A build writes `ts-symbols` there; a checkout's
+ * `src/bundled/` holds no `bin/`, so run as `bun src/rafa.ts` it names
+ * a directory that is not there.
+ */
+export declare function bundledBinDirectory(entry?: string): string;
+/**
+ * The directory `tier` resolves to, or null for the project tier with
+ * no project root: a tier with no directory is not an empty one, and
+ * a caller has to be able to tell them apart.
+ */
+export declare function skillTierDirectory(tier: SkillTier, seams: TierSeams): string | null;
+/**
+ * Every tier that has a directory, in {@link SKILL_TIERS} order. The
+ * directory need not be there: an absent one is {@link tierExists}'s
+ * question, and a tier is left out here only when it resolves to no
+ * path at all.
+ */
+export declare function resolveSkillTiers(seams: TierSeams): readonly SkillTierLocation[];
+/** The directory `scope` resolves to, or null for the project scope with no project root. */
+export declare function instinctScopeDirectory(scope: InstinctScope, seams: TierSeams): string | null;
+/** Every instinct scope that has a directory, in {@link INSTINCT_SCOPES} order. */
+export declare function resolveInstinctScopes(seams: TierSeams): readonly InstinctScopeLocation[];
+/** What {@link shadowLessonsById} ranks: a record, the scope holding it, and its id. */
+export interface ScopedLesson {
+    /** The scope that holds it. */
+    readonly scope: InstinctScope;
+    /** The id a nearer scope shadows it by. */
+    readonly id: string;
+}
+/** A record that lost to a nearer one of the same id. */
+export interface ShadowedLesson<T extends ScopedLesson> {
+    /** The record that lost. */
+    readonly record: T;
+    /** The record that shadows it, in a nearer scope or first in the same one. */
+    readonly by: T;
+}
+/** What {@link shadowLessonsById} answers. */
+export interface LessonShadowing<T extends ScopedLesson> {
+    /** One record per id, in {@link INSTINCT_SCOPES} order, then the order handed. */
+    readonly winners: readonly T[];
+    /** Every other record, each beside the winner that shadows it. */
+    readonly shadowed: readonly ShadowedLesson<T>[];
+}
+/**
+ * The record a reader takes for each `id` across the instinct scopes:
+ * the project scope's before the user scope's. Records may come in any
+ * order and are taken in scope order, stably, so a second record of
+ * one id inside one scope is shadowed by the first that scope was
+ * handed. Throws on a record whose scope is not an instinct scope:
+ * the rafa tier holds no lessons (see the module note).
+ */
+export declare function shadowLessonsById<T extends ScopedLesson>(records: readonly T[]): LessonShadowing<T>;
+/** Whether a resolved tier or scope directory is there at all. */
+export declare function tierExists(dir: string): boolean;