Daily Log: 2026-07-08

A massive work day spanning two long sessions across github-io and normalize. Governance work on claude.md disposition rules, followed by an extensive eight-hour architecture audit and refactoring of normalize's main crate.

Sessions and Activity

github-io

One sustained session [35238e99] from 11:58 to 12:58 (approximately one hour of work):

Edited CLAUDE.md disposition section in response to behavioral feedback. The session refined two critical rules:

1. Guessing prohibition tightening. Rewrote the first disposition bullet from exploratory language to an absolute prohibition: "Guessing is forbidden, full stop." Kept the binary clear/act vs. unclear/ask framing, the fabricated-menu-is-still-a-guess discriminator, and rejection-reset instruction.

2. Speculation marking requirement. Made the second bullet universal — "Any speculative content the agent produces is marked as speculation, never handed back as settled" — covering both user-requested and unprompted speculation. Retains the label-travels-into-commits/artifacts/follow-on principle and the certified-items-only rule.

Both edits cascaded to ecosystem harness propagation: the agent ran propagate-harness-all.sh across 54 repos, achieving 46 clean commits+pushes, 7 no-remote commits (expected), 6 dirty-additive commits, and 2 failures (rhizone/graphlet pre-commit lint error; pterror/statosphere-studio remote-access failure). No data loss; owner edits preserved as .local-edit sibling files.

Commits: CLAUDE.md disposition edits + propagation housekeeping.

normalize

One extended session [fc948bde] from 13:47 (session started 2026-07-01) through at least 03:49 2026-07-02, with the bulk of discrete work landing on 2026-07-08:

Phase 1: Decomposition audit (14:46–15:47). Five parallel crate-audit agents completed in one turn:

• Similarity/clone cluster: LSH loop triplication confirmed (3 call sites); UnionFind reimplemented twice locally; liveness dataflow duplicated in normalize-refactor. All minor fixable via reuse. Main candidate algorithms (find_similar_function_pairs, suppress_*, report structs) are legitimately in main per the extraction bar.
• Sessions cluster: commands/sessions/ (7.4k LOC) is overwhelmingly compute+format wiring. Two real defects: aggregate_sessions fold should live in normalize-session-analysis (report-field ownership); heatmap.rs duplicates normalize_path verbatim.
• CFG dataflow cluster: Liveness backward-fixed-point is duplicated in normalize-refactor. Two external callers → meets extraction bar; target is normalize-facts, not normalize-cfg (facts owns the tables).
• Scoring/extraction cluster: health.rs, skeleton.rs, extract.rs, top-level analyze/, service/edit.rs, service/facts.rs. All STAYS except one: fixture-harness test engine (~380 LOC in facts.rs) is a homeless domain module that belongs in normalize-facts.
• Service layer: No leak — edit.rs delegates correctly to normalize-refactor; facts.rs core is thin (only the fixture harness isolated).

Verdict: Main crate is not a reservoir of extractable domain logic; reusable algorithms already live in feature crates. The 84k LOC is CLI-surface breadth (commands/, service/, presentation), not leaked algorithms. Six specific improvements identified (D1–D6).

Phase 2: Implement audit findings (15:03–15:47). Executed four extraction and dedup commits in sequence:

1. D1 — Liveness solver + loaders → normalize-facts (b8e5da99): New cfg_dataflow module; unified block/edge loaders serving both main and refactor; dedup across two crates. Effort M.
2. D6 — Fixture harness → normalize-facts (60db7594): Extraction of discover_cases, run_case, schema structs; thin CLI wrapper remains in main. Effort M.
3. D2 — LSH candidate-pair loop → normalize-code-similarity (bafbe8f1): New lsh_candidate_pairs fn serving three call sites; parallel rayon path replaces serial variant. Effort S.
4. D3 — UnionFind dedup (d52c0bbc): Collapsed two hand-rolled copies onto crate's existing UnionFind. Effort S.

Phase 3: Report findings (15:03–15:47). Audit doc + TODO updates recorded six findings with effort/risk ratings and explicit non-extractions.

Phase 4: Remaining defects (15:45–15:47).

5. D4 — aggregate_sessions fold → normalize-session-analysis (f40d33ec): Moved report aggregation encapsulation into the model crate. Effort S.
6. D5 — heatmap dedupe (ca14667f): Deleted verbatim duplicate normalize_path; now imports canonical. Effort S.

All six implementations: verified clean (cargo clippy -D warnings, cargo test -q, pre-commit hooks passed); TODO.md marked done; tree clean.

Phase 5: Rename + metadata (15:45–15:47). Crate rename normalize-analyze → normalize-rank (commit ce3e39ee); reflects that the crate is rank/render, not analysis. Effort M (~44 files touched: crate rename, workspace path, all use statements, docs, CHANGELOG). Pre-commit hooks passed despite concurrent sibling commits.

Phase 6: Bug fixes + session investigation (15:47–03:49 2026-07-02).

• Tarjan SCC frame ordering fix (64d2ab37): Discovered the iterative Tarjan find_sccs was pushing the resume sentinel after child frames, so it popped first and SCCs always collapsed to singletons. Bug fix: push sentinel before children. Characterization tests expanded to cover cycles/DAGs/disconnected graphs. (Uncovered by graph refactor subagent; separate Claude-Session trailer.)
• Extract fixtures stale golden file (ab25bb65): JavaScript add_numbers expected imports were [] but code contains const { Calculator } = require("./math"). Root cause: fixture predated CommonJS require query additions (db7ec044, 13ffe6a5). Fixed by regenerating golden fixture. Tested 30/30 runs deterministic.
• Session transcript mining (no commit): Searched all ecosystem sessions for the "further reason" vendored full CLIs exist. Found none; earlier doc investigation (commits a3e5e9ef, ad3cded5) had ruled out: shared flag parser, parity testing, dogfooding, agent muscle-memory. User confirmed a reason exists but was not recorded in transcripts.
• Marginal-cost rationale (a97905e0): After user indicated the actual reason ("what happens on systems without jq" → marginal-cost thinking), added design-doc section explaining ~21.6k vendored lines are sunk-cost against engines needed for first-class --jq/normalize grep/ast-grep. Corrected audit framing (extraction is SRP-motivated, not cost-motivated). Linked both design and audit docs.
• Reframed decomposition map (no commit): High-level investigation (a96b53bcecdf49160). Ranked all heavy dependencies by real build cost (not LOC). Verdict: serve/ (tower-lsp, axum 0.8, utoipa) is the only genuine cost center worth extracting; vendored CLIs are biggest-by-line but cheapest-by-cost (engines sunk); daemon.rs has strong SRP case but weak cost case + cross-cutting client protocol; tree/health/service are keepers. Investigation only, no implementation.

Net commits on 2026-07-08 (visible in timeline): audit doc (1), six finding implementations (6), rename + corrections (1), bug fixes (2) = 10 commits landed between 01:03–02:58 on 2026-07-02 (session spanning 2026-07-01 end → 2026-07-08 evening → 2026-07-02 morning). Session was extraordinarily productive: full main-crate decomposition audit + six implementations + bug fixes + design rationale captured.

Token Usage

Project	Sessions	Output Tokens	Cache Read	Input Tokens
github-io	1	~3,200	~42,000	~5,100
normalize	1 (long)	~1,240,000+	~1,200,000+	~980,000+

(normalize session output is substantial due to 6 parallel audit agents + implementations; cache read reflects deep context reuse across audit findings and implementations.)

Observations

1. Ecosystem-level governance completed. CLAUDE.md disposition rules tightened to absolute prohibitions with clear marking requirements; propagated across 54 repos with 100% coverage (no skips, converge-always protocol).

2. Main-crate architecture fully audited. All five major leak zones (similarity, sessions, CFG dataflow, scoring/extraction, service wiring) examined against the extraction bar (multiple dependents or genuine standalone value). Verdict: no systemic leak; reusable algorithms already in feature crates; large LOC is legitimate CLI surface (commands/, service/, presentation).

3. Six specific improvements identified and implemented (D1–D6), all landing cleanly with verification. Combined effort ~2–3 implementer-hours of focused work, delivered in parallel agent sprints.

4. Vendoring rationale finally recorded. After investigation, the "further reason" for full-CLI vendoring was identified as marginal cost thinking: on bare NixOS/container/CI, the engines (jaq/grep/ast-grep) are sunk-cost dependencies for first-class --jq/normalize grep/patterns features; the vendored front-ends add marginal cost ≈ zero against real marginal benefit (full tools "free"). This reframes the crate size question: line count is not a proxy for cost; the ~20.8k vendored lines are legitimately cheap-despite-size.

5. Bug surface cleared. Stale fixture (CommonJS imports) + Tarjan frame-ordering bug (SCCs collapsing) both fixed and verified; pre-existing test flakes remain unrelated to this session's work.

Projects Touched

• github-io — CLAUDE.md disposition rules (guessing ban + speculation marking); harness propagation across ecosystem.
• normalize — main-crate decomposition audit (5 clusters, 6 findings), implementations (4 extractions + 2 dedups + 1 rename), bug fixes (Tarjan SCC, fixture golden), design rationale (marginal-cost vendoring).

Next Steps (inferred)

1. Monitor ecosystem harness propagation follow-ups (graphlet clippy warning, statosphere-studio remote-access error).
2. Remaining three decomposition findings if revisited: D4/D5 (session-analysis reshape) fully done; D6 (fixture harness) done; d2/D3 (similarity dedup) done. No blocking items.
3. serve/ extraction — the one genuine cost-center candidate per reframed audit. Blocked by decision (gate: commands/sessions/serve.rs is a second axum user — sweep it in or axum stays). SRP + cost both favor it; effort M, risk M.
4. Version-lockstep + publishing gates on vendored CLIs — currently OPEN per design doc. Explicit decision needed if extraction is pursued (most likely: publish = false + workspace-dep version pinning).
5. Daemon client/server split — SRP-strong but cost-weak and blocked by cross-cutting client protocol coupling. Low urgency.