@fro.bot/systematic 3.35.3 → 3.37.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.
package/HARNESSES.md CHANGED
@@ -117,7 +117,7 @@ The `ce:connect` skill dispatches `connections-researcher`, an agent that must n
117
117
 
118
118
  What the evidence does not show: a scripted model makes the calls, so these proofs show enforcement plumbing, not live model choice. Read tools are not path-scoped on any host and session MCP tools are not denied; the guide documents both as limits. The v1 floor (1.18.29) has no row and is not run against this proof.
119
119
 
120
- The scheduled workflow is a separate surface: it runs the skill headless on a CI runner and posts a report issue. Live runs of it, including the report author, the in-place edit on a second same-day run, a hand cancel and an agent-step timeout, are recorded in [CN-6]. That entry also lists what was not observed live.
120
+ The scheduled workflow is a separate surface: it runs the skill headless on a CI runner and posts a report issue. Live runs of it, including the report author, the in-place edit on a second same-day run, a hand cancel and an agent-step timeout, are recorded in [CN-6]. That entry also lists what was not observed live. Calling the workflow from another repository, and the named `fetch:` that follows from it, rest on the probe runs in [CN-7], which also lists what was not observed.
121
121
 
122
122
  ## Worktree placement rule — bootstrap paths
123
123
 
@@ -308,3 +308,4 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
308
308
  - **CN-4** — Pi 1.5.0: `tests/unit/pi-delegate-session.test.ts` › "the shipped researcher reaches createAgentSession with read, grep and find and none of bash, write, edit or systematic_delegate" (the `observedBy` for this row; the real session builder runs against a fake runtime and the test asserts the `tools` that reach `createAgentSession`, not the mock); `tests/integration/pi.test.ts` › "a family completes inside the delegate turn cap with read, search and find tools only, and its batch validates" and "a child that never answers stops at the turn cap and the family is degraded, not empty" (the real Pi runtime, run in the v2 host-contract profile). Scope limit: the delegate is capped at 20 turns, and a scripted model drives the integration tests.
309
309
  - **CN-5** — Manual evidence, not a CI check. Recorded 2026-11-08 with Claude Code 2.1.319 (`claude --version` prints `2.1.319 (Claude Code)`), run by hand with the plugin bundle built from the rebased branch head and a live model. Verdict PASS. Run A dispatched `systematic:connections-researcher` through the `Agent` tool: the subagent reported its tools as Read, Grep and Glob, read a planted file and returned its marker, skipped Bash, Write, Edit and WebFetch as unavailable, and never called any of them (the checker found no call to Bash, Write, Edit, WebFetch, WebSearch or NotebookEdit). Run B started a session with `claude --agent systematic:connections-researcher`: the session's init message listed Read, Grep and Glob as its tools, none of Bash, Write, Edit, WebFetch, WebSearch or NotebookEdit, and no MCP tools; the read worked and its marker reached the answer. The `HOST_SUPPORT_TABLE` row names this entry as its `observedBy`. Limits: one live model on one Claude Code version; in run A the denial is the subagent's own report, because it never called the tools, and the host's own statement comes from run B's session tool list; the read tools are not path-scoped; whether a dispatched subagent can reach its parent session's MCP tools was not tested. `tests/unit/connect-host-isolation.test.ts` › "claude plugin validate accepts the definition and rejects one that does not parse" remains a parse check only, because an agent whose frontmatter fails to parse loads without its limits. Upstream issue reports 58645 and 94202 (cited from the research behind this feature, not re-checked) describe `disallowedTools` not being enforced for plugin and subagent Bash, so the agent leads with the positive `tools` allowlist.
310
310
  - **CN-6** — Manual evidence from live runs of `.github/workflows/connect.yaml`, not a CI check. Pins: `fro-bot/agent` v0.140.2 at `1ffb6495501f12801f770fa0c0563d16450416e7`, which runs OpenCode v2 2.2.6, and Systematic 3.33.0. Run [43362146039](https://github.com/marcusrbrown/systematic/actions/runs/43362146039) (first dispatch) ended `Connect complete` and posted report issue #1389, authored by `github-actions[bot]`. The ledger cache was empty (a reset). The agent step had no model input, so the parent ran on the action's default model; the step now passes the Fro Bot model. Run [43365759373](https://github.com/marcusrbrown/systematic/actions/runs/43365759373) (second dispatch, the same UTC date): the action log shows `hasModelOverride: true`, and the run ended `Connect complete`. `prepare` logged `Ticks from report #1389: accepted 2, skipped 0, unresolved 0`, and the ledger cache restored (sweep 96 of 435). The `render` visibility recheck passed under `permissions: {}` with the job token. `post` edited #1389 in place and opened no second issue, and the two rejected candidates left the report. Run [43368318366](https://github.com/marcusrbrown/systematic/actions/runs/43368318366) was cancelled by hand about 2.5 minutes into the agent step: the steps after the agent were skipped, `render` and `post` were cancelled, nothing was posted, and the cache and the report were untouched. That is why the agent step has its own timeout below the job's: a cancelled job skips every step after the agent, while a timed-out step lets the record be read, handed on and posted. Run [43475406631](https://github.com/marcusrbrown/systematic/actions/runs/43475406631) (a dispatch with `FRO_BOT_CONNECT_STEP_TIMEOUT` set to 2) ran that path live: the log shows `The action 'Run ce:connect' has timed out after 2 minutes.`, the next step then read the record (`ce:connect ended: no-final-line (agent step: failure).`), `render` logged `Rendered 0 of 0 open candidates, 0 new; outcome no-final-line.`, `post` ran its `Write report` step, and the final `Settle result` step failed red, so the workflow ended `failure`. Not observed live: a busy run, which cannot happen in CI by construction (the lock is never cached or handed off, each run gets a fresh runner, and the concurrency group serializes runs). The workflow tests cover the timeout path against stubbed `gh`, `git` and `npm`.
311
+ - **CN-7** — Manual evidence from live probe runs of a reusable workflow called from a local wrapper and from a wrapper in another owner, not a CI check. Recorded 2026-11-20. Pins: the probe callee was a temporary commit based on Systematic `30b57460` (a first probe commit `3c00cc70`, then a cache-path fix `585df268`, both on a probe branch since deleted); the caller in another owner was `fro-bot/agent` (a probe branch based on `e70df737`, since deleted) calling it by full 40-hex SHA; action pins copied from `connect.yaml` (`actions/checkout` v7.0.1, `actions/cache` v6.1.0, `actions/upload-artifact` v7.0.2). The probe ran no agent, used no provider secret (a literal stand-in secret was passed) and created no issue, pull request, release or tag. **Observed.** (1) Self-checkout: on the local call, [run 44700906722](https://github.com/marcusrbrown/systematic/actions/runs/44700906722), and on the cross-owner call, [run 44701027408](https://github.com/fro-bot/agent/actions/runs/44701027408), `job.workflow_repository`, `job.workflow_sha` and `job.workflow_file_path` name the callee, while `github.repository`, `github.ref` and `github.event.repository.default_branch` name the caller and `github.event_name` is the caller's event, never `workflow_call`. `job.workflow_ref` differs by call type (a branch ref on the local call, the 40-hex SHA on the cross-owner one), so the SHA is the field to read. A sparse checkout of `/.github/actions/` at `job.workflow_sha` (cone mode off, no persisted credential) succeeded on both with the caller's default job token, even for a public repository in another owner, and the action file was present (runs [44701974289](https://github.com/marcusrbrown/systematic/actions/runs/44701974289) and [44702043679](https://github.com/fro-bot/agent/actions/runs/44702043679)). (2) `referenced_workflows` is present on `/runs/{id}`, `/attempts/1` and `/attempts/2` for both call types and identical on both attempts after a failed-jobs rerun. It is a list; each entry has a `path` of `owner/repo/.github/workflows/x.yaml@<sha>` and a 40-hex `sha`, and the `ref` key appears only on the local call. The run's own `path` is the caller's wrapper. (3) Compare direction: `compare/<default branch>...<sha>` answers `ahead` for a commit on an unmerged branch, `behind` for one in the history of `main`, `identical` for its tip, and a 404 for an unknown or malformed SHA, the same shape as no access. An unauthenticated request to the public repository answered; a job-scoped token was not tried. (4) The cache is saved in the caller's repository, scoped to its ref, and a second run restored an earlier entry by prefix once save and restore used the same `path` (the cache version includes it); `cache-hit` was `false` on a prefix match and `cache-matched-key` showed the hit. `concurrency: { cancel-in-progress: false, queue: max }` is accepted in a called workflow: runs queued in push order, two runs were pending at once, cancelling the newest pending run left the older one intact (runs [44701421105](https://github.com/fro-bot/agent/actions/runs/44701421105), [44701505528](https://github.com/fro-bot/agent/actions/runs/44701505528), [44701582882](https://github.com/fro-bot/agent/actions/runs/44701582882) and [44701627675](https://github.com/fro-bot/agent/actions/runs/44701627675)), and a group of the same name in two owners did not collide. (5) `vars` resolve against the caller: Systematic's variable was empty in the cross-owner call, and a secret the caller passed by name reached the callee in both calls. (6) A failed-jobs rerun reran only the failed job, kept the callee SHA, and left only the attempt-1 artifacts, so a later job must not rebuild an artifact name from `github.run_attempt`. (7) The job token's logged grant on a callee job with `contents: read` under a caller grant of `contents: read` was `Contents: read` and `Metadata: read`, and a top-level `permissions: {}` in the callee widened nothing. (8) A caller in another organization called a public, SHA-pinned workflow in `marcusrbrown/systematic` at a commit not on `main` without a policy error; that organization's Actions policy itself was unreadable (HTTP 403). **Read from source, not run.** A read of `fro-bot/agent` v0.146.0 (`65239fc5`) with OpenCode v2.3.2 shows that `repo-skills: "false"` stages no skills, that the repository's skills are never read in place (when the setting is on, the base repository's default branch is copied), and that the action sets `OPENCODE_DISABLE_PROJECT_CONFIG` for every spawn, which turns project config and project instruction discovery off, so `.agents/skills`, `AGENTS.md`, `CLAUDE.md`, `opencode.json` and repository plugins should not load. **Not observed.** The report issue's author and an Issues write under the narrowed ceiling in a caller; a callee asking for more than its caller grants; a live agent run with repository skills off (and `.claude/skills` and `.opencode/` plugin directories, which were not traced to a line); a tag-pinned cross-owner call, whose `referenced_workflows` suffix may differ, so the skill reads the `sha` and never the suffix or `ref`; a job-scoped token for the compare request; the organization's Actions policy. The probe workflow files no longer exist on any branch, so the run pages may show no workflow definition, and the logs expire on the normal schedule. The code that relies on these facts is the self-checkout step and the guards in `.github/workflows/connect.yaml`, and the named-fetch steps in `skills/ce-connect/references/fetch-and-import.md`, which `tests/unit/connect-workflow.test.ts`, `tests/unit/connect-scheduled-workflow.test.ts` and `tests/unit/connect-skill-contract.test.ts` pin against stubs.
@@ -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.
@@ -17,7 +17,7 @@ import { type InvocationWriteOptions, type ProcessTable, type PublishOptions } f
17
17
  * file the skill writes in the run's work directory, read here through the
18
18
  * bounded reader as a regular file.
19
19
  */
20
- export declare const CE_CONNECT_USAGE = "Usage: node connect.mjs <begin|validate|publish|decide|import|apply-ticks|render-report|ledger show [--offset N]|ledger clear|ledger unlock>";
20
+ export declare const CE_CONNECT_USAGE = "Usage: node connect.mjs <begin|validate|publish|decide|import|apply-ticks|render-report|allowed-origins|verify-provenance|ledger show [--offset N]|ledger clear|ledger unlock>";
21
21
  export interface HelperDeps {
22
22
  /** Environment for `XDG_STATE_HOME`. Defaults to `process.env`. */
23
23
  readonly env?: Readonly<Record<string, string | undefined>>;
@@ -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`. */
@@ -98,6 +165,12 @@ export interface RenderRequest {
98
165
  readonly attempt: string;
99
166
  /** Whether an Actions cache was restored for this run. */
100
167
  readonly cacheRestored: boolean;
168
+ /**
169
+ * The `owner/repo` that called the workflow. Absent, or Systematic itself
170
+ * (ignoring case), the fetch words stay bare: a bare word always means
171
+ * Systematic. Any other repository is named in every fetch word.
172
+ */
173
+ readonly repo?: string;
101
174
  }
102
175
  export type RenderResult = {
103
176
  readonly status: 'rendered';
@@ -105,12 +178,16 @@ export type RenderResult = {
105
178
  readonly bodyFile: string;
106
179
  /** The hash in the body's manifest marker. */
107
180
  readonly manifest: string;
181
+ /** Every open candidate, listed or not. */
108
182
  readonly open: number;
109
183
  readonly shown: number;
184
+ /** The listable candidates the size cap left out. */
110
185
  readonly hidden: number;
186
+ /** The open candidates with no bundle for their live revision, counted in one section. */
187
+ readonly unverified: number;
111
188
  /** Candidates listed for the first time on this date. */
112
189
  readonly fresh: number;
113
- /** The `<run>.<attempt>` fetch words of the listed candidates, in the order they appear. */
190
+ /** The fetch words of the listed candidates, in the order they appear: `<run>.<attempt>`, or `<owner>/<repo>:<run>.<attempt>` for a caller other than Systematic. */
114
191
  readonly fetches: readonly string[];
115
192
  readonly outcome: ReportOutcome;
116
193
  /** The workflow job turns red after posting. */
@@ -124,6 +201,50 @@ export type RenderResult = {
124
201
  readonly status: 'failed';
125
202
  readonly reason: 'invalid-request' | 'lock-failed' | 'ledger-unreadable' | 'no-invocation' | 'payload-store-unreadable' | 'payload-store-too-large' | 'manifest-store-unreadable' | 'write-failed';
126
203
  };
204
+ export interface Row {
205
+ readonly id: string;
206
+ readonly payload: Payload;
207
+ readonly isNew: boolean;
208
+ readonly block: string;
209
+ }
210
+ export interface BodyInput {
211
+ readonly outcome: ReportOutcome;
212
+ readonly facts: readonly string[];
213
+ readonly cacheRestored: boolean;
214
+ /** The report was rendered without the lock, so no payload or manifest was recorded. */
215
+ readonly stateUpdated: boolean;
216
+ /** The open entries that have a bundle for their live revision: the only rows with boxes. */
217
+ readonly rows: readonly Row[];
218
+ /** The ids of the other open entries, oldest first. */
219
+ readonly unverified: readonly string[];
220
+ /** The caller repository the fetch words name; absent for Systematic, whose words are bare. */
221
+ readonly fetchRepo?: string;
222
+ }
223
+ export interface Assembled {
224
+ readonly body: string;
225
+ readonly ids: readonly string[];
226
+ readonly hash: string;
227
+ readonly fetches: readonly string[];
228
+ readonly fresh: number;
229
+ }
230
+ /**
231
+ * The report with its first `shown` rows and the section naming `named`
232
+ * unverified ids. Exported for the tests of the size budget.
233
+ */
234
+ export declare function assembleReport(input: BodyInput, shown: number, named: number): Assembled;
235
+ /**
236
+ * The most rows the cap leaves room for beside the section for the rows that
237
+ * cannot be settled, and how many of those ids the section names. The section
238
+ * is bounded and counts against the cap like everything else, so the whole
239
+ * body stays under `REPORT_MAX_CHARS`, which is what leaves the workflow room
240
+ * for the one line it may add. The full id list is tried first; when it would
241
+ * leave no room for the oldest row, the list is halved down to the count alone.
242
+ * Exported for the tests of the size budget.
243
+ */
244
+ export declare function fitReport(input: BodyInput): {
245
+ readonly shown: number;
246
+ readonly named: number;
247
+ };
127
248
  /**
128
249
  * Render the report body for the state in `root`: the open candidates of the
129
250
  * ledger, oldest first, as many as fit under the cap, each with its two
@@ -151,7 +272,11 @@ export interface AcceptedTick {
151
272
  readonly id: string;
152
273
  readonly status: DecisionStatus;
153
274
  }
154
- export type SkipReason = 'conflict' | 'not-in-manifest' | 'not-open' | 'already-recorded';
275
+ export type SkipReason = 'conflict' | 'not-in-manifest' | 'not-open' | 'already-recorded'
276
+ /** The tick was made against another revision of the candidate than the ledger holds. */
277
+ | 'stale'
278
+ /** The tick is on a box with no revision, from a report before revisions: tick the revision-tagged box on the current report. */
279
+ | 'unversioned';
155
280
  export interface SkippedTick {
156
281
  readonly id: string;
157
282
  readonly status?: DecisionStatus;
@@ -181,9 +306,14 @@ export type TickResult = {
181
306
  /**
182
307
  * Record the ticks of a report body. A tick counts when its box is a generated
183
308
  * 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.
309
+ * and the candidate is open at the revision the line names; a tick for any
310
+ * other revision is skipped as `stale`, and a line from before revisions as
311
+ * `unversioned`. A decision already recorded with
312
+ * the same reason is left as it is, so a second pass changes nothing. Each
313
+ * decision is made only if the candidate is still open at that revision under
314
+ * the lock, so one recorded since the ledger was read is skipped as
315
+ * `not-open`, and a candidate whose content changed since is skipped as
316
+ * `stale`, never overwritten.
188
317
  */
189
318
  export declare function applyTicks(root: string, request: TickRequest, options?: TickOptions): TickResult;
319
+ 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;
@@ -0,0 +1,34 @@
1
+ /**
2
+ * The provenance decision of a named `ce:connect` fetch: did the scheduled run
3
+ * of another repository call Systematic's reusable `connect.yaml` at a commit
4
+ * on Systematic's default branch? The skill does the network part with the
5
+ * user's own `gh` and sends the text it got here, so the choice of entry, the
6
+ * shape of the hash and the compare verdict are code, not a model's reading of
7
+ * JSON.
8
+ *
9
+ * Two questions, one function. With the attempt's `referenced_workflows` alone
10
+ * it answers which commit to compare (`selected`). With the compare `status`
11
+ * as well it answers whether that commit is on the default branch
12
+ * (`accepted`). Every other case is a refusal that names one reason.
13
+ *
14
+ * Pure: no network, no file, no state. The verdict carries a reason or a hash
15
+ * and never any of the input. Import rule: nothing, because the `ce:connect`
16
+ * helper bundles it.
17
+ */
18
+ export type ProvenanceVerdict = {
19
+ readonly status: 'selected';
20
+ readonly sha: string;
21
+ } | {
22
+ readonly status: 'accepted';
23
+ readonly sha: string;
24
+ } | {
25
+ readonly status: 'refused';
26
+ readonly reason: 'provenance-unprovable' | 'not-a-connect-run';
27
+ };
28
+ export interface ProvenanceInput {
29
+ /** The text `gh api .../attempts/<n> --jq .referenced_workflows` printed. */
30
+ readonly referencedWorkflows: unknown;
31
+ /** The text `gh api .../compare/main...<sha> --jq .status` printed, when the commit was compared. */
32
+ readonly status?: unknown;
33
+ }
34
+ export declare function verifyProvenance(input: ProvenanceInput): ProvenanceVerdict;
@@ -17,6 +17,14 @@ export interface RepoIdentity {
17
17
  /** The full hash HEAD names. */
18
18
  readonly commit?: string;
19
19
  }
20
+ /**
21
+ * `owner/repo`, shaped as GitHub allows and nothing else. The one rule for a
22
+ * repository that is printed into a command, put in an API path or recorded as
23
+ * provenance, so every `connect-*` module and the helper agree on it. It checks
24
+ * the shape only and keeps the case; it says nothing about whether the
25
+ * repository exists.
26
+ */
27
+ export declare function isGithubOwnerRepo(value: string): boolean;
20
28
  /**
21
29
  * `owner/repo` of a GitHub remote URL, lowercase, or nothing. Three forms are
22
30
  * read: an https URL, `git@github.com:o/r` and an `ssh://` URL, each with or