@holmes-lab/holmes-kit 0.1.6 → 0.1.8

package/dist/holmes/project/baseline.d.ts

@@ -0,0 +1,66 @@
+/**
+ * A NAMED reference point: "the tree as it was when this label was taken".
+ *
+ * This is the piece that makes change analysis possible without version control, and it adds no new
+ * machinery — `HashCache` already persists sha256-per-file and `ScanFileCache` stores the same hash
+ * beside each file's symbols. What was missing is a NAME, so a caller can ask "what changed since the
+ * last verified state" instead of "what changed since HEAD~1".
+ *
+ * That naming is also why this is an improvement INSIDE a git project. `HEAD~1` is a proxy for "what I
+ * have been working on" that depends entirely on commit habits — ten commits or none change the
+ * answer. `last-green`, written only when a run actually passed, does not.
+ *
+ * Storage is derived state under `.ax/state/`: reconstructable, machine-local, gitignored. It is not
+ * project content and must never be committed.
+ */
+export declare const BASELINE_DIR: string;
+export interface Baseline {
+    label: string;
+    /** ISO timestamp the baseline was taken. Informational — never an input to a change set. */
+    takenAt: string;
+    /** Project-relative POSIX path -> content hash. */
+    files: Record<string, string>;
+}
+/**
+ * @implements A-SPEC-134
+ * The tamper-evidence digest a baseline is anchored by: sha256 of the key-sorted files map. NOT the
+ * whole record (takenAt is a timestamp, not content) — only the file→hash mapping the scope narrows
+ * against. Editing any file entry changes this digest, and the anchor on the append-only chain will
+ * no longer match. Pure, key-order-insensitive.
+ */
+export declare function baselineDigest(files: Record<string, string>): string;
+/** Write (or replace) a labelled baseline. One label holds exactly one reference point. */
+export declare function writeBaseline(root: string, label: string, files: Record<string, string>): Baseline;
+/**
+ * @implements A-SPEC-134
+ * Is this baseline still the one that was recorded? Recompute its digest from the on-disk files and
+ * confirm a `baseline-recorded` chain entry carries that (label, digest). A hand-edit changes the
+ * digest and no entry matches → false. A missing baseline or missing/unreadable chain → false:
+ * cannot-verify is not permission to narrow (the caller degrades to full scope).
+ */
+export declare function isBaselineTrusted(root: string, label: string, ledgerFile: string): boolean;
+/**
+ * Read a baseline, or null when there is none.
+ *
+ * ABSENT AND EMPTY ARE DIFFERENT. Empty means "nothing existed when this was taken"; absent means
+ * "there is no reference point at all". Returning an empty baseline for a missing one would let a
+ * caller narrow its scope against a reference it never took — the silently-wrong direction. A corrupt
+ * or unreadable file is treated as absent for the same reason a cold cache is: it must degrade the
+ * run, never abort it.
+ */
+export declare function readBaseline(root: string, label: string): Baseline | null;
+/**
+ * May this run become the reference point for "since the last verified state"?
+ *
+ * ONLY a run that actually executed and passed. A red suite must not become the baseline — every
+ * later scope would then be narrowed against a state nobody verified — and a skipped run is not
+ * evidence of anything at all. This is exactly the condition that already gates writing test
+ * evidence, extracted so both branches are pinned by a test rather than only the negative one: a
+ * fixture project has no runnable suite, so the passing branch is otherwise never exercised.
+ */
+export declare function shouldRecordBaseline(result: {
+    passed: boolean;
+    skipped: boolean;
+}): boolean;
+/** Every label that exists, sorted. */
+export declare function listBaselines(root: string): string[];

package/dist/holmes/project/change-source.d.ts

@@ -0,0 +1,89 @@
+/**
+ * "What changed since a reference point" — the one question that genuinely needed version control,
+ * behind a port with two adapters so it does not need it any more.
+ *
+ * Git remains the better answer where it exists: it detects renames and it knows about commits. The
+ * snapshot adapter answers the same question from content hashes, which the scan already computes, so
+ * a project that has never run `git init` keeps change-impact, scoped regression and review.
+ *
+ * The contract that keeps this honest is `changes(): ChangeSet | null`. An unavailable source returns
+ * NULL, not empty sets: empty means "nothing changed", and a caller that read a missing reference
+ * point as "nothing changed" would narrow its scope against a baseline it never took — silently, and
+ * in the dangerous direction. Null forces a decision, and the decision the harness takes elsewhere
+ * (`computeTestScope` with no anchored tests) is to widen to full scope with a stated reason.
+ */
+export interface ChangeSet {
+    added: string[];
+    modified: string[];
+    deleted: string[];
+    renamed: {
+        from: string;
+        to: string;
+    }[];
+}
+export interface ChangeSourceInfo {
+    kind: 'git' | 'snapshot';
+    /** What the comparison is against: a git range, or a baseline label. */
+    baseline: string;
+    /** False for the snapshot adapter — a rename appears as delete + add. */
+    detectsRenames: boolean;
+    available: boolean;
+    /** Why it is unavailable. Present only when `available` is false. */
+    reason?: string;
+}
+export interface ChangeSource {
+    changes(): ChangeSet | null;
+    describe(): ChangeSourceInfo;
+}
+declare const EMPTY: ChangeSet;
+export declare const isDerivedState: (relPath: string) => boolean;
+/** Same digest the scan caches use, so a baseline and a scan cache never disagree about a file. */
+export declare const hashOf: (content: string) => string;
+/**
+ * Content hashes for every file in the tree, keyed by project-relative POSIX path.
+ *
+ * Derived state under `.ax/` is excluded (see `isDerivedState`) along with the scanner's vendor/cache
+ * skips, so a run never reports its own bookkeeping as project churn. Authored specs under
+ * `.ax/specs/**` ARE included — they are project content.
+ *
+ * Files that cannot be read are skipped rather than failing the walk — an unreadable file is not
+ * evidence of a change.
+ */
+export declare function hashTree(root: string, opts?: {
+    isIgnored?: (relPath: string) => boolean;
+}): Record<string, string>;
+/** Compare a baseline's hashes against the tree's. Pure — the adapters supply the two maps. */
+export declare function diffHashes(before: Record<string, string>, after: Record<string, string>): ChangeSet;
+/** Changes since a labelled baseline. Available on any directory, with or without version control. */
+export declare class SnapshotChangeSource implements ChangeSource {
+    private readonly root;
+    private readonly label;
+    private readonly opts;
+    constructor(root: string, label: string, opts?: {
+        isIgnored?: (relPath: string) => boolean;
+        verify?: string;
+    });
+    /** Trusted iff a baseline exists AND (no verify requested OR its digest is anchored on the chain). */
+    private trustedBaseline;
+    changes(): ChangeSet | null;
+    describe(): ChangeSourceInfo;
+}
+/**
+ * Changes across a git range.
+ *
+ * THE TOP-LEVEL GUARD LIVES HERE, and only here. `gitChangedFiles` yields paths relative to the git
+ * top-level while `scan(root, root)` tags them relative to `root`; when those disagree the keys
+ * silently diverge and impact sets come back wrong. That hazard belongs to this adapter — it was
+ * previously imposed on every tool, including ones that never look at a diff, which is what made the
+ * whole harness demand a repository.
+ */
+export declare class GitChangeSource implements ChangeSource {
+    private readonly root;
+    private readonly base;
+    private readonly head;
+    private readonly topLevel?;
+    constructor(root: string, base: string, head: string);
+    changes(): ChangeSet | null;
+    describe(): ChangeSourceInfo;
+}
+export { EMPTY as EMPTY_CHANGE_SET };

package/dist/holmes/project/ignore.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A DOCUMENTED SUBSET of `.gitignore`, for the path where git cannot be asked.
+ *
+ * Why `.gitignore` and not a Holmes-specific ignore file: a project that carries two ignore files can
+ * have them disagree, and then no one can say which one is true. One file, interpreted by whoever is
+ * available — git when there is a repository, this matcher when there is not.
+ *
+ * WHAT MAKES THIS SAFE IS THE FAILURE DIRECTION. A construct outside the subset is collected in
+ * `unsupportedPatterns()` and its files are treated as NOT ignored. Including a file and saying so
+ * costs a reviewer some noise; excluding it silently drops real source out of the graph, out of
+ * clustering, and out of every answer built on them — the same failure the scanner's vendor-skip set
+ * was written to avoid.
+ *
+ * Supported: comments and blanks, leading-`/` anchoring, trailing-`/` directory-only, `*`, `?`, `**`,
+ * character classes (`[abc]`, `[a-z]`, `[!abc]`), and `!` negation with the last matching rule
+ * winning. Not supported: backslash escapes and nested per-directory `.gitignore` files — both
+ * declared through `unsupportedPatterns()` and `limitations()`.
+ *
+ * Character classes were added because a scan of a real Python target reported exactly one
+ * unsupported pattern, `*.py[cod]` — the most common idiom in a Python .gitignore. Leaving the most
+ * common construct in the "reported but not honoured" bucket was not defensible.
+ */
+export interface IgnoreMatcher {
+    /** True when a project-relative POSIX path is excluded by the supported rules. */
+    isIgnored(relPath: string): boolean;
+    /** Patterns this matcher could not interpret. Their files are treated as NOT ignored. */
+    unsupportedPatterns(): string[];
+    /** Format-level limits of this implementation, stated so a caller never has to infer them. */
+    limitations(): string[];
+}
+export declare function parseIgnore(content: string): IgnoreMatcher;
+/** Load the project-root `.gitignore`. A missing file ignores nothing. */
+export declare function loadIgnore(root: string): IgnoreMatcher;

package/dist/holmes/project/root.d.ts

@@ -0,0 +1,34 @@
+export declare function cleanSubprocessEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * Where a project begins, for a harness that must not require version control.
+ *
+ * The anchor is `.ax/` — the directory holding the spec chain, the ledgers and the derived state,
+ * i.e. Holmes-Kit's own single source of truth. That is the correct anchor even where git exists:
+ * the path keys every graph node is built from are relative to the project, and the project is
+ * defined by its governance directory, not by whether someone happened to run `git init`.
+ *
+ * WHAT THIS REPLACES. `assertRepoTopLevel` demanded that `root` equal `git rev-parse --show-toplevel`
+ * and threw otherwise — applied uniformly, including to tools that never look at a diff. Measured, that
+ * made `cpg_scan`, `issue_localize`, `rtm_check(root)`, `test_run` and `review_scope` all throw on a
+ * tree with no `.git`, while `reverse_scan` (which asks git only for a candidacy refinement) carried on
+ * and reported `isGit: false`.
+ *
+ * The hazard that guard addressed is REAL but narrow: `gitChangedFiles` yields paths relative to the
+ * git top-level while `scan(root, root)` tags them relative to `root`, so a disagreement silently
+ * produces wrong impact sets. That is a property of the GIT CHANGE SOURCE. This resolver therefore
+ * REPORTS the pair and enforces nothing; the git adapter refuses on disagreement, and a tool that
+ * merely walks the tree proceeds.
+ */
+export interface ProjectRoot {
+    /** Absolute, symlink-resolved project root. */
+    root: string;
+    /** How the root was decided: an `.ax` marker, or the caller's own directory. */
+    marker: '.ax' | 'given';
+    /** Present only inside a git working tree. Reported for the caller to judge; never enforced here. */
+    git?: {
+        topLevel: string;
+    };
+}
+/** The marker directory that makes a directory a Holmes-Kit project. */
+export declare const MARKER = ".ax";
+export declare function resolveProjectRoot(dir: string): ProjectRoot;

package/dist/holmes/reverse/anchor.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Write `@implements` anchors back into source files — the step that actually puts a brownfield tree
+ * inside the traceability graph.
+ *
+ * PLAN AND APPLY ARE SEPARATE. An anchor is an authorship claim, so the edits must be inspectable
+ * before anything is written, and applying them is opt-in: `applyAnchors` is dry-run by DEFAULT.
+ * Anchoring to a non-approved A-SPEC is refused here as well as by the PreToolUse gate — a
+ * reverse-engineered draft is a description of code, and description does not confer approval.
+ */
+export interface AnchorMapping {
+    /** Repo-root-relative POSIX path of the file to anchor. */
+    file: string;
+    /** Target A-SPEC id. Must be approved. */
+    aspec: string;
+}
+export interface AnchorEdit extends AnchorMapping {
+    /** The exact line to insert, including its trailing newline. */
+    insert: string;
+    /** 0-based line index the insert goes at (1 when the file opens with a shebang). */
+    atLine: number;
+}
+export interface RefusedAnchor extends AnchorMapping {
+    reason: string;
+}
+export interface AnchorPlan {
+    edits: AnchorEdit[];
+    refused: RefusedAnchor[];
+}
+/**
+ * Compute the anchor edits for a mapping, refusing anything that must not be written.
+ *
+ * `approvedAspecs` is the caller's list of APPROVED A-SPEC ids — passed in rather than read here so
+ * the function stays pure with respect to the spec store and can be tested without one.
+ */
+export declare function planAnchors(root: string, mapping: AnchorMapping[], approvedAspecs: string[]): AnchorPlan;
+export interface ApplyResult {
+    applied: number;
+    dryRun: boolean;
+    /** Edits that WOULD be applied — only meaningful on a dry run. */
+    would: number;
+    /** Files that could not be written, with the reason. */
+    failed: RefusedAnchor[];
+}
+/** Apply an anchor plan. DRY-RUN BY DEFAULT: writing requires an explicit `dryRun: false`. */
+export declare function applyAnchors(root: string, edits: AnchorEdit[], opts?: {
+    dryRun?: boolean;
+}): ApplyResult;

package/dist/holmes/reverse/cluster.d.ts

@@ -0,0 +1,45 @@
+import { ScannedFile } from '../cpg/cpg-scanner';
+/** A directory with fewer files than this is folded into its nearest ancestor before classification. */
+export declare const MIN_FILES = 3;
+/** Above this a cohesive cluster is flagged `oversized` — reported, never split (H-SPEC-126). */
+export declare const MAX_FILES = 25;
+/**
+ * Cohesion threshold: ANY resolved internal call makes a directory cohesive.
+ *
+ * Derived, not chosen. Re-measured from the graph's own `calls` edges across a Python target and this
+ * repository, independent directories measure 0.00 and every cohesive one at least 0.17 — the classes
+ * separate at exactly zero. Zero is safe as a cutoff precisely because edge resolution is
+ * precision-first: an ambiguous callee resolves to nothing, so a single internal edge is evidence
+ * rather than a guess. Exported and named so a target with an unusual layout can raise it.
+ */
+export declare const COHESION_MIN = 1;
+export type Cohesion = 'cohesive' | 'independent' | 'unmeasured';
+export interface Cluster {
+    /** Directory the cluster was derived from (POSIX, repo-root-relative). */
+    dir: string;
+    /** Member files, sorted. A `per-file` split cluster holds exactly one. */
+    files: string[];
+    /** Total symbols across the member files. */
+    symbols: number;
+    /** Resolved calls from one file in the directory to another, counted before any split. */
+    internalCalls: number;
+    /** internalCalls per file in the directory — the measured density behind the split decision. */
+    density: number;
+    cohesion: Cohesion;
+    split: 'whole' | 'per-file';
+    /** True when the cluster is rooted in a test directory: reported separately, never an A-SPEC candidate. */
+    isTest: boolean;
+    /**
+     * Existing test files this slice's code is covered by, attached by name evidence (see test-map).
+     * Populated by `reverseScan`; empty from `clusterFiles`, which sees only production files.
+     */
+    testFiles: string[];
+    /** A cohesive cluster larger than MAX_FILES: kept whole, but its blast radius is coarse. */
+    oversized: boolean;
+}
+export interface ClusterOptions {
+    minFiles?: number;
+    maxFiles?: number;
+    cohesionMin?: number;
+}
+export declare function clusterFiles(files: ScannedFile[], opts?: ClusterOptions): Cluster[];

package/dist/holmes/reverse/draft.d.ts

@@ -0,0 +1,33 @@
+import { Spec } from '../spec/spec-parser';
+import { Cluster } from './cluster';
+import { AnchorMapping } from './anchor';
+import { SliceEvidence } from './surface';
+/**
+ * Exported so the approval-blocker judge can recognise an untouched draft by the marker this file
+ * plants, rather than re-typing the literal. A copy would drift silently the first time this string
+ * changes — and a silent divergence is the very class of defect REQ-182 exists to close.
+ */
+export declare const INFERRED = "<!-- inferred: not recoverable from code \u2014 a human writes this -->";
+export interface DraftRefusal {
+    ok: false;
+    reason: string;
+}
+export interface DraftResult {
+    ok: true;
+    /** The emitted documents, in chain order: H-SPEC, A-SPEC, T-SPEC. */
+    specs: Spec[];
+    /** The anchor mapping these drafts imply — plan only; nothing is written by drafting. */
+    anchorPlan: AnchorMapping[];
+    /** Identity of the cluster these drafts came from, recorded in frontmatter so a re-run recognises them. */
+    clusterKey: string;
+}
+/** The identity of a cluster: its directory, or the file itself when the directory split per file. */
+export declare function clusterKeyOf(cluster: Cluster): string;
+/**
+ * The first id number above every number already in use, across all spec kinds.
+ *
+ * Kind-agnostic on purpose: the three drafted documents share one number (H-SPEC-N / A-SPEC-N /
+ * T-SPEC-N), so the base must be free for every kind at once. Deterministic given the same spec set.
+ */
+export declare function nextIdBase(existingIds: string[]): number;
+export declare function draftSpecs(cluster: Cluster, parentReqId: string | undefined, idBase: string | number, evidence?: SliceEvidence): DraftResult | DraftRefusal;

package/dist/holmes/reverse/dynamic-wiring.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Detect the wiring forms a syntactic scan cannot follow — DI decorators, dynamic `require`/`import`,
+ * string-key dispatch, `eval`-like execution, config-driven wiring.
+ *
+ * REPORTED, NEVER RESOLVED. An indicator says "there is a relationship here that static evidence
+ * cannot recover"; it never becomes an edge or a cluster membership. The correct outcome for such a
+ * file is that it stays visibly unresolved, not that it gets attached to a guessed slice.
+ *
+ * The pattern sets are LANGUAGE-SCOPED and only exist for languages that were calibrated. Applying
+ * one language's regexes to another put nearly half of one subject's files under two indicators
+ * during calibration — and an indicator firing on most of a codebase teaches the reader to ignore it,
+ * which is worse than not shipping it. Languages with no calibrated set report nothing, and
+ * `dynamicWiringSupported` makes that gap visible instead of letting a silent zero read as "clean".
+ */
+export type Indicator = 'dynamic-import' | 'di-decorator' | 'string-key-dispatch' | 'eval-like' | 'config-driven';
+/** True when this file's language has a calibrated indicator set. */
+export declare function dynamicWiringSupported(file: string): boolean;
+export declare function detectDynamicWiring(code: string, file: string): Indicator[];

package/dist/holmes/reverse/scan.d.ts

@@ -0,0 +1,103 @@
+import { ScannedFile } from '../cpg/cpg-scanner';
+import { Cluster } from './cluster';
+import { Indicator } from './dynamic-wiring';
+import { TestMapping } from './test-map';
+import { SurfaceSymbol } from './surface';
+/**
+ * Read-only inventory of a brownfield tree: what is there, how it partitions into A-SPEC-sized
+ * candidates, and — the part that decides whether any of this is trustworthy — what the scan could
+ * NOT resolve.
+ *
+ * WRITES NOTHING, and that is a design constraint rather than an incidental property. In particular
+ * the default scan does not persist an N7 cache into the target: a cache file is a write, and the one
+ * claim this tool makes is that inventorying a codebase leaves it byte-identical. A caller that wants
+ * incremental warmth injects its own cached scanner via `opts.scan`, choosing where that cache lives.
+ */
+export interface Candidacy {
+    /** Files that are reverse-engineering candidates. */
+    files: ScannedFile[];
+    /**
+     * Test files, which the scanner deliberately excludes from the production graph. Collected here
+     * because per-A-SPEC test evidence is read from anchors INSIDE them, so the reverse flow has to be
+     * able to propose those anchors — otherwise adoption starts with every test outside the graph.
+     */
+    testFiles: string[];
+    /** How many files the scanner ingested before the tracked-file filter. */
+    scanned: number;
+    /** How many scanned files were dropped as untracked/ignored. */
+    droppedUntracked: number;
+    /** False when the target is not a git repository — the filter did not apply and the report says so. */
+    isGit: boolean;
+    /**
+     * `.gitignore` patterns the non-git matcher could not interpret. Their files were KEPT: including a
+     * file and saying so is safe, dropping it silently is not.
+     */
+    ignoreUnsupportedPatterns: string[];
+}
+/**
+ * Only git-tracked files are candidates.
+ *
+ * Ignored code is by definition not part of the shipped system, and treating it as governable
+ * produces specs for scratch work, build output and local experiments. A non-git tree accepts
+ * everything and reports `isGit: false`, which is honest rather than silently wrong.
+ */
+export declare function candidates(root: string, scan: (root: string) => ScannedFile[]): Candidacy;
+export interface FlaggedFile {
+    file: string;
+    indicators: Indicator[];
+}
+export interface ReverseScanReport {
+    root: string;
+    isGit: boolean;
+    /** Files ingested by the scanner, before the tracked-file filter. */
+    scanned: number;
+    droppedUntracked: number;
+    /** Files that are reverse-engineering candidates. */
+    candidates: number;
+    anchored: number;
+    unanchored: number;
+    /** A-SPEC candidates. */
+    clusters: Cluster[];
+    /** Clusters rooted in a test directory — a T-SPEC's business, never an A-SPEC candidate. */
+    testClusters: Cluster[];
+    /**
+     * Cluster key → public-surface candidates, for `reverse_draft` to state as evidence.
+     *
+     * Deliberately NOT part of the `reverse_scan` tool response: that response enters context on every
+     * call, and the surface measures ~5KB per cluster on the calibration target. The handler strips it.
+     */
+    surfaceByCluster: Record<string, SurfaceSymbol[]>;
+    coverage: {
+        /** Candidate files placed in a production cluster by directory evidence. */
+        structurallyResolved: number;
+        /** Candidate files that landed in a test cluster instead. */
+        inTestClusters: number;
+        /**
+         * Files in clusters whose language has no call-edge extraction. Their boundary was NOT decided by
+         * measured cohesion, so a human must confirm it — see Cluster.cohesion === 'unmeasured'.
+         */
+        cohesionUnmeasured: number;
+        /** Existing test files attached to a slice by name evidence — the per-A-SPEC evidence link. */
+        testsMatched: number;
+        /** Test files that could not be attached: an explicit gap, never a guessed attachment. */
+        testsUnmatched: number;
+        /** Files carrying at least one dynamic-wiring indicator: relationships static evidence cannot follow. */
+        withDynamicIndicators: number;
+        indicators: Partial<Record<Indicator, number>>;
+        /** Extensions present in the tree for which no indicator set is calibrated — a zero here means "not looked for". */
+        uncalibratedIndicatorLanguages: string[];
+        /** Ignore patterns the non-git path could not interpret — their files were included. */
+        ignoreUnsupportedPatterns: string[];
+    };
+    /** The flagged files themselves, sorted, so a reviewer can check the indicators rather than trust the count. */
+    needsHumanConfirmation: FlaggedFile[];
+    /** Existing tests attached to slices, and the ones that could not be — see test-map. */
+    tests: TestMapping;
+}
+export interface ReverseScanOptions {
+    /** Scan strategy. Defaults to a NON-PERSISTING scan so the target tree is never written to. */
+    scan?: (root: string) => ScannedFile[];
+    /** Cap on the flagged-file list carried in the report. The counts above it stay complete. */
+    maxFlagged?: number;
+}
+export declare function reverseScan(root: string, opts?: ReverseScanOptions): ReverseScanReport;

package/dist/holmes/reverse/surface.d.ts

@@ -0,0 +1,91 @@
+import { ScannedFile } from '../cpg/cpg-scanner';
+import { CodeSymbol } from '../cpg/language-parser';
+/**
+ * The evidence a reverse-engineered draft may state as fact, and the rendering of it.
+ *
+ * The word throughout is SURFACE, never CONTRACT. A scanner can testify that a symbol is defined at
+ * the top level of a file; it cannot testify that the symbol is something this slice promises to
+ * anyone. Naming the output `contract` would let the distinction rot away in a later edit, and the
+ * whole point of A-SPEC-181 is that filling a section with evidence is not the same as deciding it.
+ *
+ * Pure: this module reads no files and knows nothing about the spec store, so every rule below is
+ * exercisable from a literal.
+ */
+export interface SurfaceSymbol {
+    /** repo-root-relative POSIX path, exactly as `ScannedFile.sourcePath` carries it. */
+    file: string;
+    name: string;
+    kind: CodeSymbol['kind'];
+}
+/** Everything one slice's draft is allowed to state as fact. */
+export interface SliceEvidence {
+    surface: SurfaceSymbol[];
+    /** Existing test files attached to this slice by name evidence (= `Cluster.testFiles`). */
+    testFiles: string[];
+    /** Test files in the whole repository that could not be attached to ANY slice. */
+    testsUnmatched: number;
+}
+/**
+ * Total characters the rendered symbol list may occupy.
+ *
+ * Chosen from measurement, not taste. On the calibration target the 15 clusters hold 164, 132, 68,
+ * 53, 11 and ten single-symbol surfaces; listing EVERY one whole costs 11,460 characters (~2.9K
+ * tokens) for the entire adoption of a 203-file repository. So the bound exists to stop a
+ * pathological monorepo cluster, NOT to trim ordinary ones: at 4,000 every cluster on the target
+ * fits whole except the largest, which loses ~15% and says so.
+ *
+ * A tighter bound was tried first (1,200) and dropped 119 of 164 names — 73% of the largest slice —
+ * to save ~2K tokens across a whole adoption. That trade sends the human back to the scan report,
+ * which is the toil this REQ exists to remove.
+ */
+export declare const SURFACE_BUDGET = 4000;
+/**
+ * Longest name that may be quoted. A longer one is dropped rather than truncated: a partially
+ * printed identifier cannot be searched for, so it is worse than an honest omission count.
+ */
+export declare const NAME_MAX = 80;
+/**
+ * The top-level, non-underscore symbols of the given files — the PUBLIC SURFACE CANDIDATES.
+ *
+ * Two mechanical filters, no natural-language judgement:
+ *
+ * 1. NESTED, decided by line range WITHIN THE SAME FILE: a symbol `s` is nested when some other
+ *    symbol `o` of that same file satisfies `o.startLine < s.startLine && o.endLine >= s.endLine`.
+ *    `>=` (not `>`) because a nested definition may end on the same line as its enclosing one.
+ *    `<` (not `<=`) on the start because two symbols reported at the same start line cannot be
+ *    ordered by containment — refusing to decide keeps both rather than deleting a real symbol.
+ *    The comparison is per-file: a wide range in one file must not swallow a narrow one in another.
+ * 2. PRIVATE, decided by a leading underscore. `build_briefing` keeps its inner underscores; only
+ *    the first character is consulted.
+ *
+ * Sorted by file then start line so the same scan always renders byte-identically.
+ */
+export declare function surfaceOf(files: ScannedFile[]): SurfaceSymbol[];
+/**
+ * The surface as a per-file list, bounded.
+ *
+ * Four rules, the same ones A-SPEC-183 arrived at for the gate's denial text:
+ * (1) a name is printed WHOLE or not at all; (2) if nothing fits, report a COUNT instead of a list;
+ * (3) the bound is on the TOTAL, not per item; (4) no item passes unconditionally — the first entry
+ * is budget-checked like every other, so one absurd path cannot blow the bound.
+ */
+export declare function renderSurface(surface: SurfaceSymbol[]): string;
+/**
+ * The tests already attached to this slice, and — always — how many the repository could not attach
+ * to any slice at all.
+ *
+ * The unmatched count is not decoration. Measured on the calibration target the matcher attaches 46
+ * of 86 test files (53%), and the 40 it refuses are mostly its own rule's limit, not unrelated
+ * tests. A list printed without that number reads as "these are the tests for this slice".
+ */
+export declare function renderTestPoints(ev: SliceEvidence): string;
+/**
+ * A completion criterion that is checkable as written, which is why this section — alone among the
+ * three A-SPEC-181 fills — does not keep a TODO and therefore does not block approval.
+ *
+ * Clause 3 is NEVER dropped when the slice has no attached test. Dropping it would leave 1 and 2
+ * standing alone and read as "done"; the absence of a regression control is this slice's largest
+ * risk and belongs in the completion criterion, not in silence. Measured on the calibration target:
+ * 11 of 15 clusters are in exactly that state.
+ */
+export declare function renderDoneWhen(files: string[], testFiles: string[]): string;

package/dist/holmes/reverse/test-map.d.ts

@@ -0,0 +1,91 @@
+import { Cluster } from './cluster';
+/**
+ * Attach a brownfield project's EXISTING tests to the slices they cover.
+ *
+ * Why this exists: per-A-SPEC test evidence (`scanTestAnchors` → `computeTestScope` →
+ * `writeTestEvidence`) is read from `@implements` anchors inside TEST files, but the scanner
+ * deliberately keeps test files out of the production graph — so reverse engineering clustered the
+ * production code and left every test unanchored, and the evidence link had to be wired by hand.
+ * Measured on a real pytest target, that was 76 files of manual work standing between adoption and
+ * any per-slice test evidence at all.
+ *
+ * The mapping is by NAME EVIDENCE ONLY, and unmatched is a first-class outcome. A test whose subject
+ * cannot be identified, or whose subject lives in two different slices, is REPORTED rather than
+ * attached: an anchor is an authorship claim, and attaching one on directory proximity would be the
+ * guessing this whole slice refuses to do everywhere else.
+ */
+/**
+ * Candidate subjects a test file's name could be naming, STRONGEST FIRST.
+ *
+ * The first element is the whole name with its test convention stripped. The rest drop leading
+ * `_`-separated segments one at a time, because a test name routinely carries a suite qualifier
+ * ahead of its subject — measured on a real Python target, 62 of 74 tests were
+ * `tests/golden/test_golden_<subject>.py`, where `golden_` names the suite. A fixed vocabulary of
+ * qualifiers ("golden", "unit", "integration", …) would be a guess about someone else's conventions;
+ * offering weaker candidates and demanding a UNIQUE production match lets the target's own file names
+ * decide which reading is right. An empty list means the name identifies no subject at all.
+ */
+export declare function subjectStems(testPath: string, qualifiers: ReadonlySet<string>): string[];
+/**
+ * Leading name segments that the corpus itself shows to be SUITE QUALIFIERS rather than subjects.
+ *
+ * A qualifier is a word many of a project's tests start with (`golden_`, `unit_`, `integration_`),
+ * which is a property of the corpus and therefore measurable — as opposed to a vocabulary guessed in
+ * advance, which would encode one project's conventions as everyone's. The thresholds keep a
+ * coincidence from qualifying: at least three files AND at least a tenth of the suite.
+ */
+export declare function qualifierSegments(testFiles: string[]): Set<string>;
+/**
+ * @implements A-SPEC-185
+ * How strong the name evidence was, strongest first.
+ *
+ * `exact` — the subject IS the production file's name.
+ * `prefix` — the production name STARTS with the whole subject, at a segment boundary. Nothing the
+ *   test said about its subject was discarded.
+ * `shortened` — one trailing segment of the subject was dropped to reach the production name. Part
+ *   of what the test said WAS discarded, which is why this is the weakest reading.
+ *
+ * Recorded on every match because the readings are not equally trustworthy: a reviewer should see
+ * which one carried an anchor, and a false anchor found later should be traceable to the rule that
+ * produced it.
+ */
+export type MatchStrength = 'exact' | 'prefix' | 'shortened';
+export interface TestMatch {
+    /** The test file, repo-root-relative. */
+    file: string;
+    /** Key of the cluster it covers. */
+    clusterKey: string;
+    /** The production file whose name it matched — the evidence for the mapping. */
+    subject: string;
+    /** Which reading of the name produced this match. */
+    via: MatchStrength;
+}
+/**
+ * How many trailing segments the `shortened` reading may drop.
+ *
+ * ONE, and the value is measured rather than chosen. At two, the calibration target gains four more
+ * matches and two of them are the false anchor this file already warns about above:
+ * `test_golden_tool_dispatch_e2e.py` lands on `src/core/tool.py`. The more segments a reading
+ * discards, the more generic the remainder becomes — and a generic word is the kind that happens to
+ * be unique by accident.
+ */
+export declare const MAX_TRAILING_DROP = 1;
+/**
+ * Segment separators recognised WHEN WEAKENING a subject — `_` for python-style names, `-` for
+ * JS/TS-style ones.
+ *
+ * Deliberately not shared with `subjectStems`/`qualifierSegments`: widening the split there would
+ * change which leading segments count as suite qualifiers, and that could move matches that already
+ * exist. The weakening steps only ever run where the exact reading found nothing, so they can be
+ * broader without disturbing anything.
+ */
+export declare const SEGMENT_SEPARATOR: RegExp;
+export interface UnmatchedTest {
+    file: string;
+    reason: string;
+}
+export interface TestMapping {
+    matched: TestMatch[];
+    unmatched: UnmatchedTest[];
+}
+export declare function mapTestsToClusters(testFiles: string[], clusters: Cluster[]): TestMapping;