@fro.bot/systematic 3.28.0 → 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.
@@ -1,6 +1,7 @@
1
1
  /**
2
2
  * Corpus loader for durable-output search: project root, `kind` table, safe
3
- * walk of `docs/solutions/` and a narrowing wrapper around `parseFrontmatter`.
3
+ * walk of one kind's docs directory and a narrowing wrapper around
4
+ * `parseFrontmatter`.
4
5
  *
5
6
  * Reads from disk on every call and keeps no memo, because `ce:compound`
6
7
  * searches right after it writes. Never throws: every filesystem failure
@@ -17,8 +18,10 @@ export declare const MAX_DEPTH = 6;
17
18
  /** Total bytes of text loaded per call. */
18
19
  export declare const MAX_TOTAL_BYTES: number;
19
20
  /**
20
- * One entry per document kind. Release 1 indexes `docs/solutions/` only; a new
21
- * kind (plans, brainstorms) is a new entry here plus its frontmatter fit.
21
+ * One entry per document kind. Every Markdown file under a kind's directory
22
+ * counts, except a README and anything under `_archived/`. The loader reads the
23
+ * filesystem and never consults git, so a gitignored directory loads like a
24
+ * tracked one. A new kind is a new entry here plus its frontmatter fit.
22
25
  */
23
26
  export declare const KIND_TABLE: {
24
27
  readonly solution: {
@@ -27,6 +30,24 @@ export declare const KIND_TABLE: {
27
30
  readonly excludedDirs: readonly ["_archived"];
28
31
  readonly lifecycle: true;
29
32
  };
33
+ readonly plan: {
34
+ readonly dir: 'docs/plans';
35
+ readonly excludedFiles: readonly ["readme.md"];
36
+ readonly excludedDirs: readonly ["_archived"];
37
+ readonly lifecycle: true;
38
+ };
39
+ readonly brainstorm: {
40
+ readonly dir: 'docs/brainstorms';
41
+ readonly excludedFiles: readonly ["readme.md"];
42
+ readonly excludedDirs: readonly ["_archived"];
43
+ readonly lifecycle: true;
44
+ };
45
+ readonly ideation: {
46
+ readonly dir: 'docs/ideation';
47
+ readonly excludedFiles: readonly ["readme.md"];
48
+ readonly excludedDirs: readonly ["_archived"];
49
+ readonly lifecycle: true;
50
+ };
30
51
  };
31
52
  export type DocumentKind = keyof typeof KIND_TABLE;
32
53
  export declare function isDocumentKind(value: unknown): value is DocumentKind;
@@ -48,7 +69,7 @@ export interface CorpusDocument {
48
69
  /** Root-relative path with `/` separators. */
49
70
  readonly path: string;
50
71
  readonly kind: DocumentKind;
51
- /** The `title` field, else the file name without `.md`. */
72
+ /** The first non-empty string of `title`, `topic`, then the file name without `.md`. */
52
73
  readonly title: string;
53
74
  readonly tags: readonly string[];
54
75
  readonly module: string | undefined;
@@ -90,11 +111,11 @@ export type ParsedDocument = {
90
111
  readonly reason: string;
91
112
  };
92
113
  /**
93
- * Parse one file. Wraps `parseFrontmatter` (which stays unedited): strips a
94
- * leading BOM, supplies the newline its regex needs when the closing `---` is
95
- * the last line, and reads only known fields, narrowing each. No frontmatter
96
- * means a body-only document with no warning. Invalid YAML, or a frontmatter
97
- * block that is not a mapping, is not indexable.
114
+ * Parse one file. Wraps `parseFrontmatter`: strips a leading BOM, supplies the
115
+ * newline its regex needs when the closing `---` is the last line, and reads
116
+ * only known fields, narrowing each. No frontmatter means a body-only document
117
+ * with no warning. Invalid YAML, or a frontmatter block that is not a mapping,
118
+ * is not indexable.
98
119
  */
99
120
  export declare function parseCorpusDocument(kind: DocumentKind, relativePath: string, content: string): ParsedDocument;
100
121
  /**
@@ -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
@@ -4202,8 +4322,16 @@ function extractRawToolsSource(data, sourceFile) {
4202
4322
  }
4203
4323
  return trimmed;
4204
4324
  }
4325
+ var QUALIFIED_PERSONA_NAME = /^systematic:([^:]+):([^:]+)$/;
4205
4326
  function resolveAgent(catalog, name) {
4206
- return catalog.find((entry) => entry.name === name);
4327
+ const exact = catalog.find((entry) => entry.name === name);
4328
+ if (exact)
4329
+ return exact;
4330
+ const qualified = QUALIFIED_PERSONA_NAME.exec(name);
4331
+ if (!qualified)
4332
+ return;
4333
+ const [, category, flatName] = qualified;
4334
+ return catalog.find((entry) => entry.name === flatName && entry.category === category);
4207
4335
  }
4208
4336
  var DEFAULT_READONLY_TOOLS = [
4209
4337
  "read",
@@ -12221,11 +12349,12 @@ function resolvePersonaRouting(persona, agentName, ctx, routing) {
12221
12349
  return { model: resolvedModel, thinkingLevel, notice, commitNotice };
12222
12350
  }
12223
12351
  function validateDelegateRequest(catalog, params, ctx, routing) {
12224
- const { agent: agentName, task } = params;
12225
- const persona = resolveAgent(catalog, agentName);
12352
+ const { agent: requestedName, task } = params;
12353
+ const persona = resolveAgent(catalog, requestedName);
12226
12354
  if (!persona) {
12227
- throw new Error(`Unknown persona "${agentName}". Available personas: ${catalog.map((e) => e.name).join(", ")}`);
12355
+ throw new Error(`Unknown persona "${requestedName}". Available personas: ${catalog.map((e) => e.name).join(", ")}`);
12228
12356
  }
12357
+ const agentName = persona.name;
12229
12358
  const { model, thinkingLevel, notice, commitNotice } = resolvePersonaRouting(persona, agentName, ctx, routing);
12230
12359
  let allowedToolNames;
12231
12360
  try {
@@ -12657,7 +12786,7 @@ function createPiSearchTool(options) {
12657
12786
  name: SEARCH_TOOL_NAME,
12658
12787
  label: "Systematic Search",
12659
12788
  description: SEARCH_TOOL_DESCRIPTION,
12660
- 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.',
12661
12790
  parameters: buildPiParameters(Type),
12662
12791
  async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
12663
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.0",
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",
@@ -117,8 +117,8 @@
117
117
  "devDependencies": {
118
118
  "@biomejs/biome": "2.6.3",
119
119
  "@earendil-works/pi-coding-agent": "1.4.0",
120
- "@opencode-ai/plugin": "1.19.4",
121
- "@opencode-ai/sdk": "1.19.4",
120
+ "@opencode-ai/plugin": "1.19.5",
121
+ "@opencode-ai/sdk": "1.19.5",
122
122
  "@opencode/client": "2.2.0",
123
123
  "@opencode/plugin": "2.2.0",
124
124
  "@opencode/sdk": "2.2.0",