Skip to content

PATCH as the mock's canvas, every function kept (Plan-008 C2a) - #117

Merged
alexnodeland merged 19 commits into
mainfrom
claude/shell-c2a
Oct 4, 2026
Merged

alexnodeland merged 19 commits into
mainfrom
claude/shell-c2a

Conversation

@alexnodeland

Copy link
Copy Markdown
Owner

Plan-008 PR C2a: PATCH is rebuilt as the mock's canvas, and no PATCH function is dropped. C2b (the ⌥ model view in PATCH and the four engine facts) follows.

What changes

  • Head: PATCH · FAMILY, the title, and N modules · M modulators, in signal order, from the rack's real counts.
    • Actions: ⚡ EVOLVE FROM THIS ▾ (lock knobs / lock wiring / clear locks), ADD MODULE (/), NEW PATCH, HOW TO READ THIS.
    • In a new patch: CLEAR and BACK TO ‹name› (Esc).
  • Edit bar: N changes · KEEP AS NEW · pick the edit, shown only after an edit.
    • ↺ undo to as opened runs through edit_set_tree, and waits until the bench has settled.
    • A refused ↺ says why.
  • The well: plates in signal order and the measured face at OUT (a click plays).
    • Audio cables are curved, with a/b by the jacks; modulator cables are dashed and labelled depth · Hz.
    • Level marks on the cables are measured.
    • Plates carry every knob: values and labels under them, and the kind's setting in the head. ENV's head draws its knobs.
    • A compact detail level is used where labels would stop reading.
  • Selection and structure: plates are a listbox; the readout sits at the well's foot.
    • ⋯ / right-click / F2 open the structure menu (replace, insert, duplicate, set aside, bypass, modulate, probe, swap, delete, unplug).
    • Locks: L, a solid edge when locked, and dots on knobs on hover or focus.
  • Catalog on demand (ADD MODULE, /): search, set aside, in-this-patch, groups, port pips, spec card, legend, drag or click to arm.
    • θ shows only under ⌥.
    • Armed placement lights sockets and shows a price line and ▶ preview.
  • The guess: a dashed ghost plate, GUESS · KIND and the reason on the well's top line, Enter takes it.
  • Camera corner: fit · − · + · map · layout ▾ (chain / compact / by hand, snap, reset), bookmarks, ⌘0/⌘−/⌘=. Ctrl-wheel zooms the camera.
  • Other:
    • SET ASIDE n is kept across reloads.
    • TEACH · N PICKS ▸ is folded at the well's foot.
    • The scope is off until asked for.
    • PATCH's first-steps pill begins with Play it.
    • The pill's × closes it per level.
  • Keys (mock):
    • Plates: ←/→ walk them in signal order, ↑/↓ move into modulators, Enter goes into knobs or takes the guess, Esc steps back out.
    • Home/End (canvas only, never under a modal), ⇧Home, Delete, L.
    • Knob runs are one undo step.
    • Notes still play; the keys yield to text fields and modals.
  • Lanes (AUDIO IN, TRACK, CAPTURE) are drawn in the plate style with every control. The touch sheet presses the lanes' buttons.

Tests

  • New: patch_canvas, patch_catalog, patch_keys, patch_camera, patch_touch specs, plus guide_pill and guide.test additions.
  • Spec changes that change meaning:
    • guide_pill: 4 PATCH pips, and closed is per level.
    • text_fits: #nextstep is attached-only while a pair is dealt.
    • patch_keys: Home is pressed with nothing in focus.
  • Gates: make web-check (116 pass), make dev-check clean, wasm-stamp. All targeted specs pass locally; CI is the gate.

Not matched to the mock, on purpose

  • Setting words are the engine's option names (svf lp), and values are heard units (448 Hz), not normalized.
  • Every knob is drawn.
  • ENV / OUT, not AMP.
  • 1000 px is compact.
  • Below 1600 px, HOW TO READ THIS keeps only its glyph.

Cache-busters bumped. The voice.md rows follow in this PR once approved.

https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW

… ⚡ ▾

Plan-008 C2a, first step. PATCH's two toolbar rows (subject block,
callout, ⚡, teach pair, camera group, locks) become the specimen's head:
PATCH · FAMILY (a preset's category, only as made), the name at the
display size, and a subtitle the rack counts ("4 modules · 1 modulator,
in signal order", with the layout's own words when it is not the chain,
and the states the caption used to carry). On the right: what to do next
above the acts; ⚡ EVOLVE FROM THIS with a ▾ holding lock knobs, lock
wiring, clear locks and, while a stoppable ⚡ runs, stop; ADD MODULE (/);
NEW PATCH (CLEAR, BACK TO ‹name› in a new patch); HOW TO READ THIS, a
legend over the well's foot that says what each mark is, measured or not.

The edit bar ("N changes · KEEP AS NEW · pick the edit ☐ · undo to as
opened") shows once the bench is edited, in a row the head always keeps,
so nothing moves. N is the undo steps since the open (the stack starts
empty at every open); "undo to as opened" is one edit_set_tree to the
bottom of the stack, settled as that many undos (settleRestore with
`all`), so ⇧⌘Z brings them back in order. Past the stack's 60 steps it
is withheld and says why. The commit pair stays.

The camera group moves to the well's bottom-left corner unchanged (its
own commit restyles it); the budget joins the subtitle (near a ceiling,
or under Show measurements, today's rule); the belief line stays above
the well until C2b gives it a home under ⌥.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW
…plays

Plan-008 C2a. The rack's frame becomes the specimen's well: a rounded,
recessed canvas, the viewport inside it without an edge of its own. The
plates take the specimen's look over the same SVG (a flat plate with a
hairline edge and its name in silk caps; no bevel, screws or pocket;
modulators dashed), and a knob is its travel and value arcs and a
pointer. Every hook the specs and the motion system read stays on its
node.

Past the amp the build draws OUT (a lead, the jack, its name) in the
amp's own group, so it travels with it, and leaves a zone for the face
at OUT (OUT_ZONE, counted in the rack's size and in every fit). The face
is #rack-play itself, an HTML button the camera places over that zone
(placeOutFace, from applyView): the bench's measured face, the same
target as the menu bar's chip (an edit's once its render lands, never an
estimate), and a press plays the bench's phrase, waits for an edit with
▶'s dotted ring and says why when it can't, as the rack's ▶ did. The
head's small face beside the name goes; faces.spec reads the one at OUT.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW
…dges count what is past them

Plan-008 C2a. A modulation cable into a module now carries the
specimen's label, "depth 25% · 0.51 Hz": the host's mod depth and the
modulator's rate (up a chain to its source), each printed as its knob
prints it, so the words are the knobs as set and never a measurement.
It is repainted with the knobs on a value-only redraw, and leaves under
the silkscreen floor with the readouts.

When the patch is wider than the view, the well's edges say how many
modules' middles lie past each side (‹ 2 · 3 ›), and a press glides the
nearest one to the middle of the view (--d-move, instant under reduced
motion). Refreshed from applyView, so a pan, a zoom or a fit updates
them.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW
…spec dock retires

Plan-008 C2a. One module is selected at a time: the plate the keyboard
stands on, or the one a press landed on (not on a knob, jack or button);
a press on the well's bare floor that does not become a pan clears it,
and a rebuild keeps it by key. The selected plate shows its ⋯ (the
structure menu) and its lock, with its edge and name lit; other plates
show them only under the pointer (on a coarse pointer, always). A locked
plate's edge is solid amber, no longer dashed.

The readout (`#pt-read`) sits at the well's foot, beside the camera's
corner: the module under the pointer or the selected one, by name, with
its setting and what it does in one sentence. Pointed at in the
catalogue, a module's longer description (ports, settings, what is
heard, how your taste leans) opens over the well's bottom edge, so the
well never resizes on hover; at rest it says nothing. The spec dock
under the rack and its resizer (and `auracle-spec-h`) go: the armed line
lives in the readout until it moves to the well's top line. The toast
lane steps over the foot.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW
…nd on its top line

Plan-008 C2a. The module rail beside the rack becomes the specimen's
catalog (`pt-cat`): a panel over the well's left, closed at every start,
opened by ADD MODULE and /, closed by ✕ and Esc (after a module in hand,
before a new patch). It keeps everything the rail had: the search
(#nb-q), what is in this patch, the groups, the port pips, the legend,
the status line, the keyboard grid, drag a module to a socket, click to
take it in hand, the walkthrough, the guess's mark on its kind. θ is the
model view's now: the bars show only under ⌥ (the walkthrough's step
says so). A new patch opens it, as the specimen's np-desk does, and
leaving the new patch closes it. While it is open, fits keep its width
clear, and opening it over plates makes room with a jump. The rail's
collapsed tab and its width handle go with the rail.

The thing in hand moves from the strip under the rack to the well's top
line (the pick chip, no longer pinned to the plate): the module, its
price ("prices what, not where"), ▶ to hear it at the socket with that
socket's scope, how many sockets are lit, what happens at the socket
under the pointer, Esc or ✕ to put it down. The guess's line steps aside
for it. Fits keep the top line and the foot clear as well.

Specs that place a module open the catalog first (openCatalogue in
shell.js); taste_marks reads θ under the model view.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW
… the layout's ▾

Plan-008 C2a, round 2's camera decision. The toolbar's camera group
becomes quiet corner controls in the well's bottom-left: fit · − · + ·
map · layout ▾. The ▾ is a menu (arrows, Esc, a press outside): chain,
compact, by hand; snap to the grid and reset positions, which act on a
layout by hand only; the level of detail; leans (which C2b moves under
⌥). The map stands over the corner, its bookmarks with it (⇧-click,
⇧1–9); the fit hint becomes a note over the corner. Every gesture on
the canvas is unchanged, and the subtitle names the layout.

The compact level of detail is now the specimen's plate: each module
shows its first three dials to read (their arcs and pointers as set,
repainted with the knobs), not to grab, where it used to show none.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW
…, Enter in, Esc out

Plan-008 C2a, round 2's keys decision. On a module: ←/→ walk the
modules in signal order (left to right as drawn, the model's guess
among them), ↑/↓ go to the nearest module below or above (into a
module's modulators and back out), Home/End the first module and the
last (the amp, at OUT), Enter into its controls, F2 or the context-menu
key its structure menu (right-click still opens it), Delete removes it
through the survivor choice, l locks it, / puts a module after it, and
Esc leaves it. Inside a module the arrows walk its own controls and
stop at its ends; ↑/↓ turn a knob (⇧ finely, a run one undo step),
Enter or Space cycles a setting, Esc goes back to the module. Home and
End reach the modules from anywhere in PATCH, and fit-all moves to
⇧Home; `.`, ⇧1–9, ⌘0/⌘−/⌘= and ⌘Z/⇧⌘Z are unchanged.

Esc is one chain: a knob, then the module, then the catalog, then a new
patch. A pointer's turn still leaves no focus, and PERFORM's pad keys
stay PERFORM's. The ? card and the rack's accessible name say the new
keys; audio_in_takes enters a module's controls with Enter before
walking them.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW
…ps; the sheet's face

Plan-008 C2a. What was unplugged, deleted or bypassed is no longer a
strip under the rack: SET ASIDE n sits at the well's foot beside the
camera (only while something is set aside) and opens the shelf to drag
from; the catalog lists it first too. Every item keeps its jack to drag
back onto a ○ and its ✕, kept across a reload as before, with a finger's
reach on a coarse pointer.

The TEACH strip folds into a chip at the foot's right end (shown while a
pair is on the table) that unfolds it over the well, with ✕ and Esc to
fold it again; "Teach it your taste" opens it.

The bench's one-line tour becomes PATCH's first steps in the guide
pill, one at a time, each ticked when it happens: turn a knob, lock
what you love, ⚡ (guide.js now holds steps per level and says each
level's closing line; a tour already dismissed counts them done). The
pill shows on PATCH under its well, PERFORM's steps on PERFORM.
"Play it first" is PERFORM's first step, so the head's next step says
nothing until a key is played; what is not onboarding (refit, breed a
generation, what it bred) stays pressable there.

The touch sheet shows the bench's face beside its settings, the one at
OUT: "as made", "measured" once edited, "measuring…" while an edit is
on its way. AUDIO IN modules that read one input draw one stream fanning
out to each, as the specimen does, read off their input knobs.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW
…eet, a finger's reach; specs for the canvas

Plan-008 C2a. The edit bar's compare, which the inventory placed on
paintKnobKept, could not live there: that files PERFORM's performed
value behind a knob, not the value before an edit. So each continuous
knob now keeps its value as the sound was opened (by node identity, so
a structural edit leaves it on its knob) and, once turned, shows a pale
tick there; HOW TO READ THIS says what it is.

On a touch screen the module sheet carries AUDIO IN's input line,
MONITOR, NEW CLIP and ALLOW INPUT and CAPTURE's RECORD as 44 px buttons
that press the lane's own on the rack (one of each, its state read back
after the press), since the lane's buttons are 20 rack units tall. The
head's acts, ⚡ and its ▾, and a plate's ⋯ and ▢ pads reach 40 px under a
coarse pointer. A menu item that disables itself on its own press (clear
locks) still folds its menu, and the face at OUT keeps the focus ring
with the waiting cue on its edge, as ▶ did.

Specs, one per area: patch_canvas (the head's counts, the face at OUT
is the bench's and plays, the edit bar and KEEP AS NEW, undo to as
opened in one restore, ⋯ on the selected module reaching every verb, L
and ⚡'s ▾), patch_catalogue (ADD MODULE and /, search, the top line's
price and ▶, a drag placed, θ only under ⌥, set aside first),
patch_keys (signal order, into modulators, Enter and Esc, ⇧Home, F2 and
Delete, the Esc chain, armed placement, keys yield to the search and
notes still play), patch_camera (the corner, the layout menu, map and
bookmarks, ctrl-wheel zooms the camera not the level, the edges) and
patch_touch (sizes, ⋯ by tap, the sheet's face and lane buttons).
patch_audible reads the face's look in place of ▶'s glyph.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW
…ntime notes and the plan

Plan-008 C2a changed what PATCH shows, so every page that describes it
says what is there now (ADR-004): the PATCH page is rewritten for the
head, the edit bar, the well (modules in signal order, OUT and the
face, the cables' depth and rate, the edges, the guess and the thing in
hand on the top line, the foot's camera, SET ASIDE, readout and TEACH),
the catalog, first steps and the sheet; rack.md for getting around (the
corner, the keyboard's walk), the layout's ▾, locks in ⚡'s ▾ and the
selected module's ⋯; wiring.md for the catalog in place of the module
rail; keyboard.md for PATCH's keys and the Esc chain; and the pages
that named the rail, the strip under the rack or the quick-pick strip
(accessibility, faces, glossary, playing through, reading the model,
teaching, the bank, first session, your data, the guess's reference,
the READMEs). web-runtime.md gains how the canvas is built; the plan
records C2a as built (where it differs from the mock and round 2, and
the film selectors it leaves stale); the CHANGELOG says what changed.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW
…he catalog

The fan from one input to several AUDIO IN modules is drawn left of the
first plate, past the rack's origin, and contentBox floored the fit at the
origin, so its name was shaved by the well's edge. The fit now includes the
fan's box (rackExtras) and its floor follows it.

Beside the open catalog the well's top line kept the well's whole width as
its limit and started past the catalog, so the price, the preview's play
button and "N sockets lit" ran off the well's right edge at 1000 px. The line
now takes what is left and wraps.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW
Opening a preset fits it with a tween, and three of the camera's claims
read the viewBox right after: the bookmark's zoom, ctrl-wheel's "smaller
than before" and the edge's pan. Read mid-tween, the baseline was a frame
of the fit rather than the fit, and one in fifteen runs failed. The spec
now waits for two reads a quarter second apart to agree (20 of 20 passed).

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW
…arrow

At 1000 px with the catalog open, the readout beside it is about 330 px
wide, and the longer description over the well's foot kept its three
columns: each a word wide, rising past the top of the well. The readout is
now a size container and below 560 px the columns stack, with the card
scrolling at 300 px. At 1440 nothing changes.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW
…do, keys, focus, the lean and first steps

Review of C2a against the mock and the code.

The mock's plates read at the fit a patch opens at; ours were drawn for a
2x zoom and fitted at 0.6-0.7x at 1440, so the silkscreen floor took every
value and label and the settings were blank chips. The plates are re-sized
(PLATE_W 84-240, KNOB_R 11, a 30-unit head, 56-unit rows, LAYER_GAP 56,
FIT_MAX 1.25): every stock preset now opens at 0.84-1.19x at 1440 (Loom,
the widest, 0.69x) with each name, value and label at its token's size.
The setting that names a module's kind is the control in its head; each
knob prints its value then its label; a setting prints its value (no
chip); the amp's head draws its envelope from its four knobs. Audio cables
are level S-curves, a two-input module's a/b sit outside it, plain in/out
are not printed. Compact is where readouts stop reading (under 0.68x, with
its band above the line) and draws names and settings larger, keeping
AUDIO IN's and CAPTURE's lanes for the touch sheet's buttons. ⋯ and the
lock moved to a pocket on the top edge, finger-wide on touch. The scope is
off until asked for (it sat over the toasts), the belief line moved onto
the well's top line and is empty without a guess, and the picks to the
first refit have one home, the TEACH chip, which counts them. The armed
line lets the pointer through to the sockets under it.

Undo to as opened and ⌘Z waited only for the lane, so during an open they
restored the leaving sound's tree under the arriving id. Both wait for
benchSettled now; a refused ↺ says why (aria-disabled, so the press
arrives), its toast is said when it lands, and its UNDO retires on the
next step or restore. Global Home/End ran before the steered-control check
and under modals: End on VOL walked to the amp, Home in the comparison
focused a plate behind it. They are the canvas's now. A pointer's ✕ on
the catalog or TEACH no longer hands the focus to a chip (Space played
nothing); the lean shows under the model view only, as the copy said; ×
on the pill is per level, and PATCH's first step asks a player who has not
played to play.

Lows: TEACH resets with its pair, closing the catalog cancels a ⋯ handoff,
the tour's lean step points at MODEL, the keyboard card stands beside the
catalog, the selection follows the module's uid, one Esc closes one thing,
lock-clear's reason is the new one, dead pick-chip code is gone, mod-cable
words step aside while a plate is dragged, patch_touch waits on state, and
catalogue is catalog (patch_catalog.spec.js).

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW
…w left them

The guide's PATCH page, rack.md, keyboard.md, accessibility.md, wiring.md
and the first session say what the canvas now shows and does: the kind's
setting in the head, values then labels, the envelope drawn from the knobs
(not the sound), curved cables with a/b by them, compact where labels stop
reading, the scope put away until asked for, the belief line on the well's
top line, TEACH counting the picks, ↺ saying why it can't go, Home/End
belonging to the canvas, the lean under ⌥ only, × per level and PATCH's
play-it step. The runtime notes, the plan's as-built and the CHANGELOG
follow.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW
drawLane painted the lane's state but not its meter, and the meter loop
runs only while an input is open. Lanes are now drawn in compact too, so a
level-of-detail switch after an input was unplugged left a fresh lane with
the meter as built (height 0) rather than as painted (0.0), and the same
for its face. drawLane paints that lane's meter and face as they stand.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW
…p aside under a dragged plate

Two of the review's low fixes had no spec. Closing the catalog now cancels
a socket ⋯ handed it (the line goes, and the next module clicked is only in
hand, nothing posted), and the modulation cable's words hide while a plate
is in the hand (they are placed at the build, the cables move every frame)
and come back when it is put down.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW
The catalog replaces the module rail; first steps are per level; the edit
bar, the well, the camera corner, detail, TEACH and SET ASIDE get rows.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW
…he Browser job gets 25 minutes

CI went red on two specs that turn the knob the bench opens with
(keys_are_not_notes 102, evolve_truth 181) and on patch_editing's Loom
spec. The last round moved automatic detail's compact line to 0.68x, where
the readouts stop reading. The pool sound a first visit opens (ten modules)
fits at 0.51x at 1440, so it opened compact, with no knob to turn from the
mouse or the keyboard; Loom, at 0.69x locally, crossed the line on the
runner. Compact is the specimen's plate to read, not to edit, so it has to
stay where a knob really is too small for a hand: the line is 0.45x (a
10 px ring in a 16 px target, about the old knob at its floor), with the
hysteresis band below it again. Between the two, the silkscreen floor
leaves the values and labels off as it always did, and the names and head
settings now print larger there, as compact draws them, so each module
still says what it is. The new spec zooms Reese out to 0.48x and checks
the knobs are drawn, the values are off, the names show, and the keyboard
still turns one.

The Browser job's timeout goes from 20 to 25 minutes. Shard 1 already
took 19.6 of its 20 minutes before C2a's twenty-odd specs, each a fresh boot
of 7-17 s with only state waits. Shard 2 was cancelled at 20 minutes, after
spending 75 s on the two failures above. Sharing a boot across tests would
make them depend on each other's order, so the job gets the time instead.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW
@alexnodeland
alexnodeland merged commit 50b0a7c into main Oct 4, 2026
24 checks passed
@alexnodeland
alexnodeland deleted the claude/shell-c2a branch October 5, 2026 13:31
alexnodeland added a commit that referenced this pull request Oct 5, 2026
…e one source; the ship skill (#149)

* docs: how work flows, written down once (RFC-009, ADR-019, docs/process.md)

The flow from an idea to main was spread over CONTRIBUTING, testing.md,
area AGENTS.md files, agent briefs and a lead session's notes; outstanding
work lived in plan prose, and several rules (no retries, quarantine with an
issue, voice rows approved first, agents commit while the operator ships,
review before every PR) existed only in conversation. The maintainer asked
for the process to be made canonical.

docs/process.md is the living page: twelve stages from an issue to a closed
issue, the issue labels and milestones, building in worktrees, the review
checklist, PRs, CI and merging, flakes, dependencies, releases, status
updates and the machine's rules. RFC-009 argues it, ADR-019 records the
rules. The docs index gains them and the missing ADR-018; plans say their
tasks become issues; CONTRIBUTING links the page and no longer says make
check is all CI runs.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW

* docs(agents): the front door points at how work flows

Root AGENTS.md gains rule 9 (issues, a worktree per branch, agents commit
and the operator ships, review before every PR, merge on green, flakes fixed
or quarantined, new words approved) linking docs/process.md, and its commands
table says what make check runs and how a PR is waited on and merged.
CLAUDE.md listed a `site` skill that does not exist; it now lists `ship`,
and says agents hand back while the operator pushes, opens PRs and merges.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW

* docs(skills): a ship skill, and the skills say how CI and flakes work now

`ship` takes one task from its issue to a merged PR as docs/process.md
says: the worktree, the brief's essentials, review before the PR, the PR
body, waiting on CI by state, the checked squash merge and the clean-up.
auracle-strategy points at process.md and ADR-019 and lists the skills that
exist (`site` never did); check says CI is the gate and adds the spec and
workflow rows; browser-test covers make browser-changed, the eight runners,
spec-only PRs, the merged HTML report, the shared fixture when present, and
quarantine instead of retries.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW

* docs(skills): changelog says which changes get no entry

CI, specs, refactors and the contributor docs leave the release notes
alone (as #118, #119 and #121 did); a fix a player could see gets an entry
even when a test found it.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW

* docs(agents): builders commit and hand back; the reviewer has the checklist

web-engineer, engine-engineer, docs-writer and film-producer say where
their work goes: their own worktree and branch, commits only (never push,
PR or merge), Refs #N, no hand-written attribution, the fast gates and their
own specs rather than the full suite, voice rows drafted not committed, and
nothing moved without a home by mouse, keyboard and touch; each report
starts with the head SHA. The reviewer gains the drop-nothing, ADR-004/012,
spec-robustness and process checks it has been asked for in practice, a
verdict line, and how to review only the fixes. docs-writer no longer points
at a `site` skill that does not exist.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW

* chore(github): the PR template and a task and a flake issue template follow process.md

The PR template still asked for `make check` with release tests as the gate;
it now asks for what docs/process.md requires: Closes #, the review before
the PR, the fast gates and the specs the change reaches (CI runs the rest), a
test named for the behaviour, descriptions true, nothing dropped by mouse,
keyboard or touch, voice rows approved, wasm and cache-busters, no retried
test. New issue templates: Task (plan, decisions, brief, done when, depends
on) and Flaky test (the test, the run, why, the fix, quarantined?), plus a
config link to the process page.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW

* docs: the plans' open tasks link their issues; the cache-buster rule as practised

Plan-008's progress table gains an Issue column (C2a merged as #117; C2b in
review; #130–#132, #136, #139, #133/#134 to do). Plan-005 lists its open
tasks (8 touch #134, 11 the own-sound card #133). process.md says which of
two branches bumping ?b= takes the next value.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW

* docs: every CLAUDE.md is the one-line import; the Claude Code setup moves to AGENTS.md and .claude/README.md

The root CLAUDE.md carried the skills, agents, hooks and plugins tables
after its @AGENTS.md import, so the rules lived in two kinds of file. Now
every CLAUDE.md, the root one too, is `@AGENTS.md` (Claude Code loads
CLAUDE.md, so the shims stay); the root AGENTS.md gains a short Tooling
section, and .claude/README.md holds the detail.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW

* make: a branch's AURACLE_TEST_PORT reaches browser-changed, -fast and -slow

The browser targets ran on BROWSER_PORT (8690) whatever port the
environment had set, so a worktree's own port never reached them. Now the
port is AURACLE_TEST_PORT when set, else BROWSER_PORT, else 8690.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW

* docs(process): the merge rule as GitHub enforces it, and who pushes what

main's ruleset now requires the CI check with no bypass, and merged
branches delete themselves; process.md says so. Before a merge, a PR that
touches the app, tests, crates or CI is rebased if main moved, force-pushed
with lease and re-checked; a docs-only PR may merge behind main, where main's
run verifies it in full (reuse needs the same tree). While building or in
review, a rebase only resolves a conflict. Agents' branches are pushed by
the operator; a contributor pushes their own. Most PRs close an issue; a
Dependabot bump or a small fix seen in passing may stand alone. Small fixes
skip stages 2-4; stage 3 is an ADR per decision and a plan when the work
spans PRs. Voice approvals are for words voice.md's table governs. The
full-ci label, the backlog (no milestone), gh pr create --title, and where
a branch's port comes from.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW

* docs: ADR-019, RFC-009, CONTRIBUTING and AGENTS agree on pushing, issues, rebasing and voice

Agents commit and the operator pushes; a human contributor pushes their own
branch or fork. Most PRs close an issue, a Dependabot bump or a small fix
seen in passing may stand alone. Rebase only for conflicts while building;
before the merge, a PR touching app, tests, crates or CI catches up with
main and is re-checked, a docs-only PR may merge behind. main's ruleset
requires CI with no bypass. Voice approvals are for new rows in voice.md's
word table, as voice.md § How this is kept says. RFC-009's context no longer
says issues held "only" flakes (#62, #129), and it notes its one ADR and no
plan.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW

* docs(skills): ship works from any directory, opens issues non-interactively, and catches up before merging

Every git and gh command names the repository ($REPO and the worktree's
path for git, -R for gh). gh issue create --template fails without a
terminal and drops the template's labels, so step 1 passes the body
(frontmatter stripped), the labels and the milestone. CI is looked up by
the head SHA throughout. Step 7 is the pre-merge rule: rebase, push with
lease and re-check when main moved and the PR touches app, tests, crates or
CI; a docs-only PR may merge behind. The remote branch deletes itself on
merge, so clean-up removes the worktree and the local branch. The port goes
in the brief as AURACLE_TEST_PORT.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW

* docs(agents): hooks described as the scripts are, agents on Opus, the reviewer changes nothing in the repo

AGENTS.md's Tooling and .claude/README.md now say exactly what each hook
does: the session-start report (missing or stale pkg, the browser queue),
all five generated paths guard-generated refuses, the post-edit checks by
file type, and guard-bash's two refusals (cargo test without --release,
--profile or --doc on any crate; playwright test outside one_browser.sh).
Every agent definition gains `model: opus` (the maintainer's choice), and
the README says so. The reviewer has one Truth bullet, and its probes live
only in the session's scratchpad with their own Playwright config.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW

* docs(agents): the reviewer has one Truth bullet and keeps its probes out of the repo

It had two Truth bullets; they are one now, ADR-004 and ADR-012 together.
It changes nothing in the repository, and a probe lives only in the
session's scratchpad with its own Playwright config, through the browser
queue on its own port. New voice rows are those voice.md's table governs.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW

* docs(agents): builders draft only the voice rows voice.md's table governs; check_docs reads .claude/README.md

web-engineer, engine-engineer, docs-writer and film-producer, and the
auracle-strategy invariant, say the approval is for a new term, label or
phrase the word table governs, as voice.md § How this is kept has it, not
every sentence. check_docs.py now checks .claude/README.md's links too;
the check skill says actionlint runs if installed; a long line wrapped.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW

* docs(plans): Plan-004's and Plan-007's open items marked for their issues; the live face is done

Plan-004 task 1's two "still to do" items (the landing, brand, 404 and
film pages onto the size scale; the NOT_YET colour files) and Plan-007's
"a clip per input" carry a TODO for the issue the operator opens and
links. Plan-007 task 4's heading said "except the live face", but #104
built it (createLiveMeter, the audio_in spec "the square draws the input's
live face"); the heading now says so.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW

* docs: a branch's AURACLE_TEST_PORT reaches the make browser targets (browser-test skill, tests/web/AGENTS.md)

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW

* docs: Plan-004's and Plan-007's open items link their issues (#145–#148)

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW

* docs: the ship skill's commands work in zsh and across Bash calls; the session hook watches Cargo.lock

From the re-review: `GH="gh -R …"; $GH …` does not split in zsh, so every
gh line in the ship skill failed and its CI wait never ended; each command is
now written whole, and the skill says each Bash call starts a fresh shell.
The catch-up rebase checks main moved (merge-base --is-ancestor) and leases
the pushed head explicitly. session-start.sh's find dropped Cargo.lock (its
-name filter) and the root Cargo.toml; both are watched now, as the README
says. The reviewer's scratchpad probe needs NODE_PATH; the Makefile comment's
port precedence was backwards; reuse is when main did not move; the backlog is
open issues with no milestone; agent branches are what's reviewed before a PR.

Claude-Session: https://claude.ai/code/session_01GMg3KFS9ggSrYdvGkbBshW
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant