docs(01-15): complete performance and audit baseline plan

- summarize deterministic workload and bundle evidence
- record reconciled audit decisions, deviations, and self-check
This commit is contained in:
Marc-André Bombeck committed 2026-07-29 14:44:51 +02:00
1 parent 4ba4ee38cd
commit 8009c251a6
1 file changed
+139
@@ -0,0 +1,139 @@
---
phase: 01-v1-34-1-dashboard-insights-records-admin-and-integration-reliability
plan: "15"
subsystem: testing
tags: [performance-baseline, bundle-budget, audit-ledger, privacy]
requires:
- phase: 01-09
provides: performance, correctness, and read-only live audit source reports
provides:
- bounded deterministic fixtures for Google, reminder, and Health Score workload shapes
- commit-pinned release bundle and watched-route budget evidence
- privacy-safe normalized finding ledger with an executable schema checker
affects: [01-16, 01-17, 01-18, 01-20, 01-21, 01-22, 01-24, 01-25]
tech-stack:
added: []
patterns:
- deterministic local fixture with explicit workload and deadline bounds
- machine-checked Markdown finding records with privacy-dangerous pattern rejection
key-files:
created:
- scripts/v1341-performance-baseline.mjs
- scripts/v1341-audit-ledger-check.mjs
- .planning/phases/01-v1-34-1-dashboard-insights-records-admin-and-integration-reliability/01-PERFORMANCE-BASELINE.md
- .planning/phases/01-v1-34-1-dashboard-insights-records-admin-and-integration-reliability/01-AUDIT-RECONCILIATION.md
- .planning/phases/01-v1-34-1-dashboard-insights-records-admin-and-integration-reliability/01-15-SUMMARY.md
modified: []
key-decisions:
- "Treat fixture timing as local code-shape evidence only; provider, database, cache, rendering, and production behavior remain unmeasured."
- "Keep confirmed, suspected, blocked, and cleared audit states distinct; an adjacent confirmed fix cannot resolve the externally unobserved Google report."
- "Reject credentials, identifiers, network authorities, local user paths, and explicit health values from the normalized audit ledger."
patterns-established:
- "Bounded benchmark: require --fixture, reject production/live target arguments, cap duration, samples, scale, concurrency, and emitted data."
- "Audit ledger: sequential unique IDs plus source, status, severity, category, evidence, path, refutation, impact, requirement, verification, confidence, and unresolved fields."
requirements-completed: [PERF-01, AUD-01, AUD-02, AUD-03, AUD-04, AUD-05]
duration: 15min
completed: 2026-07-29
---
# Phase 01 Plan 15: Performance Baseline and Audit Reconciliation Summary
**Commit-pinned local workload and bundle measurements paired with a 35-finding privacy-safe audit ledger and executable completeness checks**
## Performance
- **Duration:** 15 min
- **Started:** 2026-07-29T12:28:51Z
- **Completed:** 2026-07-29T12:43:28Z
- **Tasks:** 3
- **Files modified:** 5
## Accomplishments
- Benchmarked the observed 786-page Google shape, a 2,000-medication reminder cohort with cleanup backlog, and dense/sparse Health Score processing with fixed concurrency, samples, scale, output, and a 30-second deadline.
- Built and analyzed one isolated source snapshot: 3,133 KB gzip total client chunks passed the 3,140 KB gate; all four watched routes passed with 25–29 KB headroom; Recharts remained one fingerprinted chunk.
- Reconciled 35 unique research, correctness, read-only live, and performance findings while preserving confirmed, suspected, blocked, and cleared states.
- Added a ledger checker that enforces required evidence fields, source/category coverage, sequential unique IDs, status consistency, and privacy-safe content.
## Task Commits
Each task was committed atomically:
1. **Task 1: Add bounded deterministic performance fixtures** - `c0321d2f2` (test)
2. **Task 2: Record release bundle and route-budget evidence** - `eccacd91e` (test)
3. **Task 3: Normalize and validate the audit finding ledger** - `4ba4ee38c` (test)
## Files Created/Modified
- `scripts/v1341-performance-baseline.mjs` - Refuses live/production modes and emits bounded cold/warm fixture evidence without sensitive data.
- `scripts/v1341-audit-ledger-check.mjs` - Validates finding structure, semantic consistency, source/category coverage, and privacy constraints.
- `01-PERFORMANCE-BASELINE.md` - Records environment, fixture scale, cold/median/p95 timings, heap deltas, bundle budgets, and explicit evidence limits.
- `01-AUDIT-RECONCILIATION.md` - Maps 35 deduplicated findings to requirements and smallest planned verification.
- `01-15-SUMMARY.md` - Captures execution evidence, decisions, deviations, and readiness.
## Decisions Made
- Local fixture timings are baselines for regression comparison, not production capacity or latency claims.
- The Health Score fixture measures dense/sparse construction, canonical selection, and a stable composite proxy; exact production score parity remains a database-backed verification requirement.
- The existing bundle checker does not emit Settings, Admin, or Documents rows while a watched-route budget is active. Their eager-import risk remains labelled as unmeasured rather than assigned invented figures.
- The reporter-specific Google sync failure remains externally blocked; confirmed cache, pagination, and outcome defects are independently actionable but cannot substantiate that resolution claim.
## Deviations from Plan
### Auto-fixed Issues
**1. [Rule 3 - Blocking] Raised only the verification build heap**
- **Found during:** Task 2 (release build and bundle evidence)
- **Issue:** The default build compiled successfully but its TypeScript worker exhausted Node's 4 GiB heap.
- **Fix:** Re-ran the build with an 8 GiB process heap in an isolated source snapshot; no repository or runtime limit changed.
- **Files modified:** None
- **Verification:** Production build completed and `node scripts/check-bundle-budget.mjs --check` passed.
- **Committed in:** `eccacd91e`
**2. [Rule 1 - Bug] Kept regenerated Markdown free of trailing whitespace**
- **Found during:** Task 2 report verification
- **Issue:** The generator used Markdown hard-break whitespace, causing `git diff --check` warnings.
- **Fix:** Emitted blank-separated metadata fields and regenerated the checked report.
- **Files modified:** `scripts/v1341-performance-baseline.mjs`, `01-PERFORMANCE-BASELINE.md`
- **Verification:** `git diff --check` returned clean.
- **Committed in:** `eccacd91e`
---
**Total deviations:** 2 auto-fixed (1 blocking issue, 1 generated-report bug)
**Impact on plan:** Both changes were verification-only and preserved the prohibition on production load, optimization, dependency changes, and product-source edits.
## Issues Encountered
- A first isolated snapshot used an external `node_modules` symlink that Turbopack correctly rejected; an APFS-cloned dependency directory kept resolution inside the snapshot.
- Generated Prisma artifacts are intentionally untracked and had to be supplied as build prerequisites. They were not treated as product-source changes.
## User Setup Required
None - no external service configuration or manual action is required.
## Next Phase Readiness
- Plans 16–22 can use stable finding IDs, requirement mappings, and planned verification fields to distinguish implementation work from hypotheses.
- Plan 24 should rerun the bundle gate after the final merge, add direct Settings/Admin/Documents route evidence if needed, and reconcile each unresolved finding without weakening privacy or screening.
- Aggregate bundle headroom is only 7 KB, so the final merged build must remeasure rather than relying on this intermediate snapshot.
## Self-Check: PASSED
- All five owned files exist.
- Task commits `c0321d2f2`, `eccacd91e`, and `4ba4ee38c` exist on the branch.
- Fresh bounded fixture execution, ledger schema/privacy check, bundle budget gate, and `git diff --check` all pass.
---
*Phase: 01-v1-34-1-dashboard-insights-records-admin-and-integration-reliability*
*Completed: 2026-07-29*