any-doctor 0.0.7 → 0.0.9

package/CONTEXT.md

@@ -3,6 +3,14 @@
 Canonical vocabulary for any-doctor. Glossary only — no implementation.
 When a term here conflicts with language elsewhere, this file wins.
 
+Current product intent lives in [docs/vision.md](docs/vision.md). For work on
+persistent decisions, history, identity, or team convergence, read the
+[lifecycle design](docs/plans/finding-lifecycle/design.md); the first identity
+delivery (lifecycle M1, slices A1+A2) is planned in
+[analysis improvements](docs/plans/analysis-improvements.md). Their proposed records
+are not implemented interfaces; the glossary below describes current behavior
+unless a term is explicitly marked planned.
+
 ## Doctor program
 
 The artifact an LLM writes: a JavaScript module that inspects a target
@@ -57,6 +65,33 @@ deriving twice from one RunOutcome yields one Summary; rendering
 derivation. The facts a gate needs (`--fail-on` severity counts,
 baseline-diffable shapes) live here as data, not inside rendering.
 
+## Dashboard
+
+The interactive review surface over a RunOutcome: one module
+(src/dashboard.ts) that owns layout, the frame renderer, the TUI loop, and
+the per-finding read state — composing the Doctor tree as its view-model
+and the Task prompts it copies. Selection, expansion, keymap, and the
+clipboard notice live here; the tree's shape and the prompt copy do not.
+
+## Doctor tree
+
+The dashboard's view-model: DoctorGroup → checks → SiteFinding, computed
+once from the Summary's per-doctor check buckets (src/doctor-tree.ts —
+the tree joins and orders, it never re-groups) and ordered for triage —
+worst severity first, then finding count, then name. Every consumer (the
+list rows, the detail pane, the task prompts) flattens or reads the one
+tree without rebuilding it. A SiteFinding's readKey
+(`checkKey@file:line`) is the within-run identity the read state keys on.
+
+## Task prompt
+
+Text the dashboard copies to the clipboard as one unit of agent work: one
+finding (fixPrompt), every finding of one check (checkFixPrompt), or a
+doctor's whole batch (doctorFixPrompt) — pure functions of Doctor-tree
+types plus the verify command, no terminal required. The lifecycle plan
+(M2) reworks this family toward investigation-first framing and
+authorized decision paths.
+
 ## Gate
 
 A run's exit policy — one module (src/gate.ts), one law. Findings are
@@ -69,13 +104,15 @@ infrastructure failure is not a finding and must never paint a run
 green. Diff mode (`--base <ref>`) judges only what a change ADDED: the
 same cohort scans the merge base of the ref and HEAD (a stateless
 baseline — nothing committed, nothing stale), the two deduped finding
-sets compare through the verify gate's own rule-aware multiset, and the
+sets compare through the identity layer (movement-aware — a finding
+that moved with its code is Continuing; `compareFindings` remains the
+fixture gate's exact multiset, never the diff's), and the
 bar counts added findings only; a change is not blamed for the debt it
 was born into. A partial base never gates: any base-scan crash aborts
 the run loudly (exit 1, no report, no JSON), because a baseline
 missing findings would dress pre-existing debt up as "added" — and a
 crashed HEAD doctor skips the diff for the same reason: its findings
-are absent, and absence must never read as "resolved". Machine
+are absent, and absence must never read as "no longer detected". Machine
 output rides `--format json` — one schema-tagged object on stdout,
 diagnostics on stderr.
 
@@ -93,12 +130,21 @@ runs. There is no override in any mode.
 
 ## Finding
 
-One emitted finding: a location (file, line) plus optional per-finding
+One emitted finding: an observed condition, represented by a location (file, line, optional zero-based column) plus optional per-finding
 message or severity override. "Issue" and "instance" are retired
 synonyms — Finding is the term in code, copy, and prompts. The
 doctor-level truth (id, description, default severity, blind spots)
 lives in the program's meta, not in individual findings.
 
+A finding may establish a defect, flag a project convention, or identify a
+contextual review candidate. Its existence alone does not establish that a code
+change is appropriate. Current locations are not durable lifecycle identities,
+but a finding may carry an optional `evidence` range (`endLine`, exclusive
+`endColumn`) covering its whole expression: the host validates it against the
+scanned source and the identity layer digests the covered span, so edits on
+continuation lines still break identity. Findings without a range match on
+their flagged line alone — line-scoped, surfaced as such.
+
 ## Check
 
 One rule within a doctor program. A finding names its check via `rule`;
@@ -107,7 +153,7 @@ and, when the check uses the identity engine at full power, its
 declaration of that need (`needs`), which is what renders "narrowed"
 when the engine is absent; the doctor's meta supplies the defaults when
 a finding names no check. A check id is a short kebab-case noun phrase
-over [a-z0-9-], unique within its doctor, naming the defect
+over [a-z0-9-], unique within its doctor, naming the detected concern
 (fetch-calls-without-abortsignal, filter-table-scan). One doctor
 program, many checks.
 
@@ -167,9 +213,12 @@ scans doctors once carried privately (the audit truncation bugs lived in
 those approximations). The engine is optional (oxc-parser +
 eslint-scope behind the Engine seam's second adapter): checks declare
 the analysis they need on their CheckMeta (`needs` — vocabulary:
-"bindings", "spans"), narrow without it,
+"bindings", "spans", "calls"), narrow without it,
 and the report renders "narrowed" — a degraded run is visible, never
-silent. References answer by position, so analysis queries compose with
+silent. `ctx.analysis.calls(file)` provides immediate call use, receiver identity,
+inline callback registration, and linked call ranges. These are syntax facts;
+stored, passed, or returned is not a promise-settlement verdict. Parse/adapter
+errors fail the doctor run explicitly. References answer by position, so analysis queries compose with
 rule queries: shapes from one engine, identities from the other.
 
 ## Engine
@@ -197,7 +246,7 @@ count as the doctors scanned it (default extensions); findings naming
 files outside that count can push the raw value negative, so the result
 is floored into 0–100 — and floored, never rounded, so any finding costs
 at least one point. Findings duplicated across doctors at the same
-file:line are deduplicated before scoring — the first-sorted copy wins
+file:line:column are deduplicated before scoring — the first-sorted copy wins
 (groups sort by the first finding carrying an explicit severity
 override, else the doctor's declared default; equal-severity groups
 fall back to input order) and a hidden duplicate's severity does not
@@ -227,9 +276,10 @@ known input.
 ## Fixture
 
 One seed plus the findings expected from running a doctor program against
-it. Expected findings match exactly on (rule, file, line), duplicates
+it. Expected findings match on (rule, file, line, optional column), duplicates
 counted: a missing expected finding is a recall failure; an unexpected
-finding is a precision failure. The rule in an expectation is part of the
+finding is a precision failure within these labeled cases, not a population
+accuracy measurement. The rule in an expectation is part of the
 match — a wrong-check finding at the right line fails the gate. A fixture
 also declares its analysis mode (D20 Stage 2): "on" (default) pins the
 full-power path and skips with a named notice where the engine is not
@@ -248,8 +298,8 @@ workflow's second pass; a doctor ships only after surviving its attack.
 Running a doctor program against its fixtures and diffing the findings.
 The trust gate: a doctor program is not considered working until verify
 passes. The policies that compose the gate — the claim contract, the
-per-fixture diff, the shared innocent corpus, the duplicate-location
-probe, the shared sensitivity corpus — live in one module, the
+per-fixture diff, the shared innocent corpus, per-check location
+coverage, the shared sensitivity corpus — live in one module, the
 Certification harness (`src/certify.ts`), behind one interface:
 `certify(mod, fixtures) -> result rows`. The doctor loader calls it once;
 prevention tiers land there, not in loader choreography.
@@ -277,7 +327,8 @@ the consuming repo), user-global (`~/.any-doctor/doctors/`, available
 in every repo), or bundled (the first-party pack inside the package,
 read-only — a starting point, not a dependency). Repo-local wins slug
 collisions, then user-global, then bundled. Scanning a target repo
-never writes to any scope.
+currently does not persist state in any scope. Planned CLI-owned state is
+separate from doctor discovery and does not grant doctors write capabilities.
 
 ## Skill
 
@@ -287,3 +338,36 @@ marker; `generate` refreshes a copy it planted (the marker is the
 boundary) and never touches a copy without one. The generation prompt
 embeds the skill verbatim. Any Doctor equips agents with the skill;
 it never launches, deploys, or speaks for an agent.
+
+## Location coverage
+
+A certification result for one check's reporting unit. Occurrence-level
+warning/error checks need a passing, context-preserving fixture with two
+distinct locations of that check in one file. File/project checks need a
+positive witness. Unspecified legacy units and unavailable analysis are
+reported as not exercised, not counted as passing. Fixture expectations
+establish tested coverage, not general correctness or independence of labels.
+
+## Lifecycle vocabulary (planned, except where marked landed)
+
+These terms describe the accepted direction, not current fields on Finding or
+DoctorCtx. The [design](docs/plans/finding-lifecycle/design.md) owns their data
+and applicability rules.
+
+- **Finding identity** *(landed in the diff path, D30)*: continuity of one
+  occurrence across comparable scans, distinct from its current source
+  coordinates. Host-derived today — check key, file, normalized flagged-line
+  digest, indentation-relative column, and innermost enclosing function span —
+  computed per comparison from one post-scan read, never persisted.
+- **Observation:** evidence that a finding was detected in a particular scan.
+- **Decision:** a reasoned accepted/not-applicable disposition with local or project
+  scope; it changes review state, not the raw observation.
+- **Continuing** *(landed in the diff path)*: a head occurrence matched to a
+  compatible base occurrence by identity — movement is not addition. Matches
+  resting on content alone are flagged contextFallback; identical copies
+  matched by cardinality are flagged ambiguous.
+- **No longer detected** *(landed in the diff path)*: absence established by
+  compatible, completed coverage.
+- **Claimed fix:** a recorded explanation of remediation, separate from rescan evidence.
+- **Reassessment:** a decision requires review because identity or applicability is
+  changed, conflicting, or uncertain.

package/README.md

@@ -1,17 +1,20 @@
 # any-doctor
 
-> Your agent writes the analyzer. Fixtures prove it. CI reruns it forever.
+> Your agent writes the doctor. Inspect its findings. Remember what matters.
 
-Your LLM writes code fast and roughly. **Doctors** are small deterministic
-programs that catch what it keeps getting wrong — and any-doctor ships with
-five of them covering the disciplines LLMs fumble most.
+Any Doctor helps you and your agent find recurring problems in AI-written code
+beyond ordinary lint configurations. **Doctors** are small deterministic analysis
+programs that surface concrete concerns and codebase-specific conventions.
 
 When none of them covers the convention you keep explaining in code review,
-your agent writes a new doctor for it — against a typed `ctx` API, gated by
-fixtures, rerun forever in CI with zero inference. **A skill without a doctor
-is a suggestion.**
+your own agent writes a doctor for it against a typed `ctx` API, with positive
+examples and valid lookalikes. Run it after coding, inspect the evidence, and
+rescan after changes. Saved doctors run without model inference.
 
-Everything runs locally. No account, no API key, no telemetry, no network.
+Analysis runs locally without an account, API key, or telemetry. Package/tool
+installation can require downloads; the doctor runtime has no network access.
+Remembered decisions and finding history are [planned](docs/plans/finding-lifecycle/proposal.md),
+not available yet.
 
 [![npm version](https://img.shields.io/npm/v/any-doctor.svg)](https://www.npmjs.com/package/any-doctor)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](#)
@@ -45,11 +48,12 @@ Non-terminals and CI never see a prompt — output is stable and pipeable
 | **openrouter-doctor** | OpenRouter discipline: stream errors surfaced, keep-alives skipped, cancellations that stop billing | 5 |
 | **async-doctor** | Async and concurrency: dropped promise results, uncleared timers, fetch hygiene | 3 |
 
-Every check ships with fixtures proving both directions — it fires on the
-shapes it claims (recall) and stays silent on innocent lookalikes
-(precision). 144 fixtures across the pack, run by `verify` as an exact
-multiset on `rule:file:line`. slop-doctor's checks were born from 1,368
-Bugbot findings across 182 reviewed PRs — every check carries its evidence.
+Checks ship positive and innocent-lookalike fixtures. `verify` compares an
+exact multiset of rule/file/line and optional column, then runs shared innocent
+and sensitivity corpora. Convex checks also declare per-check location coverage;
+legacy undeclared coverage is reported as not exercised. Passing fixtures show
+agreement on those cases, not a general accuracy guarantee. See
+[the reliability protocol](docs/doctor-reliability.md).
 
 ## Write your own
 
@@ -64,7 +68,7 @@ writes two files:
 - `doctors/your-doctor.mjs` — the analyzer: `meta` (checks, blind spots,
   severity) + `doctor(ctx)`. One self-contained file; `ctx` is its entire
   world (files, structural search via ast-grep, binding analysis, findings).
-- `doctors/your-doctor.fixtures.mjs` — the proof: seed codebases plus the
+- `doctors/your-doctor.fixtures.mjs` — regression evidence: seed codebases plus the
   findings the doctor must produce, and the lookalikes it must ignore.
 
 Then the loop agents love:
@@ -76,11 +80,11 @@ npx any-doctor@latest verify doctors/your-doctor.mjs
 #   ✔ accepts an awaited result
 ```
 
-`missing` fails recall, `unexpected` fails precision, the exit code stays
-non-zero until every fixture passes — and the skill teaches the sharp edges
+`missing` and `unexpected` identify failures against the labeled fixture cases;
+the exit code stays non-zero until every fixture passes. The skill teaches the sharp edges
 (scope-analysis semantics, fixture-seed worlds, the adversarial
-counter-fixture pass) so the loop converges fast. No install needed;
-`verify` sandboxes everything.
+counter-fixture pass). Passing these cases does not measure general accuracy.
+No project install needed; `verify` sandboxes the doctor runs.
 
 ## CI: the gate
 
@@ -100,17 +104,22 @@ npx any-doctor@latest run --all --fail-on warning --base origin/main
 
 ## Why trust a finding
 
-- **Deterministic.** The same doctor on the same commit produces the same
-  report — no model runs at scan time, ever.
-- **Fixtures gate everything.** A doctor that hasn't passed `verify` doesn't
-  exist; discovery lists it as broken, not as a tool.
+- **Repeatable analysis.** Hold source contents, doctor implementation, engine
+  versions, configuration, and capabilities fixed when comparing runs. No model
+  runs at scan time.
+- **Executable evidence.** Run `verify` to test declared cases and shared
+  counterexamples. Discovery is not proof that a doctor passed verification;
+  independent real-code evaluation is still needed.
+- **Specific claims.** A finding can establish a defect, flag a project convention,
+  or identify a review candidate. Its evidence should support that interpretation;
+  a suggested change can still require judgment.
 - **Blind spots are data.** Every doctor declares what it cannot see, and
   the report renders those declarations beside the findings.
 - **Doctors are confined.** The runtime capability gate refuses to execute
   a doctor that imports, writes, spawns, or touches the network — a
   malicious doctor is refused before it runs, with no override.
-- **The score is the share of clean files**, per doctor and overall —
-  health and work are reported together, never conflated.
+- **The score summarizes files without reported findings**, per doctor and overall.
+  It is not a probability of correctness or proof that unexamined code is safe.
 
 ## Docs
 
@@ -118,14 +127,21 @@ npx any-doctor@latest run --all --fail-on warning --base origin/main
 |---|---|
 | [skill/any-doctor.skill.md](skill/any-doctor.skill.md) | The authoring contract — what your agent reads to write doctors |
 | [CONTEXT.md](CONTEXT.md) | Domain glossary — canonical terms |
-| [docs/decisions.md](docs/decisions.md) | Decision log (D1–D20). Read first; don't relitigate |
-| [docs/vision.md](docs/vision.md) | The product idea and lifecycle novelty |
+| [docs/vision.md](docs/vision.md) | Current goals and product direction |
+| [docs/features.md](docs/features.md) | Available features versus planned work |
+| [docs/plans/analysis-improvements.md](docs/plans/analysis-improvements.md) | Next slice: source evidence, identity, and reliable Git-base comparisons |
+| [docs/plans/finding-lifecycle/proposal.md](docs/plans/finding-lifecycle/proposal.md) | Planned decisions, history, and team workflows |
+| [docs/plans/finding-lifecycle/design.md](docs/plans/finding-lifecycle/design.md) | State ownership, SQLite, Git convergence, and open choices |
+| [docs/plans/finding-lifecycle/milestones.md](docs/plans/finding-lifecycle/milestones.md) | Implementation slices and acceptance evidence |
+| [docs/HANDOFF.md](docs/HANDOFF.md) | Current handoff and next bounded task |
+| [docs/decisions.md](docs/decisions.md) | Historical choices and explicit supersessions |
 | [docs/kill-test.md](docs/kill-test.md) + [docs/RESULTS.md](docs/RESULTS.md) | The validation experiment and its numbers |
 | [docs/REPAIR-LOG.md](docs/REPAIR-LOG.md) | Generation-bug categories — feeds the authoring skill |
 | [docs/example-catalog.md](docs/example-catalog.md) | Rule intents across the JS ecosystem |
 
 ## Status
 
-Pre-1.0 and moving fast — the decision log is the honest history. Next on
-the ladder: the registry (`any-doctor add <slug>`), adoption (`init`), and
-a growing pack. MIT.
+Pre-1.0. The next direction is reliable finding identity, remembered decisions,
+team sharing, and bounded local history. Scanning stays available through npx
+without mandatory initialization. See the [feature map](docs/features.md) for
+current availability. MIT.

package/bin/analysis-host.d.ts

@@ -1,5 +1,5 @@
-import { AnalysisFile, AnalysisSpans, Mode } from "./contract.js";
-import { analysisStatus, analyzeBindings, analyzeSpans } from "./analysis.js";
+import { AnalysisFile, AnalysisSpans, AnalysisCalls, Mode } from "./contract.js";
+import { analysisStatus, analyzeBindings, analyzeSpans, analyzeCalls } from "./analysis.js";
 type Analyzer = typeof analyzeBindings;
 type SpansAnalyzer = typeof analyzeSpans;
 type Status = typeof analysisStatus;
@@ -16,8 +16,10 @@ export type AnalysisResponse = {
     file: AnalysisFile;
 } | {
     file: AnalysisSpans;
+} | {
+    file: AnalysisCalls;
 } | {
     error: string;
 };
-export declare function handleAnalysisRequest(req: AnalysisRequestBody, mode: Mode, analyzer?: Analyzer, status?: Status, spansAnalyzer?: SpansAnalyzer): AnalysisResponse;
+export declare function handleAnalysisRequest(req: AnalysisRequestBody, mode: Mode, analyzer?: Analyzer, status?: Status, spansAnalyzer?: SpansAnalyzer, callsAnalyzer?: typeof analyzeCalls): AnalysisResponse;
 export {};

package/bin/analysis-host.js

@@ -1,11 +1,12 @@
 import * as fs from "fs";
 import * as path from "path";
-import { analysisStatus, analyzeBindings, analyzeSpans } from "./analysis.js";
-import { searchBase, withinBase } from "./search-host.js";
+import { searchBase, withinBase, withinDir } from "./contract.js";
+import { analysisStatus, analyzeBindings, analyzeSpans, analyzeCalls } from "./analysis.js";
 // One cache per host process. The host lives in the runner process, so
 // the lifetime is the any-doctor invocation; across a cohort's doctors
 // the same unchanged file answers from memory.
 const modelCache = new Map();
+const callsCache = new Map();
 const spansCache = new Map();
 // Test seam: the model cache is keyed by mtime+size for the process
 // lifetime; tests bust it between cases. Invisible to slop-doctor's
@@ -13,8 +14,9 @@ const spansCache = new Map();
 export function clearAnalysisCache() {
     modelCache.clear();
     spansCache.clear();
+    callsCache.clear();
 }
-export function handleAnalysisRequest(req, mode, analyzer = analyzeBindings, status = analysisStatus, spansAnalyzer = analyzeSpans) {
+export function handleAnalysisRequest(req, mode, analyzer = analyzeBindings, status = analysisStatus, spansAnalyzer = analyzeSpans, callsAnalyzer = analyzeCalls) {
     const base = searchBase(mode);
     const root = typeof req.root === "string" ? path.resolve(req.root) : "";
     if (base === "" || !withinBase(root, base)) {
@@ -24,20 +26,22 @@ export function handleAnalysisRequest(req, mode, analyzer = analyzeBindings, sta
         const s = status();
         return s.available ? { available: true } : { available: false, reason: s.reason };
     }
-    if (req.kind === "bindings" || req.kind === "spans") {
+    if (req.kind === "bindings" || req.kind === "spans" || req.kind === "calls") {
         if (typeof req.file !== "string" || req.file === "") {
             return { error: `ctx.analysis.${req.kind} needs a "file" path` };
         }
         const abs = path.resolve(root, req.file);
-        if (!withinBase(abs, root)) {
+        if (!withinDir(abs, root)) {
             return { error: `ctx.analysis failed: file is outside the search root: ${req.file}` };
         }
         if (req.kind === "bindings") {
             return cachedModel(abs, root, modelCache, analyzer, req.file);
         }
+        if (req.kind === "calls")
+            return cachedModel(abs, root, callsCache, callsAnalyzer, req.file);
         return cachedModel(abs, root, spansCache, spansAnalyzer, req.file);
     }
-    return { error: `unknown analysis kind ${JSON.stringify(req.kind)} — known kinds: available, bindings, spans` };
+    return { error: `unknown analysis kind ${JSON.stringify(req.kind)} — known kinds: available, bindings, spans, calls` };
 }
 // The shared per-file model lifecycle: stat (cache hit on mtime+size),
 // read, compute, cache. Bindings and spans are the same policy over two

package/bin/analysis.d.ts

@@ -1,4 +1,4 @@
-import { AnalysisFile, AnalysisSpans, BindingInfo, BindingRef, SpanInfo } from "./contract.js";
+import { AnalysisFile, AnalysisSpans, AnalysisCalls, BindingInfo, BindingRef, SpanInfo } from "./contract.js";
 export type { AnalysisFile, AnalysisSpans, BindingInfo, BindingRef, SpanInfo };
 export interface AnalysisStatus {
     available: true;
@@ -15,6 +15,13 @@ export type AnalysisResult = {
     ok: false;
     error: string;
 };
+export type CallsResult = {
+    ok: true;
+    file: AnalysisCalls;
+} | {
+    ok: false;
+    error: string;
+};
 export type SpansResult = {
     ok: true;
     file: AnalysisSpans;
@@ -24,3 +31,4 @@ export type SpansResult = {
 };
 export declare function analyzeSpans(file: string, source: string): SpansResult;
 export declare function analyzeBindings(file: string, source: string): AnalysisResult;
+export declare function analyzeCalls(file: string, source: string): CallsResult;