Backlog processing strategy: volume without compromising quality
Goal
Process the ~80 open issues without compromising code quality, performance, functionality, or
documentation accuracy, using the available hardware (M5 MacBook Pro Max, Mac Mini, Linux x86
with SIMD, minimal EC2 for SVE2).
State snapshot (2026-07-18)
~80 open issues clustering into: jq semantics bugs (jq: array slice .[a:b] returns a stream of elements instead of a single sub-array #154 –jq: integer literals larger than i64 fail to parse instead of becoming floats #166 ), YAML semantics bugs
(YAML: block scalars type-coerce on the streaming path (|- 123 becomes a number) #168 –YAML: duplicate mapping keys are first-wins (YAML 1.2 / yq take last or error) #174 , yaml: scalar type resolution diverges from the 1.2 core schema, and is duplicated across 5 sites #226 ), CLI bugs (CLI: yq -I 0 (compact YAML identity) quotes scalars and drops --- document separators #175 –CLI: dsv --header is effectively a no-op and cannot be disabled #180 , yq: -I 0 changes document values, not just formatting #222 ), arch-specific SIMD bugs (yaml/simd/x86: signed compare misreads UTF-8 bytes as control chars, panicking yq on non-ASCII #230 , yaml: x86 without AVX2 silently misparses YAML (classify_yaml_chars classifies 16 bytes, parser skips 32) #231 , YAML to_json() drops multibyte UTF-8 on x86 (signed compare in find_json_escape) #150 ,
NEON JSON classifier over-matches boundary bytes (differential vs x86/scalar on invalid JSON) #186 , DSV BMI2/SVE2 quote-mask carry is wrong when a quote lands on bit 63 (silent row/field corruption) #149 , bug(dsv): select1 underflow on zero-marker words (markers/newlines_select1) #196 ), robustness (JSON validator: unbounded recursion causes stack-overflow abort on deeply nested input #151 –YAML alias resolution: no cycle guard causes infinite recursion abort #153 , BitVec::rank0(i) over-counts for i > len (inherits the non-clamping trait default) #187 , Structural indices use u32/i16 counters that silently truncate on large/deeply-nested input #188 , popcount_words returns u32 which overflows at 512MB of ones #44 ), test infrastructure (test: land the green test scaffolding (CI arch-matrix, skip-visibility, differential harnesses, refactor snapshots) #192 –test: SVE2 SIMD coverage — toggle64 parity reference + differential execution under emulation (split from #191) #194 ,
test: the 8 yq comparison tests have never run in CI (skip silently, report green) #227 ), cleanup/refactor (Refactor: consolidate duplicated helpers between jq_runner and yq_runner #181 –Cleanup: YAML SIMD has duplicated scalar helpers, stale doc comments, and a latent terminator mismatch #185 , chore(lint): clippy --all-features -D warnings fails (18 pre-existing errors) on clippy 1.96 #197 ), and perf/research/features (the rest).
47 of 50 worktrees are empty scaffolding — zero commits ahead, zero dirty files; the 40
covering DSV BMI2/SVE2 quote-mask carry is wrong when a quote lands on bit 63 (silent row/field corruption) #149 –Structural indices use u32/i16 counters that silently truncate on large/deeply-nested input #188 are also 58 commits behind main. Only three contained real work, and all
three are now open PRs: bench(bench): add Rust succinct-library comparison and document build-vs-buy decision (ADR-0011) #232 (issue Document evaluation of existing succinct bitvector libraries #47 ), fix(cli): honor NO_COLOR spec, validate JQ_COLORS, and document environment variables #233 (issue Document environment variables (especially SUCCINCTLY_SVE2) #48 ), YAML test suite: live conformance harness, conformance docs, issue tracking #229 (issue YAML parser: consider YAML Test Suite and document parser behavior differences #49 ).
All three PRs have been reviewed and verified safe to merge (claims reproduced locally,
including the yaml/simd/x86: signed compare misreads UTF-8 bytes as control chars, panicking yq on non-ASCII #230 SIMD fix under Rosetta and the BitVec overhead correction re-derived from
the source).
Five stale PRs untouched since Feb/Mar: refactor(yaml): eliminate seq_items bitvector for memory optimization #104 , perf(simd): implement SIMD-accelerated JSON string escaping #115 , feat(simd): implement AVX2-accelerated JSON string validation for x86_64 #127 , feat(text): implement UTF-8 validation with scalar algorithm, CLI, and benchmarking #132 , docs(docs): establish Architecture Decision Records system for project governance #136 .
CI red herrings : the nightly x86_64 leg fails on every fresh PR run because
test_quiet_mode_no_output asserts empty stderr while current nightly cargo emits a
future-incompat-report note; https://no-color.org/ intermittently fails the link check.
The core insight
The risk is not fixing bugs wrong — it is fixing them at volume against a test suite that
silently under-reports (#227 : 8 yq comparison tests skip silently and report green) and code
that is duplicated (#226 : scalar type resolution in 5 sites; #161 /#162 : eval.rs vs eval_generic
divergence). Spend the first ~10% of effort on harnesses and consolidation; the remaining 90%
becomes safely parallelizable. PR #229 's two-sided known-failures manifest is the model: every
future YAML fix is forced to update the conformance record, keeping docs accurate automatically.
Progress update (2026-07-19)
Phase 0 is essentially complete; Phase 1 (the safety net) is largely landed. The 2026-07-18
snapshot above is kept as the historical baseline; this section is the current state.
Phase 0 — done:
All three real PRs merged: feat(bench): add succinct library comparison benchmarks and ADR-0011 #237 (issue Document evaluation of existing succinct bitvector libraries #47 — ADR-0011 + succinct-library comparison bench;
superseded the closed bench(bench): add Rust succinct-library comparison and document build-vs-buy decision (ADR-0011) #232 ), fix(cli): honor NO_COLOR spec, validate JQ_COLORS, and document environment variables #233 (Document environment variables (especially SUCCINCTLY_SVE2) #48 ), YAML test suite: live conformance harness, conformance docs, issue tracking #229 (YAML parser: consider YAML Test Suite and document parser behavior differences #49 ).
CI red herrings fixed: nightly test_quiet_mode_no_output brittleness (PR test(test): refactor JSON validation tests to use pre-built binary #236 ); the
no-color.org link-check flake (PR ci: exclude no-color.org from link checker #238 ).
YAML to_json() drops multibyte UTF-8 on x86 (signed compare in find_json_escape) #150 closed as resolved by the already-merged yaml/simd/x86: signed compare misreads UTF-8 bytes as control chars, panicking yq on non-ASCII #230 signed-compare fix.
ci: add commit-message linting workflow (commit-check.yml) #201 and ci(coverage): adopt omni-dev-coverage-check for PR diff coverage + line gate (x86_64 + ARM64), replacing tarpaulin/codecov #198 verified-and-closed — commit-check.yml (via ci: add commit message linting workflow #210 ) and the omni-dev coverage
action (via ci: replace codecov with omni-dev coverage check action and document coverage workflow #199 ) are live in CI.
Five stale PRs dispositioned:
Worktree pruning: still deferred. Merged/redirect/obsolete worktrees were pruned, but the
~40 empty issue-* scaffolding worktrees remain — the background implementation fleet is
active (it auto-implemented test: the 8 yq comparison tests have never run in CI (skip silently, report green) #227 /test: land the green test scaffolding (CI arch-matrix, skip-visibility, differential harnesses, refactor snapshots) #192 /test: x86 SIMD coverage — CI leg + differential execution, find_json_escape signed-compare (split from #191) #193 and keeps iterating on issue-* worktrees), so
the "confirm the fleet is stopped, then prune" precondition is not yet met.
Phase 1 — safety net:
test: the 8 yq comparison tests have never run in CI (skip silently, report green) #227 — merged (PR test(yaml): make the yq comparison tests actually run — pinned-yq goldens + CI drift check #241 ): pinned-yq golden conformance suite with goldens sourced from
the oracle (not the SUT), a two-sided known-failures manifest, a CI drift-check job, and the
cli feature gate. Design decision recorded on test: the 8 yq comparison tests have never run in CI (skip silently, report green) #227 .
test: land the green test scaffolding (CI arch-matrix, skip-visibility, differential harnesses, refactor snapshots) #192 — merged (PR test(test): add comprehensive refactor guard tests and SIMD CI verification (#192) #242 ): characterization snapshots + deep-nesting-valid guards +
CI-fails-loud-on-missing-SIMD-features. Its one remaining item (non-fast -e/--exit-status
guard) split out as test: guard the non-fast -e/--exit-status path returns correct exit codes (green; #192 Part 4b) #244 .
test: x86 SIMD coverage — CI leg + differential execution, find_json_escape signed-compare (split from #191) #193 — in flight (PR test(simd): implement comprehensive x86 SIMD test coverage and hard feature expectations for CI #245 , marked ready): x86 SIMD skip-visibility, SUCCINCTLY_EXPECT_SIMD
hard contract, per-kernel find_json_escape differential tests, and a product fix for yaml: x86 without AVX2 silently misparses YAML (classify_yaml_chars classifies 16 bytes, parser skips 32) #231
(SSE2 classify/skip-width mismatch — Rosetta-verified fail-without/pass-with). Review gap: the
yaml: x86 without AVX2 silently misparses YAML (classify_yaml_chars classifies 16 bytes, parser skips 32) #231 fix has no CI-executable regression guard (the bug is non-AVX2-x86-only and CI runners have
AVX2) → filed as test(ci): CI-executable regression guard for the x86 SSE2 classify/skip-width path (non-AVX2 fallback) #247 .
chore(lint): clippy --all-features -D warnings fails (18 pre-existing errors) on clippy 1.96 #197 (clippy --all-features -D warnings) — observed clean in recent worktrees off main;
verify-then-close candidate.
New tracking issues created this session: #244 (#192 Part 4b), #247 (CI regression guard
for the SSE2 classify/skip-width path). #231 is being fixed by PR #245 .
Progress update (2026-07-25)
The 2026-07-19 section above is kept as historical baseline; this section is the current state.
Verified against the live issue tracker (gh issue list --state open cross-referenced against every
issue named below), not against the snapshot prose above.
Phases 0–2 and 5 are complete; the safety net is fully in place. Remaining work is Phase 3's two
open lanes (jq, YAML), the Phase 4 cleanups, and the Phase 6 perf/research + feature bulk.
Phase 0 — done, except worktree pruning. All reconcile items closed. The one open item —
confirm the fleet is stopped, then prune the empty worktrees — remains deferred : the
background implementation fleet has not been confirmed stopped, and in-flight worktrees remain
for the open jq/YAML lanes. Independently prunable now: stale worktrees whose issues have since
merged (O5: Extract shared SIMD escape scanning module #125 , YAML alias resolution: no cycle guard causes infinite recursion abort #153 , jq: array index out of bounds errors instead of returning null #157 , jq: object comparison/sort interleaves key and value comparison #163 , YAML: block scalars type-coerce on the streaming path (|- 123 becomes a number) #168 , YAML: leading-dot floats stay strings on the streaming path (.5) #170 ).
Phase 1 — safety net: complete. test: the 8 yq comparison tests have never run in CI (skip silently, report green) #227 , test: land the green test scaffolding (CI arch-matrix, skip-visibility, differential harnesses, refactor snapshots) #192 , test: x86 SIMD coverage — CI leg + differential execution, find_json_escape signed-compare (split from #191) #193 (merged; carried the yaml: x86 without AVX2 silently misparses YAML (classify_yaml_chars classifies 16 bytes, parser skips 32) #231 non-AVX2
classify/skip-width product fix), and chore(lint): clippy --all-features -D warnings fails (18 pre-existing errors) on clippy 1.96 #197 are all closed. Both 07-19 gap-trackers are closed:
test: guard the non-fast -e/--exit-status path returns correct exit codes (green; #192 Part 4b) #244 (PR test(test): add comprehensive exit status tests for non-fast path #248 ) and test(ci): CI-executable regression guard for the x86 SSE2 classify/skip-width path (non-AVX2 fallback) #247 (PR test(yaml): CI-executable regression guard for the x86 SSE2 classify/skip-width path (#247) #251 ). Every semantics fix now ships against the
jq/yq/yaml-suite golden + differential harnesses with two-sided known-failures manifests and a CI
drift job.
Phase 2 — consolidate: complete. yaml: scalar type resolution diverges from the 1.2 core schema, and is duplicated across 5 sites #226 (5-site scalar type resolution), jq: values/first/last have wrong semantics in eval_generic (divergence from eval.rs) #161 /jq: object </> comparisons always false in eval_generic #162 (eval.rs
↔ eval_generic divergence), and Refactor: consolidate duplicated helpers between jq_runner and yq_runner #181 (jq_runner/yq_runner helper consolidation) are all closed —
the jq/YAML bug lanes now fix single sites, not N copies.
Phase 3 — correctness fleet: CLI, SIMD, and bits lanes fully closed (CLI: yq -I 0 (compact YAML identity) quotes scalars and drops --- document separators #175 –CLI: dsv --header is effectively a no-op and cannot be disabled #180 /yq: -I 0 changes document values, not just formatting #222 /jq: regex builtins (test/match/sub/gsub/scan/splits/capture) unavailable in the shipped CLI #167 ;
yaml: x86 without AVX2 silently misparses YAML (classify_yaml_chars classifies 16 bytes, parser skips 32) #231 /NEON JSON classifier over-matches boundary bytes (differential vs x86/scalar on invalid JSON) #186 /bug(dsv): select1 underflow on zero-marker words (markers/newlines_select1) #196 /DSV BMI2/SVE2 quote-mask carry is wrong when a quote lands on bit 63 (silent row/field corruption) #149 ; BitVec::rank0(i) over-counts for i > len (inherits the non-clamping trait default) #187 /Structural indices use u32/i16 counters that silently truncate on large/deeply-nested input #188 /popcount_words returns u32 which overflows at 512MB of ones #44 /JSON validator: unbounded recursion causes stack-overflow abort on deeply nested input #151 –YAML alias resolution: no cycle guard causes infinite recursion abort #153 ). Remaining open, both in-flight via the fleet:
Phase 4 — cleanups: Refactor: DSV has three copies of prefix_xor_scalar and scattered quote-mask logic #182 (DSV prefix_xor ×3) and Cleanup: YAML SIMD has duplicated scalar helpers, stale doc comments, and a latent terminator mismatch #185 (YAML SIMD duplicated helpers) remain
open, in-flight.
Phase 5 — SVE2: complete — test: SVE2 SIMD coverage — toggle64 parity reference + differential execution under emulation (split from #191) #194 and DSV BMI2/SVE2 quote-mask carry is wrong when a quote lands on bit 63 (silent row/field corruption) #149 closed.
Phase 6 — perf/research + features: the remaining bulk, mostly untouched.
perf/research (open): Investigate SIMD batch select optimization #40 , Reduce bp_to_text memory overhead while maintaining access performance #56 , Cursor-based Elias-Fano for bp_to_text with SIMD acceleration #58 , feat: Shrink the BP/YAML select index with combined sampling (CS-Poppy) #64 , SIMD optimization for JSON escape scanning in jq output path #91 , perf: investigate seq_item detection optimizations after bitvector elimination #106 , feat: SIMD optimization for JSON validator (x86_64 AVX2) #122 , perf(json): Implement chunked SIMD validation with register reuse #123 , O4: SIMD escape scanning for jq format functions (@uri, @html, @csv, @dsv) #124 , State Machine JSON Validator: Implementation Complete, Optimization Opportunities #130 , perf(text): Broadword (SWAR) optimizations for scalar UTF-8 validation #133 , perf(text): Implement broadword + DFA hybrid UTF-8 validation #134 , BitVec loses to vers-vecs/sux on space, build, rank and select — reconsider its auxiliary use #228 .
(O5: Extract shared SIMD escape scanning module #125 /O6: Profile jq string operations for SIMD opportunity #126 closed.)
features (open): Evaluate jaq's ValT as interoperability layer for jq/yq evaluation #70 , feat: xq - XML query language using jq syntax #85 , feat(bench): SSH-based distributed benchmark orchestration #98 , M3.1: Lazy streaming keys via JqValue::LazyKeysArray #140 , yaml: add opt-in strict validation (yaml validate / syq --validate) #223 , yaml: support tags (!!str, !custom, verbatim) #224 , yaml: recognize %YAML and %TAG directives #225 .
Guardrail landed: bench: real-workload input corpus + shape statistics for end-to-end perf validation #301 — merged (PR feat(cli,bench,test): implement real-workload corpus with corpus-stats shape-statistics reporting (#301) #319 ): real-workload corpus + corpus-stats
shape-statistics reporting. This supplies the representative inputs for the Phase 6 rule
"end-to-end measurement before any doc claim," the specific guard against the
P5/P2.6/P2.8/P3/P8 pattern. Every Phase 6 perf change should now be measured against this
corpus.
jq: A/B-test memchr::memmem for substring builtins (index/rindex/indices/contains/split) — bench-only, guarded adoption (follow-up to #126) #303 (memchr::memmem substring A/B) closed: the bench-only measurement landed (PR feat(bench, build, cli): add jq substring-search A/B benchmark + defer phase 2 #316 ) and
phase 2 (guarded adoption) was deliberately deferred.
Corpus/suite coverage extended, and perf: investigate seq_item detection optimizations after bitvector elimination #106 re-priced (2026-07-25): bench: corpus has no bare-dash YAML sequence items, so a 16x path is unrepresented #326 (bare-dash corpus
file + corpus-stats metric, PR feat(cli): establish bare-dash YAML shape existence and frequency baselines for #326 #331 ) and bench: end-to-end YAML suite generates no flow, anchors, block scalars, explicit keys or multi-doc #327 (generated suite now emits
flow/anchors/block-scalars/explicit-keys/multi-doc, PR feat(cli): generate flow, anchors, block scalars, explicit keys and multi-doc #330 ) both merged. The bench: corpus has no bare-dash YAML sequence items, so a 16x path is unrepresented #326 survey
(docs/benchmarks/yaml-shape-survey.md, 33,575 real YAML files) then corrected two perf
assumptions: perf: investigate seq_item detection optimizations after bitvector elimination #106 's 16× win is on a shape occurring in only 0.042% of real YAML → treat as
low priority , not rushed; and anchors are ~100× more common (0.494%, 4–11% in Home
Assistant/Salt/Concourse/GitLab CI), so the corpus anchors: 0 is a sampling artifact and the
live anchor work is the silent-corruption bug yaml: anchor on a sequence item with a collection value silently corrupts the document #328 , not more bare-dash tuning. Findings
recorded on perf: investigate seq_item detection optimizations after bitvector elimination #106 / bench: end-to-end YAML suite generates no flow, anchors, block scalars, explicit keys or multi-doc #327 / yaml: anchor on a sequence item with a collection value silently corrupts the document #328 .
Recommended sequencing from here: with #301 landed, the Phase 6 measurement guardrail is in place —
ADR-gate the architectural / core-structure perf issues (#70 , #85 , #228 , #64 , #56 /#58 ) before
implementation, and measure every perf change against the new corpus; let the fleet drain the
jq/YAML lanes and #182 /#185 under the now-complete guardrails.
Phase 0 — Reconcile state (one sitting)
Merge bench(bench): add Rust succinct-library comparison and document build-vs-buy decision (ADR-0011) #232 , fix(cli): honor NO_COLOR spec, validate JQ_COLORS, and document environment variables #233 , YAML test suite: live conformance harness, conformance docs, issue tracking #229 (done — bench(bench): add Rust succinct-library comparison and document build-vs-buy decision (ADR-0011) #232 superseded by feat(bench): add succinct library comparison benchmarks and ADR-0011 #237 ; all three merged)
Fix the nightly brittleness: make test_quiet_mode_no_output immune to cargo's own
stderr (filter it or exec the built binary directly) — PR test(test): refactor JSON validation tests to use pre-built binary #236
Add no-color.org to the link-checker exclusions (or accept occasional re-runs) — PR ci: exclude no-color.org from link checker #238
After YAML test suite: live conformance harness, conformance docs, issue tracking #229 merges: re-test YAML to_json() drops multibyte UTF-8 on x86 (signed compare in find_json_escape) #150 's repro — resolved by yaml/simd/x86: signed compare misreads UTF-8 bytes as control chars, panicking yq on non-ASCII #230 ; YAML to_json() drops multibyte UTF-8 on x86 (signed compare in find_json_escape) #150 closed as duplicate
Verify-then-close issues already implemented: ci: add commit-message linting workflow (commit-check.yml) #201 (commit-check.yml exists), ci(coverage): adopt omni-dev-coverage-check for PR diff coverage + line gate (x86_64 + ARM64), replacing tarpaulin/codecov #198
(coverage action already in CI per CLAUDE.md) — both closed
Decide keep-or-close on the five stale PRs: refactor(yaml): eliminate seq_items bitvector for memory optimization #104 merged, feat(text): implement UTF-8 validation with scalar algorithm, CLI, and benchmarking #132 merged, perf(simd): implement SIMD-accelerated JSON string escaping #115 & feat(simd): implement AVX2-accelerated JSON string validation for x86_64 #127 closed
(redirect), docs(docs): establish Architecture Decision Records system for project governance #136 closed (obsolete)
Confirm the background issue-implementation fleet is not running, then prune the 47 empty
worktrees and their branches — still deferred: the fleet is active (see progress update)
Phase 1 — Build the safety net first
With jq/yq-as-oracle differential testing in place, every subsequent semantics fix ships with a
machine-checked proof.
Phase 2 — Consolidate before fixing duplicated code
Phase 3 — The correctness fleet (the bulk, ~35 small bugs)
Parallelize across modules, not within them — one in-flight PR per module lane to avoid
rebase storms:
Lane
Issues
Machine
jq
#154 –#166 (post Phase 2)
Any
CLI
#175 –#180 , #222 , #167 , #176 –#179
Any
YAML
#168 –#174 , #171 –#173 (post #226 )
Any
SIMD
#231 , #186 , #196 , #149 (BMI2 half)
Per-arch (see below)
bits
#187 , #188 , #44 , #151 –#153
Any; large-tests on Mini
Every PR: failing repro test on main first → fix → differential test where an oracle exists →
clippy → patch coverage → conformance manifest updated where YAML behavior changes.
Phase 4 — Cleanups after their module's bug wave lands
Phase 5 — SVE2 batch (cost-minimized)
Phase 6 — Perf and research (strictly sequential benchmarks)
BitVec loses to vers-vecs/sux on space, build, rank and select — reconsider its auxiliary use #228 — BitVec vs vers-vecs/sux, in bench-compare/ (ADR-0011 and the succinct-library
comparison bench from feat(bench): add succinct library comparison benchmarks and ADR-0011 #237 — merged — are the starting point)
feat: Shrink the BP/YAML select index with combined sampling (CS-Poppy) #64 , Cursor-based Elias-Fano for bp_to_text with SIMD acceleration #58 , Reduce bp_to_text memory overhead while maintaining access performance #56 , perf: investigate seq_item detection optimizations after bitvector elimination #106 , feat: SIMD optimization for JSON validator (x86_64 AVX2) #122 –O6: Profile jq string operations for SIMD opportunity #126 , perf(text): Broadword (SWAR) optimizations for scalar UTF-8 validation #133 –perf(text): Implement broadword + DFA hybrid UTF-8 validation #134 , SIMD optimization for JSON escape scanning in jq output path #91 , Investigate SIMD batch select optimization #40 — one machine at a time, exclusive
CPU, end-to-end measurement before any doc claim (the project's own record: P2.6, P2.8,
P3, P8 all showed micro-benchmarks misleading)
Features last: yaml: add opt-in strict validation (yaml validate / syq --validate) #223 –yaml: recognize %YAML and %TAG directives #225 (YAML tags/directives/validation), feat: xq - XML query language using jq syntax #85 , feat(bench): SSH-based distributed benchmark orchestration #98 , Set up Dependabot for dependency updates #148 , perf(text): SIMD-accelerate the utf8 validator (CLI already landed; scalar remains, overlaps #133/#134) #131
Machine assignment
Machine
Role
M5 MacBook
Interactive dev, orchestration, review; NEON bug #186 ; Rosetta x86 tests
Mac Mini
Background lanes, large-tests, ARM benchmark box (sequential)
Linux x86
x86 SIMD bugs (#231 , #149 -BMI2, #193 ), x86 benchmarks, QEMU SVE2 (#194 )
EC2 (SVE2)
Single batch validation session after QEMU is green
Benchmarks are never run concurrently with anything; the benchmark machine is quiesced.
Rosetta on the M5 covers x86 correctness checks (as used to verify the #230 fix); it is
never used for x86 performance numbers.
Quality guardrails (definition of done per PR)
Failing repro test on main before the fix
Differential test against jq/yq oracle where applicable
cargo clippy --all-targets --all-features -- -D warnings clean
Patch coverage via omni-dev coverage diff
Docs updated if the change touches documented behavior; every perf/space claim in docs
backed by a fresh measurement on the named platform
Conventional commit with required scope from .omni-dev/scopes.yaml
Worktrees external under $HOME/wrk/work-trees/succinctly/<branch>/, one issue = one
worktree = one PR
Backlog processing strategy: volume without compromising quality
Goal
Process the ~80 open issues without compromising code quality, performance, functionality, or
documentation accuracy, using the available hardware (M5 MacBook Pro Max, Mac Mini, Linux x86
with SIMD, minimal EC2 for SVE2).
State snapshot (2026-07-18)
(YAML: block scalars type-coerce on the streaming path (|- 123 becomes a number) #168–YAML: duplicate mapping keys are first-wins (YAML 1.2 / yq take last or error) #174, yaml: scalar type resolution diverges from the 1.2 core schema, and is duplicated across 5 sites #226), CLI bugs (CLI: yq -I 0 (compact YAML identity) quotes scalars and drops --- document separators #175–CLI: dsv --header is effectively a no-op and cannot be disabled #180, yq: -I 0 changes document values, not just formatting #222), arch-specific SIMD bugs (yaml/simd/x86: signed compare misreads UTF-8 bytes as control chars, panicking yq on non-ASCII #230, yaml: x86 without AVX2 silently misparses YAML (classify_yaml_chars classifies 16 bytes, parser skips 32) #231, YAML to_json() drops multibyte UTF-8 on x86 (signed compare in find_json_escape) #150,
NEON JSON classifier over-matches boundary bytes (differential vs x86/scalar on invalid JSON) #186, DSV BMI2/SVE2 quote-mask carry is wrong when a quote lands on bit 63 (silent row/field corruption) #149, bug(dsv): select1 underflow on zero-marker words (markers/newlines_select1) #196), robustness (JSON validator: unbounded recursion causes stack-overflow abort on deeply nested input #151–YAML alias resolution: no cycle guard causes infinite recursion abort #153, BitVec::rank0(i) over-counts for i > len (inherits the non-clamping trait default) #187, Structural indices use u32/i16 counters that silently truncate on large/deeply-nested input #188, popcount_words returns u32 which overflows at 512MB of ones #44), test infrastructure (test: land the green test scaffolding (CI arch-matrix, skip-visibility, differential harnesses, refactor snapshots) #192–test: SVE2 SIMD coverage — toggle64 parity reference + differential execution under emulation (split from #191) #194,
test: the 8 yq comparison tests have never run in CI (skip silently, report green) #227), cleanup/refactor (Refactor: consolidate duplicated helpers between jq_runner and yq_runner #181–Cleanup: YAML SIMD has duplicated scalar helpers, stale doc comments, and a latent terminator mismatch #185, chore(lint): clippy --all-features -D warnings fails (18 pre-existing errors) on clippy 1.96 #197), and perf/research/features (the rest).
covering DSV BMI2/SVE2 quote-mask carry is wrong when a quote lands on bit 63 (silent row/field corruption) #149–Structural indices use u32/i16 counters that silently truncate on large/deeply-nested input #188 are also 58 commits behind main. Only three contained real work, and all
three are now open PRs: bench(bench): add Rust succinct-library comparison and document build-vs-buy decision (ADR-0011) #232 (issue Document evaluation of existing succinct bitvector libraries #47), fix(cli): honor NO_COLOR spec, validate JQ_COLORS, and document environment variables #233 (issue Document environment variables (especially SUCCINCTLY_SVE2) #48), YAML test suite: live conformance harness, conformance docs, issue tracking #229 (issue YAML parser: consider YAML Test Suite and document parser behavior differences #49).
including the yaml/simd/x86: signed compare misreads UTF-8 bytes as control chars, panicking yq on non-ASCII #230 SIMD fix under Rosetta and the BitVec overhead correction re-derived from
the source).
test_quiet_mode_no_outputasserts empty stderr while current nightly cargo emits afuture-incompat-reportnote;https://no-color.org/intermittently fails the link check.The core insight
The risk is not fixing bugs wrong — it is fixing them at volume against a test suite that
silently under-reports (#227: 8 yq comparison tests skip silently and report green) and code
that is duplicated (#226: scalar type resolution in 5 sites; #161/#162: eval.rs vs eval_generic
divergence). Spend the first ~10% of effort on harnesses and consolidation; the remaining 90%
becomes safely parallelizable. PR #229's two-sided known-failures manifest is the model: every
future YAML fix is forced to update the conformance record, keeping docs accurate automatically.
Progress update (2026-07-19)
Phase 0 is essentially complete; Phase 1 (the safety net) is largely landed. The 2026-07-18
snapshot above is kept as the historical baseline; this section is the current state.
Phase 0 — done:
superseded the closed bench(bench): add Rust succinct-library comparison and document build-vs-buy decision (ADR-0011) #232), fix(cli): honor NO_COLOR spec, validate JQ_COLORS, and document environment variables #233 (Document environment variables (especially SUCCINCTLY_SVE2) #48), YAML test suite: live conformance harness, conformance docs, issue tracking #229 (YAML parser: consider YAML Test Suite and document parser behavior differences #49).
test_quiet_mode_no_outputbrittleness (PR test(test): refactor JSON validation tests to use pre-built binary #236); theno-color.orglink-check flake (PR ci: exclude no-color.org from link checker #238).commit-check.yml(via ci: add commit message linting workflow #210) and the omni-dev coverageaction (via ci: replace codecov with omni-dev coverage check action and document coverage workflow #199) are live in CI.
mitigation folded in (recovers the 7–15% CPU regression) and stale
docs/parsingrefreshed.Follow-up: sequential
yaml_bench+dev bench yqconfirmation (branchbench-seq-items-elimination-tradeoff).textmodule +text validate utf8CLI baseline that perf(text): SIMD-accelerate the utf8 validator (CLI already landed; scalar remains, overlaps #133/#134) #131/perf(text): Broadword (SWAR) optimizations for scalar UTF-8 validation #133/perf(text): Implement broadword + DFA hybrid UTF-8 validation #134 build on. Benchmark doc markedprovisional pending re-measurement.
escape module) → SIMD optimization for JSON escape scanning in jq output path #91. Salvage on
refs/pull/115/head.feat: SIMD optimization for JSON validator (x86_64 AVX2) #122/perf(json): Implement chunked SIMD validation with register reuse #123/State Machine JSON Validator: Implementation Complete, Optimization Opportunities #130. Salvage on
refs/pull/127/head.from docs: adopt Architecture Decision Records (docs/adrs/) #207/docs: adopt Architecture Decision Records practice with corpus and cross-linking #211).
~40 empty
issue-*scaffolding worktrees remain — the background implementation fleet isactive (it auto-implemented test: the 8 yq comparison tests have never run in CI (skip silently, report green) #227/test: land the green test scaffolding (CI arch-matrix, skip-visibility, differential harnesses, refactor snapshots) #192/test: x86 SIMD coverage — CI leg + differential execution, find_json_escape signed-compare (split from #191) #193 and keeps iterating on
issue-*worktrees), sothe "confirm the fleet is stopped, then prune" precondition is not yet met.
Phase 1 — safety net:
yqgolden conformance suite with goldens sourced fromthe oracle (not the SUT), a two-sided known-failures manifest, a CI drift-check job, and the
clifeature gate. Design decision recorded on test: the 8 yq comparison tests have never run in CI (skip silently, report green) #227.CI-fails-loud-on-missing-SIMD-features. Its one remaining item (non-fast
-e/--exit-statusguard) split out as test: guard the non-fast -e/--exit-status path returns correct exit codes (green; #192 Part 4b) #244.
SUCCINCTLY_EXPECT_SIMDhard contract, per-kernel
find_json_escapedifferential tests, and a product fix for yaml: x86 without AVX2 silently misparses YAML (classify_yaml_chars classifies 16 bytes, parser skips 32) #231(SSE2 classify/skip-width mismatch — Rosetta-verified fail-without/pass-with). Review gap: the
yaml: x86 without AVX2 silently misparses YAML (classify_yaml_chars classifies 16 bytes, parser skips 32) #231 fix has no CI-executable regression guard (the bug is non-AVX2-x86-only and CI runners have
AVX2) → filed as test(ci): CI-executable regression guard for the x86 SSE2 classify/skip-width path (non-AVX2 fallback) #247.
clippy --all-features -D warnings) — observed clean in recent worktrees offmain;verify-then-close candidate.
New tracking issues created this session: #244 (#192 Part 4b), #247 (CI regression guard
for the SSE2 classify/skip-width path). #231 is being fixed by PR #245.
Progress update (2026-07-25)
The 2026-07-19 section above is kept as historical baseline; this section is the current state.
Verified against the live issue tracker (
gh issue list --state opencross-referenced against everyissue named below), not against the snapshot prose above.
Phases 0–2 and 5 are complete; the safety net is fully in place. Remaining work is Phase 3's two
open lanes (jq, YAML), the Phase 4 cleanups, and the Phase 6 perf/research + feature bulk.
confirm the fleet is stopped, then prune the empty worktrees — remains deferred: the
background implementation fleet has not been confirmed stopped, and in-flight worktrees remain
for the open jq/YAML lanes. Independently prunable now: stale worktrees whose issues have since
merged (O5: Extract shared SIMD escape scanning module #125, YAML alias resolution: no cycle guard causes infinite recursion abort #153, jq: array index out of bounds errors instead of returning null #157, jq: object comparison/sort interleaves key and value comparison #163, YAML: block scalars type-coerce on the streaming path (|- 123 becomes a number) #168, YAML: leading-dot floats stay strings on the streaming path (.5) #170).
classify/skip-width product fix), and chore(lint): clippy --all-features -D warnings fails (18 pre-existing errors) on clippy 1.96 #197 are all closed. Both 07-19 gap-trackers are closed:
test: guard the non-fast -e/--exit-status path returns correct exit codes (green; #192 Part 4b) #244 (PR test(test): add comprehensive exit status tests for non-fast path #248) and test(ci): CI-executable regression guard for the x86 SSE2 classify/skip-width path (non-AVX2 fallback) #247 (PR test(yaml): CI-executable regression guard for the x86 SSE2 classify/skip-width path (#247) #251). Every semantics fix now ships against the
jq/yq/yaml-suite golden + differential harnesses with two-sided known-failures manifests and a CI
drift job.
eval.rs↔
eval_genericdivergence), and Refactor: consolidate duplicated helpers between jq_runner and yq_runner #181 (jq_runner/yq_runner helper consolidation) are all closed —the jq/YAML bug lanes now fix single sites, not N copies.
yaml: x86 without AVX2 silently misparses YAML (classify_yaml_chars classifies 16 bytes, parser skips 32) #231/NEON JSON classifier over-matches boundary bytes (differential vs x86/scalar on invalid JSON) #186/bug(dsv): select1 underflow on zero-marker words (markers/newlines_select1) #196/DSV BMI2/SVE2 quote-mask carry is wrong when a quote lands on bit 63 (silent row/field corruption) #149; BitVec::rank0(i) over-counts for i > len (inherits the non-clamping trait default) #187/Structural indices use u32/i16 counters that silently truncate on large/deeply-nested input #188/popcount_words returns u32 which overflows at 512MB of ones #44/JSON validator: unbounded recursion causes stack-overflow abort on deeply nested input #151–YAML alias resolution: no cycle guard causes infinite recursion abort #153). Remaining open, both in-flight via the fleet:
prefix_xor×3) and Cleanup: YAML SIMD has duplicated scalar helpers, stale doc comments, and a latent terminator mismatch #185 (YAML SIMD duplicated helpers) remainopen, in-flight.
(O5: Extract shared SIMD escape scanning module #125/O6: Profile jq string operations for SIMD opportunity #126 closed.)
corpus-statsshape-statistics reporting. This supplies the representative inputs for the Phase 6 rule
"end-to-end measurement before any doc claim," the specific guard against the
P5/P2.6/P2.8/P3/P8 pattern. Every Phase 6 perf change should now be measured against this
corpus.
phase 2 (guarded adoption) was deliberately deferred.
file +
corpus-statsmetric, PR feat(cli): establish bare-dash YAML shape existence and frequency baselines for #326 #331) and bench: end-to-end YAML suite generates no flow, anchors, block scalars, explicit keys or multi-doc #327 (generated suite now emitsflow/anchors/block-scalars/explicit-keys/multi-doc, PR feat(cli): generate flow, anchors, block scalars, explicit keys and multi-doc #330) both merged. The bench: corpus has no bare-dash YAML sequence items, so a 16x path is unrepresented #326 survey
(
docs/benchmarks/yaml-shape-survey.md, 33,575 real YAML files) then corrected two perfassumptions: perf: investigate seq_item detection optimizations after bitvector elimination #106's 16× win is on a shape occurring in only 0.042% of real YAML → treat as
low priority, not rushed; and anchors are ~100× more common (0.494%, 4–11% in Home
Assistant/Salt/Concourse/GitLab CI), so the corpus
anchors: 0is a sampling artifact and thelive anchor work is the silent-corruption bug yaml: anchor on a sequence item with a collection value silently corrupts the document #328, not more bare-dash tuning. Findings
recorded on perf: investigate seq_item detection optimizations after bitvector elimination #106 / bench: end-to-end YAML suite generates no flow, anchors, block scalars, explicit keys or multi-doc #327 / yaml: anchor on a sequence item with a collection value silently corrupts the document #328.
Recommended sequencing from here: with #301 landed, the Phase 6 measurement guardrail is in place —
ADR-gate the architectural / core-structure perf issues (#70, #85, #228, #64, #56/#58) before
implementation, and measure every perf change against the new corpus; let the fleet drain the
jq/YAML lanes and #182/#185 under the now-complete guardrails.
Phase 0 — Reconcile state (one sitting)
test_quiet_mode_no_outputimmune to cargo's ownstderr (filter it or exec the built binary directly) — PR test(test): refactor JSON validation tests to use pre-built binary #236
no-color.orgto the link-checker exclusions (or accept occasional re-runs) — PR ci: exclude no-color.org from link checker #238(coverage action already in CI per CLAUDE.md) — both closed
(redirect), docs(docs): establish Architecture Decision Records system for project governance #136 closed (obsolete)
worktrees and their branches — still deferred: the fleet is active (see progress update)
Phase 1 — Build the safety net first
pinned-
yqgolden suite (oracle-sourced) + two-sided known-failures manifest + drift-check jobdeep-nesting guards — merged (PR test(test): add comprehensive refactor guard tests and SIMD CI verification (#192) #242); residual
-eguard split to test: guard the non-fast -e/--exit-status path returns correct exit codes (green; #192 Part 4b) #244carries the yaml: x86 without AVX2 silently misparses YAML (classify_yaml_chars classifies 16 bytes, parser skips 32) #231 SSE2 classify/skip-width fix (Rosetta-verified); CI-guard gap tracked as test(ci): CI-executable regression guard for the x86 SSE2 classify/skip-width path (non-AVX2 fallback) #247
clippy --all-features -D warningsclean — observed clean in recent worktrees;verify-then-close candidate
With jq/yq-as-oracle differential testing in place, every subsequent semantics fix ships with a
machine-checked proof.
Phase 2 — Consolidate before fixing duplicated code
it means fixing each bug five times
refactor) before the jq semantics batch, or at minimum require fixes land in both sites
with shared tests
Phase 3 — The correctness fleet (the bulk, ~35 small bugs)
Parallelize across modules, not within them — one in-flight PR per module lane to avoid
rebase storms:
Every PR: failing repro test on main first → fix → differential test where an oracle exists →
clippy → patch coverage → conformance manifest updated where YAML behavior changes.
Phase 4 — Cleanups after their module's bug wave lands
Phase 5 — SVE2 batch (cost-minimized)
capture artifacts, terminate
Phase 6 — Perf and research (strictly sequential benchmarks)
bench-compare/(ADR-0011 and the succinct-librarycomparison bench from feat(bench): add succinct library comparison benchmarks and ADR-0011 #237 — merged — are the starting point)
CPU, end-to-end measurement before any doc claim (the project's own record: P2.6, P2.8,
P3, P8 all showed micro-benchmarks misleading)
Machine assignment
large-tests, ARM benchmark box (sequential)Benchmarks are never run concurrently with anything; the benchmark machine is quiesced.
Rosetta on the M5 covers x86 correctness checks (as used to verify the #230 fix); it is
never used for x86 performance numbers.
Quality guardrails (definition of done per PR)
cargo clippy --all-targets --all-features -- -D warningscleanomni-dev coverage diffbacked by a fresh measurement on the named platform
.omni-dev/scopes.yaml$HOME/wrk/work-trees/succinctly/<branch>/, one issue = oneworktree = one PR