pi-braid 0.43.36 → 0.43.38

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
@@ -96,6 +96,46 @@ record; the tag scheme above applies unchanged.
96
96
  note that a clean disable releases it, because a refusal an operator cannot act on
97
97
  is a support ticket.
98
98
 
99
+ ## Skills — 0.2.6 / Core 0.43.38
100
+
101
+ - **The whisper in an exported session was JSON, not prose.** A context-lifecycle proposal was stored as a
102
+ content array of two text parts, and pi-core's export template falls back to `JSON.stringify` for a
103
+ non-string custom message, so an exported HTML showed `[{"type":"text",…},{"type":"text","text":"[braid-whisper-end]"}]`
104
+ where the reader expected a suggestion. The channel now stores text, envelope first and marker last, which
105
+ is also exactly what the agent reads on resume.
106
+ (2026-11-09: a landing page is a set of mechanisms and a set of refusals)
107
+
108
+ - **`landing-page` joins the pack.** The family-tree landing was rebuilt against a professional reference
109
+ and the knowledge that made it safe existed only in that wave's report: the rail-and-panel switcher whose
110
+ no-script form is jump links, the timeline drawn as a line with stops, price tiers on shared rows, the
111
+ header action that survives 320px, and the rule that a form with no endpoint is a lie.
112
+ - **The refusals are the load-bearing half.** A page whose promise is that every fact has a source cannot
113
+ open with a testimonial from a client nobody served, an invented number, or a contact nobody answers. The
114
+ skill states that before it states any technique.
115
+ - **It names the gate that text checks cannot replace**: a headless browser at 320, 375, 768 and 1280 asking
116
+ whether the document is wider than its viewport, and whether any element's box crosses an edge from
117
+ outside every clipping ancestor.
118
+
119
+ ## Core — 0.43.37 (2026-11-08: the shapes were rare, and the instrument policed the wrong text)
120
+
121
+ - **Measured over the shipped corpus, the seven sentence shapes fired in 8 of 61 files.** 21 hits in
122
+ 41,575 words — and 11 of those were the catalogue quoting the shapes it forbids, so the file that defines
123
+ the failure was the file that scored worst. The prose that makes the complaint is not built out of those
124
+ seven shapes; it is built out of long sentences, asides and em-dashes, which the instrument counts
125
+ separately and which nothing has yet acted on.
126
+ - **The instrument read comments, not prompts.** Over `packages/*/src/**/*.ts` the voice check scores the
127
+ comments beside a prompt; the strings the agent actually reads were outside its reach until they were
128
+ extracted, and over extracted strings its empty-sentence counter collapses into fragments. A gate placed
129
+ on that path would have policed documentation and passed the prompt.
130
+ - **`check-voice.mjs` stays advisory, and the reason is a number.** After the rewrite the only files with a
131
+ hit are the three that must not change — the catalogue, the identity, and a skill whose before/after
132
+ example is deliberate. A threshold low enough to catch a regression fires on honest prose; a threshold
133
+ above the catalogue catches nothing. The band between those two numbers is empty.
134
+ - **Eight files rewritten anyway**, each removing the shape it carries rather than paraphrasing it:
135
+ `skill-usage`'s process narration, `paper-writer`'s importance paragraph, `subagent-orchestration`,
136
+ `adversarial-engagement`, `socratic-irony`, the shared engagement fundamentals, and two prompt-builder
137
+ sections.
138
+
99
139
  ## Core — 0.43.36 (2026-11-08: the digest reads the window it prints)
100
140
 
101
141
  - **Two readers of one file disagreed about the same intention.** The checker treats a past
package/build-info.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "name": "pi-braid",
3
- "version": "0.43.36",
4
- "sha": "16830ad24d5daaf2ae069abeea22b0b9c2ed8f04",
5
- "shaShort": "16830ad2",
3
+ "version": "0.43.38",
4
+ "sha": "46a4e6d6fdd50ba65eddc36b58424c08022fefa5",
5
+ "shaShort": "46a4e6d6",
6
6
  "branch": "detached",
7
7
  "dirty": false,
8
- "packedAt": "2026-11-08T15:28:44.955Z"
8
+ "packedAt": "2026-11-09T12:26:34.508Z"
9
9
  }
@@ -22,7 +22,7 @@ export interface ProjectContextFile {
22
22
  *
23
23
  * Shape:
24
24
  * Read the project docs in full before editing the areas they cover: the
25
- * AGENTS.md / CLAUDE.md files below are this project's authoritative contract —
25
+ * AGENTS.md / CLAUDE.md files below are this project's authoritative contract;
26
26
  * cross-check references against source.
27
27
  *
28
28
  * - AGENTS.md at /abs/path/AGENTS.md
@@ -21,7 +21,7 @@ function basename(p) {
21
21
  *
22
22
  * Shape:
23
23
  * Read the project docs in full before editing the areas they cover: the
24
- * AGENTS.md / CLAUDE.md files below are this project's authoritative contract —
24
+ * AGENTS.md / CLAUDE.md files below are this project's authoritative contract;
25
25
  * cross-check references against source.
26
26
  *
27
27
  * - AGENTS.md at /abs/path/AGENTS.md
@@ -36,7 +36,7 @@ export async function projectDocsSection(contextFiles) {
36
36
  return "";
37
37
  }
38
38
  const lines = [
39
- "Read the project docs in full before editing the areas they cover: the AGENTS.md / CLAUDE.md files below are this project's authoritative contract — cross-check references against source.",
39
+ "Read the project docs in full before editing the areas they cover: the AGENTS.md / CLAUDE.md files below are this project's authoritative contract; cross-check references against source.",
40
40
  "",
41
41
  ];
42
42
  for (const file of contextFiles) {
@@ -8,7 +8,7 @@ import { type PromptSection } from "./section.js";
8
8
  * instead of a prohibition list. The text is pinned verbatim by the lockstep
9
9
  * test — no paraphrasing here either.
10
10
  */
11
- export declare const SURFACE_DISCIPLINE = "Signal discipline binds every surface you produce: code comments, commit messages, tests, docs, reports, logs. A comment earns its place only by explaining why \u2014 code that needs a what-narration is rewritten, not annotated. Never commit internal task IDs, wave or phase labels, or session-ephemeral figures: a future reader has no context for them. Internal labels present in task text or briefs are never copied into code, tests, comments, docs, or commit messages. A report's filename and title are the only sanctioned seats for wave context: a branch name may carry an internal handle for the operator, but the commit subject must not, because git derives it from the branch name and a reader keeps the subject. Write any spec or brief so a teammate with zero context can act on it.";
11
+ export declare const SURFACE_DISCIPLINE = "Signal discipline binds every surface you produce: code comments, commit messages, tests, docs, reports, logs. A comment earns its place only by explaining why; if the code needs a what-narration, rewrite the code. Never commit internal task IDs, wave or phase labels, or session-ephemeral figures: a future reader has no context for them. Internal labels present in task text or briefs are never copied into code, tests, comments, docs, or commit messages. A report's filename and title carry wave context; a branch name may carry an operator handle, but not the commit subject, because git derives it and a reader keeps it. Write any spec or brief so a teammate with zero context can act on it.";
12
12
  /**
13
13
  * Its own section: the handler places it between the identity block and the
14
14
  * identity-core block — render order: COMMUNICATION ��� SURFACE_DISCIPLINE
@@ -8,7 +8,7 @@ import { simpleSection } from "./section.js";
8
8
  * instead of a prohibition list. The text is pinned verbatim by the lockstep
9
9
  * test — no paraphrasing here either.
10
10
  */
11
- export const SURFACE_DISCIPLINE = `Signal discipline binds every surface you produce: code comments, commit messages, tests, docs, reports, logs. A comment earns its place only by explaining why — code that needs a what-narration is rewritten, not annotated. Never commit internal task IDs, wave or phase labels, or session-ephemeral figures: a future reader has no context for them. Internal labels present in task text or briefs are never copied into code, tests, comments, docs, or commit messages. A report's filename and title are the only sanctioned seats for wave context: a branch name may carry an internal handle for the operator, but the commit subject must not, because git derives it from the branch name and a reader keeps the subject. Write any spec or brief so a teammate with zero context can act on it.`;
11
+ export const SURFACE_DISCIPLINE = `Signal discipline binds every surface you produce: code comments, commit messages, tests, docs, reports, logs. A comment earns its place only by explaining why; if the code needs a what-narration, rewrite the code. Never commit internal task IDs, wave or phase labels, or session-ephemeral figures: a future reader has no context for them. Internal labels present in task text or briefs are never copied into code, tests, comments, docs, or commit messages. A report's filename and title carry wave context; a branch name may carry an operator handle, but not the commit subject, because git derives it and a reader keeps it. Write any spec or brief so a teammate with zero context can act on it.`;
12
12
  /**
13
13
  * Its own section: the handler places it between the identity block and the
14
14
  * identity-core block — render order: COMMUNICATION ��� SURFACE_DISCIPLINE
@@ -411,7 +411,12 @@ async function queueProposal(evaluated, pi, ctx, branchLength) {
411
411
  // measured deliveries). The source must be the TRUE family, so the
412
412
  // envelope says context-lifecycle.
413
413
  applyWhisperEnvelope(proposalContent, "context-lifecycle/proposal");
414
- sm?.appendCustomMessageEntry?.(PROPOSAL_CUSTOM_TYPE, proposalContent, true, proposal);
414
+ // A custom message rendered into an exported session prints its content
415
+ // as JSON when the content is an array of parts (pi-core's export template
416
+ // falls back to JSON.stringify for a non-string). The proposal is text, so
417
+ // it is stored as text: one string, envelope first and marker last, which
418
+ // is also what the agent reads on resume.
419
+ sm?.appendCustomMessageEntry?.(PROPOSAL_CUSTOM_TYPE, proposalContent.map((part) => part.text).join("\n"), true, proposal);
415
420
  // Record the suggestion class so a repeat re-fire is suppressed while
416
421
  // this one is still actionable (gate + dedupe rely on this map).
417
422
  state(ctx).proposalKeys.set(proposalKeyFor(proposal.message, proposal.suggested_action), Date.now());
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-braid",
3
- "version": "0.43.36",
3
+ "version": "0.43.38",
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",
@@ -13,7 +13,7 @@ verdict: KEEP
13
13
 
14
14
  # Skill Usage: Measuring Skill Adoption
15
15
 
16
- The skill-loading problem is unmeasured, not unbroken. This skill turns "skills are barely used" from an owner observation into a number you can act on. It reads telemetry that already exists - no new runtime code required - and emits a per-skill usage table.
16
+ Skill loading is unmeasured. This skill turns "skills are barely used" from an owner observation into a number you can act on. No new runtime code is needed: the table is per skill, computed from telemetry already on disk.
17
17
 
18
18
  The validation-first stance: **a zero-evidence skill must NOT be KEEP.** Every skill is suspect until measured. This skill is the measurement instrument; `meta-improvement` is the evolution engine. Run this first, feed the result to `meta-improvement`.
19
19
 
@@ -26,7 +26,7 @@ The validation-first stance: **a zero-evidence skill must NOT be KEEP.** Every s
26
26
 
27
27
  ## Step 1: Read the session counters (exact, per-session)
28
28
 
29
- Call the `skill_stats` tool. It returns `sessionHasSkillLoad` plus a per-skill map:
29
+ Call the `skill_stats` tool. The reply carries `sessionHasSkillLoad` plus a per-skill map:
30
30
 
31
31
  ```json
32
32
  {
@@ -57,7 +57,7 @@ Fallback / cross-check: scan session files under `~/.pi/agent/sessions/` for:
57
57
 
58
58
  ## Step 4: Join with an outcome proxy (where available)
59
59
 
60
- Where a turn's reasoning metrics exist (`measureStability`: topic anchor, bigram entropy, self-contradiction), tag each skill-loading turn with a coarse outcome: `stable` (no self-contradiction, anchored) or `unstable`. The goal is not a perfect score - it is a **delta you can compare after a change**.
60
+ Where a turn's reasoning metrics exist (`measureStability`: topic anchor, bigram entropy, self-contradiction), tag each skill-loading turn with a coarse outcome: `stable` (no self-contradiction, anchored) or `unstable`. What matters is the **delta between two runs**, because that is what a change is compared against.
61
61
 
62
62
  ## Step 5: Emit the table and bucket
63
63
 
@@ -231,7 +231,7 @@ When a worker signals completion, review critically before closing the pane.
231
231
 
232
232
  - **APPROVED** - `herdr action=send pane=<worker-pane> text="[agent:orchestrator→worker] APPROVED. Close your pane."` Then close the worker pane and capture knowledge to memory.
233
233
  - **REVISION** - `herdr action=send pane=<worker-pane> text="[agent:orchestrator→worker] REVISION: <specific feedback>."` Set a timer to check back.
234
- - **REJECTED** - If fundamentally wrong: send rejection and close the pane manually.
234
+ - **REJECTED** - If the output fails the task: send rejection and close the pane manually.
235
235
 
236
236
  ### Failure modes
237
237
 
@@ -415,11 +415,10 @@ node scripts/workers.mjs --json # machine-readable
415
415
  node scripts/workers.mjs --stale 30 # age at which 'working' is flagged (default 15m)
416
416
  ```
417
417
 
418
- One row per worker: session age, event count, commits ahead, dirty count, deliverable size. It reads
419
- four independent sources because no single one is trustworthy - the registry is only the _claim_;
420
- session mtime proves motion, git proves commits and dirty state, the filesystem proves the
421
- deliverable exists. The registry reports `working` long after a pane has died, and `admitted` for a
422
- worker that has been running for an hour.
418
+ One row per worker: session age, event count, commits ahead, dirty count, deliverable size. Four sources
419
+ back the row, none trustworthy alone: the registry is only the _claim_, session mtime proves motion,
420
+ git proves commits and dirty state, the filesystem proves the deliverable exists. The registry reports
421
+ `working` long after a pane has died, and `admitted` for a worker that has been running for an hour.
423
422
 
424
423
  The flags name the failure modes worth acting on:
425
424
 
@@ -31,7 +31,7 @@ function basename(p: string): string {
31
31
  *
32
32
  * Shape:
33
33
  * Read the project docs in full before editing the areas they cover: the
34
- * AGENTS.md / CLAUDE.md files below are this project's authoritative contract —
34
+ * AGENTS.md / CLAUDE.md files below are this project's authoritative contract;
35
35
  * cross-check references against source.
36
36
  *
37
37
  * - AGENTS.md at /abs/path/AGENTS.md
@@ -49,7 +49,7 @@ export async function projectDocsSection(
49
49
  }
50
50
 
51
51
  const lines: string[] = [
52
- "Read the project docs in full before editing the areas they cover: the AGENTS.md / CLAUDE.md files below are this project's authoritative contract — cross-check references against source.",
52
+ "Read the project docs in full before editing the areas they cover: the AGENTS.md / CLAUDE.md files below are this project's authoritative contract; cross-check references against source.",
53
53
  "",
54
54
  ];
55
55
 
@@ -9,7 +9,7 @@ import { simpleSection, type PromptSection } from "./section.js";
9
9
  * instead of a prohibition list. The text is pinned verbatim by the lockstep
10
10
  * test — no paraphrasing here either.
11
11
  */
12
- export const SURFACE_DISCIPLINE = `Signal discipline binds every surface you produce: code comments, commit messages, tests, docs, reports, logs. A comment earns its place only by explaining why — code that needs a what-narration is rewritten, not annotated. Never commit internal task IDs, wave or phase labels, or session-ephemeral figures: a future reader has no context for them. Internal labels present in task text or briefs are never copied into code, tests, comments, docs, or commit messages. A report's filename and title are the only sanctioned seats for wave context: a branch name may carry an internal handle for the operator, but the commit subject must not, because git derives it from the branch name and a reader keeps the subject. Write any spec or brief so a teammate with zero context can act on it.`;
12
+ export const SURFACE_DISCIPLINE = `Signal discipline binds every surface you produce: code comments, commit messages, tests, docs, reports, logs. A comment earns its place only by explaining why; if the code needs a what-narration, rewrite the code. Never commit internal task IDs, wave or phase labels, or session-ephemeral figures: a future reader has no context for them. Internal labels present in task text or briefs are never copied into code, tests, comments, docs, or commit messages. A report's filename and title carry wave context; a branch name may carry an operator handle, but not the commit subject, because git derives it and a reader keeps it. Write any spec or brief so a teammate with zero context can act on it.`;
13
13
 
14
14
  /**
15
15
  * Its own section: the handler places it between the identity block and the
@@ -573,7 +573,17 @@ async function queueProposal(
573
573
  // measured deliveries). The source must be the TRUE family, so the
574
574
  // envelope says context-lifecycle.
575
575
  applyWhisperEnvelope(proposalContent, "context-lifecycle/proposal");
576
- sm?.appendCustomMessageEntry?.(PROPOSAL_CUSTOM_TYPE, proposalContent, true, proposal);
576
+ // A custom message rendered into an exported session prints its content
577
+ // as JSON when the content is an array of parts (pi-core's export template
578
+ // falls back to JSON.stringify for a non-string). The proposal is text, so
579
+ // it is stored as text: one string, envelope first and marker last, which
580
+ // is also what the agent reads on resume.
581
+ sm?.appendCustomMessageEntry?.(
582
+ PROPOSAL_CUSTOM_TYPE,
583
+ proposalContent.map((part) => part.text).join("\n"),
584
+ true,
585
+ proposal,
586
+ );
577
587
  // Record the suggestion class so a repeat re-fire is suppressed while
578
588
  // this one is still actionable (gate + dedupe rely on this map).
579
589
  state(ctx).proposalKeys.set(