pi-braid 0.43.4 → 0.43.6
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/AGENTS.md +9 -0
- package/CHANGELOG.md +121 -7
- package/build-info.json +4 -4
- package/dist/extensions/core/prompt-builder/surface-discipline-section.d.ts +1 -1
- package/dist/extensions/core/prompt-builder/surface-discipline-section.js +1 -1
- package/dist/extensions/orchestrator/index.js +11 -1
- package/docs/LOCAL_DEV.md +109 -0
- package/package.json +1 -1
- package/skills/misdirection-audit/SKILL.md +1 -1
- package/src/extensions/core/prompt-builder/surface-discipline-section.ts +1 -1
- package/src/extensions/orchestrator/index.ts +13 -1
package/AGENTS.md
CHANGED
|
@@ -141,6 +141,15 @@ both code and any docs that reference it - or mark the doc
|
|
|
141
141
|
Add new API names to `TRACKED_NAMES` in `check-doc-drift.mjs` as new
|
|
142
142
|
drift surfaces emerge.
|
|
143
143
|
|
|
144
|
+
A third gate covers the counts these documents state, which the status and drift
|
|
145
|
+
gates do not read: **`scripts/check-source-claims.mjs`** re-runs the command
|
|
146
|
+
behind every count enrolled in `scripts/source-claims.json` and fails when a
|
|
147
|
+
document states a different number (`npm run check:source-claims`, part of
|
|
148
|
+
`npm run ci:check`). Enrol a count only when a command re-derives it: a measured
|
|
149
|
+
figure (a duration, a load average) and a released changelog's number belong to
|
|
150
|
+
the run that produced them, and an entry that holds an expected value with no
|
|
151
|
+
command behind it is the same drift with a gate painted on it.
|
|
152
|
+
|
|
144
153
|
## Tool Inventory
|
|
145
154
|
|
|
146
155
|
The canonical, source-derived inventory of every tool provided/exposed by this
|
package/CHANGELOG.md
CHANGED
|
@@ -33,16 +33,130 @@ stay core history and no longer occupy a sibling's release name: past a bare
|
|
|
33
33
|
|
|
34
34
|
## Repository history
|
|
35
35
|
|
|
36
|
-
`main`
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
36
|
+
`main` is a linear history above the tag line described above; `git rev-list --count main` states how
|
|
37
|
+
many commits it holds.
|
|
38
|
+
|
|
39
|
+
Two rewrites are visible to anyone holding an older clone, and both preserved content byte for byte:
|
|
40
|
+
|
|
41
|
+
- the 2026-10-12 consolidation replaced the per-iteration series (380 commits) with one consolidated
|
|
42
|
+
commit; that series is kept outside this repository, in a local-only ref
|
|
43
|
+
(`refs/archive/main-pre-squash`) plus an all-refs bundle, so a public clone has the consolidated line
|
|
44
|
+
only;
|
|
45
|
+
- the 2026-10-29 subject rewrite changed 16 commit messages and nothing else: the generated
|
|
46
|
+
`Merge branch '<internal branch name>'` subjects became the subject of the commit that landed, and two
|
|
47
|
+
older hand-written subjects lost a prefix. Every tree hash is unchanged and the tags were re-pointed,
|
|
48
|
+
so fetching this history can report a forced update. Packed artifacts from releases before it name a
|
|
49
|
+
`build-info` commit from the old history, and that commit no longer resolves here.
|
|
50
|
+
|
|
51
|
+
This file and [`packages/core/docs/HISTORY.md`](packages/core/docs/HISTORY.md) are the reader-facing
|
|
52
|
+
record; the tag scheme above applies unchanged.
|
|
43
53
|
|
|
44
54
|
---
|
|
45
55
|
|
|
56
|
+
## Core — 0.43.6 (2026-10-29: the rule says one thing, and a merge states what landed)
|
|
57
|
+
|
|
58
|
+
- **The identity block contradicted itself, and the contradiction is gone.** One sentence forbade
|
|
59
|
+
internal labels in commit messages while the next sanctioned the commit subject as a seat for them, so
|
|
60
|
+
the rule could be quoted in either direction and nothing could be gated against it. It now says one
|
|
61
|
+
thing: a branch name may carry an internal handle for the operator, a commit subject must not. The
|
|
62
|
+
file gate's own comment, the design research behind the rule, and the open-source readiness audit all
|
|
63
|
+
already said subjects stay clean; the block was the outlier.
|
|
64
|
+
- **A merge states what landed.** Git derives `Merge branch '<name>'` from the branch name, so every
|
|
65
|
+
merge out of a worker branch published a handle nobody chose to write: 14 of the 24 merge commits then
|
|
66
|
+
in this repository carried that shape, and no gate read commit messages. The merge path now passes the
|
|
67
|
+
landed commit's own subject, and refuses the merge when it cannot read one, because the fallback is
|
|
68
|
+
precisely the derived subject. A probe through the real tool on a two-parent merge shows the landed
|
|
69
|
+
subject before and after; against a build with the change reverted it prints the derived one.
|
|
70
|
+
- **History has a gate now.** `check:commit-subjects` reads every commit since the newest tag reachable
|
|
71
|
+
from HEAD, merges included, and refuses internal-label tokens and the branch namespace a merge subject
|
|
72
|
+
inherits. Its range re-anchors at each release, and the summary line carries the range, the baseline tag
|
|
73
|
+
and the head, so a recorded population names the revision it certifies. Both workflows now fetch full
|
|
74
|
+
history, because a shallow clone has no tag to anchor the range, and the gate fails closed rather than
|
|
75
|
+
certifying nothing.
|
|
76
|
+
- **One vocabulary, two surfaces.** The label patterns the source gate used moved into a module both
|
|
77
|
+
gates read, so a token added once is refused in files and in history. The source gate's behaviour is
|
|
78
|
+
unchanged, proven by the same planted token caught at the same line and column either side of the
|
|
79
|
+
extraction.
|
|
80
|
+
- **The spelling seats actually typed is refused.** The shared vocabulary is uppercase, and the lowercase
|
|
81
|
+
form slid through: it is refused in history now, where the population has no fixture strings to
|
|
82
|
+
confuse it, with three near-miss cases in the fixture proving a word character before the handle, two
|
|
83
|
+
digits, and a four-digit run are not hits. The source surface keeps the uppercase vocabulary until the
|
|
84
|
+
lowercase strings inside fixture names are swept, which is tracked rather than assumed.
|
|
85
|
+
- **The fixture builds its own repositories.** A tag and a clean range, a planted label reported with its
|
|
86
|
+
sha, token and subject while a clean commit beside it stays unreported, a tagless tree refused with a
|
|
87
|
+
reason, the subject git itself derives from a worker branch, and the lowercase spelling with its
|
|
88
|
+
near-misses. The label tokens are composed at runtime, so the fixture does not plant what it tests.
|
|
89
|
+
|
|
90
|
+
## Core — 0.43.5 (2026-10-28: the runtime suite runs eight files at once, and a planted hang still dies at its cap)
|
|
91
|
+
|
|
92
|
+
- **The core suite stopped waiting on one file at a time.** Its 320 files ran serially in 640s; eight in flight measured
|
|
93
|
+
157s here, a 3.9x drop, with every file's own result unchanged: 320 passed either way. Results print in fixture
|
|
94
|
+
order, so the fixture lines of two runs of the same tree still match and a failing file's own output stays under
|
|
95
|
+
its line; the summary tail carries the run's wall clock, so that line differs whenever the run did.
|
|
96
|
+
- **Width sixteen is past the knee, and the numbers say why.** It bought 8 to 14 seconds of makespan over eight and
|
|
97
|
+
cost 82% more total work, 2,490s against 1,364s, doubling the median file's duration from 3.5s to 7.3s and turning
|
|
98
|
+
eight files red. The default is the machine's own parallelism capped at eight, and `--jobs 1` restores the serial
|
|
99
|
+
order a bisect needs.
|
|
100
|
+
- **The default cap moved from 30s to 60s because the cap was making the verdict.** A file's own duration grows by
|
|
101
|
+
1.03x to 2.5x beside seven others, and the slowest file without an allowance of its own takes 21.5s alone; in the
|
|
102
|
+
pooled run measured for this release `fleet/test-drain-contention.mjs` took 33.9s, which a 30s cap kills as a
|
|
103
|
+
timeout the code did not earn. The three declared allowances stay: they bound wedges, not durations.
|
|
104
|
+
- **The pool cleans up after itself.** SIGINT and SIGTERM kill every live file group before the runner exits, so a
|
|
105
|
+
cancelled run leaves no detached children; a `PI_TEST_ROOT` that resolves to nothing is a failure instead of a
|
|
106
|
+
green run of zero files; `--timings` and `--timings-json` expose the durations a width has to be argued from.
|
|
107
|
+
- **The new fixture pins the contract, and it was made to fail before it was trusted.** It checks the three outcome
|
|
108
|
+
classes, the exit code, that a hang is killed at its cap rather than awaited, and that two one-second files at
|
|
109
|
+
width two overlap. At width one the two pool assertions redden and print the numbers that explain it: 2,278ms for
|
|
110
|
+
the pair, and 2,188ms of summed file duration inside a 2,192ms run.
|
|
111
|
+
- **A telegram fixture stopped inheriting the machine's own poller state, and its five siblings followed.**
|
|
112
|
+
`busy-steer.test.mjs` failed deterministically on any machine where a live pi process held the poller ownership
|
|
113
|
+
lock, because the extension correctly refuses to start a second `getUpdates` consumer and every delivery wait then
|
|
114
|
+
starved on a poller that never polled. It now pins `BRAID_HOME`, the lock path and the session role for the whole
|
|
115
|
+
case, and so do `coalesce`, `inbound-queue-durability`, `collision-aware`, `collision-idle-ctx` and `index`, which
|
|
116
|
+
inherited the same state: the whole telegram suite now runs green beside a live seat, where five of its files
|
|
117
|
+
previously failed up to twenty cases each. A refused start names its three causes instead of starving mute.
|
|
118
|
+
- **The runner names what it is waiting on, and the width it was given.** A run that has printed nothing for 30
|
|
119
|
+
seconds says once which file is holding the line, so an ordered flush that stalls on one slow file is visible
|
|
120
|
+
instead of looking like a hung suite. The contract fixture now also pins `--jobs` by census: a runner that ignores
|
|
121
|
+
the flag is caught, where before it passed every check in the file.
|
|
122
|
+
- **Four claims the runner made about itself were wrong, and the sentences moved rather than the behaviour.** An
|
|
123
|
+
invalid `PI_TEST_TIMEOUT_MS` now warns like its siblings instead of silently keeping the default; the loader
|
|
124
|
+
allowance is 200s because twelve cases over five lanes is three waves of a 60s driver cap, not two; `SKIP` is keyed
|
|
125
|
+
by path relative to the test root, and its dead entry for a file that exists nowhere is gone; and the verdict's
|
|
126
|
+
reliance on the file's output pipes closing, not just its exit, is now stated and pinned by a fixture, because a
|
|
127
|
+
helper holding the inherited stdout keeps the file open past its own exit.
|
|
128
|
+
- **Three fixtures were printing a verdict their cases had not earned.** Their local `test()` helper called an
|
|
129
|
+
`async` case and discarded the promise, so the case ran detached: a rejected case was marked as passing, the tally
|
|
130
|
+
read `0 failed`, and only Node's default unhandled-rejection handler made the exit non-zero. With nothing keeping
|
|
131
|
+
the loop alive past the summary, the same file printed `7 passed, 0 failed` and exited 0. Both halves are fixed -
|
|
132
|
+
the helper awaits its case and the call sites await the helper - and a rejecting case now fails the file.
|
|
133
|
+
- **A cleanup kill no longer fails a case because the process left first.** `fleet/test-cli.mjs` failed under a loaded
|
|
134
|
+
pooled run with `kill ESRCH`, because the supervisor had already exited when the signal arrived. A gone process is
|
|
135
|
+
what that cleanup wanted, so `ESRCH` is accepted there and any other errno still fails the case; the four kill
|
|
136
|
+
sites share the one helper.
|
|
137
|
+
- **The suite's tally stopped counting modules it never judged.** The run counted every walked `.mjs` as a passed
|
|
138
|
+
fixture, so three shared modules that assert nothing and the root aggregator added five to a number readers
|
|
139
|
+
compare between runs. They are now declared in `packages/core/test/runtime/fixture-manifest.json` with a reason each, the run
|
|
140
|
+
lists them beside the count instead of running them, and `check:suite-coverage` fails in both directions: a
|
|
141
|
+
counted module that cannot fail, and a declaration for a module the tree no longer carries.
|
|
142
|
+
- **A run that is interrupted leaves nothing behind.** `SIGINT` and `SIGTERM` killed every live file group but not
|
|
143
|
+
the per-file temp sandbox the runner creates, so every interrupted run stranded one directory. The handler now
|
|
144
|
+
sweeps them too, and both signals keep their exit codes.
|
|
145
|
+
- **The telegram suite stopped leaving 246 directories per run.** Its runner spawned each file with no `TMPDIR`, so
|
|
146
|
+
every per-case tree a fixture made landed in the machine's real temp directory and stayed. Each file now gets its
|
|
147
|
+
own sandbox, removed when it settles and on a signal, with the per-file `BRAID_HOME` and poller lock derived from
|
|
148
|
+
it so nothing a child writes to temp lands outside it.
|
|
149
|
+
- **Two fixtures stopped deciding their verdict from a fixed sleep.** They waited a guessed number of milliseconds
|
|
150
|
+
for a chain of deferrals and then read a count, which failed 19 times in 130 loaded attempts; they now poll for
|
|
151
|
+
arrival, hold until the count stops moving so a double send is still caught, and say which way a count went wrong.
|
|
152
|
+
- **`scripts/prompt-capture.mjs` renders a build's assembled prompt and diffs two captures.** Two captures of one
|
|
153
|
+
build are byte-identical, each hunk is labelled with its prompt region, and the header lists the surfaces the
|
|
154
|
+
pinning hides. The misdirection audit's third probe pointed at a two-build prompt diff no tool could produce;
|
|
155
|
+
it names this one now.
|
|
156
|
+
- **Two files earned a longer allowance from measurement rather than from their idle duration.** `test-pack-provenance`
|
|
157
|
+
and `test-braid-home-containment` sit at 48.3s and 47.2s beside seven other files under load and at 28.1s and
|
|
158
|
+
21.9s one at a time, so a pool on a box slower than this one would have killed them for the box's weather.
|
|
159
|
+
|
|
46
160
|
## Core — 0.43.4 (2026-10-28: the pane guide is named for the model, and a seat can hand over)
|
|
47
161
|
|
|
48
162
|
- **The skill about panes is named for what it teaches.** Workspaces, tabs, panes, opaque ids, read sources and the
|
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.6",
|
|
4
|
+
"sha": "e7ebbc542f5983f2270e96628def7a9b6d654610",
|
|
5
|
+
"shaShort": "e7ebbc54",
|
|
6
6
|
"branch": "detached",
|
|
7
7
|
"dirty": false,
|
|
8
|
-
"packedAt": "2026-10-
|
|
8
|
+
"packedAt": "2026-10-29T14:29:10.456Z"
|
|
9
9
|
}
|
|
@@ -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
|
|
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.";
|
|
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
|
|
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.`;
|
|
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
|
|
@@ -211,7 +211,17 @@ function verifyAndMergeBase(workerId, workerBranch, base, repoRoot, population)
|
|
|
211
211
|
if (dirty === undefined || dirty.length > 0) {
|
|
212
212
|
return nothingMerged(`NOT merged: worktree on ${base} has uncommitted changes; refusing to merge over them. Base unchanged at ${short(baseBefore)}. Locks and branch kept.`);
|
|
213
213
|
}
|
|
214
|
-
|
|
214
|
+
// Git derives a merge subject from the branch name, so a merge out of a
|
|
215
|
+
// worker branch would publish that branch's namespace in the one part of a
|
|
216
|
+
// commit a reader keeps. The subject states what landed instead. A tip
|
|
217
|
+
// whose subject cannot be read (missing, or empty) refuses the merge: the
|
|
218
|
+
// fallback is precisely the derived subject this avoids, so a silent
|
|
219
|
+
// fallback would put the leak back.
|
|
220
|
+
const landed = git(repoRoot, ["log", "-1", "--format=%s", workerBranch]);
|
|
221
|
+
if (!landed) {
|
|
222
|
+
return nothingMerged(`NOT merged: cannot read the subject of ${workerBranch} at ${short(tip)}; refusing to merge without an explicit subject, since git would derive the merge subject from that branch name. Base unchanged at ${short(baseBefore)}. Locks and branch kept.`);
|
|
223
|
+
}
|
|
224
|
+
if (git(repoRoot, ["merge", "--no-edit", "-m", landed, workerBranch]) === undefined) {
|
|
215
225
|
return nothingMerged(`NOT merged: git merge ${workerBranch} into ${base} failed (conflict or refusal). Base unchanged at ${short(baseBefore)}. Locks and branch kept.`);
|
|
216
226
|
}
|
|
217
227
|
}
|
package/docs/LOCAL_DEV.md
CHANGED
|
@@ -47,20 +47,129 @@ npm install # installs all workspaces (peer-resolves the pi packages)
|
|
|
47
47
|
npm run typecheck # all four code packages
|
|
48
48
|
npm run build # compile core to dist/
|
|
49
49
|
npm test # build + runtime test suites (core)
|
|
50
|
+
node packages/core/scripts/run-tests.mjs --jobs 1 --timings # the same files serially, with durations
|
|
50
51
|
npm run lint # ESLint over all four code packages
|
|
51
52
|
npm run format # prettier --write .
|
|
52
53
|
npm run format:check # prettier --check .
|
|
53
54
|
npm run check:docs # every in-scope .md has a status marker
|
|
54
55
|
npm run check:doc-drift # current-state docs must not reference APIs missing from code
|
|
55
56
|
npm run check:deps # layer-boundary check
|
|
57
|
+
npm run check:source-claims # every count a doc states is re-derived from the tree
|
|
56
58
|
```
|
|
57
59
|
|
|
60
|
+
The counts these documents state are re-derived, not copied.
|
|
61
|
+
`packages/core/scripts/source-claims.json` holds the counts the gate governs - the
|
|
62
|
+
file and line each one is written on, a pattern that reads it out of that line,
|
|
63
|
+
and the command that derives it from the tree - and `npm run check:source-claims`
|
|
64
|
+
re-runs every command and fails on a disagreement. A count no command re-derives
|
|
65
|
+
is not enrolled: a measurement (a duration, a load average) belongs to the run
|
|
66
|
+
that produced it, and a figure in a released changelog belongs to that release.
|
|
67
|
+
|
|
68
|
+
The core runtime suite runs its files in a bounded pool: the machine's own
|
|
69
|
+
parallelism, at most eight. The width is a flag, so the same files can be run
|
|
70
|
+
one at a time when a failure needs the serial order, and their durations can
|
|
71
|
+
be printed or written for a comparison between two widths:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
node packages/core/scripts/run-tests.mjs --jobs 1 # one file at a time
|
|
75
|
+
node packages/core/scripts/run-tests.mjs --timings # per-file durations, slowest first
|
|
76
|
+
node packages/core/scripts/run-tests.mjs --timings-json=/tmp/timings.json
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
`PI_TEST_JOBS` sets the width without the flag. Results always print in
|
|
80
|
+
fixture order, so the per-file lines of two runs of the same tree match; the
|
|
81
|
+
summary line carries the run's own wall clock, so it differs whenever the run
|
|
82
|
+
did, and a diff between two widths should compare the file lines rather than
|
|
83
|
+
the tail. The cost of that order is that a slow file at the head of the walk
|
|
84
|
+
holds every later line, so a run that has printed nothing for 30 seconds says
|
|
85
|
+
once which file it is waiting on.
|
|
86
|
+
|
|
58
87
|
Per-workspace variants use the workspace flag, e.g.
|
|
59
88
|
`npm run build -w packages/core`, `npm test -w packages/providers`.
|
|
60
89
|
|
|
61
90
|
The combined gate is `npm run ci:check` (docs, drift, deps, format,
|
|
62
91
|
typecheck, tests).
|
|
63
92
|
|
|
93
|
+
### Fixtures and process groups
|
|
94
|
+
|
|
95
|
+
The runner starts each file in its own process group and signals the group: at
|
|
96
|
+
the file's cap with `SIGKILL`, and the same on `SIGINT`/`SIGTERM`. A fixture's
|
|
97
|
+
own helpers therefore stay in that group, so nothing a helper starts outlives
|
|
98
|
+
the run: the group is killed when the file settles or reaches its cap.
|
|
99
|
+
|
|
100
|
+
The file settles when its output pipes close, not when its process exits. A
|
|
101
|
+
helper that inherits the file's stdout keeps that pipe open after the file
|
|
102
|
+
exits, so the runner still counts the file as running; if the helper outlives
|
|
103
|
+
the cap, the file is reported as a timeout even though its own exit code was 0.
|
|
104
|
+
Give a helper its own stdio, or wait for it to exit, before the fixture exits.
|
|
105
|
+
|
|
106
|
+
A helper spawned with `detached: true` calls `setsid()`, leaves the group, and
|
|
107
|
+
outlives the run that started it: no group signal reaches it. One fixture needs
|
|
108
|
+
that escape - `test/runtime/fleet/test-supervisor-recovery.mjs` fabricates an
|
|
109
|
+
owner and an orphaned turn, and `detached: true` is what keeps those processes
|
|
110
|
+
from being the fixture's own children, since a zombie child keeps its group
|
|
111
|
+
answering a liveness check long after the kernel killed the process. It reaps
|
|
112
|
+
each of them by pid when it is done, and an interrupt caught while that file is
|
|
113
|
+
in flight leaves nothing longer-lived than its own `sleep 30`, which ends
|
|
114
|
+
itself. Any other fixture that escapes the group owes an explicit cleanup on
|
|
115
|
+
every exit path, the interrupt one included.
|
|
116
|
+
|
|
117
|
+
### Fixtures and their own temp directory
|
|
118
|
+
|
|
119
|
+
Every runner that spawns fixture files gives each file its own `TMPDIR` and
|
|
120
|
+
removes that tree when the file settles, and on `SIGINT`/`SIGTERM` too. A
|
|
121
|
+
fixture's `mkdtemp` then writes inside the sandbox instead of the machine's
|
|
122
|
+
temp directory: a case that never cleans up after itself, or a file killed at
|
|
123
|
+
its cap, which cannot clean up, costs one tree the runner already owns.
|
|
124
|
+
`packages/core/scripts/run-tests.mjs` and
|
|
125
|
+
`packages/telegram/test/run-tests.mjs` both do this; the telegram runner also
|
|
126
|
+
derives its per-file `BRAID_HOME` and poller-lock pins from that same temp
|
|
127
|
+
root, so nothing a child writes to temp lands outside the sandbox.
|
|
128
|
+
|
|
129
|
+
The signal path needs a runner that is not blocked in a synchronous spawn:
|
|
130
|
+
a JS signal handler cannot run while `spawnSync` waits, so a blocking loop
|
|
131
|
+
only cleans up after the file it was waiting on has already returned. The
|
|
132
|
+
core runner's pool and the telegram runner's per-file `spawn` both keep the
|
|
133
|
+
loop free for the handler.
|
|
134
|
+
|
|
135
|
+
When you change a runner, count the fixture-named directories under `$TMPDIR`
|
|
136
|
+
before and after a full run. A non-zero delta is the leak this rule prevents.
|
|
137
|
+
|
|
138
|
+
### New fixtures: use `node:test`
|
|
139
|
+
|
|
140
|
+
A new fixture is written on `node:test`. The runner does not care which style a
|
|
141
|
+
file uses - 88 of the core suite's 322 fixtures already use `node:test` - so the
|
|
142
|
+
reason is the failure the other style produces. A hand-rolled helper that calls
|
|
143
|
+
`fn()` without awaiting it discards the case's promise, so an `async` case runs
|
|
144
|
+
detached and the file can print its green tally before that case settles, with
|
|
145
|
+
the exit code computed from a counter the case never reached. `node:test` cannot
|
|
146
|
+
take that shape. Existing files are not rewritten for style; a file with async
|
|
147
|
+
cases that a synchronous helper discards is fixed when it is touched, by
|
|
148
|
+
awaiting the helper's call or by moving to `node:test`.
|
|
149
|
+
|
|
150
|
+
### What the count counts
|
|
151
|
+
|
|
152
|
+
The runner walks every `.mjs` under `test/runtime` and counts each file that
|
|
153
|
+
exits 0 as a passed fixture, so a module the walk sees and no case ever judges
|
|
154
|
+
would still add one to the summary line. A shared helper in `test/runtime/lib/`
|
|
155
|
+
is exactly that: the fixtures import it, it registers nothing, and it asserts
|
|
156
|
+
nothing when the runner loads it on its own.
|
|
157
|
+
|
|
158
|
+
Those modules are declared in `test/runtime/fixture-manifest.json`, under
|
|
159
|
+
`notFixtures`, each with the reason it is not a fixture. The runner neither runs
|
|
160
|
+
nor counts a declared module, and says so where it introduces the count. The
|
|
161
|
+
reason is required, so a module leaves the count with one on record, and
|
|
162
|
+
`node packages/core/scripts/run-tests.mjs --list` prints the whole population
|
|
163
|
+
with the declarations beside it, running nothing.
|
|
164
|
+
|
|
165
|
+
`npm run check:suite-coverage` holds both halves of that declaration. A counted
|
|
166
|
+
module must register a case with `node:test`, assert from `node:assert` while it
|
|
167
|
+
loads, or call a function it declares at load (the hand-rolled harness that
|
|
168
|
+
names its own cases and sets the exit code). A declared module must be none of
|
|
169
|
+
those, because a declaration that names a real fixture keeps a test out of the
|
|
170
|
+
run. A new helper therefore fails the gate until it is declared, and a declared
|
|
171
|
+
helper that grows a case fails it until it is taken back into the count.
|
|
172
|
+
|
|
64
173
|
## Two install modes
|
|
65
174
|
|
|
66
175
|
### 1. Live symlink (default for active development)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.43.
|
|
3
|
+
"version": "0.43.6",
|
|
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",
|
|
@@ -19,7 +19,7 @@ Three probes, in order. Record command, exit code, and raw output for each.
|
|
|
19
19
|
|
|
20
20
|
1. **Tree provenance scan.** `npm run check:placement -- --strict` at the repo root. Flags provenance tokens (wave/worker/round labels, ISO dates, commit refs) in comments and string literals, role words used as policy in generic layers, and owner home paths anywhere. Exit 0 is clean; every hit is an instance with a file:line.
|
|
21
21
|
2. **Domain-literal grep.** Beyond the checker's built-in classes, grep the generic layers for policy that belongs to a domain: role names inside cwd gates or classification logic, hardcoded home-directory roots, project or feature names inside shared mechanism code. The checker's exclusion list documents which paths legitimately own these words; a hit outside the owners is an instance.
|
|
22
|
-
3. **Prompt-capture diff.** Capture the assembled prompt from two builds (shipped vs candidate)
|
|
22
|
+
3. **Prompt-capture diff.** Capture the assembled prompt from two builds (shipped vs candidate) with `node scripts/prompt-capture.mjs capture --root <dir holding dist> --out <file>`, then `node scripts/prompt-capture.mjs diff <old> <new>`. The root is the directory that holds `dist/`, and that differs by arm: a checkout is `<repo>/packages/core`, while the installed package at `~/.pi/agent/npm/node_modules/pi-braid` carries `dist/` at its own root, so pointing the command at `<installed>/packages/core` exits 2 with ENOENT. Every delta must map to an intended text change; an unintended delta is an instance (unmeasured innovation, or doc drift at the prompt layer). The capture pins every non-code input, so two captures of one build are byte-identical and the only hunks are real; it labels each hunk with the prompt region it belongs to. What it cannot see is listed in its header.
|
|
23
23
|
|
|
24
24
|
Then read the recent output corpus: reports, briefs, and the git log since the last audit. Admit an instance only with a file:line, message id, or commit ref. "It feels like" is not an instance.
|
|
25
25
|
|
|
@@ -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
|
|
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.`;
|
|
13
13
|
|
|
14
14
|
/**
|
|
15
15
|
* Its own section: the handler places it between the identity block and the
|
|
@@ -324,7 +324,19 @@ function verifyAndMergeBase(
|
|
|
324
324
|
`NOT merged: worktree on ${base} has uncommitted changes; refusing to merge over them. Base unchanged at ${short(baseBefore)}. Locks and branch kept.`,
|
|
325
325
|
);
|
|
326
326
|
}
|
|
327
|
-
|
|
327
|
+
// Git derives a merge subject from the branch name, so a merge out of a
|
|
328
|
+
// worker branch would publish that branch's namespace in the one part of a
|
|
329
|
+
// commit a reader keeps. The subject states what landed instead. A tip
|
|
330
|
+
// whose subject cannot be read (missing, or empty) refuses the merge: the
|
|
331
|
+
// fallback is precisely the derived subject this avoids, so a silent
|
|
332
|
+
// fallback would put the leak back.
|
|
333
|
+
const landed = git(repoRoot, ["log", "-1", "--format=%s", workerBranch]);
|
|
334
|
+
if (!landed) {
|
|
335
|
+
return nothingMerged(
|
|
336
|
+
`NOT merged: cannot read the subject of ${workerBranch} at ${short(tip)}; refusing to merge without an explicit subject, since git would derive the merge subject from that branch name. Base unchanged at ${short(baseBefore)}. Locks and branch kept.`,
|
|
337
|
+
);
|
|
338
|
+
}
|
|
339
|
+
if (git(repoRoot, ["merge", "--no-edit", "-m", landed, workerBranch]) === undefined) {
|
|
328
340
|
return nothingMerged(
|
|
329
341
|
`NOT merged: git merge ${workerBranch} into ${base} failed (conflict or refusal). Base unchanged at ${short(baseBefore)}. Locks and branch kept.`,
|
|
330
342
|
);
|