pi-braid 0.43.9 → 0.43.12

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/CHANGELOG.md CHANGED
@@ -53,6 +53,54 @@ record; the tag scheme above applies unchanged.
53
53
 
54
54
  ---
55
55
 
56
+ ## Core — 0.43.12 (2026-11-01: a skill that says it is retired stops being advertised)
57
+
58
+ - **A retired skill no longer competes with its successor.** Four skills in the packs declare
59
+ `status: merged` and nothing read the declaration, so `code-search` was still listed beside
60
+ `code-refactoring` — two entries for one job, no sign which was current. A declared status of
61
+ `merged`, `archived` or `deprecated` now rides the exclusion the cache already had, so the catalog,
62
+ the suggestion whisper, the at-use line, both catalog accessors and `list_skills` agree without a
63
+ second concept. The file stays on disk and an explicit read of it still resolves: the skill stops
64
+ being advertised, it does not become unreadable. The status comes from the frontmatter parse the
65
+ trigger phrases already paid for, so no skill file is read a third time.
66
+ - **The budget gate it disturbed now tests the rule rather than its own reflection.** One existing
67
+ measurement asserted that every skill in the pack appears in one catalog page; with a retired skill
68
+ legitimately absent, the writer's first repair compared the page to the module's own accessor, which
69
+ is the same code on both sides and cannot catch a _wrong_ exclusion. The assertion instead derives the
70
+ expected population from the SKILL.md files themselves, so a skill retired for no reason in its
71
+ frontmatter reddens the gate. The seat verified that by planting one.
72
+
73
+ ## Core — 0.43.11 (2026-11-01: an owner ruling becomes findable, and the pointer rule stops licensing the skip)
74
+
75
+ - **The pointer rule no longer licenses skipping the read.** The sentence it carried — `The prompt already
76
+ covering the domain is the only reason to skip the read` — named the wrong test: a prompt that covers a
77
+ domain carries a description, a catalog line or an excerpt, and the body is what the agent is supposed
78
+ to read. So it authorised skipping in precisely the case where a summary and the body part company, and
79
+ it called that the _only_ reason, denying the legitimate one. It now reads `If the body itself is
80
+ already in this prompt you have read it; if you have only a description or an excerpt, you have not.` A
81
+ new fixture asserts this against the assembled prompt, reddens on three planted licences including the
82
+ retired sentence, and re-runs the whole check against a rebuilt copy of the module with the old
83
+ sentence restored. The behavioural effect is unmeasured and the report says so: this subsystem's claims
84
+ are structural until a probe with a control arm runs.
85
+ - **Owner rulings are filed where recall can reach them, and split by layer.** A backfill reads the
86
+ session corpus, decides which user turns are the owner stating a standing instruction, and writes each
87
+ one into the semantic store with a pointer that re-reads the original transcript line. The classifier
88
+ is split along the line the placement gate draws: the generic decision grammar stays in the memory
89
+ layer, and everything braid-shaped — whisper envelopes, a seat's dispatch anatomy, pasted-brief
90
+ headings, session machinery, role vocabulary — lives in the orchestration domain layer that already
91
+ owns those words. A generic layer holding them is what refused this work the first time, at nine
92
+ literal hits with the exclusion budget full.
93
+ - **A ruling's tags are derived from the store, because a flat bonus does not pay for rarity.** A
94
+ pre-registered measurement over ten questions found only three reachable answers and reached two of
95
+ them. The rule that did it is the opposite of the intuition: a tag's bonus is a constant, so how rare a
96
+ token is buys the entry nothing, and the only property worth maximising is whether a later question
97
+ names it — which is what store frequency measures. Measured against five control entries, both
98
+ reachable questions then hold rank one. The price is stated rather than hidden: across the twenty
99
+ questions that have an answer in the store, non-expected rulings appear in the top five 33 times
100
+ against 25 before, because a common tag fires on more queries. Four provenance scoring policies were
101
+ then measured as a replacement and none pays: they are inert on this store, and the one shape that
102
+ bites costs more noise and still leaves the target at rank two.
103
+
56
104
  ## Core — 0.43.9 (2026-10-31: a query is read as tokens, and the store can be told what to keep)
57
105
 
58
106
  - **A question could not match a word it contained.** Recall split a query on whitespace alone, so a
package/build-info.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "name": "pi-braid",
3
- "version": "0.43.9",
4
- "sha": "bce25581c535c3a318787d6c3a12b6beb76ff7ca",
5
- "shaShort": "bce25581",
3
+ "version": "0.43.12",
4
+ "sha": "f6a311a974d34f1d7cc70a491a8f5544e85dd233",
5
+ "shaShort": "f6a311a9",
6
6
  "branch": "detached",
7
7
  "dirty": false,
8
- "packedAt": "2026-10-31T15:50:23.130Z"
8
+ "packedAt": "2026-11-01T08:52:31.302Z"
9
9
  }
@@ -45,9 +45,10 @@ interface CachedSkill {
45
45
  package?: string;
46
46
  };
47
47
  /**
48
- * pi frontmatter flag: the skill is excluded from model selection and is
49
- * reachable only through its explicit /skill:name command. braid must keep
50
- * it out of the surfaces that advertise skills to the model.
48
+ * Excluded from model selection: pi's own frontmatter flag, or a status this
49
+ * cache reads as retired (see RETIRED_STATUSES). Either way braid keeps the
50
+ * skill out of the surfaces that advertise skills to the model, while the
51
+ * file stays on disk and an explicit read of it still resolves.
51
52
  */
52
53
  disableModelInvocation?: boolean;
53
54
  /** Frontmatter trigger phrases, resolved from SKILL.md at cache time. */
@@ -60,6 +61,13 @@ interface CachedSkill {
60
61
  * Resolves each skill's frontmatter trigger phrases here, once per turn:
61
62
  * the matcher scores triggers, pi's skill objects never carry them (fixed
62
63
  * shape), and the memoized read makes repeat turns stat-only.
64
+ *
65
+ * The same read answers the file's `status:`, and a retired status rides the
66
+ * `disableModelInvocation` exclusion rather than a second one: every surface
67
+ * that advertises skills already filters on that flag, so one derived field
68
+ * keeps the catalog, the whisper, the at-use line and the accessors in
69
+ * agreement. The row is still cached, so an explicit read of the file is still
70
+ * recognized — the skill stops being advertised, not becoming unreadable.
63
71
  */
64
72
  export declare function setCachedSkills(skills: CachedSkill[]): void;
65
73
  /**
@@ -35,25 +35,47 @@ import { Type } from "typebox";
35
35
  import { createLogger } from "../../../lib/core/logger.js";
36
36
  import { getSkillsInformMode, getSkillsRankingMode } from "../../../lib/config/braid-settings.js";
37
37
  import { registerAutoInject, updateSkillCache, getSkillStats, getDurableSkillStats, noteObligationListed, resolveDiscoveryMode, rankSkillsDeterministic, } from "./auto-inject.js";
38
- import { readSkillTriggerEntries } from "./skill-triggers.js";
38
+ import { readSkillFrontmatter } from "./skill-triggers.js";
39
39
  import { readGovernedFamilies } from "./skill-families.js";
40
40
  import { clampSectionsMax, DEFAULT_SECTIONS_MAX, SECTIONS_MAX_LIMIT, readSkillReach, } from "./reach.js";
41
41
  import { getInformRate, getMonthlyAdoptionRollup, getObligationRate, getSessionApplicability, getSessionObligation, judgeSessionObligations, } from "./session-records.js";
42
42
  import { checkArgumentValues } from "../../../lib/utils/argument-report.js";
43
43
  const log = createLogger("skills-tool");
44
44
  let cachedSkills = [];
45
+ /**
46
+ * Statuses that mean the skill is no longer the place to look: its content
47
+ * lives in a successor, or the file is kept as history. The vocabulary is the
48
+ * pack's (a `status:` frontmatter key), and the exclusion is this module's:
49
+ * no file is deleted, renamed or edited to make a skill stop being advertised.
50
+ */
51
+ const RETIRED_STATUSES = new Set(["merged", "archived", "deprecated"]);
52
+ /** Whether a declared status retires the skill from model selection. */
53
+ function isRetiredStatus(status) {
54
+ return RETIRED_STATUSES.has(status);
55
+ }
45
56
  /**
46
57
  * Called from prompt-builder's before_agent_start to populate the cache.
47
58
  * Resolves each skill's frontmatter trigger phrases here, once per turn:
48
59
  * the matcher scores triggers, pi's skill objects never carry them (fixed
49
60
  * shape), and the memoized read makes repeat turns stat-only.
61
+ *
62
+ * The same read answers the file's `status:`, and a retired status rides the
63
+ * `disableModelInvocation` exclusion rather than a second one: every surface
64
+ * that advertises skills already filters on that flag, so one derived field
65
+ * keeps the catalog, the whisper, the at-use line and the accessors in
66
+ * agreement. The row is still cached, so an explicit read of the file is still
67
+ * recognized — the skill stops being advertised, not becoming unreadable.
50
68
  */
51
69
  export function setCachedSkills(skills) {
70
+ let retired = 0;
52
71
  cachedSkills = skills.map((s) => {
53
- const entries = readSkillTriggerEntries(s.filePath, s.description);
72
+ const { entries, status } = readSkillFrontmatter(s.filePath, s.description);
54
73
  const triggerSources = {};
55
74
  for (const entry of entries)
56
75
  triggerSources[entry.phrase] = entry.source;
76
+ const isRetired = isRetiredStatus(status);
77
+ if (isRetired)
78
+ retired++;
57
79
  return {
58
80
  ...s,
59
81
  triggers: entries.map((entry) => entry.phrase),
@@ -62,11 +84,13 @@ export function setCachedSkills(skills) {
62
84
  // frontmatter read the phrases come from (one extra parse per file per
63
85
  // process). An empty list is a declaration of no family, not a miss.
64
86
  families: readGovernedFamilies(s.filePath),
87
+ disableModelInvocation: s.disableModelInvocation === true || isRetired,
65
88
  };
66
89
  });
67
90
  // Sync with auto-inject subsystem (enriched cache — triggers ride along)
68
91
  updateSkillCache(cachedSkills);
69
- log.debug(`Cached ${skills.length} skills for list_skills tool`);
92
+ log.debug(`Cached ${skills.length} skills for list_skills tool` +
93
+ (retired ? ` (${retired} retired by status)` : ""));
70
94
  }
71
95
  /**
72
96
  * The installed visible skill names — the same set the list_skills catalog
@@ -51,8 +51,8 @@ export interface CatalogEntry {
51
51
  * the honest answer when the paths cannot be derived.
52
52
  */
53
53
  export declare function skillsCatalogRule(readRoot: string, grouped?: boolean): string;
54
- /** Paragraph 2: the pointer rule (pinned verbatim by test-prompt-budget.mjs). */
55
- export declare const SKILLS_POINTER_RULE = "Pointer rule: the catalog one-liner is metadata, not content \u2014 the SKILL.md path is the knowledge. The prompt already covering the domain is the only reason to skip the read.";
54
+ /** Paragraph 2: the pointer rule, exported so a fixture can pin its text. */
55
+ export declare const SKILLS_POINTER_RULE = "Pointer rule: the catalog one-liner is metadata, not content \u2014 the SKILL.md path is the knowledge. If the body itself is already in this prompt you have read it; if you have only a description or an excerpt, you have not.";
56
56
  /** One directory a catalog's bodies live in, with the skills filed under it. */
57
57
  export interface CatalogGroup {
58
58
  /** The pack directory itself, in forward-slash form. */
@@ -54,8 +54,8 @@ export function skillsCatalogRule(readRoot, grouped = false) {
54
54
  : "";
55
55
  return `This catalog is every installed skill: one row per skill, name and description.${readPath} When the task enters a listed skill's domain, read the WHOLE SKILL.md before acting in that domain; never act from memory of a skill's contents.`;
56
56
  }
57
- /** Paragraph 2: the pointer rule (pinned verbatim by test-prompt-budget.mjs). */
58
- export const SKILLS_POINTER_RULE = `Pointer rule: the catalog one-liner is metadata, not content — the SKILL.md path is the knowledge. The prompt already covering the domain is the only reason to skip the read.`;
57
+ /** Paragraph 2: the pointer rule, exported so a fixture can pin its text. */
58
+ export const SKILLS_POINTER_RULE = `Pointer rule: the catalog one-liner is metadata, not content — the SKILL.md path is the knowledge. If the body itself is already in this prompt you have read it; if you have only a description or an excerpt, you have not.`;
59
59
  const MECHANICAL_TRIGGER_LEAD = `Mechanical trigger, no judgment call: about to use a tool family whose word appears in a skill's name`;
60
60
  const MECHANICAL_TRIGGER_TAIL = `→ read that SKILL.md before the first call in the family.`;
61
61
  /** Forward-slash form of a path, for segment arithmetic on either platform. */
@@ -28,6 +28,12 @@
28
28
  * capitalized ("MASTERSHIP TRANSFER: …"), and a phrase that only matched
29
29
  * lowercase text would be dead in production while a lowercase-only unit
30
30
  * fixture kept the suite green.
31
+ *
32
+ * The same parse also returns the file's declared lifecycle `status`, which is
33
+ * NOT matcher input: the skills-tool needs it once per file, at cache time, to
34
+ * decide whether the skill is still advertised. It rides this read because the
35
+ * file is already open here — a reader of its own would be a third read of the
36
+ * same bytes per process, and a status is not worth one.
31
37
  */
32
38
  /**
33
39
  * Max trigger phrases read per skill — a longer list is an authoring bug, not a
@@ -51,6 +57,15 @@ export interface TriggerEntry {
51
57
  phrase: string;
52
58
  source: TriggerSource;
53
59
  }
60
+ /**
61
+ * One SKILL.md's trigger phrases plus the lifecycle status its frontmatter
62
+ * declares — everything one parse of the file answers.
63
+ */
64
+ export interface SkillFrontmatterRead {
65
+ entries: TriggerEntry[];
66
+ /** Lowercased `status:` token, or "" when the file declares none. */
67
+ status: string;
68
+ }
54
69
  /**
55
70
  * Normalize a frontmatter `triggers` value into clean phrases. Accepts a YAML
56
71
  * list or a comma-separated string; drops empty, overlong, and surplus
@@ -76,6 +91,13 @@ export declare function readSkillTriggers(filePath: string, description?: string
76
91
  * a miss, because the merged list depends on it).
77
92
  */
78
93
  export declare function readSkillTriggerEntries(filePath: string, description?: string): TriggerEntry[];
94
+ /**
95
+ * Read a skill's trigger phrases WITH their provenance plus its declared
96
+ * lifecycle status, from one memoized parse. Same sources, precedence and
97
+ * memoization as readSkillTriggerEntries; the status is the frontmatter key of
98
+ * that name, lowercased, "" when absent or unreadable.
99
+ */
100
+ export declare function readSkillFrontmatter(filePath: string, description?: string): SkillFrontmatterRead;
79
101
  /**
80
102
  * Merge authored phrase sources into one bounded list, in priority order.
81
103
  *
@@ -28,6 +28,12 @@
28
28
  * capitalized ("MASTERSHIP TRANSFER: …"), and a phrase that only matched
29
29
  * lowercase text would be dead in production while a lowercase-only unit
30
30
  * fixture kept the suite green.
31
+ *
32
+ * The same parse also returns the file's declared lifecycle `status`, which is
33
+ * NOT matcher input: the skills-tool needs it once per file, at cache time, to
34
+ * decide whether the skill is still advertised. It rides this read because the
35
+ * file is already open here — a reader of its own would be a third read of the
36
+ * same bytes per process, and a status is not worth one.
31
37
  */
32
38
  import { statSync, readFileSync } from "node:fs";
33
39
  import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
@@ -76,6 +82,14 @@ export function normalizeTriggers(value) {
76
82
  export function readSkillTriggers(filePath, description) {
77
83
  return readSkillTriggerEntries(filePath, description).map((entry) => entry.phrase);
78
84
  }
85
+ /**
86
+ * Normalize a frontmatter `status` value into the token a caller matches on.
87
+ * Only a string is a declaration: a missing key, a null, or a nested shape is
88
+ * the absence of one. Pure.
89
+ */
90
+ function normalizeSkillStatus(value) {
91
+ return typeof value === "string" ? value.trim().toLowerCase() : "";
92
+ }
79
93
  /**
80
94
  * Read a skill's authored phrases WITH their provenance, merged in priority
81
95
  * order: frontmatter (`trigger` or `triggers`), then a `## trigger:` body
@@ -86,6 +100,15 @@ export function readSkillTriggers(filePath, description) {
86
100
  * a miss, because the merged list depends on it).
87
101
  */
88
102
  export function readSkillTriggerEntries(filePath, description) {
103
+ return readSkillFrontmatter(filePath, description).entries;
104
+ }
105
+ /**
106
+ * Read a skill's trigger phrases WITH their provenance plus its declared
107
+ * lifecycle status, from one memoized parse. Same sources, precedence and
108
+ * memoization as readSkillTriggerEntries; the status is the frontmatter key of
109
+ * that name, lowercased, "" when absent or unreadable.
110
+ */
111
+ export function readSkillFrontmatter(filePath, description) {
89
112
  const desc = description ?? "";
90
113
  let st;
91
114
  try {
@@ -93,20 +116,22 @@ export function readSkillTriggerEntries(filePath, description) {
93
116
  }
94
117
  catch {
95
118
  cache.delete(filePath);
96
- return [];
119
+ return { entries: [], status: "" };
97
120
  }
98
121
  const cached = cache.get(filePath);
99
122
  if (cached &&
100
123
  cached.mtimeMs === st.mtimeMs &&
101
124
  cached.size === st.size &&
102
125
  cached.description === desc) {
103
- return cached.entries;
126
+ return { entries: cached.entries, status: cached.status };
104
127
  }
105
128
  const sources = [];
129
+ let status = "";
106
130
  try {
107
131
  const { frontmatter, body } = parseFrontmatter(readFileSync(filePath, "utf-8"));
108
132
  const fm = frontmatter;
109
133
  const label = (source) => (phrase) => ({ phrase, source });
134
+ status = normalizeSkillStatus(fm.status);
110
135
  sources.push(normalizeTriggers(fm.trigger).map(label("frontmatter")), normalizeTriggers(fm.triggers).map(label("frontmatter")), parseBodyTriggers(body).map(label("heading")));
111
136
  }
112
137
  catch {
@@ -116,8 +141,8 @@ export function readSkillTriggerEntries(filePath, description) {
116
141
  if (desc)
117
142
  sources.push(parseDescriptionTriggers(desc).map((phrase) => ({ phrase, source: "description" })));
118
143
  const entries = mergeTriggerEntries(sources);
119
- cache.set(filePath, { mtimeMs: st.mtimeMs, size: st.size, description: desc, entries });
120
- return entries;
144
+ cache.set(filePath, { mtimeMs: st.mtimeMs, size: st.size, description: desc, entries, status });
145
+ return { entries, status };
121
146
  }
122
147
  /**
123
148
  * Merge authored phrase sources into one bounded list, in priority order.
@@ -0,0 +1,94 @@
1
+ /**
2
+ * Decision grammar: the generic half of the ruling write path.
3
+ *
4
+ * One body of text in, either the standing instruction it carries or `null`.
5
+ * "Generic" is a claim about what the module is allowed to know: sentence
6
+ * spans, the marker table that turns a sentence into a standing instruction,
7
+ * the shapes that are not instructions (a question, a status report, a paste, a
8
+ * hedge, a conversational aside), and the first- and second-person grammar of
9
+ * English. It knows nothing about who wrote the text, which channel carried it,
10
+ * or what the caller's world is made of.
11
+ *
12
+ * The last of those is the one thing a grammar cannot supply, so the caller
13
+ * hands it in as `GrammarVocabulary`: which words name a subject a ruling can be
14
+ * about, which words describe the caller's own machinery, and how an explicit
15
+ * generalization reads. `classifyRulingBody()` applies those three tests at the
16
+ * same two places it applies its own - the turn and the sentence that gets
17
+ * quoted - so a directive aimed at the reader is told apart from a rule about
18
+ * the system by vocabulary this layer never spells.
19
+ *
20
+ * The second half of the module is the store side of the same write path:
21
+ * `deriveTopicTags()` reads a quote and the population it is filed into and
22
+ * returns the words worth carrying as tags. The rule reasons about tokens,
23
+ * document frequency and a generic English stop list, so it belongs next to the
24
+ * grammar rather than in the caller's vocabulary.
25
+ *
26
+ * Pure by construction: no I/O, no clock, no randomness, so its behaviour is a
27
+ * fixture instead of a story.
28
+ */
29
+ /** The closed set of ruling shapes the classifier can name. */
30
+ export type RulingClass = "prohibition" | "preference" | "requirement" | "policy";
31
+ /** A classified body: what kind of instruction it is, and the words to keep. */
32
+ export interface RulingShape {
33
+ class: RulingClass;
34
+ /** A contiguous, verbatim slice of the body, capped with a trailing ellipsis. */
35
+ quote: string;
36
+ }
37
+ /**
38
+ * The three questions a grammar has to ask the caller's world.
39
+ *
40
+ * `namesSubject` is the escape hatch for a bare directive: "Do not read or
41
+ * write files." names no system, so without first person it is an instruction
42
+ * aimed at the reader, not a rule about anything. `talksProcess` refuses a body
43
+ * whose subject is the caller's own machinery rather than the thing a ruling is
44
+ * about, and `generalizes` admits a second-person body that says it speaks to
45
+ * every recipient ("any instance", "generically"), which is a rule rather than
46
+ * a steer.
47
+ */
48
+ export interface GrammarVocabulary {
49
+ namesSubject(text: string): boolean;
50
+ talksProcess(text: string): boolean;
51
+ generalizes(text: string): boolean;
52
+ }
53
+ /** Longest quote the caller receives; past this the quote is cut, not summarized. */
54
+ export declare const QUOTE_LIMIT = 400;
55
+ /**
56
+ * Classify one body that is already known to be owner speech.
57
+ *
58
+ * Returns `null` for everything that is not a standing instruction: a question,
59
+ * a paste, a status report, a hedged recommendation, an acknowledgement, a
60
+ * second-person directive, or a body too long to cut a self-contained sentence
61
+ * from. Returns the class and the verbatim quote otherwise. The caller owns the
62
+ * provenance fields, because the caller is the one that knows where the text
63
+ * came from.
64
+ */
65
+ export declare function classifyRulingBody(text: string, vocabulary: GrammarVocabulary): RulingShape | null;
66
+ /** How many tags a ruling carries. */
67
+ export declare const TAG_LIMIT = 3;
68
+ /**
69
+ * The population a quote is filed into, as the frequency test sees it:
70
+ * how many documents it holds, and how many of them carry a token.
71
+ */
72
+ export interface TagPopulation {
73
+ /** Documents in the population. */
74
+ total: number;
75
+ /** Documents carrying `token`. */
76
+ count(token: string): number;
77
+ }
78
+ /**
79
+ * The tags a quote earns from the population it is filed into.
80
+ *
81
+ * Take the quote's tokens of four characters or more, drop the read path's stop
82
+ * words, drop any token more than a quarter of the population carries, and keep
83
+ * the three the population carries most, ties by first occurrence.
84
+ *
85
+ * The ranking is by frequency and not by rarity, and the reason is the read
86
+ * path's own arithmetic: a tag's bonus is a flat constant however rare the
87
+ * token is, so rarity buys nothing a later query will say. Two tokens of equal
88
+ * rarity are worth the same as tags, and the one a question is likelier to name
89
+ * is the one the population's own prose uses more often. That makes the
90
+ * frequency ranking the findability ranking, and it leaves the 25% cap as the
91
+ * only guard against a tag that names nothing.
92
+ */
93
+ export declare function deriveTopicTags(text: string, population: TagPopulation, limit?: number): string[];
94
+ //# sourceMappingURL=decision-grammar.d.ts.map