@ngockhoale/ukit 3.4.47 → 3.4.49

package/scripts/perf/perf-measure.md

@@ -1,271 +0,0 @@
-# perf-measure.md — raw measurement notes (TASK-233)
-
-Generated: 2026-09-20T23:07:33.744Z
-
-Appendix source for `docs/AI_REPORT/AI_REVIEW_BUGS_REPORT.md`. Every number in
-`perf-findings.json` comes from one of the four sources below. TASK-236 re-runs
-the identical command for the before/after table (SPEC §5). Two numbers from two
-different snapshots are only comparable once their provenance line agrees.
-
-## 1. Reproduce
-
-```bash
-node scripts/perf/audit-perf.mjs \
-  --telemetry-dir "/Volumes/KHOA_EXTENAL/WORKING_PROJECT/WORKING/UKit/.ukit/storage/cache/hook-latency" \
-  --out "/Volumes/KHOA_EXTENAL/WORKING_PROJECT/WORKING/UKit/scripts/perf/perf-findings.json"
-node scripts/perf/diff-perf-findings.mjs <earlier-snapshot>.json scripts/perf/perf-findings.json
-node --test tests/handoff/c33/perfFindings.test.js
-
-- root: `/Volumes/KHOA_EXTENAL/WORKING_PROJECT/WORKING/UKit`
-- settings.json: `/Volumes/KHOA_EXTENAL/WORKING_PROJECT/WORKING/UKit/template_project/.claude/settings.json`
-- hooks resolved from: `NOT FOUND`
-- telemetry: `/Volumes/KHOA_EXTENAL/WORKING_PROJECT/WORKING/UKit/.ukit/storage/cache/hook-latency` — 62854 rows in 120 files
-- snapshot provenance: generatedAt `2026-09-20T23:07:33.744Z`, telemetryRows: 62854, telemetryFiles: 120 — hooks append continuously, so a report is a point-in-time view, not a stable dataset
-- benchmark iterations per subject: 2
-
-## 2. Process floor (live spawnSync, ms)
-
-| subject | p50 | p95 | max |
-|---|---|---|---|
-| `bash -c true` | 3.13 | 3.13 | 3.13 |
-| `node -e 0` | 16.11 | 16.11 | 16.11 |
-| `node hook-telemetry.mjs --finish` | 19.50 | 19.50 | 19.50 |
-
-A hook row = wrapper bash + node runtime + advisory telemetry child = **3 processes**.
-
-## 3. Telemetry append overhead (O5 — in-process `appendTelemetryRow`, ms)
-
-| subject | iterations | p50 | p95 | max |
-|---|---|---|---|---|
-| `appendTelemetryRow` → throwaway temp root | 2 | 0.407 | 0.407 | 0.407 |
-
-Writer: `template_project/.claude/ukit/runtime/hook-telemetry.mjs`. Measured against a temp project root, so auditing a tree never adds rows to the dataset it is counting.
-
-## 4. Per-hook standalone re-run (`/bin/bash <script>` with `{}` on stdin, ms)
-| hook | p50 | p95 | max |
-|---|---|---|---|
-| _(no settings hook resolvable from this root)_ | | | |
-
-## 5. Router/index helper cold start (ms)
-
-| helper | p50 | p95 | max |
-|---|---|---|---|
-| `skill-router.sh` | 105.2 | 105.2 | 105.2 |
-| `route-task.mjs` | 26.4 | 26.4 | 26.4 |
-| `query-index.mjs` | 23.6 | 23.6 | 23.6 |
-| `resolve-context.mjs` | 21.9 | 21.9 | 21.9 |
-
-## 6. Per-hook telemetry (every hook with rows)
-
-| hook | n | p50 | p95 | max | total |
-|---|---|---|---|---|---|
-| `hook-chain-runner` | 9453 | 80 | 375 | 2020 | 1269815 |
-| `block-dangerous.sh` | 5107 | 83 | 237 | 426 | 461434 |
-| `sensitive-data-guard.sh` | 5001 | 45 | 91 | 1591 | 398855 |
-| `context-hardcap-gate.sh` | 5650 | 55 | 88 | 291 | 334184 |
-| `auto-allow-bash.sh` | 4864 | 50 | 86 | 285 | 264888 |
-| `compress-output.sh` | 4701 | 49 | 66 | 207 | 237025 |
-| `record-execution.sh` | 4880 | 39 | 63 | 178 | 207226 |
-| `handoff-model-guard.sh` | 5603 | 22 | 53 | 189 | 136670 |
-| `verification-guard.sh` | 3520 | 33 | 61 | 137 | 136027 |
-| `skill-router.sh` | 1089 | 52 | 134 | 311 | 68680 |
-| `protect-files.sh` | 1544 | 21 | 156 | 344 | 58507 |
-| `task-watchdog.sh` | 930 | 38 | 216 | 237 | 42736 |
-| `pre-edit-backup.sh` | 732 | 50 | 72 | 216 | 35743 |
-| `stale-spec-guard.sh` | 745 | 46 | 70 | 169 | 34187 |
-| `post-edit-verify.sh` | 716 | 43 | 60 | 145 | 32444 |
-| `vision-router.sh` | 325 | 73 | 220 | 395 | 29834 |
-| `record-execution.mjs` | 2864 | 5 | 16 | 53 | 17607 |
-| `context-window-guard.sh` | 325 | 45 | 84 | 109 | 15798 |
-| `sensitive-data-guard.mjs` | 2812 | 4 | 6 | 15 | 11498 |
-| `completion-gate.sh` | 119 | 80 | 108 | 174 | 9881 |
-| `handoff-resume.sh` | 122 | 31 | 55 | 97 | 4307 |
-| `block-dangerous.mjs` | 1632 | 1 | 2 | 3 | 2334 |
-| `project-important.sh` | 47 | 38 | 61 | 62 | 1962 |
-| `auto-prune-bash.sh` | 19 | 34 | 44 | 44 | 679 |
-| `reset-compact-pressure.sh` | 19 | 34 | 38 | 38 | 647 |
-| `probe-source-only.sh` | 20 | 10 | 22 | 22 | 216 |
-| `probe-s2.sh` | 15 | 10 | 25 | 25 | 164 |
-
-## 7. Stdin stage vs execution split (O3 — the wall-time tail attributed)
-
-A row's `elapsedMs` is the stdin stage plus the hook's own execution. `stageMs`
-(direct rows) and `stdinStageMs` (chain rows) are the first half — the producer's
-time, not the hook's — and `exec` below is the remainder, derived from the SAME
-row so the two halves always sum to it. A row carrying neither field predates the
-split or never staged stdin: it is excluded, never counted as a 0ms stage.
-
-- rows with the split: 0 of 62854
-- overall: stage n/ams p50 / n/ams p95, exec n/ams p50 / n/ams p95
-
-| hook | field | n | stage p50 | stage p95 | exec p50 | exec p95 |
-|---|---|---|---|---|---|---|
-| _(no row carries the split on this tree)_ | | | | | | |
-
-## 8. Per tool / per event cost (chain-runner total where present, else direct sum)
-
-| scope | calls | cost p50 | cost p95 | hook rows/call p50 | direct / chain-runner calls |
-|---|---|---|---|---|---|
-| PostToolUse Bash | 4701 | 87 | 150 | 2 | 2406 / 2295 |
-| PostToolUse Edit | 610 | 129 | 222 | 3 | 351 / 259 |
-| PostToolUse Glob | 60 | 78 | 117 | 2 | 0 / 60 |
-| PostToolUse Grep | 275 | 15 | 101 | 2 | 0 / 275 |
-| PostToolUse Read | 1994 | 37 | 122 | 2 | 393 / 1601 |
-| PostToolUse Write | 103 | 132 | 219 | 4 | 46 / 57 |
-| PreToolUse Bash | 4853 | 307 | 474 | 6 | 2519 / 2334 |
-| PreToolUse Edit | 616 | 328 | 432 | 6 | 356 / 260 |
-| PreToolUse Glob | 60 | 59 | 74 | 2 | 0 / 60 |
-| PreToolUse Grep | 275 | 7 | 74 | 2 | 0 / 275 |
-| PreToolUse Read | 2005 | 39 | 71 | 2 | 404 / 1601 |
-| PreToolUse Write | 112 | 344 | 418 | 7 | 46 / 66 |
-| event (unattributed) (clustered, gap ≤ 1500ms) | 775 | 313 | 1567 | 1 | 752 / 23 |
-| event PostToolUse (clustered, gap ≤ 1500ms) | 7886 | 84 | 154 | 2 | 3339 / 4547 |
-| event PreCompact (clustered, gap ≤ 1500ms) | 6 | 49 | 53 | 1 | 0 / 6 |
-| event PreToolUse (clustered, gap ≤ 1500ms) | 8045 | 255 | 442 | 6 | 3431 / 4614 |
-| event SessionEnd (clustered, gap ≤ 1500ms) | 1 | 2020 | 2020 | 1 | 0 / 1 |
-| event SessionStart (clustered, gap ≤ 1500ms) | 113 | 119 | 289 | 2 | 38 / 75 |
-| event Stop (clustered, gap ≤ 1500ms) | 116 | 81 | 111 | 1 | 113 / 3 |
-| event UserPromptSubmit (clustered, gap ≤ 1500ms) | 349 | 291 | 582 | 4 | 200 / 149 |
-
-## 9. Hook multiplicity proof (repeat-fire check)
-
-| hook | max fires in one tool call | calls observed | fire-count distribution |
-|---|---|---|---|
-| `auto-allow-bash.sh` | 6 | 4859 | {"1":4858,"6":1} |
-| `auto-prune-bash.sh` | 2 | 17 | {"1":15,"2":2} |
-| `block-dangerous.mjs` | 1 | 1632 | {"1":1632} |
-| `block-dangerous.sh` | 24 | 3651 | {"1":3475,"2":59,"3":55,"6":1,"20":1,"22":58,"23":1,"24":1} |
-| `completion-gate.sh` | 3 | 117 | {"1":116,"3":1} |
-| `compress-output.sh` | 3 | 4699 | {"1":4698,"3":1} |
-| `context-hardcap-gate.sh` | 46 | 5601 | {"1":5599,"5":1,"46":1} |
-| `context-window-guard.sh` | 4 | 295 | {"1":272,"2":17,"3":5,"4":1} |
-| `handoff-model-guard.sh` | 46 | 5553 | {"1":5550,"2":1,"5":1,"46":1} |
-| `handoff-resume.sh` | 4 | 109 | {"1":99,"2":8,"3":1,"4":1} |
-| `post-edit-verify.sh` | 4 | 713 | {"1":712,"4":1} |
-| `pre-edit-backup.sh` | 6 | 727 | {"1":726,"6":1} |
-| `probe-s2.sh` | 15 | 1 | {"15":1} |
-| `probe-source-only.sh` | 20 | 1 | {"20":1} |
-| `project-important.sh` | 5 | 37 | {"1":33,"2":1,"3":1,"4":1,"5":1} |
-| `protect-files.sh` | 26 | 992 | {"1":881,"2":57,"3":1,"10":52,"26":1} |
-| `record-execution.mjs` | 1 | 2864 | {"1":2864} |
-| `record-execution.sh` | 4 | 4875 | {"1":4873,"3":1,"4":1} |
-| `reset-compact-pressure.sh` | 2 | 17 | {"1":15,"2":2} |
-| `sensitive-data-guard.mjs` | 3 | 2806 | {"1":2801,"2":4,"3":1} |
-| `sensitive-data-guard.sh` | 21 | 4949 | {"1":4927,"2":15,"3":3,"4":1,"5":2,"21":1} |
-| `skill-router.sh` | 26 | 1029 | {"1":1000,"2":22,"3":5,"4":1,"26":1} |
-| `stale-spec-guard.sh` | 6 | 736 | {"1":731,"2":4,"6":1} |
-| `task-watchdog.sh` | 4 | 925 | {"1":922,"2":2,"4":1} |
-| `verification-guard.sh` | 6 | 3515 | {"1":3514,"6":1} |
-| `vision-router.sh` | 4 | 295 | {"1":272,"2":17,"3":5,"4":1} |
-
-## 10. hook-chain-runner nested per-script (already-consolidated omp path)
-
-| script | n | p50 | p95 | max |
-|---|---|---|---|---|
-| `record-execution.mjs` | 2864 | 5 | 16 | 53 |
-| `sensitive-data-guard.mjs` | 2816 | 4 | 6 | 15 |
-| `handoff-model-guard.sh` | 2641 | 39 | 58 | 166 |
-| `context-hardcap-gate.sh` | 2635 | 68 | 82 | 152 |
-| `auto-allow-bash.sh` | 2350 | 72 | 82 | 426 |
-| `compress-output.sh` | 2295 | 73 | 92 | 169 |
-| `verification-guard.sh` | 2290 | 55 | 67 | 305 |
-| `record-execution.sh` | 1683 | 66 | 129 | 253 |
-| `block-dangerous.mjs` | 1636 | 1 | 2 | 3 |
-| `sensitive-data-guard.sh` | 1634 | 60 | 76 | 203 |
-| `block-dangerous.sh` | 737 | 79 | 150 | 425 |
-| `skill-router.sh` | 486 | 69 | 166 | 280 |
-| `protect-files.sh` | 336 | 50 | 59 | 360 |
-| `stale-spec-guard.sh` | 336 | 57 | 70 | 149 |
-| `pre-edit-backup.sh` | 325 | 59 | 72 | 115 |
-| `post-edit-verify.sh` | 316 | 67 | 90 | 184 |
-| `task-watchdog.sh` | 316 | 59 | 72 | 118 |
-| `vision-router.sh` | 160 | 83 | 161 | 231 |
-| `context-window-guard.sh` | 160 | 59 | 74 | 86 |
-| `project-important.sh` | 87 | 15 | 104 | 529 |
-| `auto-prune-bash.sh` | 86 | 26 | 64 | 75 |
-| `reset-compact-pressure.sh` | 86 | 26 | 56 | 70 |
-| `handoff-resume.sh` | 86 | 56 | 69 | 86 |
-| `reinject-context.sh` | 6 | 49 | 53 | 53 |
-| `completion-gate.sh` | 3 | 111 | 134 | 134 |
-| `t234-silent.sh` | 3 | 2 | 106 | 106 |
-| `session-episode.sh` | 1 | 2020 | 2020 | 2020 |
-
-## 11. settings.json groups (spawn budget per call)
-
-| event | matcher | hooks | registered timeouts | spawns/call |
-|---|---|---|---|---|
-| PreToolUse | Read|Grep|Glob | sensitive-data-guard.mjs:8 | 18s | 3 |
-| PreToolUse | Edit|Write | context-hardcap-gate.sh:8 | 73s | 3 |
-| PreToolUse | Bash | verification-guard.sh:8 | 65s | 3 |
-| PostToolUse | Read|Grep|Glob | record-execution.mjs:8 | 18s | 3 |
-| PostToolUse | Edit|Write | task-watchdog.sh:8 | 34s | 3 |
-| PostToolUse | Bash | record-execution.mjs:8 | 30s | 3 |
-| UserPromptSubmit | (all) | context-window-guard.sh:10 | 60s | 3 |
-| Stop | (all) | completion-gate.sh:8 | 18s | 3 |
-| PreCompact | (all) | reinject-context.sh:8 | 18s | 3 |
-| SessionStart | (all) | handoff-resume.sh:8 | 50s | 3 |
-| SessionEnd | (all) | session-episode.sh:8 | 18s | 3 |
-
-## 12. Recent hot-path additions (`git log --diff-filter=A`)
-
-| commit | date | subject | files added |
-|---|---|---|---|
-| `c0443e73` | 2026-09-20 | handoff: wave 2 — TASK-003 (block-dangerous.mjs port) + TASK-004 (record-execution.mjs + ledger emitter) + manifest module entries | `template_project/.claude/hooks/block-dangerous.mjs`, `template_project/.claude/hooks/record-execution.mjs` |
-| `79f747b6` | 2026-09-20 | handoff: wave 1 — TASK-001 (runner .mjs module-steps) + TASK-002 (sensitive-data-guard port + field-salvage) | `template_project/.claude/hooks/sensitive-data-guard.mjs`, `template_project/.claude/ukit/runtime/hook-field-salvage.mjs` |
-| `6b339905` | 2026-09-20 | handoff: wave 3 — TASK-231, TASK-232 | `template_project/.claude/hooks/session-episode.sh` |
-| `4903ee62` | 2026-09-18 | handoff: restore wave-4a files removed by stale worktree diff | `template_project/.claude/hooks/project-important.sh` |
-| `2b367850` | 2026-09-18 | handoff: wave 4a — TASK-041 (sessionstart wiring, hook template+manifest) | `template_project/.claude/hooks/project-important.sh` |
-| `5ffefb09` | 2026-09-18 | handoff: wave 3 — TASK-038 | `template_project/.claude/ukit/runtime/project-important.mjs`, `template_project/.claude/ukit/runtime/sensitive-value-scanner.mjs` |
-| `ebb846b8` | 2026-09-17 | handoff: R4.5 fix round 1 — TASK-018, TASK-023 | `template_project/.claude/ukit/runtime/hook-chain-budget.mjs` |
-| `c9da9734` | 2026-09-17 | handoff: wave 6 — TASK-025 copy-back (Stop coordinator) | `template_project/.claude/ukit/runtime/stop-coordinator.mjs` |
-| `a1361afd` | 2026-09-17 | handoff: wave 5 — TASK-031 copy-back | `template_project/.claude/ukit/runtime/hook-payload-store.mjs` |
-| `66787f98` | 2026-09-17 | handoff: wave 5 — TASK-019 copy-back | `template_project/.claude/ukit/runtime/hook-telemetry.mjs`, `template_project/.claude/ukit/runtime/hook-telemetry.sh` |
-| `3afc88e6` | 2026-09-17 | handoff: wave 5 — TASK-029 copy-back (context capacity negotiation) | `template_project/.claude/ukit/runtime/context-capacity.mjs` |
-| `6f224875` | 2026-09-17 | handoff: wave 3 — TASK-028 copy-back | `template_project/.claude/ukit/runtime/async-lock.mjs` |
-| `e4b647a3` | 2026-09-17 | handoff: wave 3 — TASK-016 copy-back | `template_project/.claude/ukit/runtime/hook-process.mjs` |
-| `7aa89361` | 2026-09-17 | handoff: wave 2 — TASK-015, TASK-017 | `template_project/.claude/ukit/runtime/transcript-tail.mjs` |
-| `2652bbff` | 2026-09-17 | milestone: TASK-014 bounded stdin transport (H01) | `template_project/.claude/ukit/runtime/hook-input.mjs`, `template_project/.claude/ukit/runtime/hook-input.sh` |
-| `6b40da83` | 2026-09-12 | handoff: wave 1 batch 2 — TASK-016 wall-clock watchdog hook (hardPolicy=split) | `template_project/.claude/hooks/task-watchdog.sh`, `template_project/.claude/ukit/runtime/task-watchdog.mjs` |
-| `0fc81692` | 2026-09-12 | handoff: wave 1 fix — anchor runtime-dir ignores, track lost TASK-014 CLI twin | `template_project/.claude/ukit/index/task-budget-validator.mjs` |
-| `cfc3b7f1` | 2026-09-08 | 2.3.0 — fail-closed sensitive-data gate; contract tables unified to executionContracts.js; tierLane wiring; evidence + vision hardening | `template_project/.claude/hooks/sensitive-data-guard.sh` |
-
-## 13. Findings emitted
-
-| id | evidence | p50 | p95 | status | fixTask |
-|---|---|---|---|---|---|
-| `chain-pretooluse-read-grep-glob` | telemetry | 37 | 72 | confirmed | TASK-234 |
-| `chain-pretooluse-edit-write` | telemetry | 331 | 429 | confirmed | TASK-234 |
-| `chain-pretooluse-bash` | telemetry | 307 | 474 | confirmed | TASK-234 |
-| `chain-posttooluse-read-grep-glob` | telemetry | 37 | 118 | confirmed | TASK-234 |
-| `chain-posttooluse-edit-write` | telemetry | 130 | 222 | confirmed | TASK-234 |
-| `chain-posttooluse-bash` | telemetry | 87 | 150 | confirmed | TASK-234 |
-| `chain-userpromptsubmit-all` | telemetry | 291 | 582 | confirmed | TASK-234 |
-| `chain-stop-all` | telemetry | 81 | 111 | confirmed | TASK-234 |
-| `chain-precompact-all` | telemetry | 49 | 53 | confirmed | TASK-234 |
-| `chain-sessionstart-all` | telemetry | 119 | 289 | confirmed | TASK-234 |
-| `chain-sessionend-all` | telemetry | 2020 | 2020 | confirmed | TASK-234 |
-| `hook-hook-chain-runner` | telemetry | 80 | 375 | confirmed | TASK-234 |
-| `hook-skill-router-sh` | telemetry | 52 | 134 | confirmed | TASK-234 |
-| `hook-vision-router-sh` | telemetry | 73 | 220 | confirmed | TASK-234 |
-| `hook-block-dangerous-sh` | telemetry | 83 | 237 | confirmed | TASK-234 |
-| `hook-context-hardcap-gate-sh` | telemetry | 55 | 88 | confirmed | TASK-234 |
-| `hook-completion-gate-sh` | telemetry | 80 | 108 | confirmed | TASK-234 |
-| `hook-project-important-tail` | telemetry | n/a | 61 | confirmed | TASK-235 |
-| `record-execution-multiplicity` | telemetry | 39 | 63 | not-a-bug | - |
-| `index-router-cold-start` | telemetry | 291 | 582 | confirmed | TASK-234 |
-| `c29-c32-hot-path-additions` | git-log | n/a | n/a | confirmed | TASK-234 |
-| `existing-chain-runner-baseline` | telemetry | 80 | 375 | confirmed | TASK-234 |
-| `process-floor` | micro-benchmark | 38.73741700000001 | 38.73741700000001 | not-a-bug | TASK-234 |
-| `telemetry-append-overhead` | micro-benchmark | 0.407125 | 0.407125 | not-a-bug | - |
-| `stdin-stage-vs-exec-split` | unavailable | n/a | n/a | deferred | - |
-| `hook-sensitive-data-guard-mjs-8-unmeasured` | unavailable | n/a | n/a | deferred | - |
-| `hook-context-hardcap-gate-sh-8-unmeasured` | unavailable | n/a | n/a | deferred | - |
-| `hook-verification-guard-sh-8-unmeasured` | unavailable | n/a | n/a | deferred | - |
-| `hook-record-execution-mjs-8-unmeasured` | unavailable | n/a | n/a | deferred | - |
-| `hook-task-watchdog-sh-8-unmeasured` | unavailable | n/a | n/a | deferred | - |
-| `hook-context-window-guard-sh-10-unmeasured` | unavailable | n/a | n/a | deferred | - |
-| `hook-completion-gate-sh-8-unmeasured` | unavailable | n/a | n/a | deferred | - |
-| `hook-reinject-context-sh-8-unmeasured` | unavailable | n/a | n/a | deferred | - |
-| `hook-handoff-resume-sh-8-unmeasured` | unavailable | n/a | n/a | deferred | - |
-| `hook-session-episode-sh-8-unmeasured` | unavailable | n/a | n/a | deferred | - |
-