@fro.bot/systematic 3.28.1 → 3.29.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 `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
+ | 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) |
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.
@@ -56,7 +56,7 @@ Pi's profile records degraded or unavailable native capabilities and explicit fa
56
56
 
57
57
  Optional mature delegation is available via [pi-subagents](https://github.com/tintinweb/pi-subagents). It is outside Systematic's bounded-delegate guarantees and governed by pi-subagents' own configuration. Tested against pi-subagents 0.22.0 on Pi 1.3.0; versions outside the tested range are unsupported but nonfatal. pi-subagents reaches Systematic's personas by two paths:
58
58
 
59
- - **Installed package.** The package declares `pi.subagents.agents` at `package.json:24-28`, pointing at `dist/pi-subagents/agents/`. `scripts/build-pi-package-agents.ts` writes that directory at build time from the same render the export uses, so the 29 curated personas it ships are byte-equal to the committed fixtures (`tests/unit/package-exports.test.ts:289-344`) [PI-7]. pi-subagents 0.22 is the first release that reads package-declared agents. It reads them from the packages in Pi's `settings.json` `packages[]`, global and project, and never from `node_modules`, because the only scan is Pi's own configured-package list (`node_modules/@tintinweb/pi-subagents/dist/package-resources.js:327-341`). It sees a project-scope package only after the project is trusted: the trust flag starts `false` (`node_modules/@tintinweb/pi-subagents/dist/package-resources.js:90`), is passed to `SettingsManager.create` when the package list is read (`node_modules/@tintinweb/pi-subagents/dist/package-resources.js:332`), and keys the scan (`node_modules/@tintinweb/pi-subagents/dist/package-resources.js:432`). An installed Systematic therefore exposes `systematic-<name>` types with plain defaults and no export step. `pi -e` does not, because it is not in `packages[]`, and neither does a git install, which has no built `dist/`. `tests/integration/pi.test.ts:1550-1652` pins dispatch from the package at project and global scope, the `packageAgents: false` switch in `subagents.json`, and local precedence [PI-7].
59
+ - **Installed package.** The package declares `pi.subagents.agents` at `package.json:24-28`, pointing at `dist/pi-subagents/agents/`. `scripts/build-pi-package-agents.ts` writes that directory at build time from the same render the export uses, so the 29 curated personas it ships are byte-equal to the committed fixtures (`tests/unit/package-exports.test.ts:289-344`) [PI-7]. pi-subagents 0.22 is the first release that reads package-declared agents. It reads them from the packages in Pi's `settings.json` `packages[]`, global and project, and never from `node_modules`, because the only scan is Pi's own configured-package list (`node_modules/@tintinweb/pi-subagents/dist/package-resources.js:327-341`). It sees a project-scope package only after the project is trusted: the trust flag starts `false` (`node_modules/@tintinweb/pi-subagents/dist/package-resources.js:90`), is passed to `SettingsManager.create` when the package list is read (`node_modules/@tintinweb/pi-subagents/dist/package-resources.js:332`), and keys the scan (`node_modules/@tintinweb/pi-subagents/dist/package-resources.js:432`). An installed Systematic therefore exposes `systematic-<name>` types with plain defaults and no export step. `pi -e` does not, because it is not in `packages[]`, and neither does a git install, which has no built `dist/`. `tests/integration/pi.test.ts:1553-1655` pins dispatch from the package at project and global scope, the `packageAgents: false` switch in `subagents.json`, and local precedence [PI-7].
60
60
  - **Export.** `systematic pi-subagents <preview|export|refresh|cleanup> --scope project|global` writes flat files that carry `systematic.json` overlays. Package agents load first, so a local file of the same name outranks the packaged one (`node_modules/@tintinweb/pi-subagents/dist/custom-agents.js:36-39,59-64`). No files are written without an explicit command [PI-7].
61
61
 
62
62
  Packaged personas are config-blind. The only function that sets pi-subagents' agent registry, `registerAgents` (`node_modules/@tintinweb/pi-subagents/dist/agent-types.js:65`), is called only from its own `dist/index.js:361`, so another extension cannot register or filter agent types. Overlays, `disabled_agents` and `agents.<name>.disable` therefore cannot reach a packaged file. `src/pi.ts:165-179` warns once at startup when either is configured. pi-subagents' own `/agents → Disable` turns off one packaged persona, and `packageAgents: false` in `subagents.json` turns off all of them (`node_modules/@tintinweb/pi-subagents/dist/settings.js:133-135`). A top-level `Agent` call runs in the background unless it passes `run_in_background: false` (`node_modules/@tintinweb/pi-subagents/dist/index.js:1187`).
@@ -67,7 +67,7 @@ Systematic's own config (`systematic.json`/`.jsonc`) is the durable source of tr
67
67
 
68
68
  Every export/refresh/cleanup operation walks every path component from a scope-anchored root down to the target agents directory and fails closed if any intermediate component is a symlink or a non-directory: the project anchor is the current working directory, the default global anchor is the user's home directory, and when `PI_CODING_AGENT_DIR` is set the anchor is that variable's parent directory. Manifest entries must name files matching `systematic-*.md`. `cleanup` deletes a manifest-owned file only when its on-disk content hash still matches the manifest's recorded hash — if a generated file has drifted from what the manifest recorded, `cleanup` refuses before any mutation and leaves both the file and the manifest untouched, and the user reverts the file to its exported content or deletes it by hand before running it again. `export` and `refresh` apply the same hash check to files that are no longer wanted, but a drifted file is left in place and reported as still active, and its previous manifest entry is kept unchanged, so a hand-edit never aborts the run. Manifest content hashes are ownership/drift evidence only — they are not a cryptographic integrity or authenticity guarantee.
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
+ 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:348-387`), and the installed runtime exposes environment-specific agent/session directories `node_modules/@earendil-works/pi-coding-agent/dist/config.js:396-398` [PI-5].
71
71
 
72
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.
73
73
 
@@ -90,12 +90,13 @@ 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 `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.
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.
94
94
 
95
95
  Evidence tiers differ by host, and this file does not claim more than the tests do:
96
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
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].
98
+ - **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].
99
100
 
100
101
  ## Worktree placement rule — bootstrap paths
101
102
 
@@ -235,9 +236,9 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
235
236
  - **PI-2** — [Pi profile](skills/using-systematic/references/pi-profile.md#L5-L8).
236
237
  - **PI-3** — `src/pi.ts:218-237`.
237
238
  - **PI-4** — `package.json:17-23`; `tests/unit/package-exports.test.ts:64-84,268-288`.
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`.
239
+ - **PI-5** — `tests/integration/pi.test.ts:348-387`; installed Pi source `node_modules/@earendil-works/pi-coding-agent/dist/config.js:396-398`.
239
240
  - **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`.
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.
241
+ - **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:1553-1655` (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.
241
242
  - **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
243
  - **CC-P** — [Claude Code profile](skills/using-systematic/references/claude-code-profile.md#L3-L9).
243
244
  - **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].
@@ -272,4 +273,6 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
272
273
  - **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
274
  - **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
275
  - **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.
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.
278
+ - **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.
@@ -1,23 +1,35 @@
1
1
  ---
2
2
  name: learnings-researcher
3
- description: "Searches docs/solutions/ for relevant past solutions by frontmatter metadata. Use before implementing features or fixing problems to surface institutional knowledge and prevent repeated mistakes."
3
+ description: "Searches docs/solutions/ for relevant past solutions by frontmatter metadata; with scope: past-work, also plans, brainstorms and ideation. Use before implementing features or fixing problems to surface institutional knowledge and prevent repeated mistakes."
4
4
  mode: subagent
5
5
  temperature: 0.2
6
6
  ---
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
+ ## Scope
11
+
12
+ The first line of the prompt may be `scope: <value>`. An optional `exclude: <repo-root path>` line may follow it.
13
+
14
+ - `solutions` is the default, and a prompt with no `scope:` line means `solutions`.
15
+ - `past-work` also covers `docs/plans/`, `docs/brainstorms/` and `docs/ideation/`. Text marked "Past-work" applies only to this scope.
16
+ - Any other value is unknown: name it in the Search Context, and use `solutions`.
17
+ - Overlap mode (the caller asks for an overlap assessment) uses `solutions` whatever the line says.
18
+
19
+ Drop the `exclude:` path from the hits by exact path; a `Supersedes:` line keeps its other entries.
20
+
10
21
  ## Search Strategy (Search First, Grep Fallback)
11
22
 
12
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.
13
24
 
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.
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.
15
26
 
16
27
  ### Step 0: Discover What Exists
17
28
 
18
29
  List `docs/solutions/` with a directory listing tool.
19
30
 
20
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.
21
33
  - The subdirectories you find are the categories. Do not assume any particular category exists.
22
34
  - Skip `README.md` files and anything under `_archived/` when collecting candidates. Never treat `critical-patterns.md` as a candidate (Step 3b handles it).
23
35
 
@@ -36,7 +48,9 @@ From the feature/task description, identify:
36
48
  - **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
49
  - If there is no such tool, go to Step 2 and use the grep path.
38
50
 
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.
51
+ **In `solutions` scope, 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.
52
+
53
+ **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.
40
54
 
41
55
  **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
56
 
@@ -44,12 +58,13 @@ In overlap mode (the caller asks for an overlap assessment against a new doc), d
44
58
 
45
59
  | Reply | Path |
46
60
  |-------|------|
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. |
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. |
49
64
  | 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
65
  | 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
66
  | 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. |
67
+ | 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. |
53
68
 
54
69
  The grep path keeps its OR patterns for synonyms. A zero-hit search does not add a new synonym pass.
55
70
 
@@ -57,13 +72,14 @@ The grep path keeps its OR patterns for synonyms. A zero-hit search does not add
57
72
  - The hits are already ranked and already resolved for lifecycle. Do not run Step 4's resolution again.
58
73
  - 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
74
  - Read a hit's `Status` and lifecycle lines from the reply. Take the other frontmatter fields in Step 5.
75
+ - Copy any `Successor:` line (a successor in another kind) literally in `solutions` and `past-work` scope, overlap mode included. The hit stays, and you never follow it. Past-work: read each hit's `Kind:` and `Status:` fields; Step 3b stays solution-only.
60
76
  - 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
77
 
62
78
  ### Step 2: Category-Based Narrowing (Optional but Recommended)
63
79
 
64
80
  The grep path starts here.
65
81
 
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.
82
+ If the feature type is clear, narrow the search to the category directories from Step 0 whose names fit it. Match by name; several can fit. When the type is unclear, or no directory fits, search `docs/solutions/` as a whole.
67
83
 
68
84
  ### Step 3: Content-Search Pre-Filter (Critical for Efficiency)
69
85
 
@@ -79,13 +95,8 @@ content-search: pattern="component:.*background_job" path=docs/solutions/ files_
79
95
 
80
96
  **Pattern construction tips:**
81
97
  - Use `|` for synonyms: `tags:.*(auth|login|session|token)`
82
- - Include `title:` - often the most descriptive field
83
- - Search case-insensitively
84
- - Include related terms the user might not have mentioned
85
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.
86
99
 
87
- **Why this works:** Content search scans file contents without reading into context. Only matching filenames are returned, dramatically reducing the set of files to examine.
88
-
89
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.
90
101
 
91
102
  **If search returns >25 candidates:** Re-run with more specific patterns or combine with category narrowing.
@@ -121,20 +132,21 @@ Then resolve every candidate before scoring:
121
132
  | `stale` | Keep it, and give it a `Caution:` line (see Output Format). |
122
133
  | `superseded` | Replace it with its successor, if the successor resolves. Otherwise keep the superseded doc and give it `Caution: successor unresolved`. |
123
134
 
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.
135
+ **Resolving a successor.** A successor resolves only within its own kind (`docs/solutions/`, `docs/plans/`, `docs/brainstorms/`, `docs/ideation/`). The link must be a repo-root path under the holding doc's directory, end in `.md`, contain no `..` segment, not be a `README.md`, not be under `_archived/`, and name a file that exists. A link that fits another of the four directories is not followed (see the apply step). Any other form, such as a bare filename, relative path, empty value or list, and a missing same-kind file, is unresolvable. Do not guess.
125
136
 
126
137
  1. Start with the candidate's `superseded_by` value. Keep a visited set holding the candidate's own path.
127
- 2. At every hop, before taking the target as the successor, check that it passes the form rule above and that the file exists. Check existence against the Step 0 listing or Glob results you already have, or with a direct existence check. A target that fails either check makes the chain unresolvable. A target that did not match the search is not evidence that it exists, because most active docs have no `status` line.
138
+ 2. At every hop, before taking the target as the successor, check that it passes the form rule above for the current doc's kind. If it fits another of the four directories, the walk ends here and the doc you are on stays, without reading or checking the target. Otherwise check that the file exists. Check existence against the Step 0 listing or Glob results you already have, or with a direct existence check. A target that fails either check makes the chain unresolvable. A target that did not match the search is not evidence that it exists, because most active docs have no `status` line.
128
139
  3. If the target is already in the visited set, the chain is a cycle: unresolvable.
129
140
  4. Read the target's frontmatter and take its `status`. If it is `superseded`, follow its `superseded_by` and repeat from step 2.
130
141
  5. One hop is one `superseded_by` link. Follow at most 5 hops. A target still superseded after the fifth hop makes the chain unresolvable.
131
- 6. The first target that is not `superseded` is the successor. An unrecognized status counts as active. If reading the target's frontmatter fails, the chain is unresolvable.
142
+ 6. The first target that is not `superseded` is the successor. If reading the target's frontmatter fails, the chain is unresolvable.
132
143
 
133
144
  **Then apply the result.**
134
145
  - 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.
135
146
  - If the successor is `stale`, it also gets a `Caution:` line.
136
147
  - 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.
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.
148
+ - A walk that ends at a link into another of the four directories leaves the doc it stopped on in place, at its own rank. It stays, with the line `Successor: <path>`, not `Caution: successor unresolved`. This holds in both scopes: a solution superseded by a plan prints `Successor:` on the grep path too, as search does.
149
+ - A superseded candidate with an unresolvable successor is returned itself, at its own rank, with the line `Caution: successor unresolved`. Nothing is dropped. A same-kind successor that is missing, any other form, a cycle and a chain past the hop cap are unresolvable.
138
150
 
139
151
  ### Step 5: Read Frontmatter of Candidates Only
140
152
 
@@ -156,6 +168,8 @@ Extract these fields from the YAML frontmatter:
156
168
 
157
169
  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.
158
170
 
171
+ Past-work: for plans, brainstorms and ideation docs, read `title`, `topic` and `status`, and the headings of the decision or requirements sections, not the solution fields above.
172
+
159
173
  ### Step 6: Score and Rank Relevance
160
174
 
161
175
  Match frontmatter fields against the feature/task description:
@@ -175,17 +189,15 @@ Match frontmatter fields against the feature/task description:
175
189
  - No overlapping tags, symptoms, or modules
176
190
  - Unrelated problem types
177
191
 
192
+ **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
+
178
194
  ### Step 7: Full Read of Relevant Files
179
195
 
180
- Only for files that pass the filter (strong or moderate matches), read the complete document to extract:
181
- - The full problem description
182
- - The solution implemented
183
- - Prevention guidance
184
- - Code examples
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.
185
197
 
186
198
  ### Step 8: Return Distilled Summaries
187
199
 
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`.
200
+ For each relevant document, return a summary in this format. `Supersedes:`, `Successor:` and `Caution:` are optional; include each only when it applies. `Successor:` is copied from the hit, or written on the grep path from a cross-kind link. `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`.
189
201
 
190
202
  ```markdown
191
203
  ### [Title from document]
@@ -196,9 +208,18 @@ For each relevant document, return a summary in this format. `Supersedes:` and `
196
208
  - **Key Insight**: [The most important takeaway - the thing that prevents repeating the mistake]
197
209
  - **Severity**: [severity level]
198
210
  Supersedes: <path>[, <path>]
211
+ Successor: <path>
199
212
  Caution: <text>
200
213
  ```
201
214
 
215
+ ### Past-work grep fallback
216
+
217
+ In `past-work` scope, when search cannot help, run Steps 2 to 6 over each of the four directories that exists. If only some kinds errored, run them over that kind's directory only.
218
+
219
+ - **Patterns.** In each directory, match the frontmatter fields `title:`, `topic:`, `status:`, `type:`, `origin:` and `date:`, and match filenames with a glob on the keywords. Read those fields in Steps 5 and 6; a missing `status` is `unspecified`.
220
+ - **Lifecycle.** Run the Step 4 content search over all four. Step 4's rule holds in each: a `superseded_by` resolves only within the doc's own directory, a path in another of the four stays a `Successor:` line, and any other form is `Caution: successor unresolved`.
221
+ - **Origin lookups.** To learn whether a plan carried out a brainstorm, grep `docs/plans/` for its path in `origin:`. The proposal counts as implemented only when that plan's recorded status is `completed`.
222
+
202
223
  ## Output Format
203
224
 
204
225
  Structure your findings as:
@@ -223,6 +244,7 @@ Structure your findings as:
223
244
  - **Relevance**: [why this matters for current task]
224
245
  - **Key Insight**: [the gotcha or pattern to apply]
225
246
  Supersedes: <path>[, <path>]
247
+ Successor: <path>
226
248
  Caution: <text>
227
249
 
228
250
  #### 2. [Title]
@@ -242,52 +264,53 @@ Overlap: <repo-root path> | problem=match|no-match root_cause=match|no-match sol
242
264
 
243
265
  **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.
244
266
 
267
+ ## Past-Work Output
268
+
269
+ In `past-work` scope, return this in place of the Output Format template.
270
+
271
+ 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
+
273
+ **Budget.** Report at most 12 items. Read each one's frontmatter and targeted headings, with at most 3 full reads.
274
+
275
+ **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
+
277
+ | Recorded status | Group |
278
+ |-----------------|-------|
279
+ | any `Kind: solution` hit | Proven lessons |
280
+ | `completed` | Existing or completed work |
281
+ | `abandoned`, `deferred`, `archived`, `superseded` | Rejected, deferred or superseded directions |
282
+ | `draft`, `active`, `unspecified` | Conflicts and open questions, worded "proposed in <path>" |
283
+ | any other value, such as `pending` or `planned`; `stale` keeps its `Caution:` line | Conflicts and open questions, worded "proposed in <path>" |
284
+
285
+ Recorded decisions and their rationale come from body sections (Key Decisions, Scope Boundaries) of lessons, existing work and rejected items, never from an item proposed in <path>. A proposal is never reported as implemented, shipped or decided. Every item carries its repo-root path and recorded status. A recorded status is not verified.
286
+
287
+ When nothing matches, write "no recorded plan or solution found in the results". Do not say the repo holds none.
288
+
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`.
290
+
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.
292
+
245
293
  ## Efficiency Guidelines
246
294
 
247
295
  The rules below about content search, patterns, synonyms and narrowing apply to the grep path. On the search path, the hits replace them.
248
296
 
249
297
  **DO:**
250
298
  - List `docs/solutions/` first and work from the directories that exist
251
- - Try the search tool once, when it exists, before any grep step
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
252
300
  - Take the grep path when search finds nothing, is disabled, errors or does not exist
253
301
  - Use the native content-search tool to pre-filter files BEFORE reading any content (critical for 100+ files)
254
- - Run multiple content searches in PARALLEL for different keywords
255
- - Include `title:` in search patterns - often the most descriptive field
256
- - Use OR patterns for synonyms: `tags:.*(auth|login|session)`
257
- - Use `-i=true` for case-insensitive matching
258
- - Use category directories to narrow scope when feature type is clear
259
- - Do a broader content search as fallback if <3 candidates found
260
- - Re-narrow with more specific patterns if >25 candidates found
302
+ - Run content searches in PARALLEL, with `title:` and OR patterns for synonyms
261
303
  - 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
262
- - Read the critical patterns file only when it exists
263
- - Only read frontmatter of search-matched candidates (not all files)
264
- - Filter aggressively - only fully read truly relevant files
265
304
  - Prioritize high-severity and critical patterns
266
- - Extract actionable insights, not just summaries
267
- - Note when no relevant learnings exist (this is valuable information too)
268
305
 
269
306
  **DON'T:**
270
307
  - Read a path that may not exist (a category directory, `critical-patterns.md`, a successor) without checking that it exists
271
- - Read frontmatter of ALL files (use content-search to pre-filter first)
272
- - Run searches sequentially when they can be parallel
273
- - Use only exact keyword matches (include synonyms)
274
- - Skip the `title:` field in search patterns
275
- - Proceed with >25 candidates without narrowing first
276
- - Read every file in full (wasteful)
277
308
  - Return raw document contents (distill instead)
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
280
- - Follow a `superseded_by` that is not a repo-root `docs/solutions/` path, and never follow more than 5 hops
309
+ - 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)
311
+ - 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
281
312
  - Include tangentially related learnings (focus on relevance)
282
313
 
283
314
  ## Integration Points
284
315
 
285
- This agent is designed to be invoked by:
286
- - `/ce:plan` - To inform planning with institutional knowledge and add depth during confidence checking
287
- - `/ce:review` - To flag known patterns in the diff under review
288
- - `/ce:ideate` - To ground ideas in documented past solutions
289
- - `/ce:compound` - As the Related Docs Finder when a new learning is written
290
- - `/deepen-plan` - To strengthen plans with documented prior art
291
- - Manual invocation before starting work on a feature
292
-
293
- The goal is to surface relevant learnings in under 30 seconds for a typical solutions directory, enabling fast knowledge retrieval during planning phases.
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.
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-9chxhh5j.js";
47
+ } from "./index-e467g4b6.js";
48
48
  var __defProp = Object.defineProperty;
49
49
  var __returnValue = (v) => v;
50
50
  function __exportSetter(name, newValue) {
@@ -2927,15 +2927,18 @@ function runReviewReturnValidator(options) {
2927
2927
  // src/lib/search-cli.ts
2928
2928
  import path4 from "path";
2929
2929
  function searchCliUsage(commandName) {
2930
- return `Usage: ${commandName} <query...> [--dir <path>] [--kind solution] [--limit <${MIN_LIMIT}-${MAX_LIMIT}>] [--]
2930
+ return `Usage: ${commandName} <query...> [--dir <path>] [--kind solution|plan|brainstorm|ideation|all] [--limit <${MIN_LIMIT}-${MAX_LIMIT}>] [--]
2931
2931
 
2932
- Searches the project's docs/solutions learnings by symptom, error text, module
2933
- or topic, and prints ranked hits.
2932
+ Searches the project's past work by symptom, error text, module or topic, and
2933
+ prints ranked hits: the docs/solutions learnings, and the docs/plans,
2934
+ docs/brainstorms and docs/ideation documents.
2934
2935
 
2935
2936
  Options:
2936
2937
  --dir <path> Start the search from <path> (default: the current directory).
2937
2938
  The project root is the nearest ancestor holding .git.
2938
- --kind <kind> The kind of durable output to search. Only "solution" exists.
2939
+ --kind <kind> The kind of durable output to search: solution (docs/solutions,
2940
+ the default), plan (docs/plans), brainstorm (docs/brainstorms),
2941
+ ideation (docs/ideation), or all to rank every kind together.
2939
2942
  --limit <n> How many hits to return, ${MIN_LIMIT} to ${MAX_LIMIT} (default: 8).
2940
2943
  -- End of options; everything after it is part of the query.
2941
2944
  -h, --help Show this help.
@@ -3387,10 +3390,12 @@ Commands:
3387
3390
  CI, issues, or fixtures. Not for the ce:review parent's own run artifact.
3388
3391
  Exit statuses: 0 valid artifact, 1 validation failure,
3389
3392
  2 operational failure, 3 legacy artifact with no schema_version
3390
- search <query...> [--dir <path>] [--kind solution] [--limit <1-20>]
3391
- Search the project's docs/solutions learnings by symptom, error text,
3392
- module or topic, and print ranked hits. The project root is the nearest
3393
- ancestor of --dir (default: the current directory) that holds .git.
3393
+ search <query...> [--dir <path>] [--kind solution|plan|brainstorm|ideation|all] [--limit <1-20>]
3394
+ Search the project's past work by symptom, error text, module or topic,
3395
+ and print ranked hits: docs/solutions learnings (the default kind),
3396
+ 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.
3394
3399
  Reads user-level search settings; a project config cannot change them.
3395
3400
  Exit statuses: 0 results, no hits, or search disabled; 2 usage error
3396
3401
  Use -- to end options, for a query that starts with a dash