@futurelastic/colab-handbook 1.13.0-rc.25 → 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
@@ -98,6 +98,8 @@ const installRoute = require("../tools/lib/install-route.js");
98
98
  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
+ const ciProfile = require("../tools/lib/ci-profile.js"); // #559
102
+ const thresholdsLib = require("../tools/lib/thresholds.js"); // #560
101
103
  // #383: where migrations live — the one rule `colab ship`'s gate and `release cut` read; the audit
102
104
  // validates the `migrations:` declaration against it and reports a `*/migrations/` dir it misses.
103
105
  const migrationPaths = require("../tools/lib/migration-paths.js");
@@ -218,7 +220,7 @@ function parseScalarValue(raw) {
218
220
  return val;
219
221
  }
220
222
 
221
- 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
222
224
 
223
225
  function parseFlatYaml(text) {
224
226
  const out = {};
@@ -1053,7 +1055,7 @@ function yamlRawValue(text, key) {
1053
1055
  return m[1].replace(/\s+#.*$/, "").trim();
1054
1056
  }
1055
1057
 
1056
- 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
1057
1059
  // "transitional descriptor is clean" case, which this
1058
1060
  // threshold exists to keep passing untouched: a descriptor
1059
1061
  // committed moments ago must never earn a duration line.
@@ -1091,9 +1093,9 @@ function declaredStateAge(src, key) {
1091
1093
 
1092
1094
  // Prose for a declaredStateAge() result, or null when it is too recent to be worth saying
1093
1095
  // (the DURATION_MIN_DAYS gate — the caller must check this before calling warn()).
1094
- function renderDuration(age) {
1096
+ function renderDuration(age, minDays = DURATION_MIN_DAYS) {
1095
1097
  const days = Math.floor((Date.now() / 1000 - age.epoch) / DURATION_DAY_SECONDS);
1096
- if (days < DURATION_MIN_DAYS) return null;
1098
+ if (days < minDays) return null;
1097
1099
  const months = Math.floor(days / 30); // coarse on purpose — a report, not a countdown
1098
1100
  return `${age.lowerBound ? "at least " : ""}${months} month${months === 1 ? "" : "s"}`;
1099
1101
  }
@@ -1122,12 +1124,15 @@ function auditRepo(target, ctx) {
1122
1124
  // ---- .github/project.yml -------------------------------------------------
1123
1125
  const rawCfg = src.readFile(".github/project.yml");
1124
1126
  let cfg = null;
1127
+ // #560: the advisory thresholds this run applies — defaults until the descriptor declares otherwise.
1128
+ let th = thresholdsLib.parseThresholds(null);
1125
1129
  if (rawCfg === null) {
1126
1130
  fail("no .github/project.yml — repo is undescribed (tier/trunk/deploy unknown)");
1127
1131
  } else {
1128
1132
  const { data, problems } = parseFlatYaml(rawCfg);
1129
1133
  problems.forEach((p) => fail(`project.yml: ${p}`));
1130
1134
  cfg = data;
1135
+ th = thresholdsLib.parseThresholds(cfg);
1131
1136
  // `tier` is deliberately NOT in this list as of #144: it used to be the sole axis of
1132
1137
  // record and therefore unconditionally required, but a descriptor may now answer the
1133
1138
  // gate-count question with `exposure` instead — see the "axis of record" check below,
@@ -1315,6 +1320,22 @@ function auditRepo(target, ctx) {
1315
1320
  else if (wCfg.sec > 0 && shipBatch.parseShipBatch(cfg).n <= 1) warn(`${wCfg.reason} is inert without ship-batch > 1 — there is no batch for a partner to join`);
1316
1321
  }
1317
1322
 
1323
+ // ---- ci-wait-factor (#559) ----------------------------------------------------
1324
+ // The one declared part of every CI wait bound: a multiple of the repo's MEASURED CI duration
1325
+ // (tools/lib/ci-profile.js parseFactor, the reading colab ci-wait and colab ship use). A malformed
1326
+ // value fails here; the tools fall back to the documented default (2) and say so — never to a
1327
+ // different behaviour. No ceiling: how patient a repo is, is the repo's choice.
1328
+ if (ciProfile.FACTOR_KEY in (cfg || {}) && cfg[ciProfile.FACTOR_KEY] !== null) {
1329
+ const f = ciProfile.parseFactor(cfg);
1330
+ if (!f.valid) fail(`${f.reason} — see project.schema.md, ci-wait-factor`);
1331
+ }
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
+
1318
1339
  // ---- migrations (#383) ----------------------------------------------------
1319
1340
  // Where the repo's migrations live, beyond the two defaults (database/migrations/,
1320
1341
  // prisma/migrations/) — tools/lib/migration-paths.js is the one reading, shared with
@@ -1467,7 +1488,7 @@ function auditRepo(target, ctx) {
1467
1488
  );
1468
1489
  }
1469
1490
  const exposureAge = declaredStateAge(src, "exposure");
1470
- const durationLine = exposureAge && renderDuration(exposureAge);
1491
+ const durationLine = exposureAge && renderDuration(exposureAge, th.values["transitional-days"]);
1471
1492
  if (durationLine) {
1472
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`);
1473
1494
  }
@@ -1557,7 +1578,7 @@ function auditRepo(target, ctx) {
1557
1578
  );
1558
1579
  }
1559
1580
  const channelsAge = declaredStateAge(src, "channels");
1560
- const durationLine = channelsAge && renderDuration(channelsAge);
1581
+ const durationLine = channelsAge && renderDuration(channelsAge, th.values["transitional-days"]);
1561
1582
  if (durationLine) {
1562
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`);
1563
1584
  }
@@ -1702,7 +1723,7 @@ function auditRepo(target, ctx) {
1702
1723
  // ---- CLAUDE.md is a router, not an archive (#64) -------------------------
1703
1724
  // Unconditional: this is a repo-doc concern, not a tier/deploy one, and it applies to
1704
1725
  // the handbook's OWN CLAUDE.md too (not a stamp check, so it is not gated on !isSelf).
1705
- checkClaudeMdSize(src, warn);
1726
+ checkClaudeMdSize(src, warn, th.values);
1706
1727
  // #417: same posture — a tool block loaded twice, or the Conventions block moved out of the
1707
1728
  // file tools look it up in, is a repo-doc concern on every repo, the handbook's own included.
1708
1729
  checkInstructionFileBlocks(src, warn);
@@ -2204,9 +2225,10 @@ function checkReleaseBranch(cfg, trunk, branches, fail, warn, deploy) {
2204
2225
  // a starting point rather than a recommendation", wanting calibration across adopting repos
2205
2226
  // before anything here becomes a hard gate — the goal is a finding with the measured number
2206
2227
  // ("state the condition"), not a build-breaking assertion of a still-uncalibrated one.
2207
- const CLAUDE_MD_MAX_BYTES = 40 * 1024; // near the handbook's own cited worst case (39 KB / 452 lines)
2208
- const CLAUDE_MD_LINE_MULTIPLE = 6; // "some small multiple of the [file's] median row"
2209
- 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).
2210
2232
 
2211
2233
  // #117: the byte ceiling above was built to catch hand-written accretion, but it counts
2212
2234
  // TOTAL file bytes — which also charges a repo for content it cannot shorten by the rule's
@@ -2439,7 +2461,11 @@ function checkAnchorLinks(src, fail) {
2439
2461
  }
2440
2462
  }
2441
2463
 
2442
- 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"];
2443
2469
  // #417: measure what is LOADED, not one file. A thin-shell CLAUDE.md (`@AGENTS.md` plus the
2444
2470
  // by-name tool blocks) is tiny by construction, so measuring it alone would neuter this guard
2445
2471
  // while a bloated AGENTS.md rides in behind it on every turn. The loaded set is CLAUDE.md plus
@@ -2462,7 +2488,7 @@ function checkClaudeMdSize(src, warn) {
2462
2488
  }
2463
2489
  const derivedBytes = Math.max(0, bytes - authoredBytes);
2464
2490
 
2465
- if (authoredBytes > CLAUDE_MD_MAX_BYTES) {
2491
+ if (authoredBytes > maxBytes) {
2466
2492
  const totalNote = derivedBytes > 0
2467
2493
  ? ` (of ${bytes} bytes total; ${derivedBytes} bytes are marked colab:derived and excluded — #117)`
2468
2494
  : "";
@@ -2471,7 +2497,7 @@ function checkClaudeMdSize(src, warn) {
2471
2497
  : `CLAUDE.md plus its @-imports (${files.slice(1).map((f) => f.path).join(", ")}) is`;
2472
2498
  warn(
2473
2499
  `${subject} ${authoredBytes} bytes (~${(authoredBytes / 1024).toFixed(1)} KB)${totalNote} — over the ` +
2474
- `${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 ` +
2475
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)`,
2476
2502
  );
2477
2503
  }
@@ -2486,7 +2512,7 @@ function checkClaudeMdSize(src, warn) {
2486
2512
  if (lens.length < 2) continue; // no meaningful median from 0 or 1 lines
2487
2513
  const median = lens[Math.floor(lens.length / 2)];
2488
2514
  const worst = lens[lens.length - 1];
2489
- if (median > 0 && worst > CLAUDE_MD_LINE_ABS_FLOOR && worst > median * CLAUDE_MD_LINE_MULTIPLE) {
2515
+ if (median > 0 && worst > lineFloor && worst > median * lineMultiple) {
2490
2516
  const pct = ((worst / f.authoredBytes) * 100).toFixed(1);
2491
2517
  warn(
2492
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.25"
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
@@ -49,6 +49,8 @@ const baseCiVerdict = require('./lib/base-ci-verdict');
49
49
  const treeGreen = require('./lib/tree-green');
50
50
  const verifyRuns = require('./lib/verify-runs');
51
51
  const ciWait = require('./lib/ci-wait'); // #495
52
+ const ciProfile = require('./lib/ci-profile'); // #559
53
+ const thresholdsLib = require('./lib/thresholds'); // #560
52
54
  const staleBase = require('./lib/stale-base');
53
55
  const dirtyOwner = require('./lib/dirty-owner');
54
56
  const scratchDirs = require('./lib/scratch-dirs');
@@ -10885,10 +10887,11 @@ function readCiVerdict(repoAbs, gh, target, trunk) {
10885
10887
  // (a ship reading trunk right after another ship landed it). That clears on its own: SELF_CLEARING,
10886
10888
  // never HUMAN_GATED, until the grace window has passed. Age unknown keeps the old class.
10887
10889
  if (run.status === 'none' && target === trunk) {
10888
- const fresh = ciVerdict.emptyReadVerdict(git.commitTimeMs(repoAbs, run.sha));
10890
+ // #559: the grace is the repo's measured push→run lag when there is one — read from cache, never fetched here.
10891
+ const fresh = ciVerdict.emptyReadVerdict(git.commitTimeMs(repoAbs, run.sha), { graceSec: ciProfileFor(repoAbs).th.emptyReadGraceSec });
10889
10892
  if (fresh.fresh) {
10890
10893
  verdict = { ok: false, class: SELF_CLEARING,
10891
- detail: `no run yet for ${at} — committed ${fresh.minutes.toFixed(1)}m ago, inside the ${ciVerdict.EMPTY_READ_GRACE_MINUTES}m grace; retry later${excludedRunsNote(run)}${verifyRuns.setAsideNote(run.setAside)}` };
10894
+ detail: `no run yet for ${at} — committed ${fresh.minutes.toFixed(1)}m ago, inside the ${Math.round(fresh.graceMinutes * 10) / 10}m grace; retry later${excludedRunsNote(run)}${verifyRuns.setAsideNote(run.setAside)}` };
10892
10895
  }
10893
10896
  }
10894
10897
  // #373: trunk's own run not there yet or still in flight (never a finished red) — a batch that landed
@@ -11001,7 +11004,9 @@ function classifyCiRunRaw(repoAbs, run, at) {
11001
11004
  // Non-completed, non-none: running/queued/etc. Ordinarily SELF_CLEARING — but #155's wedged
11002
11005
  // shape (queued, zero jobs, unmoving for hours) can never clear on its own, so check for it.
11003
11006
  const jobCount = run.databaseId != null ? git.ghRunJobCount(repoAbs, run.databaseId) : null;
11004
- const wedge = ciVerdict.wedgedVerdict({ status: run.status, createdAt: run.createdAt, jobCount });
11007
+ // #559: wedge age and zero-jobs floor follow the repo's measured CI (cached profile; bootstrap = 6h / 2m).
11008
+ const th = ciProfileFor(repoAbs).th;
11009
+ const wedge = ciVerdict.wedgedVerdict({ status: run.status, createdAt: run.createdAt, jobCount }, { wedgeAgeSec: th.wedgeAgeSec, zeroJobsFloorSec: th.zeroJobsFloorSec });
11005
11010
  if (wedge.wedged) {
11006
11011
  return { ok: false, class: HUMAN_GATED, detail: `run for ${at}: status=${run.status} — WEDGED (${wedge.reason}); a human must look, not retry` };
11007
11012
  }
@@ -14491,6 +14496,110 @@ function trunkCiCache(repoAbs) {
14491
14496
  };
14492
14497
  }
14493
14498
 
14499
+ // ---- ci-profile (#559) ------------------------------------------------------------------------
14500
+ // Every CI wait bound derives from the repo's own measured CI duration (tools/lib/ci-profile.js).
14501
+ // The profile is cached per checkout in `<git common dir>/colab-ci-profile.json` for a day; the
14502
+ // thresholds are NOT cached — they are recomputed from the cached profile and the CURRENT
14503
+ // `ci-wait-factor`, so editing the factor applies at once with no refetch.
14504
+ const CI_PROFILE_TTL_DEFAULT_SEC = 24 * 3600;
14505
+ const CI_PROFILE_CACHE_V = 1;
14506
+
14507
+ function ciProfileTtlSec() {
14508
+ const env = process.env.COLAB_CI_PROFILE_TTL;
14509
+ return env !== undefined && env !== '' && Number.isFinite(Number(env)) ? Number(env) : CI_PROFILE_TTL_DEFAULT_SEC;
14510
+ }
14511
+
14512
+ function ciProfileCacheFile(repoAbs) {
14513
+ const dir = git.git(['rev-parse', '--path-format=absolute', '--git-common-dir'], repoAbs);
14514
+ return dir.ok && dir.stdout ? path.join(dir.stdout.trim(), 'colab-ci-profile.json') : null;
14515
+ }
14516
+
14517
+ /**
14518
+ * The repo's completed CI runs in the profile window — up to 3 pages of the whole list plus one page
14519
+ * of trunk pushes, so a branch-heavy repo still yields trunk samples. Returns `{ rows, runsRead }`,
14520
+ * or `{ error }` when the list cannot be read (the caller falls back, never fails a wait on it).
14521
+ */
14522
+ function fetchCiProfileRows(repoAbs, trunk, sinceIso) {
14523
+ const jq = '.workflow_runs[] | [.id, .head_branch, .head_sha, .event, .name, .status, .conclusion, .run_attempt, .created_at, .updated_at, .head_commit.timestamp] | @json';
14524
+ const day = sinceIso.slice(0, 10);
14525
+ const paths = [1, 2, 3].map((n) => `repos/{owner}/{repo}/actions/runs?per_page=100&status=completed&created=%3E%3D${day}&page=${n}`);
14526
+ paths.push(`repos/{owner}/{repo}/actions/runs?per_page=100&status=completed&created=%3E%3D${day}&branch=${encodeURIComponent(trunk)}&event=push`);
14527
+ const seen = new Map();
14528
+ for (let i = 0; i < paths.length; i++) {
14529
+ const r = git.ghApi(repoAbs, [paths[i], '--jq', jq]);
14530
+ if (!r.ok) return { error: git.gitFailureLine(r.stderr) || 'gh api failed' };
14531
+ let n = 0;
14532
+ for (const line of String(r.stdout || '').split('\n')) {
14533
+ if (!line.trim()) continue;
14534
+ let a; try { a = JSON.parse(line); } catch (_) { continue; }
14535
+ n++;
14536
+ seen.set(a[0], {
14537
+ id: a[0], branch: a[1], sha: a[2], event: a[3], workflowName: a[4], status: a[5], conclusion: a[6],
14538
+ attempt: a[7], createdMs: Date.parse(a[8]), updatedMs: Date.parse(a[9]), headCommitMs: a[10] ? Date.parse(a[10]) : null,
14539
+ });
14540
+ }
14541
+ if (i < 3 && n < 100) i = 2; // a short page ends the paged list; the trunk page still runs
14542
+ }
14543
+ return { rows: [...seen.values()], runsRead: seen.size };
14544
+ }
14545
+
14546
+ const ciProfileMemo = new Map();
14547
+
14548
+ /**
14549
+ * The one reader: `{ profile, th, factor, kindTrunk, cache: { state, ageSec, fetchedAt }, notes }`.
14550
+ * `fetch`: 'never' (ship's hot path — never blocks a verdict on a history read) · 'if-stale' ·
14551
+ * 'always'. A stale cache is still used when a refetch fails: old measured data beats bootstrap.
14552
+ * TTL 0 (`COLAB_CI_PROFILE_TTL=0`) means no cache and no fetch — the bootstrap everywhere.
14553
+ */
14554
+ function ciProfileFor(repoAbs, { fetch = 'never' } = {}) {
14555
+ const memoKey = `${repoAbs}\u0000${fetch}`;
14556
+ if (ciProfileMemo.has(memoKey)) return ciProfileMemo.get(memoKey);
14557
+ const doc = projectDoc(repoAbs);
14558
+ const factor = ciProfile.parseFactor(doc);
14559
+ const trunk = resolveTrunk(repoAbs, doc);
14560
+ const notes = [];
14561
+ if (!factor.valid) notes.push(factor.reason);
14562
+ const ttl = ciProfileTtlSec();
14563
+ const file = ttl > 0 ? ciProfileCacheFile(repoAbs) : null;
14564
+ let entry = null;
14565
+ if (file) {
14566
+ try { entry = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (_) { entry = null; }
14567
+ if (entry && (entry.v !== CI_PROFILE_CACHE_V || entry.trunk !== trunk || !entry.profile)) entry = null;
14568
+ }
14569
+ const ageSec = entry ? Math.max(0, Math.floor((Date.now() - entry.fetchedAt) / 1000)) : null;
14570
+ let state = entry ? (ageSec < ttl ? 'fresh' : 'stale') : 'none';
14571
+ const want = file && trunk && (fetch === 'always' || (fetch === 'if-stale' && state !== 'fresh'));
14572
+ if (want) {
14573
+ if (!isGhUsable(repoAbs)) notes.push(`gh not usable (${ghUnusableWhy(repoAbs)}) — CI history not read`);
14574
+ else {
14575
+ const nowMs = Date.now();
14576
+ const sinceMs = nowMs - ciProfile.WINDOW_DAYS * 86_400_000;
14577
+ const got = fetchCiProfileRows(repoAbs, trunk, new Date(sinceMs).toISOString());
14578
+ if (got.error) notes.push(`could not read CI history (${got.error}) — ${entry ? 'using the stale cached profile' : 'using the bootstrap bounds'}`);
14579
+ else {
14580
+ const policy = verifyRuns.parsePolicy(doc);
14581
+ const prof = ciProfile.profile(ciProfile.shaDurations(got.rows, { trunk, policy }), { sinceMs });
14582
+ entry = { v: CI_PROFILE_CACHE_V, trunk, fetchedAt: nowMs, since: new Date(sinceMs).toISOString(), runsRead: got.runsRead, profile: prof };
14583
+ state = 'fetched';
14584
+ try {
14585
+ const tmp = `${file}.${process.pid}.tmp`;
14586
+ fs.writeFileSync(tmp, JSON.stringify(entry));
14587
+ fs.renameSync(tmp, file);
14588
+ } catch (_) { /* no cache, not an error */ }
14589
+ }
14590
+ }
14591
+ }
14592
+ const profile = entry ? entry.profile : null;
14593
+ const out = {
14594
+ trunk, factor, profile, th: ciProfile.thresholds(profile, factor.value),
14595
+ cache: { state, ageSec: state === 'fetched' ? 0 : ageSec, fetchedAt: entry ? new Date(entry.fetchedAt).toISOString() : null,
14596
+ since: entry ? entry.since : null, runsRead: entry ? entry.runsRead : null },
14597
+ notes,
14598
+ };
14599
+ ciProfileMemo.set(memoKey, out);
14600
+ return out;
14601
+ }
14602
+
14494
14603
  // ci-wait — THE way to wait for CI (#495). Agents' hand-rolled `sleep N; gh run …` loops spent ~88%
14495
14604
  // of a shared identity's REST quota in one measured hour; this waits with backoff, conditional
14496
14605
  // requests, a deadline, and a distinct exit code for every way a wait can end.
@@ -14506,9 +14615,13 @@ Wait for CI and exit with its outcome. The ONE way to wait for a run: never hand
14506
14615
  with no run yet counts as pending until the deadline. An abbreviated sha is
14507
14616
  resolved in the repo first, and refused (exit 2) when it does not resolve — #529
14508
14617
  --branch <b> narrow --sha to runs on that branch
14509
- --timeout <d> deadline: 45m (default), 90s, 1h, or seconds
14618
+ --timeout <d> deadline: 90s, 15m, 1h, or seconds. Default: this repo's CI wait bound, derived
14619
+ from its measured CI duration (\`colab ci-profile\`, #559) — the trunk bound
14620
+ when the target is trunk, the branch bound for any other branch, the larger
14621
+ for a bare run id; 15m while the repo has no CI history. Skills omit it.
14510
14622
 
14511
- Polls at 0s, then +30s, +60s, +120s, +120s … until the deadline. Every poll after the first is a
14623
+ Polls at 0s, then +30s, +60s, +120s, +120s … until the deadline (a repo whose CI bound is past 15m
14624
+ gets the same schedule stretched in proportion — never a faster one). Every poll after the first is a
14512
14625
  conditional request (If-None-Match); a 304 is not counted against the REST rate limit. After two
14513
14626
  304s in a row, and on the last poll before the deadline, it re-reads unconditionally: a stale ETag
14514
14627
  can cost one paid call, never the whole wait (#505). A 15-minute run costs about 10 requests. One wait per run per checkout: a second waiter is refused.
@@ -14523,7 +14636,8 @@ Exit codes — branch on these, never on the text:
14523
14636
  6 ALREADY_WAITING another live ci-wait on this checkout holds the same run/sha
14524
14637
 
14525
14638
  It prints the wait it did: outcome, elapsed time, polls, and how many were 304s.
14526
- --json { outcome, exit, target, polls, notModified, forced, waitedSec, detail, status, conclusion, url }`;
14639
+ --json { outcome, exit, target, polls, notModified, forced, waitedSec, deadlineSec, deadlineBasis,
14640
+ detail, status, conclusion, url }`;
14527
14641
 
14528
14642
  function cmdCiWait(argv) {
14529
14643
  const opts = parseArgs(argv, {
@@ -14536,8 +14650,10 @@ function cmdCiWait(argv) {
14536
14650
  warn('ci-wait takes exactly one of <run-id> (numeric) or --sha <sha> [--branch <b>]');
14537
14651
  return ciWait.EXIT.USAGE;
14538
14652
  }
14539
- const deadlineSec = opts.timeout !== undefined ? ciWait.parseDuration(opts.timeout) : ciWait.DEFAULT_DEADLINE_SEC;
14540
- if (!deadlineSec) { warn(`--timeout: cannot read "${opts.timeout}" (try 45m, 90s, 1h)`); return ciWait.EXIT.USAGE; }
14653
+ let deadlineSec = opts.timeout !== undefined ? ciWait.parseDuration(opts.timeout) : ciWait.DEFAULT_DEADLINE_SEC;
14654
+ if (!deadlineSec) { warn(`--timeout: cannot read "${opts.timeout}" (try 15m, 90s, 1h)`); return ciWait.EXIT.USAGE; }
14655
+ let deadlineBasis = opts.timeout !== undefined ? '--timeout' : 'bootstrap';
14656
+ let schedule = ciWait.DEFAULT_SCHEDULE_SEC;
14541
14657
  const repoAbs = resolveRepo(opts);
14542
14658
  if (opts.sha) {
14543
14659
  // #529: the API reports a 40-hex head_sha and the rows are matched by equality, so an
@@ -14564,6 +14680,23 @@ function cmdCiWait(argv) {
14564
14680
  return ciWait.EXIT.ALREADY_WAITING;
14565
14681
  }
14566
14682
 
14683
+ // #559: no --timeout → the repo's own bound, one source with every skill (they omit the flag). Read
14684
+ // after the lock, so a refused second waiter never spends a history fetch; a failed read is a note.
14685
+ if (opts.timeout === undefined) {
14686
+ const cp = ciProfileFor(repoAbs, { fetch: 'if-stale' });
14687
+ let onTrunk = null;
14688
+ if (!runId && !opts.branch && cp.trunk) {
14689
+ const remote = git.remoteFor(repoAbs);
14690
+ onTrunk = git.git(['merge-base', '--is-ancestor', opts.sha, `${remote}/${cp.trunk}`], repoAbs).ok;
14691
+ }
14692
+ const kind = ciProfile.kindFor({ branch: opts.branch || null, trunk: cp.trunk, onTrunk });
14693
+ deadlineSec = cp.th.ciWaitDefaultSec[kind];
14694
+ schedule = cp.th.scheduleSec[kind];
14695
+ const b = kind === 'any' ? (cp.th.basis.branchWait === 'measured' || cp.th.basis.trunkWait === 'measured' ? 'measured' : 'bootstrap') : cp.th.basis[`${kind}Wait`];
14696
+ deadlineBasis = `${kind === 'any' ? 'larger' : kind} bound, ${b}`;
14697
+ if (!opts.json) for (const n of cp.notes) process.stderr.write(`ci-wait: ${n}\n`);
14698
+ }
14699
+
14567
14700
  const verifyPolicy = verifyRuns.parsePolicy(projectDoc(repoAbs));
14568
14701
  const poll = (etag) => {
14569
14702
  const r = git.ghApiConditional(repoAbs, apiPath, etag);
@@ -14583,11 +14716,11 @@ function cmdCiWait(argv) {
14583
14716
  return { ...r, summary, state: ciWait.runState(summary) };
14584
14717
  };
14585
14718
 
14586
- if (!opts.json) process.stderr.write(`ci-wait: waiting on ${target} (deadline ${ciWait.fmtDuration(deadlineSec * 1000)}; polls at +0s, +30s, +60s, then every 120s)\n`);
14719
+ if (!opts.json) process.stderr.write(`ci-wait: waiting on ${target} (deadline ${ciWait.fmtDuration(deadlineSec * 1000)}, ${deadlineBasis}; polls at +0s, +${schedule[0]}s, +${schedule[1]}s, then every ${schedule[2]}s)\n`);
14587
14720
  let res;
14588
14721
  try {
14589
14722
  res = ciWait.waitLoop({
14590
- poll, sleep: ciWait.sleepSync, deadlineSec,
14723
+ poll, sleep: ciWait.sleepSync, deadlineSec, schedule,
14591
14724
  onPoll: (p) => { if (!opts.json) process.stderr.write(`ci-wait: poll ${p.poll} at +${ciWait.fmtDuration(p.elapsedMs)} — ${p.state}${p.notModified ? ' (304, not counted)' : ''}${p.forced ? ' (unconditional re-read — #505)' : ''}\n`); },
14592
14725
  });
14593
14726
  } finally {
@@ -14597,7 +14730,7 @@ function cmdCiWait(argv) {
14597
14730
  const code = ciWait.EXIT[res.outcome];
14598
14731
  const out = {
14599
14732
  outcome: res.outcome, exit: code, target, polls: res.polls, notModified: res.notModified, forced: res.forced,
14600
- waitedSec: Math.round(res.waitedMs / 1000), detail: res.detail || null,
14733
+ waitedSec: Math.round(res.waitedMs / 1000), deadlineSec, deadlineBasis, detail: res.detail || null,
14601
14734
  status: s.status || null, conclusion: s.conclusion || null, url: s.url || null,
14602
14735
  ...(Array.isArray(s.setAside) && s.setAside.length ? { setAside: s.setAside } : {}),
14603
14736
  };
@@ -14793,6 +14926,122 @@ function cmdBatchStats(argv) {
14793
14926
  return 0;
14794
14927
  }
14795
14928
 
14929
+ // ci-profile (#559) — the repo's measured CI duration and every wait bound derived from it.
14930
+ const HELP_CI_PROFILE = `colab ci-profile [--repo <path>] [--json] [--refresh]
14931
+
14932
+ This repo's measured CI duration, and every CI wait bound derived from it (#559). One source:
14933
+ \`colab ci-wait\` with no --timeout, and \`colab ship\`'s wedged-run and empty-read verdicts, read
14934
+ these same numbers — no skill hard-codes a wait.
14935
+
14936
+ Measured: per sha, the wall time from the first verifying run's creation to the last one's
14937
+ finish, over clean first-attempt green shas in the last ${ciProfile.WINDOW_DAYS} days — split into branch runs and trunk
14938
+ runs — plus the push → run lag on trunk. A kind with fewer than ${ciProfile.MIN_SAMPLES} samples stays on its
14939
+ bootstrap value, which is today's fleet value exactly (15m waits, 6h wedge, 10m grace, 2m floor).
14940
+
14941
+ Declared: only \`ci-wait-factor: <number ≥ 1>\` in .github/project.yml (default ${ciProfile.DEFAULT_FACTOR}) — how many times
14942
+ the measured p95 a repo will wait. Every bound:
14943
+ branch / trunk wait 2m + factor × p95 of that kind, rounded up to the minute
14944
+ wedged-run age factor × the longer wait, never above 6h
14945
+ empty-read grace factor × push→run p95, never below 2m
14946
+ zero-jobs floor 2m (not measurable from the run list)
14947
+ poll backoff 30/60/120s, stretched in proportion to a wait past 15m — never faster
14948
+
14949
+ The profile is cached per checkout for a day (<git common dir>/colab-ci-profile.json;
14950
+ COLAB_CI_PROFILE_TTL seconds overrides, 0 = no cache and no read: the bootstrap). The bounds are
14951
+ recomputed from it on every read, so a changed ci-wait-factor applies at once.
14952
+
14953
+ --refresh re-read the CI history now, whatever the cache's age
14954
+ --json { repo, trunk, source, factor, cache, measured: { branch, trunk, lag }, thresholds, notes }`;
14955
+
14956
+ function cmdCiProfile(argv) {
14957
+ const opts = parseArgs(argv, {
14958
+ values: { '--repo': 'repo' },
14959
+ flags: { '--json': 'json', '--refresh': 'refresh', '-h': 'help', '--help': 'help' },
14960
+ });
14961
+ if (opts.help) return print(HELP_CI_PROFILE);
14962
+ const repoAbs = resolveRepo(opts);
14963
+ if (!git.repoRoot(repoAbs)) throw new UserError(`${repoAbs} is not a git repo — pass --repo <path> to a clone, then run \`colab ci-profile\` again`);
14964
+ const cp = ciProfileFor(repoAbs, { fetch: opts.refresh ? 'always' : 'if-stale' });
14965
+ if (!cp.trunk) throw new UserError('Could not determine trunk branch — add `trunk: <branch>` to .github/project.yml, then run `colab ci-profile` again');
14966
+ const p = cp.profile || ciProfile.profile([]);
14967
+ const th = cp.th;
14968
+ const source = cp.profile ? cp.profile.source : 'bootstrap';
14969
+ if (opts.json) {
14970
+ print(JSON.stringify({
14971
+ repo: shortRepo(repoAbs), trunk: cp.trunk, source, factor: cp.factor, cache: cp.cache,
14972
+ measured: { branch: p.branch, trunk: p.trunk, lag: p.lag }, thresholds: th, notes: cp.notes,
14973
+ }, null, 2));
14974
+ return 0;
14975
+ }
14976
+ const dur = (s) => (s === null || s === undefined ? '—' : ciWait.fmtDuration(s * 1000));
14977
+ const cacheTxt = cp.cache.state === 'fetched' ? 'read now'
14978
+ : cp.cache.state === 'none' ? 'no history read' : `read ${dur(cp.cache.ageSec)} ago (cache${cp.cache.state === 'stale' ? ', stale' : ''})`;
14979
+ print(`ci-profile ${shortRepo(repoAbs)} → ${cp.trunk} ${source.toUpperCase()} · ${cacheTxt} · ${cp.factor.valid ? cp.factor.reason : `${ciProfile.FACTOR_KEY}: ${ciProfile.DEFAULT_FACTOR} (declared value invalid)`}`);
14980
+ if (source !== 'measured') print(` ${source === 'bootstrap' ? 'every bound is' : 'unmeasured bounds are'} the bootstrap — fewer than ${ciProfile.MIN_SAMPLES} clean green shas per kind in ${ciProfile.WINDOW_DAYS}d`);
14981
+ const k = (name, x) => print(` ${name.padEnd(11)} ${x.source} · ${x.samples} sha(s)${x.samples ? ` · p50 ${dur(x.p50Sec)} · p95 ${dur(x.p95Sec)} · max ${dur(x.maxSec)}` : ''}`);
14982
+ k('branch', p.branch);
14983
+ k('trunk', p.trunk);
14984
+ print(` ${'push→run'.padEnd(11)} ${p.lag.source} · ${p.lag.samples} sample(s)${p.lag.samples ? ` · p95 ${dur(p.lag.p95Sec)}` : ''}`);
14985
+ const row = (name, sec, basis, how, boot) => print(` ${name.padEnd(11)} ${dur(sec).padEnd(7)} ${basis === 'measured' ? how : basis === 'default' ? how : 'bootstrap'}${basis === 'measured' && boot ? ` (bootstrap ${boot})` : ''}`);
14986
+ row('branch wait', th.branchWaitSec, th.basis.branchWait, `2m + ${th.factor} × p95`, '15m');
14987
+ row('trunk wait', th.trunkWaitSec, th.basis.trunkWait, `2m + ${th.factor} × p95`, '15m');
14988
+ print(` ${'ci-wait'.padEnd(11)} ${dur(th.ciWaitDefaultSec.branch)} branch · ${dur(th.ciWaitDefaultSec.trunk)} trunk · ${dur(th.ciWaitDefaultSec.any)} run id (its default with no --timeout)`);
14989
+ row('wedged age', th.wedgeAgeSec, th.basis.wedgeAge, `${th.factor} × the longer wait, ≤ 6h`, '6h');
14990
+ row('empty read', th.emptyReadGraceSec, th.basis.emptyReadGrace, `${th.factor} × push→run p95, ≥ 2m`, '10m');
14991
+ row('zero jobs', th.zeroJobsFloorSec, th.basis.zeroJobsFloor, 'default — not measurable from the run list');
14992
+ print(` ${'backoff'.padEnd(11)} branch ${th.scheduleSec.branch.map((x) => `${x}s`).join('/')} · trunk ${th.scheduleSec.trunk.map((x) => `${x}s`).join('/')}`);
14993
+ for (const n of cp.notes) print(` ! ${n}`);
14994
+ return 0;
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
+
14796
15045
  function cmdLanded(argv) {
14797
15046
  const opts = parseArgs(argv, {
14798
15047
  values: { '--repo': 'repo', '--worktree': 'worktree', '--branch': 'branch', '--base': 'base' },
@@ -15580,6 +15829,10 @@ Commands:
15580
15829
  batch-stats [--since 30d] [--json] how batch landing performs here, from git + CI history —
15581
15830
  fill, first-attempt green, drops, missed partners, queue
15582
15831
  wait; how a repo tunes ship-batch / ship-batch-wait (#554)
15832
+ ci-profile [--json] [--refresh] this repo's measured CI duration and every CI wait bound
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)
15583
15836
  holders <path> [--base B] [--json] who else is holding <path> — refs that touched it and
15584
15837
  have not landed on the base (filters the raw git-log
15585
15838
  one-liner through \`landed\`'s content classification)
@@ -15665,6 +15918,8 @@ function main(argv) {
15665
15918
  case 'ship': return cmdShip(rest);
15666
15919
  case 'landed': return cmdLanded(rest);
15667
15920
  case 'batch-stats': return cmdBatchStats(rest);
15921
+ case 'ci-profile': return cmdCiProfile(rest);
15922
+ case 'thresholds': return cmdThresholds(rest);
15668
15923
  case 'trunk-ci': return cmdTrunkCi(rest);
15669
15924
  case 'ci-wait': return cmdCiWait(rest);
15670
15925
  case 'holders': return cmdHolders(rest);
@@ -0,0 +1,195 @@
1
+ 'use strict';
2
+ /**
3
+ * tools/lib/ci-profile.js — a repo's measured CI duration, and every CI wait bound derived from it (#559).
4
+ *
5
+ * Before this module every CI wait was a fleet-wide constant, and two of them disagreed: the skills
6
+ * passed `--timeout 15m` to `colab ci-wait` everywhere while its own default was 45 minutes, so a
7
+ * caller that omitted the flag silently waited three times as long. Repos' CI ranges from a few
8
+ * minutes to nearly half an hour, so one number was too long for a fast repo and too short for a
9
+ * slow one.
10
+ *
11
+ * The rule (epic #558): a threshold that depends on a repo's nature comes from THAT repo. Here the
12
+ * duration is MEASURED from the repo's own CI history; the only DECLARED part is the multiple of it
13
+ * a repo is willing to wait (`ci-wait-factor`, default 2). Where nothing has been measured yet, each
14
+ * bound is today's value exactly — documented as the bootstrap, never a different behaviour.
15
+ *
16
+ * Pure: run rows in, a profile and thresholds out — no git, no gh, no clock. `tools/colab` fetches
17
+ * (`fetchCiProfileRows`), caches (`ciProfileFor`) and prints (`cmdCiProfile`).
18
+ *
19
+ * What is measured, per sha: the wall time from the first run's creation to the last run's last
20
+ * update, across every run that verifies the code at that sha (verify-runs.js, the same set
21
+ * `ci-wait --sha` waits on). That is exactly the wait a session sits through: "every run at the sha
22
+ * has finished". Only clean first-attempt green shas count — a re-run measures an incident, a red
23
+ * run measures how fast it failed.
24
+ */
25
+
26
+ const ciWait = require('./ci-wait');
27
+ const ciVerdict = require('./ci-verdict');
28
+ const verifyRuns = require('./verify-runs');
29
+ const { quantile } = require('./batch-stats');
30
+
31
+ const FACTOR_KEY = 'ci-wait-factor';
32
+ const DEFAULT_FACTOR = 2;
33
+ /** A kind with fewer clean green shas than this in the window stays on its bootstrap value. */
34
+ const MIN_SAMPLES = 10;
35
+ const WINDOW_DAYS = 30;
36
+
37
+ /**
38
+ * The one platform constant: how long GitHub may take to start a run and materialize its job list
39
+ * (ci-verdict's zero-jobs floor). It floors every derived bound — a 20-second CI must not produce a
40
+ * wait shorter than the time a run can take to appear at all. Not repo-measurable at run-list cost:
41
+ * `run_started_at` equals `created_at` on every row we read, so the list carries no queue signal.
42
+ */
43
+ const PLATFORM_FLOOR_SEC = ciVerdict.ZERO_JOBS_AGE_FLOOR_MINUTES * 60;
44
+
45
+ /**
46
+ * Today's values, exactly — what a repo with no history gets, built from the constants that hold
47
+ * them rather than restated. The 6 h wedge age is also a CAP: it is the hosted-runner job limit, so
48
+ * measurement may only lower it (a safety limit a repo may only tighten, epic #558). Likewise the
49
+ * 30/60/120 s poll schedule is a REST-quota floor — measurement may only stretch it.
50
+ */
51
+ const BOOTSTRAP = Object.freeze({
52
+ branchWaitSec: 15 * 60,
53
+ trunkWaitSec: 15 * 60,
54
+ wedgeAgeSec: ciVerdict.WEDGE_AGE_HOURS * 3600,
55
+ emptyReadGraceSec: ciVerdict.EMPTY_READ_GRACE_MINUTES * 60,
56
+ zeroJobsFloorSec: PLATFORM_FLOOR_SEC,
57
+ scheduleSec: ciWait.DEFAULT_SCHEDULE_SEC,
58
+ });
59
+
60
+ /**
61
+ * `ci-wait-factor: <number ≥ 1>` — absent → 2. A malformed value falls back to the documented
62
+ * default (never to a different behaviour) and is reported; the audit fails it.
63
+ */
64
+ function parseFactor(doc) {
65
+ const has = !!doc && Object.prototype.hasOwnProperty.call(doc, FACTOR_KEY) && doc[FACTOR_KEY] !== null && doc[FACTOR_KEY] !== undefined;
66
+ if (!has) return { value: DEFAULT_FACTOR, declared: false, valid: true, reason: `${FACTOR_KEY}: ${DEFAULT_FACTOR} (default)` };
67
+ const raw = doc[FACTOR_KEY];
68
+ const n = typeof raw === 'number' ? raw : (typeof raw === 'string' && /^\s*\d+(\.\d+)?\s*$/.test(raw) ? Number(raw) : NaN);
69
+ if (!Number.isFinite(n) || n < 1) {
70
+ return { value: DEFAULT_FACTOR, declared: true, valid: false,
71
+ reason: `${FACTOR_KEY} must be a number ≥ 1 (a multiple of the measured CI duration), got ${JSON.stringify(raw)} — using ${DEFAULT_FACTOR}` };
72
+ }
73
+ return { value: n, declared: true, valid: true, reason: `${FACTOR_KEY}: ${n}` };
74
+ }
75
+
76
+ /**
77
+ * Rows → one wall time per clean green sha. A row: `{ sha, branch, event, workflowName, status,
78
+ * conclusion, attempt, createdMs, updatedMs, headCommitMs }`.
79
+ *
80
+ * A branch group at a sha that is also a trunk sha is dropped: a branch cut moments ago re-runs
81
+ * trunk's content, and those near-instant runs would drag the branch duration down.
82
+ */
83
+ function shaDurations(rows, { trunk, policy = null } = {}) {
84
+ const groups = new Map();
85
+ for (const r of rows || []) {
86
+ if (!r || !r.sha || r.event === 'dynamic') continue;
87
+ const key = `${r.branch || ''}\u0000${r.sha}`;
88
+ if (!groups.has(key)) groups.set(key, []);
89
+ groups.get(key).push(r);
90
+ }
91
+ const trunkShas = new Set([...groups.values()].filter((g) => g[0].branch === trunk).map((g) => g[0].sha));
92
+ const out = [];
93
+ for (const g of groups.values()) {
94
+ const split = verifyRuns.splitVerifying(g, policy);
95
+ const counted = split ? split.counted : g;
96
+ if (!counted.length) continue;
97
+ if (!counted.every((r) => r.status === 'completed')) continue;
98
+ if (!counted.every((r) => ['success', 'skipped', 'neutral'].includes(r.conclusion))) continue;
99
+ if (!counted.some((r) => r.conclusion === 'success')) continue;
100
+ if (counted.some((r) => Number(r.attempt) > 1)) continue;
101
+ const created = Math.min(...counted.map((r) => r.createdMs));
102
+ const ended = Math.max(...counted.map((r) => r.updatedMs));
103
+ if (!Number.isFinite(created) || !Number.isFinite(ended) || ended < created) continue;
104
+ const kind = g[0].branch === trunk ? 'trunk' : 'branch';
105
+ if (kind === 'branch' && trunkShas.has(g[0].sha)) continue;
106
+ let lagSec = null;
107
+ if (kind === 'trunk') {
108
+ const c = Math.min(...counted.map((r) => r.headCommitMs).filter(Number.isFinite));
109
+ if (Number.isFinite(c) && created >= c) lagSec = Math.round((created - c) / 1000);
110
+ }
111
+ out.push({ sha: g[0].sha, kind, sec: Math.round((ended - created) / 1000), lagSec, endMs: ended });
112
+ }
113
+ return out;
114
+ }
115
+
116
+ function stats(values) {
117
+ const v = values.filter(Number.isFinite);
118
+ return {
119
+ source: v.length >= MIN_SAMPLES ? 'measured' : 'bootstrap',
120
+ samples: v.length,
121
+ p50Sec: quantile(v, 0.5),
122
+ p95Sec: quantile(v, 0.95),
123
+ maxSec: v.length ? Math.max(...v) : null,
124
+ };
125
+ }
126
+
127
+ /** Durations → `{ branch, trunk, lag, source }`; only samples ending at or after `sinceMs` count. */
128
+ function profile(durations, { sinceMs = null } = {}) {
129
+ const d = (durations || []).filter((x) => sinceMs === null || x.endMs >= sinceMs);
130
+ const branch = stats(d.filter((x) => x.kind === 'branch').map((x) => x.sec));
131
+ const trunk = stats(d.filter((x) => x.kind === 'trunk').map((x) => x.sec));
132
+ const lagV = d.filter((x) => x.kind === 'trunk' && x.lagSec !== null).map((x) => x.lagSec);
133
+ const lag = { source: lagV.length >= MIN_SAMPLES ? 'measured' : 'bootstrap', samples: lagV.length, p95Sec: quantile(lagV, 0.95) };
134
+ const n = [branch, trunk].filter((k) => k.source === 'measured').length;
135
+ return { branch, trunk, lag, source: n === 2 ? 'measured' : n === 0 ? 'bootstrap' : 'partial' };
136
+ }
137
+
138
+ const ceilMinute = (sec) => Math.ceil(sec / 60) * 60;
139
+
140
+ /** A kind's wait bound: GitHub must start the run, then `factor` times what it takes at p95. */
141
+ function boundFor(k, factor, bootstrapSec) {
142
+ if (!k || k.source !== 'measured' || !Number.isFinite(k.p95Sec)) return { sec: bootstrapSec, basis: 'bootstrap' };
143
+ return { sec: ceilMinute(PLATFORM_FLOOR_SEC + factor * k.p95Sec), basis: 'measured' };
144
+ }
145
+
146
+ /** The schedule for a bound: 30/60/120 s stretched in proportion to a bound past 15 min, never shrunk. */
147
+ function scheduleFor(boundSec) {
148
+ const k = Math.max(1, boundSec / BOOTSTRAP.branchWaitSec);
149
+ return BOOTSTRAP.scheduleSec.map((s) => Math.round(s * k));
150
+ }
151
+
152
+ /**
153
+ * Profile + factor → every threshold, each with the basis it came from. A null profile (nothing
154
+ * read, no cache) is the bootstrap in full.
155
+ */
156
+ function thresholds(prof, factor = DEFAULT_FACTOR) {
157
+ const f = Number.isFinite(factor) && factor >= 1 ? factor : DEFAULT_FACTOR;
158
+ const p = prof || {};
159
+ const branch = boundFor(p.branch, f, BOOTSTRAP.branchWaitSec);
160
+ const trunk = boundFor(p.trunk, f, BOOTSTRAP.trunkWaitSec);
161
+ const anyMeasured = branch.basis === 'measured' || trunk.basis === 'measured';
162
+ const wedgeAgeSec = anyMeasured ? Math.min(BOOTSTRAP.wedgeAgeSec, ceilMinute(f * Math.max(branch.sec, trunk.sec))) : BOOTSTRAP.wedgeAgeSec;
163
+ const lagMeasured = p.lag && p.lag.source === 'measured' && Number.isFinite(p.lag.p95Sec);
164
+ const emptyReadGraceSec = lagMeasured ? Math.max(PLATFORM_FLOOR_SEC, ceilMinute(f * p.lag.p95Sec)) : BOOTSTRAP.emptyReadGraceSec;
165
+ return {
166
+ factor: f,
167
+ branchWaitSec: branch.sec,
168
+ trunkWaitSec: trunk.sec,
169
+ ciWaitDefaultSec: { branch: branch.sec, trunk: trunk.sec, any: Math.max(branch.sec, trunk.sec) },
170
+ wedgeAgeSec,
171
+ emptyReadGraceSec,
172
+ zeroJobsFloorSec: BOOTSTRAP.zeroJobsFloorSec,
173
+ scheduleSec: { branch: scheduleFor(branch.sec), trunk: scheduleFor(trunk.sec), any: scheduleFor(Math.max(branch.sec, trunk.sec)) },
174
+ basis: {
175
+ branchWait: branch.basis,
176
+ trunkWait: trunk.basis,
177
+ wedgeAge: anyMeasured ? 'measured' : 'bootstrap',
178
+ emptyReadGrace: lagMeasured ? 'measured' : 'bootstrap',
179
+ zeroJobsFloor: 'default',
180
+ },
181
+ };
182
+ }
183
+
184
+ /** Which bound a wait uses: trunk when the target is trunk, branch for any other branch, else `any`. */
185
+ function kindFor({ branch = null, trunk = null, onTrunk = null } = {}) {
186
+ if (branch) return branch === trunk ? 'trunk' : 'branch';
187
+ if (onTrunk === true) return 'trunk';
188
+ if (onTrunk === false) return 'branch';
189
+ return 'any';
190
+ }
191
+
192
+ module.exports = {
193
+ FACTOR_KEY, DEFAULT_FACTOR, MIN_SAMPLES, WINDOW_DAYS, PLATFORM_FLOOR_SEC, BOOTSTRAP,
194
+ parseFactor, shaDurations, profile, thresholds, scheduleFor, kindFor,
195
+ };
@@ -72,24 +72,30 @@ function hoursSince(iso, nowMs) {
72
72
  function wedgedVerdict(run, opts = {}) {
73
73
  if (!run || run.status === 'completed' || run.status === 'none') return { wedged: false, reason: null };
74
74
  const age = hoursSince(run.createdAt, opts.nowMs);
75
+ // #559: both bounds may come from the repo's measured CI (tools/lib/ci-profile.js); absent → today's.
76
+ const floorMin = Number.isFinite(opts.zeroJobsFloorSec) ? opts.zeroJobsFloorSec / 60 : ZERO_JOBS_AGE_FLOOR_MINUTES;
77
+ const wedgeHours = Number.isFinite(opts.wedgeAgeSec) ? opts.wedgeAgeSec / 3600 : WEDGE_AGE_HOURS;
75
78
  if (run.jobCount === 0) {
76
79
  // #171: no createdAt (age unknown) never manufactures a positive here, same posture as the age
77
80
  // backstop below when createdAt is missing/unparseable — a missing signal must not wedge on its own.
78
- const floorHours = ZERO_JOBS_AGE_FLOOR_MINUTES / 60;
81
+ const floorHours = floorMin / 60;
79
82
  if (age !== null && age >= floorHours) {
80
83
  return {
81
84
  wedged: true,
82
- reason: `zero jobs — no runner has ever picked it up (unmoving for ${age.toFixed(2)}h, past the ${ZERO_JOBS_AGE_FLOOR_MINUTES}m floor)`,
85
+ reason: `zero jobs — no runner has ever picked it up (unmoving for ${age.toFixed(2)}h, past the ${fmtMin(floorMin)} floor)`,
83
86
  };
84
87
  }
85
88
  return { wedged: false, reason: null };
86
89
  }
87
- if (age !== null && age >= WEDGE_AGE_HOURS) {
88
- return { wedged: true, reason: `status=${run.status} for ${age.toFixed(1)}h (>= ${WEDGE_AGE_HOURS}h backstop)` };
90
+ if (age !== null && age >= wedgeHours) {
91
+ return { wedged: true, reason: `status=${run.status} for ${age.toFixed(1)}h (>= ${fmtHours(wedgeHours)} backstop)` };
89
92
  }
90
93
  return { wedged: false, reason: null };
91
94
  }
92
95
 
96
+ const fmtMin = (m) => `${Number.isInteger(m) ? m : m.toFixed(1)}m`;
97
+ const fmtHours = (h) => (Number.isInteger(h) ? `${h}h` : `${Math.round(h * 60)}m`);
98
+
93
99
  // #413: how long after a trunk commit "no run at this sha" is still the ordinary state. GitHub
94
100
  // creates a push run seconds after the push, but a ship reading trunk right after another ship
95
101
  // landed it can get there first. Ten minutes covers queueing on a busy account; past it, an empty
@@ -107,7 +113,9 @@ function emptyReadVerdict(committedAtMs, opts = {}) {
107
113
  if (committedAtMs == null || !Number.isFinite(committedAtMs)) return { fresh: false, minutes: null };
108
114
  const now = opts.nowMs != null ? opts.nowMs : Date.now();
109
115
  const minutes = (now - committedAtMs) / 60000;
110
- return { fresh: minutes >= 0 && minutes < EMPTY_READ_GRACE_MINUTES, minutes };
116
+ // #559: the grace may be the repo's measured push→run lag (tools/lib/ci-profile.js); absent → 10 min.
117
+ const graceMinutes = Number.isFinite(opts.graceSec) ? opts.graceSec / 60 : EMPTY_READ_GRACE_MINUTES;
118
+ return { fresh: minutes >= 0 && minutes < graceMinutes, minutes, graceMinutes };
111
119
  }
112
120
 
113
121
  module.exports = { WEDGE_AGE_HOURS, ZERO_JOBS_AGE_FLOOR_MINUTES, EMPTY_READ_GRACE_MINUTES, wedgedVerdict, emptyReadVerdict };
@@ -38,7 +38,10 @@ const EXIT = Object.freeze({
38
38
  });
39
39
 
40
40
  const DEFAULT_SCHEDULE_SEC = Object.freeze([30, 60, 120]);
41
- const DEFAULT_DEADLINE_SEC = 45 * 60;
41
+ // #559: the bootstrap deadline — the same 15 minutes every skill passed as `--timeout 15m`, so a caller
42
+ // that omits the flag no longer silently waits three times as long (it was 45 min). Once a repo has CI
43
+ // history, `colab ci-wait` derives its deadline from it instead (tools/lib/ci-profile.js).
44
+ const DEFAULT_DEADLINE_SEC = 15 * 60;
42
45
 
43
46
  /** Seconds to sleep before poll number `i` (0-based, i ≥ 1); the last step repeats. */
44
47
  function delayFor(i, schedule = DEFAULT_SCHEDULE_SEC) {
@@ -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 };