pi-braid 0.43.11 → 0.43.16
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 +39 -0
- package/build-info.json +4 -4
- package/dist/extensions/core/skills-tool/index.d.ts +11 -3
- package/dist/extensions/core/skills-tool/index.js +27 -3
- package/dist/extensions/core/skills-tool/skill-triggers.d.ts +43 -9
- package/dist/extensions/core/skills-tool/skill-triggers.js +50 -13
- package/docs/LOCAL_DEV.md +1 -1
- package/package.json +1 -1
- package/src/extensions/core/AGENTS.md +1 -0
- package/src/extensions/core/skills-tool/index.ts +34 -6
- package/src/extensions/core/skills-tool/skill-triggers.ts +64 -13
package/CHANGELOG.md
CHANGED
|
@@ -53,6 +53,45 @@ record; the tag scheme above applies unchanged.
|
|
|
53
53
|
|
|
54
54
|
---
|
|
55
55
|
|
|
56
|
+
## Core — 0.43.16 (2026-11-02: a skill stops claiming phrases the reader throws away)
|
|
57
|
+
|
|
58
|
+
- **The trigger caps now fit what authors actually write, and a violation fails loudly.** The reader kept
|
|
59
|
+
12 phrases per skill and dropped the rest in silence, so three skills were claiming words that could
|
|
60
|
+
never match: `braid-reference` authored 16, `pi-reference` 15, `voice-replies` 13, and
|
|
61
|
+
`subagent-verification` had a 66-character phrase against a 64 cap. A question about `polyfill` or
|
|
62
|
+
`braid install paths` did not reach the skill that advertises it. The caps are 16 and 66, and the
|
|
63
|
+
justification is measured rather than argued: a phrase compiles to one word-bounded substring test over
|
|
64
|
+
the prompt, reaches no prompt, and costs the same at any length — 4.35 µs at 50 characters, 4.34 at 66,
|
|
65
|
+
4.32 at 98. So the old numbers bounded shape, not hazard, and the shape they bounded was wrong. A new
|
|
66
|
+
fixture reads the authored files itself and fails naming a skill that overflows, because the reader
|
|
67
|
+
cannot answer the question once the cap has already spent the list.
|
|
68
|
+
- **The TypeBox surface is pinned to JSON Schema, so the announced pi-schema swap stays an import edit.**
|
|
69
|
+
A fixture refuses any constructor outside the eight the tree uses, the six features JSON Schema cannot
|
|
70
|
+
carry, and any imported symbol beyond `Type` and a type-only `Static`. The point is timing: the way a
|
|
71
|
+
mechanical swap becomes a rewrite is somebody reaching for `Type.Refine` for a good local reason six
|
|
72
|
+
weeks before the dependency moves.
|
|
73
|
+
- **The skills block is priced the way an agent reads it.** The only gate that priced it measured one
|
|
74
|
+
pack; an agent reads the union. Every pack is now discovered from its manifest, each prices separately,
|
|
75
|
+
and one composition over the union prints the total, with controls proving the number moves when a row
|
|
76
|
+
moves and that the union is never the sum of separate renders.
|
|
77
|
+
|
|
78
|
+
## Core — 0.43.12 (2026-11-01: a skill that says it is retired stops being advertised)
|
|
79
|
+
|
|
80
|
+
- **A retired skill no longer competes with its successor.** Four skills in the packs declare
|
|
81
|
+
`status: merged` and nothing read the declaration, so `code-search` was still listed beside
|
|
82
|
+
`code-refactoring` — two entries for one job, no sign which was current. A declared status of
|
|
83
|
+
`merged`, `archived` or `deprecated` now rides the exclusion the cache already had, so the catalog,
|
|
84
|
+
the suggestion whisper, the at-use line, both catalog accessors and `list_skills` agree without a
|
|
85
|
+
second concept. The file stays on disk and an explicit read of it still resolves: the skill stops
|
|
86
|
+
being advertised, it does not become unreadable. The status comes from the frontmatter parse the
|
|
87
|
+
trigger phrases already paid for, so no skill file is read a third time.
|
|
88
|
+
- **The budget gate it disturbed now tests the rule rather than its own reflection.** One existing
|
|
89
|
+
measurement asserted that every skill in the pack appears in one catalog page; with a retired skill
|
|
90
|
+
legitimately absent, the writer's first repair compared the page to the module's own accessor, which
|
|
91
|
+
is the same code on both sides and cannot catch a _wrong_ exclusion. The assertion instead derives the
|
|
92
|
+
expected population from the SKILL.md files themselves, so a skill retired for no reason in its
|
|
93
|
+
frontmatter reddens the gate. The seat verified that by planting one.
|
|
94
|
+
|
|
56
95
|
## Core — 0.43.11 (2026-11-01: an owner ruling becomes findable, and the pointer rule stops licensing the skip)
|
|
57
96
|
|
|
58
97
|
- **The pointer rule no longer licenses skipping the read.** The sentence it carried — `The prompt already
|
package/build-info.json
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.43.
|
|
4
|
-
"sha": "
|
|
5
|
-
"shaShort": "
|
|
3
|
+
"version": "0.43.16",
|
|
4
|
+
"sha": "22a4c1c3ef6d7a1f50a6877810d635eabb021ce1",
|
|
5
|
+
"shaShort": "22a4c1c3",
|
|
6
6
|
"branch": "detached",
|
|
7
7
|
"dirty": false,
|
|
8
|
-
"packedAt": "2026-11-
|
|
8
|
+
"packedAt": "2026-11-02T00:28:28.254Z"
|
|
9
9
|
}
|
|
@@ -45,9 +45,10 @@ interface CachedSkill {
|
|
|
45
45
|
package?: string;
|
|
46
46
|
};
|
|
47
47
|
/**
|
|
48
|
-
*
|
|
49
|
-
*
|
|
50
|
-
*
|
|
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 {
|
|
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 =
|
|
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
|
|
@@ -28,18 +28,36 @@
|
|
|
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
|
-
* Max trigger phrases
|
|
34
|
-
*
|
|
35
|
-
*
|
|
36
|
-
*
|
|
37
|
-
*
|
|
38
|
-
*
|
|
39
|
+
* Max trigger phrases kept per skill: a budget, spent down the merged list so
|
|
40
|
+
* the lowest-priority source loses first. Past it the reader drops the tail and
|
|
41
|
+
* reports nothing, which is why test-trigger-cap.mjs reads the authored files
|
|
42
|
+
* itself and fails by name: a claim past the cap is a build failure, not a
|
|
43
|
+
* silent loss.
|
|
44
|
+
*
|
|
45
|
+
* It bounds what one file may claim, not what a turn may spend. A phrase costs
|
|
46
|
+
* one word-bounded regex test over the prompt per turn (`triggerMatches`, from
|
|
47
|
+
* the suggestion matcher and the applicability pass) — flat in the phrase,
|
|
48
|
+
* linear in the prompt — so the ceiling is about shape: a list this long is a
|
|
49
|
+
* page of situations, and a longer one is a description in disguise.
|
|
39
50
|
*/
|
|
40
|
-
export declare const MAX_TRIGGERS =
|
|
41
|
-
/**
|
|
42
|
-
|
|
51
|
+
export declare const MAX_TRIGGERS = 16;
|
|
52
|
+
/**
|
|
53
|
+
* Max characters of one trigger phrase. A phrase compiles to a literal,
|
|
54
|
+
* word-bounded substring test: it reaches no prompt and costs the same at any
|
|
55
|
+
* length, so this is a shape bound rather than a hazard bound. A string long
|
|
56
|
+
* enough to be a sentence is a condition, and it matches only a prompt that
|
|
57
|
+
* carries that sentence verbatim. The bound sits above the longest shipped
|
|
58
|
+
* phrase, and test-trigger-cap.mjs fails by name past it.
|
|
59
|
+
*/
|
|
60
|
+
export declare const MAX_TRIGGER_CHARS = 66;
|
|
43
61
|
/**
|
|
44
62
|
* Where an authored phrase came from. Precedence (frontmatter, heading,
|
|
45
63
|
* description) orders the merged list and decides which source the cap cuts
|
|
@@ -51,6 +69,15 @@ export interface TriggerEntry {
|
|
|
51
69
|
phrase: string;
|
|
52
70
|
source: TriggerSource;
|
|
53
71
|
}
|
|
72
|
+
/**
|
|
73
|
+
* One SKILL.md's trigger phrases plus the lifecycle status its frontmatter
|
|
74
|
+
* declares — everything one parse of the file answers.
|
|
75
|
+
*/
|
|
76
|
+
export interface SkillFrontmatterRead {
|
|
77
|
+
entries: TriggerEntry[];
|
|
78
|
+
/** Lowercased `status:` token, or "" when the file declares none. */
|
|
79
|
+
status: string;
|
|
80
|
+
}
|
|
54
81
|
/**
|
|
55
82
|
* Normalize a frontmatter `triggers` value into clean phrases. Accepts a YAML
|
|
56
83
|
* list or a comma-separated string; drops empty, overlong, and surplus
|
|
@@ -76,6 +103,13 @@ export declare function readSkillTriggers(filePath: string, description?: string
|
|
|
76
103
|
* a miss, because the merged list depends on it).
|
|
77
104
|
*/
|
|
78
105
|
export declare function readSkillTriggerEntries(filePath: string, description?: string): TriggerEntry[];
|
|
106
|
+
/**
|
|
107
|
+
* Read a skill's trigger phrases WITH their provenance plus its declared
|
|
108
|
+
* lifecycle status, from one memoized parse. Same sources, precedence and
|
|
109
|
+
* memoization as readSkillTriggerEntries; the status is the frontmatter key of
|
|
110
|
+
* that name, lowercased, "" when absent or unreadable.
|
|
111
|
+
*/
|
|
112
|
+
export declare function readSkillFrontmatter(filePath: string, description?: string): SkillFrontmatterRead;
|
|
79
113
|
/**
|
|
80
114
|
* Merge authored phrase sources into one bounded list, in priority order.
|
|
81
115
|
*
|
|
@@ -28,20 +28,38 @@
|
|
|
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";
|
|
34
40
|
/**
|
|
35
|
-
* Max trigger phrases
|
|
36
|
-
*
|
|
37
|
-
*
|
|
38
|
-
*
|
|
39
|
-
*
|
|
40
|
-
*
|
|
41
|
+
* Max trigger phrases kept per skill: a budget, spent down the merged list so
|
|
42
|
+
* the lowest-priority source loses first. Past it the reader drops the tail and
|
|
43
|
+
* reports nothing, which is why test-trigger-cap.mjs reads the authored files
|
|
44
|
+
* itself and fails by name: a claim past the cap is a build failure, not a
|
|
45
|
+
* silent loss.
|
|
46
|
+
*
|
|
47
|
+
* It bounds what one file may claim, not what a turn may spend. A phrase costs
|
|
48
|
+
* one word-bounded regex test over the prompt per turn (`triggerMatches`, from
|
|
49
|
+
* the suggestion matcher and the applicability pass) — flat in the phrase,
|
|
50
|
+
* linear in the prompt — so the ceiling is about shape: a list this long is a
|
|
51
|
+
* page of situations, and a longer one is a description in disguise.
|
|
52
|
+
*/
|
|
53
|
+
export const MAX_TRIGGERS = 16;
|
|
54
|
+
/**
|
|
55
|
+
* Max characters of one trigger phrase. A phrase compiles to a literal,
|
|
56
|
+
* word-bounded substring test: it reaches no prompt and costs the same at any
|
|
57
|
+
* length, so this is a shape bound rather than a hazard bound. A string long
|
|
58
|
+
* enough to be a sentence is a condition, and it matches only a prompt that
|
|
59
|
+
* carries that sentence verbatim. The bound sits above the longest shipped
|
|
60
|
+
* phrase, and test-trigger-cap.mjs fails by name past it.
|
|
41
61
|
*/
|
|
42
|
-
export const
|
|
43
|
-
/** Max characters of one trigger phrase. */
|
|
44
|
-
export const MAX_TRIGGER_CHARS = 64;
|
|
62
|
+
export const MAX_TRIGGER_CHARS = 66;
|
|
45
63
|
const cache = new Map();
|
|
46
64
|
/** Compiled word-boundary matchers, memoized per normalized phrase. */
|
|
47
65
|
const regexCache = new Map();
|
|
@@ -76,6 +94,14 @@ export function normalizeTriggers(value) {
|
|
|
76
94
|
export function readSkillTriggers(filePath, description) {
|
|
77
95
|
return readSkillTriggerEntries(filePath, description).map((entry) => entry.phrase);
|
|
78
96
|
}
|
|
97
|
+
/**
|
|
98
|
+
* Normalize a frontmatter `status` value into the token a caller matches on.
|
|
99
|
+
* Only a string is a declaration: a missing key, a null, or a nested shape is
|
|
100
|
+
* the absence of one. Pure.
|
|
101
|
+
*/
|
|
102
|
+
function normalizeSkillStatus(value) {
|
|
103
|
+
return typeof value === "string" ? value.trim().toLowerCase() : "";
|
|
104
|
+
}
|
|
79
105
|
/**
|
|
80
106
|
* Read a skill's authored phrases WITH their provenance, merged in priority
|
|
81
107
|
* order: frontmatter (`trigger` or `triggers`), then a `## trigger:` body
|
|
@@ -86,6 +112,15 @@ export function readSkillTriggers(filePath, description) {
|
|
|
86
112
|
* a miss, because the merged list depends on it).
|
|
87
113
|
*/
|
|
88
114
|
export function readSkillTriggerEntries(filePath, description) {
|
|
115
|
+
return readSkillFrontmatter(filePath, description).entries;
|
|
116
|
+
}
|
|
117
|
+
/**
|
|
118
|
+
* Read a skill's trigger phrases WITH their provenance plus its declared
|
|
119
|
+
* lifecycle status, from one memoized parse. Same sources, precedence and
|
|
120
|
+
* memoization as readSkillTriggerEntries; the status is the frontmatter key of
|
|
121
|
+
* that name, lowercased, "" when absent or unreadable.
|
|
122
|
+
*/
|
|
123
|
+
export function readSkillFrontmatter(filePath, description) {
|
|
89
124
|
const desc = description ?? "";
|
|
90
125
|
let st;
|
|
91
126
|
try {
|
|
@@ -93,20 +128,22 @@ export function readSkillTriggerEntries(filePath, description) {
|
|
|
93
128
|
}
|
|
94
129
|
catch {
|
|
95
130
|
cache.delete(filePath);
|
|
96
|
-
return [];
|
|
131
|
+
return { entries: [], status: "" };
|
|
97
132
|
}
|
|
98
133
|
const cached = cache.get(filePath);
|
|
99
134
|
if (cached &&
|
|
100
135
|
cached.mtimeMs === st.mtimeMs &&
|
|
101
136
|
cached.size === st.size &&
|
|
102
137
|
cached.description === desc) {
|
|
103
|
-
return cached.entries;
|
|
138
|
+
return { entries: cached.entries, status: cached.status };
|
|
104
139
|
}
|
|
105
140
|
const sources = [];
|
|
141
|
+
let status = "";
|
|
106
142
|
try {
|
|
107
143
|
const { frontmatter, body } = parseFrontmatter(readFileSync(filePath, "utf-8"));
|
|
108
144
|
const fm = frontmatter;
|
|
109
145
|
const label = (source) => (phrase) => ({ phrase, source });
|
|
146
|
+
status = normalizeSkillStatus(fm.status);
|
|
110
147
|
sources.push(normalizeTriggers(fm.trigger).map(label("frontmatter")), normalizeTriggers(fm.triggers).map(label("frontmatter")), parseBodyTriggers(body).map(label("heading")));
|
|
111
148
|
}
|
|
112
149
|
catch {
|
|
@@ -116,8 +153,8 @@ export function readSkillTriggerEntries(filePath, description) {
|
|
|
116
153
|
if (desc)
|
|
117
154
|
sources.push(parseDescriptionTriggers(desc).map((phrase) => ({ phrase, source: "description" })));
|
|
118
155
|
const entries = mergeTriggerEntries(sources);
|
|
119
|
-
cache.set(filePath, { mtimeMs: st.mtimeMs, size: st.size, description: desc, entries });
|
|
120
|
-
return entries;
|
|
156
|
+
cache.set(filePath, { mtimeMs: st.mtimeMs, size: st.size, description: desc, entries, status });
|
|
157
|
+
return { entries, status };
|
|
121
158
|
}
|
|
122
159
|
/**
|
|
123
160
|
* Merge authored phrase sources into one bounded list, in priority order.
|
package/docs/LOCAL_DEV.md
CHANGED
|
@@ -138,7 +138,7 @@ before and after a full run. A non-zero delta is the leak this rule prevents.
|
|
|
138
138
|
### New fixtures: use `node:test`
|
|
139
139
|
|
|
140
140
|
A new fixture is written on `node:test`. The runner does not care which style a
|
|
141
|
-
file uses -
|
|
141
|
+
file uses - 100 of the core suite's 335 fixtures already use `node:test` - so the
|
|
142
142
|
reason is the failure the other style produces. A hand-rolled helper that calls
|
|
143
143
|
`fn()` without awaiting it discards the case's promise, so an `async` case runs
|
|
144
144
|
detached and the file can print its green tally before that case settles, with
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.43.
|
|
3
|
+
"version": "0.43.16",
|
|
4
4
|
"description": "🥨 Braid - Metacognitive extension suite for pi coding agent: Adds memory, plan tracking, structured cognitive signals and completion checks on top of pi core loop, so long sessions keep their context and stop claiming unfinished work.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -33,6 +33,7 @@ Two surfaces in `skills-tool/` put a skill body in front of the agent: the auto-
|
|
|
33
33
|
- **Conversion is a detected read.** The whisper asks the agent to open the SKILL.md; the conversion signal is the `read` tool_result (`actual`), which is also what sets `hadSkillLoad` in the durable session record. The retired LOADED/SKIP reply is no longer solicited; `claimed` keeps its historical honor-system meaning and stays monotone.
|
|
34
34
|
- **The trigger has a mechanical form.** `skills-tool/loading-guidance.ts` carries both the judgment form (the task entered a listed skill's domain) and the mechanical form (about to call a tool family whose word appears in a skill's name). `prompt-builder` renders that text through the `skillsLoadingText` builder as the `skills-loading` section and holds no copy of the rules; the trigger's worked examples are derived at assembly from the live tool and skill names, so the text names no pair that the running session does not have. The identity's skills prose stays one sentence.
|
|
35
35
|
- **The catalog is in the prompt.** The same section renders every visible skill as one `- name: description` row, with the read path derived from the skills' own file paths (one root for a single pack, a directory heading per pack when a catalog is installed from several). A tool call is no longer the way the agent learns which skills exist: the floor exists because the prompt that opens a resumed session carries no domain vocabulary for a matcher to rank against. `list_skills` remains the price tool (reach, headings, ranking) rather than the catalog.
|
|
36
|
+
- **A retired skill is not advertised.** A SKILL.md whose frontmatter declares `status: merged`, `archived` or `deprecated` stops being advertised and matched, and the file stays on disk as history. The exclusion rides the flag `disable-model-invocation` already owns (derived at cache time in `index.ts`), so the catalog, the suggestion whisper, the at-use line, the accessor and `list_skills` agree without a second concept. The row stays in the unfiltered cache, so a read of the file still resolves.
|
|
36
37
|
- **Drift re-points at the floor.** When the session's own path-taking calls (`read`/`edit`/`write`) accumulate entries in a work area the floor was not rendered against, one steer line names that area and points back at the catalog. The rule and its bounds (two entries, one fire per twelve calls, three per session, quiet for the same window after any skill surface) live in `loading-guidance.ts` beside the floor text; the wiring is the `tool_result` handler in `auto-inject.ts`. Bounds are the whole design: the line is only worth its noise if it stays rare.
|
|
37
38
|
- **The at-use line is observed, never enforced.** With `braid.skills.inform` set to `inform` (default `off`), a `tool_result` whose call **succeeded**, whose tool name yields a family token some visible cached skill declares with `governs:`, and whose obligation row carries no `read` leg emits one steer line naming the file path and the family. It runs after the result exists, returns no replacement, and refuses, delays and rewrites nothing: any gating change can only make it quieter, which is the property that separates it from a refusal gate. The payload is derived from the declaration and the catalogue entry only (the skill's own `filePath`, the token the call's name yields), so no skill name is invented in code and no tool argument is echoed. Once per session per skill, suppressed by the same obligation record the legs write (its `informed` leg), silenced by a read at any point, and hidden skills are never named. `skill_stats` reports it as `inform` from the store: `undecided` below twenty informs, `beats` only when the lower Wilson bound clears the suggestion channel's 18.8% pair conversion, `noise` otherwise.
|
|
38
39
|
- **Applicability is recorded, never enforced.** The counters cannot tell a skill that applied and was ignored from one that never applied, and the sessions that read nothing are mostly sessions no phrase matches. `skills-tool/applicability.ts` decides that difference from the skill's own declaration (the trigger phrases its file carries: frontmatter `trigger:`/`triggers:`, a `## trigger:` body heading, a description `Triggers:` tail), never from the ranking heuristic, with the injector's occurrence boundary and a clause-scoped negation read, so a phrase inside "do not research this" is not a condition met. The verdict is `read` (condition held and a detected read followed), `ignored` (condition held and no read followed), or `not-applicable` (derived: the census's `evaluated` minus the verdict rows); a skill whose file declares no phrase is named `undeclared` rather than judged either way. It reaches disk as `kind: "applicability"` rows in the per-session store (one verdict row per applicable skill keyed on `sessionId` + `skill`, one census row per session) and out through `skill_stats`. It is an observer: it writes no delivery, slot, cooldown, counter or prompt, and it owns no compliance leg. `suggested`/`listed`/`informed`/`read`/`applied` belong to the record that owns each skill's declared tool family; the verdict row joins it on the skill name.
|
|
@@ -48,7 +48,7 @@ import {
|
|
|
48
48
|
rankSkillsDeterministic,
|
|
49
49
|
} from "./auto-inject.js";
|
|
50
50
|
import type { DeterministicRanking, RankedSkill, RelevanceReason } from "./auto-inject.js";
|
|
51
|
-
import {
|
|
51
|
+
import { readSkillFrontmatter } from "./skill-triggers.js";
|
|
52
52
|
import type { TriggerSource } from "./skill-triggers.js";
|
|
53
53
|
import { readGovernedFamilies } from "./skill-families.js";
|
|
54
54
|
import {
|
|
@@ -78,9 +78,10 @@ interface CachedSkill {
|
|
|
78
78
|
baseDir: string;
|
|
79
79
|
sourceInfo?: { source?: string; package?: string };
|
|
80
80
|
/**
|
|
81
|
-
*
|
|
82
|
-
*
|
|
83
|
-
*
|
|
81
|
+
* Excluded from model selection: pi's own frontmatter flag, or a status this
|
|
82
|
+
* cache reads as retired (see RETIRED_STATUSES). Either way braid keeps the
|
|
83
|
+
* skill out of the surfaces that advertise skills to the model, while the
|
|
84
|
+
* file stays on disk and an explicit read of it still resolves.
|
|
84
85
|
*/
|
|
85
86
|
disableModelInvocation?: boolean;
|
|
86
87
|
/** Frontmatter trigger phrases, resolved from SKILL.md at cache time. */
|
|
@@ -91,17 +92,40 @@ interface CachedSkill {
|
|
|
91
92
|
|
|
92
93
|
let cachedSkills: CachedSkill[] = [];
|
|
93
94
|
|
|
95
|
+
/**
|
|
96
|
+
* Statuses that mean the skill is no longer the place to look: its content
|
|
97
|
+
* lives in a successor, or the file is kept as history. The vocabulary is the
|
|
98
|
+
* pack's (a `status:` frontmatter key), and the exclusion is this module's:
|
|
99
|
+
* no file is deleted, renamed or edited to make a skill stop being advertised.
|
|
100
|
+
*/
|
|
101
|
+
const RETIRED_STATUSES = new Set(["merged", "archived", "deprecated"]);
|
|
102
|
+
|
|
103
|
+
/** Whether a declared status retires the skill from model selection. */
|
|
104
|
+
function isRetiredStatus(status: string): boolean {
|
|
105
|
+
return RETIRED_STATUSES.has(status);
|
|
106
|
+
}
|
|
107
|
+
|
|
94
108
|
/**
|
|
95
109
|
* Called from prompt-builder's before_agent_start to populate the cache.
|
|
96
110
|
* Resolves each skill's frontmatter trigger phrases here, once per turn:
|
|
97
111
|
* the matcher scores triggers, pi's skill objects never carry them (fixed
|
|
98
112
|
* shape), and the memoized read makes repeat turns stat-only.
|
|
113
|
+
*
|
|
114
|
+
* The same read answers the file's `status:`, and a retired status rides the
|
|
115
|
+
* `disableModelInvocation` exclusion rather than a second one: every surface
|
|
116
|
+
* that advertises skills already filters on that flag, so one derived field
|
|
117
|
+
* keeps the catalog, the whisper, the at-use line and the accessors in
|
|
118
|
+
* agreement. The row is still cached, so an explicit read of the file is still
|
|
119
|
+
* recognized — the skill stops being advertised, not becoming unreadable.
|
|
99
120
|
*/
|
|
100
121
|
export function setCachedSkills(skills: CachedSkill[]): void {
|
|
122
|
+
let retired = 0;
|
|
101
123
|
cachedSkills = skills.map((s) => {
|
|
102
|
-
const entries =
|
|
124
|
+
const { entries, status } = readSkillFrontmatter(s.filePath, s.description);
|
|
103
125
|
const triggerSources: Record<string, TriggerSource> = {};
|
|
104
126
|
for (const entry of entries) triggerSources[entry.phrase] = entry.source;
|
|
127
|
+
const isRetired = isRetiredStatus(status);
|
|
128
|
+
if (isRetired) retired++;
|
|
105
129
|
return {
|
|
106
130
|
...s,
|
|
107
131
|
triggers: entries.map((entry) => entry.phrase),
|
|
@@ -110,11 +134,15 @@ export function setCachedSkills(skills: CachedSkill[]): void {
|
|
|
110
134
|
// frontmatter read the phrases come from (one extra parse per file per
|
|
111
135
|
// process). An empty list is a declaration of no family, not a miss.
|
|
112
136
|
families: readGovernedFamilies(s.filePath),
|
|
137
|
+
disableModelInvocation: s.disableModelInvocation === true || isRetired,
|
|
113
138
|
};
|
|
114
139
|
});
|
|
115
140
|
// Sync with auto-inject subsystem (enriched cache — triggers ride along)
|
|
116
141
|
updateSkillCache(cachedSkills);
|
|
117
|
-
log.debug(
|
|
142
|
+
log.debug(
|
|
143
|
+
`Cached ${skills.length} skills for list_skills tool` +
|
|
144
|
+
(retired ? ` (${retired} retired by status)` : ""),
|
|
145
|
+
);
|
|
118
146
|
}
|
|
119
147
|
|
|
120
148
|
/**
|
|
@@ -28,23 +28,41 @@
|
|
|
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
|
import { statSync, readFileSync } from "node:fs";
|
|
34
40
|
import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
|
|
35
41
|
|
|
36
42
|
/**
|
|
37
|
-
* Max trigger phrases
|
|
38
|
-
*
|
|
39
|
-
*
|
|
40
|
-
*
|
|
41
|
-
*
|
|
42
|
-
*
|
|
43
|
+
* Max trigger phrases kept per skill: a budget, spent down the merged list so
|
|
44
|
+
* the lowest-priority source loses first. Past it the reader drops the tail and
|
|
45
|
+
* reports nothing, which is why test-trigger-cap.mjs reads the authored files
|
|
46
|
+
* itself and fails by name: a claim past the cap is a build failure, not a
|
|
47
|
+
* silent loss.
|
|
48
|
+
*
|
|
49
|
+
* It bounds what one file may claim, not what a turn may spend. A phrase costs
|
|
50
|
+
* one word-bounded regex test over the prompt per turn (`triggerMatches`, from
|
|
51
|
+
* the suggestion matcher and the applicability pass) — flat in the phrase,
|
|
52
|
+
* linear in the prompt — so the ceiling is about shape: a list this long is a
|
|
53
|
+
* page of situations, and a longer one is a description in disguise.
|
|
43
54
|
*/
|
|
44
|
-
export const MAX_TRIGGERS =
|
|
55
|
+
export const MAX_TRIGGERS = 16;
|
|
45
56
|
|
|
46
|
-
/**
|
|
47
|
-
|
|
57
|
+
/**
|
|
58
|
+
* Max characters of one trigger phrase. A phrase compiles to a literal,
|
|
59
|
+
* word-bounded substring test: it reaches no prompt and costs the same at any
|
|
60
|
+
* length, so this is a shape bound rather than a hazard bound. A string long
|
|
61
|
+
* enough to be a sentence is a condition, and it matches only a prompt that
|
|
62
|
+
* carries that sentence verbatim. The bound sits above the longest shipped
|
|
63
|
+
* phrase, and test-trigger-cap.mjs fails by name past it.
|
|
64
|
+
*/
|
|
65
|
+
export const MAX_TRIGGER_CHARS = 66;
|
|
48
66
|
|
|
49
67
|
/**
|
|
50
68
|
* Where an authored phrase came from. Precedence (frontmatter, heading,
|
|
@@ -65,6 +83,18 @@ interface TriggerCacheEntry {
|
|
|
65
83
|
/** The description the entries were merged with: a different one is a miss. */
|
|
66
84
|
description: string;
|
|
67
85
|
entries: TriggerEntry[];
|
|
86
|
+
/** The declared lifecycle status, lowercased; "" when the file declares none. */
|
|
87
|
+
status: string;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/**
|
|
91
|
+
* One SKILL.md's trigger phrases plus the lifecycle status its frontmatter
|
|
92
|
+
* declares — everything one parse of the file answers.
|
|
93
|
+
*/
|
|
94
|
+
export interface SkillFrontmatterRead {
|
|
95
|
+
entries: TriggerEntry[];
|
|
96
|
+
/** Lowercased `status:` token, or "" when the file declares none. */
|
|
97
|
+
status: string;
|
|
68
98
|
}
|
|
69
99
|
|
|
70
100
|
const cache = new Map<string, TriggerCacheEntry>();
|
|
@@ -102,6 +132,15 @@ export function readSkillTriggers(filePath: string, description?: string): strin
|
|
|
102
132
|
return readSkillTriggerEntries(filePath, description).map((entry) => entry.phrase);
|
|
103
133
|
}
|
|
104
134
|
|
|
135
|
+
/**
|
|
136
|
+
* Normalize a frontmatter `status` value into the token a caller matches on.
|
|
137
|
+
* Only a string is a declaration: a missing key, a null, or a nested shape is
|
|
138
|
+
* the absence of one. Pure.
|
|
139
|
+
*/
|
|
140
|
+
function normalizeSkillStatus(value: unknown): string {
|
|
141
|
+
return typeof value === "string" ? value.trim().toLowerCase() : "";
|
|
142
|
+
}
|
|
143
|
+
|
|
105
144
|
/**
|
|
106
145
|
* Read a skill's authored phrases WITH their provenance, merged in priority
|
|
107
146
|
* order: frontmatter (`trigger` or `triggers`), then a `## trigger:` body
|
|
@@ -112,13 +151,23 @@ export function readSkillTriggers(filePath: string, description?: string): strin
|
|
|
112
151
|
* a miss, because the merged list depends on it).
|
|
113
152
|
*/
|
|
114
153
|
export function readSkillTriggerEntries(filePath: string, description?: string): TriggerEntry[] {
|
|
154
|
+
return readSkillFrontmatter(filePath, description).entries;
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
/**
|
|
158
|
+
* Read a skill's trigger phrases WITH their provenance plus its declared
|
|
159
|
+
* lifecycle status, from one memoized parse. Same sources, precedence and
|
|
160
|
+
* memoization as readSkillTriggerEntries; the status is the frontmatter key of
|
|
161
|
+
* that name, lowercased, "" when absent or unreadable.
|
|
162
|
+
*/
|
|
163
|
+
export function readSkillFrontmatter(filePath: string, description?: string): SkillFrontmatterRead {
|
|
115
164
|
const desc = description ?? "";
|
|
116
165
|
let st;
|
|
117
166
|
try {
|
|
118
167
|
st = statSync(filePath);
|
|
119
168
|
} catch {
|
|
120
169
|
cache.delete(filePath);
|
|
121
|
-
return [];
|
|
170
|
+
return { entries: [], status: "" };
|
|
122
171
|
}
|
|
123
172
|
const cached = cache.get(filePath);
|
|
124
173
|
if (
|
|
@@ -127,13 +176,15 @@ export function readSkillTriggerEntries(filePath: string, description?: string):
|
|
|
127
176
|
cached.size === st.size &&
|
|
128
177
|
cached.description === desc
|
|
129
178
|
) {
|
|
130
|
-
return cached.entries;
|
|
179
|
+
return { entries: cached.entries, status: cached.status };
|
|
131
180
|
}
|
|
132
181
|
const sources: TriggerEntry[][] = [];
|
|
182
|
+
let status = "";
|
|
133
183
|
try {
|
|
134
184
|
const { frontmatter, body } = parseFrontmatter(readFileSync(filePath, "utf-8"));
|
|
135
185
|
const fm = frontmatter as Record<string, unknown>;
|
|
136
186
|
const label = (source: TriggerSource) => (phrase: string) => ({ phrase, source });
|
|
187
|
+
status = normalizeSkillStatus(fm.status);
|
|
137
188
|
sources.push(
|
|
138
189
|
normalizeTriggers(fm.trigger).map(label("frontmatter")),
|
|
139
190
|
normalizeTriggers(fm.triggers).map(label("frontmatter")),
|
|
@@ -148,8 +199,8 @@ export function readSkillTriggerEntries(filePath: string, description?: string):
|
|
|
148
199
|
parseDescriptionTriggers(desc).map((phrase) => ({ phrase, source: "description" })),
|
|
149
200
|
);
|
|
150
201
|
const entries = mergeTriggerEntries(sources);
|
|
151
|
-
cache.set(filePath, { mtimeMs: st.mtimeMs, size: st.size, description: desc, entries });
|
|
152
|
-
return entries;
|
|
202
|
+
cache.set(filePath, { mtimeMs: st.mtimeMs, size: st.size, description: desc, entries, status });
|
|
203
|
+
return { entries, status };
|
|
153
204
|
}
|
|
154
205
|
|
|
155
206
|
/**
|