@fro.bot/systematic 3.35.2 → 3.36.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: connections-researcher
3
- description: "Reads the learnings of several allowed projects, one rule family at a time, and proposes contradictions between learnings and lessons one project recorded that a sibling still needs. Read-only. Use only through the ce:connect skill."
3
+ description: "Reads the learnings of several allowed projects, one rule family at a time, and proposes contradictions between learnings, lessons one project recorded that a sibling still needs, and learnings whose present-tense claim the code no longer supports. Read-only. Use only through the ce:connect skill."
4
4
  mode: subagent
5
5
  temperature: 0.1
6
6
  color: info
@@ -38,23 +38,30 @@ One family of rules, in these lines:
38
38
  - `rule ids`: the rules of this family. Work on these and no others.
39
39
  - `max candidates`: at most this many candidates.
40
40
 
41
- A rule entry gives `appliesWhen`, `guidance` and `prevention` text with the path and the hash of its file. Use those sections. You do not need the rest of the file unless an excerpt comes from it.
41
+ A rule entry gives `appliesWhen`, `guidance` and `prevention` text with the path and the hash of its file. Use those sections for the contradiction and transferable-lesson tests: you do not need the rest of the file unless an excerpt comes from it. The code-mismatch test checks the learning file itself, so you read that file whole (Method, step 5).
42
42
 
43
43
  ## Method
44
44
 
45
45
  Work in the fewest turns you can. Make independent searches and reads in one turn. You have at most 20 turns in total.
46
46
 
47
- 1. Find and read the entries for your rule ids, in one turn.
47
+ 1. Find and read the entries for your rule ids, in one turn. In the next turn, read the learning file of every rule, all in one turn.
48
48
  2. For each rule, say in a sentence what goes wrong when it is ignored (the failure shape). That is what you search for.
49
49
  3. Contradiction test. Search the other allowed projects' `docs/solutions` for guidance on the same contract in the same situation that says something incompatible. Two documents on one subject are usually compatible, and different contexts with different right answers are not a contradiction. A document that is only more detailed than another is not one either. Returning no contradiction is a valid result.
50
50
  4. Transferable-lesson test. A project other than the rule's own shows the same failure class in its code, workflows, config, plans or learnings, and records no rule for it. Search that project's tracked files for the failure shape and cite the lines. A project that could plausibly hit the problem someday is not enough.
51
- 5. For each candidate, look for counterevidence: a later or superseding document, a plan that decided the other way, or a learning that already records the rule under other words (search the target's `docs/solutions` for it). Report what you searched in `overlapCheck`. Drop a candidate that the counterevidence settles.
52
- 6. Take every fingerprint from the files index or the rules file. Search the files index for the path and use its `sha256` and `project root` as they are. Never compute, invent or guess a fingerprint or a path.
53
- 7. Copy every excerpt from a read of that file, character for character, 20 to 1500 characters. A target-evidence excerpt must lie inside the line span you cite and contain the symbol you name. Never paraphrase inside an excerpt.
51
+ 5. Code-mismatch test. The learning file that your rule names makes present-tense claims about how code, config or a tool behaves. Read the whole learning file before the rule counts as covered: the rule entry is not the file, and a claim you never read is a claim you never checked. Your `files` list names each learning you read, and the helper does not count a rule as covered when its learning is missing from `files`. Check the present-tense claims that matter against the code at their governing revision, within your turns and `max candidates`. Each claim is judged on its own. The governing revision is the checkout of the project the claim is about. For a claim about a dependency, it is the version the consumer pins, so judge the claim at that pin. A claim that was true at the pin is never `stale`, however far upstream has moved on. Read a lockfile as plain text only to learn which version to look at.
52
+ - `stale`: code at the governing revision contradicts the claim. Quote the contradicting lines.
53
+ - `unscoped`: the claim holds where the learning was written, the learning does not say in which context, and positive evidence shows the claim false in another supported context. A fixture that uses a different spelling of a value is not enough. The excerpt must show the claim failing there.
54
+ - A claim about a documented contract or interface (an SDK guarantee, an API's documented behaviour) is not `stale` merely because an implementation detail differs, such as a server's sort order today. Positive evidence must contradict the contract itself, and when it does not, send `investigate`. Evidence of how one implementation behaves is not evidence against the contract.
55
+ - A learning that deliberately describes past behaviour, such as a decision record of what was true when it was written, is never a candidate, whatever the code says now.
56
+ - Back every `stale` or `unscoped` candidate with positive evidence: a verbatim excerpt of code, config or a tool's own text that contradicts the claim. A search that found nothing, a missing path or a partial configuration is not evidence. A claim you cannot check, or one whose governing version you cannot determine, is not stale: send `investigate` with no evidence, or send nothing.
57
+ - For a `stale` claim about a dependency, show the consumer's pin: cite an excerpt of its `package.json` or of a workflow `uses:` line in `counterevidence`, or state the pin in `overlapCheck.note`, labelled unverified. Otherwise, the `nextStep` is `investigate`.
58
+ 6. For each candidate, look for counterevidence: a later or superseding document, a plan that decided the other way, or a learning that already records the rule under other words (search the target's `docs/solutions` for it). Report what you searched in `overlapCheck`. Drop a candidate that the counterevidence settles.
59
+ 7. Take every fingerprint from the files index or the rules file. Search the files index for the path and use its `sha256` and `project root` as they are. Never compute, invent or guess a fingerprint or a path.
60
+ 8. Copy every excerpt from a read of that file, character for character, 20 to 1500 characters. A target-evidence excerpt must lie inside the line span you cite and contain the symbol you name. A `code-mismatch` evidence excerpt must lie inside the line span you cite. Never paraphrase inside an excerpt.
54
61
 
55
62
  A search result that is truncated or very long is a reason to narrow the search, never a reason to stop. Search again with a more specific pattern, in one project or directory at a time, or use the files index to pick paths, and go on. Before you conclude that a rule has no candidate, read at least the most relevant file a search pointed to. Judge from what you read, not from search output alone.
56
63
 
57
- If you are short of turns, stop searching, answer at once, and set `"complete": false`. Do not guess to finish. That is the only case for `"complete": false`. When the searches are done and nothing holds up, set `"complete": true` with no candidates.
64
+ If you are short of turns, stop searching, answer at once, and set `"complete": false`. Do not guess to finish. That is the only case for `"complete": false`, and it includes running out of turns before you have read the learning file of every rule: never set `"complete": true` while the learning of any rule is unread. When the searches are done, every learning is read and nothing holds up, set `"complete": true` with no candidates.
58
65
 
59
66
  ## What you return
60
67
 
@@ -64,7 +71,7 @@ The types matter, because the helper rejects the whole answer on a wrong one:
64
71
 
65
72
  - `ruleIds`, `projects`, `files` and `searches` are lists of plain strings. Nothing in them is an object.
66
73
  - Each entry of `projects` is a project root exactly as written after `projects:` in your instructions, an absolute path. Never a project name.
67
- - Each entry of `files` is a path relative to its project root, as in the files index. Each entry of `searches` is one short string, such as the pattern you searched.
74
+ - Each entry of `files` is a path relative to its project root, as in the files index. When another allowed project has a learning at the same relative path, write the entry as its project root, a `/` and the path, so the helper can tell which you read. Each entry of `searches` is one short string, such as the pattern you searched. `files` holds at most 50 entries, so list the learnings first and other files after.
68
75
  - `complete` is `true` or `false`, never a string. `start` and `end` are whole numbers.
69
76
  - A candidate has exactly the fields shown below and no others. It has no `id`, `type`, `urgency` or `description`.
70
77
 
@@ -80,7 +87,8 @@ The types matter, because the helper rejects the whole answer on a wrong one:
80
87
  "complete": true,
81
88
  "candidates": [
82
89
  {
83
- "kind": "contradiction | transferable-lesson",
90
+ "kind": "contradiction | transferable-lesson | code-mismatch",
91
+ "reason": "<code-mismatch only: stale | unscoped; leave the field out for any other kind>",
84
92
  "ruleId": "<a rule id from your family that one source belongs to>",
85
93
  "target": "<main root of the project that should change>",
86
94
  "title": "<one line, at most 160 characters; aim for under about 120>",
@@ -89,7 +97,7 @@ The types matter, because the helper rejects the whole answer on a wrong one:
89
97
  "overlapCheck": { "queries": ["<what you searched in the target, at most 200 characters each>"], "result": "none-found | found", "note": "<optional one paragraph, at most 400 characters>" },
90
98
  "sources": [{ "project": "<root>", "path": "<learning path>", "fingerprint": "<sha256>", "excerpt": "<verbatim>" }],
91
99
  "targetEvidence": [{ "path": "<tracked path in the target>", "start": 1, "end": 1, "symbol": "<identifier in the span>", "fingerprint": "<sha256>", "excerpt": "<verbatim, inside the span, contains the symbol>" }],
92
- "counterevidence": [{ "project": "<root>", "path": "<path>", "fingerprint": "<sha256>", "excerpt": "<verbatim>" }]
100
+ "counterevidence": [{ "project": "<root>", "path": "<path>", "start": 1, "end": 1, "fingerprint": "<sha256>", "excerpt": "<verbatim>" }]
93
101
  }
94
102
  ]
95
103
  }
@@ -98,8 +106,9 @@ The types matter, because the helper rejects the whole answer on a wrong one:
98
106
  - `ruleIds` lists every rule id you examined, even when you found nothing. The helper checks it against the index, so a family that finds nothing still lists them all.
99
107
  - A `contradiction` has two or more `sources`, all learnings, one of them in the `target` project and at least one in another project (two learnings of the target alone are not a cross-project connection), and its `nextStep` is `refresh-learning` or `investigate`.
100
108
  - A `transferable-lesson` has `sources` outside the `target` project, at least one `targetEvidence` item, and its `nextStep` is `compound-learning` or `investigate`.
109
+ - A `code-mismatch` has exactly one `source`, a learning in the `target` project, and no `targetEvidence`. Its `reason` is `stale` or `unscoped`, and its `nextStep` is `refresh-learning` or `investigate`. A `refresh-learning` needs at least one `counterevidence` item. Its `counterevidence` is the positive evidence, from any allowed project including the target, and each item carries `start` and `end`, a line span that holds its excerpt. Leave `start` and `end` out of `counterevidence` for the other two kinds, and `reason` out of their candidates.
101
110
  - `sources` are learnings. `counterevidence` may be any tracked file.
102
111
  - Free text (`title`, `summary`, `note`, each query) is one paragraph within these caps: title 160 characters, summary 800, note 400, query 200. Put nothing in it that you copied from a file other than in an excerpt.
103
- - Send at most one candidate for each rule and target. When one rule shows several gaps in the same target, put them in that one candidate, each gap as its own `targetEvidence` entry, and keep the summary within its cap: the helper drops a second candidate for the same rule, sources and target as a duplicate, and the finding is lost.
104
- - Propose only the two kinds above. Send at most `max candidates`. An empty `candidates` list with `complete` true is the right answer when nothing holds up.
112
+ - For `contradiction` and `transferable-lesson`, send at most one candidate for each rule and target. When one rule shows several gaps in the same target, put them in that one candidate, each gap as its own `targetEvidence` entry, and keep the summary within its cap: the helper drops a second candidate for the same rule, sources and target as a duplicate, and the finding is lost. A `code-mismatch` is the exception: send a separate candidate for each claim and reason, each with its own evidence, because the claim and the reason make up its identity. The helper drops only a repeat of the same claim and reason.
113
+ - Propose only the three kinds above. Send at most `max candidates`. An empty `candidates` list with `complete` true is the right answer when nothing holds up.
105
114
  - Last check, before you answer: measure each title, summary and note you wrote. If one is over its cap, cut it, and drop detail that is already in the excerpts. Never answer with an over-length field: the helper drops the whole candidate for it, and the finding is lost.
package/dist/index.js CHANGED
@@ -1867,7 +1867,20 @@ function restorePart(store, sessionID, part) {
1867
1867
  const full = store.peek(sessionID, part.id);
1868
1868
  if (full === undefined)
1869
1869
  return;
1870
- part.result = { type: "content", value: [{ type: "text", text: full }] };
1870
+ part.result = restoredResult(part.result, full);
1871
+ }
1872
+ function restoredResult(result, full) {
1873
+ if (!isRecord(result))
1874
+ return result;
1875
+ if (result.type === "text") {
1876
+ return result.value === full ? result : { type: "text", value: full };
1877
+ }
1878
+ if (result.type !== "content" || !Array.isArray(result.value))
1879
+ return result;
1880
+ const [only, ...more] = result.value;
1881
+ if (more.length === 0 && isRecord(only) && only.type === "text" && only.text === full)
1882
+ return result;
1883
+ return { ...result, value: [{ type: "text", text: full }] };
1871
1884
  }
1872
1885
  function createToolDefinition(ctx, descriptor, store, guard) {
1873
1886
  return {
@@ -12,11 +12,20 @@
12
12
  *
13
13
  * A decision comes from one place: a checkbox line the renderer generated,
14
14
  * inside the single delimited section, outside any code fence, whose id is in
15
- * the manifest of the report that was read and whose candidate is still open.
15
+ * the manifest of the report that was read, whose candidate is still open and
16
+ * whose revision is the one the line was generated for.
16
17
  * The manifest of a report is stored under the hash its body carries, so a
17
18
  * report that was posted keeps its own manifest even when a later render
18
19
  * failed to post or posted something else.
19
20
  *
21
+ * Every line names the revision of its candidate as `:r<12 hex>`: a hash of
22
+ * the fingerprints a decision reviews, so it changes when the candidate's
23
+ * learning, target or evidence does, and the same content always has the same
24
+ * revision. A tick made against another revision is skipped as stale and never
25
+ * recorded, so it cannot settle a candidate nobody has decided. A line without
26
+ * one is from a report before revisions and is skipped as `unversioned`: the
27
+ * operator ticks the revision-tagged box of the current report instead.
28
+ *
20
29
  * Import rule: node builtins and the `connect-*` modules. The `ce:connect`
21
30
  * helper bundles this module, so it must never import zod, `config.ts` or
22
31
  * `config-schema.ts`.
@@ -33,6 +42,8 @@
33
42
  import { type LockBusyReason, type ProcessTable } from './connect-state.js';
34
43
  /** A report body is never longer than this many characters. */
35
44
  export declare const REPORT_MAX_CHARS = 60000;
45
+ /** The most candidate ids the section for rows with no verified details names; the rest are counted. */
46
+ export declare const MAX_UNVERIFIED_IDS = 20;
36
47
  /** The manifests kept: the newest reports a person can still be looking at. */
37
48
  export declare const MANIFESTS_KEPT = 14;
38
49
  export declare const REPORT_FILE = "report.md";
@@ -43,8 +54,12 @@ export declare const DECISIONS_END = "<!-- connect-decisions:end -->";
43
54
  export type DecisionStatus = 'promoted' | 'rejected';
44
55
  /** `<!-- connect-manifest:<hash> -->`: which stored manifest this body was rendered with. */
45
56
  export declare function manifestMarker(hash: string): string;
46
- /** One generated checkbox line. The marker carries the id; nothing else on the line is read. */
47
- export declare function decisionLine(id: string, status: DecisionStatus, ticked: boolean): string;
57
+ /**
58
+ * One generated checkbox line. The marker carries the id and the revision as
59
+ * `:r<12 hex>`; nothing else on the line is read. A line made without a
60
+ * revision is the one reports used before revisions.
61
+ */
62
+ export declare function decisionLine(id: string, status: DecisionStatus, ticked: boolean, revision?: string): string;
48
63
  export interface CiOptions {
49
64
  readonly processes?: ProcessTable;
50
65
  readonly now?: () => number;
@@ -65,6 +80,8 @@ export interface ParsedBox {
65
80
  readonly id: string;
66
81
  readonly status: DecisionStatus;
67
82
  readonly ticked: boolean;
83
+ /** The revision the line names; absent for a line from before revisions. */
84
+ readonly revision: string | undefined;
68
85
  }
69
86
  export interface ParsedBody {
70
87
  /** The hash in the manifest marker, when the body has exactly one. */
@@ -89,6 +106,56 @@ export type BodyRead = {
89
106
  };
90
107
  /** Read a report body from a file: one bounded regular file, never a symlink. */
91
108
  export declare function readReportBody(file: string): BodyRead;
109
+ interface PayloadSource {
110
+ readonly projectName: string;
111
+ readonly path: string;
112
+ readonly excerpt?: string;
113
+ }
114
+ /**
115
+ * A file a `code-mismatch` candidate cites as evidence: where it is and the
116
+ * checkout HEAD its project had when the run read it. The excerpt is not kept;
117
+ * `fetch:` brings it in.
118
+ */
119
+ interface PayloadEvidence {
120
+ readonly projectName: string;
121
+ /**
122
+ * The `owner/repo` the file belongs to, so the visibility rechecks can name
123
+ * a repository only this candidate cites. Absent when it could not be named.
124
+ */
125
+ readonly repo?: string;
126
+ readonly path: string;
127
+ readonly start?: number;
128
+ readonly end?: number;
129
+ readonly head?: string;
130
+ }
131
+ /** The text of one open candidate, kept bounded and display-safe. */
132
+ interface Payload {
133
+ readonly id: string;
134
+ readonly title: string;
135
+ readonly summary: string;
136
+ readonly kind: string;
137
+ readonly nextStep: string;
138
+ readonly targetName: string;
139
+ readonly repo?: string;
140
+ readonly sources: readonly PayloadSource[];
141
+ /** Why a `code-mismatch` learning is a candidate. Absent for every other kind. */
142
+ readonly reason?: string;
143
+ /** The evidence a `code-mismatch` candidate cites. Absent for every other kind. */
144
+ readonly evidence?: readonly PayloadEvidence[];
145
+ /** The UTC date the candidate was first listed. Absent until it is listed. */
146
+ readonly firstShown?: string;
147
+ /** The GitHub run and attempt whose artifact holds the candidate's evidence. */
148
+ readonly runId: string;
149
+ readonly attempt: string;
150
+ /**
151
+ * The revision this text describes: what the run that proposed it recorded.
152
+ * Absent in a store from before revisions, and then no box is rendered for
153
+ * it until a run stores text with a revision. A box is rendered only when it
154
+ * equals the entry's revision, so a proposal that was never committed can
155
+ * never sit above another revision's box.
156
+ */
157
+ readonly revision?: string;
158
+ }
92
159
  export type ReportOutcome = 'complete' | 'degraded' | 'busy' | 'failed' | 'no-final-line';
93
160
  export interface RenderRequest {
94
161
  /** The UTC date of the report, `YYYY-MM-DD`. */
@@ -105,9 +172,13 @@ export type RenderResult = {
105
172
  readonly bodyFile: string;
106
173
  /** The hash in the body's manifest marker. */
107
174
  readonly manifest: string;
175
+ /** Every open candidate, listed or not. */
108
176
  readonly open: number;
109
177
  readonly shown: number;
178
+ /** The listable candidates the size cap left out. */
110
179
  readonly hidden: number;
180
+ /** The open candidates with no bundle for their live revision, counted in one section. */
181
+ readonly unverified: number;
111
182
  /** Candidates listed for the first time on this date. */
112
183
  readonly fresh: number;
113
184
  /** The `<run>.<attempt>` fetch words of the listed candidates, in the order they appear. */
@@ -124,6 +195,48 @@ export type RenderResult = {
124
195
  readonly status: 'failed';
125
196
  readonly reason: 'invalid-request' | 'lock-failed' | 'ledger-unreadable' | 'no-invocation' | 'payload-store-unreadable' | 'payload-store-too-large' | 'manifest-store-unreadable' | 'write-failed';
126
197
  };
198
+ export interface Row {
199
+ readonly id: string;
200
+ readonly payload: Payload;
201
+ readonly isNew: boolean;
202
+ readonly block: string;
203
+ }
204
+ export interface BodyInput {
205
+ readonly outcome: ReportOutcome;
206
+ readonly facts: readonly string[];
207
+ readonly cacheRestored: boolean;
208
+ /** The report was rendered without the lock, so no payload or manifest was recorded. */
209
+ readonly stateUpdated: boolean;
210
+ /** The open entries that have a bundle for their live revision: the only rows with boxes. */
211
+ readonly rows: readonly Row[];
212
+ /** The ids of the other open entries, oldest first. */
213
+ readonly unverified: readonly string[];
214
+ }
215
+ export interface Assembled {
216
+ readonly body: string;
217
+ readonly ids: readonly string[];
218
+ readonly hash: string;
219
+ readonly fetches: readonly string[];
220
+ readonly fresh: number;
221
+ }
222
+ /**
223
+ * The report with its first `shown` rows and the section naming `named`
224
+ * unverified ids. Exported for the tests of the size budget.
225
+ */
226
+ export declare function assembleReport(input: BodyInput, shown: number, named: number): Assembled;
227
+ /**
228
+ * The most rows the cap leaves room for beside the section for the rows that
229
+ * cannot be settled, and how many of those ids the section names. The section
230
+ * is bounded and counts against the cap like everything else, so the whole
231
+ * body stays under `REPORT_MAX_CHARS`, which is what leaves the workflow room
232
+ * for the one line it may add. The full id list is tried first; when it would
233
+ * leave no room for the oldest row, the list is halved down to the count alone.
234
+ * Exported for the tests of the size budget.
235
+ */
236
+ export declare function fitReport(input: BodyInput): {
237
+ readonly shown: number;
238
+ readonly named: number;
239
+ };
127
240
  /**
128
241
  * Render the report body for the state in `root`: the open candidates of the
129
242
  * ledger, oldest first, as many as fit under the cap, each with its two
@@ -151,7 +264,11 @@ export interface AcceptedTick {
151
264
  readonly id: string;
152
265
  readonly status: DecisionStatus;
153
266
  }
154
- export type SkipReason = 'conflict' | 'not-in-manifest' | 'not-open' | 'already-recorded';
267
+ export type SkipReason = 'conflict' | 'not-in-manifest' | 'not-open' | 'already-recorded'
268
+ /** The tick was made against another revision of the candidate than the ledger holds. */
269
+ | 'stale'
270
+ /** The tick is on a box with no revision, from a report before revisions: tick the revision-tagged box on the current report. */
271
+ | 'unversioned';
155
272
  export interface SkippedTick {
156
273
  readonly id: string;
157
274
  readonly status?: DecisionStatus;
@@ -181,9 +298,14 @@ export type TickResult = {
181
298
  /**
182
299
  * Record the ticks of a report body. A tick counts when its box is a generated
183
300
  * line in the section of the body, its id is in the manifest the body names,
184
- * and the candidate is open; a decision already recorded with the same reason
185
- * is left as it is, so a second pass changes nothing. Each decision is made
186
- * only if the candidate is still open under the lock, so one recorded since
187
- * the ledger was read is skipped as `not-open`, never overwritten.
301
+ * and the candidate is open at the revision the line names; a tick for any
302
+ * other revision is skipped as `stale`, and a line from before revisions as
303
+ * `unversioned`. A decision already recorded with
304
+ * the same reason is left as it is, so a second pass changes nothing. Each
305
+ * decision is made only if the candidate is still open at that revision under
306
+ * the lock, so one recorded since the ledger was read is skipped as
307
+ * `not-open`, and a candidate whose content changed since is skipped as
308
+ * `stale`, never overwritten.
188
309
  */
189
310
  export declare function applyTicks(root: string, request: TickRequest, options?: TickOptions): TickResult;
311
+ export {};
@@ -118,6 +118,11 @@ export declare function parseBatch(text: string, runId: string): BatchParse;
118
118
  export interface Coverage {
119
119
  /** Indexed rules that no complete batch reported. */
120
120
  readonly uncoveredRuleIds: readonly string[];
121
+ /**
122
+ * Rules a complete batch named but none listed the learning of among its
123
+ * files. They are also in `uncoveredRuleIds`; this says why.
124
+ */
125
+ readonly learningUnreadRuleIds: readonly string[];
121
126
  /** Allowed projects that no batch reported reading. */
122
127
  readonly untouchedProjects: readonly string[];
123
128
  /** Families that stopped before covering their rules. */
@@ -127,12 +132,30 @@ export interface CoverageInput {
127
132
  readonly ruleIds: readonly string[];
128
133
  readonly projects: readonly string[];
129
134
  readonly batches: readonly Batch[];
135
+ /**
136
+ * The learning path of each rule, relative to its project. A batch covers a
137
+ * rule only when it lists that path among its files, so a rule whose entry
138
+ * alone was read is not covered. A rule with no path here owes no read.
139
+ */
140
+ readonly learningPaths?: ReadonlyMap<string, string>;
141
+ /**
142
+ * The root of the project each rule belongs to. Two projects can hold a
143
+ * learning at one relative path, so with a root a batch's read is the path
144
+ * under that root (`<root>/<path>`), or the bare path when no other project's
145
+ * learning in the run (every rule in `learningPaths`, named by the batch or
146
+ * not) has that path. A rule with no root here is matched on the bare path
147
+ * alone.
148
+ */
149
+ readonly learningProjects?: ReadonlyMap<string, string>;
130
150
  }
131
151
  /**
132
152
  * Whether the batches cover what the index issued. A model that is told to
133
153
  * report nothing still has to name every rule id in a complete batch and every
134
- * project it read, so silence cannot pass for a clean scan. A run with no
135
- * rules has nothing to cover.
154
+ * project it read, so silence cannot pass for a clean scan. A complete batch
155
+ * that names a rule without listing its learning among its files has not read
156
+ * what the code-mismatch test checks, so the rule is held back. The list is
157
+ * the family's own report: it catches a learning that was skipped, not one
158
+ * that was listed and never opened. A run with no rules has nothing to cover.
136
159
  */
137
160
  export declare function checkCoverage(input: CoverageInput): Coverage;
138
161
  export interface OfferInput {
@@ -187,10 +210,14 @@ export declare function sweepBefore(offer: Pick<Offer, 'total' | 'coveredBefore'
187
210
  export declare function sweepProgress(offer: Pick<Offer, 'offered' | 'fresh' | 'total' | 'coveredBefore' | 'sliceSize'>, coveredRuleIds: readonly string[]): SweepProgress;
188
211
  /** The one-line progress report of the digest header and the publish summary. */
189
212
  export declare function renderSweepLine(progress: SweepProgress): string;
190
- export declare const CANDIDATE_KINDS: readonly ['contradiction', 'transferable-lesson'];
213
+ export declare const CANDIDATE_KINDS: readonly ['contradiction', 'transferable-lesson', 'code-mismatch'];
191
214
  export type CandidateKind = (typeof CANDIDATE_KINDS)[number];
192
215
  export declare const NEXT_STEPS: readonly ['refresh-learning', 'compound-learning', 'investigate'];
193
216
  export type NextStep = (typeof NEXT_STEPS)[number];
217
+ /** Why a learning's claim no longer matches the code. */
218
+ export declare const MISMATCH_REASONS: readonly ['stale', 'unscoped'];
219
+ export type MismatchReason = (typeof MISMATCH_REASONS)[number];
220
+ export declare function isMismatchReason(value: unknown): value is MismatchReason;
194
221
  /** Limits on a candidate's fields. */
195
222
  export declare const CANDIDATE_LIMITS: Readonly<{
196
223
  title: 160;
@@ -231,6 +258,9 @@ export interface ValidSource {
231
258
  readonly excerpt: string;
232
259
  /** How a learning cites this text: `<project>:<path>@<fingerprint>`. */
233
260
  readonly cite: string;
261
+ /** The line span the researcher named. Only `code-mismatch` evidence carries one. */
262
+ readonly start?: number;
263
+ readonly end?: number;
234
264
  }
235
265
  export interface ValidTargetEvidence {
236
266
  readonly path: string;
@@ -254,6 +284,8 @@ export interface ValidCandidate {
254
284
  readonly title: string;
255
285
  readonly summary: string;
256
286
  readonly nextStep: NextStep;
287
+ /** Why a `code-mismatch` learning is a candidate. Absent for every other kind. */
288
+ readonly reason?: MismatchReason;
257
289
  readonly overlapCheck: OverlapCheck;
258
290
  readonly sources: readonly ValidSource[];
259
291
  readonly targetEvidence: readonly ValidTargetEvidence[];
@@ -280,6 +312,8 @@ export declare function pathProblem(rel: unknown): DropReason | undefined;
280
312
  * reason, or `unresolved` when a cited file vanished after the run began.
281
313
  */
282
314
  export declare function checkCandidate(raw: unknown, ctx: ValidationContext): CandidateCheck;
315
+ /** A fingerprint of a claim: the learning's verbatim source excerpt. */
316
+ export declare function claimFingerprint(excerpt: string): string;
283
317
  /**
284
318
  * The record the ledger identifies a candidate by. A source's role carries the
285
319
  * project key, so the same relative path in two projects stays two sources.
@@ -301,13 +335,28 @@ export declare function findRenamedEntries(ledger: Ledger, record: CandidateReco
301
335
  export declare function findRecorded(candidate: ValidCandidate, index: readonly ProvenanceIndexEntry[]): {
302
336
  readonly pointer: string;
303
337
  } | undefined;
304
- export type Standing = 'new' | 'sources changed' | 'target changed';
338
+ export type Standing = 'new' | 'sources changed' | 'target changed' | 'evidence changed';
305
339
  export interface DigestCandidate {
306
340
  readonly id: string;
307
341
  readonly standing: Standing;
308
342
  readonly refreshPointer?: string;
309
343
  readonly possibleMatches: readonly string[];
310
344
  readonly candidate: ValidCandidate;
345
+ /**
346
+ * The revision the ledger gives the candidate once the run is written: 12 hex
347
+ * characters of a hash of the fingerprints a decision reviews. A decision
348
+ * sends it back, so one made from a digest of other evidence is refused. Left
349
+ * out when the digest has none to show.
350
+ */
351
+ readonly revision?: string;
352
+ /**
353
+ * The checkout HEAD each `counterevidence` item was recorded at, in the same
354
+ * order. An import sets it, because it cannot find an item's HEAD by the item's
355
+ * local root: two recorded checkouts can map to one local root. An entry is
356
+ * undefined when the recorded checkout had no HEAD. Left out, an item's HEAD
357
+ * is looked up by its project root.
358
+ */
359
+ readonly evidenceHeads?: ReadonlyArray<string | undefined>;
311
360
  }
312
361
  export interface RecordedConnection {
313
362
  readonly pointer: string;
@@ -332,6 +381,10 @@ export interface DigestProject {
332
381
  readonly citationsUnsupported: boolean;
333
382
  /** A bound stopped the inventory. */
334
383
  readonly truncated: boolean;
384
+ /** The commit the checkout's HEAD named when the run began, when it could be read. */
385
+ readonly commit?: string;
386
+ /** The project holds no learning, so it was read only as evidence. */
387
+ readonly evidenceOnly?: boolean;
335
388
  }
336
389
  export interface DigestModel {
337
390
  readonly runId: string;
@@ -394,7 +447,7 @@ export declare function nameDropped(family: string, raw: unknown, reason: string
394
447
  /** Render untrusted prose as a block quote, so it cannot become a heading or a list. */
395
448
  export declare function quote(text: string): string;
396
449
  export declare function inline(text: string): string;
397
- export declare function renderCandidate(item: DigestCandidate, index: number): string[];
450
+ export declare function renderCandidate(item: DigestCandidate, index: number, heads?: ReadonlyMap<string, string>): string[];
398
451
  /**
399
452
  * Render the digest. All free text in it came from documents or from the
400
453
  * researcher, so it appears only as block quotes and fenced excerpts with
@@ -408,8 +461,10 @@ export declare function isPasteablePath(file: string): boolean;
408
461
  * The next step for one candidate, built from values the helper made and never
409
462
  * from candidate text. A lesson is promoted by `ce:compound` from its tokens. A
410
463
  * contradiction is promoted by `ce:compound-refresh` with the exact path of the
411
- * target's own learning, which `ce:compound` refuses. A candidate to
412
- * investigate has nothing to promote yet.
464
+ * target's own learning, which `ce:compound` refuses. A code-mismatch
465
+ * candidate is promoted the same way, with the evidence listed beside the
466
+ * command for the person to recheck; the list names only values the helper
467
+ * verified. A candidate to investigate has nothing to promote yet.
413
468
  */
414
469
  export declare function handoffLine(item: DigestModel['candidates'][number], runRecordPath: string, pasteable: boolean): string;
415
470
  /**
@@ -88,6 +88,8 @@ export interface ProjectReport {
88
88
  export type RefusalReason = 'candidate-malformed' | 'duplicate-candidate' | 'candidate-id-mismatch' | 'project-not-in-record' | MappingRefusal | 'project-unreadable' | 'path-rejected' | 'rule-id-mismatch' | 'file-not-tracked' | 'file-symlink' | 'file-changed' | 'file-vanished' | 'check-failed';
89
89
  /** The fixed text for each refusal. */
90
90
  export declare const REFUSAL_TEXT: Readonly<Record<RefusalReason, string>>;
91
+ /** What to do about an evidence project of a code-mismatch candidate that has no allowed checkout. */
92
+ export declare function evidenceRemedy(repo: string | undefined): string;
91
93
  export interface ImportRefusal {
92
94
  /** The recorded id, when it is well formed. */
93
95
  readonly id: string | null;
@@ -101,11 +103,19 @@ export interface ImportRefusal {
101
103
  readonly file?: string;
102
104
  readonly keys?: readonly string[];
103
105
  readonly repo?: string;
106
+ /** One line on how to get the candidate imported, when the refusal has a known fix. */
107
+ readonly remedy?: string;
104
108
  }
105
109
  export interface ImportAccepted {
106
110
  readonly recordedId: string;
107
111
  /** The candidate with local roots, checked against local files. */
108
112
  readonly candidate: ValidCandidate;
113
+ /**
114
+ * The checkout HEAD each `counterevidence` item was recorded at, by the root
115
+ * the run recorded it under. A local root cannot key it: two recorded
116
+ * checkouts can map to one local root.
117
+ */
118
+ readonly evidenceHeads: ReadonlyArray<string | undefined>;
109
119
  readonly record: CandidateRecord;
110
120
  /** The id computed from local roots. */
111
121
  readonly id: string;