Ledger follow-ups from the shape audit (milestone 294: #2868–#2874) #122

Merged

bvandeusen merged 12 commits from dev into main 2026-08-21 15:24:04 -04:00

Conversation 0 Commits 12 Files Changed 22

+1202 -75

bvandeusen commented 2026-08-21 15:23:43 -04:00

Owner

Copy Link

Copy Source

What the milestone-296 audit taught about the mechanism, applied:

• #2871 proposer v3 — sym bases gated by language family; reference basis skips generic verbs; semantic held to the shape's own project; ruleset bump re-examines standing proposals.
• #2868 bulk surfaces — list_shapes(compact=True); classify_shapes_by_rule (one judgment over a directory + glob, unjudged rows only unless include_judged).
• #2869 scoped bucket — Vue scoped <style> rules and <script setup> functions are stamped scoped (mechanical) by the sync; exempt stays a human judgment; the machine still sees them. Plugin 0.1.37 (skill doc).
• #2872 derive ranking — body-identical groups first, wider file spread first; CSS fingerprints are declarations only.
• #2873 binding ref — repo_bindings.ref (migration 0082); bind_repo(..., ref=); the refresh reads the binding's branch.
• #2874 — reason_code catalogue (migration 0083); case-insensitive repo filter in both location dialects; coverage line names the top canon queue and top copy.
• #2870 uses edges — code_shape_uses (migration 0084): consumption separate from conformance; classify/sweep take uses=; hook and proposer write edges; list_shapes(uses=N); consumer map gains uses. Backup v9 carries it.

Every push CI-green on dev (last: run 4179). Migrations 0082–0084 run on deploy.

🤖 Generated with Claude Code

What the milestone-296 audit taught about the mechanism, applied: - **#2871 proposer v3** — sym bases gated by language family; reference basis skips generic verbs; semantic held to the shape's own project; ruleset bump re-examines standing proposals. - **#2868 bulk surfaces** — `list_shapes(compact=True)`; `classify_shapes_by_rule` (one judgment over a directory + glob, unjudged rows only unless `include_judged`). - **#2869 `scoped` bucket** — Vue scoped `<style>` rules and `<script setup>` functions are stamped `scoped` (mechanical) by the sync; `exempt` stays a human judgment; the machine still sees them. Plugin 0.1.37 (skill doc). - **#2872 derive ranking** — body-identical groups first, wider file spread first; CSS fingerprints are declarations only. - **#2873 binding ref** — `repo_bindings.ref` (migration 0082); `bind_repo(..., ref=)`; the refresh reads the binding's branch. - **#2874** — `reason_code` catalogue (migration 0083); case-insensitive repo filter in both location dialects; coverage line names the top canon queue and top copy. - **#2870 uses edges** — `code_shape_uses` (migration 0084): consumption separate from conformance; classify/sweep take `uses=`; hook and proposer write edges; `list_shapes(uses=N)`; consumer map gains `uses`. Backup v9 carries it. Every push CI-green on dev (last: run 4179). Migrations 0082–0084 run on deploy. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

bvandeusen added 12 commits 2026-08-21 15:23:43 -04:00

fix(ledger): proposer v3 — sym bases gated by language family, reference skips generic verbs, semantic held to the shape's own project (#2871, milestone 294) ... 3a4031d7f8

The 2026-08 audit examined 407 proposals. Every cross-language hit was wrong:
the Python MCP tool-module canon (symbol `register`) was offered for each auth
view's handleSubmit (it calls authStore.register()) and for the TS auth store's
own `register`; Minstrel/Forge TS canon matched Python bodies by resemblance.
Every cross-project semantic proposal was noise.

- Canon carries the snippet's language; match_canon skips a sym canon whose
  family (py / js / css / sh / sql, by language ↔ by path extension) differs
  from the shape's. Unknown on either side = no gate.
- The reference basis ignores a stoplist of generic verbs (register, load,
  save, get, …): a bare mention is not a call site of THIS canon; the symbol
  basis still catches a second definition, and the call-site relation moves
  to `uses` edges with #2870.
- The semantic arm only reaches canon in the shape's own project and family;
  symbol/text still reach family canon elsewhere (note 2786).
- _PROPOSER_VERSION 2 → 3 so standing proposals re-examine on the next refresh.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

feat(ledger): audit surfaces — list_shapes(compact=True) and classify_shapes_by_rule, the sweep form of a judgment (#2868, milestone 294) ... 9abc4443fb

The 2026-08 audit judged 3,427 rows in 14 hand-driven batches through a raw
MCP client because a list_shapes page overflowed the tool budget and every
row had to be sent back one by one. Now:

- list_shapes(compact=True): path · symbol · kind · status · signature, plus
  snippet_id / by / proposal / diverges_from / recheck only when set. A full
  500-row page fits. CodeShape.to_compact() is the row shape.
- classify_shapes_by_rule(project_id, path, status, pattern=, kind=,
  snippet_id=, reason=, via=, include_judged=): ONE judgment over every
  unclassified live row under a directory whose symbol matches a glob;
  judged rows are untouched unless include_judged; canonical is refused;
  same gates as the row form; one transaction; returns count + sample.
  shape_ledger.classify_shapes_where / rule_matches (pure) carry it.

Tests: compact row pinned, rule_matches directory/glob/kind semantics, the
tool mount, and an integration sweep (unclassified-only, include_judged,
gates).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

feat(ledger): the scoped bucket — by-construction one-offs are stamped by the sync, not judged by a person (#2869, milestone 294) ... 1ab614bfbe

The 2026-08 audit left 77% of Scribe's ledger `exempt`, most of it a Vue
component's scoped <style> rules and <script setup> functions — one-offs by
construction (unreachable from any other file) that add nothing when judged
one by one and bury the rows a person should look at.

- coverage: Definition carries its line; scoped_definitions() names, per
  .vue file, every sym and every css rule inside <style scoped>; ArchiveShape
  carries the flag.
- sync: such rows are stamped status=scoped / classified_by=mechanical with
  the by-construction reason (history event recorded); un-stamped back to
  unclassified if a later tree makes them ordinary; a judgment overrides.
- The machine still sees them: proposer, derive grouping, divergence, hook
  evidence, canonical stamping and classify_shapes_by_rule's default all
  treat unclassified + scoped as the unjudged set (_MECHANICAL_TODO). Only
  the human todo (status=unclassified) and largest_gaps exclude them.
- accounting counts `scoped`; coverage line and the project card legend show
  it; SHAPE_STATUSES gains it (no DB CHECK on status — no migration).
- shape-accounting skill documents the bucket; plugin 0.1.37.

Operator decision on #2869 (2026-08-21): keep extracting everything, stamp
mechanically, keep `exempt` a human judgment.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

test(ledger): the divergence acceptance case uses TS canon — proposer v3 gates sym bases by language family (#2871) ... 1126bbe84f

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

feat(ledger): derive readout ranks body-identical groups first; CSS fingerprints are declarations, not selectors (#2872, milestone 294) ... 57d68c9355

The 2026-08 audit consolidated identical bodies under different names and
files (five auth views' CSS, two Workspace formatDate()s, four modal blocks)
while the derive readout led with name groups (to_dict ×25, main ×5, load ×6)
that were convention or coincidence.

- proposal_summary ranks dup:<sha> groups above name groups, wider file spread
  first, and carries `files`; scoped rows (#2869) are in the readout, since
  that is where view-level copies live.
- extract_definitions fingerprints a CSS rule by its declarations — the row
  identity already carries the selector — so .closed-msg / .error-block /
  .success-msg with one body are one dup group. One-time effect: judged css
  rows whose stored fingerprint predates this may show a recheck on the next
  refresh (the judgment stands; re-confirm).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

feat(ledger): a repo binding names the branch its ledger follows — bind_repo(ref=) (#2873, milestone 294) ... 1209e1c2d9

Project 2 is bound to main, so every consolidation of the 2026-08 audit was
invisible to the ledger until the dev→main merge; the operator works on dev
(rule 1). repo_bindings.ref (migration 0082, nullable) is the branch the
coverage refresh reads; NULL keeps the forge default branch. set_binding takes
ref (name sets, "" clears, None leaves standing); bindings_for_project feeds
the refresh; bind_repo exposes ref ("-" clears). to_dict carries it.

Operator decision on #2873 (2026-08-21): per-binding ref, chosen at bind time,
default the repo default branch.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

test(ledger): derive summary expectation follows #2872 — dup group before name group ... d01201539b

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

feat(ledger): reason codes, case-insensitive repo filter, next action on the coverage line (#2874, milestone 294) ... 1a8e5787e8

- code_shapes.reason_code (migration 0083): an optional code from a fixed
  catalogue (scoped-css, one-off-handler, test-helper, convention-plumbing,
  pure-helper, generated, script, typed-record) beside the prose reason, so
  the ledger can be filtered/aggregated by kind of one-off; validated in
  classify_shapes and classify_shapes_by_rule; on to_dict/to_compact.
- Snippet location lookups match repo case-insensitively in both dialects
  (location_matches / location_jsonpath via like_regex flag "i") — "Scribe"
  vs "FabledScribe" vs "fabledscribe" recorded free-form hid half the canon
  from list_snippets(repo=, path=).
- coverage line names the next action: "top canon #N ×k" (biggest proposal
  queue) and "top copy <label> ×files" (widest body-identical group).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

test(ledger): derive label order follows #2872; binding-ref test imports compute_coverage ... 3849c6fff3

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

test(ledger): derive group sizes follow the #2872 order ... bfe5a461b4

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

feat(ledger): uses edges — consumption is its own relation, conformance keeps one snippet_id (#2870, milestone 294) ... d4c7b0e48d

A shape can follow one convention canon AND call several helper canons; the
row's single snippet_id made the 2026-08 audit pick (hash_token won, the
service-function convention lost), and hook evidence — pulled a snippet, then
wrote code naming it — was stamped as instance when it is a uses fact.

- code_shape_uses (migration 0084): shape → snippet, basis, evidence; unique
  per pair; cascades with both ends. USE_BASES: reference | hook | agent |
  audit | import. A judgment-grade basis overwrites a mechanical one, never
  the reverse.
- classify_shapes items and classify_shapes_by_rule take uses=[snippet ids]
  (targets validated like snippet_id; all-or-nothing).
- The write-path hook writes a uses edge for every pulled canon the payload
  names (the instance stamp is unchanged); the proposer writes a uses edge
  for every canon a body names (reference_canons: kind + language family +
  stoplist, same rules as the reference basis) — the mechanical form of
  "auto-confirm own-import references" deferred from #2871.
- list_shapes(uses=N) lists the consumers of a canon; get_snippet's consumer
  map gains `uses` beside instances/variants.

Operator decision on #2870 (2026-08-21): keep one snippet_id, add uses edges.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

feat(backup): code_shape_uses travels (v9); consumer-map test expects uses (#2870) ... 6a0f8ad328

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

bvandeusen merged commit f0c915a6bc into main 2026-08-21 15:24:04 -04:00

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

No items

No labels

Milestone

No items

No Milestone

Projects

Clear projects

No projects

Assignees

Clear assignees

renovate-bot bvandeusen

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: bvandeusen/FabledScribe#122