- 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>
1. Shebang (Codex P2): scripts/agent-bootstrap.sh and .claude/hooks/session-start.sh
now use #!/usr/bin/env bash instead of #!/bin/bash, matching repo convention
enforced by checkers.sh.
2. Fail-closed bd pin (Codex P2): .claude/hooks/session-start.sh local path now
exits 2 with a warning when pinned or running version cannot be parsed,
instead of silently succeeding. An unparseable version is not a pass.
3. pr-reviews failure (Codex P2): scripts/pr-watch no longer uses '|| true' to
swallow pr-reviews failures. If pr-reviews fails (fetch error, malformed
response), pr-watch now exits 6 with a warning. Empty successful fetch
(no reviews) is still exit 0.
- Added exit 6 to usage text and skill documentation
- Added test case 'pr-reviews failure exits 6' using malformed JSON fixture
- All 57 pr-watch tests pass
Co-authored-by: Ed Langley <fiddlerwoaroof@users.noreply.github.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>
context/code/protocol.md gains section 10 and tui.md's colour section now
describes face_style; the pointers to axis_fg, minibuf_fg and AxisColor
elsewhere follow. Evidence for the new tests.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdfEGXA7aJ6ftMsCc9PJze
The wrapper's contract drops cherry-pick, because git ignores
GIT_AUTHOR_NAME there, and rule 8's cherry-pick -x should keep who wrote
the commit. A new case asserts it. The pre-push check now asks that every
commit you made names your actor, since a stacked or cherry-picked commit
keeps its own author. Answers the Codex P2 and the review on PR #310.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdfEGXA7aJ6ftMsCc9PJze
The rule sits beside the claim in agent-rules.md, and the brief checklist
in wave/SKILL.md ties the actor to it. The evidence entry records why the
wrapper sets GIT_AUTHOR_NAME and not user.name, and its two rivals.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdfEGXA7aJ6ftMsCc9PJze
Answers the Codex P2 on #306: the type list read as exhaustive and left out
refactor, perf and style, all in use on main. Ad-hoc prefixes become a
standard type with a scope, and the user's quote is marked [sic].
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdfEGXA7aJ6ftMsCc9PJze
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
ci.yml: this branch's check-harness-lock --allow-network step is kept, ahead
of main's nix-build clippy and test steps that #228's merge brought in.
test-evidence/tooling.md: both EOF appends kept, no heading lost (42 = union).
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
The required Browser harness check comes from a job that needs: build, so for
a moment per push every registered check is green and GitHub says
MERGEABLE/BLOCKED. #186 at 128a2a0 refused that and exited 1 on healthy PRs.
BLOCKED with no failed check is now waited on (exit 3 if it never clears).
Adds the gap sequence from PR #189's real rollup, and a head moving during
the UNKNOWN wait. Corrects tooling.md's claim that nothing else produces
BLOCKED, the evidence entry's rival-2 claims, and the fixture wording.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdfEGXA7aJ6ftMsCc9PJze
The restated list said cargo fmt --all --check, which reaches one of two
workspace roots, and omitted direnv exec, checkers.sh and node-test.sh.
agent-rules gains two rules from PRs #176 and #177.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdfEGXA7aJ6ftMsCc9PJze
Only the .agents copy is edited: .claude/skills/pr-watch becomes a symlink to
it in the improvise-5fzx PR, and editing both here would make that PR's merge
a modify/delete conflict.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdfEGXA7aJ6ftMsCc9PJze
The kb skill (both copies) now describes the HEAD comparison, the ledger,
exit code 3 and the recovery. kb-tool.md records the ih3k/yea8 arguments and
corrects the residue paragraph: .gitignore hides the leftovers, and there are
six, not one.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VdfEGXA7aJ6ftMsCc9PJze
The move in b6d2c47 dropped two items from the old brief lists: the agent
checking its base against the named commit, and reporting branch, head SHA,
PR number and per-ticket changes. The attribution line now comes from the
brief, so the shared file stays agent-neutral and ours still open with
"Posted by Claude".
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
The skill covers the four things that bit us today: the per-clone git config
the driver needs (.gitattributes names it, but the driver lives in git config,
which a checkout does not carry -- without it git silently line-merges), how to
recover a file that already has markers in it, where genuine same-issue
divergence is reconciled (bd conflicts, against Dolt -- not reconstructed from
the JSONL), and the autostash trap that writes markers without anyone running
`git stash`.
Driver verified against a real conflict: plain text merge produced 3 marker
lines and 3 invalid JSONL lines; the driver produced 470 rows, 0 invalid, and
left the database byte-identical (470 rows before and after).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FC2jVn8Au7E9JPkw6bwXXH
Edward Langley
Cursor Agent