1565 Commits

This Branch

This Branch

All Branches

Author	SHA1	Message	Date
bvandeusenandClaude Opus 5	e2197ac799	fix(tests): assert the withdrawn flag on its row, not on a count the skew margin inflates (#4208) ... Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-22 08:09:52 -04:00
bvandeusenandClaude Opus 5	19438cc894	fix(shapes): the capped meaning pass reads new shapes first, and its miss withdraws an early flag (#4208) ... Measured on the first live refresh after 91cde6c deployed: the version bump queued 1,533 rows for the semantic arm, the cap read 150 of them in row order, and all six shapes new since the previous refresh - the only rows flag_divergence acts on, and the highest ids - were flagged before the arm reached them. The gate silenced nothing because it never got to look, and since a flag persists until judged, a later conclusive miss could not take it back. - propose_for_repo sorts the semantic todo by _semantic_priority: unclassified before scoped, newest first. - flag_divergence withdraws a standing flag when the row now carries a conclusive miss; that evidence alone withdraws one. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-22 08:05:49 -04:00
bvandeusenandClaude Opus 5	cef91f4cd4	feat(write-path): a UI write is told which design system binds it (#4256) ... A design system binds like a rule but reached a session only through the session-start block: complete for a session that asks, silent for one writing a component. The write-path hint now carries a design arm. A trigger, not a search: a project has one design system, so the question is answered by the file being UI (.vue, .css, .tsx, ...) in a project that has one. No vectors, no score, no slot from the ranked menu. An index, not the prose: resolved guidance runs to ~8,000 chars (the house style alone), near the hook's whole additionalContext cap. The line names each inherited layer's section headings and inlines a layer short enough to be a line - in practice the leaf's departure. The other arms do not move. A design-only write returns on its own rather than joining the prior-art guard, so the standing-rule arm still runs only where it ran before. Once per session per system, on the hook's existing token-keyed channel (exclude_derive, design:<id>) - no plugin change. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 23:02:44 -04:00
bvandeusenandClaude Opus 5	ad4bd101db	fix(tests): the stale-premise guard keys on the retired conclusion, not the quoted premise (#4134) ... Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 22:44:01 -04:00
bvandeusenandClaude Opus 5	108b12eeb0	fix(dedup): a rule or preference create surfaces what it overlaps by meaning (#4134) ... find_duplicate_rule was title-only, on the stated premise that rules are not a semantic-retrieval surface - false since rules were embedded. A preference restating a rule under another title passed untouched, and since both kinds share one ranking, the weaker label could arrive alone. find_overlapping_rules queries semantic_search_rules with the rule_document shape, both kinds, in the scope the new record ranks in (global: every rule the caller owns; project: global + that project). All three MCP create doors call it before creating and return overlaps + overlap_note on the reply. It advises rather than blocks, on measurement: across 16 sampled records the nearest DISTINCT neighbour reached 0.853, while a true rewording scored 0.850. No threshold separates the bands, so the floor (0.80) sits below the restatement and the author judges. The stale docstring is corrected. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 22:39:02 -04:00
bvandeusenandClaude Opus 5	22bb6d7a1a	fix(tests): move #4196's usage guards to the seam they now describe (#4230) ... CI 7223 went red on seven tests in test_lesson_usage_surface.py. None of them caught a regression. Every property they pin still holds; they pinned it at the old LOCATION: they patched `usage_for_notes` on the door modules and read the route source for `usage_for_notes(` and `empty_usage()`. 62f3a48 moved all seven doors onto `note_usage.attach_usage`, so the name is gone from the doors. This is rule 167's case: a guard that fails on code you believe is correct has usually moved out from under its property. So the guards are relocated, not deleted. Each one still has an assertion that can fail: - MCP list / once-per-page / read-before-pull: patch `usage_for_notes` on `note_usage`, the module every door now reads it through. The ordering test still fails if a pull is recorded before the count is read. - REST list: calls `attach_usage(items)` exactly once, and does NOT hand-roll `it["usage"] =`, which is how a row could lose its zero-filled key again. The seam's own zero-fill and single aggregate are asserted in test_usage_attach_seam.py. - REST detail: `attach_usage(` still precedes `record_pulled(`. - Detail view: the advice moved into utils/deadWeight.ts, so assert BOTH that the view reads DEAD_WEIGHT_ADVICE.lesson AND that the table's lesson entry still points at `when_to_apply`, so the guard cannot pass by pointing at an entry that has stopped saying the right thing. Missed before pushing because I grepped src/ for callers of the old name and not tests/ for patchers of it. A test that patches a name off a module is a caller too. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 22:03:05 -04:00
bvandeusenandClaude Opus 5	62f3a485ad	fix(usage): one seam attaches the surfaced-vs-opened chip, and the Knowledge browse uses it (#4230) ... `usage_for_notes` is named for notes and works on every note row, yet the chip reached snippets and rules only. Notes had it nowhere. Lessons had it collected and shown nowhere a person could reach, because #4196 taught `/api/lessons` to attach it and `KnowledgeView` — the only lesson list in the UI — browses through `/api/knowledge`, so `listLessons` still has no consumer. The cause was not a missing line. SEVEN call sites carried their own copy of the same few lines: two REST lists, two REST details, two MCP lists, one MCP detail. Each read perfectly well alone, so "which doors attach usage?" had no answer anywhere in the code — the same asymmetry test_system_tagging_door_parity.py records for System tagging (#4249), where whichever door nobody exercised for a kind is the one that never grew the feature. `attach_usage(rows, key="id")` is now that answer, and all seven go through it. A detail payload is a one-row list, so the single-record doors share the seam rather than keeping a second shape beside it. Deliberately NO try/except: the fail-open already lives in `usage_for_notes`, which reports through `_report_failure("readout")` and returns the zero-filled map. Wrapping it again would swallow the REPORT as well as the error, and a silently-swallowed readout failure is exactly #2663 — every counter reading zero in production for weeks while the writes landed fine. `/api/knowledge` now attaches usage, which closes both holes at once: it is how notes, lessons and processes are all browsed. `KnowledgeView` renders the badge on the card footer, looking the advice up per row because the feed is mixed. The advice moves to utils/deadWeight.ts. Canon #3460 says each caller owns its own const, and that held while each caller showed ONE kind; a mixed feed would need five of its own and the next surface another five. The canon's actual invariant — advice is kind-specific and never baked into the badge — is kept: it is still a prop. The three existing callers now read the same table, so the sentence has one home rather than four. Recorded against #3460 so the next reader is not left re-litigating it. `_row_id` rejects bools explicitly: `int(True)` is 1, so a row carrying a flag under the key would be credited with note #1's counts, and a wrong chip is worse than no chip because it reads as a measurement. A row with no usable id is skipped rather than failing the page. Tests pin the PROPERTY, not one route: no door calls the aggregate directly (AST, so a comment naming it is not a false positive), and every door that shows usage reaches the seam. Plus the N+1 guard — one aggregate per page, asserted on await_count, because the per-row version reads more naturally and is invisible in review. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 20:47:16 -04:00
bvandeusenandClaude Opus 5	91cde6c3e4	fix(shapes): let a measured meaning-miss silence a divergence prompt (#4208) ... #4204 gave the divergence check a structural gate, which silenced one of the five false prompts it was filed for. The other four are `def` helpers in a directory whose canon is an `async def` service unit. No refinement of `shape_form` reaches them: they differ from #2793's acceptance case — a hand-rolled sync `confirmDanger` where an async confirm helper is canon — only by the JOB they do, and a signature does not carry a job. The proposer's semantic arm already reads bodies per symbol, which is the comparison option 2 asked for and was thought to be missing. What it did not do was record its MISSES: a hit became `proposal_basis = "semantic"`, a miss left the row indistinguishable from one nobody had looked at. So `flag_divergence` could ask the proposer "do you agree this is the canon?" but never "did you check, and is it not?". `_semantic_canon` now reports whether an empty answer is evidence, and `flag_divergence` withholds the prompt when it is. The whole risk is in the negative, so only a conclusive miss is stored. A body too thin to embed, a row the per-refresh cap never reached, an arm that threw, and a result set that came back full — and may therefore have hidden the canon behind the limit — all stay "cannot tell" and still ask the question. That is the discipline `FORM_UNKNOWN` already enforces here: not knowing must make a check quieter, never more confident. `_SEMANTIC_LIMIT` is named for that reason; the number is load-bearing, not a tuning knob. No migration: `proposal_basis` is nullable Text with no CHECK constraint (verified in the model and across alembic/versions), so rule 36 does not bite. Nothing can mistake the miss for a proposal either — every reader keys on `proposed_snippet_id` or `proposal_group`, and `confirm_shape_proposals` requires the id non-NULL before it will confirm anything. `_PROPOSER_VERSION` 3 -> 4, per its own contract: rows remember the ruleset they were examined under, and without the bump no already-examined row would ever acquire a miss. Option 1 (widening `kind`) stays closed, on the merits rather than on cost: bucketing density by exact form takes the async canon out of a sync candidate's denominator and silences #2793's acceptance case by the identical mechanism, one layer down. The reasoning is on #4208. Tests: tests/test_divergence_meaning_gate.py pins the report contract, with the truncation case tested hardest — reading a cut-off as a negative would weaken the guard in proportion to how many snippets the operator has. The end-to-end discrimination is in test_integration_shape_classify.py on deliberately the SAME fixture as #2793's acceptance case, so the two runs differ in exactly one thing: whether the arm claims to have looked. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 20:35:55 -04:00
bvandeusenandClaude Opus 5	d49e4ad106	refactor(tests): derive the two duplicated test helpers into tests/helpers.py (#4276) ... Derive-first, ahead of the tests shape pay-down. An AST pass over all 2628 definitions under `tests/` found exactly three helper bodies duplicated across files. Two are real copies and are consolidated here; the third is not, and is left alone. `need_tools(*tools)` — byte-identical in three hook-test modules, each skipping when `jq`/`awk`/`git` is absent from PATH. Now snippet #4277. The `import shutil` each file carried existed only to serve it and goes with it. `rule_row(rule_id)` — byte-identical in two integration modules, reading a Rule back through a SEPARATE session so the assertion is about what Postgres holds rather than what the writing session's identity map remembers. Now snippet #4278. Its imports are lazy, because `tests/helpers.py` is imported by unit tests that have no database, which is the same reason `plugin_config` defers its service imports. NOT consolidated: `_side(uid, k, d="")` in test_services_plugin_context and test_write_path_trigger. The body is identical but it closes over a module-local `stored` dict, so it is not self-contained and "moving" it would mean inventing a parameter neither call site wants. That is convention plumbing — two tests independently writing the same one-line side_effect — and it is dismissed in the ledger rather than lifted. Worth recording for the next pass: a repeated NAME is not a family. `_row` is defined in five modules and only two of those share a body; the other three (test_list_rows_brief, test_calibration_stamp, test_shape_ledger) build entirely different objects. Grouping by name would have consolidated three things that have nothing in common. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 18:27:05 -04:00
bvandeusenandClaude Opus 5	b47dc97ca8	fix(tests): the round-trip guard needs fake_lesson, not fake_note (#4272) ... Run 7208 failed 5 of 23 in the new file, all with a `**Learned from:** #1` that no shape asked for. `lesson_sources` falls back to `arose_from_id` when neither the mirror nor the body names a source. `fake_note` leaves that field to MagicMock, which auto-creates it truthy and coerces to 1 — so every no-sources shape recomposed with a provenance line and the round trip failed for a reason with nothing to do with the trigger. `fake_lesson` pins `arose_from_id` to None and its docstring says why; it is also the truthful stand-in, since these are lessons. Worth recording separately: the local harness that cleared this change used a plain stub class, so it was kinder than the real fixture and could not reproduce the truthiness. The stub has been given the same None. A stand-in that is more forgiving than the one the suite uses will verify a change that CI then rejects — note #2109's point, arriving from the other direction. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 16:39:31 -04:00
bvandeusenandClaude Opus 5	9883b010b3	docs(lessons): give the round-trip guard the measured growth, not a remembered one (#4272) ... The module docstring said the defect grew the worst real body by 520 characters over ten edits. That number was recalled, not measured, and it is wrong — as was the 2500 I then got by deriving it on paper instead of running it. Replayed lesson #4207's actual stored shape through the old code: 607 characters per edit, exactly the length of the trigger's paragraphs 2 and 3 with their separators, taking the body from 1291 to 7361 over ten edits. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 16:37:10 -04:00
bvandeusenandClaude Opus 5	8de97b3190	fix(lessons): strip a lesson's trigger by what was stored, not by matching a line (#4272) ... `update_lesson` is field-wise: an edit that touches only `system_ids`, or only the title, passes `insight=None`. The service then derives the insight from the stored body and hands it straight back to `compose_body`, which re-adds the trigger and the provenance line. The derivation and the composition have to be inverses, and they were not. `_strip_composed_lines` filtered out body LINES matching the trigger marker's pattern. That pattern is `re.M`, so it matches one line. `when_to_apply` is free text and is routinely several paragraphs — `compose_body` writes all of it after the marker, so paragraphs 2..n were ordinary lines the filter had no reason to touch. They came back as part of "the insight", the whole trigger was prepended again on top of them, and the record gained (n-1) paragraphs per update. Silent, compounding, and in the half of the document that does the retrieving: a lesson edited a few times ends up stating when it applies several times over and burying the insight below it. No marker could fix this. There is no end-of-trigger marker in the body, and adding one would not repair a row already written without it. What makes an exact strip possible is that the trigger is mirrored in `data[TRIGGER_KEY]`, so the composed head can be rebuilt byte for byte and removed by subtraction rather than matched by pattern. Hence `lesson_insight(note)` rather than `_strip_composed_lines(body)` — it takes the record because the body alone does not say where the trigger ends. The line-wise removal survives as the fallback for a row whose mirror is missing, where it is right for a one-paragraph trigger and is the best available without one; a mirror that disagrees with the body falls back rather than cutting into the insight. tests/test_lesson_insight_round_trip.py asserts the property rather than the strip: `lesson_document(what, trigger(n), insight(n), sources(n)) == (n.title, n.body)` across six shapes, and again over ten consecutive no-op edits. Falsified against the old code before committing: 11 of 23 fail on HEAD, the headline one reporting a body grown by 3230 characters over ten edits. The one damaged row in the corpus (#4207, two paragraphs duplicated by a `system_ids` edit) was repaired by hand against its authored text. #4221 is the only other lesson with a multi-paragraph trigger and has never been updated, so its body is intact — its derived `insight` was wrong, its storage was not. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 16:35:51 -04:00
bvandeusenandClaude Opus 5	43ed7f4db7	fix(access): tag a record as the user doing it, not as its owner (#4249) ... `set_record_systems` is not a dumb setter. It runs its own `can_write_note` and then links only the Systems the given user can READ. Four of twenty call sites handed it the record's owner instead of the acting user, which did two quiet things at once: the access check became trivially true, since an owner can always write their own record, and the System filter used the owner's visibility rather than the actor's. On a single-user install neither is observable. With a share it is an editor acting with the owner's reach — the shape rule 47 exists to prevent, and the same reasoning routes/notes.py already spells out for `set_supersedes` two lines away. This is NOT a permission change. Every one of the four sites establishes the caller's write access first: routes/lessons.py and routes/snippets.py call `can_write_note(uid, …)`, mcp/tools/processes.py does the same, and mcp/tools/snippets.py reaches `set_record_systems` only after `update_snippet` has raised PermissionError if the caller may not write. So nobody gains or loses the ability to edit anything. What changes is whose reach the tagging runs with, which is exactly the kind of difference that survives review because every call site reads fine on its own. The four: routes/lessons.py:243 owner_uid -> uid routes/snippets.py:211 owner_uid -> uid mcp/tools/snippets.py:486 note.user_id -> uid mcp/tools/processes.py:196 note.user_id -> uid The last one was written earlier in this same session, an hour before the sweep that found it, with a comment confidently explaining why the owner was correct. That is the argument for the guard rather than for care: the unified stance was known and still got it wrong at the next opportunity. So the guard is the point again. `test_every_tagging_write_acts_as_the_caller` walks every `set_record_systems` call in src/ and asserts the first argument is a bare local named `uid` or `user_id` — an attribute access is a record's owner by construction. Verified against `git show HEAD:` as well as the working tree: clean now, four offenders on the code it replaces. Reads are deliberately untouched. `list_record_systems(owner_uid, …)` gates on reading the NOTE, which the caller can do anyway, so it returns the same list either way; it is a different operation and churning it would add noise without changing behaviour. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 16:09:41 -04:00
bvandeusenandClaude Opus 5	e2e1ea3667	fix(systems): a record can be filed under a System from whichever door wrote it (#4249) ... A System tag is how `list_system_records` gathers an area's pile, so a record that cannot be tagged is reachable by search and by nothing else. `update_lesson` did not take `system_ids` while `create_lesson` did, which made tagging available exactly once — at the moment of least information. A lesson is usually written at the end of a piece of work, which is precisely when that argument gets dropped, and after that the record could never be filed at all. Filling in the rest of the table found three more gaps, and the issue's own generalisation was wrong. It read as "the REST door can do something the MCP door cannot", on three instances in a row. In fact: * `create_preference` is the exact MIRROR of the lesson bug — update takes `system_ids`, create does not. The same capability missing from the opposite end of the same lifecycle. * `routes/notes.py` handled `system_ids` NOWHERE, while the MCP door handled both ends. That runs the opposite way round from the premise. * `create_process` / `update_process` took it at neither door, though a process is a note and has always been taggable in the data model. The real pattern is that whichever door nobody exercised for a kind is the one that never grew the parameter — which is a better statement of #4248 than the one recorded there, and is not something a reviewer reliably notices, because each door is only ever read on its own. Milestones are NOT a fifth gap. `RecordSystem.note_id` is a ForeignKey to `notes.id` and milestones are their own table, so they cannot be tagged at any door by construction. Pinned in the test so the next pass does not re-open it. So the guard is the point, not the four parameters. `update_lesson` alone would have left the shape that produced it intact. The new test asserts the TABLE — every kind taggable anywhere is taggable everywhere it is written — and keys the registry-coverage check on the SIGNATURE rather than on a grep, so a module that only names the argument in prose is not swept in and no hand-kept skip list can go stale. A fifth kind fails there rather than shipping half-wired, the same reasoning test_derived_mirror_generic_door.py records for derived mirrors (#3734). One inconsistency found and deliberately not changed here: for the same operation `routes/tasks.py` scopes `set_record_systems` by the caller while `routes/lessons.py` and `routes/snippets.py` scope it by the owner. The new notes code follows tasks.py and says why in a comment (#47 — an editor-share holder should tag from what they can see rather than inherit the owner's reach). Recorded in #4249 rather than fixed as a drive-by. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 16:02:16 -04:00
bvandeusenandClaude Opus 5	42360f616c	fix(telemetry): silence is only an answer where the ledger was watching (#4268) ... `band_hugs_floor` compares an arm's weakest tenth against its floor, and #4225 made it SUSPEND rather than soften when the floor moved inside the window — because across a change the scores and the bar come from two different populations. It reads `floor_moves_since`, which answers "did this arm's floor move", and it read an empty answer as "no, it held steady". Those are the same answer only where the ledger was watching. Before an arm's first floor row there is nothing to move, nothing to report, and no way to tell a steady floor from an unrecorded one. The suspension was reading absence of evidence as evidence of absence, and the symptom is the one #4225 documented: a band "-0.0208 above its floor" — an impossible negative distance, printed with the suspension silent. Every install passes through this. The ledger's first row for an arm is written when that install first boots the release that records baselines, so any window longer than the install is old reaches back past it. The lowered-floor direction hides: the gap comes out comfortably positive and reads as a clean bill of health. `floor_history_gaps(since)` answers the question its companion cannot: which arms' floor history does not REACH the start of the window. Arms come from `surface_names()`, not from the ledger — an arm the ledger has never heard of is exactly the one at risk, so it cannot be the ledger that decides which arms get asked about. Baselines count here, which is the one place the two deliberately disagree. A baseline records a default without changing it, so it is not a move and `floor_moves_since` filters it out. It IS the ledger beginning to observe the arm, and from that moment silence genuinely means the floor held — filtering it out here would suspend the band check forever on every install that has never tuned. `floor_history_unknown` sits between the known move and the band, so an arm with a date to give gives it. Two sentences, because the remedies differ: a date says ask again with a smaller `days`; no history at all says there is nothing to wait for, and names what starts the record. Why now: #4261 measures the work-log change by reading these warnings, and every window for the next month opens before this ledger's first row. Measuring against an instrument that prints a number it cannot support is the #4225 trap one level up. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 14:38:16 -04:00
bvandeusenandClaude Opus 5	a58a225d7b	fix(embeddings): a backfill reads text when it embeds, not when it scanned (#4264) ... Every backfill selected the text alongside the id and then iterated that snapshot, sleeping between records. Over a real corpus that is minutes, and anything edited inside the window was re-embedded by its own write path and then OVERWRITTEN with the pre-edit text the scan had captured — stamped at the current chunker version, so the next boot considered it current and never repaired it. The record stayed findable by what it used to say, indefinitely, until someone happened to edit it again. Nothing reported it, and no existing signal separated it from a correct record: the version was right and the vectors were there. All four backfills had it. Three were pre-existing; I wrote the fourth an hour ago for #4251 by copying the third. #4251 also widened the exposure. The race used to need a note-body edit; now every add_task_log re-embeds its task, so any session recording work during a backfill can hit it — which is exactly what "forward work continues while the backfill runs" means. TWO HALVES, SEPARATE ON PURPOSE. Stopping it: the scan takes IDS ONLY and `_current_row` re-reads each record at the moment it is embedded. One indexed primary-key read, negligible beside the forward pass that follows, and it turns a backfill from "replay a snapshot" into "repair to current truth". The residual race shrinks from the length of the run to the width of one record, which the parent-row claim and the single-transaction replacement narrow further. Repairing it: `_vectors_older_than_their_record` adds a third staleness condition beside "no vectors" and "old chunker" — vectors older than the text they encode. A guard that refuses to write a bad value does not undo the bad values already stored (#4202); the rows are what has to change. That check earns its place beyond the bug that prompted it. It equally catches a record whose `embed_note` never ran — no event loop, a swallowed refresh, a process that died between the commit and the index. Every one of those looks identical from the version column and identical from outside. And a work log is part of a task's document while living in its own table, so writing one never moves `notes.updated_at` and the timestamp comparison cannot see it. `_tasks_logged_since_embedding` covers exactly the records the race was most likely to have hit. The live instance has already run #4251's backfill — the prior-art arm is surfacing `## Work log —` passages, which is the thing itself rather than a banner about it. Whether that run clobbered anything is unknown and was not measured; the repair half picks up whatever it did on the next boot, without needing it diagnosed first. The structural guard in the tests was checked against the old shape, not just the new one: reintroducing `select(Note.id, Note.title, Note.body)` makes it fail, so it can catch the next copy of this rather than only agreeing with today's code (#167). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 13:38:12 -04:00
bvandeusenandClaude Opus 5	1fca8c2808	feat(retrieval): a System's charter becomes an answer, not just a filter (#4251) ... Step 2 of #4251. A System's `description` is a charter — several hundred words saying what belongs in that area and what does not — and it is the answer to "which part of this codebase does X live in". There was no semantic path to one: `list_systems` enumerates, and `search(system_id=…)` uses a System as a FILTER over notes. So a System could narrow a search and could never be the answer to one, and an agent asking where a record belonged had to read every charter or guess. ITS OWN SEARCH, not a `content_type` over notes, for the reason note 3163 gives about milestones: the row could be shared, the search cannot. A charter competing with the whole note corpus for one top-k is outranked by the records filed under it — the right answer crowded out by its own contents — and "where does this belong?" is a different question from "what prior art is there?", which a caller asking one should not have to read past answers to. So `system_embeddings` (0107) joins note_, rule_ and milestone_embeddings as the fourth sibling, with `system_document`, `upsert_system_embedding`, `semantic_search_systems`, a startup backfill and `search(content_type= "system")`. Scoped like milestones: with a project_id, that project's Systems if the caller can read the project (rule 78); without one, the caller's own. Archived Systems are excluded — an archived area is one the operator has said is no longer where things go, which is exactly the question being asked. `system_document` is the plainest of the four shapes on purpose. A charter is already written as the thing this search has to match, in the words someone asking would use — so there is no trigger to synthesise as `rule_document` must, and no second record to gather as `task_document` must. The stored charter IS the sharp document, the way a snippet's is. `color`, `status` and `order_index` stay out: presentation and bookkeeping, and a vector carrying them would be answering a question nobody asks of a charter. The search publishes `report["best_chunk"]` from the start rather than being retrofitted, which is what #4251 asked of any fourth search. It matters more here than anywhere: a charter runs long and a result shows its NAME, so a match on the paragraph that actually decides where a record belongs would otherwise be previewed by two words that cannot say. The id that comes back is the one `system_id`, `system_ids` and `list_system_records` already take, so the answer to "where does this belong?" is directly usable as "show me what is there" and as "file it here". `embed_system` sits beside `notes.embed_note` at the service for #2056's reason — every door gets it by construction. Not called on delete: that is a soft delete and the search joins through `System`, so the vectors are already unreachable, and leaving them means a restore is findable again immediately. `system_embeddings` is declared in backup's `_NOT_INCLUDED` as derived, beside its three siblings. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 11:25:53 -04:00
bvandeusenandClaude Opus 5	aa95c109ea	feat(retrieval): a task's work logs join the document it is embedded as (#4251) ... Step 1 of #4251. A work log is the richest prose Scribe holds about WHY something is the way it is — written during the work, recording what was tried and ruled out. #4241 made it readable from the agent's door. It was still not findable, so "has anyone tried this approach?" — precisely the question a log answers — could not reach one. The cost is not hypothetical: #4208 was rebuilt in this session because its logs were unreachable. THE DESIGN QUESTION the issue left open was whether logs embed as part of their task's document or as rows of their own. As their own rows, a hit has to be resolved back to a task to be worth anything, and it needs a fourth search, a fourth result shape and a fourth arm. As part of the task, the objection is that a long log drowns a short title. That objection was true before #280 and is not true now. Chunking made one record into one vector per section, so each log becomes its own title-anchored chunk, scored separately, and the task's own prose keeps the chunk it always had — a task is as findable as its best-matching log rather than as the average of everything in it. The other half is this session's other build: a search hands back the chunk that won (#4243), so a hit earned by a log shows that log's passage under the task's title. Without that a reader would have got body[:240] of the task — the opening of a record whose relevance lives three hundred lines further down. So `task_document(title, body, logs)` sits beside `rule_document`: a synthesised embed-time shape, because the stored record is the task row and the logs live in their own table, so the document that should be searchable exists nowhere until it is built. A task with no logs is returned untouched — most notes are not tasks and most tasks carry no log, and their vectors are the corpus every tuned number here was measured against. CHUNKER_VERSION 1 → 2, and its comment now says what the version actually means. It used to read "whenever chunk_document's output can change for the same input", which this change would slip past: `chunk_document` is untouched and every task with a log now embeds differently while its title, body and the chunker all stand still. The invariant is the document a record is embedded as. The startup backfill re-embeds on that. Create, edit and delete of a log all refresh the task through `embed_note`, the one path every writer shares — an edited log whose vectors still carry its old wording keeps matching what it no longer says. No new kind enters the auto-inject menu: tasks were always in it, and this makes recall on them better rather than changing what the menu spans. The calibration stamp will now report shape_version 2 against numbers measured at 1, which is exactly the report #4104 built it to make. Also promoted `session_returning` into tests/helpers beside `make_mock_session` (#2834) — two files had spelled it out identically and a third was about to. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 11:20:27 -04:00
bvandeusenandClaude Opus 5	5fb41af9b0	feat(search): the agent's search can ask for every kind the corpus has (#4250) ... The engine took `note_type` and `task_kind` all along. What was missing was a way to say them: the MCP tool's `content_type` knew `note`, `task` and `all`, and `/api/search` knew the same two — so an agent could not ask "has this snippet already been recorded" or "what lessons apply here" without searching everything and reading past the rest. Browse offered nine kinds from the same data. The cause is that each door kept its own map. `_FACETS` in services/knowledge is where a kind is declared, and #3161 made adding one a single edit by generating the SQL filter, the Python predicate and the door's validation from it — but the two search doors were written before that and never joined. So this adds the third dialect, `search_filters_for`, and one composition over it, `content_type_filters`, and both doors now derive instead of listing. Two names keep a meaning of their own, and the docstrings say so: `all` is no filter, and `note` is BROAD — any non-task, snippets and lessons included — where the browse facet of the same name is narrow (`note_type == 'note'`). They are left different deliberately; narrowing this one would stop returning snippets to every caller that already asks this way. An unrecognised kind is now refused rather than answered. Both doors used to fall through: the MCP tool into a filter matching no row, the route into no filter at all, so `?content_type=snippets` returned the whole corpus while looking like a narrowed search. An empty result set is a claim — "the corpus holds nothing like this" — and an agent acts on that claim by building the thing it could not find, so a typo must not be able to make it. The docstring is the agent-facing contract (#2846), and a test now holds it to the table: every kind `_FACETS` declares has to appear in it, because a filter an agent has not been told about is unreachable however well it is wired. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 11:12:48 -04:00
bvandeusenandClaude Opus 5	0ec499d9b4	test: the milestone result shape moved, and its fake had a mock for a body ... test_milestone_search_is_its_own_shape asserts the result dict exactly, so adding `matched` / `matched_is` / `body_length` broke it — which is the test doing its job. Its fake was a bare MagicMock, so `m.body` autovivified: `matched` came out as a mock object and `body_length` as 0, and nothing in the old assertion touched either. Lesson #2833 is about exactly this, and the failure output is what surfaced it. The fake now carries a real body string and a report with the chunk that matched, so the assertion is about the product rather than about MagicMock's attribute behaviour. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 09:46:33 -04:00
bvandeusenandClaude Opus 5	253fb974f3	feat(retrieval): every semantic search hands on the passage that matched ... #4243 fixed one door. Scribe has three semantic searches over three chunk tables, and all three collapsed chunk rows to the best one per record — each of them KNEW which passage earned the hit, and each dropped it. Every surface downstream then previewed the head of the document instead: a span the search had already scored lower, with nothing saying so. Mechanism, one place: - embeddings.record_best_chunk publishes {id: {index, text}} into `report`. Carried in `report`, NOT the return value: all three return list[tuple[float, Record]] and ~30 sites unpack that pair (lesson #4207). - semantic_search_rules and semantic_search_milestones now select chunk_index/chunk_text and publish the winner, as notes already did. semantic_search_milestones gains `report`, which it had no way to take. - services/text.matched_excerpt is the one choice of span, and excerpt_fields the one result block. Doors keep their own field names — the web renders `snippet`, MCP returns `excerpt` — because renaming a field a frontend reads is a different change from fixing what goes in it. Surfaces: - knowledge.query_knowledge, whose own comment calls it "the human's MAIN search surface", was `(note.body or "")[:200]` on every row alike. Now the matched passage on a search, the opening on a browse, and `snippet_is` saying which. KnowledgeView renders that snippet, so this was live. - search(content_type='milestone') gains `matched` — the plan body stays out, but the passage that matched comes along, because recognising a plan means recognising the part you asked about and a description written at the start need not mention it. - The auto-inject menu and the write-path prior-art menu put the passage under their line. Both were title-only, which answers "does this apply?" for a lesson or snippet (the trigger is IN the title) and not at all for an issue or dev-log. No fallback to the body's opening: on a menu that is preamble dressed as a reason, and once indented it cannot be told apart. Left alone deliberately: the rule arms. A rule hint already renders the rule's TRIGGER, which is written to answer exactly "does this apply to me" and beats a matched chunk at it; and that line's budget was measured at #3851. Adding a passage there would duplicate the trigger and spend the budget twice. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 09:44:10 -04:00
bvandeusenandClaude Opus 5	6abedb0168	test: two tests that had to move with the chunk-carrying select (#4243) ... test_chunking::test_search_collapses_chunk_rows_to_best_chunk_per_note feeds rows straight into the real semantic_search_notes, so widening the select to carry chunk_index/chunk_text broke its 2-tuple fakes. I had claimed no unit test did this after grepping test_embeddings.py, which was the wrong file. Rows are 4-tuples now, and the test additionally asserts the winning chunk is REPORTED and not merely used for scoring — the property #4243 exists for, and this is where it belongs, beside the collapse it comes from. test_task_work_log_surface's ACL test asserted "task_logs.user_id" was absent from the compiled statement. It is present in every SELECT as a projected column; the claim was about the WHERE clause. Asserts on stmt.whereclause now, which is what was actually meant and still fails if an owner filter returns. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 08:54:15 -04:00
bvandeusenandClaude Opus 5	fdc07f2a2b	fix(search): show the passage that matched, not the opening of the body (#4243) ... Raised by the operator: are we limiting what comes back by character count, and how do we verify the pertinent part is the part displayed? We were not. mcp/tools/search.py sent (note.body or "")[:240] — a head cut, with no marker that anything had been removed, so a 240-character preview of a 4000-character record was indistinguishable from a complete short one. The opening is the wrong span. The match is semantic and per chunk, and semantic_search_notes collapses to best-chunk-per-note — its own comment at the collapse says "the first appearance of a note is its best chunk". So the system identified the passage that earned the hit and then discarded it: select(Note, distance) kept no chunk column. A record could rank first on its sixth paragraph, be previewed by its first, and be judged irrelevant on a span the search had already scored lower. That biases against long records, and it is self-concealing — the caller who does not open it never learns the preview was misleading. - embeddings: chunk_index/chunk_text ride along in the select, and the collapse records the winner in report["best_chunk"]. Carried in `report`, NOT by widening the return tuple: ten callers unpack (score, note) at ~18 sites and nothing would catch the misses (lesson #4207). `report` is the side-channel this function already uses for best_available_score. - search(): excerpt / excerpt_is / body_length, and read_full when there is more. A caller that cannot tell a matched passage from a document opening cannot judge whether to look deeper, which is the only decision the field supports. elide() moves to services/text.py so both callers share one copy, and it keeps BOTH ends with a stated gap — it is the fallback for when nothing identifies a better span than "all of it", not the goal. Also fixes a guard that produced a false failure on the previous commit: test_pull_telemetry checked `"project_id: int = 0" in body.split("\n")[0]`, which sees only the first line, so wrapping get_task's signature over four lines made it report a function that does take the project as one that does not. Parsed with ast now, and proven to still reject an absent or wrongly-typed parameter rather than being appeased by reflowing the code. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 08:50:16 -04:00
bvandeusenandClaude Opus 5	4f2977b848	fix(tasks): add_task_log wrote to a surface no agent could read back (#4241) ... The work log reached the web UI through routes/task_logs.py and nothing else. get_task returned only the body — a claim written once, before the work — with the record written during it invisible beside it. So a stale body arrived with nothing to contradict it, and this session rebuilt work that had already shipped, with the evidence sitting in the task's own logs. Read side, scoped through the access layer (rule 78): - logs_for_task / count_logs_for_task / log_counts_for_tasks in services/task_logs.py. Scoped by who may read the TASK rather than by who wrote the entry: list_logs filters TaskLog.user_id == user_id, which hands a shared collaborator an empty list reading as "no work has been done". The page query folds readable_notes_clause into the same statement so the permission does not become an N+1. - get_task returns work_log; list_tasks and get_milestone steps carry log_count, zero-filled so "none" is a count and not a missing key. Elision keeps both ends. The newest entry arrives whole to 4000 chars because it answers "where does this stand"; older ones are shortened from the MIDDLE, never the head. A head cut selects what a reader sees by character position, which is uncorrelated with what matters — an entry closing with "so this shipped in 04775c3" loses the one sentence that answers the question, and a truncated flag says something went, never whether it mattered. The gap states how many characters it covers. conftest gains an autouse stub for the new read arm, same reasoning as _no_rule_arm: three widely-called tools grew a database read, and the existing call sites should not each have to learn about it. Raised while reviewing this: search() has the same shape and worse — body[:240] with no marker at all, while the chunk that actually matched sits unused in the row that won. Filed as #4243, not fixed here. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 08:45:43 -04:00
bvandeusenandClaude Opus 5	f8e53c1c35	fix(telemetry): a warning fired on an arm whose decline rate is arithmetic, not evidence (#4232) ... Found by reading a live `retrieval_telemetry` readout after milestone 419 deployed, not by inspection. The readout said: cannot_decline / report_preference — "45 calls, 0 of them returned nothing. An arm that fires unasked has to be able to say nothing; this one never has. Check that it applies its floor at all." And printed, beside it, that arm's band: p10 = p50 = p90 = min = max = 0.791. FIVE IDENTICAL PERCENTILES IS THE TELL. That is not a ranking, it is one record at one score on every call — because `report_preference` searches a fixed string (`reply_preferences.COMPLETION_QUERY`, a module constant, and deliberately so). For a fixed query against a stable corpus the top score is a CONSTANT, so the arm's decline rate is 0% or 100% and never in between; which of the two it is depends only on where the bar sits relative to that one number. "Never returned nothing" is therefore arithmetic, not evidence, and the warning's own remedy — check whether it applies a floor — cannot be answered from it. The arm already knew this about itself; the warning did not: "a fixed query makes this arm's score a constant and a floor a hair above it produces a dead arm no amount of traffic will ever reveal" — services/reply_preferences.py THIS CLASS OF BUG ALREADY HAS A GUARD, which is the argument for the shape of the fix. `Point.logs_unconditionally` exists because of #3497: both rule arms once logged only their hits, so their zero count was structurally 0 and this same warning would have fired on a LOGGING property while sending the reader to move a threshold that was never involved. This is that one step over — a QUERY-SHAPE property — and gets the same treatment: a declared field on `Point`, and exclusion rather than trust. AND THE WARNING THAT WOULD BE INFORMATIVE HERE DID NOT EXIST. For a fixed-query arm the dangerous state is the mirror image: every call empty, meaning the bar is above the constant and no further traffic will ever move it. The arm is off rather than quiet, and nothing in the readout said so — `expects_traffic` covers an arm with NO calls, not one with calls and a 100% decline rate. That state is real and reached: `report_preference` once logged 69 consecutive declines at 0.0006 under its bar. So `fixed_query_never_clears` sends the reader to `near_miss_samples` and not to the dial — because that incident is also the one where the statistic and the correct action pointed opposite ways. Every percentile said lower the floor; opening the refused record showed it was rule 77 arriving as a false positive, and lowering it would have delivered that rule on every completion report ever written. Guards in tests/test_retrieval_warnings.py, including the falsifier that matters most here: `cannot_decline` must still fire on an arm whose query varies, or this change is a disabled check wearing a narrowed one's clothes. Both boundaries tested from both sides, per that module's own standard. The new code is documented in the `retrieval_telemetry` tool docstring beside the others (rule 33) — an undocumented code in a readout is a reader meeting a verdict with no way to disagree with it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 08:05:52 -04:00
bvandeusenandClaude Opus 5	029692945e	fix(hooks): the by-name duplicate arm confirms its grep hits against the real extractor (#4227) ... #4222 fixed one end of this defect — the extractors that decide what a payload DEFINES now blank comment and string spans before any line matcher runs. This is the other end: `scribe_local_dups`, which decides which OTHER files already define that name, and which was still a plain `git grep`. A grep sees lines, not spans, so the sentence class with only modifier rules is a deletion that went half-way. — real prose from a module docstring in this repo — matched the arm's pattern for `name=with`. Writing a genuine `change`, `beside` or `wrapped` would be told it already existed, and pointed at a docstring. EVERY HIT IS NOW CONFIRMED by running `scribe_defs` over the candidate file and keeping only names it actually reports. That is the only check that cannot disagree with the other end of the pipe, which is the whole point. MEASURED, NOT ASSUMED — both numbers the task reasoned from turned out wrong. - WHAT IT REMOVES, across 141 payload files of this repo: 15 of 210 report lines. Every one a string literal, a comment, a TypeScript `import { type Foo }`, or Vue's `const emit = defineEmits()` boilerplate. No real definition was lost. Where a name had both — `create_note` — the phantom in a test's `shape_form("async def create_note(...)")` argument dropped out and the definition in services/notes.py stayed. `with` went from four files to none, which is the correct answer: nothing here defines it, and it is a keyword in several of these languages. - WHAT IT COSTS: mean 193ms -> 222ms, worst 569ms -> 572ms. The task feared "over a second added to a PreToolUse hook" from 48 confirmations. It is about 15%, because the arm was already dominated by its twelve `git grep` calls, and because confirmation runs once per DISTINCT candidate file rather than once per (name, file) pair. A deliberately pathological payload — nine names that are ordinary English words — reaches 28 distinct files and 947KB; `scribe_defs` runs at ~33ms per 250KB. THE CANDIDATE CAP IS RAISED FROM FOUR TO TWELVE, and that is load-bearing. Confirmation REMOVES hits, so capping before it runs lets phantom matches crowd a real definition out of the window — hits dropped before anyone looked at them, which is #4042's bug in a new place. The display cap stays at four and now applies to CONFIRMED hits, which is where a cap belongs. #4042's own `|| true` inside the substitution is untouched, and its regression case still passes. The task's own advice not to fix this by tightening the grep pattern is followed and written down: requiring `(` or `{` or `:` after the name rejects `class with only…` and also `class Foo extends Bar {`, `class Foo : Base()` and `type Foo struct {`. This arm exists because it works with no server, no index and no binding (#2280, #2682), which makes a miss here invisible — a visible false positive is the better failure. Guards: tests/test_hook_duplicate_confirmation.py, against real git repos because what is pinned is the interaction between `git grep`, `head` and the extractor. Seven of the eight fail against the previous implementation; the eighth is #4042's regression case, whose job is to keep passing. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 02:49:07 -04:00
bvandeusenandClaude Opus 5	edbc31f8ca	feat(lessons): the kind whose whole question is "is this trigger right" was the one kind that could not see its own counts (#4196) ... The lesson slot has recorded surfaced-vs-opened since it shipped. Nothing showed it. `get_lesson`'s REST door attached `usage` to the payload and no view rendered it; the listing did not attach it at all, and neither MCP door did. #4196 asks when a lesson that keeps getting followed should become a rule, and names the trap in the same breath: raw frequency cannot separate "this should bind" from "this trigger is too broad", and the second is the commoner reading by a wide margin. Surfaced-AND-opened can separate them. Neither question is answerable by a reader who cannot see the numbers, which is why this is the first step and not the threshold. NO THRESHOLD IS PROPOSED HERE, deliberately. The corpus today is 10 lessons with 7 recorded surfacings and 3 opens, over about fifteen hours of usage data. A promotion rule fitted to that would be fitting noise — #3311's failure, and the warning lesson #4228 was written to carry. `UsageBadge` already declines to render a verdict under three surfacings for the same reason. So #4196 stays open: its subject, the promotion path, is still unbuilt. What lands is the evidence it needs. - REST `GET /api/lessons` and MCP `list_lessons` attach `usage` to every row, from one aggregate per page rather than a per-row read, which would be N+1 by construction. Every row carries the key zero-filled, so "never surfaced" is a state a reader can see rather than a missing field they have to interpret. - MCP `get_lesson` attaches it too, and reads it BEFORE recording its own pull. That door records a pull on every open — it has to, or the kind sits permanently at zero — which makes the order load-bearing in a way it is not for a kind that only counts. The REST detail door already ordered it this way; the two now agree about what the number means. - `LessonDetailView` renders `UsageBadge` (snippet #3460) rather than re-spelling the chip, with the advice keyed to this kind: a lesson that is repeatedly offered and never opened is usually keyed to a situation nobody is in, so it points at re-keying `when_to_apply`, not at deleting the claim. Guards, in the two styles this pair of doors already uses: the MCP side driven behaviourally through mocks, including the call ORDER for `get_lesson`; the REST side on structure like its siblings in test_lesson_rest_door.py, because the route is decorated and returns a Quart response. Rule 167's falsifier is included. KNOWN GAP, not fixed here: `KnowledgeView` is the only lesson LIST in the UI and it reads `/knowledge`, not `/lessons` — so the REST listing change reaches `frontend/src/api/lessons.ts::listLessons`, which currently has no consumer. The agent-facing listing does reach a reader today. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 02:33:33 -04:00
bvandeusenandClaude Opus 5	5d06b74599	test(backup): prove the three restored code_shapes columns survive real Postgres (#4197) ... The column guard is a claim about kwargs; "the value comes back" is a different claim, and only a round trip settles it. This drives the real `restore_full_backup` over a judged shape carrying all three of the columns that were going missing. `diverges_from` gets the harder assertion. It is a FK to notes.id, so the tempting fix — carry the exported id across — produces a row pointing at whatever note holds that number in the target database: not dropped, REATTACHED, with the restore reporting success and the divergence about the wrong snippet. So the test asserts WHOSE note the pointer landed on rather than which integer it holds, and it refuses to run at all if the restore happened to reuse the source id, which would let it pass without proving anything. Same shape as the assertion in the rule_usage round trip, for the same seam. Also corrects this module's own docstring, which said the round-trip module "is not written yet". Three existed; this is the fourth. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 02:18:51 -04:00
bvandeusenandClaude Opus 5	33346da381	fix(backup): a restore could lose a column and still report success — code_shapes lost three (#4197) ... The column guard (#3182) makes a dropped column unexpressible on the way OUT. Nothing watched the way back IN, and that is the worse half: an export gap leaves an obviously thin backup, an import gap means holding a complete, correct file and restoring an incomplete database from it, with a success message. WHAT IT FOUND, the first time it ran. `code_shapes` was exporting `reason_code`, `recheck_at` and `diverges_from` and importing none of them. A restored ledger would have carried every judgment's verdict and not the code for WHY — the column the accounting reads to tell a scoped-css exemption from convention-plumbing — with every recheck flag cleared and every divergence pointer gone. `diverges_from` is a FK to notes.id, so it is re-mapped rather than carried: the raw source id would point at whatever snippet took that number in the destination, which is wrong rather than missing and is the milestone 333 trap one table over. WHY THE GUARD WAS ONE-SIDED. Not an oversight — the code was. Export goes through per-table pure helpers, so a test can hand one a stand-in and read which keys came out. `_restore_v2` built all 26 models inline in one 690-line procedural function, and there was no per-table unit to hand anything to. So the construction moved out, into a `_build_*` helper per table taking the exported row plus the id maps built so far. What deliberately did NOT move is the loops, the flushes and the id-map bookkeeping: that is the order-dependent part, where a mistake is a restore that half-works, and it gains nothing from being split. Returning None is "skip" and a None field is "degrade" — which one a table wants stays the table's own call, because both are right somewhere: a shape event without its project says nothing, while a usage event without one is still a real pull and dropping it would deflate the pull-through the table exists to report. The refactor was checked to be behaviour-preserving before the guard went in: all 26 constructor kwarg sets identical to HEAD, and all 28 skip conditions accounted for — 25 now in builders, 3 in loops that construct nothing (the rule_systems raw insert and the two in the final project patch). The guard then composes the two halves end to end: export a stand-in row, feed THAT dict to the builder, read which columns the model actually received. `test_the_usage_importer_restores_the_reading_project` read the source of `_restore_v2` with `inspect.getsource` because there was nothing to call; it is replaced by tests that call the builders and assert the skip/degrade behaviour directly. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 02:15:10 -04:00
bvandeusenandClaude Opus 5	d309fd7f0f	test(drafter): pin the rest of #2990's verify list to the span scan (#4222) ... #2990 asked for three cases. The wrapped-comment-continuation one shipped with #4222; these are the other two — a comment holding a whole rule defines nothing, and an unterminated comment does not swallow the file. Both already pass on both sides; the vectors are what stops a later change to the scan quietly taking them back. The phantom #2990 was filed for is among the twenty-two #4222 removes: `.editor-body` in TaskEditorView.vue, a persisted `code_shapes` row whose signature ends in `*/` and whose `used_by` count is zero — so it has been sitting in the unused_css number the operator is meant to act on. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 02:04:06 -04:00
bvandeusenandClaude Opus 5	84476d7ecf	fix(drafter): a wrapped docstring line beginning "class AND the" defines a shape called AND (#4222) ... The definition extractor is line-oriented and knows nothing about what a line is INSIDE. A docstring that wraps onto a line starting with a keyword announces a definition: `AND` reached a live session as a divergence prompt asking it to justify a symbol that does not exist, and `is` reached it as a repo-wide duplicate of four files that define nothing of the kind. Measured, not assumed: running the extractor over every scannable file with and without the scan differs by twenty-two phantoms. Two of them — `with` and `nobody`, both out of the module docstring in check_dangling_styles.py — are persisted `code_shapes` rows that have been judged. Those need no migration: sync_shapes marks a row it no longer extracts as vanished. `ast` would be the honest tool for .py and is not what this uses, because the extractor is mirrored rule for rule by an awk program in the hook, awk cannot parse Python, and a fix only one of the pair can run is the drift the mirror exists to prevent. Both sides now run the same left-to-right scan and blank comment and string spans to their own newlines before any matcher sees a line. Three things the scan has to get right, each of which cost real definitions while it was being written: - a string that HOLDS a marker is not a marker. `"red /* "` in test_design_stylesheet.py and a triple quote inside a single-quoted regex in plugin_context.py each ate every definition below them. - `#` is a colour in CSS and a comment in Python, and the extractor is handed no path. An alphanumeric straight after it settles it. - an unterminated opener blanks NOTHING. The scan rewinds past it and continues, so a stray marker costs one span rather than the rest of the file. The comment claiming the two extractors agree has been the only thing holding them together, and a comment cannot fail. The mirror test now RUNS the hook's awk over the same vectors: with the old program it reports the phantoms, which is what a guard that can fail looks like. Across all 631 scannable files in this repo the two now agree line for line. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 02:01:56 -04:00
bvandeusenandClaude Opus 5	04775c3496	fix(drafter): the base rate counted a dataclass and an async service unit as comparable things (#4208) ... A CORRECTION TO THIS ISSUE'S OWN PLAN, first, because the plan was wrong in a way that would have cost the acceptance case. #4208 recommended widening `kind` past `css | sym` to carry the form, calling the denominator the deeper win and a migration the price. Two things: 1. THE MIGRATION IS NOT NEEDED. The issue says density "is computed from stored rows and `shape_form` only runs on read". `canon_density` does `select(CodeShape)...scalars().all()` and filters to the directory in PYTHON; `signature` is a stored column; `canon_form(siblings, ...)` on the next line already derives form from those rows. Bucketing the denominator costs a list comprehension. 2. WIDENING `kind` WOULD BREAK MILESTONE #2793's ACCEPTANCE CASE. If `kind` separated `fn` from `async-fn`, density would bucket them apart — which does silence #4204's four `def` helpers, as claimed. Apply it to a hand-rolled SYNC `confirmDanger` in a directory where an async confirm helper is canon: the canon leaves the candidate's denominator, nothing dominates, no flag. That is the flag the milestone exists to produce, and it is the same inversion the first form gate made, one layer down. So option 1 is not expensive-but-right, it is wrong; and option 2 (compare meaning) is not the interim, it is the only lever. `confirmDanger` beside an async confirm helper and `is_registered` beside a service unit are identical at every structural level — same family, same form contradiction, same density. They differ only in whether the candidate does the canon's JOB, and no signature carries that. WHAT THIS SHIPS is the part that is right and provable: an honest denominator. `comparable_siblings` narrows the count to rows whose family does not contradict the candidate's, using `families_conflict` — the same predicate the gate uses, so the count and the verdict cannot drift into disagreeing about what comparable means. "372 judged siblings" stops counting a dataclass, a constant and an async service unit as three comparable things. NARROWED BY FAMILY, NOT FORM, for the reason above: `fn` beside `async-fn` stays a fair question. An unreadable sibling STAYS COUNTED — dropping it would shrink `judged`, raise the share, and fire the check more on the directories it can read least. Every unknown-form decision in this module goes that way. Density is now per candidate rather than per kind, cached on (kind, form). TWO BUGS THIS CHANGE HAD, both caught before CI and both pinned: - I passed a FAMILY where `families_conflict` reads a FORM, so `shape_family("callable")` returned "" and the narrowing was a silent no-op that still read as applied. The regression guard deliberately uses a callable: `type` is both a form and a family name, so testing with it proves nothing and the bug hides. - My new `_Row` in the test file shadowed the one already there — same fields, different `snippet_id` default — silently breaking three passing `canon_form` tests. Reused the existing class. A duplicate definition quietly changing a neighbour's meaning is this file's own subject. The residue test's docstring said separating the four needs "widen `kind` or a comparison of meaning". Corrected: they are not alternatives. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 01:33:45 -04:00
bvandeusenandClaude Opus 5	512d0326a0	fix(telemetry): a floor that moved inside the window makes the band check a comparison of two populations (#4225) ... `retrieval_telemetry(days=30)` reported, for write_path_rule: "the weakest tenth of what this arm returns scores 0.6984, only -0.0216 above its floor of 0.72" A negative distance above something. The tenth percentile of what an arm RETURNED cannot sit below the floor that gates what it may return — not inside one population. MEASURED CAUSE. write_path_rule's floor was 0.68 until 2026-09-02, when 2385100 (#3318) raised the shipped default to 0.72. The window opened 2026-08-22, so six days of it are calls made under the old bar; top_score.min for the surface is exactly 0.68, the old bar still in the sample. AND THE CHANGE LEFT NO TRACE THE READOUT COULD SEE. retrieval_tuning_events records dial turns — a person or a model choosing a number. It was silent about the other way a floor moves: somebody edits floor_default and ships it. retrieval_tuning_history returned {"events": []} and retrieval_surfaces said last_change: {}, source: "shipped". All true, and all of it silent about a floor that had in fact moved. THE RAISE ANNOUNCED ITSELF. A LOWERED FLOOR WOULD NOT: the gap comes out comfortably positive and reads as a clean bill of health on a sample that half predates the bar being judged. Both directions are now pinned. So the check is SUSPENDED, not softened. band_hugs_floor asks whether the scores are piled on the bar; that needs the scores and the bar to come from the same regime. Where they do not, the honest answer is that this sample cannot say, plus the date after which one can — floor_moved_mid_window replaces band_hugs_floor for that arm and never accompanies it. A reader told a number is unavailable goes and gets one; a reader handed a qualified number uses it. NO MIGRATION. `actor` is Text with no CHECK precisely so a new kind of actor is not one — the model's own comment says so, and this is the case it anticipated. "release" joins "model" and "human". user_id is already nullable, which is right: no user did this, a release acts on every account that has not overridden the dial, and a row per user would both multiply and misattribute it. Both readers now take the newest of (this user's change, the release's). THE FIRST SIGHTING IS A BASELINE, written with old_value NULL. Nothing moved; the row exists so the next release has a predecessor. That null is load-bearing: floor_moves_since asks for old_value IS NOT NULL, so a fresh install's baseline does not silently retire the check on every new install. UI: the tuning history rendered actor as `human ? 'you' : 'Claude'`, so a release row would have told the operator that Claude moved a floor it never touched — the one failure the actor column exists to prevent. Three-way now, with an unknown value printing itself rather than guessing. Recorded at startup, inline and awaited. What #4181 cost three hours was concurrency — a background task racing the hook for the same pool. Sequential creates no contention, and this is twelve single-row reads. It must finish before serving because a readout served before the change was recorded is the exact answer this exists to stop giving. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 01:17:37 -04:00
bvandeusenandClaude Opus 5	36b54bff1f	fix(plugin): the ledger that proves a rule was read was being deleted by the compaction that asked about it (#4217) ... Milestone 419's acceptance, and it failed the first time it was run — which is the only reason this commit exists. THE MEASUREMENT. Ran the step-5 readout against this session's real traffic instead of a fixture. It reported 19 rules named by an arm and none opened. That is false: the session had called `get_rule` 45 times. Across six real sessions on this instance: 208 opens, 3 surviving ledger entries. 1.4%. THE CAUSE. `.opened.ids` was doing two jobs with opposite lifetimes. - "this context HOLDS rule 156" — false after a compaction, and three hooks read it to decide whether to stay quiet. Clearing it is correct. - "rule 156 WAS OPENED" — which no compaction makes untrue, and which the session-end readout is built on. `scribe_clear_session_ledgers` sweeps every `<sid>*.ids` on SessionStart source=compact. Right for the first claim, and it was deleting the second. The TTL did the same thing more quietly: `scribe_rules_live` ages an exclusion ledger, which is right, and would have eaten the early part of any long session's evidence too. So the readout was reporting only the stretch since the last compaction while reading as though it had reported the session — a statistic that cannot vary being mistaken for a finding (#3311), which is the shape this whole milestone exists to stop producing. It ran AT the seam it was blind to. THE SPLIT. `scribe_rules_append` now writes both: the exclusion ledger it always wrote, and `<kind>.keep.ids`, an evidence twin that is never aged and never swept. The readout reads twins; the three `held` readers are untouched. DERIVED, NOT LISTED, because a list is what broke this before — the comment above the sweep says so about its own history. Every ledger written through the appender gets a twin, including the next one somebody adds; a new ledger is born on the swept side unless its name opts out. `scribe_checkpoint_allowed` writes its twin explicitly since it bypasses the appender, and there the split lands right on both sides: the cap counts the swept file, so a compaction honestly restores the budget to stop an act the context can no longer justify, while the record that a stop happened stays. Removed `scribe_ledger_ids`, orphaned by the change — a dead helper beside a live one is a thing the next reader trusts. test_session_ledger_clear.py asserted every ledger dies and could not have caught this: its fixture never created a twin, so the sweep was one glob away from either mistake with only one of them guarded. Both sides now asserted. The slippage tests build their ledgers through the real writers rather than by hand, for the same reason — a fixture that writes the bytes itself keeps passing after the writer stops. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 01:04:17 -04:00
bvandeusenandClaude Opus 5	ae773740b4	feat(plugin): the seam that erases the evidence is where the unresolved rules get named (#4216) ... Step 5 of milestone 419. The milestone's subject is that a rule read and ignored is arithmetically identical to a rule read and followed, and the compaction is where that identity becomes permanent — the turns holding the evidence are summarised away, and the unjudged thing survives as nothing. WHY THIS IS ASSEMBLED IN THE HOOK. `rule_usage_events` has no session column; it is per user over a window. A session-scoped answer therefore cannot be asked of the server, and has to be built where a session is a thing that exists. Four ledgers four hooks already write: .rules.ids an arm NAMED the rule .opened.ids the session called get_rule (#4100) .acted.ids the session called rule_outcome (new here) .checkpoint.ids the rule HELD an act (#4214) Every one is an observed tool call. Nothing asks the model what it followed — milestone 386 ruled that out, because a model asked "did you apply rule 156?" says yes. Two subtractions: named-minus-opened is the arm talking to nobody, opened-minus-acted is the milestone's whole subject. PreCompact stdout is the compaction's custom instructions (#3680), not a message to the model, so the readout does not say "you slipped" — it says which ids must be carried through, which is the one thing a summary can do about an unjudged finding. SILENT WHEN NOTHING HAPPENED, and the accusations are conditional on having members. "0 rules unresolved" on every compaction is how a readout teaches its reader to skip it. Traffic is still reported, because the static instructions already ask for it in prose; these lines are the measured version. scribe_record_outcome.sh is the third ledger's writer, matched on mcp__.*__rule_outcome and mirroring scribe_record_opened.sh: TMPDIR only, silent, exit 0 on every path. A PostToolUse hook that spoke would put a line after every rule_outcome call and give recording an outcome a cost. Also: check_plugin.py skipped the new hook for want of a smoke event, which would have left the newest of the three ledgers as the only one the plugin lane never runs. Added, mirroring its sibling. tests/test_precompact_hook.py now isolates TMPDIR — the hook reads session ledgers from there, so without isolation a test would see whatever this real session had accumulated. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 00:53:29 -04:00
bvandeusenandClaude Opus 5	fdfb2d94ac	feat(plugin): you altered the shape of something — here is everything that reads it (#4215) ... Milestone 419 step 4. Five of the milestone's seven misses were the same move: acting on the thing in hand without reading the contract around it. Lesson #4207 says so in words, and was written by its author hours before a structurally identical mistake, having been surfaced twice in the turns between. Text delivered at the moment of acting is too weak a carrier for a reflex that has to change what the act IS. This looks it up instead. Rule 33 one scope down: its checks are between layers, and the same question exists between a definition and its callers. THREE KINDS OF EXPOSED NAME, because a contract breaks three ways that look nothing alike in source — the defined symbol (a rename or removal), its parameter names (arity), and the quoted keys of its dict literals (the shape of what it returns). THE THIRD IS THE ONE A SIGNATURE-WATCHER MISSES, and it is in because of the miss that produced this step. Two commits ago `get_writepath_config` gained one dict key; three arms read that dict inside a fail-open `except`, every one silently became a no-op, and ten tests went red with nothing pointing at the cause. No signature changed. Run against that exact edit, the check now names tests/helpers.py — the actual root cause — among six files, before the write. TWO GATES, AND THE SECOND IS WHAT MAKES IT USABLE. A change to the exposed set is necessary but not sufficient: a definition nothing else references has no contract to break, so the readers lookup runs second and an empty result ends it silently. Body-only edits say nothing, a subject is named once per session, and the ledger lives in the swept directory under the `.ids` convention, so the existing compaction-clear guards cover it — checked against test_session_ledger_clear's own parsers rather than assumed. LOCAL AND SERVERLESS, like the duplicate-name arm beside it. It needs the working tree and nothing else; the server has no checkout, so this is the only place the question can be asked. It is a NUDGE: scribe_prior_art.sh still returns no permissionDecision, which is the operator's recorded decision that a recall aid may not stand in the way of a write. A test asserts that here as well as in test_write_path_trigger.py, because this is the arm most likely to tempt someone into making it a gate — it reports something that may already be broken. The `sym` half delegates to `scribe_defs` rather than repeating its patterns: those cover nine languages and have been corrected several times, and a second copy would inherit today's version and quietly stop agreeing with it (#3497). Verified by lifting the test file's own helpers and driving all 19 cases against the real shell over a fixture git repo. Two of my own errors were caught that way and are fixed: the fixtures were arriving as single lines because Python `repr` inside bash single quotes leaves `\n` as two characters (the extractor is line-oriented, so the tests would have gone green against input no editor can produce), and the no-readers case put its subject in a file that was not the excluded one, so it had a reader and tested the opposite of its name. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 00:43:29 -04:00
bvandeusenandClaude Opus 5	028d5218fc	fix(tests): the prompt arm has no act to hold, so it carries no checkpoint (#4214) ... CI 7126: 1 failed, 2227 passed — down from 14. The last one was mine, and a different mistake from the batch before it: I widened four assertions on the literal `{"context": "", "rule_ids": []}` by replacing the string, without checking which arm each test was calling. Three are the tool arm. The fourth, `test_the_prompt_arm_says_nothing_when_asked_nothing`, is not. The distinction is real rather than an omission, so the assertion goes back with it written down. The two ACT arms can hold a call because there is a composed act to hold. The prompt arm fires on the operator's message, before anything has been decided — there is nothing to put a rule in front of, and a checkpoint there would have to guess at an act that does not exist yet. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 00:32:23 -04:00
bvandeusenandClaude Opus 5	4e59af380a	fix(tests): the config stand-in fell behind the real one, and ten arms silently no-opped (#4214) ... CI 7124 Python tests: 14 failed. One root cause behind ten of them, and the failure was the exact one `tests/helpers.writepath_cfg`'s docstring already warns about in prose — while being unable to prevent this instance of it. Three arms read their numbers out of that config dict inside a fail-open `except`. A missing key raises where nobody sees it, so the arm becomes a silent no-op, indistinguishable from the arm working and finding nothing. The helper derives its keys from `retrieval_surfaces.SURFACES` precisely to stop that — and `checkpoint_threshold` is deliberately NOT a surface, because everything in that table is a floor/budget pair belonging to one query and the checkpoint runs none. The derivation therefore could not see it, the write-path rule arm died before `record_retrieval`, and ten tests went red at once. Fixed at the helper, from the module constant, so there is still exactly one literal and it lives in the product. And the guard the docstring claimed now exists: `test_the_config_stand_in_carries_every_key_the_real_one_does` compares the stand-in's key set against the real `get_writepath_config`, so the next key that is not a surface fails loudly here instead of quietly disabling an arm under test. `test_retrieval_surfaces`'s hand-written key list gains it for the same reason, spelled out in place. The other four were the contract widening itself: `checkpoint` is present on every return of the tool arm, including its early ones, so four assertions comparing the whole dict needed it. That key is deliberately always present — the two arms feed one shell reader where an absent key and an empty one are read the same, so the difference is invisible exactly where it would bite. Verified statically: every cfg in the suite now routes through `writepath_cfg` (test_write_path_trigger's local `_cfg` delegates to it), no hand-written config dict survives, and the real config's eight keys match the stand-in's. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 00:30:20 -04:00
bvandeusenandClaude Opus 5	91bc0fb01e	feat(plugin): a high-confidence rule is put in front of a command, not beside its result (#4214) ... Milestone 419 step 3, the pre-act checkpoint. Every rule surface in this plugin returns `additionalContext`, which Claude Code delivers alongside the tool RESULT — so the rule is read after the call is written and lands as commentary on a decision already made. That is the milestone's central finding, measured over a session with seven misses, three caught by the operator and none by this system. The action arm can now return a `deny` instead. The act does not run, the rule's text can be read before the call exists, and the remedy is one `get_rule` call after which the act may be re-submitted unchanged. Nothing reaches the operator: a deny is a message to the model. "CONSEQUENTIAL" IS DERIVED, NOT ENUMERATED. The obvious implementation lists act kinds — a write to product code, a schema change, a bulk classification, a merge. Every one of those is consequential because THIS operator wrote rules about it, and shipping that list is this instance's corpus hard-coded into the product (rule 115). So the corpus decides: an act is consequential when the install's own rules speak to it above the checkpoint bar. A fresh install with no rules never stops anything. FOUR CONDITIONS, EACH PREVENTING A DIFFERENT WRONG. Above the bar; a rule and never a preference (which claims no such force); the band's top hit only (the ranker's confidence claim attaches to its first element); and only a rule the session has NOT opened — `held` is observable from the get_rule PostToolUse hook (#4100), not self-report. WHY "NOT OPENED" RATHER THAN "NO OUTCOME RECORDED". An outcome can be satisfied with one cheap call asserting compliance without producing any, and a checkpoint dismissible that way manufactures exactly the compliance data step 2 was built to measure. Reading a rule cannot be faked in that direction: after `get_rule` the statement is in context, which is the whole of what was wanted. THE BAR IS MEASURED. `retrieval_telemetry(days=30)`: write_path_rule p90 0.7628 max 0.8817; pre_tool_rule p90 0.7373 max 0.8293. 0.80 is above p90 on both and below max on both, so it selects from the top decile of an already selective arm and is still reachable. It ships as a setting with a Settings card, because a cosine distance in one model's geometry over one corpus cannot transfer. TWO GUARDS ON THE WORST CASE: at most one hold per rule and five per session, so a mis-set floor degrades to a noisy session rather than one that cannot proceed. The ledger lives in the swept directory and is named `.ids`, so the existing compaction-clear guards cover it. WRITES ARE NOT HELD, AND THAT IS THE OPERATOR'S DECISION RATHER THAN MINE. `scribe_prior_art.sh` carries a tested property that it never returns a permissionDecision — a recall aid may not stand in the way of a write. Three of the milestone's seven misses were file edits and none are reachable from the command side, so there is a live argument for extending this; that argument is exactly why the boundary is now asserted by a test rather than left to memory. The write-path arm computes and returns the same block so the decision can be revisited with evidence; the hook ignores it, and a change of mind is a hook edit rather than a feature. Verified by lifting `checkpoint_for` and `_rule_band` out of source with `ast` and exercising the shipped functions over 17 populations, by running the ledger and deny envelope in bash (10 cases, including that a refused hold is not written and that a garbled rule id fails closed), and by scripts/check_plugin.py — which caught the unminted plugin version, 0300 -> 0426. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 00:26:54 -04:00
bvandeusenandClaude Opus 5	bb8013928f	feat(telemetry): the readout names rules that were opened and changed nothing (#4213) ... Milestone 419 step 2. Step 1 made an outcome recordable; this makes it readable. `retrieval_summary`'s rule block gains `applied`, `departed` and `distinct_rules_acted`, and `_compute_warnings` gains two codes. TWO CODES, NOT ONE WITH A ZERO IN IT. `read_and_unacted` reports rules that were opened and left no outcome, against the ones that did. It only fires once outcomes exist anywhere in the window, because a window with none cannot tell "every rule was ignored" from "nothing calls `rule_outcome` yet" — and on every install the day this ships, the truth is the second. Claiming the first there would be #3311's failure exactly: a statistic that could not vary being read as a fact about the corpus. The cold case gets its own code, `outcomes_never_recorded`, whose prose says in as many words that it does NOT mean the rules were ignored. `applied` AND `departed` ARE NOT SUMMED. A departure carries the reason the agent gave and is evidence about the RULE; an application is evidence about the agent. Folded together they would say only "an outcome exists", which is true of both and useful about neither. `distinct_rules_acted` counts either, because for the unacted arithmetic the distinction does not matter. An outcome is not a pull. The fold branches on OUTCOMES first and never routes an outcome through the surfaced/ambient split: `source` on an outcome row names the door the outcome came through, not a ranker, so the ambient distinction has nothing to say about it. An integration test holds that line — if an outcome leaked into the pull counters the silently-unchanged rule would vanish into a compliant-looking total, which is the confusion #4212 was opened to end. Verified by lifting the shipped `_compute_warnings` out of source with `ast` and exercising it against the six populations the new tests assert: cold instrument, warm instrument, departures-only, full compliance, nothing opened, and a failed read. The integration tests for the new counts run against real Postgres in CI — count(distinct) with an IN over an unconstrained column is a SQL shape a mock would agree with whatever it did, which is what #2663 was. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-21 00:13:45 -04:00
bvandeusenandClaude Opus 5	4ebf478575	fix(rules): the registration guard counts 24 now that rule_outcome exists ... Milestone 419's own subject, committed while building it. The module header of mcp/tools/rulebooks.py says the tool count "lives in the registration test, which fails when it drifts" — I read that line while adding the tool and did not act on it, which is a rule surfaced, read, and silently unchanged. The only reason it was caught is that the guard exists and CI ran it; nothing about my process would have found it. Worth stating plainly because the milestone is about exactly this class of miss, and step 1 shipped the record that would let a future session SEE it: a rule read and not followed is invisible unless something independent notices. Here the something was a test written by whoever last changed this count. Integration was already green on the previous run, so the migration, the backup round trip and the new `detail` column were never in question — this was one integer. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-20 23:58:27 -04:00
bvandeusenandClaude Opus 5	dfcb000719	feat(rules): a surfaced rule gets an outcome, not just a read (#4212) ... Milestone 419 step 1. `rule_usage_events` could say a rule was SURFACED and that it was PULLED. It could not say what happened next, so a rule that fires constantly and is always obeyed and a rule that fires constantly and is never obeyed left byte-identical telemetry. The second is far the more urgent and was the one the readout could not name — measured on a session where three of seven misses were caught by the operator and none by the system. Two new events, `applied` and `departed`, and a `detail` column carrying the why of a departure. No CHECK migration: `event` was created in 0094 as plain Text with no constraint, verified in the migration rather than assumed from the model, so rule 36 does not bite here — said in both places because the next person adding a value will reach for it. THE THIRD STATE IS DERIVED, AND THAT IS THE DESIGN. Read-and-silently- unchanged is the failure this milestone was opened on, and it cannot be reported: an agent that knew it was ignoring a rule would not be ignoring it. So nothing here asks. `applied` and `departed` are reported; the third state is a rule that was opened and left no trace. An `ignored` enum member would collect nothing while reading as though it had measured something, which is #3311's failure — a statistic that could not vary being taken for a finding. `detail` is a column rather than two more bare event strings because a departure stripped of its reason reads back as a miss, so the two states this exists to separate would collapse again one layer down, in the readout, where nobody would see it happen. Nullable: following a rule needs no argument, and an expensive event is one that stops being recorded. `outcome_state` is the single reading of the four states, taking the aggregate `usage_for_rules` already returns, so the badge, the readout and any later session summary cannot disagree about what "followed" means — the drift #3246 found across the rules system. A departure outranks an application: a rule both applied and argued with is a rule someone argued with, and the argument is the half worth surfacing. `rule_outcome` is the MCP door, classed as a WRITE. The read-only set tolerates getters that call record_pulled, but those are reads that leave a trace; this tool's entire effect is the row, and the row carries prose the agent authored. A read-scoped key that can put text in the operator's database is not read-scoped, whatever table it lands in. Backup carries `detail` on both sides. It is the one field here a fresh install cannot re-earn — counts come back by being used again, a stated reason exists once — and #4197 records that the column guard watches the export side only, so the round-trip test is the thing that would catch a one-sided add. Delivery is deliberately not settled here: how an agent gets prompted to record an outcome is step 3's subject, and the same record serves whichever answer that step reaches. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-20 23:56:05 -04:00
bvandeusenandClaude Opus 5	0fe19a8440	fix(ledger): a canon may hold a class and the to_dict beside it (#4220) ... The review surface shipped yesterday reported two canons on its first live day and both were sound. Coherence was "do all judged rows share a form", which #2844 failed at 37/62 = 0.597 for containing a model class and the to_dict the canon's own text says the class must carry, and #2849 failed at 4/7 for pairing sync loop-starters with the async ticks they schedule. A review surface whose whole output is noise is one that stops being read. The obvious repair is a trap, and there is now a test standing in front of it. Grouping by family and keeping a majority test makes the check BLIND: before #2844 was cleaned by hand it held 37 classes and 56 callables, which as families is 56/93 = 0.602 — a clean pass, and the 31 rows that had no business being there (Vue functions, route handlers, a dozen tests) would never have been reported at all. A looser bar in the same shape is worse than the bug. So the verdict is inverted. Instead of asking whether most rows agree, it asks how many rows the canon CANNOT ACCOUNT FOR: a row in the majority family is accounted for; a callable defined in a file that also holds a majority-family `type` row is a method of a member, not a foreign body; and strangers above a fifth of the readable rows make the canon incoherent. The majority vote abstains those methods, so a class's own serialisers cannot outvote the classes and turn the members into the strangers. Measured on the real ledger before it was written, which is why it is this rule and not a nudge to the share: clean #2844 has 0 strangers in 62, #2849 has 0 in 7, and polluted #2844 had 31 in 93 — the same 31 withdrawn by hand this morning, named exactly. The entry now carries `families`, the majority `family`, `attached`, `stranger_count`, `unattended`, and `strangers` — THE ROWS THAT DO NOT FIT, replacing a sample of the first twelve members. The reader's question is which rows are wrong, and a sample of the agreeing majority cannot answer it. `unattended` is the discriminator between a check that is too strict and a ledger full of junk: both canons flagged on day one were entirely audit-judged, and nothing showed that without opening each one. Scoped to the review surface. `canon_form` still answers at the precise form level for stamping and divergence, where a sync helper beside an async canon is a fair question; nothing here changes what the ledger writes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-20 23:39:01 -04:00
bvandeusenandClaude Opus 5	e87bcfa48c	fix(guidance): the index had two characters of headroom, and I spent 391 ... CI 7098: unit tests red, everything else green. `_INSTRUCTIONS` was 2439 against a 2000 budget. WHAT I DID NOT CHECK. That block is capped because Claude Code injects only the first ~2,048 characters of a server's instructions and cuts the rest mid-word (#2562, observed live — a 20k version delivered ~10% of itself and the Systems guidance never reached a session). The cap is stated in a comment directly above the literal I edited. It was at 1998/2000 before this batch: a shared, nearly-exhausted resource, and I added a six-line entry to it. THE JUDGE LINE STAYS, and paying for it is the decision rather than dropping it. A client with no Agent Skills support receives this index and nothing else, so of everything here, "you are the judge of record" is among the least safe to leave past the fold — an agent that never learns it defers every call to an operator who was never going to make them. So the line is earned by compressing prose AROUND the existing markers, not by removing anyone's entry: RULES loses a clause, RECORD and REPORT lose trailing restatement, PLAN drops a sentence the two markers already imply, and the opening paragraph tightens. Every index marker the ownership registry requires survives verbatim — that is what test_the_index_names_each_reflex_it_points_at checks, and it passes. Back to 1998/2000: the same headroom as before, with one more reflex indexed. The next addition pays the same way. Three guidance modules run green locally (21 tests) — they read files and need no database, so this one did not have to go to CI to be known. Plugin version re-minted; the previous mint is on a commit that never went green. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-20 23:00:14 -04:00
bvandeusenandClaude Opus 5	76bf21633e	feat(guidance): the agent is the judge — stated in the product, not in a rule ... I recorded this as project rule 174 first. That was wrong twice over, and the second reason is the one that matters. RULE 119 SAYS THIS EXACTLY: guidance about how an agent should behave with Scribe belongs in `_INSTRUCTIONS`, `plugin/skills/*` or the adapter's static context, never in the corpus. I read 119 while writing the rule, decided it was "about authority rather than about using Scribe", and wrote it anyway — which is the reasoning preference 29 exists to catch, performed in full. THE REASON THAT MATTERS: a rule in the corpus is true on ONE install. If the agent being the judge is how Scribe works, every install gets it or none does. Baked in, it ships. As a rule it was one operator's private note about a product stance. WHAT IT SAYS. The agent is the judge of record for the work — what a shape is, whether a finding holds, whether something is done. Surfacing a finding for the operator to rule on is the judgment NOT made, however well written up: it reads as diligence and functions as a backlog. Escalate the acts that are genuinely theirs — their money, their infrastructure, anything hard to reverse or facing outward — and keep the decisions. A hard call is still yours; an irreversible act is still theirs. And the half that keeps this from becoming the previous defect: JUDGING IS ATTENDED. An agent reading evidence and recording why is judgment; a threshold or a sweep reclassifying in bulk with nobody reading is the thing that fills a ledger with confident nonsense (#4208, and Portal's 35 rows). When the fix for bad unattended writes is another unattended write, stop. THE PRODUCT WAS TEACHING THE OPPOSITE. reporting-back's Finding row read "Symptom · Cause · Size of the fix · **Offer to fix it**". So the behaviour I was corrected for is the behaviour the skill prescribed — which is the better argument for fixing it here than any rule could be. Three surfaces, per 119 and the ownership registry (#4027): `_INSTRUCTIONS` gets a one-line JUDGE index entry; using-scribe owns the authority and the attended/unattended distinction; reporting-back owns the report shape. Two topics rather than one, registered separately in test_guidance_ownership so trimming one cannot quietly take the other. Plugin version minted — skills only reach a session when the manifest moves (#2209). Rule 174 deleted (trash 074434a2, recoverable). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-20 22:54:19 -04:00
bvandeusenandClaude Opus 5	2be17828a9	fix(ledger): live_rows_for called access with nothing in scope (#4208) ... Lint caught an F821 that would have been a NameError the first time `stamps_to_review` was called: `access` is imported locally inside each of the seven functions in this module that need it — services/access reaches back here, so a module-level import closes a cycle — and the new function used it without one. I wrote the function by pattern-matching its neighbours and did not check what those neighbours do to make themselves work. Same shape as the tuple unpack two commits ago (#4207): the mistake is not in the logic I was thinking about, it is in the surrounding contract I did not read. Unit and integration were both green on the failing run (7095); only lint was red. Worth recording because the lane that caught it is the cheapest one and I had read its command as covering tests — `ruff check src/ scripts/` does not look at tests/ at all, so a clean test suite says nothing about it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-20 22:33:22 -04:00
bvandeusenandClaude Opus 5	400253d039	feat(ledger): the ledger can say "these look wrong" without acting on it (#4208) ... THE HALF THAT WAS MISSING. #4204 put a floor under what the write-path hook may assert. A floor only guards new writes; every row already stored stands (lesson #4202). Measured after that fix shipped: Portal carried 32 rows under one canon and 3 under another, all stamped on scores of 0.69-0.77 — below the 0.80 floor, so none of them could be written today, and all of them were still there. Scribe's own ledger carries 334 under #2860. `stamps_to_review` reports two things and changes nothing: weak — rows the hook stamped on a resemblance below the current floor, each with its score, signature and derived form. incoherent — canons whose own judged rows do not agree on a form. A canon claims some shapes are the same sort of thing; when its members are a class, three getters and a dozen tests, that claim has stopped being true and every base-rate reading built on it is reading noise. `canon_form` already made such a canon fall silent — nothing made it VISIBLE. IT DELIBERATELY CANNOT FIX ANYTHING, and that is the design, not an omission. The first version of this commit was an automatic sweep that reset rows by score. That is the original defect pointed the other way: what harmed the ledger was not one wrong score, it was a machine recording permanent classifications unattended. Un-recording them unattended is the same act with a wider blast radius. An agent reads the evidence, judges, and records the judgment under its own name through `classify_shapes`. `test_the_service_carries_no_machinery_for_bulk_withdrawal` asserts that structurally, so the next person to reach for an auto-retire has the argument again on purpose rather than in a diff nobody reads. A JUDGMENT IS NEVER LISTED AS WEAK, whatever its age. This is the measured correction to an assumption I nearly shipped: of Scribe's 334 rows under #2860, 302 are in `services/` — the canon's own home — and the ones sampled there are `classified_by="audit"` with no score at all. The legitimate bulk of that canon was never scored; it was judged by an agent in batch. Listing those as weak would invite an agent to withdraw the only real judgments in the ledger. An agent's decision is a different KIND of evidence, not a worse one. THE SCORE NOW HAS A PARSER. It lived only inside a prose sentence, so nothing could ask how strong the evidence for a row was without re-deriving it — which is how 32 rows sat unexamined for nineteen days. Format and reader are one constant apart (`_RESEMBLE_REASON` / `stamp_score`), with a round-trip test and a test pinned to reason strings taken verbatim from the two poisoned ledgers. `live_rows_for` is `live_rows` behind the project read gate, for callers that arrive from outside rather than from a job that already knows who is asking. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-20 22:28:12 -04:00
bvandeusenandClaude Opus 5	d5b46ffc45	fix(ledger): the in-play tuple widened and one consumer kept reading four (#4204) ... [s_id for rank, _at, s_id, _why in bucket if rank == 2] ValueError: too many values to unpack (expected 4, got 5) `in_play` gained the canon's form as a fifth element so the stamp could be decided per shape rather than per file. The `record_uses` call eighty lines below still destructured four, and every stamp that reached it raised. Both integration failures on runs 7090 and 7091 are this one line — `test_write_path_stamp_is_evidence_that_yields_to_judgment` and `test_a_brand_new_shape_gets_a_provisional_row_the_sync_settles`. Now indexed rather than destructured, matching the candidate scan above it, so the next widening cannot break it positionally. WHY THE UNIT LANE STAYED GREEN THROUGH TWO PUSHES. `record_uses` is only reached once a stamp is actually written, which needs a real snippet, a real ledger row and the write ACL — so no unit test crosses that line. 139 local assertions and the whole unit suite passed on code that raised on every successful stamp. The integration lane was the only thing that could say so, which is the case for it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-20 21:53:53 -04:00
bvandeusenandClaude Opus 5	a4883c8ac1	fix(ledger): divergence asks at family level — the first gate was inverted (#4204) ... CI run 7090 caught this; the unit suite could not. Integration job 25763 — `test_a_second_confirm_dialog_is_detected_and_named`, the acceptance case of milestone #2793. WHAT I GOT WRONG. The previous commit gated BOTH halves of the ledger on `forms_agree`. That is right for stamping and backwards for divergence, because the two assert opposite things: STAMPING says "this IS that canon". Agreement in form is evidence FOR the claim, so demanding it is correct. DIVERGENCE says "this is NOT the canon that dominates here — did you mean to?" A form MISMATCH is the PREMISE of that prompt. Requiring the candidate to match the canon silences the check precisely where it belongs. So #2793's case stopped firing: a hand-rolled sync `confirmDanger` in a directory where an async confirm helper is canon read as `fn` against `async-fn`, disagreed, and was dropped. `flag_divergence` returned 0 where the test demands 1, and the write-time check returned nothing where it must name the canon. That is a real flag the milestone exists to produce, and my change removed it. THE FIX. Divergence now gates at FAMILY level — callable {fn, async-fn}, type, value, css — and only on contradiction. A sync function beside an async one is still a fair question. A frozen dataclass told to build from an async service function is not a question at all. WHAT THIS DOES NOT FIX, asserted rather than commented so it fails the day it changes (`test_how_many_of_the_five_the_divergence_gate_actually_silences`): of #4204's five false prompts this silences ONE. `Point` is a type against a callable canon. `_p`, `get_point`, `is_registered` and `sources_expected_to_emit` are callables like the canon and still ask — and at the signature level they are indistinguishable from the #2793 case above, so nothing readable here can separate them. That needs #4204 option 2 (widen `kind` past `css | sym`) or a comparison of meaning rather than form. The stamping half — `_RESEMBLE_MIN` 0.80 and the graded burden — is unchanged and unaffected by this failure. It is also the half that matters more: loose stamping is what manufactures the density the divergence check reads as authority. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-20 21:26:12 -04:00
bvandeusenandClaude Opus 5	947203fa44	fix(ledger): a canon is only urged on a shape that could be it (#4204) ... Two halves of one defect, found while writing #3431 and measured on a second project. THE DIVERGENCE CHECK WAS A BASE RATE. `dominant_canon` answers "what is most common in this directory" and never "is this that" — the candidate's signature was not examined at all. With `kind` carrying only `css | sym`, a frozen dataclass, a module constant, a sync predicate, a class and an async service function are all siblings, so the prior was not merely the best signal, it was the only one. Writing a registry module of pure helpers produced five prompts to build them from the `async_session` service canon. THE AUTO-STAMP HAD NO FLOOR. `elif sid in resembles` took any score at all: 0.69 asserted as confidently as 0.95, and the number went into the reason line without ever being compared to anything. Worse, the score is computed against the WHOLE PAYLOAD, so one number spoke for every symbol in the file. On Portal that recorded `class SessionAbsent`, `def build_channel`, `async def attach` and a dozen test functions as instances of one snippet — 17 rows under #3283, which then made that directory "canon-dense" and started instructing every later writer in it. The two compound: loose stamping manufactures the density the divergence check reads as authority. Both are fixed by one primitive. `shape_form` derives a coarse form — css / type / async-fn / fn / binding — from the signature, on READ. `kind` is part of the row identity, so widening that column needs a migration and a re-extract (#4204 option 2, still the principled fix); deriving costs nothing and is reversible. Every caller asks `shape_form`, so the day the column carries the answer it returns that. THE BURDEN SCALES WITH THE EVIDENCE, and getting this wrong was the first version. A by-name reference — the payload names the canon's symbol — is strong and needs only the absence of contradiction; demanding positive agreement there silenced it whenever a shape's definition was not in the payload (an Edit rather than a Write), turning strong evidence into none for a reason unrelated to the code. A resemblance score is weak and must positively agree. `canon_form` reads the form a canon's own judged rows agree on, and returns unknown when they disagree. That makes the halves cooperate: a canon already poisoned by loose stamping — Portal's #3283 — falls silent instead of flagging anyone else. `forms_agree` requires BOTH sides known, so an unreadable signature makes the checks quieter rather than more confident. `_RESEMBLE_MIN` is 0.80 rather than the retrieval floors near 0.70: those decide whether to SHOW a record, where being wrong costs a glance; this decides whether to RECORD a claim unattended, where being wrong misinstructs everyone who writes there after. Caught by the tests, not by review: a first pass required `const`/`let`/`var` before a binding, so every Python module constant read as unreadable and a whole form was silently excluded from both checks. Not addressed: rows already carrying a wrong snippet_id are not undone by a guard at the point of classification (lesson #4202). Portal's 17 keep producing dominance until something re-judges them. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01821k5B3Ysecp9fNYs92Kuy	2026-09-20 21:16:51 -04:00