- AGENTS.md: "Three files" is now "These files"; the table lists five.
- Digests 43 and 45 regain the traps the review found missing.
- protocol.md and formula-and-io.md cite file-inventory.md for the Wasm
appendix and the inventory, which moved there.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
- repo-stats reads the gotcha list from context/gotchas.md (the digest in
repo-map.md no longer measures the doc-growth signal) and reports it as
`docs.gotchas`; the test fixture and its derived expectations follow.
- AGENTS.md and the wave agent-rules protect gotchas.md and
file-inventory.md like the repo map they were split from.
- doc-site.md's publication table lists the two new pages.
- file-inventory.md's Context docs rows describe the three files correctly.
- the code-review skill points at gotchas.md for the long form.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Every GitHub write (PR, comment, review reply) must include an attribution line
identifying the AI agent. Posts go out under the repository owner's account, so
an unattributed post reads as the human's words.
Format: _Posted by <Agent Stack> (<model>)_
Examples:
- _Posted by Claude (Opus 4.5)_
- _Posted by Cursor Agent (claude-sonnet-5)_
AGENTS.md:
- Added 'GitHub Attribution (Hard Rule)' section in multi-stack docs
- Concrete format and examples
- Clarified that a thread is not 'answered' until the reply has attribution
.agents/skills/pr-watch/SKILL.md:
- Added 'GitHub Attribution (Hard Rule)' subsection
- Updated 'Answer substantive feedback with attribution' in obligations
- Cross-references AGENTS.md for full rule
context/cloud-agents.md:
- Added 'GitHub Attribution (Hard Rule)' section
- Same format and examples as AGENTS.md
This ensures any agent reading the shared docs (Cursor, Claude, etc.) knows to
attribute every GitHub write to the specific AI agent.
Co-authored-by: Ed Langley <fiddlerwoaroof@users.noreply.github.com>
The pr-watch skill and script now cover reviews/comments, not just CI checks.
An agent reading only the pr-watch skill now knows to track both.
.agents/skills/pr-watch/SKILL.md:
- Reframed: 'watching a PR' means checks AND reviews
- Added 'Reviews and Comments' section with the three surfaces table
- Added 'Review Obligations' subsection (answer feedback, identity line, etc.)
- Documented --reviews (default) and --no-reviews flags
- Cross-references AGENTS.md for full workflow details
scripts/pr-watch:
- Added --reviews (default) and --no-reviews flags
- After exit 0 (green/mergeable), calls scripts/pr-reviews to show all
reviews and comments. Does not change exit code — answering is agent's job.
- Updated usage text to document the new behavior
- Composes with existing pr-reviews (fixture mode passes through)
scripts/pr-watch-test.sh:
- Added mk_reviews_empty() and mk_reviews_with_review() helpers
- Added review fixtures to all cases that exit 0 (pr-reviews needs them)
- Added tests: 'green with reviews shows review output' and
'--no-reviews skips review output'
- All 56 tests pass
AGENTS.md / context/cloud-agents.md:
- Updated cross-references to point to pr-watch skill as agent-facing recipe
- Simplified text now that pr-watch handles reviews automatically
Co-authored-by: Ed Langley <fiddlerwoaroof@users.noreply.github.com>
Multi-stack agents (especially Cursor cloud) may focus on pr-watch (CI checks
only) and miss review feedback. This makes the obligation explicit.
AGENTS.md - new 'PR Tracking: Checks AND Reviews' subsection:
- Fetch reviews AND comments (reviews are separate API surface)
- Codex/ChatGPT reviews arrive as reviews, not comments
- Use ./scripts/pr-reviews <n> to see all feedback together
- Answer substantive feedback with identity line before done/merge
- Re-check after push that reviews target current head SHA
- Don't wait indefinitely on Copilot/Codex (quota-limited)
- Points to existing wave essay for full workflow
context/cloud-agents.md - new 'PR Tracking' section:
- Brief summary of the obligation
- Points to pr-watch skill for CI, scripts/pr-reviews for reviews
- Cross-references AGENTS.md for full details
Co-authored-by: Ed Langley <fiddlerwoaroof@users.noreply.github.com>
User ruling: agents must work inside nix develop (or direnv) for this repo.
Bare system cargo that fails edition2024 is a misconfigured session.
Changes:
1. scripts/agent-bootstrap.sh:
- Added section 0: seed nix flake inputs automatically
- Cargo warm now runs inside 'nix develop --command'
- Added --skip-nix-seed flag for environments that don't need it
- Updated environment notes to emphasize nix-first
2. .cursor/environment.json:
- Removed --skip-cargo-warm (full nix-backed warm now default)
3. AGENTS.md:
- Added 'Toolchain' row to multi-stack table (nix develop required)
- Added 'Toolchain Requirement' subsection with usage examples
- Updated local agents guidance to use 'direnv allow'
4. context/cloud-agents.md:
- Bootstrap now lists nix-seed as step 1
- 'What does not work' table updated: bare system cargo now listed as
failing; nix develop works after bootstrap
- Updated nix section to reflect automatic seeding
Previous soft gap: nix-seed was a manual footnote; now it runs in bootstrap.
Co-authored-by: Ed Langley <fiddlerwoaroof@users.noreply.github.com>
Unifies coding-agent setup across Claude Code and Cursor so both stacks get:
- Pin-matched bd from flake.nix
- Fresh Dolt beads tracker sync (not stale JSONL export)
- Same skills via symlinks to .agents/skills/
Key changes:
1. scripts/agent-bootstrap.sh: stack-agnostic bootstrap that handles bd
installation, tracker sync, and optional cargo warming. Works for any
agent stack (Claude, Cursor, or manual).
2. .claude/hooks/session-start.sh: now a thin wrapper that calls the
shared bootstrap for cloud sessions, keeping only the local pin-check
inline.
3. .cursor/environment.json: configures Cursor cloud agents to run the
bootstrap via 'install'.
4. .cursor/skills/: symlinks to .agents/skills/* so Cursor agents
discover the same skills Claude has.
5. AGENTS.md: adds Multi-Stack Agent Support section; clarifies that
scripts/kb is the KB interface (Prolog MCP is not required and not
available in all stacks).
6. context/cloud-agents.md: updated for multi-stack support; added KB
section emphasizing scripts/kb over Prolog MCP.
The canonical skill source remains .agents/skills/. Both .claude/skills/
and .cursor/skills/ are symlinks to it, so there is one truth that both
stacks read.
Co-authored-by: Ed Langley <fiddlerwoaroof@users.noreply.github.com>
Narrows what #305 allowed to the user's ruling: reordering, folding and
tidying WIPs are out, and commit messages follow Conventional Commits with
the ticket id at the end of the subject.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdfEGXA7aJ6ftMsCc9PJze
The user settled the second half of improvise-79h5: "I don't mind
amending on a branch that hasn't been pushed, but don't do anything that
requires a force push". Rule 8, AGENTS.md's top line, "Commit early",
cloud-agents and the code-review summary now say so. Unpushed commits may
be tidied but never moved onto another base; nothing pushed is rewritten.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdfEGXA7aJ6ftMsCc9PJze
Review of #305 at ac2efdc8: "no merge can do it" is false when the
foreign commits belong to an open PR that will land as a merge commit.
Stack on it, or wait for it and merge a newly pinned gh/main. cherry-pick
-x is kept only for commits that will never reach main as they are.
Rule 8 now says to re-pin before merging a newer main (improvise-79h5,
first half), and context/cloud-agents.md states the new rule.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdfEGXA7aJ6ftMsCc9PJze
agent-rules gains rule 8, which forbids rebase, squash in any form, reset
that drops commits, amending a pushed commit and force-push. Rule 7 keeps
the SHA pinning for merge, merge-base and diff. The user's reason is quoted
in the rule: the merge structure of git history is a causal record.
AGENTS.md: the fix-after-merge recipe is now a merge. The wrong-base
rebuild stays the one sanctioned cherry-pick, with -x, and the text says
why no merge can do it. Merge PRs with a merge commit, never squash or
rebase. Also bounds test loops that walk a state machine until a step.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdfEGXA7aJ6ftMsCc9PJze
AGENTS.md and the wave skill: Copilot reviews again and is answered like
Codex; check baseRefName before merging a stacked PR; land a batch as one
integration PR; never resolve with --ours/--theirs, diff against both
parents; a clean merge of one test file can still fail together; CI takes
its tools from the .#ci dev shell; watch open ADR PRs; fmt-workspaces must
not be piped; Playwright serves the assembled harness/serve/.
repo-map: gotchas 1, 3, 18, 19, 38, 42, 44 and 47 brought up to gh/main
(view-named record resolution and Grids, nested group runs and remark,
the fold's spanned narrowing, uneditable/NonItem, the browser editor's
opened cell, NEEDS_THE_HOST, notify/settle_status); recounted the wire
vocabulary (28 model effects, 26 ModelCommand variants); File Inventory
line counts refreshed at c1772ca9; the median-binary ratio is degenerate.
kb.pl, through scripts/kb: 19 new facts; five stale ones replaced (the
checker's bash pin, the nix-shebang premise, the Copilot lapse, the
dev-shell environment, the fmt pipe).
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdfEGXA7aJ6ftMsCc9PJze
improvise-52eq: the AGENTS.md recipe searched `bd show` output for "not
found" and printed "all resolve" when there was none, so a bd that was
missing, failing or never run passed the audit. scripts/bd-audit-ids
keeps the file scan and exclusions, then `comm -23`s the cited ids
against `bd list --all --limit 0 --json`. A dead id is exit 1 and is
named. A bd that does not answer is exit 3, never a pass.
scripts/bd-audit-ids-test.sh has eight cases on a throwaway repo with a
fake bd. The old recipe as a rival fails 7 of the 8. Disabling the
comparison fails the dead-id case, and an empty exclusion list fails the
pass case. CI runs it with the other named suites. The "One environment
note" now reports which forms the guard refused and allowed, as observed.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdfEGXA7aJ6ftMsCc9PJze
improvise-28ri, from the #211 review at 6ccad4b: the recipe's grep has no
-r, so the skills' symlinks arrive as directory operands and are never
read. -d skip only silences "Is a directory", and sort -u would absorb a
duplicate anyway. Measured with BSD grep 2.6.0 and GNU grep 3.12: 3092
matches either way, 462 distinct ids. GNU grep -r follows those
symlinks (3107), so -r must not be added.
improvise-oga4: "Shipping a wave"'s opening and "Repository policy over
the Beads blocks" now point at the ADR exception. The wave SKILL.md
pointer is unwrapped, so a grep for "ADR pull requests" finds it.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdfEGXA7aJ6ftMsCc9PJze
The user's ruling: "An ADR isn't approved until I say it is." CI, the
reviews and the adversarial review stay required as gates, but none of
them is approval. SKILL.md's "not on a review" pointer is reworded to
match.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdfEGXA7aJ6ftMsCc9PJze
improvise-28ri: -d skip only silences "Is a directory" on the skills'
symlinks, which git ls-files lists as files. grep -r never follows them,
so nothing was ever read twice. The "spells no id" sentence now says what
the recipe actually cites.
improvise-oga4: the review-reply and head-SHA rules live only in
agent-rules "GitHub" (plus the after-merge clause moved there); AGENTS.md
points to it, and the code-review skill names it. An ADR's "Approved" is
an extra gate on top of CI, every review answered and the adversarial
review.
improvise-diho: agent-rules rule 7, pin gh/main to a SHA at task start.
Also: build a test-name list in a fresh CARGO_TARGET_DIR, because
git archive's commit mtimes make a reused one return a stale list.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdfEGXA7aJ6ftMsCc9PJze
- agent-rules "GitHub": authors reply on the PR to every finding they
address (commit, or why declined); reviewers read existing reviews first
with scripts/pr-reviews, answer every Codex review on its thread, and
state the head SHA they reviewed. SKILL.md points reviewers there.
- AGENTS.md "ADR pull requests": numbered open questions, the user answers
on the PR, "What the user decided", merge only on "Approved" (PR #122).
SKILL.md "Shepherding" points to it.
- Fix a pointer to the renamed policy section that wrapped across a line
break and so escaped the rename.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdfEGXA7aJ6ftMsCc9PJze
- User ruling: work is not done until it is in a PR and that PR has
merged. Stated once, in AGENTS.md's repo-owned section outside bd's
markers (renamed "Repository policy over the Beads blocks"); agent-rules
"Do not merge" and SKILL.md "Shepherding" point to it.
- "Who owns what" no longer says kb facts are batched two sentences
before saying they are not: repo-map lines are batched, kb facts are
written as they arrive.
- improvise-8haj: the ID audit takes its file list from git ls-files
(tracked + untracked, minus ignored), so build output such as
harness/serve and other agents' worktrees are not scanned; grep -d skip
passes over the .claude/skills symlinks.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdfEGXA7aJ6ftMsCc9PJze
- improvise-rzux: AGENTS.md now states the per-agent PR workflow the wave
skill uses (adversarial review at the head SHA, merge on GitHub, local main
fast-forwards to gh/main) and points to SKILL.md "Shepherding". The
obsolete one-PR-per-wave and local-integration text is cut.
- improvise-x1uk: the Beads integration block is regenerated whole by bd
(bd init, bd setup factory|opencode|mux). It is replaced with bd 1.3.0's
own minimal render, which no longer says git merge origin/main, and the
repository's policy (no team-maintainer opt-in, the TODO exception that
had been hand-edited inside the markers) moves to a section outside them.
- improvise-anmm: the ID audit scans .agents and the tracked .claude files,
excludes the kb skill's example crate name, and anchors its matcher so a
ticket body saying "not found" is not reported as a dead id.
- improvise-xolb: agent-rules' gate list is the test/js/kb CI jobs step for
step, with the conditional jobs (wasm incl. improvise-gp, harness-lint,
build+browser incl. the bundle node tests) and the excluded one named.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdfEGXA7aJ6ftMsCc9PJze
.agents/skills/wave is the one copy; .claude/skills/wave is a symlink to it,
as beads-merge already is. SKILL.md holds the brief checklist, agent-rules.md
the agent-side rules, and AGENTS.md points at both instead of carrying a third
list. The bd-generated Session Completion block is overridden in agent-rules.md
rather than hand-edited (improvise-x1uk).
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdfEGXA7aJ6ftMsCc9PJze
User ruling. A worktree is not durable storage: an agent finished a whole
ticket with every gate green and lost all of it, uncommitted, when its
worktree was deleted during a disk cleanup. The brief template now requires a
WIP commit after the first green test and after every meaningful step, and
separates "do not merge to main" from pushing the agent's own branch, which is
encouraged.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdfEGXA7aJ6ftMsCc9PJze
AGENTS.md's brief template now carries the gate list, because the one I had
been handing agents said `cargo fmt --all`, which reaches only one of this
repo's two workspace roots — and `cargo fmt -p opfs-contract` from the root
exits 1 as a usage error indistinguishable from a real verdict
(improvise-b4ks). Both spellings fail in the direction that looks like
success. The gate is `scripts/fmt-workspaces.sh`.
kb: the improvise-6qet ruling (a collapsed group is one aggregate row), and
the CI lane's doctrine on stubs and fixtures.
Also recovers kb.pl from a truncation: the working tree had lost 276 of 801
facts, most likely to a `kb replace` killed mid-write at a session boundary,
and `kb add` had written onto it with kb_consistent passing. Restored from
HEAD; this commit is 6 insertions, 0 deletions. Filed as improvise-usus.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
From PRs #144/#148/#151. `AGENTS.md`'s remote note gains the worktree-base
vector: a branch cut from the orchestrator's local `main` inherits whatever
that checkout merged but did not push, and nothing in the branch says so —
which is how #148's diff came to name the three orchestrator-only files and
read as a rule violation rather than a base problem.
Four facts. A fold test must fold the batch the producer really emits — a
`Binding::Sequence` flattens into one vec, and a per-step batching cannot see
intra-batch order at all. A type name is not a field, measured: one 14-site
rival left 14 of 16 assertions passing, while an assertion on a *fieldless*
effect is complete rather than smoke. A registry with two arms demotes the
weaker caller, and neither direction is safe by default. And a clean text
merge can delete an evidence entry that no gate checks.
Two gate traps: `--check-evidence` prints the comment cap FIRST, so reading it
through `tail -1` drops the half that was always there; and a compound command
refused by the worktree shell guard runs NEITHER part.
kb_consistent: TRUE, 798 facts.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FC2jVn8Au7E9JPkw6bwXXH
PRs #145/#149. New gotcha 50: `fill_line` takes a `Keeps` because the three
rows sharing a line disagree about which side yields, and the one key table on
screen is the one derived from the keymap — with the import wizard as the
deliberate inverse, since its derived line comes from the mode keymap while
the real keys are per-step.
AGENTS.md gains the remote trap, and it is the orchestrator's fault: briefs
said "merge `main`", and because `origin`/`gitea` take `main` directly while
GitHub gets branches, `origin/main` runs ahead of `gh/main`. An agent doing
the habitual thing pulled four unmerged commits — another PR's whole diff —
into a branch based on `gh/main`. Nothing in CI can see it; the result
compiles and passes. Codex caught it. The window is transient, which makes it
worse: the hazard is absent exactly when you would think to check.
Closes improvise-t14d, improvise-rr8n and improvise-vgp4 — the last
stale-open, fixed by 94a3d17 two days before it was filed.
Measured on main at 78a7bbf: 1700 passed / 0 failed / 7 ignored over 38
binaries, longest single binary 0.69s. kb_consistent: TRUE, 792 facts.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FC2jVn8Au7E9JPkw6bwXXH
Three things the merge with #120 (ui/shell-polish) actually required, none of
which a clean auto-merge could have told us.
MOVED, not preserved. #120 left <header>'s markup alone but gave every child
explicit styling and a stated reading order -- "what this is, which document,
which view, which mode, what keys, what the peer is doing". A build identifier
is "what this is", so the span moves from after #status to beside <h1>. Keeping
it at the tail was loyalty to my own first draft: it read as metadata trailing
#status, and with #hint's `flex: 1 1 auto` fighting for the slack a 40-char
commit SHA there is the thing that crowds the bar.
STYLED, because unstyled is illegible-by-default in a design system. It takes
`var(--dim)` -- the same token #hint and #status use, so it tracks both themes
by construction rather than by a hand-picked colour -- at 0.72rem, and clamps
to 14ch. Measured under Chromium on the merged tree: a tag renders whole
(scrollWidth == clientWidth, 69px), a 40-char SHA truncates to a 13-character
prefix with an ellipsis, and `header` does not overflow in either case
(scrollWidth == clientWidth == 1280). Contrast of rgb(107,103,95) on
rgb(244,241,234) is ~5.0:1, above AA for small text. Selecting the text still
copies the whole SHA -- text-overflow is a rendering clamp, not a truncation.
NOT AN ID. `improvise-web.tar.gz` puts the token `improvise-web` in the tree,
and AGENTS.md's audit matches `improvise-[a-z0-9]{3,8}` -- so the artifact name
resolved to no ticket and read exactly like a dead id, which AGENTS.md calls
worse than one. `improvise-installer.sh` escapes only by being ten characters,
which is luck rather than a rule, so the exclusion list gains `web` and the
paragraph gains the general case.
RELEASING.md (which arrived in this same merge, from improvise-gx5d) listed
what a tag publishes and was made wrong by omission; it now names the web
capture and says plainly that it is not what Pages is serving.
Verified on the merged tree: 1631 cargo tests over 37 binaries, node --test
47 -> 50 (so #120's three new shell tests survived the merge rather than being
silently dropped), 42 Playwright tests green under Chromium, and the stamp
gate re-proved by injecting the missed substitution again -- a header rewrite
does not carry the old fault injection.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FC2jVn8Au7E9JPkw6bwXXH
I merged twenty PRs this campaign without reading their REVIEWS. CI green plus
a dispatched adversarial agent felt like the whole gate and was not. Two
ChatGPT Codex reviews were sitting on merged PRs; both were correct.
improvise-x1ns (P2, filed, live on main): encoded_width's categorical branch
counts only distinct PRESENT values, while build_categorical maps every
missing cell to MISSING_CAT and emits an additional one-hot. A forced category
with N present values plus one missing coordinate passes the preflight as N
and materializes N+1 — caught only by the later exact check, which is the
allocation the preflight exists to prevent.
The keeper from that review: 'bounded by the later exact check' is not a
defence, because the exact check runs AFTER the allocation. It bounds the
error message, not the cost. Our own review had seen the shape and reasoned it
away on exactly that ground.
The PR #91 review described round 1 and round 2 fixed it — verified with a
probe rather than assumed, both directions. But the regression it asked for
does not exist, so improvise-4dpj now carries it.
Three things make a Codex review easy to miss, all now in AGENTS.md: it
arrives as a review rather than a comment; it posts under the owner's account,
the same one our agents use, so authorship cannot distinguish it — the tell is
the TRAILING '_Automated review by ChatGPT Codex_' where ours OPEN with
'_Posted by Claude_'; and it may target an earlier head, so a finding can be
already fixed or still live and you must check which.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FC2jVn8Au7E9JPkw6bwXXH
Measured: PRs #12, #21 and #27 carry 2, 8 and 4 Copilot reviews; #61, #66, #68
and #70 carry none. Both request paths report success and register nothing --
the GraphQL mutation returns clientMutationId null, the REST call returns 200
with requested_reviewers empty, and no review_requested event appears.
So "merge only once Copilot passes" was an instruction to wait forever on a
review that was never requested. An absent review and an unrequested one look
identical from outside, which is review_is_requested_not_inherited seen from the
requester's side. Review is now an adversarial agent the orchestrator dispatches,
naming the head SHA it reviewed; the Copilot mechanics are kept for the day it
returns.
Found by the PR #70 agent, which noticed its own review request had produced
nothing rather than assuming the review was queued.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FC2jVn8Au7E9JPkw6bwXXH
Second review pass on PR #68. All three findings real; the first two reproduced
by injection before fixing.
The candidate is validated by CONSULTING it, so the thing being checked got to
influence the check. Three ways through, all demonstrated:
- `:- halt(0).` as a delta -- fixed last round by refusing directives
- REMOVING kb_consistent: it then throws existence_error, and tpl exits 0 when a
goal throws before reaching halt, so the gate passed by not existing. The
error was printed and the tool still reported success.
- REPLACING it with the fact `kb_consistent.`, which passes forever after.
CHECK_GOAL now catches, so a throw exits non-zero, and writes touching the gate
predicates are refused unless KB_ALLOW_GATE makes it deliberate. That list is
hand-maintained and a new gate predicate is unprotected until named -- stated
rather than hidden.
Writes were read/validate/mv with nothing in between, so two agents -- ordinary
here, waves run in parallel -- would both read the same file, both validate, and
the later mv would discard the earlier addition. The lost-update class this tool
exists to remove, reintroduced in the tool. Closed by stamping content at read
time and refusing to commit if it moved, plus an mkdir lock. The stamp is the
part that matters; the lock only makes the collision rare.
AGENTS.md's top-level instruction still said to save facts through the MCP. The
wave section had been fixed; the authoritative line had not.
kb-test.sh is 17 cases. The race is deterministic via KB_TEST_RACE.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FC2jVn8Au7E9JPkw6bwXXH
Two user rulings.
Documentation should not spend itself on history -- that is bloat. Prose docs
now lead with the rule and keep only the line that stops it looking arbitrary;
the worked examples and the how-we-found-it move into doctrine/2 text, which is
what that predicate is for and where a reader goes deliberately rather than
while looking for a command. Trimmed: both skills, context/code/kb-tool.md, and
the kb paragraph in AGENTS.md.
Anything an agent posts to GitHub goes out under the owner's account, so every
comment, review and issue body now opens with a line naming the model and that
an agent wrote it. A PR body's generated-with footer already did this; comments
carried nothing, and an unattributed one reads as his own words to every reader
-- including a reviewer deciding how much weight to give it. The reply on PR #68
has been amended in place.
improvise-xfsb files the structural fix: a GitHub App or machine user so agents
post under their own identity. An attribution line is a convention an agent can
forget; a separate identity cannot be.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FC2jVn8Au7E9JPkw6bwXXH
Review on PR #68 found two real holes, both reproduced by injection before
fixing and both now regression-tested:
- A DIRECTIVE is callable, so the callable check let one through -- and the
candidate is validated by CONSULTING it, so a delta of `:- halt(0).` exited
the check with success before kb_consistent ran. The gate passed by never
running, and the directive landed in kb.pl. Directives and queries are now
refused by shape.
- Keys were checked only against the EXISTING file, so two clauses sharing a
previously-unused key clashed with nothing and the merge dropped the first --
add discarding part of its own payload. Visible in the tool's own output ("2
in delta" against one clause added) and nothing compared those numbers.
Also from the review: nothing ran kb-test.sh. A suite that gates the only writer
of kb.pl but is invoked by no workflow is doctrine(an_advisory_gate_is_not_a_gate)
in the PR that adds it. Both suites now run in the kb job.
AGENTS.md now leads with the rule instead of describing the retired procedure
first -- the review read against the earlier head, but it was half right at the
later one too: a skimming reader followed the batching paragraph.
Both tools are packaged as skills, because the failure is not that the scripts
are missing, it is that agents do not know they exist and write their own. Three
hand-rolled PR watchers in one session all reported green while wrong, which is
what scripts/pr-watch and its eight fixture cases exist to stop. One of those
cases -- a head that moves mid-wait -- was untestable until a subshell bug in the
fixture seam was fixed: fetch ran inside "$(...)", so its counter never advanced
and every poll re-read the first fixture.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FC2jVn8Au7E9JPkw6bwXXH
Three gaps in the tool as first written, each found by asking what it could not
do rather than by running it:
- There was no way to REMOVE a clause. Every correction could add or overwrite,
so a fact that went false could only be rewritten, never dropped. `kb rm`
takes keys and refuses when any is absent -- a typo'd key would otherwise
report success and leave the clause in place.
- `doctrine(kb_is_maintained_through_the_mcp)` is retired for
kb_is_maintained_by_scripts_kb. The NAME was the claim that went false, which
is the repair opfs_is_run_but_bindings_is_not needed for the same reason. The
replacement records why nobody should go back, and that READING through the
MCP is unaffected.
- AGENTS.md said kb.pl was "MCP-maintained, whole-predicate replacement" and
told agents to strip host_rpc shims after each save. Both described the
retired mechanism. This is a_fact_stated_twice_is_changed_by_grep landing
inside the PR that depends on that doctrine being true.
Also fixes a printed value that was an unevaluated expression: `rm` reported
"530-529 removed" rather than 1.
kb-test.sh is 11 cases now, both new ones proved by injection.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FC2jVn8Au7E9JPkw6bwXXH
Both are the reviewers' framings rather than mine, and both are better arguments
than the ones I gave.
AGENTS.md: under merge-as-soon-as-green a review round can finish AFTER its own
merge, and GitHub has deleted the branch by then — so a fix push to the old name
silently succeeds and accomplishes nothing. It re-creates a branch main will
never see, CI runs on it and passes, and the commit is nowhere. The tell is in
git's own output: `* [new branch]` where an `old..new` range was expected.
Happened on #51, four minutes after the merge.
design-principles §6: an argument must not live only in a commit message. I had
justified the context/ rule as "context/ is what readers grep", which is weak.
The real reason is that a commit message is write-once and unauditable — it
cannot be corrected without rewriting merged history, and NO check in this repo
can read one, because the ID audit greps source and docs and a message is in
neither. A reason recorded only there is a reason nothing can ever find wrong.
PR #51's 7d25762 is the worked example: a declined-test reason that was
factually wrong, cited across two rounds, and correctable only by #56 saying so
in context/.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Reconcile the docs with the code after wave 1.
Gotchas 1, 11, 18, 21, 42, 43, 44, 45, 46, 47, 48 corrected against the tree; the File Inventory regenerated rather than patched; kb.pl's seven now-false invariants replaced in place and the counts up (doctrine 48->55, invariant 44->51, location 31->34); the dead-ID audit recipe widened, anchored and made runnable.
Includes the repair of a false claim this campaign propagated: improvise-xps8 described a watchdog bug the merged tree does not have, because a partial simulation of PR #21's fix reproduced the original by construction. The open-then-dropped harness test now runs past the handshake timeout and asserts the false message never appears — proved discriminating by removing setShellFailure's clearTimeout.
Review findings on PR #30, all three applied.
1 [P1]. The claim that the handshake watchdog overwrites a genuine mid-session
disconnect 8s later is FALSE on any tree that has PR #21. `close` routes BOTH
arms through `setShellFailure` (app.js:248-250), which clears the timer
synchronously (app.js:165-169).
It was believed because it was measured honestly — against a tree predating
PR #21 — and then reported as "surviving" that PR on the strength of a
simulation that re-created only the `opened` flag and not the other half of the
fix, the routing. A simulated fix that is not the fix you named reproduces a
bug the real code does not have, and reads exactly like a confirmation.
Rather than delete the claim, execute the property it denied: the
open-then-dropped test now runs past HANDSHAKE_TIMEOUT_MS + 2s and asserts
"sent no document" never appears. Proved discriminating by removing
`setShellFailure`'s `clearTimeout` — the assertion then fails with exactly the
message xps8 described. gotcha 48 and the spec's comment block corrected; the
ticket is cited in neither. Recorded as
doctrine(a_simulated_fix_must_be_the_fix_you_named), the sibling of
an_injected_fault_must_be_the_fault_you_named that fails the other way: a wrong
fault proves a check that cannot fire, a wrong simulated fix proves a bug that
does not exist.
2 [P1]. The previous commit created the contradiction it was meant to remove:
design-principles recorded the measured ~2.2s while kb.pl still said "under 2
seconds". The ambiguity between per-binary and wall clock is what let it drift,
so both now state two numbers — no single binary over 2s, wall clock is the
sum, measured 1309 tests / 33 binaries / ~2.2s / longest 1.42s — in kb.pl,
design-principles and repo-map alike. Also 16 -> 17 in doctrine(binding_dump_diff).
3 [P2]. The new audit exclusion was unanchored, so `improvise-gp` was a prefix
match that would silently exclude a real future ticket. Anchored `^…$`. It
immediately caught the example id the explanatory paragraph itself spelled out
— a recipe is code, twice over.
CLAUDE.md: declined, with evidence. Both copies of the duplicated tail sit
inside `<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:ca08a54f -->`
markers written by `bd setup claude` and `bd setup codex` and refreshed against
that hash. A process change there is one tool invocation, not two hand edits,
and a pointer makes `bd setup <recipe> --check` report it modified. Recorded as
kb_issue_found(claude_md_tail_is_generated_not_duplicated) so it is not
re-proposed.
kb.pl: doctrine 54->55, kb_issue_found 11->12; invariant 51, decision 47,
location 34 unchanged. kb_consistent passes.
cargo test --workspace: 1309 passed, 0 failed, 2 ignored.
harness (Playwright): 12 passed, 3 skipped (webkit has no OPFS).
Dead-ID audit with the anchored recipe: 157 tokens, all resolve.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
An independent review checked every factual claim in the docs against the
code at 22d43b2, after eight PRs landed in one wave. This applies its
replacement text.
context/repo-map.md
- gotcha 44 rewritten: the cache DOES frame the grid now (improvise-anr9,
AxisFrame/FrameEntry/header_level_widths). The surviving half — the TUI
builds at offsets zero, so a cache position is absolute — is kept,
because four code comments cite gotcha 44 for exactly that.
- gotcha 45: ClientFrame::Save exists (improvise-368h); MarkDirty is gone
and dirtiness is read off EffectKind::Model(_); Rc<T>: Storage lives in
improvise-io (improvise-hmws); OpfsFs::list joins dir (improvise-vhcz);
OpfsFs is run by harness/ and bindings.rs is now the dark corner.
- gotcha 47: Host::commands answers the frame whole (improvise-955n); the
open hole is clause 4, not a per-command Checked. set_viewport "must"
-> "does".
- gotcha 43: the frame, not the command, is what is answered; two of three
tiers hoist.
- gotcha 21 widened: three effects abort, and tidy-up goes at the head.
- gotcha 48: web/app.js is executed by harness/tests/shell.spec.js;
improvise-m18f -> improvise-taxx (fixed); the open half is improvise-xps8.
- gotcha 42: the never-rendered / improvise-hwpi sentence pair deleted.
- gotcha 18: live_records and analyze_records are both decided now.
- gotcha 1: the records columns are [coords…, +cat, measures…, +].
- AppMode is 17 variants, ModeKey is 17, eight text-entry modes; the keymap
table moved to improvise-protocol/src/keymap.rs (six references).
- the Wasm section: the mirror is gone; the wasm gate covers eight crates.
- the File Inventory regenerated rather than patched (57/79 rows were
stale); the duplicate ws-server/host.rs collapsed to a pointer at the
23-line shim; harness/, protocol keymap.rs/viewmodel.rs, improvise-gp
fit.rs/dataset.rs, cmd/fit.rs, model/record.rs and the integration tests
added.
- the suite speed re-measured rather than re-asserted.
README.md — the four "no browser here" sites narrowed to what is still true;
17 modes; the browser section names the Playwright harness.
AGENTS.md — the dead-ID audit recipe was itself defective: two paths, a
character class blind to a commit SHA, and a two-name exclusion list. Widened,
made runnable under the worktree shell guard, and its own prose no longer
spells any id.
prolog-sessions/kb.pl — seven invariants replaced in place (they were false),
five location/3 facts re-sited plus three new, six doctrines and seven
invariants added. doctrine 48->54, invariant 44->51, decision 47 unchanged,
location 31->34. kb_consistent passes.
Comment-only Rust changes: a duplicated sentence in worker.rs, records_columns'
doc omitting NewCategory, improvise-709f2df -> commit 709f2df, and three more
copies of "OpfsFs has never been run".
cargo test --workspace: 1309 passed, 0 failed, 2 ignored — unchanged.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The browser JavaScript is argued, not tested, and the two rules it can break
are both about WHEN: an async message listener does not serialize, and a
watchdog must be disarmed rather than pre-empted. Both found by review
rather than by a test, because nothing here runs a browser.
Plus the third thing no test can see: three comments in one range said 'not
built yet' about work that landed in that same range, each because a
follow-up commit updated one copy of an argument and not its siblings.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EoW5BB87ZZdm96SvBTWawH
Work reaches GitHub as a branch and a PR. The orchestrator still merges
agent branches into its local main to integrate and run the gates -- that is
how conflicts get found early -- but the push is a branch push.
Written because it drifted: 27 commits across six agent branches, including
a new crate, a new protocol type and a type moving between crates, went
straight to main unreviewed while this file already said not to. Records the
review-only PR as the cheap repair, and that rewinding the default branch to
fake a mergeable PR is not worth it with other collaborators on the repo.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EoW5BB87ZZdm96SvBTWawH
Six improvise-* IDs cited in repo-map and ADR 001 never existed -- filed
with output suppressed and then written into the docs from memory. A dead ID
is worse than no ID, because it reads as a promise the follow-up exists. All
six corrected to the real tickets, and AGENTS.md gains the audit loop.
AGENTS.md also gains what PR #12 learned: requestReviews takes botIds and not
userIds, gh is shell-aliased to a different tool here, a Copilot review takes
about six minutes, and a finding can be CORRECT and still be wrong to fix in
that PR -- #12 applied a truncate panic (byte-identical on ASCII, so it cost
no evidence) and declined a padding bug in the same file that would have
rewritten the characterization tests which were the PR's only evidence.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EoW5BB87ZZdm96SvBTWawH
Most work here is done by waves of agents in worktrees, and every rule in
this section was learned by breaking it: the three orchestrator-only files
and why, that kb.pl additions must be batched because loadProgram replaces a
whole predicate, that tickets sharing a file belong to one agent, that a
worktree does not reliably branch from the orchestrator's HEAD, that direnv
status reports 0 for allowed, and that the code review's characteristic find
here is a test that passes while the thing it names is broken.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EoW5BB87ZZdm96SvBTWawH
Edward Langley
Cursor Agent