Calculate The Perf Performance

Calculate the Perf (Performance)

Run every package benchmark, compare normalized operations per second with each package's preceding version baseline, and summarize the monorepo-wide movement.

Read .agents/PERFORMANCE.md completely before auditing a workload, editing a perf check, resetting history, or interpreting results. It is the source of truth for benchmark intent, normalization, and history invalidation.

Workflow

1. Locate the repository root by walking upward from the current directory until finding a package.json whose name is codsen-mono. Stop and explain if it cannot be found.

2. Before benchmarking, record git status --short -- packages/*/perf/check.js packages/*/perf/historical.json. These files may already contain user changes; preserve them.

3. For a release-wide audit, inspect every packages/*/perf/check.js; otherwise inspect every working-tree-modified check and each check relevant to the request. Confirm that testme() calls the current built public API with valid, meaningful, deterministic inputs and no mutable state that grows across iterations. Use source types, examples, and tests as evidence. If dist is missing or stale, treat source/types as the contract and rebuild before a runtime smoke test when the user has authorized builds.

4. Before changing the measured workload, run the changelog reconciliation and preservation checks in step 9 against the existing history. Then reset that package's complete perf/historical.json to {} before the next run. This is mandatory for changes to the callable, arguments, options, fixture contents, callbacks, setup placement, or amount of work. Do not reset for imports, comments, or formatting alone. Record every reset; never compare the new workload with old records.

5. If the user requested only an audit or workload repair, do not run perf merely to refill reset histories; leave them {}, complete static/smoke validation, and skip measurement and analysis in steps 6–8. Still complete the reconciliation checks in step 9. Otherwise, from the repository root, run npm run perf. It builds all packages before measuring one at a time; keep other substantial CPU work stopped during measurement. Allow the command to finish because each benchmark runs asynchronously and writes perf/historical.json when its own suite completes. A reset package will gain only a fresh baseline for its new workload.

6. A valid slowdown is a reported result, not a failure of npm run perf. Its baseline remains intact and the score is stored in lastSlowerRun. Execution, abort, invalid-rate and write errors still fail the sweep; inspect package output and Turbo task counts before claiming a complete run. Use npm run perf:check for optional strict validation of the latest saved results without remeasurement. A correctness fix can legitimately cost performance because it now does previously skipped work; investigate avoidable overhead, then explain and retain the necessary cost instead of reverting the fix or promising an open-ended algorithm project.

7. Run:

   node .agents/skills/calculate-the-perf-performance/scripts/analyze-perf.mjs

   Pass --root /absolute/path/to/repo only when running the script outside the repository root. Pass --all when the user asks for the full per-package comparison table.

8. Read the complete analyser output before drawing conclusions. Higher normalized operations per second is better.

9. Run npm run perf:changelogs and npm run perf:changelogs:check to reconcile all retained version-keyed gains above the noise tolerance into each package changelog, including release sections removed by cleaning. Use verified dates (or an explicitly undated historical record when Git and npm provide none), add ### Performance Improvements when needed, retain existing prose, and check that regeneration and cleaning preserve each gain exactly once. Use comma thousands separators for quantities such as scores and large percentages (1,234,567, 12,345.67); preserve fractional precision, version numbers and dates, and check the same formatting in generated notes. Do not advertise first baselines, bookkeeping duplicates or pending slowdowns as improvements. Do this before a workload reset too, preserving valid gains from the previous workload.

10. After benchmarking, run git status --short -- packages/*/perf/historical.json and mention that the benchmark updated performance history files. Preserve those run results unless the user asks otherwise; the mandatory pre-run reset for a changed workload is the sole automatic reset rule.

Normalization model

Let R be the freshly measured perfRef() rate, T the freshly measured testme() rate, and C the canonical opsPerSec exported by perf-ref. Persist T * C / R, not raw T. The shared scale factor C / R makes the reference score equal C — 183, the canonical value exported by perf-ref — and scales the target equally. Compare this relative, normalized score across releases; do not compare raw machine throughput.