diff --git a/.agents/sow/current/SOW-0047-20260605-codacy-complexity-backlog.md b/.agents/sow/done/SOW-0047-20260605-codacy-complexity-backlog.md similarity index 94% rename from .agents/sow/current/SOW-0047-20260605-codacy-complexity-backlog.md rename to .agents/sow/done/SOW-0047-20260605-codacy-complexity-backlog.md index 803e7d6..158f0be 100644 --- a/.agents/sow/current/SOW-0047-20260605-codacy-complexity-backlog.md +++ b/.agents/sow/done/SOW-0047-20260605-codacy-complexity-backlog.md @@ -2,24 +2,17 @@ ## Status -Status: open - -Sub-state: active 2026-06-05. First production slice -`frontend/src/state/filters.ts` is merged. Second production slice -`internal/adapters/aiagent_v2/mapper.go` is merged. Third production slice -`internal/ingest/writer.go` `applyOpFinalized` is merged. Fourth production -slice `internal/ingest/catalog.go` `onOpStarted` and `onOpFinalized` is merged. -Fifth slice implemented: baseline Claude-code scan/tail benchmarks before -scanner/tailer decomposition. Next slice resumes production complexity -reduction. Sixth slice selected: Claude-code scanner decomposition with Tail -behavior preserved by focused regression tests and the new benchmark guard. -Sixth slice is merged. Seventh slice selected: Claude-code tailer/parser -decomposition, using the existing Scan/Tail benchmark guard and Tail restart -regression suite. Seventh slice is merged. Eighth slice selected: -Claude-code mapper ops decomposition in `internal/adapters/claude_code/ops.go`, -using the existing mapper fixtures/tests and Claude-code Scan/Tail benchmark -guard. Eighth slice is implemented and locally validated; external review -converged; PR checks, merge, and post-merge gates remain pending. +Status: completed + +Sub-state: completed 2026-06-06. Eight production slices were merged: +frontend filter helpers, ai-agent v2 mapper decomposition, ingest writer +`applyOpFinalized`, ingest catalog writer decomposition, Claude-code benchmark +baselines, Claude-code scanner decomposition, Claude-code tailer/parser +decomposition, and Claude-code mapper ops decomposition. PR #57 merged the +eighth slice. Final closeout measured 141 remaining strict source-only Lizard +warnings, plus frontend tooling warnings when a broader source/tooling filter is +used, and split the remaining work into narrower follow-up SOWs instead of +keeping this SOW open indefinitely. ## Requirements @@ -1312,8 +1305,12 @@ Open decisions: ### Eighth Slice Gate - claude-code mapper ops decomposition -Status: implementation and local validation complete; external review -converged; PR checks, merge, and post-merge gates remain pending. +Status: completed. PR #57 merged on 2026-06-06 after external review +converged and all PR checks were green except the expected +`codacy-coverage` PR skip. A post-merge `./scripts/gates.sh` attempt on +`master` failed only in the local workstation benchmark gate under high +ambient CPU load; the immediately repeated `scripts/check-bench.sh` passed, +confirming no repeatable benchmark regression. Selected eighth slice: @@ -2283,7 +2280,8 @@ Eighth slice focused validation: passing tests, frontend E2E/axe with 51 passing tests, and main frontend bundle size 132.2 KB gzipped against the 500 KB budget. - External review converged in Round 37 with no actionable findings remaining. - PR checks, merge, and post-merge gates remain pending for this eighth slice. + PR #57 merged after all PR checks passed except the expected + `codacy-coverage` PR skip. - Final post-review `./scripts/gates.sh` passed in 553s on the staged Round 37 state: lint/static/security/vulnerability checks, secrets over 861 tracked files, attribution scan, spec drift, Codacy coverage/config self-tests, @@ -2294,6 +2292,42 @@ Eighth slice focused validation: `internal/adapters/claude_code` coverage 86.9%, frontend Vitest with 631 passing tests, frontend E2E/axe with 51 passing tests, and main frontend bundle size 132.2 KB gzipped against the 500 KB budget. +- Post-merge validation on `master`: an initial `./scripts/gates.sh` run passed + lint/static/security/vulnerability checks, secrets, attribution scan, + spec drift, Codacy coverage/config self-tests, systemd unit lint, and + build + bundle-size, then failed only in `scripts/check-bench.sh`. The + failure touched unrelated packages as well as the Claude-code adapter while + the workstation was under high ambient CPU load. A direct repeat of + `scripts/check-bench.sh` passed with no `sec/op` regression over the 20% + threshold. Because `gates.sh` is fail-fast, that first post-merge aggregate + did not run the later race/coverage, fuzz, or Playwright stages; full staged + gates and PR checks remain the full-green evidence for the eighth slice. +- SOW-only closeout branch validation: `./scripts/test.sh`, + `scripts/check-coverage.sh coverage.out`, `go test -run='^Fuzz' + ./internal/adapters/...`, `cd frontend && npm run e2e`, `cd frontend && + npm run e2e:a11y`, `git diff --check`, `git diff --cached --check`, + `scripts/scan-secrets.sh`, `scripts/scan-ai-attribution.sh`, and + `scripts/spec-drift.sh` passed on the staged closeout diff. Repeated + `./scripts/gates.sh` and isolated `scripts/check-bench.sh` attempts failed + only at the local workstation benchmark gate while unrelated CPU-heavy + workstation processes were active; the branch changes only SOW files and does + not touch benchmarked code, memory/allocation metrics stayed flat, and no + benchmark threshold or baseline was changed. +- Closeout strict source-only Lizard warning scan on 2026-06-06 found 141 + warnings after excluding tests and generated embedded frontend assets. The + largest remaining buckets were Codex adapter tailer/scanner/mapper/parser + paths, Opencode adapter tailer/mapper paths, remaining ai-agent/Claude-code + adapter paths, ingest writer/worker/catalog migration paths, CLI/presenter/ + pricing/store handlers, frontend trace/topology visualization components, and + smaller frontend component/state/utility helpers. A broader source/tooling + filter also reports `frontend/scripts/check-bundle-size.js`; that frontend + tooling bucket is tracked with the frontend residual SOW. +- Remaining complexity is tracked by follow-up SOWs: + `.agents/sow/pending/SOW-0048-20260606-codex-adapter-complexity.md`, + `.agents/sow/pending/SOW-0049-20260606-opencode-adapter-complexity.md`, + `.agents/sow/pending/SOW-0050-20260606-backend-residual-complexity.md`, + `.agents/sow/pending/SOW-0051-20260606-frontend-visualization-complexity.md`, + and `.agents/sow/pending/SOW-0052-20260606-residual-adapter-complexity.md`. ## Reviews @@ -3647,11 +3681,146 @@ Resolution: duplication, intermediate helper slices, no new direct compaction/meta tests in the new file, and the snapshot test helper's parsed-type assertion style. - No code/spec changes were required after Round 37. PR checks, merge, and - post-merge gates remain pending. + post-merge validation were completed before closeout; PR #57 merged on + 2026-06-06. The first post-merge aggregate gate on `master` failed only at + the workstation benchmark gate under high ambient CPU load; an immediate + isolated benchmark-gate rerun passed. Later SOW-only closeout branch + aggregate attempts also failed only in the benchmark gate while unrelated + CPU-heavy workstation processes were active; the closeout branch changes only + SOW files and does not alter benchmarked code. + +### Round 38 - 2026-06-06 + +Scope: staged SOW-only closeout diff after moving SOW-0047 to `done/` and +adding residual-complexity follow-up SOWs. + +Reviewers: + +- `qwen`: found one low stale wording issue in the Round 37 resolution, noted + optional validation-summary hygiene, and otherwise found the closeout sound. +- `glm`: no blocker. Treated historical `current/` and "remains active" slice + notes as accurate historical records and found the follow-up SOW shells + sufficient for future activation. +- `codex`: found two actionable closeout issues: the four initial follow-up + SOWs did not clearly cover all 141 source-only warnings, and post-merge gate + wording did not make clear that the failed aggregate stopped before later + stages. Also repeated the stale Round 37 pending sentence finding. + +Resolution: + +- Accepted the stale Round 37 wording finding and updated it with the actual + PR #57 merge and post-merge benchmark-rerun evidence. +- Accepted the residual-tracking gap as real. Added + `SOW-0052-20260606-residual-adapter-complexity.md` for ai-agent v2/v3 and + Claude-code residual adapter warnings, broadened SOW-0050 to cover CLI and + backend tooling warnings, and broadened SOW-0051 to cover non-visual frontend + component/state/utility/tooling warnings. +- Accepted the post-merge gate wording finding. The closeout now states that + the post-merge `master` aggregate failed fast before later stages, while the + eighth-slice staged gates and PR checks were full-green evidence. The + closeout validation record now separately lists the SOW-only branch checks + that passed and the benchmark-only limitation caused by ambient workstation + load. +- The optional validation-summary recommendation is not implemented in this + closeout because SOW-0047 already contains per-slice evidence and final + acceptance/follow-up mapping; adding a large duplicate summary would make the + already-long audit trail harder to maintain. + +### Round 39 - 2026-06-06 + +Scope: same staged SOW-only closeout diff after Round 38 fixes. + +Reviewers: + +- `qwen`: no blocker. Verified closeout consistency, follow-up SOW coverage, + sensitive-data hygiene, stale wording, and the empty-`current/` lifecycle + state. +- `glm`: no blocker. Found SOW-0047 completion evidence internally consistent, + follow-up scopes adequate, and noted SOW-0050/SOW-0051 breadth as a low + style caveat mitigated by their one-slice-at-a-time implementation plans. +- `codex`: one low finding. SOW-0049 lacked the explicit residual-closeout + guard already present in the other follow-up SOWs. + +Resolution: + +- Accepted the SOW-0049 finding and added an acceptance criterion requiring any + remaining Opencode warning to be reduced, explicitly justified, or split into + a narrower follow-up SOW before completion. +- Treated the SOW-0050/SOW-0051 breadth note as non-blocking because both SOWs + are pending activation shells whose implementation plans rank findings first + and select one package-local or frontend slice at a time. If activation shows + the scope is still too broad, the SOW itself requires remaining warnings to be + justified or split further. +- Same-scope reviewer rerun is required after this fix before merge. + +### Round 40 - 2026-06-06 + +Scope: same staged SOW-only closeout diff after the SOW-0049 residual guard fix. + +Reviewers: + +- `codex`: no actionable finding. Verified SOW-only staged diff, completed + SOW-0047 status, PR #57 merge record, 141-warning follow-up mapping, follow-up + coverage across all residual buckets, and sensitive-data constraints. +- `qwen`: one low finding. SOW-0051's acceptance criteria did not explicitly + include the "split into a narrower follow-up SOW" residual guard used by the + other four follow-up SOWs. +- `glm`: same low SOW-0051 residual-guard finding. Otherwise verified closeout + consistency, safe lifecycle move, PR #57 merge evidence, sensitive-data + hygiene, complete pre-implementation gates, and no unwanted side effects. + +Resolution: + +- Accepted the SOW-0051 finding and updated its acceptance criteria to require + strict Lizard/local Codacy findings to be reduced, explicitly justified, or + split into a narrower follow-up SOW before completion. +- Same-scope reviewer rerun is required after this fix before merge. + +### Round 41 - 2026-06-06 + +Scope: same staged SOW-only closeout diff after the SOW-0051 residual guard fix. + +Reviewers: + +- `codex`: no actionable finding. Verified the staged diff is SOW-only, + SOW-0047 is completed, PR #57 is recorded as merged, all 141 residual warnings + are mapped to follow-up SOWs, residual-closeout guards are present in all five + follow-ups, sensitive-data handling is preserved, and staged diff whitespace + is clean. +- `qwen`: no blocking finding. Verified closeout consistency, lifecycle move + safety, warning-bucket coverage, residual guards, sensitive-data constraints, + complete pre-implementation gates, and review convergence. Noted only + cosmetic historical wording in old review rounds and that SOW-0050's + "split further" wording is less parallel than the other guard bullets. +- `glm`: no blocker. Verified the same closeout state and noted only a cosmetic + point that historical slice-gate `Status: ready...` lines were not rewritten + after their slices merged. + +Resolution: + +- Review converged with no actionable findings. +- Preserved historical slice-gate and review-round wording as audit trail. The + top-level completed status, closeout sub-state, eighth-slice status, Round 37 + through Round 41 review records, and Outcome section state the current + lifecycle and PR #57 merge state. +- Accepted SOW-0050's `split further` wording as equivalent to a narrower + follow-up guard because its implementation plan selects one package-local + slice at a time and its acceptance criteria already require remaining warnings + to be explicitly justified or split further. ## Outcome -Pending. +Completed. + +- The original Codacy/Lizard backlog was reduced through eight merged, + reviewed, tested production slices. +- The highest-risk early hotspots were decomposed with characterization tests, + package race tests, direct strict Lizard checks, local Codacy checks where + relevant, benchmark gates for hot paths, full local gates, PR checks, and + external reviewer convergence. +- Remaining strict source-only warnings are no longer hidden inside this SOW. + They are split into narrower follow-up SOWs with explicit scope, risk, and + validation expectations. ## Lessons Extracted @@ -3659,10 +3828,27 @@ Pending. is needed for a union, intersection, mapped/conditional type, or utility-type expression. Codacy Cloud enforces this convention even when project-native ESLint does not surface the same rule locally. +- Use Lizard's `--warnings_only` mode for closeout backlog grouping. Plain + tabular output lists all functions, not only threshold warnings, and can + inflate file bucket counts if parsed naively. +- Local benchmark failures need environmental triage before code action. When + benchmark failures hit unrelated packages on a SOW-only branch under high + workstation load, record the load evidence and do not refresh baselines, + widen thresholds, or claim a full-green aggregate until the benchmark gate can + run under trustworthy conditions. ## Followup -None yet. +- `SOW-0048`: Codex adapter complexity, including a benchmark prerequisite + before scanner/tailer decomposition. +- `SOW-0049`: Opencode adapter complexity, including a benchmark prerequisite + before SQLite tailer/mapper decomposition. +- `SOW-0050`: residual backend complexity in ingest, presenter, pricing, store, + notify, CLI, and backend tooling paths. +- `SOW-0051`: frontend trace/topology visualization, non-visual component/ + state/utility helpers, and frontend tooling complexity. +- `SOW-0052`: residual ai-agent v2/v3 and Claude-code adapter complexity not + covered by the Codex and Opencode follow-up SOWs. ## Regression Log diff --git a/.agents/sow/pending/SOW-0048-20260606-codex-adapter-complexity.md b/.agents/sow/pending/SOW-0048-20260606-codex-adapter-complexity.md new file mode 100644 index 0000000..2bf13bf --- /dev/null +++ b/.agents/sow/pending/SOW-0048-20260606-codex-adapter-complexity.md @@ -0,0 +1,157 @@ +# SOW-0048 - Codex Adapter Complexity Reduction + +## Status + +Status: open + +Sub-state: pending from SOW-0047 closeout. Not active yet. + +## Requirements + +### Purpose + +Keep the Codex adapter maintainable and safe before it grows more source-format +surface area. + +### User Request + +Continue reducing code-scanning complexity findings autonomously, SOW by SOW, +without weakening tests, performance gates, or security posture. + +### Assistant Understanding + +Facts: + +- SOW-0047 closeout measured 141 strict source-only Lizard warnings after + excluding tests and generated embedded frontend assets. +- The Codex adapter is the largest remaining single adapter cluster. +- Current strict warning evidence includes: + `internal/adapters/codex/tailer.go` with 5 warnings, + `scanner.go` with 3 warnings, `mapper_turn.go` with 3 warnings, + `ops_tools.go` with 3 warnings, `stream.go` and `discovery.go` with 2 each, + and single warnings in `cursor.go`, `mapper.go`, `ops_event.go`, + `ops_enrich.go`, `ops_response.go`, `parser.go`, and `types.go`. + +Inferences: + +- The scanner/tailer warnings are high blast-radius because they cover file + discovery, line streaming, cursor offsets, and real-time updates. +- A Codex adapter benchmark baseline should be added before scanner/tailer + decomposition, mirroring the Claude-code pattern from SOW-0047. + +Unknowns: + +- Which Codex warnings are true maintainability defects versus parser/tailer + state-machine density must be determined by reading the adapter tests and + current source. + +### Acceptance Criteria + +- Codex adapter complexity findings are ranked by risk with file/function + evidence. +- Deterministic Codex `Scan` and `Tail` benchmarks exist before hot-path + scanner/tailer refactors. +- Behavior-preserving refactors are covered by focused adapter tests, package + race tests, fuzz seed corpus, benchmark gate, local Codacy/Lizard analysis, + full gates, and external review convergence. +- Any remaining Codex complexity is justified in this SOW or split into a + narrower follow-up. + +## Analysis + +Sources checked: + +- SOW-0047 closeout warning-only Lizard scan. +- Existing Codex adapter warning files listed above. + +Current state: + +- Codex adapter complexity is now the highest adapter-specific residual + complexity cluster. + +Risks: + +- Tail/scan regressions can drop or replay source records. +- Parser regressions can hide malformed input or change canonical mapping. +- Benchmark baseline changes can add workstation-gate noise if the benchmark is + not deterministic. + +## Pre-Implementation Gate + +Status: ready for future activation. + +Problem / root-cause model: + +- The Codex adapter combines source discovery, rollout streaming, cursor + handling, parser dispatch, and mapper state transitions in a few dense files. +- The correct fix is not a semantic rewrite. It is benchmark-guarded + decomposition around existing adapter contracts. + +Evidence reviewed: + +- SOW-0047 closeout strict warning buckets and function list. + +Affected contracts and surfaces: + +- Codex adapter `Scan`, `Tail`, cursor persistence, parser classification, and + canonical event mapping. +- Benchmark inventory if Codex benchmarks are added to `scripts/check-bench.sh`. + +Existing patterns to reuse: + +- Claude-code benchmark prerequisite and decomposition sequence from SOW-0047. +- Adapter spec/test workflow in `.agents/skills/project-adapters/SKILL.md`. + +Risk and blast radius: + +- High within the Codex adapter. Schema, REST, SSE, and frontend changes are not + expected. + +Sensitive data handling plan: + +- Use synthetic or already-sanitized Codex fixtures only. Do not write raw + source transcripts or prompts to durable artifacts. + +Implementation plan: + +1. Read the Codex adapter spec, tests, fixtures, and current warning functions. +2. Add deterministic Codex `Scan` and `Tail` benchmarks and wire them into the + local benchmark gate if the scanner/tailer paths are selected. +3. Add focused characterization tests for any helper-boundary gaps. +4. Decompose the highest-risk Codex scanner/tailer/parser/mapper functions in + small slices. +5. Run focused tests, package race tests, direct strict Lizard, local Codacy + analysis, benchmark gate, full gates, and external review. + +Validation plan: + +- Focused Codex adapter tests chosen after reading existing coverage. +- `go test ./internal/adapters/codex -count=1` +- `go test -race -count=1 ./internal/adapters/codex` +- Direct strict Lizard on changed Codex production and test files. +- Local Codacy analysis on changed files. +- `scripts/check-bench.sh` when benchmarks are added or hot paths change. +- Full `./scripts/gates.sh`. +- External second-opinion review until convergence. + +Artifact impact plan: + +- Specs: likely `adapter-codex.md`, `quality-gates.md`, and + `testing-strategy.md` if benchmarks are added. +- Runtime project skills: likely unaffected. +- End-user docs: likely unaffected. +- SOW lifecycle: move to `current/` when activated. + +Open-source reference evidence: + +- No new source-format claim is made yet. If implementation changes Codex + format interpretation, inspect upstream source or mirrored repositories first + and cite upstream repository identity plus commit. + +Open decisions: + +- None for the operator. + +## Outcome + +Pending. diff --git a/.agents/sow/pending/SOW-0049-20260606-opencode-adapter-complexity.md b/.agents/sow/pending/SOW-0049-20260606-opencode-adapter-complexity.md new file mode 100644 index 0000000..32a5816 --- /dev/null +++ b/.agents/sow/pending/SOW-0049-20260606-opencode-adapter-complexity.md @@ -0,0 +1,146 @@ +# SOW-0049 - Opencode Adapter Complexity Reduction + +## Status + +Status: open + +Sub-state: pending from SOW-0047 closeout. Not active yet. + +## Requirements + +### Purpose + +Keep the Opencode SQLite adapter maintainable, benchmarked, and safe under +polling/tailing changes. + +### User Request + +Continue reducing code-scanning complexity findings autonomously, SOW by SOW, +while preserving quality, maintainability, performance, and security. + +### Assistant Understanding + +Facts: + +- SOW-0047 closeout measured residual Opencode adapter warnings in + `conn.go`, `cursor.go`, `mapper_ops.go`, `mapper_parts.go`, `migrations.go`, + `tailer.go`, `tailer_batch.go`, `tailer_changes.go`, and `tailer_wal.go`. +- Largest Opencode buckets from the warning-only scan include + `tailer.go` with 3 warnings and two-warning clusters in + `tailer_changes.go`, `mapper_parts.go`, `mapper_ops.go`, and `conn.go`. + +Inferences: + +- The Opencode tailer is likely high risk because it reads an external SQLite + database, detects WAL changes, and maps batches into canonical events. +- A deterministic Opencode scan/tail benchmark should be considered before + refactoring polling or batch mapping hot paths. + +Unknowns: + +- Existing Opencode adapter coverage and benchmark gaps must be confirmed by + reading the package before implementation. + +### Acceptance Criteria + +- Opencode complexity findings are ranked with exact file/function evidence. +- Any SQLite/tailer hot-path refactor has benchmark or focused performance + evidence before implementation. +- Refactors preserve read-only SQLite access, cursor ordering, migration + handling, mapper output, and error surfacing. +- Any remaining Opencode complexity warning is reduced, explicitly justified, + or split into a narrower follow-up SOW before completion. +- Full gates and external review converge before completion. + +## Analysis + +Sources checked: + +- SOW-0047 closeout warning-only Lizard scan. + +Current state: + +- Opencode adapter complexity remains a material residual adapter cluster after + SOW-0047 focused on ai-agent v2 and Claude-code first. + +Risks: + +- SQLite read-mode regressions could violate the read-only source contract. +- Tailer regressions can miss changes, re-emit rows, or corrupt cursor state. +- Mapper regressions can change canonical event order or totals. + +## Pre-Implementation Gate + +Status: ready for future activation. + +Problem / root-cause model: + +- Opencode adapter responsibilities are spread across connection setup, + migration reads, cursor comparison, polling, WAL detection, batch collection, + and canonical mapping. Several functions exceed strict complexity limits. + +Evidence reviewed: + +- SOW-0047 closeout warning buckets. + +Affected contracts and surfaces: + +- Opencode adapter `Scan`, `Tail`, read-only SQLite DSN construction, cursor + comparison, migration discovery, and canonical mapping. + +Existing patterns to reuse: + +- Adapter decomposition and benchmark-gate patterns established in SOW-0047. + +Risk and blast radius: + +- Medium to high within the Opencode adapter; no schema/API/frontend change is + expected. + +Sensitive data handling plan: + +- Use synthetic SQLite fixtures or already-sanitized test fixtures only. Do not + record real database contents in durable artifacts. + +Implementation plan: + +1. Audit Opencode spec, fixtures, tests, and warning functions. +2. Add or strengthen characterization tests before production refactors. +3. Add deterministic benchmarks if scan/tail hot paths are selected. +4. Decompose selected functions into focused helpers without changing adapter + semantics. +5. Validate with focused tests, package race tests, strict Lizard, local Codacy, + benchmark gate where applicable, full gates, and external review. + +Validation plan: + +- Focused Opencode tests selected after coverage audit. +- `go test ./internal/adapters/opencode -count=1` +- `go test -race -count=1 ./internal/adapters/opencode` +- Direct strict Lizard on changed Opencode files. +- Local Codacy analysis on changed files. +- `scripts/check-bench.sh` if benchmarks or hot paths change. +- Full `./scripts/gates.sh`. +- External second-opinion review until convergence. + +Artifact impact plan: + +- Specs: likely `adapter-opencode.md`; quality/testing specs only if benchmark + inventory changes. +- Runtime project skills: likely unaffected. +- End-user docs: likely unaffected. +- SOW lifecycle: move to `current/` when activated. + +Open-source reference evidence: + +- No new source-format claim is made yet. If implementation changes Opencode + interpretation, inspect upstream source or mirrored repositories first and + cite upstream repository identity plus commit. + +Open decisions: + +- None for the operator. + +## Outcome + +Pending. diff --git a/.agents/sow/pending/SOW-0050-20260606-backend-residual-complexity.md b/.agents/sow/pending/SOW-0050-20260606-backend-residual-complexity.md new file mode 100644 index 0000000..2f00aad --- /dev/null +++ b/.agents/sow/pending/SOW-0050-20260606-backend-residual-complexity.md @@ -0,0 +1,158 @@ +# SOW-0050 - Backend And CLI Residual Complexity Reduction + +## Status + +Status: open + +Sub-state: pending from SOW-0047 closeout. Not active yet. + +## Requirements + +### Purpose + +Reduce or justify residual backend and CLI complexity in ingest, presenter, +pricing, store, notify, command entrypoint, and backend tooling paths without +changing product behavior. + +### User Request + +Continue maintainability cleanup autonomously while keeping quality gates, +security, and performance strict. + +### Assistant Understanding + +Facts: + +- SOW-0047 closeout found backend residual warnings in: + `internal/ingest/writer.go`, `worker.go`, `catalog_migrate.go`, + `notify_producer.go`, `resolver.go`, `rollup_backfill.go`, + `rollup_refresh.go`, presenter handlers/middleware, pricing loader, + store DSN/migration helpers, notify subscription replay, `cmd/ai-viewer-*` + command entrypoints, and internal backend helper commands. +- The largest backend buckets were `internal/ingest/writer.go` with 4 warnings, + `internal/ingest/worker.go` with 3, `internal/presenter/middleware.go` with + 4, `internal/presenter/embed.go` with 3, and `internal/pricing/loader.go` + with 4. +- Command/tooling warnings include `cmd/ai-viewer-ingest/main.go`, + `cmd/ai-viewer-ingest/sources.go`, `cmd/ai-viewer-ingest/backfill.go`, + `cmd/ai-viewer-ingest/discovery.go`, and `cmd/ai-viewer-serve/main.go`. + +Inferences: + +- Ingest worker/writer complexity carries the highest data-integrity and + performance risk. +- Presenter/pricing/store complexity is likely lower data-risk but still + important for maintainability and security review. + +Unknowns: + +- Some warnings may be intentional orchestration density; each must be judged + with tests and code evidence before refactoring. + +### Acceptance Criteria + +- Backend and CLI residual findings are ranked into ingest, presenter, + pricing/store, notify, command entrypoint, and backend tooling slices. +- Each selected slice has tests before implementation and benchmarks when a hot + path is touched. +- Remaining warnings are explicitly justified or split further. +- Full gates and external review converge before completion. + +## Analysis + +Sources checked: + +- SOW-0047 closeout warning-only Lizard scan. + +Current state: + +- SOW-0047 already decomposed specific ingest writer and catalog hotspots, but + residual backend warnings remain across several packages. + +Risks: + +- Ingest regressions can affect persisted rows, rollups, catalog totals, FTS, + or notify events. +- Presenter regressions can affect REST/SSE responses and static asset serving. +- Pricing/store regressions can affect cost calculations or database opening. + +## Pre-Implementation Gate + +Status: ready for future activation. + +Problem / root-cause model: + +- Backend residual complexity is no longer concentrated in one file. It is a + set of smaller orchestration, command setup, and validation functions that + need package-local treatment. + +Evidence reviewed: + +- SOW-0047 closeout warning buckets and functions. + +Affected contracts and surfaces: + +- Ingest event application, worker batching, rollups, catalog migration, + presenter REST/static/middleware paths, pricing validation, store connection + setup, notify replay, command entrypoint startup, source discovery, and + backend helper commands. + +Existing patterns to reuse: + +- SOW-0047 ingest writer/catalog decomposition style. +- Existing package-level race tests, coverage gates, and benchmark gate. + +Risk and blast radius: + +- Medium to high for ingest; medium for presenter/security-sensitive request + handling; low to medium for pricing/store and command setup helpers depending + on selected functions. + +Sensitive data handling plan: + +- Use synthetic events and existing sanitized fixtures only. Do not write raw + session content, secrets, private endpoints, or personal data to durable + artifacts. + +Implementation plan: + +1. Rank backend warning clusters by risk and available test coverage. +2. Select one package-local slice at a time. +3. Update specs first if runtime behavior or documented contracts change. +4. Add characterization tests before refactoring. +5. Refactor selected functions into smaller helpers while preserving behavior. +6. Validate with focused tests, package race tests, strict Lizard, local Codacy, + benchmark gate where applicable, full gates, and external review. + +Validation plan: + +- Focused package tests chosen per selected slice. +- Relevant package `go test -count=1` and `go test -race -count=1`. +- Direct strict Lizard on changed files. +- Local Codacy analysis on changed files. +- `scripts/check-bench.sh` for ingest or notify/presenter hot paths. +- Full `./scripts/gates.sh`. +- External second-opinion review until convergence. + +Artifact impact plan: + +- Specs: ingester, presenter, pricing, data-model, security, or deployment + specs only if behavior/contracts change. +- Runtime project skills: update only if a new permanent backend pattern + emerges. +- End-user docs: likely unaffected. +- SOW lifecycle: move to `current/` when activated. + +Open-source reference evidence: + +- This is internal backend maintainability work. External open-source evidence + is required only if a selected slice changes a protocol or dependency + behavior claim. + +Open decisions: + +- None for the operator. + +## Outcome + +Pending. diff --git a/.agents/sow/pending/SOW-0051-20260606-frontend-visualization-complexity.md b/.agents/sow/pending/SOW-0051-20260606-frontend-visualization-complexity.md new file mode 100644 index 0000000..f6befa2 --- /dev/null +++ b/.agents/sow/pending/SOW-0051-20260606-frontend-visualization-complexity.md @@ -0,0 +1,163 @@ +# SOW-0051 - Frontend Residual Complexity Reduction + +## Status + +Status: open + +Sub-state: pending from SOW-0047 closeout. Not active yet. + +## Requirements + +### Purpose + +Reduce frontend trace/topology visualization, non-visual component/state/ +utility, and frontend tooling complexity while preserving the current design and +user-visible behavior. + +### User Request + +Continue maintainability cleanup autonomously. The operator owns visual design; +technical decomposition belongs to the assistant. + +### Assistant Understanding + +Facts: + +- SOW-0047 closeout found frontend residual warnings in trace and topology + surfaces, including `Waterfall.tsx`, `TraceTab.tsx`, `FlameGraph.tsx`, + `TimelineRenderer.tsx`, `TopologyRenderer.tsx`, `ByTurnWaterfall.tsx`, + `SpanDetailDrawer.tsx`, `Stats.tsx`, `SessionsList.tsx`, and visualization + helpers under `frontend/src/viz/`. +- The same residual class includes smaller non-visual frontend helpers such as + `StatusBadge.tsx`, `Tabs.tsx`, `frontend/src/lib/format.ts`, and + `frontend/src/state/theme.ts`. +- A broader source/tooling scan also reports frontend tooling complexity in + `frontend/scripts/check-bundle-size.js`; this SOW tracks that bucket if it is + still present when activated. +- These are user-facing paths, so refactors must preserve layout, labels, + interactions, accessibility, and existing visual behavior. + +Inferences: + +- Many warnings are likely from render callbacks and visualization layout + builders. The right fix is separation of pure data preparation from compact + React/D3 rendering components. + +Unknowns: + +- Which warnings can be reduced without visual changes must be determined by + reading component tests, Playwright coverage, and current screenshots only if + needed. + +### Acceptance Criteria + +- Frontend residual warnings are ranked by user-facing risk, tooling risk, and + test coverage. +- Refactors preserve the current design and user-visible behavior. +- Component/unit tests and Playwright/axe coverage protect changed behavior. +- Strict Lizard/local Codacy findings are reduced, explicitly justified, or + split into a narrower follow-up SOW before completion. +- Full gates and external review converge before completion. + +## Analysis + +Sources checked: + +- SOW-0047 closeout warning-only Lizard scan. + +Current state: + +- Backend and adapter cleanup has progressed further than frontend visualization + cleanup. Trace/topology rendering now deserves its own focused SOW. + +Risks: + +- Visual regressions can reduce operator trust even when tests pass. +- Over-extracting React render logic can make components harder to follow. +- D3/Canvas/SVG changes can affect performance and accessibility. + +## Pre-Implementation Gate + +Status: ready for future activation. + +Problem / root-cause model: + +- Frontend visualization files combine data preparation, layout, styling + decisions, and render callbacks. Smaller component/state/utility and tooling + helpers also carry strict complexity warnings. That structure makes future + visual and frontend-gate changes risky. + +Evidence reviewed: + +- SOW-0047 closeout warning buckets and affected frontend files. + +Affected contracts and surfaces: + +- Session detail trace, timeline, topology, span detail drawer, sessions list, + stats page, visualization helpers, shared UI components, formatting/theme + helpers, and frontend gate tooling scripts. + +Existing patterns to reuse: + +- Existing React component tests, Playwright/axe routes, `frontend/src/viz/` + isolation for visualization logic, frontend tooling self-tests, and the + SOW-0047 frontend filter characterization approach. + +Risk and blast radius: + +- Medium user-facing risk for UI surfaces, medium gate-risk for frontend + tooling scripts, and low backend risk. No REST, SSE, schema, or adapter + behavior change is expected. + +Sensitive data handling plan: + +- Use existing mock data and sanitized fixtures only. Do not add real prompts, + tool output, personal data, or private session content. + +Implementation plan: + +1. Rank frontend visualization, component/state/utility, and tooling warning + clusters by user-facing risk, gate risk, and current test coverage. +2. Add or strengthen component/Playwright tests before refactoring. +3. Extract pure data-preparation helpers from render callbacks where it reduces + real complexity; split utility/tooling branches only when tests preserve the + current behavior. +4. Preserve current design and interactions; do not make visual design changes + without operator design input. +5. Validate with focused Vitest, Playwright/axe, strict Lizard, local Codacy, + full gates, and external review. + +Validation plan: + +- Focused Vitest files selected after coverage audit. +- `cd frontend && npm run lint` +- `cd frontend && npm run typecheck` +- `cd frontend && npm test -- --run --coverage` +- `cd frontend && npm run e2e` +- `cd frontend && npm run e2e:a11y` +- Direct strict Lizard on changed frontend files. +- Local Codacy analysis on changed files. +- Full `./scripts/gates.sh`. +- External second-opinion review until convergence. + +Artifact impact plan: + +- Specs: `frontend-architecture.md` or `ui-pages.md` only if component + contracts or user-visible behavior change. +- Runtime project skills: likely unaffected unless a new frontend decomposition + pattern emerges. +- End-user docs: likely unaffected. +- SOW lifecycle: move to `current/` when activated. + +Open-source reference evidence: + +- This is internal frontend maintainability work. External references are + required only if a selected slice introduces or changes library behavior. + +Open decisions: + +- None for technical decomposition. Visual design changes are out of scope. + +## Outcome + +Pending. diff --git a/.agents/sow/pending/SOW-0052-20260606-residual-adapter-complexity.md b/.agents/sow/pending/SOW-0052-20260606-residual-adapter-complexity.md new file mode 100644 index 0000000..05d5ed1 --- /dev/null +++ b/.agents/sow/pending/SOW-0052-20260606-residual-adapter-complexity.md @@ -0,0 +1,158 @@ +# SOW-0052 - Residual Adapter Complexity Reduction + +## Status + +Status: open + +Sub-state: pending from SOW-0047 closeout. Not active yet. + +## Requirements + +### Purpose + +Reduce or justify remaining adapter complexity not covered by the Codex and +Opencode follow-up SOWs, while preserving source-format behavior. + +### User Request + +Continue maintainability cleanup autonomously, SOW by SOW, with tests, +benchmarks, security checks, and external review before completion. + +### Assistant Understanding + +Facts: + +- SOW-0047 closeout left residual strict source-only warnings in ai-agent v2, + ai-agent v3, and Claude-code adapter paths after the main high-risk mapper + and Claude-code scanner/tailer/parser/ops slices were merged. +- Residual examples include ai-agent v2 cursor/scanner/tailer/helper command + warnings, ai-agent v3 cursor/mapper/parser/scanner/tailer warnings, and + Claude-code cursor/mapper warnings. +- Codex and Opencode residuals are intentionally tracked separately by + SOW-0048 and SOW-0049 because they are larger adapter-specific clusters. + +Inferences: + +- Some residual adapter warnings may be deliberate state-machine density or + helper-command complexity. They still need explicit triage so they are not + hidden by SOW-0047 closeout. +- Parser/scanner/tailer residuals remain higher risk than cursor or helper + command warnings because they process untrusted source bytes. + +Unknowns: + +- Which residual adapter warnings are worth refactoring versus documenting as + intentional must be decided package by package after reading tests and specs. + +### Acceptance Criteria + +- Residual ai-agent v2, ai-agent v3, and Claude-code adapter warnings are + ranked with file/function evidence. +- Parser, scanner, and tailer changes have focused characterization tests and + benchmark evidence where the path is performance-sensitive. +- Cursor and helper-command warnings are either simplified safely or explicitly + justified. +- Any remaining residual adapter warnings are tracked by narrower follow-ups or + justified in this SOW. +- Full gates and external review converge before completion. + +## Analysis + +Sources checked: + +- SOW-0047 closeout warning-only Lizard scan. + +Current state: + +- The largest pre-existing adapter clusters were reduced first, but smaller + ai-agent v2/v3 and Claude-code warnings remain outside the Codex/Opencode + follow-up SOWs. + +Risks: + +- Parser/scanner/tailer regressions can hide malformed input, drop records, + duplicate events, or corrupt cursor state. +- Helper-command changes can affect benchmark/fixture generation and therefore + test reliability. + +## Pre-Implementation Gate + +Status: ready for future activation. + +Problem / root-cause model: + +- Residual adapter complexity is distributed across smaller functions and + helper commands rather than one dominant hotspot. It needs a triage-first + SOW so each warning is either fixed with coverage or intentionally deferred. + +Evidence reviewed: + +- SOW-0047 closeout strict warning buckets and external closeout review. + +Affected contracts and surfaces: + +- ai-agent v2 adapter cursor, scanner, tailer, and helper commands. +- ai-agent v3 adapter cursor, parser, mapper, scanner, and tailer. +- Claude-code adapter cursor and residual mapper dispatch. +- Adapter benchmarks and fixtures if helper commands or hot paths are touched. + +Existing patterns to reuse: + +- SOW-0047 adapter decomposition, characterization, race-test, benchmark, and + external-review workflow. +- `.agents/skills/project-adapters/SKILL.md` adapter modification checklist. + +Risk and blast radius: + +- Medium to high within selected adapters; no REST, SSE, SQLite schema, or + frontend behavior change is expected. + +Sensitive data handling plan: + +- Use synthetic or committed sanitized fixtures only. Do not add raw prompts, + tool output, source IDs, session IDs, private paths, secrets, or personal data + to durable artifacts. + +Implementation plan: + +1. Audit residual ai-agent v2, ai-agent v3, and Claude-code warning functions. +2. Rank by parser/tailer/scanner risk first, then cursor/helper-command risk. +3. Add characterization tests before any production refactor. +4. Refactor selected warnings in small package-local slices. +5. Validate with focused tests, package race tests, direct strict Lizard, local + Codacy, benchmark gate where applicable, full gates, and external review. + +Validation plan: + +- Focused adapter tests selected after coverage audit. +- `go test ./internal/adapters/aiagent_v2 -count=1` +- `go test ./internal/adapters/aiagent_v3 -count=1` +- `go test ./internal/adapters/claude_code -count=1` +- Race tests for each touched adapter package. +- Direct strict Lizard on changed files. +- Local Codacy analysis on changed files. +- `scripts/check-bench.sh` when hot paths or helper benchmark commands change. +- Full `./scripts/gates.sh`. +- External second-opinion review until convergence. + +Artifact impact plan: + +- Specs: affected adapter specs only if behavior/contracts change. +- Runtime project skills: likely unaffected unless a new adapter-decomposition + convention emerges. +- End-user docs: likely unaffected. +- SOW lifecycle: move to `current/` when activated. + +Open-source reference evidence: + +- No new source-format claim is made yet. If implementation changes an adapter's + interpretation of source data, inspect upstream source or mirrored + repositories first and cite upstream repository identity plus commit. + +Open decisions: + +- None for the operator. + +## Outcome + +Pending.