@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.
@@ -10,7 +10,7 @@
10
10
  * names and bodies are untrusted text that ends up in an agent's context and
11
11
  * a human's terminal.
12
12
  */
13
- import type { CorpusDocument } from './search-corpus.js';
13
+ import type { CorpusDocument, DocumentKind } from './search-corpus.js';
14
14
  /** Hard cap on rendered output, in UTF-8 bytes. */
15
15
  export declare const MAX_OUTPUT_BYTES: number;
16
16
  /** Appended on its own line when output is cut. */
@@ -21,24 +21,43 @@ export declare const MAX_SNIPPET_CHARS = 240;
21
21
  export declare const MAX_WARNINGS = 5;
22
22
  /** The lifecycle line that lists the docs a successor replaces. */
23
23
  export declare const SUPERSEDES_LABEL = "Supersedes:";
24
- export type SearchHitStatus = 'active' | 'stale' | 'superseded';
24
+ /** The lifecycle line that names a successor in another kind. Information, not a caution. */
25
+ export declare const SUCCESSOR_LABEL = "Successor:";
26
+ /**
27
+ * The status a hit prints. A solution gets `active`, `stale` or `superseded`;
28
+ * the other kinds get the recorded value as written, or `unspecified`.
29
+ */
30
+ export type SearchHitStatus = string;
25
31
  export interface SearchHit {
26
32
  /** 1-based position in the final list. */
27
33
  readonly rank: number;
28
34
  readonly document: CorpusDocument;
29
35
  readonly status: SearchHitStatus;
30
- /** Fully formed `Supersedes:` and `Caution:` lines, in print order. */
36
+ /** Fully formed `Supersedes:`, `Successor:` and `Caution:` lines, in print order. */
31
37
  readonly lifecycle: readonly string[];
32
38
  }
39
+ /** What one searched kind held: its directory, its state and how many documents loaded. */
40
+ export interface KindCorpus {
41
+ readonly kind: DocumentKind;
42
+ /** Root-relative directory, with `/` separators and no trailing slash. */
43
+ readonly dir: string;
44
+ readonly state: 'none' | 'empty' | 'docs';
45
+ readonly docCount: number;
46
+ }
33
47
  export interface SearchResult {
34
48
  /** The query as the caller sent it; sanitised and capped when echoed. */
35
49
  readonly query: string;
36
50
  /** Unique, sorted query terms, used to pick snippet windows. */
37
51
  readonly queryTerms: readonly string[];
38
- /** `none`: no docs/solutions/. `empty`: the directory holds no indexable doc. */
52
+ /**
53
+ * `none`: no searched directory exists. `empty`: a directory exists but none
54
+ * holds an indexable doc. `docs` otherwise. `kinds` is one report per searched
55
+ * kind, in table order: one entry for a single-kind search, every kind for `all`.
56
+ */
39
57
  readonly corpus: {
40
58
  readonly state: 'none' | 'empty' | 'docs';
41
59
  readonly docCount: number;
60
+ readonly kinds: readonly KindCorpus[];
42
61
  };
43
62
  readonly hits: readonly SearchHit[];
44
63
  readonly notes: readonly string[];
@@ -6,7 +6,8 @@
6
6
  * of the rendered text belong to `runSearch` in `search-core.ts`.
7
7
  *
8
8
  * No adapter asks for a permission: the tool reads only the project's own
9
- * `docs/solutions/`, under a realpath containment check in the corpus loader.
9
+ * `docs/solutions/`, `docs/plans/`, `docs/brainstorms/` and `docs/ideation/`,
10
+ * under a realpath containment check in the corpus loader.
10
11
  * Every host schema declares `limit` as a plain integer and states the range
11
12
  * in the description, so the core's fixed error is what an out-of-range value
12
13
  * gets wherever the host passes it through.
package/dist/pi.js CHANGED
@@ -3254,6 +3254,24 @@ var KIND_TABLE = {
3254
3254
  excludedFiles: ["readme.md", "critical-patterns.md"],
3255
3255
  excludedDirs: ["_archived"],
3256
3256
  lifecycle: true
3257
+ },
3258
+ plan: {
3259
+ dir: "docs/plans",
3260
+ excludedFiles: ["readme.md"],
3261
+ excludedDirs: ["_archived"],
3262
+ lifecycle: true
3263
+ },
3264
+ brainstorm: {
3265
+ dir: "docs/brainstorms",
3266
+ excludedFiles: ["readme.md"],
3267
+ excludedDirs: ["_archived"],
3268
+ lifecycle: true
3269
+ },
3270
+ ideation: {
3271
+ dir: "docs/ideation",
3272
+ excludedFiles: ["readme.md"],
3273
+ excludedDirs: ["_archived"],
3274
+ lifecycle: true
3257
3275
  }
3258
3276
  };
3259
3277
  function isDocumentKind(value) {
@@ -3377,6 +3395,10 @@ function discoverFiles(spec, directory, prefix, depth, found, warnings) {
3377
3395
  function narrowString(value) {
3378
3396
  return typeof value === "string" ? value : undefined;
3379
3397
  }
3398
+ function narrowNonEmptyString(value) {
3399
+ const trimmed = narrowString(value)?.trim();
3400
+ return trimmed ? trimmed : undefined;
3401
+ }
3380
3402
  function narrowStringList(value) {
3381
3403
  const items = Array.isArray(value) ? value : [value];
3382
3404
  const result = [];
@@ -3409,13 +3431,13 @@ function parseCorpusDocument(kind, relativePath, content) {
3409
3431
  }
3410
3432
  const data = isRecord(parsed.data) ? parsed.data : {};
3411
3433
  const fileName = relativePath.slice(relativePath.lastIndexOf("/") + 1);
3412
- const title = narrowString(data.title)?.trim();
3434
+ const title = narrowNonEmptyString(data.title) ?? narrowNonEmptyString(data.topic) ?? fileName.replace(/\.md$/i, "");
3413
3435
  return {
3414
3436
  ok: true,
3415
3437
  document: {
3416
3438
  path: relativePath,
3417
3439
  kind,
3418
- title: title ? title : fileName.replace(/\.md$/i, ""),
3440
+ title,
3419
3441
  tags: narrowStringList(data.tags),
3420
3442
  module: narrowString(data.module),
3421
3443
  component: narrowString(data.component),
@@ -3499,10 +3521,10 @@ function loadCorpus(root, kind = "solution") {
3499
3521
  const capSkipped = candidates.length - considered;
3500
3522
  if (capSkipped > 0) {
3501
3523
  const atLeast = found.truncated ? "at least " : "";
3502
- warnings.push(`file limit of ${MAX_FILES} reached; skipped ${atLeast}${capSkipped} files`);
3524
+ warnings.push(`${spec.dir}: file limit of ${MAX_FILES} reached; skipped ${atLeast}${capSkipped} files`);
3503
3525
  }
3504
3526
  if (budgetSkipped > 0) {
3505
- warnings.push(`text budget of ${MAX_TOTAL_BYTES} bytes reached; skipped ${budgetSkipped} files`);
3527
+ warnings.push(`${spec.dir}: text budget of ${MAX_TOTAL_BYTES} bytes reached; skipped ${budgetSkipped} files`);
3506
3528
  }
3507
3529
  return { state: "loaded", documents, warnings };
3508
3530
  }
@@ -3667,6 +3689,7 @@ var MAX_TAGS = 8;
3667
3689
  var MAX_SNIPPET_CHARS = 240;
3668
3690
  var MAX_WARNINGS = 5;
3669
3691
  var SUPERSEDES_LABEL = "Supersedes:";
3692
+ var SUCCESSOR_LABEL = "Successor:";
3670
3693
  var MAX_TAG_CHARS = 64;
3671
3694
  var MAX_MODULE_CHARS = 120;
3672
3695
  var MAX_QUERY_ECHO_CHARS = 200;
@@ -3832,25 +3855,46 @@ function extractSnippet(document, queryTerms) {
3832
3855
  function plural(count, singular) {
3833
3856
  return `${count} ${singular}${count === 1 ? "" : "s"}`;
3834
3857
  }
3858
+ function joinOr(items) {
3859
+ const last = items[items.length - 1];
3860
+ if (items.length < 2 || last === undefined)
3861
+ return items.join("");
3862
+ return `${items.slice(0, -1).join(", ")} or ${last}`;
3863
+ }
3864
+ function kindTokens(kinds) {
3865
+ return kinds.map(({ kind, state, docCount }) => `${kind} ${state === "docs" ? docCount : state}`).join(", ");
3866
+ }
3835
3867
  function renderHeader(result) {
3836
3868
  const query = sanitizeInline(result.query, MAX_QUERY_ECHO_CHARS);
3837
3869
  const prefix = `Search "${query}":`;
3838
- switch (result.corpus.state) {
3839
- case "none":
3840
- return `${prefix} corpus: none (no docs/solutions/ directory under the project root).`;
3870
+ const { corpus } = result;
3871
+ const [only, ...others] = corpus.kinds;
3872
+ const single = only !== undefined && others.length === 0;
3873
+ switch (corpus.state) {
3874
+ case "none": {
3875
+ const dirs = joinOr(corpus.kinds.map(({ dir }) => `${dir}/`));
3876
+ return `${prefix} corpus: none (no ${dirs} directory under the project root).`;
3877
+ }
3841
3878
  case "empty":
3842
- return `${prefix} corpus: empty (docs/solutions/ holds no indexable docs).`;
3843
- case "docs":
3844
- return `${prefix} ${plural(result.corpus.docCount, "doc")}, ${plural(result.hits.length, "hit")}. Corpus: docs/solutions.`;
3879
+ return single ? `${prefix} corpus: empty (${only.dir}/ holds no indexable docs).` : `${prefix} corpus: empty (no indexable docs: ${kindTokens(corpus.kinds)}).`;
3880
+ case "docs": {
3881
+ const counts = `${plural(corpus.docCount, "doc")}, ${plural(result.hits.length, "hit")}`;
3882
+ const searched = single ? only.dir : kindTokens(corpus.kinds);
3883
+ return `${prefix} ${counts}. Corpus: ${searched}.`;
3884
+ }
3845
3885
  }
3846
3886
  }
3847
3887
  function renderLifecycleLine(line) {
3848
- const prefix = `${SUPERSEDES_LABEL} `;
3849
- if (!line.startsWith(prefix)) {
3850
- return sanitizeInline(line, MAX_LIFECYCLE_LINE_CHARS);
3888
+ const supersedes = `${SUPERSEDES_LABEL} `;
3889
+ if (line.startsWith(supersedes)) {
3890
+ const paths = line.slice(supersedes.length).split(", ").map((path) => sanitizeInline(path, MAX_PATH_CHARS)).filter((path) => path !== "");
3891
+ return `${supersedes}${paths.join(", ")}`;
3892
+ }
3893
+ const successor = `${SUCCESSOR_LABEL} `;
3894
+ if (line.startsWith(successor)) {
3895
+ return `${successor}${sanitizeInline(line.slice(successor.length), MAX_PATH_CHARS)}`;
3851
3896
  }
3852
- const paths = line.slice(prefix.length).split(", ").map((path) => sanitizeInline(path, MAX_PATH_CHARS)).filter((path) => path !== "");
3853
- return `${prefix}${paths.join(", ")}`;
3897
+ return sanitizeInline(line, MAX_LIFECYCLE_LINE_CHARS);
3854
3898
  }
3855
3899
  function renderHit(hit, queryTerms) {
3856
3900
  const { document } = hit;
@@ -3906,10 +3950,13 @@ var DEFAULT_LIMIT = 8;
3906
3950
  var MIN_LIMIT = 1;
3907
3951
  var MAX_LIMIT = 20;
3908
3952
  var MAX_QUERY_CHARS = 2000;
3909
- var SEARCH_TOOL_DESCRIPTION = "Search this project's durable outputs (the docs/solutions learnings) by symptom, error text, module or topic. Returns ranked hits with path, title, snippet, tags and status. A superseded learning is replaced by its successor, and a stale one carries a caution. Read a hit's path for the full text. Use it before debugging a failure or planning work a past learning may already cover.";
3953
+ var KIND_SELECTOR_ALL = "all";
3954
+ var DOCUMENT_KINDS = Object.keys(KIND_TABLE).filter(isDocumentKind);
3955
+ var KIND_NAMES = [...DOCUMENT_KINDS, KIND_SELECTOR_ALL];
3956
+ var SEARCH_TOOL_DESCRIPTION = "Search this project's durable outputs by symptom, error text, module or topic: the docs/solutions learnings, and the docs/plans, docs/brainstorms and docs/ideation documents that earlier work wrote. Returns ranked hits with path, title, kind, snippet, tags and status. A superseded document is replaced by its successor in the same kind, a successor in another kind is named on a Successor line, and a stale one carries a caution. Read a hit's path for the full text. Use it before debugging a failure or planning work that a past learning, plan, brainstorm or ideation doc may already cover.";
3910
3957
  var SEARCH_ARG_DESCRIPTIONS = {
3911
3958
  query: `What to look for: a symptom, error message, module or topic, in plain words. At most ${MAX_QUERY_CHARS} characters.`,
3912
- kind: 'Optional. The kind of durable output to search. Only "solution" (docs/solutions/) exists today, and it is the default.',
3959
+ kind: `Optional. The kind of durable output to search: ${DOCUMENT_KINDS.map((kind) => `"${kind}" (${KIND_TABLE[kind].dir}/)`).join(", ")}, or "${KIND_SELECTOR_ALL}" for every kind in one ranking. Defaults to "solution".`,
3913
3960
  limit: `Optional. How many hits to return, an integer from ${MIN_LIMIT} to ${MAX_LIMIT}. Defaults to ${DEFAULT_LIMIT}.`
3914
3961
  };
3915
3962
  var SEARCH_NOTICES = {
@@ -3918,19 +3965,20 @@ var SEARCH_NOTICES = {
3918
3965
  };
3919
3966
  var SEARCH_CONFIG_UNREADABLE_NOTE = "config unreadable";
3920
3967
  var MAX_SUCCESSOR_HOPS = 5;
3921
- var SUCCESSOR_PATH_PREFIX = `${KIND_TABLE.solution.dir}/`;
3922
3968
  var CAUTION_LABEL = "Caution:";
3923
3969
  var SUCCESSOR_UNRESOLVED_TEXT = "successor unresolved";
3924
3970
  var STALE_CAUTION_TEXT = "marked stale";
3925
3971
  var MAX_STALE_REASON_CHARS = 200;
3972
+ var UNSPECIFIED_STATUS = "unspecified";
3926
3973
  var SEARCH_ERRORS = {
3927
3974
  queryEmpty: "Error: query must be a non-empty string.",
3928
3975
  queryTooLong: `Error: query must be at most ${MAX_QUERY_CHARS} characters.`,
3929
- kindUnknown: `Error: kind must be one of: ${Object.keys(KIND_TABLE).join(", ")}.`,
3976
+ kindUnknown: `Error: kind must be one of: ${KIND_NAMES.join(", ")}.`,
3930
3977
  limitInvalid: `Error: limit must be an integer from ${MIN_LIMIT} to ${MAX_LIMIT}.`
3931
3978
  };
3932
- function isSuccessorPathForm(value) {
3933
- if (!value.startsWith(SUCCESSOR_PATH_PREFIX))
3979
+ function isSuccessorPathForm(value, kind = "solution") {
3980
+ const spec = KIND_TABLE[kind];
3981
+ if (!value.startsWith(`${spec.dir}/`))
3934
3982
  return false;
3935
3983
  if (!value.endsWith(".md"))
3936
3984
  return false;
@@ -3938,31 +3986,50 @@ function isSuccessorPathForm(value) {
3938
3986
  if (segments.includes(".."))
3939
3987
  return false;
3940
3988
  const name = segments[segments.length - 1]?.toLowerCase();
3941
- if (name === "readme.md")
3942
- return false;
3943
- if (segments.includes("_archived"))
3989
+ if (name !== undefined && spec.excludedFiles.includes(name)) {
3944
3990
  return false;
3945
- return true;
3991
+ }
3992
+ return !segments.some((segment) => spec.excludedDirs.includes(segment));
3993
+ }
3994
+ function successorFormKind(value) {
3995
+ return DOCUMENT_KINDS.find((kind) => isSuccessorPathForm(value, kind));
3946
3996
  }
3947
- function resolveSuccessor(candidate, byPath) {
3997
+ function hasStatus(document, wanted) {
3998
+ if (document.status === undefined)
3999
+ return false;
4000
+ if (document.kind === "solution")
4001
+ return document.status === wanted;
4002
+ return document.status.trim().toLowerCase() === wanted;
4003
+ }
4004
+ function stepSuccessor(current, byPath, visited) {
4005
+ const link = current.supersededBy;
4006
+ if (link.state !== "value")
4007
+ return { outcome: "unresolved" };
4008
+ if (!isSuccessorPathForm(link.value, current.kind)) {
4009
+ if (successorFormKind(link.value) === undefined) {
4010
+ return { outcome: "unresolved" };
4011
+ }
4012
+ return { outcome: "resolved", document: current, successorPath: link.value };
4013
+ }
4014
+ const target = byPath.get(link.value);
4015
+ if (target === undefined || visited.has(target.path)) {
4016
+ return { outcome: "unresolved" };
4017
+ }
4018
+ visited.add(target.path);
4019
+ if (hasStatus(target, "superseded"))
4020
+ return { outcome: "continue", next: target };
4021
+ return { outcome: "resolved", document: target, successorPath: undefined };
4022
+ }
4023
+ function walkSuccessors(candidate, byPath) {
3948
4024
  const visited = new Set([candidate.path]);
3949
4025
  let current = candidate;
3950
4026
  for (let hop = 1;hop <= MAX_SUCCESSOR_HOPS; hop++) {
3951
- const link = current.supersededBy;
3952
- if (link.state !== "value" || !isSuccessorPathForm(link.value)) {
3953
- return;
3954
- }
3955
- if (visited.has(link.value))
3956
- return;
3957
- const target = byPath.get(link.value);
3958
- if (target === undefined)
3959
- return;
3960
- visited.add(target.path);
3961
- if (target.status !== "superseded")
3962
- return target;
3963
- current = target;
4027
+ const step = stepSuccessor(current, byPath, visited);
4028
+ if (step.outcome !== "continue")
4029
+ return step;
4030
+ current = step.next;
3964
4031
  }
3965
- return;
4032
+ return { outcome: "unresolved" };
3966
4033
  }
3967
4034
  function compareCodeUnits3(a, b) {
3968
4035
  if (a < b)
@@ -3977,18 +4044,21 @@ function resolveLifecycle(ranked, documents) {
3977
4044
  let target = candidate;
3978
4045
  let replaces;
3979
4046
  let unresolved = false;
3980
- if (candidate.status === "superseded") {
3981
- const successor = resolveSuccessor(candidate, byPath);
3982
- if (successor === undefined)
4047
+ let successor;
4048
+ if (hasStatus(candidate, "superseded")) {
4049
+ const walk = walkSuccessors(candidate, byPath);
4050
+ if (walk.outcome === "unresolved")
3983
4051
  unresolved = true;
3984
4052
  else {
3985
- target = successor;
3986
- replaces = candidate.path;
4053
+ target = walk.document;
4054
+ successor = walk.successorPath;
4055
+ if (target.path !== candidate.path)
4056
+ replaces = candidate.path;
3987
4057
  }
3988
4058
  }
3989
4059
  let entry = entries.get(target.path);
3990
4060
  if (entry === undefined) {
3991
- entry = { document: target, replaced: new Set, unresolved };
4061
+ entry = { document: target, replaced: new Set, unresolved, successor };
3992
4062
  entries.set(target.path, entry);
3993
4063
  order.push(target.path);
3994
4064
  }
@@ -4003,24 +4073,33 @@ function resolveLifecycle(ranked, documents) {
4003
4073
  {
4004
4074
  document: entry.document,
4005
4075
  supersedes: [...entry.replaced].sort(compareCodeUnits3),
4006
- unresolved: entry.unresolved
4076
+ unresolved: entry.unresolved,
4077
+ successor: entry.successor
4007
4078
  }
4008
4079
  ];
4009
4080
  });
4010
4081
  }
4011
4082
  function entryStatus(entry) {
4012
- if (entry.unresolved)
4083
+ const { document } = entry;
4084
+ if (document.kind !== "solution") {
4085
+ const { status } = document;
4086
+ return status !== undefined && status.trim() !== "" ? status : UNSPECIFIED_STATUS;
4087
+ }
4088
+ if (entry.unresolved || entry.successor !== undefined)
4013
4089
  return "superseded";
4014
- return entry.document.status === "stale" ? "stale" : "active";
4090
+ return document.status === "stale" ? "stale" : "active";
4015
4091
  }
4016
4092
  function lifecycleLines(entry) {
4017
4093
  const lines = [];
4018
4094
  if (entry.supersedes.length > 0) {
4019
4095
  lines.push(`${SUPERSEDES_LABEL} ${entry.supersedes.join(", ")}`);
4020
4096
  }
4097
+ if (entry.successor !== undefined) {
4098
+ lines.push(`${SUCCESSOR_LABEL} ${entry.successor}`);
4099
+ }
4021
4100
  if (entry.unresolved) {
4022
4101
  lines.push(`${CAUTION_LABEL} ${SUCCESSOR_UNRESOLVED_TEXT}`);
4023
- } else if (entry.document.status === "stale") {
4102
+ } else if (hasStatus(entry.document, "stale")) {
4024
4103
  const reason = sanitizeInline(entry.document.staleReason ?? "", MAX_STALE_REASON_CHARS);
4025
4104
  lines.push(reason === "" ? `${CAUTION_LABEL} ${STALE_CAUTION_TEXT}` : `${CAUTION_LABEL} ${STALE_CAUTION_TEXT}: ${reason}`);
4026
4105
  }
@@ -4043,6 +4122,13 @@ function toLexicalDocument(document) {
4043
4122
  }
4044
4123
  };
4045
4124
  }
4125
+ function requestedKinds(value) {
4126
+ if (value === undefined)
4127
+ return ["solution"];
4128
+ if (value === KIND_SELECTOR_ALL)
4129
+ return DOCUMENT_KINDS;
4130
+ return isDocumentKind(value) ? [value] : undefined;
4131
+ }
4046
4132
  function validate(request) {
4047
4133
  const { query } = request;
4048
4134
  if (typeof query !== "string" || query.trim() === "") {
@@ -4051,12 +4137,9 @@ function validate(request) {
4051
4137
  if (query.length > MAX_QUERY_CHARS) {
4052
4138
  return { ok: false, error: SEARCH_ERRORS.queryTooLong };
4053
4139
  }
4054
- let kind = "solution";
4055
- if (request.kind !== undefined) {
4056
- if (!isDocumentKind(request.kind)) {
4057
- return { ok: false, error: SEARCH_ERRORS.kindUnknown };
4058
- }
4059
- kind = request.kind;
4140
+ const kinds = requestedKinds(request.kind);
4141
+ if (kinds === undefined) {
4142
+ return { ok: false, error: SEARCH_ERRORS.kindUnknown };
4060
4143
  }
4061
4144
  let limit = DEFAULT_LIMIT;
4062
4145
  if (request.limit !== undefined) {
@@ -4066,20 +4149,74 @@ function validate(request) {
4066
4149
  }
4067
4150
  limit = value;
4068
4151
  }
4069
- return { ok: true, query, kind, limit };
4152
+ return { ok: true, query, kinds, limit };
4153
+ }
4154
+ var SKIPPED_PREFIX = "skipped ";
4155
+ function skipReason(warning) {
4156
+ if (!warning.startsWith(SKIPPED_PREFIX))
4157
+ return;
4158
+ const colon = warning.lastIndexOf(": ");
4159
+ return colon === -1 ? undefined : warning.slice(colon + 2);
4160
+ }
4161
+ function plural2(count, singular) {
4162
+ return `${count} ${singular}${count === 1 ? "" : "s"}`;
4163
+ }
4164
+ function skipSummary(dir, reasons) {
4165
+ const parts = [...reasons].sort(([a, x], [b, y]) => y - x || compareCodeUnits3(a, b)).map(([reason, count]) => `${count} ${reason}`);
4166
+ const total = [...reasons.values()].reduce((sum, count) => sum + count, 0);
4167
+ return `${dir}: skipped ${plural2(total, "file")} (${parts.join(", ")})`;
4168
+ }
4169
+ function aggregateWarnings(loads) {
4170
+ const structural = [];
4171
+ const summaries = [];
4172
+ for (const { kind, load } of loads) {
4173
+ const reasons = new Map;
4174
+ for (const warning of load.warnings) {
4175
+ const reason = skipReason(warning);
4176
+ if (reason === undefined)
4177
+ structural.push(warning);
4178
+ else
4179
+ reasons.set(reason, (reasons.get(reason) ?? 0) + 1);
4180
+ }
4181
+ if (reasons.size > 0) {
4182
+ summaries.push(skipSummary(KIND_TABLE[kind].dir, reasons));
4183
+ }
4184
+ }
4185
+ return [...structural, ...summaries];
4186
+ }
4187
+ function kindCorpus({ kind, load }) {
4188
+ const docCount = load.documents.length;
4189
+ let state = "docs";
4190
+ if (load.state === "none")
4191
+ state = "none";
4192
+ else if (docCount === 0)
4193
+ state = "empty";
4194
+ return { kind, dir: KIND_TABLE[kind].dir, state, docCount };
4195
+ }
4196
+ function combinedState(kinds) {
4197
+ if (kinds.some((report) => report.state === "docs"))
4198
+ return "docs";
4199
+ return kinds.every((report) => report.state === "none") ? "none" : "empty";
4070
4200
  }
4071
4201
  async function runSearch(request, options) {
4072
4202
  const checked = validate(request);
4073
4203
  if (!checked.ok)
4074
4204
  return { ok: false, text: checked.error };
4075
- const { query, kind, limit } = checked;
4205
+ const { query, kinds, limit } = checked;
4076
4206
  const root = resolveSearchRoot(options.startDir);
4077
- const load = (options.corpusLoader ?? loadCorpus)(root, kind);
4207
+ const loader = options.corpusLoader ?? loadCorpus;
4208
+ const loads = kinds.map((kind) => ({ kind, load: loader(root, kind) }));
4209
+ const reports = loads.map(kindCorpus);
4210
+ const corpus = {
4211
+ state: combinedState(reports),
4212
+ docCount: reports.reduce((sum, report) => sum + report.docCount, 0),
4213
+ kinds: reports
4214
+ };
4078
4215
  const { terms, truncated } = uniqueQueryTerms(query);
4079
4216
  const base = {
4080
4217
  query,
4081
4218
  queryTerms: terms,
4082
- warnings: load.warnings
4219
+ warnings: aggregateWarnings(loads)
4083
4220
  };
4084
4221
  const noteList = [...options.notes ?? []];
4085
4222
  if (truncated)
@@ -4089,43 +4226,26 @@ async function runSearch(request, options) {
4089
4226
  text: renderSearchResult(result),
4090
4227
  result
4091
4228
  });
4092
- if (load.state === "none") {
4093
- return finish({
4094
- ...base,
4095
- corpus: { state: "none", docCount: 0 },
4096
- hits: [],
4097
- notes: noteList
4098
- });
4099
- }
4100
- if (load.documents.length === 0) {
4101
- return finish({
4102
- ...base,
4103
- corpus: { state: "empty", docCount: 0 },
4104
- hits: [],
4105
- notes: noteList
4106
- });
4229
+ if (corpus.state !== "docs") {
4230
+ return finish({ ...base, corpus, hits: [], notes: noteList });
4107
4231
  }
4108
- const index = buildLexicalIndex(load.documents.map(toLexicalDocument), options.lexicalParams ?? BM25F_PARAMS);
4232
+ const documents = loads.flatMap(({ load }) => load.documents).sort((a, b) => compareCodeUnits3(a.path, b.path));
4233
+ const index = buildLexicalIndex(documents.map(toLexicalDocument), options.lexicalParams ?? BM25F_PARAMS);
4109
4234
  const lexical = searchLexical(index, terms);
4110
- const byPath = new Map(load.documents.map((doc) => [doc.path, doc]));
4235
+ const byPath = new Map(documents.map((doc) => [doc.path, doc]));
4111
4236
  const candidates = [];
4112
4237
  for (const hit of lexical) {
4113
4238
  const document = byPath.get(hit.id);
4114
4239
  if (document !== undefined)
4115
4240
  candidates.push(document);
4116
4241
  }
4117
- const hits = resolveLifecycle(candidates, load.documents).slice(0, limit).map((entry, position) => ({
4242
+ const hits = resolveLifecycle(candidates, documents).slice(0, limit).map((entry, position) => ({
4118
4243
  rank: position + 1,
4119
4244
  document: entry.document,
4120
4245
  status: entryStatus(entry),
4121
4246
  lifecycle: lifecycleLines(entry)
4122
4247
  }));
4123
- return finish({
4124
- ...base,
4125
- corpus: { state: "docs", docCount: load.documents.length },
4126
- hits,
4127
- notes: noteList
4128
- });
4248
+ return finish({ ...base, corpus, hits, notes: noteList });
4129
4249
  }
4130
4250
 
4131
4251
  // src/lib/agent-resolver.ts
@@ -12666,7 +12786,7 @@ function createPiSearchTool(options) {
12666
12786
  name: SEARCH_TOOL_NAME,
12667
12787
  label: "Systematic Search",
12668
12788
  description: SEARCH_TOOL_DESCRIPTION,
12669
- promptSnippet: "Use `systematic_search` to find past learnings in docs/solutions.",
12789
+ promptSnippet: 'Use `systematic_search` to find past learnings (docs/solutions), plans, brainstorms and ideation (docs/plans, docs/brainstorms, docs/ideation). Pass kind "all" to search them together.',
12670
12790
  parameters: buildPiParameters(Type),
12671
12791
  async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
12672
12792
  const text = await executeSearch(params, usableDirectory(ctx.cwd), settings, unreadable);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fro.bot/systematic",
3
- "version": "3.28.1",
3
+ "version": "3.29.0",
4
4
  "description": "Compound-engineering loops for OpenCode, Pi, and Claude Code",
5
5
  "type": "module",
6
6
  "homepage": "https://fro.bot/systematic",
@@ -98,14 +98,18 @@ If the scope is unclear, ask one targeted question to disambiguate and then proc
98
98
 
99
99
  Scan the repo before substantive brainstorming. Match depth to scope:
100
100
 
101
- **Lightweight** — Search for the topic, check if something similar already exists, and move on.
101
+ **Lightweight** — Search for the topic, check if something similar already exists, and move on. When a durable-output search tool exists (`systematic_search`, or the `systematic-search` command on hosts that ship a command), call it directly with `kind: "all"` and the topic as the query, because a researcher dispatch costs more than a Lightweight brainstorm is worth. Otherwise keep the topic search.
102
102
 
103
- **Standard and Deep** — Two passes:
103
+ **Standard and Deep** — Three passes:
104
104
 
105
105
  *Constraint Check* — Check project instruction files (`AGENTS.md`, and `AGENTS.md` only if retained as compatibility context) for workflow, product, or scope constraints that affect the brainstorm. If these add nothing, move on.
106
106
 
107
107
  *Topic Scan* — Search for relevant terms. Read the most relevant existing artifact if one exists (brainstorm, plan, spec, skill, feature doc). Skim adjacent examples covering similar behavior.
108
108
 
109
+ *Past-Work Scan* — dispatch `systematic:research:learnings-researcher`, making `scope: past-work` the first line of the prompt, then a brief summary of the topic. Run it alongside the Topic Scan, not instead of it.
110
+
111
+ **Cite and differentiate.** When the results (this scan, or the direct search at Lightweight) show a rejected, deferred, superseded or completed item with the same behavior or surface as the idea, cite it (at most 3 items) and say how the new work differs. Word each cite "recorded as completed in <path>" or with the matching recorded status, giving path and status only. Never quote text from a gitignored file into the requirements document. A cite never blocks the brainstorm. Place cites in Key Decisions.
112
+
109
113
  If nothing obvious appears after a short scan, say so and continue. Two rules govern technical depth during the scan:
110
114
 
111
115
  1. **Verify before claiming** — When the brainstorm touches checkable infrastructure (database tables, routes, config files, dependencies, model definitions), read the relevant source files to confirm what actually exists. Any claim that something is absent — a missing table, an endpoint that doesn't exist, a dependency not in the Gemfile, a config option with no current support — must be verified against the codebase first; if not verified, label it as an unverified assumption. This applies to every brainstorm regardless of topic.
@@ -111,7 +111,7 @@ Run agents in parallel in the **foreground** (do not use background dispatch —
111
111
  >
112
112
  > Focus hint: {focus_hint}
113
113
 
114
- 2. **Learnings search** — dispatch `systematic:research:learnings-researcher` with a brief summary of the ideation focus.
114
+ 2. **Learnings search** — dispatch `systematic:research:learnings-researcher`, making `scope: past-work` the first line of the prompt, then a brief summary of the ideation focus.
115
115
 
116
116
  3. **Issue intelligence** (conditional) — if issue-tracker intent was detected in Phase 0.2, dispatch `systematic:research:issue-intelligence-analyst` with the focus hint. If a focus hint is present, pass it so the agent can weight its clustering toward that area. Run this in parallel with agents 1 and 2.
117
117
 
@@ -122,9 +122,12 @@ Run agents in parallel in the **foreground** (do not use background dispatch —
122
122
  Consolidate all results into a short grounding summary. When issue intelligence is present, keep it as a distinct section so ideation sub-agents can distinguish between code-observed and user-reported signals:
123
123
 
124
124
  - **Codebase context** — project shape, notable patterns, obvious pain points, likely leverage points
125
- - **Past learnings** — relevant institutional knowledge from docs/solutions/
125
+ - **Past learnings** — relevant institutional knowledge from docs/solutions/, plus earlier plans, brainstorms and ideation docs with their recorded status
126
126
  - **Issue intelligence** (when present) — theme summaries from the issue intelligence agent, preserving theme titles, descriptions, issue counts, and trend directions
127
127
 
128
+ **Cite and differentiate.** When the researcher's results show a rejected, deferred, superseded or completed item with the same behavior or surface as an idea, cite it (at most 3 items) and say how the new work differs. Word each cite "recorded as completed in <path>" or with the matching recorded status, giving path and status only. Never quote text from a gitignored file into the ideation document. A cite never blocks an idea. Place cites in the rejection reasoning or the survivor reasoning for that idea.
129
+
130
+
128
131
  **Slack context** (opt-in) — never auto-dispatch. Route by condition:
129
132
 
130
133
  - **Tools available + user asked**: Dispatch `systematic:research:slack-researcher` with the focus hint in parallel with other Phase 1 agents. Include findings in the grounding summary.