@ngockhoale/ukit 3.5.11 → 3.5.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/CHANGELOG.md +62 -0
  2. package/manifests/documentation.yaml +11 -0
  3. package/manifests/platform.full.yaml +39 -2
  4. package/package.json +1 -1
  5. package/scripts/audit/field-replay.mjs +194 -0
  6. package/scripts/audit/field-telemetry.mjs +341 -0
  7. package/scripts/release/candidate-state.mjs +4 -1
  8. package/template_project/.claude/agents/code-reviewer.md +1 -0
  9. package/template_project/.claude/agents/feature-implementer.md +1 -0
  10. package/template_project/.claude/hooks/completion-gate.sh +3 -3
  11. package/template_project/.claude/hooks/context-hardcap-gate.sh +40 -230
  12. package/template_project/.claude/hooks/context-window-guard.sh +1 -1
  13. package/template_project/.claude/hooks/sensitive-data-guard.mjs +297 -13
  14. package/template_project/.claude/settings.json +2 -2
  15. package/template_project/.claude/skills/code-review/SKILL.md +14 -0
  16. package/template_project/.claude/skills/testing-quality/SKILL.md +31 -1
  17. package/template_project/.claude/skills/testing-quality/memory-safe-tests.md +133 -0
  18. package/template_project/.claude/ukit/index/post-edit-verify.mjs +3 -7
  19. package/template_project/.claude/ukit/index/pre-edit-backup.mjs +1 -0
  20. package/template_project/.claude/ukit/index/test-batches-adapters.mjs +261 -0
  21. package/template_project/.claude/ukit/index/test-batches.mjs +829 -0
  22. package/template_project/.claude/ukit/runtime/compact-threshold.mjs +3 -3
  23. package/template_project/.claude/ukit/runtime/execution-ledger.mjs +92 -3
  24. package/template_project/.claude/ukit/runtime/output-compression.mjs +28 -1
  25. package/template_project/.claude/ukit/runtime/safe-patch-core.mjs +22 -0
  26. package/template_project/.claude/ukit/runtime/stop-coordinator.mjs +40 -4
  27. package/template_project/.omp/agents/code-reviewer.md +1 -0
  28. package/template_project/.omp/agents/feature-implementer.md +1 -0
  29. package/template_project/.omp/config.yml +1 -1
  30. package/template_project/AGENTS.md +1 -1
  31. package/template_project/CLAUDE.md +1 -1
  32. package/template_project/docs/AI_HANDOFF/RULES.md +1 -1
  33. package/template_project/docs/memory/testing.md +10 -0
  34. package/template_project/instructions/core.md +1 -1
  35. package/template_project/ukit/storage/config.json +3 -3
@@ -497,28 +497,265 @@ async function evaluate({ rawInput, projectRoot, env }) {
497
497
  return bodies;
498
498
  };
499
499
 
500
+ // Field-telemetry #4 (2026-11-20): quote/substitution/heredoc-aware split of
501
+ // a command into its top-level list segments. The old
502
+ // `command.split(/\|\||&&|;|\||\n/)` cut INSIDE quotes, so `grep -E
503
+ // "release|history"` produced a bare `history` segment, and heredoc body
504
+ // lines were parsed as commands. Returns the segments, the command text with
505
+ // heredoc bodies removed, and the bodies of UNQUOTED heredocs (where `$(…)`
506
+ // still expands); quoted-delimiter heredoc bodies (`<<'EOF'`) are literal
507
+ // data and dropped. Unbalanced input consumes the rest of the text (bash
508
+ // would reject it; the scan stays pessimistic, never skips content).
509
+ const skipBalancedSubst = (src, i) => {
510
+ // src[i] === '$' && src[i+1] === '(' -> index after the matching ')'.
511
+ let d = 1;
512
+ let j = i + 2;
513
+ while (j < src.length && d > 0) {
514
+ const b = src[j];
515
+ if (b === '\\') { j += 2; continue; }
516
+ if (b === "'") { const e = src.indexOf("'", j + 1); j = e === -1 ? src.length : e + 1; continue; }
517
+ if (b === '"') {
518
+ j += 1;
519
+ while (j < src.length && src[j] !== '"') {
520
+ if (src[j] === '\\') { j += 2; continue; }
521
+ if (src[j] === '$' && src[j + 1] === '(') { j = skipBalancedSubst(src, j); continue; }
522
+ j += 1;
523
+ }
524
+ j += 1;
525
+ continue;
526
+ }
527
+ if (b === '`') { const e = src.indexOf('`', j + 1); j = e === -1 ? src.length : e + 1; continue; }
528
+ if (b === '(') d += 1;
529
+ else if (b === ')') d -= 1;
530
+ j += 1;
531
+ }
532
+ return Math.min(j, src.length);
533
+ };
534
+ const splitTopLevel = (command) => {
535
+ const src = String(command ?? '');
536
+ const segments = [];
537
+ const heredocBodies = [];
538
+ let stripped = '';
539
+ let cur = '';
540
+ const seps = []; // separator FOLLOWING each segment ('|', '||', ';', '&&', '&', '\n', '')
541
+ const pending = []; // { delim, quoted, stripTabs }
542
+ const push = (sep = '') => { segments.push(cur); seps.push(sep); cur = ''; };
543
+ let i = 0;
544
+ while (i < src.length) {
545
+ const ch = src[i];
546
+ if (ch === '\\') { const s = src.slice(i, i + 2); cur += s; stripped += s; i += 2; continue; }
547
+ if (ch === "'") {
548
+ const e = src.indexOf("'", i + 1);
549
+ const end = e === -1 ? src.length : e + 1;
550
+ cur += src.slice(i, end); stripped += src.slice(i, end); i = end; continue;
551
+ }
552
+ if (ch === '"') {
553
+ let j = i + 1;
554
+ while (j < src.length && src[j] !== '"') {
555
+ if (src[j] === '\\') { j += 2; continue; }
556
+ if (src[j] === '$' && src[j + 1] === '(') { j = skipBalancedSubst(src, j); continue; }
557
+ if (src[j] === '`') { const e = src.indexOf('`', j + 1); j = e === -1 ? src.length : e + 1; continue; }
558
+ j += 1;
559
+ }
560
+ const end = Math.min(j + 1, src.length);
561
+ cur += src.slice(i, end); stripped += src.slice(i, end); i = end; continue;
562
+ }
563
+ if (ch === '`') {
564
+ const e = src.indexOf('`', i + 1);
565
+ const end = e === -1 ? src.length : e + 1;
566
+ cur += src.slice(i, end); stripped += src.slice(i, end); i = end; continue;
567
+ }
568
+ if (ch === '$' && src[i + 1] === '(') {
569
+ const end = skipBalancedSubst(src, i);
570
+ cur += src.slice(i, end); stripped += src.slice(i, end); i = end; continue;
571
+ }
572
+ if (ch === '<' && src[i + 1] === '<' && src[i + 2] !== '<') {
573
+ // Heredoc operator: record the delimiter; the body starts after the
574
+ // next unquoted newline.
575
+ let j = i + 2;
576
+ const stripTabs = src[j] === '-';
577
+ if (stripTabs) j += 1;
578
+ while (src[j] === ' ' || src[j] === '\t') j += 1;
579
+ const wordStart = j;
580
+ while (j < src.length && !/[\s;&|<>()]/.test(src[j])) {
581
+ if (src[j] === "'") { const e = src.indexOf("'", j + 1); j = e === -1 ? src.length : e + 1; continue; }
582
+ if (src[j] === '"') { const e = src.indexOf('"', j + 1); j = e === -1 ? src.length : e + 1; continue; }
583
+ if (src[j] === '\\') { j += 2; continue; }
584
+ j += 1;
585
+ }
586
+ const word = src.slice(wordStart, j);
587
+ if (word) {
588
+ pending.push({ delim: stripQuotes(word), quoted: /["'\\]/.test(word), stripTabs });
589
+ }
590
+ cur += src.slice(i, j); stripped += src.slice(i, j); i = j; continue;
591
+ }
592
+ if (ch === '\n') {
593
+ push('\n');
594
+ stripped += '\n';
595
+ i += 1;
596
+ // Consume heredoc bodies, in operator order, line by line.
597
+ while (pending.length) {
598
+ const doc = pending.shift();
599
+ const bodyLines = [];
600
+ let closed = false;
601
+ while (i < src.length) {
602
+ const nl = src.indexOf('\n', i);
603
+ const lineEnd = nl === -1 ? src.length : nl;
604
+ const line = src.slice(i, lineEnd);
605
+ i = nl === -1 ? src.length : nl + 1;
606
+ const cmp = doc.stripTabs ? line.replace(/^\t+/, '') : line;
607
+ if (cmp === doc.delim) { closed = true; break; }
608
+ bodyLines.push(line);
609
+ }
610
+ if (!doc.quoted) heredocBodies.push(bodyLines.join('\n'));
611
+ if (!closed) break;
612
+ }
613
+ continue;
614
+ }
615
+ if (ch === ';' || ch === '|') {
616
+ const two = src[i + 1] === ch || (ch === '|' && src[i + 1] === '&');
617
+ push(two ? ch + src[i + 1] : ch);
618
+ stripped += ch;
619
+ i += two ? 2 : 1;
620
+ continue;
621
+ }
622
+ if (ch === '&') {
623
+ const prev = src[i - 1];
624
+ if (src[i + 1] === '&') { push('&&'); stripped += '&&'; i += 2; continue; }
625
+ // `2>&1`, `&>file`, `>&2` are redirects, not list separators.
626
+ if (prev !== '>' && prev !== '<' && src[i + 1] !== '>') { push('&'); stripped += '&'; i += 1; continue; }
627
+ }
628
+ cur += ch; stripped += ch; i += 1;
629
+ }
630
+ push();
631
+ return { segments, seps, stripped, heredocBodies };
632
+ };
633
+
634
+ // grep-family verbs: the first positional operand is the PATTERN (unless
635
+ // -e/-f/--regexp/--file supplied it), never a file. `grep -v "^./\.env"`
636
+ // reads stdin. `-f FILE` / `--file=FILE` does read FILE, so it stays
637
+ // classified like any file operand.
638
+ const PATTERN_VERBS = new Set(['grep', 'egrep', 'fgrep', 'rg', 'zgrep']);
639
+ const PATTERN_FLAG_OPERANDS = new Set([
640
+ '-A', '-B', '-C', '-m', '-d', '-D', '-g', '-t', '-T', '-M', '-j',
641
+ '--include', '--exclude', '--exclude-dir', '--glob', '--type', '--type-not',
642
+ '--max-count', '--context', '--after-context', '--before-context',
643
+ ]);
644
+ const patternOperandIndex = (tokens, verbIdx) => {
645
+ let explicit = false;
646
+ let firstPositional = -1;
647
+ let endOfFlags = false;
648
+ for (let k = verbIdx + 1; k < tokens.length; k += 1) {
649
+ const t = stripQuotes(tokens[k]);
650
+ if (!endOfFlags && t === '--') { endOfFlags = true; continue; }
651
+ if (!endOfFlags && t.startsWith('-') && t.length > 1) {
652
+ if (/^--(regexp|file)(=|$)/.test(t) || /^-[^-]*[ef]/.test(t)) explicit = true;
653
+ // -e PATTERN as a separate word: that word is a pattern, skip it.
654
+ // Flags whose operand is a separate word (`-A 3`, `rg -g '*.ts'`)
655
+ // also consume it, so the operand is never mistaken for the pattern.
656
+ if (/^(-[^-]*e|--regexp)$/.test(t) || PATTERN_FLAG_OPERANDS.has(t)) k += 1;
657
+ continue;
658
+ }
659
+ if (firstPositional === -1) firstPositional = k;
660
+ }
661
+ return explicit ? -1 : firstPositional;
662
+ };
663
+ const regexpOperandIndexes = (tokens, verbIdx) => {
664
+ const idx = new Set();
665
+ for (let k = verbIdx + 1; k < tokens.length; k += 1) {
666
+ const t = stripQuotes(tokens[k]);
667
+ if (t === '--') break;
668
+ if (/^(-[^-]*e|--regexp)$/.test(t)) { idx.add(k + 1); k += 1; }
669
+ }
670
+ return idx;
671
+ };
672
+
673
+ const JQ_SECRET_FIELD_RE = /(token|secret|password|passwd|api[_-]?key|auth|credential|private)/i;
674
+ // Count-only / list-only grep flags (-c, -q, -l, -L, --count, --quiet,
675
+ // --files-with-matches) print a number or file names, never matched text.
676
+ // `-o`/`-n`/`-h` and friends are NOT in this set, so `grep -oE '^KEY_' .env`
677
+ // stays blocked (it prints key names/values).
678
+ // Only REAL flag words count: the operand of -e/--regexp and of operand-taking
679
+ // flags (-A/-m/...) is skipped, so `grep -e -c -e . .env` is not count-only.
680
+ // Any value-printing flag (-o/-n/-b/-A/-B/-C/-f, --only-matching, ...) next to
681
+ // -c/-l/-q disqualifies the call: the guard stays conservative.
682
+ const VALUE_PRINT_LONG_RE = /^--(only-matching|line-number|byte-offset|context|after-context|before-context|file|replace|passthru|json|vimgrep)(=|$)/;
683
+ const isCountOnlyGrep = (tokens, verbIdx) => {
684
+ let countOnly = false;
685
+ for (let k = verbIdx + 1; k < tokens.length; k += 1) {
686
+ const t = stripQuotes(tokens[k]);
687
+ if (t === '--') break;
688
+ if (!t.startsWith('-') || t.length < 2) continue;
689
+ if (/^(-[^-]*e|--regexp)$/.test(t) || PATTERN_FLAG_OPERANDS.has(t)) { k += 1; }
690
+ if (t.startsWith('--')) {
691
+ if (VALUE_PRINT_LONG_RE.test(t)) return false;
692
+ if (/^--(count|quiet|silent|files-with-matches|files-without-match)$/.test(t)) countOnly = true;
693
+ continue;
694
+ }
695
+ // Short cluster: letters up to the first operand-taking letter are flags;
696
+ // the rest of the word is that flag's attached operand.
697
+ const flags = t.slice(1).replace(/([efmABCdDgtTMj]).*$/, '$1');
698
+ if (/[onbABCf]/.test(flags)) return false;
699
+ if (/[cqlL]/.test(flags)) countOnly = true;
700
+ }
701
+ return countOnly;
702
+ };
703
+ // `env | grep -c X` / `printenv | grep -q X`: decided per segment — only an
704
+ // env/printenv segment whose OWN pipe feeds a count-only grep is exempt.
705
+ const envPipedToCountGrep = (segments, seps, si) => {
706
+ if (seps[si] !== '|' || si + 1 >= segments.length) return false;
707
+ const next = splitShellWords(String(segments[si + 1]).trim()).filter((t) => stripQuotes(t) !== '');
708
+ if (!next.length) return false;
709
+ const nextHead = cleanPathToken(next[0]).replace(/^.*\//, '');
710
+ return PATTERN_VERBS.has(nextHead) && isCountOnlyGrep(next, 0);
711
+ };
712
+
500
713
  const scanBashShapes = (command, depth = 0) => {
501
714
  const found = [];
715
+ const { segments, seps, stripped, heredocBodies } = splitTopLevel(command);
502
716
  // Substitution bodies are extracted BEFORE segment splitting — a `;`
503
717
  // inside `$(…)` belongs to the substitution, not the top level. Each body
504
718
  // is scanned recursively AND its words are classified directly: `cat
505
719
  // $(echo .env)` produces the file via substitution, a route no segment
506
- // split can see.
720
+ // split can see. Quoted heredoc bodies are literal (already dropped);
721
+ // unquoted heredoc bodies still expand `$(…)`/backticks, and quotes there
722
+ // are literal characters, so they are neutralised before extraction.
723
+ const substSources = [stripped, ...heredocBodies.map((b) => b.replace(/["']/g, ' '))];
507
724
  if (depth < MAX_SUBST_DEPTH) {
508
- for (const body of extractSubstBodies(command)) {
725
+ for (const body of substSources.flatMap((s) => extractSubstBodies(s))) {
509
726
  for (const inner of scanBashShapes(body, depth + 1)) found.push(inner);
510
- for (const rawTok of splitShellWords(body)) {
511
- const cleaned = cleanPathToken(rawTok);
512
- const kind = classifySecretFile(cleaned);
513
- if (kind && !pathAllowed(cleaned)) {
514
- found.push({ label: `${kind} referenced in command substitution`, value: cleaned, isPath: true });
727
+ // Per segment: a grep-family PATTERN operand (`grep -x id_rsa`,
728
+ // `grep -E "^\.env"`) is a regexp, not a file; a `jq` path
729
+ // (`.env.FOO`) is a JSON path, not a dotenv file.
730
+ for (const bodySeg of splitTopLevel(body).segments) {
731
+ const segTokens = splitShellWords(bodySeg.trim()).filter((t) => stripQuotes(t) !== '');
732
+ if (!segTokens.length) continue;
733
+ const segHead = cleanPathToken(segTokens[0]).replace(/^.*\//, '');
734
+ const skip = new Set();
735
+ if (PATTERN_VERBS.has(segHead)) {
736
+ const pi = patternOperandIndex(segTokens, 0);
737
+ if (pi !== -1) skip.add(pi);
738
+ for (const ri of regexpOperandIndexes(segTokens, 0)) skip.add(ri);
515
739
  }
740
+ segTokens.forEach((rawTok, ti) => {
741
+ if (skip.has(ti)) return;
742
+ const cleaned = cleanPathToken(rawTok);
743
+ const kind = classifySecretFile(cleaned);
744
+ if (!kind || pathAllowed(cleaned)) return;
745
+ if (segHead === 'jq' && /^\.env\./.test(cleaned)) {
746
+ // jq path into a JSON document: only credential-named fields matter.
747
+ if (JQ_SECRET_FIELD_RE.test(cleaned)) {
748
+ found.push({ label: 'jq path reads a credential field of a JSON document referenced in command substitution', value: cleaned, isPath: true });
749
+ }
750
+ return;
751
+ }
752
+ found.push({ label: `${kind} referenced in command substitution`, value: cleaned, isPath: true });
753
+ });
516
754
  }
517
755
  }
518
756
  }
519
- const segments = command.split(/\|\||&&|;|\||\n/);
520
- for (const rawSegment of segments) {
521
- const segment = rawSegment.trim();
757
+ for (let si = 0; si < segments.length; si += 1) {
758
+ const segment = segments[si].trim();
522
759
  if (!segment) continue;
523
760
  // Shell word semantics: whitespace AND `<`/`>` split words, quoted runs
524
761
  // (`"a b"`), escapes and `${IFS}` separators behave like the shell —
@@ -536,6 +773,7 @@ async function evaluate({ rawInput, projectRoot, env }) {
536
773
  const unquote = stripQuotes;
537
774
 
538
775
  if ((head === 'env' || head === 'printenv' || head === 'history') && tokens.length === 1) {
776
+ if (head !== 'history' && envPipedToCountGrep(segments, seps, si)) continue;
539
777
  found.push({ label: `bare \`${head}\` dumps environment/history (may contain tokens)`, value: segment });
540
778
  continue;
541
779
  }
@@ -674,8 +912,19 @@ async function evaluate({ rawInput, projectRoot, env }) {
674
912
  const headBase = effectiveHead.replace(/^.*\//, '');
675
913
 
676
914
  if (DUMP_VERBS.has(headBase)) {
677
- for (const token of tokens.slice(headIdx + 1)) {
678
- const cleaned = cleanPathToken(token);
915
+ const isPatternVerb = PATTERN_VERBS.has(headBase);
916
+ const patternIdx = isPatternVerb ? patternOperandIndex(tokens, headIdx) : -1;
917
+ const regexpIdx = isPatternVerb ? regexpOperandIndexes(tokens, headIdx) : new Set();
918
+ const countOnly = isPatternVerb && isCountOnlyGrep(tokens, headIdx);
919
+ for (let k = headIdx + 1; k < tokens.length; k += 1) {
920
+ if (k === patternIdx || regexpIdx.has(k) || countOnly) continue;
921
+ const token = tokens[k];
922
+ // Attached pattern-file operand (`--file=.env`, `-f.env`) reads that
923
+ // file: classify the value, not the whole flag word.
924
+ const attachedFile = isPatternVerb
925
+ ? /^(?:--file=|-[^-]*f)(.+)$/.exec(stripQuotes(token))
926
+ : null;
927
+ const cleaned = cleanPathToken(attachedFile ? attachedFile[1] : token);
679
928
  const kind = classifySecretFile(cleaned);
680
929
  if (kind && !pathAllowed(cleaned)) {
681
930
  found.push({ label: `${effectiveHead} reads ${kind}`, value: cleaned, isPath: true });
@@ -789,6 +1038,41 @@ async function evaluate({ rawInput, projectRoot, env }) {
789
1038
  return verdict && Array.isArray(verdict.labels) ? verdict.labels : [];
790
1039
  };
791
1040
 
1041
+ // Fixture/doc keys in a Bash command (heredoc test files, `memory propose`
1042
+ // examples) are not secrets: gitleaks/trufflehog ship the same kind of
1043
+ // stopword/placeholder allowlist. A vendor-shaped match whose body holds an
1044
+ // alphabet/digit run or an obvious placeholder word is neutralised before the
1045
+ // scan; random-looking keys are untouched. Bash channel only.
1046
+ const PLACEHOLDER_KEY_RE = /\b(?:sk-|gh[pousr]_)[A-Za-z0-9_-]{20,}/g;
1047
+ const PLACEHOLDER_WORD_RE = /(claude|secret|canary|example|sample|fake|dummy|placeholder|redacted|changeme|your[_-]?key|x{6,})/gi;
1048
+ // A placeholder word must be a real share of the body (>= 1/4), so a random
1049
+ // key that merely contains "secret" somewhere is not exempted.
1050
+ const placeholderShare = (body) => (body.match(PLACEHOLDER_WORD_RE) || []).join('').length / Math.max(1, body.length);
1051
+ // Longest ascending alphabet/digit run (a-b-c-d..., 1-2-3-4...) in a key body.
1052
+ const longestSequentialRun = (body) => {
1053
+ const lower = body.toLowerCase();
1054
+ let run = 1;
1055
+ let best = 1;
1056
+ for (let i = 1; i < lower.length; i += 1) {
1057
+ const sameClass = /[a-z]/.test(lower[i]) === /[a-z]/.test(lower[i - 1]);
1058
+ run = lower.charCodeAt(i) - lower.charCodeAt(i - 1) === 1 && sameClass && /[a-z0-9]/.test(lower[i]) ? run + 1 : 1;
1059
+ if (run > best) best = run;
1060
+ }
1061
+ return best;
1062
+ };
1063
+ const stripPlaceholderKeys = (text) => {
1064
+ const inHeredoc = text.includes('<<');
1065
+ return text.replace(PLACEHOLDER_KEY_RE, (m) => {
1066
+ // Anthropic-shaped keys are never treated as fixtures.
1067
+ if (/^sk-ant-/i.test(m)) return m;
1068
+ const body = m.replace(/^(?:sk-|gh[pousr]_)/, '');
1069
+ const run = longestSequentialRun(body);
1070
+ // Full-alphabet run (26) is never random; a shorter ascending run only
1071
+ // counts as a fixture inside a heredoc body (test file being written).
1072
+ return placeholderShare(body) >= 0.25 || run >= 26 || (inHeredoc && run >= 8) ? '<placeholder-key>' : m;
1073
+ });
1074
+ };
1075
+
792
1076
  const seenLabels = new Set();
793
1077
  for (const { channel, text } of textChannels) {
794
1078
  for (const label of scanTextLabels(text)) {
@@ -808,7 +1092,7 @@ async function evaluate({ rawInput, projectRoot, env }) {
808
1092
  if (allowedValueHashes.has(sha256(finding.value))) continue;
809
1093
  findings.push({ label: `${finding.label} in bash command`, value: finding.value });
810
1094
  }
811
- for (const label of scanTextLabels(bashCommand)) {
1095
+ for (const label of scanTextLabels(stripPlaceholderKeys(bashCommand))) {
812
1096
  const key = `bash:${label}`;
813
1097
  if (seenLabels.has(key)) continue;
814
1098
  seenLabels.add(key);
@@ -213,8 +213,8 @@
213
213
  "hooks": [
214
214
  {
215
215
  "type": "command",
216
- "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/completion-gate.sh\":12",
217
- "timeout": 22
216
+ "command": "node \"$CLAUDE_PROJECT_DIR/.claude/ukit/runtime/hook-chain-runner.mjs\" --emit-verdict - \"$CLAUDE_PROJECT_DIR/.claude/hooks/completion-gate.sh\":16",
217
+ "timeout": 26
218
218
  }
219
219
  ]
220
220
  }
@@ -46,6 +46,20 @@ Check in this order:
46
46
  - misleading naming
47
47
  - drift between docs/tests/source
48
48
 
49
+ ## Test Diffs (when the change adds or edits tests)
50
+
51
+ Run `node .claude/ukit/index/test-batches.mjs audit --changed` first. It statically enforces case budgets and fixture teardown on new test files. Then verify by reading:
52
+
53
+ - **Fixture builds an app/server/client/DB/browser without teardown** → **P1**. Flag `return app` fixtures, `yield` with nothing after it, missing `afterAll`/`afterEach` close, and uncancelled background tasks. These leak per test and caused multi-GB suites in the field.
54
+ - **App per test with unique names / global registries** (`Sanic(f"app_{uuid}")`, OpenAPI/docs singletons, module-level routers keeping app refs) → **P1**, unless teardown unregisters and clears them.
55
+ - **Real data reachable** → **P0** if it writes, P1 if it reads. Examples: hardcoded user/project paths, app paths captured at import time, test env set after the app import, background sweeps/fetch left enabled.
56
+ - **Oversized new test file** over the category budget (count parametrize expansion) without a recorded exception → **P2**. Suggest a split by behaviour that keeps fixture lifecycles intact.
57
+ - **Shared mutable state / order dependence / unclosed files, sessions or subprocesses** → P2 (P1 if it already flakes).
58
+ - **Tests skipped, deselected or xfailed to save time or RAM**, or a full-suite claim backed only by the last batch → **P1**.
59
+ - **Legacy test files**: report violations for refactoring. Never ask to delete, exclude or bulk-rewrite their tests.
60
+
61
+ Details and remediation patterns: `.claude/skills/testing-quality/memory-safe-tests.md`.
62
+
49
63
  ## Workflow
50
64
 
51
65
  ### 1. Gather minimal context
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: testing-quality
3
- description: Quality-driven testing methodology combining Test-Driven Development (TDD) principles with common anti-pattern prevention - enforces test-first implementation and clean, reliable test practices
3
+ description: Quality-driven testing methodology combining Test-Driven Development (TDD) principles with common anti-pattern prevention - enforces test-first implementation and clean, reliable test practices. Also use when writing or planning tests (small focused files, fixture teardown, isolated test data) and when running a full or large test suite, or when tests are slow, swap, or grow in RAM (memory-safe sequential batches).
4
4
  ---
5
5
 
6
6
  # Testing Quality & TDD
@@ -77,6 +77,33 @@ After green only:
77
77
  **Good:** TDD cycle includes integration tests.
78
78
  **Fix:** Write failing integration test first.
79
79
 
80
+ ## Writing Memory-Safe Tests
81
+
82
+ Applies whenever you create or substantially change tests. Full rules + examples: `memory-safe-tests.md` (same folder).
83
+
84
+ 1. **Plan the test layout before writing.** Note the feature, category (unit / integration / app-heavy / e2e), expected case count *including parametrize expansion*, the files you will create, and how fixtures are torn down. Default per-file budgets: unit 40 · integration 20 · app-heavy 10 · e2e 10. Over budget → split by behaviour into focused files. Never write one 200-case file when the cases group into smaller modules. Do not split if it breaks a fixture lifecycle.
85
+ 2. **Every fixture that builds something releases it.** App, server, client, DB, browser, thread, subprocess, async task: use `yield` + `try/finally` (pytest) or `afterEach`/`afterAll` (JS). Cancel background tasks, close connections, unregister the app from global registries, clear docs/OpenAPI singletons. Prefer one app per module (`scope="module"`) when tests do not mutate app state. Never give each test a uniquely named app without unregistering it.
86
+ 3. **Isolate data before import.** Point data, DB, log and telemetry paths to a temp dir *before* the app module is imported. Disable schedulers, sweeps and auto-fetch. App code reads paths from config at call time, not at import. Tests never touch real project data, real auth/system DBs or shared logs.
87
+ 4. **Tests stay independent.** No shared mutable state, no order dependence, and each test passes when run alone.
88
+
89
+ Check your work: `node .claude/ukit/index/test-batches.mjs audit --changed`. It enforces budgets and fixture teardown on **new** test files only. Legacy files are reported, never rewritten, deleted or excluded.
90
+
91
+ ## Memory-Safe Full Suite
92
+
93
+ When the whole suite must run (release gate, "run all tests", large suites, or any suite that has swapped or grown in RAM):
94
+
95
+ ```
96
+ node .claude/ukit/index/test-batches.mjs run --guard <real-data-dir>
97
+ ```
98
+
99
+ - Runs **sequentially in small batches, one fresh process per batch**, so the OS gets RAM back after each batch. Do not add parallel workers (`-n`, `--maxWorkers`) as a memory fix — workers multiply RAM.
100
+ - **Every file always runs.** The RAM threshold only flags heavy batches/files (MB) in the report. It never skips or kills tests. If free RAM is critically low, the runner waits a bounded time and then stops as `INCOMPLETE`. It never reports green with batches left.
101
+ - The aggregated report gives total time, max batch RSS, pass/fail/skip/xfail/error totals, every failed id, unaccounted ids, heavy files and isolation findings. Exit codes: `0 PASS · 1 FAIL · 2 INCOMPLETE · 3 UNSAFE`. Only `PASS` satisfies a release gate.
102
+ - Suspected leak → `detect-leaks --file <heavy file>` for in-process growth evidence, plus `--resource-warnings` to surface unclosed DB connections. Fix the fixture teardown; smaller batches alone do not fix a per-test leak.
103
+ - After the work: delete probe scripts, temp logs and superseded run logs, and remove tools you tried and abandoned (for example xdist). Nothing left over.
104
+
105
+ Never skip, deselect or `xfail` tests to save RAM or time. Never loosen trust/permission settings to make tests pass.
106
+
80
107
  ## Quick Reference
81
108
 
82
109
  | Quality | Good | Bad |
@@ -95,3 +122,6 @@ Before marking work complete:
95
122
  - [ ] All tests pass (green)
96
123
  - [ ] No test-only methods in production code
97
124
  - [ ] Mocks mirror real API structure
125
+ - [ ] New test files within the case budget (or a recorded exception); app/client fixtures torn down
126
+ - [ ] Test paths/env isolated before app import; no real data touched
127
+ - [ ] Full-suite claims backed by a `test-batches.mjs run` verdict of `PASS` (not "the last batch passed")
@@ -0,0 +1,133 @@
1
+ # Memory-Safe Tests — reference
2
+
3
+ Read on demand from `SKILL.md`. Origin: a Python/Sanic backend (~790 files, ~10k tests) where one pytest
4
+ process grew to ~5 GB RSS and swapped for hours; `pytest-xdist -n4` was worse (4 × 1.2–1.9 GB). Batches near
5
+ 750 MB ran ~0.16 s/test, batches near 2.4 GB ran 0.66–1.2 s/test. The leak was per **test**, not per file, so
6
+ smaller files alone did not fix it. Those numbers are that project's incident evidence, not UKit benchmarks.
7
+
8
+ ## 1. Plan the test layout before writing (lightweight)
9
+
10
+ Before creating or substantially changing tests, write a 3–6 line plan in your working notes:
11
+
12
+ ```
13
+ feature: <name> category: unit | integration | app-heavy | e2e
14
+ cases: ~<N incl. parametrize expansion> → files: <file A (cases)>, <file B (cases)>
15
+ fixtures: <what is built, scope, how it is torn down>
16
+ isolation: <temp dirs / env set before app import; background jobs disabled>
17
+ ```
18
+
19
+ Starting budgets (defaults, override in `.ukit/storage/test-batches.json` → `budgets`):
20
+
21
+ | Category | max cases / file | max cases / batch |
22
+ |---|---:|---:|
23
+ | unit | 40 | 100 |
24
+ | integration | 20 | 40 |
25
+ | app-heavy (builds an app/server/client) | 10 | 20 |
26
+ | e2e (browser/full stack) | 10 | 10 |
27
+
28
+ - Count **expanded** cases: `parametrize([...30 items])` is 30 cases, not 1.
29
+ - Split by feature/behaviour (`test_orders_create.py`, `test_orders_refund.py`), never by arbitrary halves.
30
+ - Do not split when it would break a module-scoped fixture's lifecycle or scatter one behaviour across files.
31
+ - A justified exception goes in config: `"exceptions": { "<test file>": "<reason>" }`.
32
+
33
+ ## 2. Fixture lifecycle rules
34
+
35
+ Any fixture that creates an app, server, client, DB connection/pool, browser, worker, thread, subprocess or
36
+ async task MUST release it, including on failure and partial setup:
37
+
38
+ **pytest**
39
+ ```python
40
+ @pytest.fixture(scope="module") # one app per module when tests do not mutate app state
41
+ def app(tmp_path_factory):
42
+ app = create_app(config={"DATA_DIR": tmp_path_factory.mktemp("data"), "SCHEDULER": False})
43
+ try:
44
+ yield app
45
+ finally:
46
+ for task in list(getattr(app, "background_tasks", [])): # framework-specific task handles
47
+ task.cancel()
48
+ app.ctx.db.close()
49
+ Sanic._app_registry.pop(app.name, None) # global app registry (Sanic); clear other singletons too
50
+ openapi_registry.clear() # docs/OpenAPI singletons that accumulate per app
51
+ gc.collect()
52
+ ```
53
+ - Module-level blueprints/routers that remember every app they were attached to: build them inside a
54
+ factory, or detach/reset them in teardown.
55
+ - Unique app names per test (`Sanic(f"app_{uuid}")`) are a leak signal — every name stays registered.
56
+ - Use `request.addfinalizer` or `try/finally` when setup has several steps, so partial setup is cleaned.
57
+
58
+ **vitest / jest**
59
+ ```js
60
+ let server;
61
+ beforeAll(async () => { server = await buildApp({ dataDir: tmpDir }); await server.listen({ port: 0 }); });
62
+ afterAll(async () => { await server?.close(); }); // also clearInterval, await pool.end(), browser.close()
63
+ ```
64
+ - `vi.useFakeTimers()` must be paired with `vi.useRealTimers()`; timers need `clearInterval`/`unref`.
65
+
66
+ Do not promote every fixture to module/session scope — only when reuse cannot leak state between tests.
67
+ Every test must still pass alone and in any order.
68
+
69
+ ## 3. Test data safety (mandatory)
70
+
71
+ - Set the test environment **before the app module is imported** (top of `conftest.py`, vitest
72
+ `setupFiles`/`globalSetup`): data, DB, log, cache, upload and telemetry paths → a temp dir.
73
+ - App code reads paths from config **at call time**. A module-level `DATA_DIR = os.environ[...]` captured at
74
+ import silently points tests at real data; refactor it to read from app config.
75
+ - Disable schedulers, sweeps, auto-fetch, polling and startup migrations unless the test is about them.
76
+ - Never point tests at the real project data dir, real auth/system DB or the shared log file.
77
+ - Prove it: run the suite with `--guard <real data dir>` (repeatable). Any change there makes the run `UNSAFE`.
78
+
79
+ ## 4. Running the full suite: `test-batches.mjs`
80
+
81
+ ```
82
+ node .claude/ukit/index/test-batches.mjs plan # inventory + batches, runs nothing
83
+ node .claude/ukit/index/test-batches.mjs run --guard data # full suite, sequential fresh-process batches
84
+ node .claude/ukit/index/test-batches.mjs audit [--changed] # design-time budgets + fixture teardown + real paths
85
+ node .claude/ukit/index/test-batches.mjs detect-leaks --file <heavy test file>
86
+ ```
87
+ Options: `--framework pytest|vitest|jest`, `--batch-files N` (default 10), `--batch-size <cases>`,
88
+ `--heavy-mb N` (flag only, default 1024), `--critical-free-mb N` (default 200), `--timeout-ms N`,
89
+ `--resource-warnings` (pytest `-W error::ResourceWarning`), `--python <path>`, `--out <dir>`, `--json`,
90
+ `-- <framework args>`. Project defaults: `.ukit/storage/test-batches.json`.
91
+
92
+ Guarantees:
93
+ - Native discovery (pytest `--collect-only` node ids, `vitest list`, `jest --listTests`); batches are whole
94
+ files sorted deterministically; no name-regex filtering. One batch at a time, one fresh process each, no
95
+ parallel workers added; leftover child processes of a batch are reaped before the next one.
96
+ - Every file runs. RAM thresholds only **flag** heavy batches; they never skip, filter or kill tests.
97
+ - Low memory before a batch → bounded wait (2 min), then the run stops as `INCOMPLETE` (never green).
98
+ - Verdicts / exit codes: `PASS` 0 · `FAIL` 1 (test failures/errors, file import errors) · `INCOMPLETE` 2
99
+ (crash, timeout, collection error, unaccounted ids, deferred batches) · `UNSAFE` 3 (guarded path changed).
100
+ `PASS` requires every discovered id (pytest/vitest) or file (jest) reported by a completed batch.
101
+ - Report: `.ukit/storage/test-batches/runs/<run>/summary.json` + `manifest.json` + per-batch `output.log`
102
+ and `batch.json` (duration, ms/test, peak RSS + its source). Only the newest 5 runs are kept; temp files
103
+ and the injected plugin are removed after every run.
104
+ - Peak RSS: macOS `/usr/bin/time -l` (bytes), Linux `/usr/bin/time -v` (KiB), else pytest `ru_maxrss`
105
+ in-process; Windows without these → `unknown`, never 0. A multi-file batch peak is never attributed to one
106
+ file; single-file batches are stored in `history.json` and later plans run measured-heavy files solo.
107
+ - Each batch gets `UKIT_TEST_TMPDIR` (removed afterwards) — conftest/setup files may use it as the root for
108
+ data/log/DB paths.
109
+
110
+ Release gates and "run the whole suite" requests use `run`. Targeted checks while coding still run the one
111
+ relevant test file directly — no batching needed for that.
112
+
113
+ ## 5. Leak diagnosis
114
+
115
+ `detect-leaks --file <f>` runs the file **twice in one process** (pytest `--keep-duplicates`) or samples
116
+ heap every 250 ms (vitest/jest) and classifies `warmup-then-flat` / `some-growth-recheck` /
117
+ `likely-unbounded-growth`. It also lists threads/child processes alive at session end and
118
+ `ResourceWarning`s. It is evidence, not a root cause: confirm with `tracemalloc` snapshots (Python) or
119
+ `--expose-gc` heap snapshots (Node) before changing code. Comparing the peak RSS of two fresh processes does
120
+ not prove a leak.
121
+
122
+ ## 6. Other frameworks — adapter contract
123
+
124
+ Add an adapter object to `test-batches-adapters.mjs` exposing `discover`, `batchCommand`, `parseReport` and
125
+ optionally `leakCommand` (contract documented at the top of that file). Discovery must use the framework's
126
+ own listing; if it cannot list case ids, return `tests: null` (file-level accounting). Never parse
127
+ human-readable output when a machine-readable reporter exists.
128
+
129
+ ## 7. Cleanup after investigation
130
+
131
+ Delete probe scripts, temp logs and superseded run logs you created. Remove tools you tried and abandoned
132
+ (e.g. a `pytest-xdist` dependency or `-n` flags added only for the experiment). Leave the project as you found
133
+ it plus the intended change.
@@ -243,13 +243,7 @@ async function main() {
243
243
  const result = await verifyPostEdit({ projectRoot, payload });
244
244
  if (json) {
245
245
  process.stdout.write(`${JSON.stringify(result)}\n`);
246
- } else if (result.status === 'ok') {
247
- // A plain-text line would make the chain's merged stdout invalid JSON and Claude Code
248
- // would drop a later step's additionalContext (edit-hint). omp's bridge appends step
249
- // stdout verbatim to the tool result, so omp keeps the plain line.
250
- const line = `[ukit-safe-patch] ${result.message}`;
251
- if (payload?.ukit_harness === 'omp' || process.env.UKIT_HARNESS === 'omp') process.stdout.write(`${line}\n`);
252
- else emitSystemMessage(line);
246
+ // status 'ok' is silent: exit 0 with no output (Claude Code hook convention; 798x field noise).
253
247
  } else if (result.status === 'advisory') {
254
248
  process.stderr.write(`[ukit-safe-patch] ${result.message}\n`);
255
249
  process.stderr.write('[ukit-safe-patch] handoff authoring advisory — change is already written; continue updating docs/AI_HANDOFF/.\n');
@@ -276,6 +270,8 @@ async function main() {
276
270
 
277
271
  if (process.argv[1] && path.basename(fileURLToPath(import.meta.url)) === path.basename(process.argv[1])) {
278
272
  main().catch((error) => {
273
+ // OS temp scratch targets are never project scope: skip silently.
274
+ if (error?.osTemp) process.exit(0);
279
275
  process.stderr.write(`[ukit-safe-patch] post-edit ERROR: ${error?.message || error}\n`);
280
276
  // BUG-C23-01: stderr-only crash announces nothing to the user — §8 requires
281
277
  // the paired stdout systemMessage before the non-zero exit.
@@ -90,6 +90,7 @@ async function main() {
90
90
 
91
91
  if (process.argv[1] && path.basename(fileURLToPath(import.meta.url)) === path.basename(process.argv[1])) {
92
92
  main().catch((error) => {
93
+ if (error?.osTemp) process.exit(0); // OS temp scratch target: silent skip
93
94
  process.stderr.write(`[ukit-safe-patch] backup ERROR: ${error?.message || error}\n`);
94
95
  process.exit(1);
95
96
  });