@futurelastic/colab-handbook 1.13.0-rc.26 → 1.13.0-rc.27

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.
package/audit/audit.mjs CHANGED
@@ -99,6 +99,7 @@ const releaseRunner = require("../tools/lib/release-runner.js"); // #453
99
99
  const { parseWorkflowOn, workflowFiresOnTag, prereleaseTagTriggers, workflowsFiringOnBranchPush } = require("../tools/lib/workflow-triggers.js");
100
100
  const shipBatch = require("../tools/lib/ship-batch.js");
101
101
  const ciProfile = require("../tools/lib/ci-profile.js"); // #559
102
+ const thresholdsLib = require("../tools/lib/thresholds.js"); // #560
102
103
  // #383: where migrations live — the one rule `colab ship`'s gate and `release cut` read; the audit
103
104
  // validates the `migrations:` declaration against it and reports a `*/migrations/` dir it misses.
104
105
  const migrationPaths = require("../tools/lib/migration-paths.js");
@@ -219,7 +220,7 @@ function parseScalarValue(raw) {
219
220
  return val;
220
221
  }
221
222
 
222
- const NESTED_MAP_KEYS = new Set(["release", "owner", "gate"]); // owner: #394 · gate: #410
223
+ const NESTED_MAP_KEYS = new Set(["release", "owner", "gate", "thresholds"]); // owner: #394 · gate: #410 · thresholds: #560
223
224
 
224
225
  function parseFlatYaml(text) {
225
226
  const out = {};
@@ -1054,7 +1055,7 @@ function yamlRawValue(text, key) {
1054
1055
  return m[1].replace(/\s+#.*$/, "").trim();
1055
1056
  }
1056
1057
 
1057
- const DURATION_MIN_DAYS = 180; // below this, silence — see audit-exposure.test.js's pinned
1058
+ const DURATION_MIN_DAYS = thresholdsLib.DEFAULTS["transitional-days"]; // 180, the DEFAULT (#560: a repo may declare thresholds.transitional-days); below this, silence — see audit-exposure.test.js's pinned
1058
1059
  // "transitional descriptor is clean" case, which this
1059
1060
  // threshold exists to keep passing untouched: a descriptor
1060
1061
  // committed moments ago must never earn a duration line.
@@ -1092,9 +1093,9 @@ function declaredStateAge(src, key) {
1092
1093
 
1093
1094
  // Prose for a declaredStateAge() result, or null when it is too recent to be worth saying
1094
1095
  // (the DURATION_MIN_DAYS gate — the caller must check this before calling warn()).
1095
- function renderDuration(age) {
1096
+ function renderDuration(age, minDays = DURATION_MIN_DAYS) {
1096
1097
  const days = Math.floor((Date.now() / 1000 - age.epoch) / DURATION_DAY_SECONDS);
1097
- if (days < DURATION_MIN_DAYS) return null;
1098
+ if (days < minDays) return null;
1098
1099
  const months = Math.floor(days / 30); // coarse on purpose — a report, not a countdown
1099
1100
  return `${age.lowerBound ? "at least " : ""}${months} month${months === 1 ? "" : "s"}`;
1100
1101
  }
@@ -1123,12 +1124,15 @@ function auditRepo(target, ctx) {
1123
1124
  // ---- .github/project.yml -------------------------------------------------
1124
1125
  const rawCfg = src.readFile(".github/project.yml");
1125
1126
  let cfg = null;
1127
+ // #560: the advisory thresholds this run applies — defaults until the descriptor declares otherwise.
1128
+ let th = thresholdsLib.parseThresholds(null);
1126
1129
  if (rawCfg === null) {
1127
1130
  fail("no .github/project.yml — repo is undescribed (tier/trunk/deploy unknown)");
1128
1131
  } else {
1129
1132
  const { data, problems } = parseFlatYaml(rawCfg);
1130
1133
  problems.forEach((p) => fail(`project.yml: ${p}`));
1131
1134
  cfg = data;
1135
+ th = thresholdsLib.parseThresholds(cfg);
1132
1136
  // `tier` is deliberately NOT in this list as of #144: it used to be the sole axis of
1133
1137
  // record and therefore unconditionally required, but a descriptor may now answer the
1134
1138
  // gate-count question with `exposure` instead — see the "axis of record" check below,
@@ -1326,6 +1330,12 @@ function auditRepo(target, ctx) {
1326
1330
  if (!f.valid) fail(`${f.reason} — see project.schema.md, ci-wait-factor`);
1327
1331
  }
1328
1332
 
1333
+ // ---- thresholds (#560) --------------------------------------------------------
1334
+ // Repo-declared values for the advisory thresholds (tools/lib/thresholds.js, the one reading
1335
+ // `colab thresholds` and every consumer use). A malformed entry fails here and in the CI
1336
+ // templates' descriptor check (the #416 pattern); every consumer falls back to the default.
1337
+ thresholdsLib.parseThresholds(cfg).problems.forEach((p) => fail(`${p} — see project.schema.md, thresholds`));
1338
+
1329
1339
  // ---- migrations (#383) ----------------------------------------------------
1330
1340
  // Where the repo's migrations live, beyond the two defaults (database/migrations/,
1331
1341
  // prisma/migrations/) — tools/lib/migration-paths.js is the one reading, shared with
@@ -1478,7 +1488,7 @@ function auditRepo(target, ctx) {
1478
1488
  );
1479
1489
  }
1480
1490
  const exposureAge = declaredStateAge(src, "exposure");
1481
- const durationLine = exposureAge && renderDuration(exposureAge);
1491
+ const durationLine = exposureAge && renderDuration(exposureAge, th.values["transitional-days"]);
1482
1492
  if (durationLine) {
1483
1493
  warn(`exposure: none has held for ${durationLine} (per the descriptor's own git history) — visible so a long-running transitional state does not go unnoticed`);
1484
1494
  }
@@ -1568,7 +1578,7 @@ function auditRepo(target, ctx) {
1568
1578
  );
1569
1579
  }
1570
1580
  const channelsAge = declaredStateAge(src, "channels");
1571
- const durationLine = channelsAge && renderDuration(channelsAge);
1581
+ const durationLine = channelsAge && renderDuration(channelsAge, th.values["transitional-days"]);
1572
1582
  if (durationLine) {
1573
1583
  warn(`channels: [none] has held for ${durationLine} (per the descriptor's own git history) — visible so a long-running transitional state does not go unnoticed`);
1574
1584
  }
@@ -1713,7 +1723,7 @@ function auditRepo(target, ctx) {
1713
1723
  // ---- CLAUDE.md is a router, not an archive (#64) -------------------------
1714
1724
  // Unconditional: this is a repo-doc concern, not a tier/deploy one, and it applies to
1715
1725
  // the handbook's OWN CLAUDE.md too (not a stamp check, so it is not gated on !isSelf).
1716
- checkClaudeMdSize(src, warn);
1726
+ checkClaudeMdSize(src, warn, th.values);
1717
1727
  // #417: same posture — a tool block loaded twice, or the Conventions block moved out of the
1718
1728
  // file tools look it up in, is a repo-doc concern on every repo, the handbook's own included.
1719
1729
  checkInstructionFileBlocks(src, warn);
@@ -2215,9 +2225,10 @@ function checkReleaseBranch(cfg, trunk, branches, fail, warn, deploy) {
2215
2225
  // a starting point rather than a recommendation", wanting calibration across adopting repos
2216
2226
  // before anything here becomes a hard gate — the goal is a finding with the measured number
2217
2227
  // ("state the condition"), not a build-breaking assertion of a still-uncalibrated one.
2218
- const CLAUDE_MD_MAX_BYTES = 40 * 1024; // near the handbook's own cited worst case (39 KB / 452 lines)
2219
- const CLAUDE_MD_LINE_MULTIPLE = 6; // "some small multiple of the [file's] median row"
2220
- const CLAUDE_MD_LINE_ABS_FLOOR = 2048; // below this, flagging on multiple alone is noise (tiny medians make everything look huge)
2228
+ const CLAUDE_MD_MAX_BYTES = thresholdsLib.DEFAULTS["claude-md-kb"] * 1024; // 40 KB by default (#560) — near the handbook's own cited worst case (39 KB / 452 lines)
2229
+ // The per-line multiple ("some small multiple of the [file's] median row", default 6) and its
2230
+ // absolute floor (default 2048 bytes — below it, flagging on the multiple alone is noise: tiny
2231
+ // medians make everything look huge) live in tools/lib/thresholds.js with the ceiling (#560).
2221
2232
 
2222
2233
  // #117: the byte ceiling above was built to catch hand-written accretion, but it counts
2223
2234
  // TOTAL file bytes — which also charges a repo for content it cannot shorten by the rule's
@@ -2450,7 +2461,11 @@ function checkAnchorLinks(src, fail) {
2450
2461
  }
2451
2462
  }
2452
2463
 
2453
- function checkClaudeMdSize(src, warn) {
2464
+ function checkClaudeMdSize(src, warn, limits = thresholdsLib.DEFAULTS) {
2465
+ // #560: the three numbers below are the defaults; a repo may declare its own under `thresholds:`.
2466
+ const maxBytes = limits["claude-md-kb"] * 1024;
2467
+ const lineMultiple = limits["claude-md-line-multiple"];
2468
+ const lineFloor = limits["claude-md-line-floor-bytes"];
2454
2469
  // #417: measure what is LOADED, not one file. A thin-shell CLAUDE.md (`@AGENTS.md` plus the
2455
2470
  // by-name tool blocks) is tiny by construction, so measuring it alone would neuter this guard
2456
2471
  // while a bloated AGENTS.md rides in behind it on every turn. The loaded set is CLAUDE.md plus
@@ -2473,7 +2488,7 @@ function checkClaudeMdSize(src, warn) {
2473
2488
  }
2474
2489
  const derivedBytes = Math.max(0, bytes - authoredBytes);
2475
2490
 
2476
- if (authoredBytes > CLAUDE_MD_MAX_BYTES) {
2491
+ if (authoredBytes > maxBytes) {
2477
2492
  const totalNote = derivedBytes > 0
2478
2493
  ? ` (of ${bytes} bytes total; ${derivedBytes} bytes are marked colab:derived and excluded — #117)`
2479
2494
  : "";
@@ -2482,7 +2497,7 @@ function checkClaudeMdSize(src, warn) {
2482
2497
  : `CLAUDE.md plus its @-imports (${files.slice(1).map((f) => f.path).join(", ")}) is`;
2483
2498
  warn(
2484
2499
  `${subject} ${authoredBytes} bytes (~${(authoredBytes / 1024).toFixed(1)} KB)${totalNote} — over the ` +
2485
- `${CLAUDE_MD_MAX_BYTES / 1024} KB advisory ceiling (#64). It is loaded in full into every session before ` +
2500
+ `${maxBytes / 1024} KB advisory ceiling (#64${maxBytes === CLAUDE_MD_MAX_BYTES ? "" : ", declared in thresholds.claude-md-kb"}). It is loaded in full into every session before ` +
2486
2501
  `any work starts; if the knowledge belongs in docs/, the ${files.length === 1 ? "CLAUDE.md" : "instruction-file"} change is a pointer, not a copy (code-wrap A2)`,
2487
2502
  );
2488
2503
  }
@@ -2497,7 +2512,7 @@ function checkClaudeMdSize(src, warn) {
2497
2512
  if (lens.length < 2) continue; // no meaningful median from 0 or 1 lines
2498
2513
  const median = lens[Math.floor(lens.length / 2)];
2499
2514
  const worst = lens[lens.length - 1];
2500
- if (median > 0 && worst > CLAUDE_MD_LINE_ABS_FLOOR && worst > median * CLAUDE_MD_LINE_MULTIPLE) {
2515
+ if (median > 0 && worst > lineFloor && worst > median * lineMultiple) {
2501
2516
  const pct = ((worst / f.authoredBytes) * 100).toFixed(1);
2502
2517
  warn(
2503
2518
  `${f.path} has a single line of ${worst} bytes — ${(worst / median).toFixed(1)}x the file's median line ` +
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.13.0-rc.26"
36
+ "version": "1.13.0-rc.27"
37
37
  }
@@ -296,6 +296,40 @@ jobs:
296
296
  exit 1
297
297
  fi ;;
298
298
  esac
299
+ # thresholds (#560): one level of `name: whole number`, each name known and at or above its
300
+ # floor — the table in tools/lib/thresholds.js (SPEC), which a test holds this list to.
301
+ # A bad entry falls back to the default everywhere, silently, so it fails here.
302
+ bad=0
303
+ while IFS= read -r t; do
304
+ case "$t" in =*)
305
+ echo "::error file=.github/project.yml::thresholds is '${t#=}', expected a map of 'name: whole number' pairs. See project.schema.md, thresholds."
306
+ bad=1; continue ;;
307
+ esac
308
+ k="${t%%:*}"
309
+ n="$(printf '%s' "${t#*:}" | sed -E -e 's/^[[:space:]]+//' -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
310
+ case "$k" in
311
+ hot-file-count|claude-md-line-multiple) min=2 ;;
312
+ dependents-count|hold-stale-days|smoke-minutes|claude-md-kb|transitional-days) min=1 ;;
313
+ claude-md-line-floor-bytes|doc-budget-slack) min=0 ;;
314
+ *) echo "::error file=.github/project.yml::thresholds.$k is not a known threshold (colab thresholds lists them). See project.schema.md, thresholds."
315
+ bad=1; continue ;;
316
+ esac
317
+ case "$n" in ''|'~'|null) continue ;; esac
318
+ if printf '%s\n' "$n" | grep -Eq '^[0-9]{1,9}$' && [ "$n" -ge "$min" ]; then
319
+ echo "thresholds.$k: $n — ok"
320
+ else
321
+ echo "::error file=.github/project.yml::thresholds.$k is '$n', expected a whole number >= $min. Every reader ignores it and uses the default. See project.schema.md, thresholds."
322
+ bad=1
323
+ fi
324
+ done < <(awk '
325
+ /^thresholds[[:space:]]*:/ { b = 1; v = $0
326
+ sub(/^thresholds[[:space:]]*:[[:space:]]*/, "", v); sub(/[[:space:]]+#.*$/, "", v); sub(/[[:space:]]+$/, "", v)
327
+ if (v != "" && v != "~" && v != "null") print "=" v
328
+ next }
329
+ b && /^[[:space:]]*(#|$)/ { next }
330
+ b && /^[[:space:]]/ { l = $0; sub(/^[[:space:]]+/, "", l); sub(/[[:space:]]+#.*$/, "", l); sub(/[[:space:]]+$/, "", l); print l; next }
331
+ { b = 0 }' .github/project.yml)
332
+ [ "$bad" = 0 ] || exit 1
299
333
 
300
334
  # ---------------------------------------------------------------------------
301
335
  # Toolchain resolution. Precedence, highest first:
@@ -291,6 +291,40 @@ jobs:
291
291
  exit 1
292
292
  fi ;;
293
293
  esac
294
+ # thresholds (#560): one level of `name: whole number`, each name known and at or above its
295
+ # floor — the table in tools/lib/thresholds.js (SPEC), which a test holds this list to.
296
+ # A bad entry falls back to the default everywhere, silently, so it fails here.
297
+ bad=0
298
+ while IFS= read -r t; do
299
+ case "$t" in =*)
300
+ echo "::error file=.github/project.yml::thresholds is '${t#=}', expected a map of 'name: whole number' pairs. See project.schema.md, thresholds."
301
+ bad=1; continue ;;
302
+ esac
303
+ k="${t%%:*}"
304
+ n="$(printf '%s' "${t#*:}" | sed -E -e 's/^[[:space:]]+//' -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
305
+ case "$k" in
306
+ hot-file-count|claude-md-line-multiple) min=2 ;;
307
+ dependents-count|hold-stale-days|smoke-minutes|claude-md-kb|transitional-days) min=1 ;;
308
+ claude-md-line-floor-bytes|doc-budget-slack) min=0 ;;
309
+ *) echo "::error file=.github/project.yml::thresholds.$k is not a known threshold (colab thresholds lists them). See project.schema.md, thresholds."
310
+ bad=1; continue ;;
311
+ esac
312
+ case "$n" in ''|'~'|null) continue ;; esac
313
+ if printf '%s\n' "$n" | grep -Eq '^[0-9]{1,9}$' && [ "$n" -ge "$min" ]; then
314
+ echo "thresholds.$k: $n — ok"
315
+ else
316
+ echo "::error file=.github/project.yml::thresholds.$k is '$n', expected a whole number >= $min. Every reader ignores it and uses the default. See project.schema.md, thresholds."
317
+ bad=1
318
+ fi
319
+ done < <(awk '
320
+ /^thresholds[[:space:]]*:/ { b = 1; v = $0
321
+ sub(/^thresholds[[:space:]]*:[[:space:]]*/, "", v); sub(/[[:space:]]+#.*$/, "", v); sub(/[[:space:]]+$/, "", v)
322
+ if (v != "" && v != "~" && v != "null") print "=" v
323
+ next }
324
+ b && /^[[:space:]]*(#|$)/ { next }
325
+ b && /^[[:space:]]/ { l = $0; sub(/^[[:space:]]+/, "", l); sub(/[[:space:]]+#.*$/, "", l); sub(/[[:space:]]+$/, "", l); print l; next }
326
+ { b = 0 }' .github/project.yml)
327
+ [ "$bad" = 0 ] || exit 1
294
328
 
295
329
  # ---------------------------------------------------------------------------
296
330
  # Toolchain resolution. Precedence, highest first:
@@ -282,6 +282,40 @@ jobs:
282
282
  exit 1
283
283
  fi ;;
284
284
  esac
285
+ # thresholds (#560): one level of `name: whole number`, each name known and at or above its
286
+ # floor — the table in tools/lib/thresholds.js (SPEC), which a test holds this list to.
287
+ # A bad entry falls back to the default everywhere, silently, so it fails here.
288
+ bad=0
289
+ while IFS= read -r t; do
290
+ case "$t" in =*)
291
+ echo "::error file=.github/project.yml::thresholds is '${t#=}', expected a map of 'name: whole number' pairs. See project.schema.md, thresholds."
292
+ bad=1; continue ;;
293
+ esac
294
+ k="${t%%:*}"
295
+ n="$(printf '%s' "${t#*:}" | sed -E -e 's/^[[:space:]]+//' -e 's/^"(.*)"$/\1/' -e "s/^'(.*)'\$/\\1/")"
296
+ case "$k" in
297
+ hot-file-count|claude-md-line-multiple) min=2 ;;
298
+ dependents-count|hold-stale-days|smoke-minutes|claude-md-kb|transitional-days) min=1 ;;
299
+ claude-md-line-floor-bytes|doc-budget-slack) min=0 ;;
300
+ *) echo "::error file=.github/project.yml::thresholds.$k is not a known threshold (colab thresholds lists them). See project.schema.md, thresholds."
301
+ bad=1; continue ;;
302
+ esac
303
+ case "$n" in ''|'~'|null) continue ;; esac
304
+ if printf '%s\n' "$n" | grep -Eq '^[0-9]{1,9}$' && [ "$n" -ge "$min" ]; then
305
+ echo "thresholds.$k: $n — ok"
306
+ else
307
+ echo "::error file=.github/project.yml::thresholds.$k is '$n', expected a whole number >= $min. Every reader ignores it and uses the default. See project.schema.md, thresholds."
308
+ bad=1
309
+ fi
310
+ done < <(awk '
311
+ /^thresholds[[:space:]]*:/ { b = 1; v = $0
312
+ sub(/^thresholds[[:space:]]*:[[:space:]]*/, "", v); sub(/[[:space:]]+#.*$/, "", v); sub(/[[:space:]]+$/, "", v)
313
+ if (v != "" && v != "~" && v != "null") print "=" v
314
+ next }
315
+ b && /^[[:space:]]*(#|$)/ { next }
316
+ b && /^[[:space:]]/ { l = $0; sub(/^[[:space:]]+/, "", l); sub(/[[:space:]]+#.*$/, "", l); sub(/[[:space:]]+$/, "", l); print l; next }
317
+ { b = 0 }' .github/project.yml)
318
+ [ "$bad" = 0 ] || exit 1
285
319
 
286
320
  # ---------------------------------------------------------------------------
287
321
  # Toolchain resolution. Precedence, highest first:
package/tools/colab CHANGED
@@ -50,6 +50,7 @@ const treeGreen = require('./lib/tree-green');
50
50
  const verifyRuns = require('./lib/verify-runs');
51
51
  const ciWait = require('./lib/ci-wait'); // #495
52
52
  const ciProfile = require('./lib/ci-profile'); // #559
53
+ const thresholdsLib = require('./lib/thresholds'); // #560
53
54
  const staleBase = require('./lib/stale-base');
54
55
  const dirtyOwner = require('./lib/dirty-owner');
55
56
  const scratchDirs = require('./lib/scratch-dirs');
@@ -14993,6 +14994,54 @@ function cmdCiProfile(argv) {
14993
14994
  return 0;
14994
14995
  }
14995
14996
 
14997
+ // thresholds (#560) — the advisory thresholds this repo applies: its declared values, else the defaults.
14998
+ const HELP_THRESHOLDS = `colab thresholds [--repo <path>] [--json] [<name>]
14999
+
15000
+ The advisory thresholds this repo applies (#560): the value of each, and whether it is this
15001
+ repo's declared value or the handbook default. A repo overrides one in .github/project.yml:
15002
+
15003
+ thresholds:
15004
+ hot-file-count: 4
15005
+
15006
+ Nothing changes for a repo that declares nothing. Skills cite these by name — code-triage's
15007
+ hot-file count and dependents band, code-wrap's gate.smoke target — and read them here, so no
15008
+ skill hard-codes a number a repo may have changed. A malformed entry falls back to the default
15009
+ and is listed under problems; the audit and the CI templates' descriptor check fail it.
15010
+
15011
+ <name> print only that threshold's value (a bare number, for a script or a skill)
15012
+ --json { repo, thresholds: { <name>: { value, default, declared, what, where } }, problems }`;
15013
+
15014
+ function cmdThresholds(argv) {
15015
+ const opts = parseArgs(argv, {
15016
+ values: { '--repo': 'repo' },
15017
+ flags: { '--json': 'json', '-h': 'help', '--help': 'help' },
15018
+ });
15019
+ if (opts.help) return print(HELP_THRESHOLDS);
15020
+ const repoAbs = resolveRepo(opts);
15021
+ const r = thresholdsLib.parseThresholds(projectDoc(repoAbs));
15022
+ const name = opts._ && opts._[0];
15023
+ if (name !== undefined) {
15024
+ if (!thresholdsLib.SPEC[name]) throw new UserError(`unknown threshold ${name} — expected one of: ${Object.keys(thresholdsLib.SPEC).join(', ')} (run \`colab thresholds\` to list them)`);
15025
+ for (const p of r.problems) process.stderr.write(`! ${p}\n`);
15026
+ print(String(r.values[name]));
15027
+ return 0;
15028
+ }
15029
+ const rows = Object.fromEntries(Object.entries(thresholdsLib.SPEC).map(([k, s]) => [k, {
15030
+ value: r.values[k], default: s.def, declared: !!r.declared[k], what: s.what, where: s.where,
15031
+ }]));
15032
+ if (opts.json) {
15033
+ print(JSON.stringify({ repo: shortRepo(repoAbs), thresholds: rows, problems: r.problems }, null, 2));
15034
+ return 0;
15035
+ }
15036
+ print(`thresholds ${shortRepo(repoAbs)}`);
15037
+ const w = Math.max(...Object.keys(rows).map((k) => k.length));
15038
+ for (const [k, row] of Object.entries(rows)) {
15039
+ print(` ${k.padEnd(w)} ${String(row.value).padStart(5)} ${row.declared ? `declared (default ${row.default})` : 'default'.padEnd(20)} ${row.what}`);
15040
+ }
15041
+ for (const p of r.problems) print(` ! ${p}`);
15042
+ return 0;
15043
+ }
15044
+
14996
15045
  function cmdLanded(argv) {
14997
15046
  const opts = parseArgs(argv, {
14998
15047
  values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--base': 'base' },
@@ -15782,6 +15831,8 @@ Commands:
15782
15831
  wait; how a repo tunes ship-batch / ship-batch-wait (#554)
15783
15832
  ci-profile [--json] [--refresh] this repo's measured CI duration and every CI wait bound
15784
15833
  derived from it — ci-wait's default deadline (#559)
15834
+ thresholds [<name>] [--json] the advisory thresholds this repo applies — declared in
15835
+ project.yml thresholds:, else the default (#560)
15785
15836
  holders <path> [--base B] [--json] who else is holding <path> — refs that touched it and
15786
15837
  have not landed on the base (filters the raw git-log
15787
15838
  one-liner through \`landed\`'s content classification)
@@ -15868,6 +15919,7 @@ function main(argv) {
15868
15919
  case 'landed': return cmdLanded(rest);
15869
15920
  case 'batch-stats': return cmdBatchStats(rest);
15870
15921
  case 'ci-profile': return cmdCiProfile(rest);
15922
+ case 'thresholds': return cmdThresholds(rest);
15871
15923
  case 'trunk-ci': return cmdTrunkCi(rest);
15872
15924
  case 'ci-wait': return cmdCiWait(rest);
15873
15925
  case 'holders': return cmdHolders(rest);
@@ -55,6 +55,7 @@
55
55
 
56
56
  const { axisOfRecord } = require('./axis-authority');
57
57
  const { parseWakeLine } = require('./wake');
58
+ const { thresholdValue, parseThresholds } = require('./thresholds');
58
59
 
59
60
  // ---------------------------------------------------------------------------------------------
60
61
  // Vocabulary
@@ -115,10 +116,10 @@ const EVIDENCE_FIELDS = Object.freeze(['what', 'command', 'result', 'remains']);
115
116
  /**
116
117
  * PROPOSAL, not a measured threshold (CONVENTIONS.md §5 says so in the same words). A hold whose
117
118
  * wake condition has sat this long without movement wants a human to confirm it is still wanted.
118
- * Exported so a consumer can measure against a different number rather than fork the module, and
119
- * so the day someone measures it, one constant moves.
119
+ * This is the DEFAULT: a repo may declare its own as `thresholds.hold-stale-days` (#560), read
120
+ * from the `project` fact through tools/lib/thresholds.js. Exported for consumers and tests.
120
121
  */
121
- const HOLD_STALE_DAYS = 30;
122
+ const HOLD_STALE_DAYS = thresholdValue({}, 'hold-stale-days');
122
123
 
123
124
  /**
124
125
  * One marker per line, `proposed=<token>`, the shape `colab:grade verdict=<token>` already uses.
@@ -320,11 +321,13 @@ function classify(facts) {
320
321
  'a park with no wake condition is not a hold — it is a silent wontfix, and should be said plainly',
321
322
  ['no review-by:<date>, no blockedBy edge, and no wake: condition from the closed vocabulary']);
322
323
  }
323
- const stale = Number.isFinite(w.ageDays) && w.ageDays > HOLD_STALE_DAYS && w.movedSince !== true;
324
+ const declared = parseThresholds(f.project); // #560: the repo's value, else the default 30
325
+ const staleDays = declared.values['hold-stale-days'];
326
+ const stale = Number.isFinite(w.ageDays) && w.ageDays > staleDays && w.movedSince !== true;
324
327
  return stale
325
328
  ? verdict(kind, HUMAN, true,
326
- `the wake condition has stood ${w.ageDays} days without movement — a human confirms it is still wanted (${HOLD_STALE_DAYS} d is a PROPOSAL, unmeasured)`,
327
- [`wake older than ${HOLD_STALE_DAYS} days with no movement`])
329
+ `the wake condition has stood ${w.ageDays} days without movement — a human confirms it is still wanted (${staleDays} d is ${declared.declared['hold-stale-days'] ? 'this repo\'s thresholds.hold-stale-days' : 'a PROPOSAL, unmeasured'})`,
330
+ [`wake older than ${staleDays} days with no movement`])
328
331
  : verdict(kind, AGENT, true, 'the park names what it is waiting on — the agent applies', []);
329
332
  }
330
333
 
@@ -0,0 +1,98 @@
1
+ 'use strict';
2
+ /**
3
+ * tools/lib/thresholds.js — repo-declared values for the ADVISORY thresholds (#560, epic #558).
4
+ *
5
+ * Before this module each of these numbers was one fleet-wide constant, written into a skill's
6
+ * prose or a tool's source. The ruling on #560: today's value stays as the documented default, and
7
+ * a repo may override it in `.github/project.yml`:
8
+ *
9
+ * thresholds:
10
+ * hot-file-count: 4
11
+ * hold-stale-days: 45
12
+ *
13
+ * Nothing changes for a repo that declares nothing. Only ADVISORY thresholds live here — a number
14
+ * that decides what gets flagged, ranked or warned about. Safety limits (a cap a repo may only
15
+ * tighten) and protocol counts are out of scope (epic #558) and keep their own fields.
16
+ *
17
+ * Every value is a whole number with a per-key floor, and the unit is in the key's name. That keeps
18
+ * the CI templates' shell copy of this rule (the descriptor check, #416) small enough to be held to
19
+ * this table by tools/lib/ci-template-descriptor-check.test.js.
20
+ *
21
+ * A malformed value — a typo'd key, a non-number, a number under the floor — falls back to the
22
+ * default and is reported; the audit and the descriptor check fail it. A typo'd key is a problem,
23
+ * not an ignored extra: silently reverting to the default is exactly the failure #416 measured.
24
+ *
25
+ * Pure: a parsed descriptor in, values out. Both YAML readers feed it — the CLI's (numbers come
26
+ * through as numbers) and the audit's (they come through as digit strings) — so it accepts both.
27
+ */
28
+
29
+ const KEY = 'thresholds';
30
+
31
+ /**
32
+ * key → { def, min, what, where }. `where` names the one place that reads the value.
33
+ * Order is the order `colab thresholds` prints.
34
+ */
35
+ const SPEC = Object.freeze({
36
+ 'hot-file-count': { def: 3, min: 2, what: 'waiting issues on one path before triage files HOT FILE', where: 'skills/code-triage/3-hot-file.md' },
37
+ 'dependents-count': { def: 3, min: 1, what: 'open issues blocked_by one issue before triage ranks it as leverage', where: 'skills/code-triage/4-order.md' },
38
+ 'hold-stale-days': { def: 30, min: 1, what: 'days a hold\'s wake condition may stand unmoved before a human confirms it', where: 'tools/lib/disposition.js' },
39
+ 'smoke-minutes': { def: 3, min: 1, what: 'target run time of gate.smoke', where: 'skills/code-wrap/SKILL.md' },
40
+ 'claude-md-kb': { def: 40, min: 1, what: 'authored KB of CLAUDE.md plus its @-imports before the audit warns', where: 'audit/audit.mjs' },
41
+ 'claude-md-line-multiple': { def: 6, min: 2, what: 'longest line as a multiple of the file\'s median line before the audit warns', where: 'audit/audit.mjs' },
42
+ 'claude-md-line-floor-bytes': { def: 2048, min: 0, what: 'a line under this many bytes is never flagged on the multiple alone', where: 'audit/audit.mjs' },
43
+ 'transitional-days': { def: 180, min: 1, what: 'days a transitional descriptor value holds before the audit says how long', where: 'audit/audit.mjs' },
44
+ 'doc-budget-slack': { def: 100, min: 0, what: 'lines under a doc budget before check-doc-budget asks to lower it', where: 'scripts/check-doc-budget.mjs' },
45
+ });
46
+
47
+ const DEFAULTS = Object.freeze(Object.fromEntries(Object.entries(SPEC).map(([k, s]) => [k, s.def])));
48
+
49
+ /** At most nine digits — the CI templates' shell check compares with `[ -ge ]`, which must not overflow. */
50
+ const MAX_VALUE = 999999999;
51
+
52
+ function wholeNumber(raw) {
53
+ if (typeof raw === 'number') return Number.isInteger(raw) && raw <= MAX_VALUE ? raw : NaN;
54
+ if (typeof raw === 'string' && /^\s*[0-9]{1,9}\s*$/.test(raw)) return Number(raw);
55
+ return NaN;
56
+ }
57
+
58
+ /**
59
+ * `doc` → `{ values, declared, problems }`. `values` always carries every key (the default where
60
+ * nothing valid was declared); `declared` names the keys whose declared value is in force;
61
+ * `problems` is one sentence per malformed entry, each ending with the default it fell back to.
62
+ */
63
+ function parseThresholds(doc) {
64
+ const values = Object.assign({}, DEFAULTS);
65
+ const declared = {};
66
+ const problems = [];
67
+ const has = !!doc && Object.prototype.hasOwnProperty.call(doc, KEY);
68
+ const raw = has ? doc[KEY] : undefined;
69
+ if (raw === undefined || raw === null || raw === '') return { values, declared, problems };
70
+ if (typeof raw !== 'object' || Array.isArray(raw)) {
71
+ problems.push(`${KEY} must be a map of "name: whole number" pairs, got ${JSON.stringify(raw)} — every threshold keeps its default`);
72
+ return { values, declared, problems };
73
+ }
74
+ for (const [k, v] of Object.entries(raw)) {
75
+ const spec = SPEC[k];
76
+ if (!spec) {
77
+ problems.push(`${KEY}.${k} is not a known threshold (known: ${Object.keys(SPEC).join(', ')}) — ignored`);
78
+ continue;
79
+ }
80
+ if (v === null || v === undefined || v === '') continue; // an empty entry declares nothing
81
+ const n = wholeNumber(v);
82
+ if (!Number.isFinite(n) || n < spec.min) {
83
+ problems.push(`${KEY}.${k} must be a whole number ≥ ${spec.min}, got ${JSON.stringify(v)} — using the default ${spec.def}`);
84
+ continue;
85
+ }
86
+ values[k] = n;
87
+ declared[k] = true;
88
+ }
89
+ return { values, declared, problems };
90
+ }
91
+
92
+ /** The resolved value of one key — the convenience a single consumer wants. */
93
+ function thresholdValue(doc, key) {
94
+ if (!SPEC[key]) throw new Error(`unknown threshold ${key}`);
95
+ return parseThresholds(doc).values[key];
96
+ }
97
+
98
+ module.exports = { KEY, SPEC, DEFAULTS, MAX_VALUE, parseThresholds, thresholdValue };