@fro.bot/systematic 3.29.1 → 3.30.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
@@ -14,7 +14,7 @@ The five capability rows use the vocabulary in the [OpenCode profile](skills/usi
14
14
  | Blocking user interaction | `question` on v1 [OC-2] and v2 [OC2-PROFILE] | No native blocking tool; numbered-chat fallback [PI-2] | `AskUserQuestion` [CC-2] | `request_user_input`; blocking and root-thread-only [CX-1][CX-2] | `ask_user`; pauses until answers [GE-1][GE-2] | No dedicated tool name verified; plan-mode clarification and `--no-ask-user` are documented [GH-3][GH-4] |
15
15
  | Task tracking | `todowrite` on v1 [OC-3]; on v2 only when the experimental `todo` option is on [OC2-TODO] | No native mechanism; visible list fallback [PI-2] | `TodoWrite` is deprecated/disabled by default; `TaskCreate`/`TaskGet`/`TaskList`/`TaskUpdate` replace it [CC-3][CC-4] | **UNVERIFIED** [U] | **UNVERIFIED** [U] | No `TodoWrite` equivalent verified; cloud-agent tasks/sessions API is documented [GH-5] |
16
16
  | Skill loading | Skills become commands and `systematic_skill` is registered [OC-4][OC-5]; v2 also registers each skill with the host's own `skill` tool [OC2-SKILL] | `systematic_skill` adapter and Pi-native activation [PI-3][PI-4] | Native Skill tool with `SKILL.md` discovery (`~/.claude/skills/`, `.claude/skills/`, plugin `skills/`); Systematic ships no `systematic_skill` tool on Claude Code [CC-5][CC-6][CC-9] | **UNVERIFIED** [U] | **UNVERIFIED** [U] | `SKILL.md` skills [GH-6] |
17
- | Durable-output search | v1 and v2: `systematic_search` over solutions, plans, brainstorms and ideation docs (`kind`: `solution`, `plan`, `brainstorm`, `ideation` or `all`) [SR-1][SR-2][SR-5] | `systematic_search` with the same kinds, also handed to the built-in read-only delegates [SR-1][SR-5] | `systematic-search` bin in the plugin's `bin/`; user-level config only [SR-3] | None (no Systematic adapter) | None (no Systematic adapter) | None (no Systematic adapter) |
17
+ | Durable-output search | v1 and v2: `systematic_search` over solutions, plans, brainstorms and ideation docs (`kind`: `solution`, `plan`, `brainstorm`, `ideation`, `all` or `external`) [SR-1][SR-2][SR-5] [SR-6] | `systematic_search` with the same kinds, also handed to the built-in read-only delegates [SR-1][SR-5] [SR-6] | `systematic-search` bin in the plugin's `bin/`; user-level config, plus the project's proposed `sources` for `--kind external` only [SR-3] [SR-6] | None (no Systematic adapter) | None (no Systematic adapter) | None (no Systematic adapter) |
18
18
  | Skills-file support | `SKILL.md` is loaded by the Systematic skill path [OC-4] | `pi.skills` ships `./skills`, including `SKILL.md` discovery [PI-4][PI-5] | `SKILL.md` and `.claude/skills/`; the plugin bundle is built and identifier-translated in CI from `skills/`, never committed [CC-5][CC-6][CC-9] | **UNVERIFIED** [U] | **UNVERIFIED** [U] | `SKILL.md` [GH-6] |
19
19
 
20
20
  `[U]` means the capability was not checked in the supplied research pack. It is not a claim that the capability does not exist.
@@ -90,13 +90,17 @@ Honest capability boundary: output-style enforcement is real and applies automat
90
90
 
91
91
  ## Durable-output search — tool surfaces
92
92
 
93
- Systematic ships its own search over four kinds of durable output: `docs/solutions/`, `docs/plans/`, `docs/brainstorms/` and `docs/ideation/`. `kind` takes each of them, or `all` for one ranking across the four; leaving it out means `solution`. It is not a host primitive, so every claim below rests on Systematic's own code and tests. One host-neutral composition, `runSearch` in `src/lib/search-core.ts`, validates, loads each requested kind, ranks lexically, resolves the lifecycle per kind and renders; every surface only maps host I/O to it [SR-1]. The surfaces are `systematic_search` on OpenCode v1, OpenCode v2 and Pi, `systematic search` on the CLI, and the `systematic-search` bin in the Claude Code bundle [SR-1][SR-3]. The learnings-researcher calls it first and keeps its grep steps as the fallback; its `scope: past-work` makes one search per kind across all four, and ce:plan, ce:ideate, ce:brainstorm and deepen-plan dispatch it that way.
93
+ Systematic ships its own search over four kinds of durable output: `docs/solutions/`, `docs/plans/`, `docs/brainstorms/` and `docs/ideation/`. `kind` takes each of them, or `all` for one ranking across the four, or `external` for the opt-in external sources described below; leaving it out means `solution`. It is not a host primitive, so every claim below rests on Systematic's own code and tests. One host-neutral composition, `runSearch` in `src/lib/search-core.ts`, validates, loads each requested kind, ranks lexically, resolves the lifecycle per kind and renders; every surface only maps host I/O to it [SR-1]. The surfaces are `systematic_search` on OpenCode v1, OpenCode v2 and Pi, `systematic search` on the CLI, and the `systematic-search` bin in the Claude Code bundle [SR-1][SR-3]. The learnings-researcher calls it first and keeps its grep steps as the fallback; its `scope: past-work` makes one search per kind across all four, and ce:plan, ce:ideate, ce:brainstorm and deepen-plan dispatch it that way, followed by one `external` call.
94
+
95
+ **External search reach.** `kind: "external"` is a selector beside `all`, not a fifth kind. It searches folders of Markdown and Deciduous sync JSON that the user opted in to. A project proposes sources in its own `.opencode/systematic.jsonc` and none is read until the user lists the project's main repository root in `search.allow_project_sources`; a user config may map folders anywhere to projects with `projects[]`. Every surface reaches one per-call reader (`resolveExternalSources` in `src/lib/search-external-sources.ts`) that re-reads both user-level files, the project file and the project identity on each call; only `search.enabled`, tool registration and the registration-time `config unreadable` note are fixed at init [SR-6]. The OpenCode v2 plugin passes no config-directory override to that reader: on the plugin hosts it reads `~/.config/opencode` and `OPENCODE_CONFIG_DIR`. The bin reads user-level config, and from project config only the proposed `sources` and only for `--kind external` [SR-3] [SR-6]. Two accepted limits: every worktree of an allowed project, including a pull-request worktree under review, contributes its own proposals and Markdown, and a stale allow entry trusts whatever repository is later cloned to that path. Sources read local files only; nothing is redacted from a hit that reaches the model provider.
94
96
 
95
97
  Evidence tiers differ by host, and this file does not claim more than the tests do:
96
98
  - **Host-free contract evidence:** one parity test drives each adapter's real entry over one fixture corpus and compares the rendered text; a second runs the built bin under real Node from a directory with no `node_modules` [SR-1].
97
99
  - **Real-host tests:** OpenCode v1 on the floor (1.18.29) and current (1.19.4) lanes, and OpenCode v2 (2.2.0), each call the tool through a real host [SR-2]. CI runs them in the host-contract jobs.
98
100
  - **Delegated-reach tests:** on OpenCode v1 (floor and current), OpenCode v2 and Pi, a dispatched learnings-researcher child calls `systematic_search` and its result reaches the parent. The child's next model request must carry a tool message that starts `Search "` and names both planted documents, and the parent's final request must carry both paths [SR-5]. These prove reach and plumbing. A scripted model makes the call, so they do not show that a live model chooses to search.
99
- - **Claude Code:** the bin has no CI real-host check. It is covered by its foreign-directory bundle run and the output-style assertion in `tests/integration/claude-code.test.ts` [SR-3]. Whether a Claude Code subagent runs it is recorded once, as manual evidence, in [SR-4].
101
+ - **External search, host-free:** one parity test drives v1, v2, Pi, the CLI, the bin in process and the built bin under Node over one fixture project with a project source and a user source, and compares the rendered `external` text byte for byte. It also covers the not-allowed reply, an allow-list edit between two calls with nothing restarted, and `search.enabled: false` [SR-6].
102
+ - **External search, delegated:** on OpenCode v2 only, a dispatched learnings-researcher child searches `kind: external` and the planted external path reaches the parent's final answer, with a negative control that withholds the allow entry [SR-6]. Delegated external proofs on OpenCode v1, Pi and Claude Code have not been run, and a scripted model makes the call, so this shows reach and plumbing, not that a live model chooses `external`. The researcher's side of the call is pinned by the wiring contract test [SR-6].
103
+ - **Claude Code:** the bin has no CI real-host check. It is covered by its foreign-directory bundle run and the output-style assertion in `tests/integration/claude-code.test.ts` [SR-3]. Whether a Claude Code subagent runs it is recorded once, as manual evidence, in [SR-4]. That record predates `external`; no live Claude Code session has run `--kind external`.
100
104
 
101
105
  ## Worktree placement rule — bootstrap paths
102
106
 
@@ -273,6 +277,7 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
273
277
  - **WT-2** — `skills/git-worktree/scripts/worktree-manager.sh` (the script); `tests/unit/git-worktree-manager.test.ts` and `tests/unit/git-worktree-cleanup.test.ts` (placement from the root, a subdirectory and a linked worktree, refused layouts, ignore policy, base resolution, `--no-track`, `list`, `switch`, `copy-env`, `cleanup`; real git in throwaway repositories with a bare `origin`, `TEST_BASH=/bin/bash` runs them under bash 3.2); `tests/unit/git-worktree-skills-contract.test.ts` (the safety and routing terms in `skills/git-worktree/SKILL.md` and the pointers in `ce-review`, `orchestrating-subagents` and `git-clean-gone-branches`). Package probe: the plugin-init, Pi-init and built-output-style tests cited by WT-1, OC-8, PI-8 and CC-13. No live session has run.
274
278
  - **SR-1** — `src/lib/search-core.ts` (`runSearch`, the tool name and argument constants, the lifecycle constants and resolver); `src/lib/search-tool.ts` (the v1, v2 and Pi adapters); `tests/unit/search-adapters-parity.test.ts` (every adapter's real entry over one corpus: byte-identical text, fixed validation errors, no permission request, registration shapes); `tests/unit/search-lifecycle.test.ts` (the resolver over a lifecycle fixture corpus); `tests/unit/search-determinism.test.ts` (Bun and Node produce the same bits).
275
279
  - **SR-2** — `tests/integration/opencode-v1.test.ts` › "systematic_search finds a document under the host project, and limit 0 and 21 reach the core" (CI jobs `Host Contract v1 floor` and `Host Contract v1 current`); `tests/integration/opencode-v2.test.ts` › "systematic_search is offered to the model, finds a document under the project, and limit 0 and 21 reach the core" (CI job `Host Contract v2 shard N/4`, OpenCode 2.2.0, run only when `SYSTEMATIC_OPENCODE_V2_BIN` is set).
276
- - **SR-3** — `src/claude-code-search.ts` (the bin entry); `tests/unit/claude-code-search.test.ts` (the bundle run from a foreign directory); `tests/unit/harness-profiles-search.test.ts` and `tests/integration/claude-code.test.ts` (the output style names `systematic-search` and `command -v systematic-search`, and still ships no `systematic_skill` tool). No CI job runs the bin inside a live Claude Code session; see SR-4.
277
- - **SR-4** — Manual evidence, not a CI check. Recorded 2026-10-31 with Claude Code 2.1.312 and model claude-sonnet-5-5. The plugin bundle was built from 9ed5a336 with `bun run claude-code:build` and loaded with `--plugin-dir`. The fixture project held one solution and one `status: abandoned` brainstorm. `claude -p --output-format stream-json --verbose --forward-subagent-text` was given a prompt to dispatch `systematic:learnings-researcher` with `scope: past-work`. Outcome: the subagent ran `systematic-search --kind all --limit 12 -- '<query>'` through Bash. The Bash `tool_use` carried `parent_tool_use_id` set to the `Agent` dispatch's id. The `tool_result` began `Search "` and named both the solution and the brainstorm. In that bundle the researcher still used the `all` call. The per-kind calls that replaced it run through the same bin.
280
+ - **SR-3** — `src/claude-code-search.ts` (the bin entry); `tests/unit/claude-code-search.test.ts` (the bundle run from a foreign directory); `tests/unit/harness-profiles-search.test.ts` and `tests/integration/claude-code.test.ts` (the output style names `systematic-search` and `command -v systematic-search`, and still ships no `systematic_skill` tool). From project config the bin reads only the `sources` a project proposes, and only for `--kind external` (SR-6). No CI job runs the bin inside a live Claude Code session; see SR-4.
281
+ - **SR-4** — Manual evidence, not a CI check. Recorded 2026-10-31 with Claude Code 2.1.312 and model claude-sonnet-5-5. The plugin bundle was built from 9ed5a336 with `bun run claude-code:build` and loaded with `--plugin-dir`. The fixture project held one solution and one `status: abandoned` brainstorm. `claude -p --output-format stream-json --verbose --forward-subagent-text` was given a prompt to dispatch `systematic:learnings-researcher` with `scope: past-work`. Outcome: the subagent ran `systematic-search --kind all --limit 12 -- '<query>'` through Bash. The Bash `tool_use` carried `parent_tool_use_id` set to the `Agent` dispatch's id. The `tool_result` began `Search "` and named both the solution and the brainstorm. In that bundle the researcher still used the `all` call. The per-kind calls that replaced it run through the same bin. Scope limit: this run predates `kind: external`, and no live Claude Code session has run `--kind external`.
278
282
  - **SR-5** — `tests/helpers/delegated-search-proof.ts` (the planted fixture, the scripted four-turn model and the proof assertion with its failure diagnostics); `tests/unit/delegated-search-proof.test.ts` (the assertion over recorded request lists, including each failure code); `tests/integration/opencode-v1.test.ts` › "a dispatched learnings-researcher child calls systematic_search and its result reaches the parent" (CI jobs `Host Contract v1 floor` and `Host Contract v1 current`, OpenCode 1.18.29 and the current v1 pin); `tests/integration/opencode-v2.test.ts` › the same test name (CI job `Host Contract v2 shard N/4`, OpenCode 2.2.0, run only when `SYSTEMATIC_OPENCODE_V2_BIN` is set); `tests/integration/pi.test.ts` › "a delegated learnings-researcher child calls systematic_search and its result reaches the parent" (the real Pi runtime, run in the v2 host-contract profile). Each file also has a negative control: with `search.enabled` false the child is not offered the tool and the proof fails saying so. Scope limit: a scripted model makes the call, so these show reach and plumbing only.
283
+ - **SR-6** — External search reach (`kind: "external"`). Code: `src/lib/search-external-sources.ts` (the per-call reader every surface shares), `src/lib/search-project-identity.ts` (main-root identity from filesystem reads), `src/lib/search-external.ts` and `src/lib/search-external-deciduous.ts` (the Markdown and Deciduous loaders), `src/lib/search-user-config.ts` (the field and entry validators and the 1 MB bin-safe project reader), `src/lib/search-render.ts` (the external renderer). Host-free tests: `tests/unit/search-project-identity.test.ts` (real git repositories and `git worktree add`: a worktree maps to its main root, forged and inconsistent `.git` files, a bare repository, `core.worktree` and a symlinked `.git` never resolve); `tests/unit/search-external-sources.test.ts` (resolution order, worktrees, shadowing, the 8-source cap, user and custom config directories, nothing cached between calls, the module graph); `tests/unit/search-external.test.ts` and `tests/unit/search-external-deciduous.test.ts` (records, caps, the shared read budget, states, symlinks and read-only behavior); `tests/unit/search-adapters-parity.test.ts` › \"search adapters parity: kind external\" (v1, v2, Pi, CLI, the bin in process and the built bin under Node give byte-identical text; not-allowed replies; an allow-list edit between calls; `search.enabled` false); `tests/unit/claude-code-search.test.ts` (`--kind external` in process and from a foreign directory under Node, the stderr warning for a broken project file, and a bundle that contains neither `config.ts` nor `config-schema.ts`); `tests/unit/opencode-v2-search.test.ts` › \"setupOpenCodeV2 with a project search.sources problem\" (a project file that parses never fails v2 setup, and one that cannot be parsed still does); `tests/unit/past-work-wiring-contract.test.ts` › \"the external call in past-work scope\" and the External records group (the researcher prompt side); `tests/unit/delegated-search-proof.test.ts` › \"external mode\" and `tests/helpers/delegated-search-proof.ts` (the external fixture, script and assertion). Real host: `tests/integration/opencode-v2.test.ts` › \"a dispatched learnings-researcher child searches kind external and the planted external record reaches the parent\" and its negative control \"with the allow entry absent the child receives the not-allowed reply, the parent never sees the external path and the proof names the failure\" (CI job `Host Contract v2 shard N/4`, OpenCode 2.2.0, run only when `SYSTEMATIC_OPENCODE_V2_BIN` is set). Scope limits: a scripted model makes the call, so the real-host proof shows reach and plumbing only; it covers OpenCode v2 alone. No real-host external proof exists for OpenCode v1, Pi or Claude Code.
@@ -20,26 +20,22 @@ Drop the `exclude:` path from the hits by exact path; a `Supersedes:` line keeps
20
20
 
21
21
  ## Search Strategy (Search First, Grep Fallback)
22
22
 
23
- The `docs/solutions/` directory holds documented solutions with YAML frontmatter. There may be hundreds of files, so use this strategy, which minimizes tool calls. Never assume a layout: discover what exists first.
23
+ `docs/solutions/` holds documented solutions with YAML frontmatter. Never assume a layout: discover what exists first.
24
24
 
25
- Try the search tool (Step 1b: one call in `solutions` scope, one per kind in `past-work` scope). When it returns hits, it replaces the grep steps (Steps 2 and 3, and the content search in Step 4). When it cannot help, the grep steps below run unchanged.
25
+ Try the search tool first (Step 1b). When it returns hits, it replaces the grep steps (Steps 2 and 3, and the content search in Step 4). When it cannot help, the grep steps below run unchanged.
26
26
 
27
27
  ### Step 0: Discover What Exists
28
28
 
29
29
  List `docs/solutions/` with a directory listing tool.
30
30
 
31
31
  - If `docs/solutions/` does not exist or holds no `.md` files, stop and return the "No Matches" result, saying the project has no solutions directory yet. This is not an error. Read no other path.
32
- - Past-work: list `docs/solutions/`, `docs/plans/`, `docs/brainstorms/` and `docs/ideation/`, and read no missing path. Stop with "No Matches" only when none of the four exists or holds a `.md` file.
32
+ - Past-work: list `docs/solutions/`, `docs/plans/`, `docs/brainstorms/` and `docs/ideation/`, and read no missing path. Stop with "No Matches" only when none of the four exists or holds a `.md` file and the external call has run and returned no hits. With hits, report them under External records and name absent kinds in Search Context.
33
33
  - The subdirectories you find are the categories. Do not assume any particular category exists.
34
34
  - Skip `README.md` files and anything under `_archived/` when collecting candidates. Never treat `critical-patterns.md` as a candidate (Step 3b handles it).
35
35
 
36
36
  ### Step 1: Extract Keywords from Feature Description
37
37
 
38
- From the feature/task description, identify:
39
- - **Module names**: the named modules, services or areas the work touches
40
- - **Technical terms**: e.g., "N+1", "caching", "authentication"
41
- - **Problem indicators**: e.g., "slow", "error", "timeout", "memory"
42
- - **Component types**: e.g., "database", "api", "background job", "cli"
38
+ From the feature/task description, identify module names, technical terms (e.g., "N+1", "caching"), problem indicators (e.g., "slow", "timeout") and component types (e.g., "database", "api", "cli").
43
39
 
44
40
  ### Step 1b: Search First (When a Search Tool Exists)
45
41
 
@@ -52,21 +48,27 @@ From the feature/task description, identify:
52
48
 
53
49
  **Past-work scope.** Make one search per kind, `solution`, `plan`, `brainstorm` and `ideation`, and merge the hits by repo-root path: `systematic_search({ query: "<description>", kind: "<kind>", limit: 5 })`. With the command, pass `--kind <kind> --limit 5`. Never search `all`: long plans crowd the other kinds out of its top results. A `none`, `empty` or zero-hit reply from one kind adds nothing. A kind whose call returns `Error:` is unsearched: say so in Search Context, and grep that kind's directory only (see the Past-work grep fallback). The other kinds' hits still route normally. If every kind errors, run the whole grep path. Route on the merged hits.
54
50
 
51
+ **External call (past-work).** Then make a fifth call: `systematic_search({ query: "<description>", kind: "external", limit: 3 })`, or `--kind external --limit 3` with the command. It runs regardless: Step 0 and the stop when all four say `none` do not end the run before it. `past-work` scope only, never `solutions` scope or overlap mode. Its reply opens `External sources for`; route it by the External rows below.
52
+
55
53
  **Read the reply, then pick one path.** Read the header from the line that starts with `Search "`. On the command path, warnings can print before it.
56
54
 
57
55
  In overlap mode (the caller asks for an overlap assessment against a new doc), drop the doc under comparison from the hits first, by its repo-root path. If that hit's `Supersedes:` line lists other docs, those docs stay in the comparison. Then route on the hits that remain, not on the count in the header.
58
56
 
59
57
  | Reply | Path |
60
58
  |-------|------|
61
- | The header says `corpus: none` | Stop and return the "No Matches" result, saying the project has no solutions directory yet. This is not an error. Do not run the grep steps. A `could not read docs/solutions` warning under the header means the directory exists but cannot be read; report that warning too. Past-work: that kind adds nothing and is not a stop while another kind has docs; stop only when all four say `none`. |
62
- | The header says `corpus: empty` | Run Step 3b first. Search leaves out `critical-patterns.md`, so a project whose only doc is that file reports `empty`. Then return the "No Matches" result, saying the project has no indexable docs, together with any relevant critical patterns in the Critical Patterns section. This is not an error. Do not run the grep steps. Past-work: that kind adds nothing; take this row only when no kind has docs. |
63
- | The reply ends with `[Systematic: search output truncated at 16 KB]` | Past-work. Results were cut: say so, and tell the caller to narrow the query. Do not repeat that call. |
59
+ | The header says `corpus: none` | Stop and return the "No Matches" result, saying the project has no solutions directory yet. This is not an error. Do not run the grep steps. A `could not read docs/solutions` warning under the header means the directory exists but cannot be read; report that warning too. Past-work: that kind adds nothing and is not a stop while another kind has docs; stop only when all four say `none` and the external call has run and returned no hits (with hits: External records and absent kinds in Search Context). |
60
+ | The header says `corpus: empty` | Run Step 3b first. Search leaves out `critical-patterns.md`, so a project whose only doc is that file reports `empty`. Then return the "No Matches" result, saying the project has no indexable docs, together with any relevant critical patterns in the Critical Patterns section. This is not an error. Do not run the grep steps. Past-work: that kind adds nothing; take this row only when no kind has docs and the external reply has no hits (else External records and absent kinds in Search Context). |
61
+ | The reply ends with `[Systematic: search output truncated at 16 KB]` (a kind) or `[Systematic: search output truncated at 12 KB]` (external) | Past-work. Results were cut: say so, and tell the caller to narrow the query. Do not repeat that call. |
64
62
  | The header says `N doc(s), M hit(s)` with M at least 1 (the header prints `1 doc` and `1 hit` in the singular), and at least one hit remains after the overlap-mode drop | **Search path.** Skip Steps 2 and 3 and the content search in Step 4. Run Step 3b. Then go to Step 5 with the hits. |
65
63
  | The header says `N doc(s), 0 hits` (including the singular `1 doc, 0 hits`), or in overlap mode no hit remains after the drop | Grep path. Go to Step 2. |
64
+ | An external reply with at least 1 hit | Up to 4 hits go under External records, whatever the built-in kinds hold. |
65
+ | An external reply with 0 hits, `no project:`, or `no external sources are active` | No records. Not an error. Do not grep. |
66
+ | Any external reply | Whatever the hit count, copy the `Notes:`, `Project sources:` (including `the project config could not be read`) and `Warnings:` lines and each source-state line (`missing: root not found.`, `empty: no readable records.`, `unreadable: root could not be read.`, `dropped: see the warnings.`) into Search Context. Hits plus a `Project sources:` line with `not in search.allow_project_sources`: route the hits and report "project sources not read: not allowed". `+N more hits not shown` is a cut like the 12 KB marker: results cut, narrow the query. |
67
+ | External call: the reply says search is disabled, starts with `Error:`, says `No project directory is available`, its first line says `not in search.allow_project_sources, so nothing was read`, or the call fails | Search Context: external records not searched, and why. Never grep or glob a source's folders, and never retry. |
66
68
  | The reply says `No project directory is available` | Grep path. Go to Step 2. |
67
69
  | The reply says search is disabled, starts with `Error:`, or the call fails | Grep path. Go to Step 2. Past-work: per kind, as above. |
68
70
 
69
- The grep path keeps its OR patterns for synonyms. A zero-hit search does not add a new synonym pass.
71
+ A zero-hit search adds no synonym pass.
70
72
 
71
73
  **On the search path:**
72
74
  - The hits are already ranked and already resolved for lifecycle. Do not run Step 4's resolution again.
@@ -90,21 +92,11 @@ If the feature type is clear, narrow the search to the category directories from
90
92
  content-search: pattern="title:.*cache" path=docs/solutions/ files_only=true case_insensitive=true
91
93
  content-search: pattern="tags:.*(cache|caching|ttl)" path=docs/solutions/ files_only=true case_insensitive=true
92
94
  content-search: pattern="module:.*(Checkout|Orders)" path=docs/solutions/ files_only=true case_insensitive=true
93
- content-search: pattern="component:.*background_job" path=docs/solutions/ files_only=true case_insensitive=true
94
95
  ```
95
96
 
96
- **Pattern construction tips:**
97
- - Use `|` for synonyms: `tags:.*(auth|login|session|token)`
98
- - To learn which `module`, `component` or `tags` values the project actually uses, search for the field name (`^module:`) and read the values the matches show. Do not guess values from memory.
99
-
100
- **Combine results** from all searches to get candidate files (typically 5-20 files instead of 200). Drop the files Step 0 says to skip.
97
+ **Combine results** from all searches to get candidate files. Drop the files Step 0 says to skip. With more than 25 candidates, re-run with more specific patterns or narrow by category.
101
98
 
102
- **If search returns >25 candidates:** Re-run with more specific patterns or combine with category narrowing.
103
-
104
- **If search returns <3 candidates:** Do a broader content search (not just frontmatter fields) as fallback:
105
- ```
106
- content-search: pattern="cache" path=docs/solutions/ files_only=true case_insensitive=true
107
- ```
99
+ **If search returns <3 candidates:** Do a broader content search (not just frontmatter fields), such as `pattern="cache"`.
108
100
 
109
101
  ### Step 3b: Check Critical Patterns (Only If the File Exists)
110
102
 
@@ -152,12 +144,7 @@ Then resolve every candidate before scoring:
152
144
 
153
145
  For each remaining candidate (including successors, and the hits on the search path), read the frontmatter:
154
146
 
155
- ```bash
156
- # Read frontmatter only (limit to first 30 lines)
157
- Read: [file_path] with limit:30
158
- ```
159
-
160
- Extract these fields from the YAML frontmatter:
147
+ Read only the first 30 lines (`limit:30`). Extract these fields from the YAML frontmatter:
161
148
  - **module**: Which module/system the solution applies to
162
149
  - **problem_type**: Category of issue
163
150
  - **component**: Technical component affected
@@ -174,26 +161,15 @@ Past-work: for plans, brainstorms and ideation docs, read `title`, `topic` and `
174
161
 
175
162
  Match frontmatter fields against the feature/task description:
176
163
 
177
- **Strong matches (prioritize):**
178
- - `module` matches the feature's target module
179
- - `tags` contain keywords from the feature description
180
- - `symptoms` describe similar observable behaviors
181
- - `component` matches the technical area being touched
182
-
183
- **Moderate matches (include):**
184
- - `problem_type` is relevant (e.g., a performance problem type for optimization work)
185
- - `root_cause` suggests a pattern that might apply
186
- - Related modules or components mentioned
187
-
188
- **Weak matches (skip):**
189
- - No overlapping tags, symptoms, or modules
190
- - Unrelated problem types
164
+ - **Strong (prioritize):** `module` matches the target module; `tags` hold keywords from the description; `symptoms` describe similar behavior; `component` matches the technical area.
165
+ - **Moderate (include):** `problem_type` is relevant; `root_cause` suggests a pattern that might apply; related modules or components are mentioned.
166
+ - **Weak (skip):** no overlapping tags, symptoms or modules; unrelated problem types.
191
167
 
192
168
  **Past-work.** Judge plans, brainstorms and ideation docs by their title, topic, filename and decision or requirements sections, not by the solution fields above. A real match on title or topic is enough to keep one. Solutions keep these rules, and `solutions` scope is unchanged.
193
169
 
194
170
  ### Step 7: Full Read of Relevant Files
195
171
 
196
- Fully read only the files that pass the filter (strong or moderate matches), to extract the problem, the solution, prevention guidance and code examples.
172
+ Fully read only the files that pass the filter (strong or moderate matches).
197
173
 
198
174
  ### Step 8: Return Distilled Summaries
199
175
 
@@ -270,7 +246,7 @@ In `past-work` scope, return this in place of the Output Format template.
270
246
 
271
247
  State the method once, on one line, in Search Context: `search`, `search, plus origin lookups by grep`, or `grep (<why search was not used>)`.
272
248
 
273
- **Budget.** Report at most 12 items. Read each one's frontmatter and targeted headings, with at most 3 full reads.
249
+ **Budget.** Report at most 16 items: at most 12 from the four built-in kinds and at most 4 External records. Read each built-in item's frontmatter and targeted headings, with at most 3 full reads in all. Never read an external source's files.
274
250
 
275
251
  **Groups.** Put every item in exactly one group, mechanically from its recorded status, never from inference. Trim and lower-case a plan, brainstorm or ideation status before comparing.
276
252
 
@@ -286,31 +262,23 @@ Recorded decisions and their rationale come from body sections (Key Decisions, S
286
262
 
287
263
  When nothing matches, write "no recorded plan or solution found in the results". Do not say the repo holds none.
288
264
 
289
- Open with `## Past-Work Search Results` and `### Search Context` (feature, method, absent kinds, unsearched kinds, "results cut, narrow the query" when truncated). Then, omitting empty groups: `### Proven lessons`, `### Recorded decisions and their rationale`, `### Existing or completed work`, `### Rejected, deferred or superseded directions`, `### Conflicts and open questions`.
265
+ **External records.** The sixth group sits outside the status table. Every external hit goes here and nowhere else, and never to a lifecycle group, whatever its text says. Never infer a status. An item reads `- **[title]**: [source], [path], [label]. [why it applies]`: the source name comes from the section header, and the label is the hit's `Status:` value, its `node_type`, or `no recorded status` when it prints neither (`node_type decision`, for example). A recorded status is not verified.
290
266
 
291
- Under each group, one line per item: `- **[title]**: [path], status [recorded status]. [why it applies]`. Copy `Supersedes:`, `Successor:` and `Caution:` lines literally under their item.
267
+ Open with `## Past-Work Search Results` and `### Search Context` (feature, method, absent kinds, unsearched kinds, external records not searched and why, external source state, "results cut, narrow the query" when truncated). Then, omitting empty groups: `### Proven lessons`, `### Recorded decisions and their rationale`, `### Existing or completed work`, `### Rejected, deferred or superseded directions`, `### Conflicts and open questions`, `### External records`.
292
268
 
293
- ## Efficiency Guidelines
269
+ Under each group, one line per item: `- **[title]**: [path], status [recorded status]. [why it applies]`. Copy `Supersedes:`, `Successor:` and `Caution:` lines literally under their item. External records use the item format above.
294
270
 
295
- The rules below about content search, patterns, synonyms and narrowing apply to the grep path. On the search path, the hits replace them.
271
+ ## Efficiency Guidelines
296
272
 
297
273
  **DO:**
298
- - List `docs/solutions/` first and work from the directories that exist
299
- - Try the search tool, when it exists, before any grep step: one call in `solutions` scope, one per kind (four) in `past-work` scope
300
- - Take the grep path when search finds nothing, is disabled, errors or does not exist
301
- - Use the native content-search tool to pre-filter files BEFORE reading any content (critical for 100+ files)
302
- - Run content searches in PARALLEL, with `title:` and OR patterns for synonyms
274
+ - Try the search tool, when it exists, before any grep step: one call in `solutions` scope; in `past-work` scope one per kind (four), then the external call
275
+ - Pre-filter with the content-search tool in parallel, with `title:` and OR patterns for synonyms, before reading any content
303
276
  - Use one search to find which files mention the lifecycle fields, read each such doc's frontmatter for the values, and resolve superseded docs before scoring
304
277
  - Prioritize high-severity and critical patterns
305
278
 
306
279
  **DON'T:**
307
280
  - Read a path that may not exist (a category directory, `critical-patterns.md`, a successor) without checking that it exists
308
- - Return raw document contents (distill instead)
309
281
  - Return a superseded doc whose successor resolves. Return its successor.
310
- - Run the grep steps after a search that returned hits, or call the search tool more than once in `solutions` scope, or more than four times in `past-work` scope (one call per kind)
282
+ - Run the grep steps after a search that returned hits, or call the search tool more than once in `solutions` scope, or more than five times in `past-work` scope (one call per kind, then the external call)
311
283
  - Follow a `superseded_by` outside the doc's own kind (a link into another of the four directories gets a `Successor:` line instead) or one that fails that kind's form rule, and never follow more than 5 hops
312
- - Include tangentially related learnings (focus on relevance)
313
-
314
- ## Integration Points
315
-
316
- Invoked by `/ce:plan` (planning and confidence checking), `/ce:review` (known patterns in the diff), `/ce:ideate` (grounding ideas), `/ce:compound` (Related Docs Finder), `/deepen-plan`, or manually before starting work. Aim to surface relevant learnings in under 30 seconds.
284
+ - Grep or glob an external source's folders, read its files, or retry an external call
@@ -6,10 +6,14 @@
6
6
  * with no `node_modules`.
7
7
  *
8
8
  * It reads search settings from the two user-level files only (through
9
- * `loadUserLevelSearchSettings`) and never reads project config, so a
10
- * repository cannot switch it off. Because it
11
- * never reads the project file it also cannot print the project-config strip
12
- * warning that `systematic search` prints; that asymmetry is accepted.
9
+ * `loadUserLevelSearchSettings`), so a repository cannot switch it off or
10
+ * allow itself. From project config it reads one thing, and only for
11
+ * `--kind external`: the `sources` the project proposes, through the bin-safe
12
+ * reader in `search-user-config.ts`. It does not read the project
13
+ * config for anything else, so it cannot print the strip warning that
14
+ * `systematic search` prints for `enabled` or `allow_project_sources`; that
15
+ * asymmetry is accepted. `userLevel` reaches the external reader as well as
16
+ * the settings loader, so one override selects the allow list for both.
13
17
  *
14
18
  * Import rule: nothing here may import `config.ts` or `config-schema.ts`.
15
19
  * The bundle would then carry the config loader and its UMD jsonc build, which
package/dist/cli.d.ts CHANGED
@@ -2,7 +2,7 @@
2
2
  import { type CapabilityClock, type CapabilityOutputSink, type ConfigObservationMetadata } from './lib/capability-snapshot.js';
3
3
  import { type LoadConfigOptions } from './lib/config.js';
4
4
  import { type ReadChunk } from './lib/review-return-validator.js';
5
- import { type SearchCliSettingsLoad } from './lib/search-cli.js';
5
+ import { type SearchCliOptions, type SearchCliSettingsLoad } from './lib/search-cli.js';
6
6
  export interface CapabilityCliRoots {
7
7
  readonly agentsRoot: string;
8
8
  readonly cwd: string;
@@ -38,12 +38,15 @@ interface ValidateReviewReturnCliOptions {
38
38
  export declare function runValidateReviewReturnCli(options: ValidateReviewReturnCliOptions): number;
39
39
  /**
40
40
  * The settings loader `systematic search` injects into `runSearchCli`: the
41
- * full config loader, so the project-config strip warning for a `search` block
42
- * reaches stderr (AE2). Config is read at the project root, resolved the same
43
- * way the corpus root is. A thrown load, an invalid user or custom source, or
44
- * an invalid `search` block all give `unreadable: true`, which makes the core
45
- * add the `config unreadable` note to the results. A project source never
46
- * counts: project config has no effect on search.
41
+ * full config loader, so the project-config strip warning for `search.enabled`
42
+ * or `search.allow_project_sources` reaches stderr. Config is read at the
43
+ * project root, resolved the same way the corpus root is. A thrown load, an
44
+ * invalid user or custom source, or an invalid `search` block all give
45
+ * `unreadable: true`, which makes the core add the `config unreadable` note to
46
+ * the results. A project source never counts toward `unreadable`, and a
47
+ * project config cannot change `enabled` or the allow list. It may propose
48
+ * `search.sources`, but the loader validates and discards them: the per-call
49
+ * external reader is their only consumer, and nothing here reads them.
47
50
  *
48
51
  * The full loader drops a whole file that fails validation, so a valid
49
52
  * `search.enabled: false` next to a bad sibling key would be lost. When a
@@ -52,4 +55,12 @@ export declare function runValidateReviewReturnCli(options: ValidateReviewReturn
52
55
  * reader the `systematic-search` bin uses), so the opt-out still holds. Never throws.
53
56
  */
54
57
  export declare function loadSearchSettingsForCli(startDir: string, configOptions?: LoadConfigOptions): SearchCliSettingsLoad;
58
+ /**
59
+ * What `systematic search` hands `runSearchCli` besides its argv: the settings
60
+ * loader and the config directories `--kind external` reads its allow list and
61
+ * user sources from. Both take the same override, so one `configOptions`
62
+ * reaches the settings loader and the external reader alike. Left out,
63
+ * both read the home directory and `OPENCODE_CONFIG_DIR`.
64
+ */
65
+ export declare function searchCliInputs(configOptions?: LoadConfigOptions): Pick<SearchCliOptions, 'loadSettings' | 'configOptions'>;
55
66
  export {};
package/dist/cli.js CHANGED
@@ -44,7 +44,7 @@ import {
44
44
  SEARCH_NOTICES,
45
45
  SEARCH_CONFIG_UNREADABLE_NOTE,
46
46
  runSearch
47
- } from "./index-e467g4b6.js";
47
+ } from "./index-jvpbpj9z.js";
48
48
  var __defProp = Object.defineProperty;
49
49
  var __returnValue = (v) => v;
50
50
  function __exportSetter(name, newValue) {
@@ -80,6 +80,20 @@ import path6 from "path";
80
80
 
81
81
  // src/lib/agent-resolver.ts
82
82
  import fs from "fs";
83
+ // node_modules/.bun/zod@4.6.7/node_modules/zod/v4/classic/iso.js
84
+ function datetime(params) {
85
+ return _isoDateTime(ZodISODateTime, params);
86
+ }
87
+ function date(params) {
88
+ return _isoDate(ZodISODate, params);
89
+ }
90
+ function time(params) {
91
+ return _isoTime(ZodISOTime, params);
92
+ }
93
+ function duration(params) {
94
+ return _isoDuration(ZodISODuration, params);
95
+ }
96
+ // src/lib/agent-resolver.ts
83
97
  function buildAgentCatalog(agentsDir) {
84
98
  const infos = findAgentsInDir(agentsDir);
85
99
  const byName = new Map;
@@ -844,19 +858,7 @@ function buildCapabilitySnapshot(options) {
844
858
  options.outputSink?.(serialized);
845
859
  return snapshot;
846
860
  }
847
- // node_modules/.bun/zod@4.6.7/node_modules/zod/v4/classic/iso.js
848
- function datetime(params) {
849
- return _isoDateTime(ZodISODateTime, params);
850
- }
851
- function date(params) {
852
- return _isoDate(ZodISODate, params);
853
- }
854
- function time(params) {
855
- return _isoTime(ZodISOTime, params);
856
- }
857
- function duration(params) {
858
- return _isoDuration(ZodISODuration, params);
859
- }
861
+
860
862
  // src/lib/main-module.ts
861
863
  import fs2 from "fs";
862
864
  import { fileURLToPath } from "url";
@@ -2927,7 +2929,7 @@ function runReviewReturnValidator(options) {
2927
2929
  // src/lib/search-cli.ts
2928
2930
  import path4 from "path";
2929
2931
  function searchCliUsage(commandName) {
2930
- return `Usage: ${commandName} <query...> [--dir <path>] [--kind solution|plan|brainstorm|ideation|all] [--limit <${MIN_LIMIT}-${MAX_LIMIT}>] [--]
2932
+ return `Usage: ${commandName} <query...> [--dir <path>] [--kind solution|plan|brainstorm|ideation|all|external] [--limit <${MIN_LIMIT}-${MAX_LIMIT}>] [--]
2931
2933
 
2932
2934
  Searches the project's past work by symptom, error text, module or topic, and
2933
2935
  prints ranked hits: the docs/solutions learnings, and the docs/plans,
@@ -2938,14 +2940,20 @@ Options:
2938
2940
  The project root is the nearest ancestor holding .git.
2939
2941
  --kind <kind> The kind of durable output to search: solution (docs/solutions,
2940
2942
  the default), plan (docs/plans), brainstorm (docs/brainstorms),
2941
- ideation (docs/ideation), or all to rank every kind together.
2942
- --limit <n> How many hits to return, ${MIN_LIMIT} to ${MAX_LIMIT} (default: 8).
2943
+ ideation (docs/ideation), all to rank every kind together, or
2944
+ external for the external sources you allowed, ranked per source.
2945
+ An external hit prints as <source>/<path>: strip the source name for a
2946
+ path inside one of that source's roots (with several roots, the first
2947
+ that has the file).
2948
+ --limit <n> How many hits to return, ${MIN_LIMIT} to ${MAX_LIMIT} (default: 8). With
2949
+ --kind external it applies to each source, at most 5 per source.
2943
2950
  -- End of options; everything after it is part of the query.
2944
2951
  -h, --help Show this help.
2945
2952
 
2946
2953
  Exit statuses: 0 results, no hits, or search disabled; 2 usage error`;
2947
2954
  }
2948
2955
  var SEARCH_CLI_DISABLED_NOTICE = "Search is disabled (search.enabled is false in your Systematic config), so there is nothing to search.";
2956
+ var SEARCH_CLI_PROJECT_CONFIG_WARNING = "[systematic] The project Systematic config could not be read, so it proposes no external sources.";
2949
2957
  var VALUE_FLAGS = new Set([
2950
2958
  "dir",
2951
2959
  "kind",
@@ -3041,12 +3049,16 @@ async function runSearchCli(options) {
3041
3049
  }, {
3042
3050
  startDir,
3043
3051
  settings: load.settings,
3052
+ configOptions: options.configOptions,
3044
3053
  ...load.unreadable && { notes: [SEARCH_CONFIG_UNREADABLE_NOTE] }
3045
3054
  });
3046
3055
  if (!response.ok) {
3047
3056
  errorSink(response.text);
3048
3057
  return 2;
3049
3058
  }
3059
+ if (response.selector === "external" && response.projectConfigUnreadable) {
3060
+ errorSink(SEARCH_CLI_PROJECT_CONFIG_WARNING);
3061
+ }
3050
3062
  outputSink(response.text);
3051
3063
  return 0;
3052
3064
  } catch {
@@ -3390,13 +3402,18 @@ Commands:
3390
3402
  CI, issues, or fixtures. Not for the ce:review parent's own run artifact.
3391
3403
  Exit statuses: 0 valid artifact, 1 validation failure,
3392
3404
  2 operational failure, 3 legacy artifact with no schema_version
3393
- search <query...> [--dir <path>] [--kind solution|plan|brainstorm|ideation|all] [--limit <1-20>]
3405
+ search <query...> [--dir <path>] [--kind solution|plan|brainstorm|ideation|all|external] [--limit <1-20>]
3394
3406
  Search the project's past work by symptom, error text, module or topic,
3395
3407
  and print ranked hits: docs/solutions learnings (the default kind),
3396
3408
  docs/plans, docs/brainstorms and docs/ideation. --kind all ranks every
3397
- kind together. The project root is the nearest ancestor of --dir
3398
- (default: the current directory) that holds .git.
3399
- Reads user-level search settings; a project config cannot change them.
3409
+ kind together; --kind external searches the external sources you
3410
+ allowed, ranked per source; --limit then applies to each source,
3411
+ at most 5 per source. An external hit prints as <source>/<path>; strip the
3412
+ source name for a path inside one of the source's roots (with several
3413
+ roots, the first that has the file). The project root is the nearest
3414
+ ancestor of --dir (default: the current directory) that holds .git.
3415
+ Reads search settings from your user config. A project config can
3416
+ propose external sources but cannot allow them or switch search off.
3400
3417
  Exit statuses: 0 results, no hits, or search disabled; 2 usage error
3401
3418
  Use -- to end options, for a query that starts with a dash
3402
3419
  validate-review-return Validate one raw ce:review persona return read from stdin
@@ -3704,6 +3721,12 @@ function loadSearchSettingsForCli(startDir, configOptions) {
3704
3721
  };
3705
3722
  }
3706
3723
  }
3724
+ function searchCliInputs(configOptions) {
3725
+ return {
3726
+ loadSettings: (startDir) => loadSearchSettingsForCli(startDir, configOptions),
3727
+ configOptions: userLevelDirOptions(configOptions)
3728
+ };
3729
+ }
3707
3730
  function isHarness(value) {
3708
3731
  return value === "opencode" || value === "pi";
3709
3732
  }
@@ -4163,7 +4186,7 @@ function runLegacyCli(args) {
4163
4186
  cwd: process.cwd(),
4164
4187
  errorSink: console.error,
4165
4188
  usageName: "systematic search",
4166
- loadSettings: loadSearchSettingsForCli,
4189
+ ...searchCliInputs(),
4167
4190
  outputSink: console.log
4168
4191
  }).then((status) => {
4169
4192
  process.exitCode = status;
@@ -4225,5 +4248,6 @@ export {
4225
4248
  loadSearchSettingsForCli,
4226
4249
  runCapabilitiesCli,
4227
4250
  runValidateReviewArtifactCli,
4228
- runValidateReviewReturnCli
4251
+ runValidateReviewReturnCli,
4252
+ searchCliInputs
4229
4253
  };