@fro.bot/systematic 3.27.1 → 3.28.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/ATTRIBUTIONS.md +2 -2
- package/HARNESSES.md +24 -11
- package/agents/research/learnings-researcher.md +49 -9
- package/dist/claude-code-search.d.ts +30 -0
- package/dist/claude-code-validator-bin.d.ts +17 -0
- package/dist/cli.d.ts +18 -0
- package/dist/cli.js +335 -108
- package/dist/{index-608preny.js → index-9chxhh5j.js} +1120 -72
- package/dist/index.js +204 -8
- package/dist/lib/agent-resolver.d.ts +8 -2
- package/dist/lib/asset-plan.d.ts +23 -1
- package/dist/lib/config-protected-fields.d.ts +1 -1
- package/dist/lib/config-schema.d.ts +6 -0
- package/dist/lib/config.d.ts +13 -0
- package/dist/lib/main-module.d.ts +30 -0
- package/dist/lib/opencode-v2-commands.d.ts +4 -3
- package/dist/lib/opencode-v2-skills.d.ts +12 -2
- package/dist/lib/opencode-v2.d.ts +1 -0
- package/dist/lib/pi-delegate-session.d.ts +3 -1
- package/dist/lib/pi-delegate-tool.d.ts +12 -1
- package/dist/lib/search-cli.d.ts +52 -0
- package/dist/lib/search-core.d.ts +128 -0
- package/dist/lib/search-corpus.d.ts +105 -0
- package/dist/lib/search-lexical.d.ts +136 -0
- package/dist/lib/search-render.d.ts +69 -0
- package/dist/lib/search-tool.d.ts +53 -0
- package/dist/lib/search-user-config.d.ts +96 -0
- package/dist/pi.js +1155 -77
- package/package.json +3 -3
- package/skills/ce-review/SKILL.md +1 -1
- package/skills/ce-review/references/review-output-template.md +1 -1
- package/skills/ce-review/scripts/validate-review.mjs +1 -3
- package/skills/using-systematic/references/claude-code-profile.md +1 -0
- package/skills/using-systematic/references/opencode-profile.md +1 -0
- package/skills/using-systematic/references/opencode-v2-profile.md +1 -0
- package/skills/using-systematic/references/pi-profile.md +1 -0
package/ATTRIBUTIONS.md
CHANGED
|
@@ -272,7 +272,7 @@ The following is the full Apache License, Version 2.0 text, reproduced here in c
|
|
|
272
272
|
## vercel-labs/agent-browser — Apache-2.0
|
|
273
273
|
|
|
274
274
|
**Source repository:** [`vercel-labs/agent-browser`](https://github.com/vercel-labs/agent-browser)
|
|
275
|
-
**Pinned version:** `v0.39.
|
|
275
|
+
**Pinned version:** `v0.39.4` (npm `agent-browser@0.39.4`)
|
|
276
276
|
**License:** Apache-2.0
|
|
277
277
|
**Copyright:** Copyright 2025 Vercel Inc.
|
|
278
278
|
|
|
@@ -296,7 +296,7 @@ This is fully automated — no human adaptation pass is required, in contrast to
|
|
|
296
296
|
|
|
297
297
|
### Upstream Apache-2.0 license text
|
|
298
298
|
|
|
299
|
-
The following is the full Apache License, Version 2.0 text from `agent-browser@0.39.
|
|
299
|
+
The following is the full Apache License, Version 2.0 text from `agent-browser@0.39.4`, reproduced here in compliance with the license's notice requirements:
|
|
300
300
|
|
|
301
301
|
```
|
|
302
302
|
Apache License
|
package/HARNESSES.md
CHANGED
|
@@ -6,7 +6,7 @@ This is the evidence registry for Systematic's harness-portability work. **Every
|
|
|
6
6
|
|
|
7
7
|
## Capability matrix
|
|
8
8
|
|
|
9
|
-
The
|
|
9
|
+
The five capability rows use the vocabulary in the [OpenCode profile](skills/using-systematic/references/opencode-profile.md#L5-L11), the [OpenCode v2 profile](skills/using-systematic/references/opencode-v2-profile.md#L5-L11), [Pi profile](skills/using-systematic/references/pi-profile.md#L5-L11), and [Claude Code profile](skills/using-systematic/references/claude-code-profile.md#L3-L9). The durable-output search row is Systematic's own tool, not a host primitive, so the Tier 2 columns read "None".
|
|
10
10
|
|
|
11
11
|
| Capability | OpenCode (Tier 1) | Pi (Tier 1) | Claude Code (Tier 1) | Codex CLI (Tier 2) | Gemini CLI (Tier 2) | GitHub Copilot (Tier 2) |
|
|
12
12
|
|---|---|---|---|---|---|---|
|
|
@@ -14,6 +14,7 @@ The four 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 `docs/solutions/` [SR-1][SR-2] | `systematic_search`, also handed to the built-in read-only delegates [SR-1] | `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
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] |
|
|
18
19
|
|
|
19
20
|
`[U]` means the capability was not checked in the supplied research pack. It is not a claim that the capability does not exist.
|
|
@@ -41,7 +42,7 @@ Each v2 mechanism was chosen by a probe against OpenCode 2.2.0 on 2026-10-27. Th
|
|
|
41
42
|
| Native skill tool | Partial | The host tool loads plugin-added skills and refuses denied ones, but takes only an `{id}`, so `$ARGUMENTS` cannot be passed. `systematic_skill` is ported | [OC2-SKILL] |
|
|
42
43
|
| Plugin tool registration | Passed | `ctx.tool.transform` with a JSON Schema input and `options: {codemode: false}` (the default registration is reachable only through Code Mode) | [OC2-TOOL] |
|
|
43
44
|
| Output truncation | Truncates | The host cuts tool output at 2000 lines or 51200 bytes after the plugin's `execute.after` hook sees the full text. The full text is kept by call id and put back in the `context` hook; nothing depends on the marker text | [OC2-TRUNC] |
|
|
44
|
-
| Commands | Passed, with constraints | `ctx.command.transform`; a plugin command receives only the typed text and does its own expansion; routing is not offered to plugin commands, so a command that declares `agent`, `model` or `subtask` is refused; a name that matches a built-in replaces it | [OC2-CMD] |
|
|
45
|
+
| Commands | Passed, with constraints | `ctx.command.transform`; a plugin command receives only the typed text and does its own expansion; routing is not offered to plugin commands, so a bundled command that declares `agent`, `model` or `subtask` is refused, while a discovered skill's fields are dropped with a note; a name that matches a built-in replaces it | [OC2-CMD] |
|
|
45
46
|
| Apply order | Documented | Plugin transforms run first, then user config and discovered sources; `reload()` replays transforms on a fresh editor and does not re-run `setup` | [OC2-ORDER] |
|
|
46
47
|
| Error handling | Documented | A rejected `setup` leaves the plugin unloaded and the host running; a throwing transform disables the whole plugin; a throwing hook breaks the turn. Every callback is guarded, and invalid config rejects `setup` as it throws on v1 | [OC2-ERR] |
|
|
47
48
|
| Project directory | Documented | `ctx.location.directory` is the project directory (the service's working directory is not); each location gets a fresh module instance and its own `setup` | [OC2-TRUST] |
|
|
@@ -68,7 +69,7 @@ Every export/refresh/cleanup operation walks every path component from a scope-a
|
|
|
68
69
|
|
|
69
70
|
The package manifest exposes the extension and skills at `package.json:17-23` (and the packaged personas at `package.json:24-28`), with tests verifying both manifest entries and their packaged paths `tests/unit/package-exports.test.ts:64-84,268-288` [PI-4]. Pi's RPC/JSONL test fixture isolates its environment (`tests/integration/pi.test.ts:349-388`), and the installed runtime exposes environment-specific agent/session directories `node_modules/@earendil-works/pi-coding-agent/dist/config.js:396-398` [PI-5].
|
|
70
71
|
|
|
71
|
-
Pi honors Systematic's disable settings. `src/pi.ts` loads the merged config once at extension start and passes `disabled_skills` to the skill resolver, so a disabled skill is absent from the `systematic_skill` description and parameter hint and fails to load as unknown. The same list reaches Pi's bootstrap, which drops the worktree placement rule when `git-worktree` is disabled; nothing else from the config reaches the bootstrap, so Pi still ignores `bootstrap.enabled` and `bootstrap.file` and carries the rule even when `bootstrap.file` is set [PI-8]. It filters the `systematic_delegate` catalog with `isAgentDisabled`, so a persona disabled by `disabled_agents` (bare name or `category/name`) or by an `agents.<name>.disable` overlay disappears from the tool's description, hint and lookup. The pi-subagents export applies the same predicate, and `tests/unit/disable-parity.test.ts` pins it to what OpenCode's config handler omits [PI-6]. Settings are read at extension start, so a Pi restart applies a change. Pi's `systematic_skill` takes a single `name` parameter and no arguments (`src/pi.ts:
|
|
72
|
+
Pi honors Systematic's disable settings. `src/pi.ts` loads the merged config once at extension start and passes `disabled_skills` to the skill resolver, so a disabled skill is absent from the `systematic_skill` description and parameter hint and fails to load as unknown. The same list reaches Pi's bootstrap, which drops the worktree placement rule when `git-worktree` is disabled; nothing else from the config reaches the bootstrap, so Pi still ignores `bootstrap.enabled` and `bootstrap.file` and carries the rule even when `bootstrap.file` is set [PI-8]. It filters the `systematic_delegate` catalog with `isAgentDisabled`, so a persona disabled by `disabled_agents` (bare name or `category/name`) or by an `agents.<name>.disable` overlay disappears from the tool's description, hint and lookup. The pi-subagents export applies the same predicate, and `tests/unit/disable-parity.test.ts` pins it to what OpenCode's config handler omits [PI-6]. Settings are read at extension start, so a Pi restart applies a change. Pi's `systematic_skill` takes a single `name` parameter and no arguments (`src/pi.ts:223-227`) [PI-3], so a skill that needs arguments, such as `mode:embed` and image paths for `pr-attachments`, reads them from the invoking instruction text instead; OpenCode and Claude Code can also pass skill arguments. Pi's own skill discovery is a separate path: `pi.skills` ships the whole `./skills` directory and Pi's `/skill:name` commands, so those still list and load disabled skills [PI-4], [PI-5]. Pi's skill loading also has no OpenCode-style permission gate — OpenCode's `skill-tool.ts` calls `context.ask({ permission: 'skill', ... })` before returning skill content, and Systematic's Pi tool implementation asks for no confirmation and registers no `tool_call` handler, the event Pi (1.4.0, as installed here) offers extensions for blocking a call (`node_modules/@earendil-works/pi-coding-agent/dist/core/extensions/types.d.ts:1224`) [PI-6]. Those are deliberate honesty boundaries, not implied parity.
|
|
72
73
|
|
|
73
74
|
## Claude Code — Tier 1 shipped adapter
|
|
74
75
|
|
|
@@ -87,6 +88,15 @@ Behavioral enforcement rides a plugin output style (`force-for-plugin: true`), w
|
|
|
87
88
|
|
|
88
89
|
Honest capability boundary: output-style enforcement is real and applies automatically on install, but it operates at the system-prompt level — the same layer as any other instruction the model receives — so it is strong guidance, not a hard gate the model cannot violate. Coverage also differs by surface: plugin-bundled hooks fire app-wide, including in Cowork, while a project-local `.claude/settings.json` hook fires in the Code tab but not in Cowork — state or enforcement reaching Cowork sessions has to come through the plugin, not a project-local hook. The output style is also static and the build reads no user config, so it cannot follow `disabled_skills`: it always carries the worktree placement rule, even when `git-worktree` is disabled [CC-13]. Integration coverage lives in `tests/integration/claude-code.test.ts` [CC-10].
|
|
89
90
|
|
|
91
|
+
## Durable-output search — tool surfaces
|
|
92
|
+
|
|
93
|
+
Systematic ships its own search over `docs/solutions/`. 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, ranks lexically, resolves the solution lifecycle 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.
|
|
94
|
+
|
|
95
|
+
Evidence tiers differ by host, and this file does not claim more than the tests do:
|
|
96
|
+
- **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
|
+
- **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
|
+
- **No real-host check:** the Pi tool and the Claude Code bin have none. Pi is covered by the host-free adapter tests and the Pi delegate tests; the Claude Code bin by its foreign-directory bundle run and the output-style assertion in `tests/integration/claude-code.test.ts` [SR-3].
|
|
99
|
+
|
|
90
100
|
## Worktree placement rule — bootstrap paths
|
|
91
101
|
|
|
92
102
|
One short rule ships in the shared bootstrap: create a worktree at `.worktrees/<branch>` under the main repository root with the `git-worktree` skill's script, and follow a different location or tool when the user or a project instruction names one. The script (`skills/git-worktree/scripts/worktree-manager.sh`) is small and non-interactive: `create`, `list`, `switch`, `copy-env` and `cleanup`, with exit codes 0 ok, 1 error, 2 usage and 3 refused, and no stdin reads. `create` places the worktree at `.worktrees/<branch>` under the main root, writes `.worktrees/.gitignore` and never edits the root `.gitignore`, and fails closed on a bare, separate-git-dir or submodule layout; `cleanup` reports and removes only named clean worktrees [WT-2]. The rule lives in `skills/using-systematic/references/worktree-placement.md` and holds no harness identifiers [WT-1]. Each adapter composes it differently:
|
|
@@ -196,7 +206,7 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
|
|
|
196
206
|
|
|
197
207
|
## Evidence registry
|
|
198
208
|
|
|
199
|
-
- **OC-P** — [OpenCode profile](skills/using-systematic/references/opencode-profile.md#
|
|
209
|
+
- **OC-P** — [OpenCode profile](skills/using-systematic/references/opencode-profile.md#L5-L11).
|
|
200
210
|
- **OC-1** — cloned OpenCode source, `.slim/clonedeps/repos/anomalyco__opencode/packages/opencode/src/tool/task.ts:24-62`.
|
|
201
211
|
- **OC-2** — cloned OpenCode source, `.slim/clonedeps/repos/anomalyco__opencode/packages/core/src/tool/question.ts:10-25`.
|
|
202
212
|
- **OC-3** — cloned OpenCode source, `.slim/clonedeps/repos/anomalyco__opencode/packages/core/src/tool/todowrite.ts:1-10`.
|
|
@@ -205,7 +215,7 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
|
|
|
205
215
|
- **OC-6** — `ARCHITECTURE.md:217-223` (invariant 2) and `agents/`.
|
|
206
216
|
- **OC-7** — `src/lib/asset-plan.ts:274-380` (a model reaches an agent only through `applyAgentOverlays`, `applyAgentOverlayPass` and `applyRoutingModel`, all driven by user-owned overlays); `tests/unit/config-handler.test.ts:1173-1330` (overlay model emitted, `model: null` restores inheritance, native same-name replacement stays model-free).
|
|
207
217
|
- **OC-8** — `src/lib/opencode-v1.ts:73-79` (v1: the loaded config and `composeBootstrapContent`; the rule is always supplied and the gate lives in `getBootstrapContent`); `src/lib/bootstrap.ts:144-160` (`readWorktreePlacementRule`), `:244-253` (`bootstrap.enabled` and `bootstrap.file` return before the rule is composed), `:265-269` (the rule is omitted when `disabled_skills` contains `git-worktree`), `:279` (placement after the usage template and before the profile), `:291-314` (`composeBootstrapContent`, shared by v1 and v2); `tests/unit/bootstrap.test.ts:1025-1227` (real `loadConfig`: default, `git-worktree` disabled, another skill disabled, qualified name rejected, `bootstrap.enabled: false`, existing and missing `bootstrap.file`); `tests/unit/plugin.test.ts:1473-1610` (real v1 plugin init).
|
|
208
|
-
- **OC2-PROFILE** — [OpenCode v2 profile](skills/using-systematic/references/opencode-v2-profile.md#L5-
|
|
218
|
+
- **OC2-PROFILE** — [OpenCode v2 profile](skills/using-systematic/references/opencode-v2-profile.md#L5-L11). Tool names and arguments: Local probe, OpenCode 2.2.0, 2026-10-27, from the tool list of a real request (`edit`, `glob`, `grep`, `question`, `read`, `shell`, `skill`, `subagent`, `webfetch`, `websearch`, `write`, `execute`): `subagent` takes `agent`, `description`, `prompt`, `model`, `sessionID` and `background`; `question` takes `questions` with `question`, `header`, `options` and `multiple`. CI covers the `subagent` call: CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0), `tests/integration/opencode-v2.test.ts` › "a subagent request carries the bootstrap once, and so does the parent request that follows it". `question` has no CI test.
|
|
209
219
|
- **OC2-LOADER** — OpenCode v1 1.18.28, 1.18.29, 1.19.4 and v2 2.1.4, 2.2.0, 2026-10-27. The object default `{id, setup, server}` loads on all five. A v1 host calls `server(input)` and then `setup(ctx)` in the same process, with a reduced context of 9 keys and no `location` or `session`; a v2 host never calls `server`. v2 2.1.4 drops a function default with no log line, and 2.2.0 logs a warning. Tarball config forms fail on v1, so installs go through `npm install <tarball>` and load the installed directory. Local probe for the version comparison. CI covers the 2.2.0 load: CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0), `tests/integration/opencode-v2.test.ts` › "the packed plugin loads, setup runs once and stderr carries nothing unexpected"; the v1 loads: CI jobs `Host Contract v1 floor` and `Host Contract v1 current`, `tests/integration/opencode-v1.test.ts` › "packaged plugin loads, warns on a removed disabled_skills name, and exposes a compliant catalog"; the bridge no-op: `tests/unit/opencode-v2.test.ts` › "default export wiring" › "setup does nothing for the reduced context a v1 host passes".
|
|
210
220
|
- **OC2-HOST** — Local probe, OpenCode 2.2.0, 2026-10-27. Isolation takes `HOME`, the four `XDG_*` variables, `OPENCODE_CONFIG_DIR` and `TMPDIR`; a managed config under `/Library` on macOS is read and cannot be isolated. One-shot runs use `run --standalone`; the default `run` starts a detached shared service on port 49374. The remote client is `@opencode/client` (`OpenCode.make`), not `@opencode/sdk`, which has only the embedded `create`. The plugin runs in the service process under a compiled Bun 1.4.4, with the home directory as its working directory. The CLI install needs `npm install --dangerously-allow-all-scripts` on npm 12. CI uses this recipe: the host install step and `tests/integration/fixtures/opencode-host.ts` in CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0).
|
|
211
221
|
- **OC2-AGENT** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "the bundled agents appear in the agent list with their v1 description and prompt" and "a user agent with the same id in config keeps the user system prompt"; `tests/unit/opencode-v2.test.ts` › "agents installer" › "replaying the transform on a fresh editor yields the same single agent set". Local probe, OpenCode 2.2.0, 2026-10-27: an extra property set in a transform is visible to later plugins in the same replay and gone from `agent.list`, so no ownership marker survives; an agent's `model` applies only when the session names no model; a session whose agent is later unregistered fails its next turn with `Session.AgentNotFoundError`.
|
|
@@ -215,21 +225,21 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
|
|
|
215
225
|
- **OC2-SKILL** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "the native skill tool sees the registered bundled skills, and not a disabled one" and "an on-disk skill with the same id replaces the registered one in the native tool, with no diagnostic". Local probe, OpenCode 2.2.0, 2026-10-27: the native tool refuses denied skills per agent, including in subagents; `<available_skills>` lists only the skills the agent may load; the permission resource is the skill id; an inline skill's base directory is `dirname(path)`; the tool takes only `{id}`, so `$ARGUMENTS` stays literal.
|
|
216
226
|
- **OC2-TOOL** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "systematic_skill is offered to the model and loads an enabled skill by bare and prefixed name", "arguments are substituted into the skill the model receives" and "a skill in disabled_skills is refused by systematic_skill". Local probe, OpenCode 2.2.0, 2026-10-27: a plugin tool takes a JSON Schema input; the default registration is reachable only through Code Mode, and `options: {codemode: false}` makes it a direct tool (`pinned: true` did not).
|
|
217
227
|
- **OC2-TRUNC** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "a skill above the host output limit reaches the model in full on the continuation request and later turns" and "a discovered project skill above the host output limit reaches the model whole as a command, with its arguments". Local probe, OpenCode 2.2.0, 2026-10-27: tool output over 2000 lines or 51200 bytes is cut after the plugin's `execute.after` hook has seen the full text, with a trailing `[showing lines a-b of N; full output saved to <path>]` part; the bundled `ce-review`, `ce-plan` and `ce-compound-refresh` skills are over the limit. Restoration matches the tool result by call id and does not read the marker. v2 has no runtime prune placeholder: `[Old tool result content cleared]` exists only in the v1-to-v2 migration converter, so v1's compacted-result restore has no v2 counterpart.
|
|
218
|
-
- **OC2-CMD** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "a command with $ARGUMENTS reaches the model expanded, on the invoking session as it is", "a command that declares agent is refused with a message and nothing is prompted" (and the same for `model` and `subtask`), "a !-backtick block in a command stays literal text in the prompt", "the command names and descriptions match the v1 set" and "a discovered skill named like a built-in command is skipped and the built-in stays". Local probe, OpenCode 2.2.0, 2026-10-27: a plugin command receives `{sessionID, prompt: {text, files, agents, skills}, delivery}` with the raw typed text; `prompt` takes no agent or model; `switchAgent` to an unregistered agent succeeds and the next turn fails; a plugin command named like a built-in replaces it; the command editor has only `add`; a throwing `execute` makes `session.command` reject with `CommandExecutionError` and leaves the plugin loaded. A session created with no agent or model reports neither from `session.get`, even after a turn; it runs on the host's default agent (`build` here) and the model `model.default` returns. `switchAgent` and `switchModel` make a session's choice explicit and persistent, and no call clears it; the host also reads a session's agent and model for every model request, so a switch made during a running turn changes that turn's later requests. Because of those three facts a plugin command cannot route without leaving the user's session changed or racing a running turn, so Systematic does not route: a command whose plan declares `agent`, `model` or `subtask` is refused with a message that points to an OpenCode command in Markdown or JSON. Only bundled skills can
|
|
228
|
+
- **OC2-CMD** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "a command with $ARGUMENTS reaches the model expanded, on the invoking session as it is", "a command that declares agent is refused with a message and nothing is prompted" (and the same for `model` and `subtask`), "a !-backtick block in a command stays literal text in the prompt", "the command names and descriptions match the v1 set" and "a discovered skill named like a built-in command is skipped and the built-in stays". Local probe, OpenCode 2.2.0, 2026-10-27: a plugin command receives `{sessionID, prompt: {text, files, agents, skills}, delivery}` with the raw typed text; `prompt` takes no agent or model; `switchAgent` to an unregistered agent succeeds and the next turn fails; a plugin command named like a built-in replaces it; the command editor has only `add`; a throwing `execute` makes `session.command` reject with `CommandExecutionError` and leaves the plugin loaded. A session created with no agent or model reports neither from `session.get`, even after a turn; it runs on the host's default agent (`build` here) and the model `model.default` returns. `switchAgent` and `switchModel` make a session's choice explicit and persistent, and no call clears it; the host also reads a session's agent and model for every model request, so a switch made during a running turn changes that turn's later requests. Because of those three facts a plugin command cannot route without leaving the user's session changed or racing a running turn, so Systematic does not route: a command whose plan declares `agent`, `model` or `subtask` is refused with a message that points to an OpenCode command in Markdown or JSON. Only bundled skills can reach that refusal, and no bundled skill declares those fields. A discovered skill is never refused: its fields are dropped with one note per skill (`tests/unit/opencode-v2-commands.test.ts` › "a discovered skill that declares routing"; `tests/integration/opencode-v2.test.ts` › "a discovered skill that declares routing is not refused"). On OpenCode v1 the same skill's `subtask` passes through, `agent` passes only for a subtask that names a known agent, and `model` passes only as `provider/model`; anything else is dropped with a warning (`tests/unit/config-handler.test.ts` › "routing fields").
|
|
219
229
|
- **OC2-ORDER** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "a user agent with the same id in config keeps the user system prompt" and "an on-disk skill with the same id replaces the registered one in the native tool, with no diagnostic" (user config and disk sources win over plugin transforms); `tests/unit/opencode-v2.test.ts` › "agents installer" › "replaying the transform on a fresh editor yields the same single agent set" (replay on a fresh editor). Local probe, OpenCode 2.2.0, 2026-10-27: plugins apply in config order and see earlier plugins' edits; `reload()` replays transforms and does not re-run `setup`.
|
|
220
230
|
- **OC2-ERR** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "invalid systematic.json fails the plugin load, is logged, and the session still answers" and "a command that declares %s is refused with a message and nothing is prompted" (a `systematic:` diagnostic reaches the server's standard error); `tests/unit/opencode-v2.test.ts` › "createSafeGuard". Local probe, OpenCode 2.2.0, 2026-10-27: a rejected `setup` leaves the plugin unloaded with one `WARN failed to load plugin` and the host and other plugins unaffected; a throwing transform disables the whole plugin; a throwing `prompt` hook returns HTTP 500; a throwing `context` hook fails the turn; a throwing `execute.before` or `execute.after` turns the tool result into an error; `console.error` reaches only the server's standard error.
|
|
221
231
|
- **OC2-TRUST** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "the packed plugin loads, setup runs once and stderr carries nothing unexpected" and every test that writes a project `.opencode/systematic.json`, such as "a skill in disabled_skills is refused by systematic_skill". Local probe, OpenCode 2.2.0, 2026-10-27: `ctx.location.directory` is the project directory and `ctx.location.project` has `id`, `directory` and `canonical`; one shared service creates one plugin instance per location, with a fresh module instance and its own `setup`; project config plugins load with no trust prompt.
|
|
222
232
|
- **OC2-TODO** — Binary strings only: no live request showed the tool, and no CI test covers it. Local probe, OpenCode 2.2.0, 2026-10-27, reading strings in the 2.2.0 CLI binary: a `todowrite` tool with input `todos: [{content, status}]` (`status` is `pending`, `in_progress`, `completed` or `cancelled`) and an experimental config option `todo` described as "Enable the experimental todowrite tool. Defaults to false". The tool list of the probe requests had no todo tool, so whether the tool appears with the option on was not observed. The v2 profile therefore marks task tracking conditional.
|
|
223
|
-
- **PI-P** — [Pi profile](skills/using-systematic/references/pi-profile.md#
|
|
233
|
+
- **PI-P** — [Pi profile](skills/using-systematic/references/pi-profile.md#L5-L11).
|
|
224
234
|
- **PI-1** — `src/lib/pi-delegate-tool.ts:14-18,245-249,279-291`.
|
|
225
235
|
- **PI-2** — [Pi profile](skills/using-systematic/references/pi-profile.md#L5-L8).
|
|
226
|
-
- **PI-3** — `src/pi.ts:
|
|
236
|
+
- **PI-3** — `src/pi.ts:218-237`.
|
|
227
237
|
- **PI-4** — `package.json:17-23`; `tests/unit/package-exports.test.ts:64-84,268-288`.
|
|
228
238
|
- **PI-5** — `tests/integration/pi.test.ts:349-388`; installed Pi source `node_modules/@earendil-works/pi-coding-agent/dist/config.js:396-398`.
|
|
229
|
-
- **PI-6** — `src/pi.ts:
|
|
239
|
+
- **PI-6** — `src/pi.ts:182-187` (merged `disabled_skills` passed to the skill resolver); `src/pi.ts:250-263` (`systematic_delegate` catalog filtered with `isAgentDisabled`); `src/lib/config.ts:2103-2115` (`isAgentDisabled`); `src/lib/pi-subagents-export.ts:857-893` (`generateEntries` applies it to the export); `tests/unit/disable-parity.test.ts` (parity with OpenCode's config handler); OpenCode's contrasting permission gate at `src/lib/skill-tool.ts:198-203`.
|
|
230
240
|
- **PI-7** — `package.json:24-28` (the `pi.subagents.agents` declaration); `scripts/build-pi-package-agents.ts` (writes `dist/pi-subagents/agents/` at build time); `tests/unit/package-exports.test.ts:76-83,289-344` (manifest key, `pi-package` keyword, packed files byte-equal to the fixtures); `tests/integration/pi.test.ts:1550-1652` (real Pi host: dispatch from the package at project and global scope, the `packageAgents: false` fallback to `general-purpose`, and a local file outranking the packaged one); `node_modules/@tintinweb/pi-subagents/dist/package-resources.js:90,327-341,432` (which packages are read, trust), `node_modules/@tintinweb/pi-subagents/dist/custom-agents.js:36-39,59-64` (precedence), `node_modules/@tintinweb/pi-subagents/dist/settings.js:133-135` (`packageAgents` gate), `node_modules/@tintinweb/pi-subagents/dist/index.js:361,1187` (registry setter and background default), `node_modules/@tintinweb/pi-subagents/dist/agent-types.js:65` (`registerAgents`); `src/lib/pi-subagents-export.ts` (export lifecycle, manifest, rollback, stale-file removal and retention); `src/lib/pi-subagents-personas.ts` (curated persona list, compatibility screening); `src/cli.ts:1080-1106` (CLI surface: `pi-subagents preview|export|refresh|cleanup`). Tested interop contract: pi-subagents 0.22.0 on Pi 1.3.0.
|
|
231
|
-
- **PI-8** — `src/pi.ts:
|
|
232
|
-
- **CC-P** — [Claude Code profile](skills/using-systematic/references/claude-code-profile.md#
|
|
241
|
+
- **PI-8** — `src/pi.ts:189-204` (rule supplied, `piConfig.disabled_skills` the only config passed); `src/lib/bootstrap.ts:172-198` (`computeBootstrapContentSafe` keeps `bootstrap.enabled` and `bootstrap.file` at their defaults); `tests/unit/pi.test.ts:1317-1447` (real extension init: default, `git-worktree` disabled, `bootstrap.file` set, `bootstrap.enabled: false`, foreign prompt text kept and not doubled).
|
|
242
|
+
- **CC-P** — [Claude Code profile](skills/using-systematic/references/claude-code-profile.md#L3-L9).
|
|
233
243
|
- **CC-1** — [Claude Code skills](https://code.claude.com/docs/en/skills) (`context: fork`); name-based subagent dispatch verified via `claude-code/agents/` and the plugin's invocation convention [CC-9].
|
|
234
244
|
- **CC-2** — [Claude Code tools reference](https://code.claude.com/docs/en/tools-reference).
|
|
235
245
|
- **CC-3** — [Claude Code tools reference](https://code.claude.com/docs/en/tools-reference).
|
|
@@ -260,3 +270,6 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
|
|
|
260
270
|
- **PA-3** — `tests/unit/pr-attachments-dry-run.test.ts` (the skill's fenced blocks run offline against a temporary repository and a local bare remote, with the real helper).
|
|
261
271
|
- **WT-1** — `skills/using-systematic/references/worktree-placement.md` (the rule text); `tests/unit/bootstrap.test.ts:1043-1092` (exact text, at most 350 bytes, names `git-worktree` and `.worktrees/<branch>`, keeps the raw-add ban and the carve-out sentence, no harness identifiers, no `CLAUDE.md` literal).
|
|
262
272
|
- **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.
|
|
273
|
+
- **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).
|
|
274
|
+
- **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).
|
|
275
|
+
- **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 live Claude Code session has run the bin or the Pi tool.
|
|
@@ -7,10 +7,12 @@ temperature: 0.2
|
|
|
7
7
|
|
|
8
8
|
You are an expert institutional knowledge researcher specializing in efficiently surfacing relevant documented solutions from the team's knowledge base. Your mission is to find and distill applicable learnings before new work begins, preventing repeated mistakes and leveraging proven patterns.
|
|
9
9
|
|
|
10
|
-
## Search Strategy (
|
|
10
|
+
## Search Strategy (Search First, Grep Fallback)
|
|
11
11
|
|
|
12
12
|
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.
|
|
13
13
|
|
|
14
|
+
Try the search tool once (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.
|
|
15
|
+
|
|
14
16
|
### Step 0: Discover What Exists
|
|
15
17
|
|
|
16
18
|
List `docs/solutions/` with a directory listing tool.
|
|
@@ -27,8 +29,40 @@ From the feature/task description, identify:
|
|
|
27
29
|
- **Problem indicators**: e.g., "slow", "error", "timeout", "memory"
|
|
28
30
|
- **Component types**: e.g., "database", "api", "background job", "cli"
|
|
29
31
|
|
|
32
|
+
### Step 1b: Search First (When a Search Tool Exists)
|
|
33
|
+
|
|
34
|
+
**Detect the tool once.**
|
|
35
|
+
- **OpenCode and Pi:** check whether a `systematic_search` tool is in your tool list.
|
|
36
|
+
- **Hosts that ship a command instead of a tool (the plugin bundle's `bin/`):** run `command -v systematic-search`. A printed path means the tool exists.
|
|
37
|
+
- If there is no such tool, go to Step 2 and use the grep path.
|
|
38
|
+
|
|
39
|
+
**Call it once**, with the problem description as the query and `kind` set to `solution`. With the tool, call `systematic_search({ query: "<description>", kind: "solution" })`. With the command, run `systematic-search --kind solution -- '<description>'` with single quotes removed from the description first. Write the query as symptoms, error text, module names and the topic, as a person would type them. Use the default limit.
|
|
40
|
+
|
|
41
|
+
**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.
|
|
42
|
+
|
|
43
|
+
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.
|
|
44
|
+
|
|
45
|
+
| Reply | Path |
|
|
46
|
+
|-------|------|
|
|
47
|
+
| 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. |
|
|
48
|
+
| 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. |
|
|
49
|
+
| 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. |
|
|
50
|
+
| 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. |
|
|
51
|
+
| The reply says `No project directory is available` | Grep path. Go to Step 2. |
|
|
52
|
+
| The reply says search is disabled, starts with `Error:`, or the call fails | Grep path. Go to Step 2. |
|
|
53
|
+
|
|
54
|
+
The grep path keeps its OR patterns for synonyms. A zero-hit search does not add a new synonym pass.
|
|
55
|
+
|
|
56
|
+
**On the search path:**
|
|
57
|
+
- The hits are already ranked and already resolved for lifecycle. Do not run Step 4's resolution again.
|
|
58
|
+
- A hit with a `Supersedes:` line is the successor that stands in for the docs it lists. Copy `Supersedes:` and `Caution:` lines literally into the entry, including `Caution: successor unresolved` on a superseded doc whose successor does not resolve.
|
|
59
|
+
- Read a hit's `Status` and lifecycle lines from the reply. Take the other frontmatter fields in Step 5.
|
|
60
|
+
- In overlap mode, you already dropped the doc under comparison. Compare the docs its `Supersedes:` line listed, as well as the remaining hits. The search rank and hit count never set the `score=` value. Judge the five dimensions for each remaining doc as described under Output Format.
|
|
61
|
+
|
|
30
62
|
### Step 2: Category-Based Narrowing (Optional but Recommended)
|
|
31
63
|
|
|
64
|
+
The grep path starts here.
|
|
65
|
+
|
|
32
66
|
If the feature type is clear, narrow the search to the category directories from Step 0 whose names fit it. Match by name. For example, performance work fits a directory with `performance` in its name, and a security change fits one with `security` in its name. Several directories can fit. When the type is unclear, or no directory fits, search `docs/solutions/` as a whole.
|
|
33
67
|
|
|
34
68
|
### Step 3: Content-Search Pre-Filter (Critical for Efficiency)
|
|
@@ -67,6 +101,8 @@ If the Step 0 listing shows a `patterns/` directory, list it. If `critical-patte
|
|
|
67
101
|
|
|
68
102
|
### Step 4: Read Lifecycle Fields and Resolve
|
|
69
103
|
|
|
104
|
+
This step is the grep path. On the search path, search has already resolved the lifecycle, so skip the content search and the successor walk below.
|
|
105
|
+
|
|
70
106
|
Run ONE content search across all of `docs/solutions/` to find which files mention the lifecycle fields, returning file paths only:
|
|
71
107
|
|
|
72
108
|
```
|
|
@@ -83,7 +119,7 @@ Then resolve every candidate before scoring:
|
|
|
83
119
|
|--------------------|--------|
|
|
84
120
|
| Missing, `active`, or any value you do not recognize | Active. Treat as a normal candidate. |
|
|
85
121
|
| `stale` | Keep it, and give it a `Caution:` line (see Output Format). |
|
|
86
|
-
| `superseded` | Replace it with its successor, if the successor resolves. Otherwise
|
|
122
|
+
| `superseded` | Replace it with its successor, if the successor resolves. Otherwise keep the superseded doc and give it `Caution: successor unresolved`. |
|
|
87
123
|
|
|
88
124
|
**Resolving a successor.** Only a repo-root path counts: a value that starts with `docs/solutions/`, ends in `.md`, contains no `..` segment, is not a `README.md`, is not under `_archived/`, and names a file that exists. A bare filename, a relative path, an empty value, a list, a missing file and any other form are all unresolvable. Do not guess.
|
|
89
125
|
|
|
@@ -98,11 +134,11 @@ Then resolve every candidate before scoring:
|
|
|
98
134
|
- A superseded candidate with a resolvable successor is never returned. Return the successor in its place, labelled with a `Supersedes:` line (see Output Format). The successor does not need to match the keywords itself, because it stands in for a doc that did.
|
|
99
135
|
- If the successor is `stale`, it also gets a `Caution:` line.
|
|
100
136
|
- Several superseded docs that resolve to the same successor return that successor once. Its `Supersedes:` line lists all of them. If the successor is also a candidate in its own right, merge the two into one entry.
|
|
101
|
-
- A superseded candidate with an unresolvable successor is
|
|
137
|
+
- A superseded candidate with an unresolvable successor is returned itself, at its own rank, with the line `Caution: successor unresolved`. Nothing is dropped. A successor that is missing, fails the form rule, forms a cycle or lies past the hop cap is unresolvable.
|
|
102
138
|
|
|
103
139
|
### Step 5: Read Frontmatter of Candidates Only
|
|
104
140
|
|
|
105
|
-
For each remaining candidate (including successors), read the frontmatter:
|
|
141
|
+
For each remaining candidate (including successors, and the hits on the search path), read the frontmatter:
|
|
106
142
|
|
|
107
143
|
```bash
|
|
108
144
|
# Read frontmatter only (limit to first 30 lines)
|
|
@@ -118,7 +154,7 @@ Extract these fields from the YAML frontmatter:
|
|
|
118
154
|
- **tags**: Searchable keywords
|
|
119
155
|
- **severity**: critical, high, medium, low
|
|
120
156
|
|
|
121
|
-
`status`, `superseded_by` and `stale_reason` come from the Step 4 frontmatter read, not from search lines. Values for these fields are whatever the docs use. Do not validate them against a fixed list.
|
|
157
|
+
On the grep path, `status`, `superseded_by` and `stale_reason` come from the Step 4 frontmatter read, not from search lines. On the search path they come from the hit's own lines. Values for these fields are whatever the docs use. Do not validate them against a fixed list.
|
|
122
158
|
|
|
123
159
|
### Step 6: Score and Rank Relevance
|
|
124
160
|
|
|
@@ -149,7 +185,7 @@ Only for files that pass the filter (strong or moderate matches), read the compl
|
|
|
149
185
|
|
|
150
186
|
### Step 8: Return Distilled Summaries
|
|
151
187
|
|
|
152
|
-
For each relevant document, return a summary in this format. `Supersedes:` and `Caution:` are optional; include each only when it applies. `Supersedes:` lists each retired doc as a repo-root path, comma-separated. `Caution:` says the doc is marked stale and quotes its `stale_reason` from its frontmatter if it has one.
|
|
188
|
+
For each relevant document, return a summary in this format. `Supersedes:` and `Caution:` are optional; include each only when it applies. `Supersedes:` lists each retired doc as a repo-root path, comma-separated. `Caution:` says the doc is marked stale and quotes its `stale_reason` from its frontmatter if it has one. On a superseded doc whose successor does not resolve, the line is exactly `Caution: successor unresolved`.
|
|
153
189
|
|
|
154
190
|
```markdown
|
|
155
191
|
### [Title from document]
|
|
@@ -175,7 +211,6 @@ Structure your findings as:
|
|
|
175
211
|
- **Keywords Used**: [tags, modules, symptoms searched]
|
|
176
212
|
- **Files Scanned**: [X total files]
|
|
177
213
|
- **Relevant Matches**: [Y files]
|
|
178
|
-
Skipped: superseded, successor unresolved: <path> <- one line per such doc; omit when none
|
|
179
214
|
|
|
180
215
|
### Critical Patterns
|
|
181
216
|
[Matching patterns from critical-patterns.md. Include this section only when that file exists.]
|
|
@@ -205,12 +240,16 @@ Overlap: <repo-root path> | problem=match|no-match root_cause=match|no-match sol
|
|
|
205
240
|
[If no relevant learnings found, explicitly state this. Say so when docs/solutions/ does not exist.]
|
|
206
241
|
```
|
|
207
242
|
|
|
208
|
-
**Overlap lines.** Include the Overlap Assessment section only when the caller asks for an overlap assessment against a new doc. Write one `Overlap:` line per compared doc. Judge each of the five dimensions (problem statement, root cause, solution approach, referenced files, prevention rules) as `match` or `no-match` first, then count the matches. The score follows the count: 4-5 is High, 2-3 is Moderate, 0-1 is Low. If the score you would write disagrees with the count, the count wins.
|
|
243
|
+
**Overlap lines.** Include the Overlap Assessment section only when the caller asks for an overlap assessment against a new doc. Write one `Overlap:` line per compared doc. Judge each of the five dimensions (problem statement, root cause, solution approach, referenced files, prevention rules) as `match` or `no-match` first, then count the matches. The score follows the count: 4-5 is High, 2-3 is Moderate, 0-1 is Low. If the score you would write disagrees with the count, the count wins. A search score, rank or hit count never maps to High, Moderate or Low. Never compare a doc with itself: leave the doc under comparison out of the lines.
|
|
209
244
|
|
|
210
245
|
## Efficiency Guidelines
|
|
211
246
|
|
|
247
|
+
The rules below about content search, patterns, synonyms and narrowing apply to the grep path. On the search path, the hits replace them.
|
|
248
|
+
|
|
212
249
|
**DO:**
|
|
213
250
|
- List `docs/solutions/` first and work from the directories that exist
|
|
251
|
+
- Try the search tool once, when it exists, before any grep step
|
|
252
|
+
- Take the grep path when search finds nothing, is disabled, errors or does not exist
|
|
214
253
|
- Use the native content-search tool to pre-filter files BEFORE reading any content (critical for 100+ files)
|
|
215
254
|
- Run multiple content searches in PARALLEL for different keywords
|
|
216
255
|
- Include `title:` in search patterns - often the most descriptive field
|
|
@@ -236,7 +275,8 @@ Overlap: <repo-root path> | problem=match|no-match root_cause=match|no-match sol
|
|
|
236
275
|
- Proceed with >25 candidates without narrowing first
|
|
237
276
|
- Read every file in full (wasteful)
|
|
238
277
|
- Return raw document contents (distill instead)
|
|
239
|
-
- Return a superseded doc. Return its successor,
|
|
278
|
+
- Return a superseded doc whose successor resolves. Return its successor. If the successor does not resolve, return the superseded doc with `Caution: successor unresolved`.
|
|
279
|
+
- Run the grep steps after a search that returned hits, or call the search tool more than once
|
|
240
280
|
- Follow a `superseded_by` that is not a repo-root `docs/solutions/` path, and never follow more than 5 hops
|
|
241
281
|
- Include tangentially related learnings (focus on relevance)
|
|
242
282
|
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Entry point of the `systematic-search` bin that ships in the plugin bundle.
|
|
3
|
+
* `scripts/build-claude-code-plugin.ts` bundles it into one
|
|
4
|
+
* self-contained file, and the foreign-directory run in
|
|
5
|
+
* `tests/unit/claude-code-search.test.ts` proves that bundle runs under `node`
|
|
6
|
+
* with no `node_modules`.
|
|
7
|
+
*
|
|
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.
|
|
13
|
+
*
|
|
14
|
+
* Import rule: nothing here may import `config.ts` or `config-schema.ts`.
|
|
15
|
+
* The bundle would then carry the config loader and its UMD jsonc build, which
|
|
16
|
+
* crashes when run from a foreign directory. The bin reaches zod only through
|
|
17
|
+
* `search-user-config.ts`.
|
|
18
|
+
*/
|
|
19
|
+
import { type UserLevelConfigDirOptions } from './lib/search-user-config.js';
|
|
20
|
+
interface ClaudeCodeSearchOptions {
|
|
21
|
+
/** Query words and flags, as `systematic search` takes them after the command. */
|
|
22
|
+
readonly argv: readonly string[];
|
|
23
|
+
readonly cwd?: string;
|
|
24
|
+
/** Override the config directories. Tests use this; the bin reads the real ones. */
|
|
25
|
+
readonly userLevel?: UserLevelConfigDirOptions;
|
|
26
|
+
readonly outputSink?: (message: string) => void;
|
|
27
|
+
readonly errorSink?: (message: string) => void;
|
|
28
|
+
}
|
|
29
|
+
export declare function runClaudeCodeSearch(options: ClaudeCodeSearchOptions): Promise<number>;
|
|
30
|
+
export {};
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Entry point of the `systematic-validate-review-artifact` bin that ships in
|
|
3
|
+
* the plugin bundle. `scripts/build-claude-code-plugin.ts` bundles this
|
|
4
|
+
* file, not `claude-code-validator.ts`.
|
|
5
|
+
*
|
|
6
|
+
* The entry guard lives here and not in `claude-code-validator.ts` on purpose.
|
|
7
|
+
* `ce-review-validator.ts` imports `runClaudeCodeValidator` from that module
|
|
8
|
+
* and is bundled into the committed `validate-review.mjs`. In a bundle every
|
|
9
|
+
* module shares one `import.meta.url`, so a realpath guard inside
|
|
10
|
+
* `claude-code-validator.ts` would fire in that bundle as well and run the
|
|
11
|
+
* validator a second time next to `ce-review-validator.ts`'s own entry. The
|
|
12
|
+
* old `import.meta.main` check avoided this only because Bun's bundler folds it
|
|
13
|
+
* to false in every module but the entry. Keeping the guard in a file nothing
|
|
14
|
+
* imports restores that property without relying on a Bun-only global, which
|
|
15
|
+
* Node gained only in 24.2.
|
|
16
|
+
*/
|
|
17
|
+
export {};
|
package/dist/cli.d.ts
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
import { type CapabilityClock, type CapabilityOutputSink, type ConfigObservationMetadata } from './lib/capability-snapshot.js';
|
|
3
|
+
import { type LoadConfigOptions } from './lib/config.js';
|
|
3
4
|
import { type ReadChunk } from './lib/review-return-validator.js';
|
|
5
|
+
import { type SearchCliSettingsLoad } from './lib/search-cli.js';
|
|
4
6
|
export interface CapabilityCliRoots {
|
|
5
7
|
readonly agentsRoot: string;
|
|
6
8
|
readonly cwd: string;
|
|
@@ -34,4 +36,20 @@ interface ValidateReviewReturnCliOptions {
|
|
|
34
36
|
readonly errorSink?: (message: string) => void;
|
|
35
37
|
}
|
|
36
38
|
export declare function runValidateReviewReturnCli(options: ValidateReviewReturnCliOptions): number;
|
|
39
|
+
/**
|
|
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.
|
|
47
|
+
*
|
|
48
|
+
* The full loader drops a whole file that fails validation, so a valid
|
|
49
|
+
* `search.enabled: false` next to a bad sibling key would be lost. When a
|
|
50
|
+
* source is invalid, or the load throws, the settings come from the user-level
|
|
51
|
+
* reader instead, which validates the `search` block on its own (the same
|
|
52
|
+
* reader the `systematic-search` bin uses), so the opt-out still holds. Never throws.
|
|
53
|
+
*/
|
|
54
|
+
export declare function loadSearchSettingsForCli(startDir: string, configOptions?: LoadConfigOptions): SearchCliSettingsLoad;
|
|
37
55
|
export {};
|