← Learnings index

Learnings — docs/learnings/

Per-session "Today I Learned" (TIL) write-ups: the non-obvious, hard-won lessons from working this repo — process friction, tooling gotchas, ISA/parity surprises, and the conventions that emerged to fix them. Each agent writes one at the end of a working session.

These are narrative retrospectives, not authority docs. When a lesson hardens into a rule it migrates into the relevant authority doc (claude_workflow.md, puzzle-velocity.md, the skills) — the TIL is where it's first noticed, not where it's enforced.

Standing follow-up: the lessons here are only mined into tracked work ad-hoc. #207 (marker at the top of this file) is the spike that systematically harvests them into codebase + process improvements. A lesson learned once by one agent shouldn't silently recur for the next.

Naming

Writing guidelines

Jargon rule: When using a project-specific term (workflow jargon, tool names, role codes), define it on first use in the doc or link to the claude_workflow.md Concept glossary. If the term isn't in the glossary yet, add it there first (see #479).

Index

Doc Date Agent Themes
TIL 2026-06-16 — DRAGONFRUIT 2026-06-16 DRAGONFRUIT Correcting a stale doc means verifying the new claim against the code first (#1063 — traced env.js/oracle specs, the golden cache not the binary gates skips); scope the fix narrow and file adjacent inaccuracies as a follow-up rather than folding them in (#1424, RULES 10/12); prefer count-free prose over a hardcoded number that goes stale; create a missing label before applying it (tiny); velocity:log --from-main is the sanctioned path for a worktree-less PM row.
TIL 2026-06-15 — APPLE (session 2) 2026-06-15 APPLE An external audit finding is a hypothesis (3 of 4 P2 notes refuted → became tests/docs); a prescribed fix can break an invisible contract (oracle parity, #1397); the orthogonality trap — tooling that captures a behavior under review is coupled to that review, not orthogonal (#1402/#159); untracked files don't carry into worktrees and collide at close (#1403); read-before-write caught a same-day TIL clobber.
TIL 2026-06-14 — HONEYDEW 2026-06-14 HONEYDEW npm run close may delete the worktree before the final comment lands; every distinct failed retry should get its own error row.
TIL 2026-06-14 — INCABERRY 2026-06-14 INCABERRY Claim warnings can be successful yet still point at stale worktree/claim-ref cleanup debt; git worktree add needs write access to refs and can fail under a read-only sandbox.
TIL 2026-06-14 — INCABERRY (session 2) 2026-06-14 INCABERRY CLI BDD tests can need an in-process driver seam when sandboxed spawnSync returns EPERM; TTY-sensitive extras like clear, cursor, and resetc are easier to prove with in-process TTY guards and spies.
TIL 2026-06-14 CHERRY 2026-06-14 CHERRY Review a ticket against the shipped sibling code it claims parity with; reproduce a worktree test red on current main before debugging it (stale-base #1215); a test's inline issue-reference is a hint not an attribution (#940≠#1215); split a user-facing convention into its own ticket and record the ruling (#1240 content-sniff).
TIL 2026-06-07 JACKFRUIT 2026-06-07 JACKFRUIT Fruit roster sync, CodeMirror per-theme bg compartments, Pages doc curation audit.
oracle-e2e .bst redundancy 2026-05-25 — A redundant .bst golden in the lcc.oracle.e2e suite: the bug, the fix, and general golden-hygiene lessons.
adopting PDD on lccjs 2026-05-26 — Why/how PDD was adopted: the layering architecture, decomposition in practice, resolution lifecycle, and where it deviates from canonical Yegor.
TIL 2026-05-28-001 2026-05-28 — Worktree isolation isn't a judgment call; one-shot spike scaffolding; de-noising docs; verify counts vs headings; asserting edit scripts; murky multi-pass velocity.
TIL 2026-05-28-002 2026-05-28 — pdd's substring scan trips on uppercase TODO; close vs blocked-follow-up; share substrate not presentation; stale-marker debt; retract confident-wrong claims; blocked vs icebox.
TIL 2026-05-28-003 2026-05-28 — "File as puzzles" = GH ticket not @todo (yet); read the tracker before filing; highest-value test = risk × testability; severity follows failure-visibility.
TIL 2026-05-28-004 2026-05-28 — Closes #N decouples GitHub from hand-maintained snapshots; quality pass = verification not discovery; sample the whole set before scoping; never hard-code issue numbers under concurrency; fixed-budget = ticket honesty.
TIL 2026-05-29 APPLE 2026-05-29 APPLE Never chain rebase && push; a repeated manual workaround is a system bug; recover from outages read-only; prove what your commands touch; dogfood coordination conventions; shortest-estimate is a tiebreak.
TIL 2026-05-29 APPLE s2 2026-05-29 APPLE "I followed the protocol" is a hypothesis to test vs artifacts; parallelizing can violate ordering; fleet-wide skips are doc-drift; fix what you predict from; a spike's best output is a negative result; match container to finding.
TIL 2026-05-29 BANANA 2026-05-29 BANANA Oracle runs what it assembles (parity programs must terminate); audit the whole class on one glitch; re-assess "epics" vs current code; delete markers wherever they live; public docs mustn't link private repos; npm run eats flags without --.
TIL 2026-05-29 BANANA s2 2026-05-29 BANANA Auto-claim handed a live agent's identity (#193–#195); close-protocol doc drift (#201); cea is fp-relative lea (#152); Read false-positives .a/.ap as binary; push-gating hook bash/grep gotchas (#205/#188).
TIL 2026-05-29 CHERRY 2026-05-29 CHERRY merge=union fires under rebase too; derive rebased values, don't store them; prefer the project's claim tooling; trust VERSION/CHANGELOG over loaded frontmatter; close a process-changing ticket using the new process.
TIL 2026-05-29 CHERRY s2 2026-05-29 CHERRY Live data is the tiebreaker when docs disagree (and the disagreement is a bug); a scope ticket is done when it spawns grabbable children; a guardrail stop means confirm not circumvent; verify outward effects landed; log live repros of documented bugs.
TIL 2026-05-29 DRAGONFRUIT 2026-05-29 DRAGONFRUIT Triage ranks importance, not what's already taken; precedent ≠ authorization for an external write; closing a ticket has a footprint beyond the tracker; a velocity row belongs to its own unit's ticket; wontfix with a forward path.
TIL 2026-05-30 CHERRY 2026-05-30 CHERRY A tool living on main is silently stale on an un-synced checkout (the #212 fix ran inert → #228 guard); "no files changed" ≠ "no logging"; sharpen an existing complaint, don't duplicate it; a guard needs both its decision and its trigger proven; logging is data, commentary is noise.
TIL 2026-05-30 APPLE 2026-05-30 APPLE A gate that false-fails on the common path trains everyone to bypass it (#224); trace to the mechanism, fix the layer that closes every entry point; capture t0 live (reconstructed start = honesty tax); dogfood the fix on your next action; consolidate onto the existing convergence point, don't spawn a competitor; the worktree default prevents stale-base clobbers.
TIL 2026-05-30 CHERRY s2 2026-05-30 CHERRY Root-caused upstream ≠ fix upstream — fix the layer that closes every entry point (#224 run-pdd symlink); a source scanner scans the code that talks about it (the keyword bit my own fix twice — comment + UC_TODO substring); a green regression test proves nothing until it's failed on the unfixed code; don't shell to grep for a metachar check (system grep may be ugrep) — use quoted case; the crash was shallow, the wrong doc model (.pddignore ∪ .gitignore, not SSOT) was the real find (#248/#249); reconstructed t₀ is an honesty tax.
TIL 2026-05-30 DRAGONFRUIT 2026-05-30 DRAGONFRUIT Don't store availability—derive it (a lock from a live worktree can't orphan, #222); batch label/state reads are cheap, native relationships expensive—never the source of truth; verify a ticket is OPEN before claiming (raced #223→filed #227); the at_todo trap bites CSV data too; cross-repo deliverable / single-repo log; npm run drops flags without -- and a leftover branch blocks a forced re-claim; decide-then-execute via documented architect calls; estimates are data, not commentary.
TIL 2026-05-30 BANANA 2026-05-30 BANANA A coverage ticket that cites a bug usually wants a regression pin, not a repro (the #166 OB sites were all fixed); "hard to test" is itself a finding (#240/#241 off-TTY + stdin-prompt CLI bugs); when the named path is blocked, drop to the pure seam underneath; cleanup must be gated on a confirmed push — a newline is not an && (#242 near-miss); puzzle:status only sees marker-backed work, read git worktree list for the real board.
TIL 2026-05-30 BANANA s2 2026-05-30 BANANA Batching tool calls makes me confabulate results — one command → read the real block → proceed (#227); don't invent an external cause (output "corruption") for a self-inflicted discipline failure; a classifier denial is a feature catching a scope escalation; I re-committed the very lesson I was fixing (claimed a CLOSED issue without checking, #239).
TIL 2026-05-30 BANANA s3 2026-05-30 BANANA Fix the chokepoint, not the line in the stack trace (#259 resetProcessStdin hit via 4 paths); check whether the contract already exists before designing one (nbain→0 was the off-TTY answer); split the crisp fix from the fuzzy decision — ship one (#259), file the other (#272); a test forces adjacent correctness you'd wave off as "optional" (cursor-escape leak); Edit/Write mangle literal control bytes — anchor on ASCII, assert via String.fromCharCode(27); don't clobber another agent's uncommitted work to satisfy a guard (--allow-stale-main); "available" ≠ "ready" — the gate can live in the body, not a label (#268 dep on #266).
TIL 2026-05-30 APPLE s2 2026-05-30 APPLE "Match the oracle" is wrong when the oracle silently corrupts — a louder/earlier failure is BY DESIGN, not a parity bug (#244 no line-length limit, 298-char buffer splits silently); before adding an exclude over a path the tool can run from, check the symmetric self-exclude case — anchor with <rootDir>, prove it with --listTests (#247 jest worktree leak); convert a permanently-skipped test into an active assertion or a deleted placeholder pointing at a findings doc.
TIL 2026-05-30 APPLE s3 2026-05-30 APPLE A bug ticket's premise is a claim — reproduce on current main first (#157 \n worked for ~17mo, demos depend on it); when the headline doesn't reproduce, the adjacent truth is the finding (oracle silently drops unknown-escape backslashes, lccjs errors — BY DESIGN); "split from #X" makes #X the parent, not the claim (mislabeled #150 the misdiagnosis — human caught it); "depends on #N" can be a typo — ground-truth a block by whether the artifact exists + git worktree list (#267 → really #266); a report's "shared root cause" is a probe spec, sweep the family (#257 no-comma spans jmp/blr/jsrr + imm5/imm9); highest-severity ≠ best-next (owner-gated/epic rank high but aren't grabbable); the shared main checkout can hold another agent's uncommitted WIP — worktree on clean origin/main.
TIL 2026-05-30 DRAGONFRUIT s2 2026-05-30 DRAGONFRUIT I confabulated #241 as a fictional "30-byte cap" and wrote a whole doc before reading the issue — the batch-calls-assume-success trap on the write side; a clean-room repro must neutralize the cwd name.nnn cache or it lies; "it already works" (OG has no author flag, only name.nnn, already mirrored) is a valid research answer; surface out-of-scope deltas as tickets (#269/#270) not as a while-I'm-here fix; a label is only useful with a self-explaining --description; gh issue create isn't idempotent — a queued retry double-filed (#273/#274); the stale-main claim guard is right, base the worktree on origin/main.
TIL 2026-05-30 CHERRY s3 2026-05-30 CHERRY Dogfooding close.js (#266) found two bugs the smoke tests missed — the pre-push banner prints on every push so success can't be string-matched (exit code is the authority), and "failed to push some refs" is git's generic any-failure summary, not a race; the at_todo trap bit a TODOS.md mention in a code comment; committing from a worktree path a failed claim never created landed tracked junk under .claude/ on main (now gitignored) — a claim failure means there's no worktree, stop; batched calls → confabulated state (the root of every error this session, re-affirmed deliberate-tool-pacing); a guard that makes the unsafe path impossible (#227/#228/#266 gate) holds even when the layer above it is buggy.
TIL 2026-05-31 BANANA 2026-05-31 BANANA No validated write path = recurring CSV corruption; SQLite eliminates the format-error class that CSV tooling cannot; auto-export on write keeps the generated file always current; DB location outside the repo solves cross-worktree access; run velocity-log from the committing worktree, not main; atomic writes (tmp + rename) are non-negotiable for generated files; walk architectural decisions phase-by-phase with the user, not as one front-loaded approval.
TIL 2026-05-31 APPLE 2026-05-31 APPLE at_todo trap bites shell script echo strings (third surface: code comments, CSV data, now string literals); parallel issue filing breaks cross-links — file siblings sequentially; git worktree .git is a file, use --git-common-dir in hook installers; committed derived artifacts create silent staleness + crash risk; two-tier approach prevents artifact catalogs from becoming file-tree dumps; document why a workaround exists so its retirement condition is clear (merge=union → SQLite).
TIL 2026-05-31 CHERRY 2026-05-31 CHERRY Exit code is the authority, don't parse git prose to decide success; dogfood a tool against its own close before trusting it; a tool failure means the precondition didn't happen — stop; every error traced to batching tool calls (enforcement-asymmetry lesson: guards held, prose didn't — that's the fix); re-verify the board before reporting it, stale worktrees lie.
TIL 2026-05-31 DRAGONFRUIT 2026-05-31 DRAGONFRUIT Pre-flight start timestamp is not optional — proved by skipping it (empty started_iso); the at_todo trap is meta-recursive in velocity notes (a row describing having dropped a marker contained the live form); two omissions, not one — the velocity row and the worktree for the row are independent obligations; puzzle:status + git worktree list are complements not alternatives; stale worktrees outlive closed issues.
TIL 2026-05-31 BANANA s2 2026-05-31 BANANA A dirty package-lock.json alone is safe to force-remove; do the data-integrity audit before the process-mapping research (concrete evidence first); keyword-overlap mismatch heuristic finds gross transpositions but has a high false-positive rate (7/9); only 1 unrecovered mis-close in 233 issues — the system is more robust than feared; file the ARCHITECT follow-up immediately, don't leave guard recs as stranded prose.
TIL 2026-05-31 APPLE s2 2026-05-31 APPLE CSV is read-only generated (never hand-edit conflict markers in it); null-ticket gap fixed (#299); merge=union only fires on merge, not rebase; guards held 8/8, prose rules violated 8/8 — the fix is converting prose to guards.
TIL 2026-05-31 APPLE s3 2026-05-31 APPLE Prose violations happen even mid-documentation — guards are structural, not discipline; .git file vs directory is the clean worktree detector; research deliverables should name the exact implementation site; smoke-test inserts pollute the global DB; N-location prose drifts, N=1+links doesn't.
TIL 2026-05-31 BANANA s3 2026-05-31 BANANA Guard before mutation not after (partial state is cleanup debt); hard failure + named escape hatch beats a warning; Guard 1 "all rows match" too strict for full-file exports — need "match present", not "no mismatch" (#346); CSV auto-resolve rewrites the SHA close.js uses for teardown gating (#350); SQLite made the DB write safe but not the export path; always --as <fruit> on claim; stubs make a skill shippable — document gaps, don't paper over them.
TIL 2026-05-31 DRAGONFRUIT s3 2026-05-31 DRAGONFRUIT OG LCC blank-.e is universal across all error types (not just undefined labels) — two sizes by pass phase; oracle requires cwd+basename invocation (absolute paths give "Bad command line switch" exit 2); velocity commit must reference Closes #N or close.js blocks on HEAD check; regex-from-end extracts simple trailing CSV fields without a full parser; SHA-rewrite issue consistently orphans worktree — cleanup does NOT happen automatically, manual teardown always needed (#350).
TIL 2026-05-31 CHERRY s3 2026-05-31 CHERRY Hit the batching footgun while building its guard — plan-mode one-call-per-step discipline held where the memory rule didn't (primary evidence for #316); my own Guard 1 (#310) blocked my own closes twice, correctly — sync+re-export, never --skip; adversarially verify a load-bearing research claim against the primary source (distrusted 2 sub-agents on PostToolBatch, WebFetched the docs — half-wrong: skepticism right, claim true); the success route is the dangerous one — close.js kills its own cwd (close must be the lone last call) and gates on a SHA its own rebase rewrites (#350, reproduced).
TIL 2026-05-31 ELDERBERRY 2026-05-31 ELDERBERRY Parallel gh issue create jobs assign numbers by arrival not submission — @todo markers get wrong issue numbers; notebook-editing script writes before asserting — re-running inserts duplicates; full marker audit prevents shipping pointers to closed issues; "not significant" ≠ "uninformative" (n=4 Spearman has ~5% power); SHA-rewrite after close is a known #350 failure mode, not a real close failure.
TIL synthesis 2026-06-01 2026-06-01 ELDERBERRY #207 harvest: 4 tier-1 process defects (batching confabulation, at_todo trap, guards-vs-prose meta, SHA-rewrite); 6 proposed follow-on puzzles P-1..P-6; periodicity recommendation (every ≥10 new TILs).
TIL 2026-06-01 FIG 2026-06-01 FIG Case-sensitive --as warning was the bug; GitHub API vs push warning text; assembleFile() early-return for .hex bypasses two-pass assembly; surfacing already-computed data; FIXED vs DOCUMENTED resolution kinds.
TIL 2026-06-01 ELDERBERRY 2026-06-01 ELDERBERRY ARC follow-on + comment is part of the deliverable (caught on #188); sanity-check neighboring entries (all 3 parity §4–6 were stale); "already fixed" is a valid research outcome (#324); SHA-rewrite cosmetic recovery; recurrence is the signal the synthesis reveals.
TIL 2026-06-01 CHERRY 2026-06-01 CHERRY Doc-audit session: verify load-bearing claims against the source, not secondary docs (caught two accurate-docs-about-to-be-broken: OB-001 mov already fixed, LOCKED state real); close.js Guard 1 collides when velocity agent ≠ branch prefix — set CLAUDE_AGENT_NAME to avoid (#361); findings become their own BDD tickets not comments (#361/#364/#369); cwd resets after worktree teardown — cd explicitly in post-close commands.
TIL 2026-06-01 CHERRY s2 2026-06-01 CHERRY The "~45m/DEV decomplect" estimate is a guess not a contract — grep the consumers first (#255 was ~450 refs + a public-API decision → architect #388; #251 was internal-only → a real 45m extraction); "no behavior change" earns a mechanical proof (84-file corpus diff #256, exhaustive 65536-word decode equivalence #251); a refactor's verify-diff is a bug detector — file what it finds, don't fix inline (pre-existing .o crash → #384); learn to see the embedded architectural decision and hand it off (#384/#388); velocity-logger sharp edges (fixed role set, canonical opus-4.8 not claude-opus-4-8, --from-main after the JSON); use the assigned name, not the claim tool's auto fruit (#386).
TIL 2026-06-03 CHERRY 2026-06-03 CHERRY Checking the producer's in-memory state doesn't verify the write path — the harness's writeSync silently corrupted binary output for months, invisible because all tests read assembler.outputBuffer directly instead of reading back through virtualFs (#527).
TIL 2026-06-03 CHERRY s2 2026-06-03 CHERRY A TIL is not done until the rule has an authority path — a lesson in docs/learnings/ is a narrative note; it only becomes enforceable when it lands in RULES.md or a ticket is filed to put it there (#548).
TIL 2026-06-03 CHERRY s3 2026-06-03 CHERRY npm run close requires "Closes #N" in HEAD — committing the velocity CSV after the closing commit breaks it; log velocity and stage the CSV before the final close commit (#571). bp is a synchronization point, not a poll — it has no coherent off-TTY idle contract and needs a fail-fast guard (#272/#561).
TIL 2026-06-03 CHERRY s4 2026-06-03 CHERRY allowedTools: ["Bash(gh issue comment *)"] in project .claude/settings.json pre-approves closing comments without per-call prompts (#623); velocity commit must be HEAD and contain "Closes #N" — split commits need git reset --soft HEAD~1 (#610); --skip-keyword-check is the correct bypass when research commit subjects use paraphrased language (#623/#634); filing a tracker + N children is one PM velocity row (null ticket); post cross-issue evidence on the target issue before closing, not after.
TIL 2026-06-04 APPLE 2026-06-04 APPLE The LCC.js Interpreter options.write callback already routes all output traps to any consumer — browser stdout requires zero interpreter changes; browser stdin has three tiers (no-input / pre-supplied data-stdin / interactive pauseOnInput) with only the third unimplemented (#702); issue-title ROLE: and commit type: answer different questions and are never interchangeable — fix:/bug: in issue titles is the most common non-standard pattern (#672/#683).
TIL 2026-06-04 CHERRY 2026-06-04 CHERRY Check the module before assuming a gap — --json already shipped in puzzle-status.js; doc review is a verification pass not a reading pass; issue citations in docs go stale silently — prefer tracker refs over implementation issue refs.
TIL 2026-06-04 GRAPE 2026-06-04 GRAPE Check git log before filing tracker child issues; webpack UMD + CJS export:default gives undefined; build-site.js generates the playground — edit the generator, not the output; two step caps can silently coexist; parallel-agent rebase conflicts in options objects usually mean keep both sides.
TIL 2026-06-04 CHERRY s2 2026-06-04 CHERRY .e oC-preamble/LE-encoding makes .e bytes ≠ .hex word values (#747/#756/#758); assembler silently drops instructions after the first on a shared line (#712/#759); spawnSync not inputBuffer for C/lccjs stdout parity (#712/#760); test.failing over test.skip for confirmed bugs (#712/#761).
TIL 2026-06-04 GRAPE s2 2026-06-04 GRAPE Read full issue body before claiming — prose blockers are invisible to puzzle:status; PostToolBatch hook flags batched Bash calls even when read-only; untracked build artifacts on main don't carry into worktrees.
TIL 2026-06-01 APPLE 2026-06-01 APPLE permissions.deny blocks direct Bash strings only — not subprocess commands; EOF vs empty-line are semantically distinct (fix: isEOF: true state, #452); test validation guards with spawnSync not live DB inserts; SELECT before DELETE — approval scope is action-specific (RULES.md Rule 7).
TIL 2026-06-01 BANANA 2026-06-01 BANANA setsid "$@" & drops stdin in non-interactive bash — gate on [ -t 0 ]; stale example in schema doc is more dangerous than no example (velocity-schema.md → #459); research findings need a follow-on DEV ticket before closing (#459); velocity-seed.js had silent positional off-by-one under column addition (fixed in #438).
TIL 2026-06-01 DRAGONFRUIT 2026-06-01 DRAGONFRUIT exec replaces the process — fork+wait for cleanup after child exits; a shell wrapper can't fix its parent's CWD (#360); three mandatory close steps cluster-fail together (velocity row, marker, closing comment); Number.isFinite(Infinity) is false.
TIL 2026-06-02 APPLE 2026-06-02 APPLE Shiki accepts VS Code tokenColors format directly (no conversion); CSS custom properties cascade theme-wide font changes cleanly; close sequence splits when ticket includes a build step — run build before closing commit, add artifact to same commit (#492).
TIL 2026-06-02 BANANA 2026-06-02 BANANA git ls-files beats find for project-internal enumeration; word-boundary mismatch is all the safety you need — check competing rule before adding lookahead.
TIL 2026-06-02 CHERRY 2026-06-02 CHERRY Closing comment is not a backlog — deferred work in prose is invisible to agents and puzzle:status; before the closing commit, convert every "out of scope" sentence to a ticket (Rule 10, #490).
TIL 2026-06-02 DRAGONFRUIT 2026-06-02 DRAGONFRUIT OP_EXT executor (ir & 0x1F, 5 bits) and disassembler (hex & 0x000F, 4 bits) decode the same field at different widths — instructions at eopcode ≥16 execute correctly and disassemble wrong (#496).
TIL 2026-06-03 APPLE 2026-06-03 APPLE A confirmed bug with no fix ticket is unfinished work — RESEARCH close checklist: file the DEV ticket first; pick the gate that blocks exactly what you mean (isNumLiteral vs isValidLabel for br/bl); npm run close checks HEAD specifically — carry Closes #N forward across all commits.
TIL 2026-06-03 BANANA 2026-06-03 BANANA assembler.error() has two output channels (console.error full context vs thrown short message) — verbose flag must live on the Assembler instance; "if large enough" is a trap qualifier on tracker tickets — always file a child issue unconditionally (RULES.md Rule 12, #559); deferred teardown stderr now visible (#551).
TIL 2026-06-03 DRAGONFRUIT 2026-06-03 DRAGONFRUIT assembleBR silently accepts numeric operands — evaluateOperand tries parseNumber first; assembleBL has isValidLabel guard but assembleBR doesn't — grep isValidLabel calls to find coverage boundary (#524).
TIL 2026-06-03 ELDERBERRY 2026-06-03 ELDERBERRY A subprocess cannot fix its parent's CWD — defer worktree deletion to a detached subprocess that runs after npm exits (#541); exec approach failed because npm itself was the getwd() source.
TIL 2026-06-03 FIG 2026-06-03 FIG Never put real email addresses in public GitHub issue comments — use placeholders; moving teardown out-of-band hides its failures — ask "how will I know if it failed?" before deferring (#542).
TIL 2026-06-03 GRAPE 2026-06-03 GRAPE Velocity notebooks need a SQL date ceiling to be idempotent on re-execution (#664); hst_day is a derived in-memory column — filter on raw finished_iso in SQL; agent casing in DB is load-bearing (never normalized, #669).
TIL 2026-06-04 BANANA 2026-06-04 BANANA Golden-cache pattern: commit oracle output once, run tests anywhere — oracle suite 18 skips → 124/124 pass (#692); build generators must own all features — never hand-edit generated output; bundle paths: repo root ≠ GitHub Pages root, add explicit copy step (#709/#710).
TIL 2026-06-04 DRAGONFRUIT 2026-06-04 DRAGONFRUIT "Already done" is a valid close — verify before implementing (#675); back up PC by 1 before throwing pause signal for resumable synchronous execution (#702); use a signal class, not an Error, for non-error control flow; build path and runtime path can silently diverge — open the browser before closing (#705/#709/#710).
TIL synthesis 2026-06-04 2026-06-04 BANANA #764 harvest: 3 tier-1 process defects (RESEARCH→fix-ticket chain, close-sequence edges, verify-before-implementing); 4 proposed follow-on puzzles N-1..N-4; 61 new files scanned (30 in depth).
TIL 2026-06-04 BANANA session 2 2026-06-04 BANANA Verify file-level conflicts before deferring; write "not feasible" findings into durable docs; oracle auto-skip ≠ real green in Jest; Playwright specs error (not skip) when picked up by Jest; SVG favicon needs one file + one tag.
TIL 2026-06-04 GRAPE s3 2026-06-04 GRAPE No-op closes use --skip-keyword-check/--skip-velocity-check correctly; tracker audit gate includes human-required children; agent-scoped memory is invisible to other agents; /fruit-agent-orchestrate cluster separation prevents merge conflicts.
TIL 2026-06-04 CHERRY s3 2026-06-04 CHERRY Regex backslashes in JS template literals must be doubled; esm.sh codemirror@6 doesn't expose barrel re-exports as named exports (#772); CM6 dom.cmView hook for Playwright test interaction; page.on('pageerror') vs console events for CDN SyntaxError detection; run new tests against broken state to calibrate.
TIL 2026-06-05 FIG 2026-06-05 FIG Parallel-agent write-safety rules by repo path cluster: skills/ subdirs always safe; src/utils/ single-owner; scripts/ serialise within a file; velocity CSV and learnings README require rebase-before-push.
TIL 2026-06-05 ELDERBERRY 2026-06-05 ELDERBERRY PostToolBatch hook fires on any ≥2 batched Bash calls (including read-only gh issue view); re-issue serially — hook does not distinguish reads from writes.
TIL 2026-06-05 FIG session 2 2026-06-05 FIG Guided-human-decision pattern: context brief → options table → recommendation → ruling → execute; claim.js vs orchestrator label-set asymmetry is load-bearing; land trivially-resolvable side-deps now not later; new label creation requires an immediate candidate sweep.
TIL 2026-06-05 CHERRY 2026-06-05 CHERRY Oracle edge-case verification before assuming errors; grammar/assembler/formatter char-class drift only surfaces with cross-module tests; TDD utility extraction clarifies interface; oracle error cases get their own test shape (no golden, just throws).
TIL 2026-06-05 APPLE 2026-06-05 APPLE slice(0) is a no-op — conditional slice needed for buffer fix; inline assembly test strings need indentation; GitHub issue body text carries ratification state that labels miss.
TIL 2026-06-05 DRAGONFRUIT 2026-06-05 DRAGONFRUIT Ticket-dependency sequencing protocol: spike to define sequencing rules, then file child tickets with explicit blockers.
TIL 2026-06-05 DRAGONFRUIT session 2 2026-06-05 DRAGONFRUIT din/ain newline parity (lccjs consumes \n, OG LCC doesn't); state current behavior before options; deferred decisions need a summary doc + two tickets; don't route closed-ticket housekeeping through owner decisions; tracker advance earns its own velocity row.
TIL 2026-06-05 CHERRY s3 2026-06-05 CHERRY Document the negative fact for closed sets or it gets re-invented; DDD refactors shift test ownership — tests must track the invariant not its location; error logging should be manual not hook-triggered.
TIL 2026-06-05 DRAGONFRUIT session 3 2026-06-05 DRAGONFRUIT Observable Plot is standalone (no notebook runtime needed); const temporal dead zone in catch paths; npm run close is push-only — commit first; velocity CSV conflicts are always append-only and mechanically resolvable.
TIL 2026-06-05 GRAPE 2026-06-05 GRAPE Cross-CLI single-letter flag namespace; tracker items may be partially done — read before filing child; errors write-path is agent not hook; worktrees need npm install before tests are meaningful.
TIL 2026-06-05 APPLE session 2 2026-06-05 APPLE Tracker body checkboxes are frozen snapshots — always verify child states via gh issue view; grep -c exits 1 on zero matches breaking && chains; skipped worktree claims lead to unverified published output; stale-read is a distinct failure mode from batching confabulation.
TIL 2026-06-05 FIG s3 2026-06-05 FIG Incomplete command examples cause recurring errors; npm run close only pushes; external LCC+ encoders need a trapVec shorthand; extension dispatch before the switch.
TIL 2026-06-05 ELDERBERRY session 2 2026-06-05 ELDERBERRY Tracker closes from main use gh not npm run close; four-file LCC+ pseudo-instruction pattern; assembler-level mnemonic aliases share one TRAP vector; stale ISA doc trap vectors; velocity-export skeleton reuse for errors table.
TIL 2026-06-05 BANANA 2026-06-05 BANANA Read tool misidentifies .a files as binary; worktree remove must run from main; cluster test failures before filing tickets; devDependency ≠ installed package; human-gate is the throughput bottleneck.
TIL 2026-06-06 FIG 2026-06-06 FIG Naming absent concepts backfires as confabulation; claim requires --as flag; gh comment multi-line quoting; error:log schema (occurred_iso + fixed enum); log errors immediately at occurrence.
TIL 2026-06-06 DRAGONFRUIT 2026-06-06 DRAGONFRUIT Own-fix verifies prior fix in production; orphan directory (no .git) still fools jest — and agent confabulated its history; until-grep is wrong for background tasks; auto-mode Self-Modification block is per-task not per-path; tracker checkboxes are frozen snapshots; pre-stated triage criteria collapse judgment into lookup.
TIL 2026-06-06 CHERRY 2026-06-06 CHERRY Shared DB path resolver + migration shim; CRLF strip for CSV seeds; TEST-agent rows are artifacts, not data; replace stale tests with protocol-documenting replacements; subprocess test helpers need the worktree-guard bypass flag.
TIL 2026-06-06 GRAPE 2026-06-06 GRAPE Worktree branch scripts can point to stale DB path; Playwright MCP resolves human-required SPA audits; source code reading ≠ runtime verification; package.json listing ≠ package installed.
TIL 2026-06-06 ELDERBERRY 2026-06-06 ELDERBERRY "No rows" can mean wrong DB — query canonical lccjs.db (db-path.js), not orphaned velocity.db; propagate a fact-correction across every memory file via grep; file the missing slice (compliance guard #990) adjacent to an existing ticket (#984), not a duplicate; re-verify a flag is still live on main before commenting.
TIL 2026-06-06 CHERRY (session 2) 2026-06-06 CHERRY Match a helper's contract to the question — write findSameIssueCollision (excludes self) instead of reusing a first-match finder (#1017); a warn-not-die guard must be pure and offline-silent (#1013); reproduce a contended git race in a local bare repo before trusting "atomic" — same-base-sha pushes are no-ops, not rejects (#1018); after npm run close the shell re-roots to main, recover an accidental main edit with stash→claim→pop (#1035).
TIL 2026-06-06 ELDERBERRY (session 2) 2026-06-06 ELDERBERRY Multi-issue batch close targets the branch's issue, not the last-committed one (#1052); Guard 1 needs --skip-ticket-match in a batch close; resolve puzzle-velocity.csv conflicts by re-exporting from the DB, never hand-merging; a scope-audit "deletion" of a file you didn't touch is a pre-rebase diff artifact — verify on origin/main; getcwd error after teardown is cosmetic.
TIL 2026-06-06 BANANA 2026-06-06 BANANA close-before-push ordering; VELOCITY_DB env override for pre-rename worktrees; git worktree prune for dangling refs; retroactive error logging; verify issue numbers before posting (#993).
TIL 2026-06-06 BANANA (session 2) 2026-06-06 BANANA A tool error is a checkpoint — verify state before retrying, never cite an uncreated #N (#996); read a sibling's deferred deliverable instead of re-running the audit (#998←#1007); collision-avoidance is by file not by label — sub-divide a giant area cluster by file-touch when agents outnumber clusters; anchor out-of-repo edits (skills, memory) to the velocity-CSV close (#978/#970); route user-only behavioral decisions via AskUserQuestion (#1009→#1049).
TIL 2026-06-06 CHERRY (session 3) 2026-06-06 CHERRY A "generated" directory can hide a source-of-truth file with no build step — run a clean build and check what git status does NOT reproduce before gitignoring it (lang-lcc.js, #1075); a node_modules symlink dirties a worktree because the node_modules/ gitignore pattern doesn't match a symlink, blocking npm run close — unlink it first (#1111); a ticket framing a global A/B choice may hide a per-item answer — trace each artifact's real consumers (#1075).
TIL 2026-06-07 INCABERRY 2026-06-07 INCABERRY Patch tool edits main checkout not worktree — verify resolved path; inline script must use .indexOf() not .has() on serialized arrays; document.documentElement and document.body theme classes must stay in sync; docs pages need JS script even without dropdown; velocity log must include model field.
TIL 2026-06-07 CHERRY 2026-06-07 CHERRY A courier kicks a refuted design back to the architect (#1086→#1129); don't snapshot a buffer two consumers share; gh issue list --state all before filing (#1146-48 dup of #1137-39); ask "did you ask for THIS action?" before acting + never fabricate attribution (#1123, #1160).
TIL 2026-06-07 ELDERBERRY 2026-06-07 ELDERBERRY Put a verification step where the information lives (close.js can't see the transcript → agent runs the error self-audit, #1117/R021); Edit writes to main checkout after claim — route through the worktree path; dogfood a new discipline in the session that created it (caught rows 60/64); gh issue list --state all + map a request onto the existing seam before filing (#1132/#1144/#1151).
TIL 2026-06-07 DRAGONFRUIT 2026-06-07 DRAGONFRUIT A compliance-guard false positive gets a documented KNOWN_BYPASSERS exception, not contorted code (#1127/#1104); velocity:log deltas are estimate − actual, must be ≥ 0; npm run close exits 1 with a benign post-teardown getcwd error after CLOSE OK; dual-close a duplicate by stacking Closes #N footers; for a dirty shared main, claim --allow-stale-main then rebase the worktree onto origin/main rather than clobbering foreign work.
TIL 2026-06-07 GRAPE 2026-06-07 GRAPE Multi-pass review trackers want one tracker-numbered findings folder + README index (other agents drop into it for free, #1105); verify an issue is OPEN before claiming — assignments/briefings go stale in hours (caught an already-closed #1061 → #1159); the close scope-audit's phantom deletions are a stale-base artifact, verify the real pushed commit not the audit (#1145); grep MEMORY.md before writing a memory — update the canonical entry, don't duplicate.
TIL 2026-06-07 FIG 2026-06-07 FIG In a worktree, point file writes at the worktree path — Write/Edit to a main-checkout absolute path strands the file on main (#1130/#1169, same trap hit INCABERRY/ELDERBERRY); file forward-linked ticket chains in reverse so each link resolves (#1157→#1156→#1155); read a ticket's comments + linked issues before redoing already-complete work (#1120); verify an edit against a known-good baseline — a tool showing a deviation is the bug, not a "display artifact" (#1130).
TIL 2026-06-07 BANANA 2026-06-07 BANANA The #986 Lezer tag-identity trap recurs for any new HighlightStyle — import tags from the parser's exact pinned CDN URL or get silent zero-highlight (#1124); two highlighters rendering one thing must share a source and use a CM Compartment to be theme-reactive (#1124); delegate browser verification to a subagent when MCP browser tools aren't in your session — never substitute source reading (#985-987/#1124); gh issue list --state all before filing (filed #1128, a dup of #1104); recover a stranded foreign commit by rebasing onto origin/main, never force-push — patch-id detection self-corrects under concurrency (#1162).
TIL 2026-06-07 APPLE 2026-06-07 APPLE Run a CLI and read its real stdout before trusting a spec's normalization — lcc prints a banner before program output, so the runner isolates output after the ===… Output separator (#1091); a spawnSync that blocks for exactly the timeout despite instant completion is an orphaned grandchild holding the pipe, not the program (lccrun watchdog sleep, #1149, verified 10005ms→85ms); push verdict logic into a pure function so an unreproducible failure (the 124 timeout — infinite loops self-terminate via max-steps) is unit-testable with a synthetic result; never git pull --rebase a shared main holding another agent's WIP — use claim --allow-stale-main and rebase the worktree instead.
TIL 2026-06-07 APPLE (2) 2026-06-07 APPLE Run the pre-close error self-audit BEFORE closing, not after a human asks — state the outcome in the closing comment (R021/#1117, caught after #1125); dog-food a fix on its next real invocation — #1145's scope-audit fix verified itself on its own close and cleaned up #1151's; the Read tool (not Bash sed/grep) satisfies the Edit precondition (EDIT_PRECOND ×2, #75/#76); implement to the canonical source, not a ticket's paraphrase that contradicts convention (#1125 "skip no-repo-file" vs #215/#216); to live-test a new guard, strip the guards in front of it (#1151 lane gate behind the #227 CLOSED guard).
TIL 2026-06-07 ELDERBERRY (2) 2026-06-07 ELDERBERRY Verify the load-bearing premise before ratifying a prior recommendation — one grep flipped #845 from Option C to B when "the harness can't load JSON" proved false for RULES.md too (#1192); a content-SHA is a great version but a terrible identity (cite a stable stem, let the SHA drive an auto-incremented -NNN, #1185); a decision ticket can be ratifying already-shipped state — read what closed since it was filed (#1061 had pre-decided #845); validation guards are loggable even when self-corrected (VALIDATION_FAIL id=77); close a no-deliverable decision ticket with gh issue close + a --from-main velocity row, not npm run close.
TIL 2026-06-07 BANANA (2) 2026-06-07 BANANA A spawnSync that blocks for exactly the timeout on instant completion is an orphaned watchdog sleep holding the captured pipe open — you wait on EOF, not on the kill; redirect the watchdog's stdio (#1149); gate closed vocabularies but only notice open-growth ones (model/agent names) — a check that reds the build whenever a legitimately-new value appears is the wrong check (#1184); before resurrecting a commit the rebase dropped as empty, diff it vs origin/main — the shared global velocity DB means another agent's export may already carry your row; a fail-fast test probe must trip on a check that runs after the behaviour you're asserting (ticket is validated before model in velocity-log).
TIL 2026-06-13 BANANA 2026-06-13 BANANA An open design question is the reporter's to rule in writing before coding — never blend architect and courier mode (#1092); verify repo + sibling state over ticket prose, a closed sibling's NOT_PLANNED reason changes the design (#1095/#1103); leave a filed follow-up a typed-error default: seam that names its ticket, not a rewrite (#1114); log forward-looking info on the OPEN consumer ticket, never the closed parent (#1093/#1094); a red you didn't cause still gets a gh issue list --state all search before you report or re-file it (#1214/#1215).
TIL 2026-06-14 ELDERBERRY 2026-06-14 ELDERBERRY A ticket can be OPEN yet wrong — grooming/PM tickets drift mid-execution as the tickets they reference close; re-resolve referenced states right before finalizing, claim-time freshness (#1159) doesn't cover it (filed #1243, drifted 3× in one session); consult yegor-microtasks+pdd before revise-vs-close — don't pre-split a sub-cap task, PDD-puzzle the blocked half during work (#1233/#1102); search --state all then augment the canonical ticket + carve only the novel facet as a child, never a dup (#1134/#1243); redline don't rewrite, even on tickets you're closing — the preserved error is evidence (#1231/#1102).
TIL 2026-06-14 GRAPE 2026-06-14 GRAPE A ticket's blocker banner is a claim not a fact — re-grep / re-check #N right before finalizing (#1100 had closed under #1102; meta-bug #1243); --explain has two render gates, the assembler's instance explainModeOn and the module-level setExplainMode in cliExit — forward both into a driver or the runtime half stays silently unexplained (#1102); "shadowed by a plus override" is literal — InterpreterPlus.handleRuntimeError rebuilt the error funnel and dropped error.explainKey (#1102); a no-worktree PM/review row logs via velocity:log -- --from-main (#1266); file the follow-up issue before writing the @todo and point at it, never the ticket you're closing (#1273).
TIL 2026-06-14 FIG 2026-06-14 FIG An issue-review READY verdict certifies clarity, not that the prescribed fix is correct — re-verify on contact with code (#1238/#1265); probe the fix mechanism, not just the bug — #1238's prescribed "add to reset" would've silently broken CLI -l because reset runs inside assembleSource after the CLI sets the field (#1285); classify a field as caller-input (survives reset, threaded per-call) vs derived state (cleared) before resetting it; surface a seam-level design fork to the human with evidence instead of folding the decision into a commit; when you fix one instance of a pattern, scan for siblings and file them — same diff fixes one, a new ticket tracks the rest (#1277).
TIL 2026-06-14 FIG (2) 2026-06-14 FIG Swapping this.error() (sets a flag, returns) for this.raiseRuntimeError() (throws) is never a local edit — the caller is in the blast radius and needs a try/catch; the #1273 review caught the bare :165 caller a six-site conversion would have left uncaught (gotchas §8); before writing a TIL, grep docs/learnings/ for today's date + the parent ticket — same-day siblings working a shared parent (#1102) had already filed 4 of my 5 candidate lessons, so write only the new one and cross-link the rest.
TIL 2026-06-14 BANANA 2026-06-14 BANANA A worktree resolves node_modules from main via parent-walk, so npm install --ignore-scripts there silently leaves better-sqlite3 unbuilt — 16 red tests that look like a regression but aren't (#1252/#1256); probe the real CLI (exit code + streams) before asserting or filing a bug — caught the undefined-external link's intentional exit-0 parity (#1258) and the interactive debugger driving fine via spawnSync (#1259); unit-green ≠ user-reachable — --explain passed unit tests yet never rendered via the CLI (#1245/#1247); a ~30-min-or-split time-box turns open-ended conversion into a self-limiting, self-perpetuating tracker loop (#1269 → 9 children); split maintainer forks into decision tickets, keep implementation a courier job (#1215/#1245/#1250).
TIL 2026-06-15 APPLE 2026-06-15 APPLE "Red on main after [old PR]" is a hypothesis — git log -L the failing lines to the introducing commit, which can be a same-day test:-typed refactor 16 min old (#1328/bc91977); "take the ticket" ≠ implement its literal body — reconcile the body + code marker against the linked contract/child tickets first, a stale @todo pointed at deferred breaking work (#255/#388/#873); closing a pdd-tracked issue means grepping @todo #N across src/ AND docs/ and neutralizing every hit, not just the code site (#255); the ≤60m cap is a reason to close-and-rescope, not just split — over-cap ticket = a complaint (#255 → #1352, children #872/#873 closed); a guard-block that forces a retry/override (claim race, close.js keyword check, velocity --from-main) still earns an R021 errors row even when working-as-designed.
TIL 2026-06-15 BANANA 2026-06-15 BANANA CM6 paints selection in .cm-selectionLayer at z-index −2, behind .cm-content (z 0) — any opaque background on .cm-content or .cm-activeLine masks it, so put editor bg on .cm-scroller (#1339); a palette-derived opaque active-line color masks a partial selection on the cursor's line, so suppress the active-line highlight while a selection is non-empty, VS-Code-style, via an updateListener-toggled class (#1347→#1355); I shipped that regression because I verified the scriptable path (Ctrl+A) not the common one (mid-line word select) — verify the real human gesture (#1360, err row 269); backticks/${} inside the build-site.js browser-script template literal break the build even in comments (#1355, err row 270); themes already carry their own editor.selectionBackground/lineHighlightBackground in Shiki'''s .colors map — derive chrome from those (#1347).
TIL 2026-06-15 FIG 2026-06-15 FIG A backgrounded npm run close reports task status=failed (exit 1) on the known-benign getcwd-after-teardown quirk (#360/#434/#533) — read the output for CLOSE OK, don't trust the status; velocity:log -- --from-main is the intended path (not just an override) once your own worktree is torn down but sibling worktrees still trip the any-worktree guard (#320), with a timing nuance vs APPLE's R021 framing; on a READY 15/15 ticket, fold non-blocking review suggestions into the implementation and log them in the close comment instead of round-tripping the issue — reserve revisions for gaps that block starting (#1340 agent-patterns.md).
TIL 2026-06-15 — BANANA (session 2) 2026-06-15 BANANA Made the Pages site fully theme-aware across four tickets: a baked <body> theme class shadows the pre-paint <html> class when the vars live on both html.X/body.X, so set the class on one element only (#1334); theme a surface via a CSS var (--surface-bg/--surface-fg), not an inline property, so higher-specificity state rules like .lcc-error still win (#1333); unify two competing theme controls into one dropdown and post the design ruling before coding (#1379, pair-work); reuse the landing page's existing .theme-panel switch so per-theme docs code blocks need zero new JS (#1388, pair-work); backticks/${} in a build-site.js template-literal comment break the build even inside comments (#1409); replace_all only matches the exact string incl. whitespace; browser-verify with computed-style probes against the built page.
TIL 2026-06-16 APPLE 2026-06-16 APPLE A skill producing a good result ≠ the skill containing the logic — grep the skill for the mechanism before crediting it (runtime routing was my own improvisation, #1420); a ticket that only produces a signal (the runtime:hermes label, #1271) isn't done until something consumes it (#1420); "no YAML" has a platform-mandated exception (GitHub Actions workflows) — honor the intent by keeping the workflow a thin shim and the logic in a pure, testable Node helper (#1246); a scoped permissions: block defaults every unlisted scope to none, so adding a step means re-deriving its token scopes (contents: read for checkout, #1246); when acceptance criteria conflict on an edge case, implement the safer reading but surface the fork to the reporter rather than coin-flipping it silently (tie→uncategorized, #1246); run the cheap count a filing request assumes before writing the ticket — "20+ uncategorized" was actually 1 (#1296), so it became a labeled-corpus backtest (#1427).
TIL 2026-06-16 CHERRY 2026-06-16 CHERRY Verify the premise a ticket asserts before editing — #1316's "frontmatter contradicts body" was a claim to grep-check, not a fact (generalizes the #1192 do-this-not-that entry); a skill has two VC homes (~/.claude→claude-config Claude port vs in-repo .agents/skills Codex port), so realpath AND git ls-files before assuming one copy — fixing one port left the other stale (#1316→#1425); the auto-mode classifier denies an external write authorized only by ticket content, not the user's live words (err #325) — surface in prose and let the user restate; two-ticket "one coherent edit" closes need one velocity row per ticket + both Closes #N in one commit (close.js guard passes if any added row matches), with out-of-repo deliverables named by external sha in the close comment; batching two state-changing gh comment calls trips the PostToolBatch pacing hook (err #326).
TIL 2026-06-16 FIG 2026-06-16 FIG Verify a ticket's stated premise against the repo before writing — three tickets this session asserted a "current state" the code contradicted (nameHandler moved to lcc.js not gone, #1374/#1395; lccjs ships 8 .agents/skills/ skills, not "all user-global", #1219→redlined #1210); for a scope audit use the merge-base (three-dot) git diff origin/main...HEAD, never tip-to-tip two-dot — a diverged origin/main folds siblings' commits into your audit as reversed hunks (#1432); batch tickets into one worktree iff they share a file, then close the branch-issue and let siblings auto-close via Closes #N, passing --skip-ticket-match when HEAD's velocity row is a sibling (#1218/#1219, #844).
TIL 2026-06-16 ELDERBERRY 2026-06-16 ELDERBERRY Grill-with-docs catches design forks before they become rework (#1418); separate architect from courier — spike→decompose fuzzy work and defer entangled entries to avoid double-touch (#1417); a rot-detector must be green-by-default AND ship a teeth-test proving it can fail (#1362); in cross-linked docs a heading rename is a link-breaking event — fix inbound links in the same commit and keep transitional (formerly X) aliases out of the header so GitHub anchors stay stable (#1418/#1435); recurring traps — EDIT_PRECOND is per-worktree-path (err #327), claim needs an area:* label (err #328).
TIL 2026-06-24 APPLE 2026-06-24 APPLE Verify a "drop-in replacement" against PRODUCTION state, not fresh fixtures — the pmtools migration passed readiness on clean DBs/fixtures but 3 of 4 switches broke on live state (legacy dup rows blocking uq_velocity_session #1457; .pddignore-ignored docs flooding status 94→1 #1458; worktree-basename scratch dir); the at_todo PDD trap bites tool authors and the pre-push hook blocks a malformed tree's own claim-ref delete, so release's abandon-path ref-delete needs --no-verify+2>&1 (#1437); split a half-blocked ticket so the ready half ships (#1454→#1459); build destructive tooling guard-first so a refusal touches nothing, and validate a config switch by dogfooding it on the next task (#1455/#1437).
TIL 2026-06-24 BANANA 2026-06-24 BANANA A tool's own git-mutating integration suite leaked 9 fixture commits into my worktree — don't run it from a live worktree, and read git log before pushing; excise a contiguous junk run with git rebase --onto <base> <top-of-junk> (pmtools#20). Route around an off-deliverable blocker in someone else's lane (file it + verify in a disposable clone) instead of stop-the-line — and when you cite a methodology, check you're applying that one, not a same-sounding import (yegor-pm vs Lean). When a delimiter shifts, audit what each parser is anchored on around the surviving token, not just that the token survives — TDD caught /issue- vs [-/]issue- before it shipped (pmtools#17 → #1461).
TIL 2026-06-26 APPLE 2026-06-26 APPLE Verify live ticket/file/coverage state in-turn — never assert from memory (confabulated #31 parent-tracker coverage → overclaim + premature close; called pmtools#53/#45 "open" when both were CLOSED). Conflict resolution is integration, not keep-both — drop a side a concurrent refactor orphaned (status MARKER_RE), weave two intents (#37 anchored guard + br-/wt- widen, which also fixed pmtools#50), re-rebase when main moves under you (pmtools#17). Gate each tool-migration flip with a live new-vs-incumbent differential across every behavior class, then dogfood by closing the switch-ticket through the new tool (#1466/#1453/#1467 — all six lccjs PM commands now on pmtools). Only the reporter closes a contract/verification ticket, and only on full verified coverage (pmtools#31). Fix recurring derived-artifact friction at the source instead of re-reverting (gitignore the CSV mirrors, pmtools#68 / lccjs#1484).

Recurring threads (informal — #207 will formalize)

A few lessons already recur across multiple agents/sessions — exactly the signal #207 is meant to catch: