@futurelastic/colab-handbook 1.15.0-rc.2 → 1.15.0-rc.4

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
@@ -1521,6 +1521,17 @@ function auditRepoInner(target, ctx) {
1521
1521
  if (!ds.valid) fail(ds.reason);
1522
1522
  }
1523
1523
 
1524
+ // ---- docs-only-paths (#626) -----------------------------------------------
1525
+ // Extra repo paths whose content files (text + the design-artifact binaries) count as
1526
+ // documentation for the no-CI-wait path only (tools/lib/docs-only.js parseDocsOnlyPaths) — never
1527
+ // for the autonomy exception. Reported as the list (`[]` when absent), or null when invalid. An
1528
+ // invalid value fails: every reader takes it as absent, so the declaration silently adds nothing.
1529
+ {
1530
+ const dp = docsOnlyLib.parseDocsOnlyPaths(cfg);
1531
+ info.docsOnlyPaths = dp.valid ? dp.include : null;
1532
+ if (!dp.valid) fail(dp.reason);
1533
+ }
1534
+
1524
1535
  // ---- ship-gate-workflows / ship-ignore-workflows (#503) ---------------------
1525
1536
  // Which workflow runs at trunk's head count as "trunk CI" for ship. Absent = the runs that verify
1526
1537
  // the code (push / pull_request triggered); post-CI release/deploy runs are set aside. An invalid
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.15.0-rc.2"
36
+ "version": "1.15.0-rc.4"
37
37
  }
package/tools/colab CHANGED
@@ -1652,7 +1652,7 @@ function commentOnce(repoAbs, num, fields, text) {
1652
1652
  * in (previous final, sha], minus `exclude` (the release tracking issues). Idempotent by event marker.
1653
1653
  * Shared by `release finalize` and, on route deploy-tag-fast (#446), `release cut`.
1654
1654
  */
1655
- function announceCarried(repoAbs, { tagNames, exclude, version, sha }) {
1655
+ function announceCarried(repoAbs, { tagNames, exclude, version, sha, early = null }) {
1656
1656
  const prev = releaseFinalize.previousFinal(tagNames, version);
1657
1657
  if (!prev) return { range: null, issues: [], posted: [], skipped: [], detail: 'no previous final — the first version announces nothing' };
1658
1658
  const log = git.git(['log', '--format=%B%x00', `${prev}..${sha}`], repoAbs);
@@ -1663,7 +1663,7 @@ function announceCarried(repoAbs, { tagNames, exclude, version, sha }) {
1663
1663
  const view = git.ghIssueView(repoAbs, n, ['comments']);
1664
1664
  if (!view) { skipped.push(n); continue; }
1665
1665
  if (releaseFinalize.hasEvent(view.comments, releaseFinalize.releasedEvent(version))) continue;
1666
- const r = git.ghIssueComment(repoAbs, n, releaseFinalize.releasedComment(version, sha));
1666
+ const r = git.ghIssueComment(repoAbs, n, releaseFinalize.releasedComment(version, sha, early));
1667
1667
  if (r.ok) posted.push(n); else { skipped.push(n); warn(`could not comment on #${n}: ${String(r.stderr || '').split('\n')[0]}`); }
1668
1668
  }
1669
1669
  return { range: `${prev}..${version}`, issues: nums, posted, skipped };
@@ -1967,7 +1967,7 @@ workflow refuses a private repo itself.
1967
1967
  (publish true, or nothing declared); exit 1 when the npm keys are declared but cannot publish.
1968
1968
  `;
1969
1969
 
1970
- const HELP_RELEASE_FINALIZE = `colab release finalize [--repo <path>] [--auto | --tag vX.Y.Z-rc.N [--answered-by <name>]] [--dry] [--json]
1970
+ const HELP_RELEASE_FINALIZE = `colab release finalize [--repo <path>] [--auto | --tag vX.Y.Z-rc.N [--answered-by <name> [--early]]] [--dry] [--json]
1971
1971
 
1972
1972
  Take the newest release CANDIDATE (a vX.Y.Z-rc.N tag made by \`colab release cut\`) one step further
1973
1973
  under CONVENTIONS.md §6's release rung, re-checking everything at the moment it runs. Every run:
@@ -1999,7 +1999,8 @@ under CONVENTIONS.md §6's release rung, re-checking everything at the moment it
1999
1999
 
2000
2000
  Conditions (--json checks[].condition; required:false means reported, not blocking, on this row):
2001
2001
  release-policy candidate tracking-issue release-hold regressions test-period trunk-green
2002
- ci-green full-suite cut-run schema-additive switch-dependencies final-grant migration-grant human
2002
+ ci-green full-suite cut-run schema-additive switch-dependencies final-grant migration-grant
2003
+ early-final human
2003
2004
 
2004
2005
  regressions blocked_by edges on the tracking issue: open -> refused; closed after the period
2005
2006
  began -> needs-new-candidate. Record one with: colab blocked <tracking> --by <issue>
@@ -2037,16 +2038,26 @@ Conditions (--json checks[].condition; required:false means reported, not blocki
2037
2038
  every row; release-hold and regressions as always. Newer candidates stay open
2038
2039
  for the next version — only versions below the final are closed as superseded
2039
2040
  --answered-by <n> with COLAB_HUMAN=1 and --tag: the human bar for a final that is a human act.
2040
- No field, flag or project.yml value lowers it, and it never shortens a test period.
2041
- Where the final is a human act the period is informational anyway, and
2042
- release.test-period: 0d declares none at all (#549)
2041
+ No field, flag or project.yml value lowers it, and on its own it never shortens a
2042
+ test period. Where the final is a human act the period is informational anyway,
2043
+ and release.test-period: 0d declares none at all (#549)
2044
+ --early with COLAB_HUMAN=1, --tag and --answered-by, on a route whose final is automatic
2045
+ (#627): finalize the newest candidate before its test period elapses. The floor
2046
+ binds the machine, not a person who answers for the release: test-period is
2047
+ reported, not required; trunk-green stays required over the elapsed part of the
2048
+ window, and every other check applies. The tag message, the tracking issue and
2049
+ every "Released in" comment record who answered and how much of the period had
2050
+ elapsed. Refused without the bar, on an older candidate, and where the final is
2051
+ already a human act (deploy-tag, or automatic only by release.final-grant).
2052
+ --auto never takes it
2043
2053
  --dry measure and report; open, post, tag and close nothing
2044
2054
  --json { repo, row, route, final, testPeriodDays, lastFinal, dry, auto, candidate, tracking,
2045
2055
  periodStart, periodEndsAt, state, tagged, finalTag, checks, handoff,
2046
2056
  skipped (--auto: [{tag, state, detail?}] — the other open candidates),
2047
2057
  channel (null, or {channel, ok, action, detail} — the stable move, #445),
2048
2058
  announced (null, or {range, issues, posted, skipped} — the "Released in" comments),
2049
- grant (null, or {issue, ruledBy} — the operator grant that made this final automatic) }
2059
+ grant (null, or {issue, ruledBy} — the operator grant that made this final automatic),
2060
+ early (null, or {answeredBy, elapsedHours, periodHours, at} — an early human final, #627) }
2050
2061
 
2051
2062
  Needs origin and gh (the tracking issue, runs and edges live on GitHub). Never cuts a candidate, never
2052
2063
  a major, never removes a label or an edge. Exit 0 when finalized (or would be) or candidate-ready; 1
@@ -2079,17 +2090,21 @@ function releaseHeavyFact(repoAbs, doc, cand) {
2079
2090
  function cmdReleaseFinalize(argv) {
2080
2091
  const opts = parseArgs(argv, {
2081
2092
  values: { '--repo': 'repo', '--tag': 'tag', '--answered-by': 'answeredBy' },
2082
- flags: { '--dry': 'dry', '--json': 'json', '--auto': 'auto', '-h': 'help', '--help': 'help' },
2093
+ flags: { '--dry': 'dry', '--json': 'json', '--auto': 'auto', '--early': 'early', '-h': 'help', '--help': 'help' },
2083
2094
  });
2084
2095
  if (opts.help) return print(HELP_RELEASE_FINALIZE);
2085
2096
  if (opts._.length) throw new UserError(`release finalize takes no positional arguments (got: ${opts._.join(' ')})`);
2086
2097
  // #423: --auto is the release workflow's mode. The human bar names one reviewed candidate; --auto
2087
2098
  // picks among them — the two never combine, so an unattended run can never carry a human's assertion.
2088
- if (opts.auto && (opts.tag || opts.answeredBy)) throw new UserError('--auto picks the candidate itself and never carries the human bar — drop --tag/--answered-by, or drop --auto');
2099
+ if (opts.auto && (opts.tag || opts.answeredBy || opts.early)) throw new UserError('--auto picks the candidate itself and never carries the human bar — drop --tag/--answered-by/--early, or drop --auto');
2089
2100
  const humanBar = !opts.auto && process.env.COLAB_HUMAN === '1' && !!opts.answeredBy;
2090
2101
  if (humanBar && !opts.tag) {
2091
2102
  throw new UserError('the human bar needs --tag <vX.Y.Z-rc.N>: it names the exact candidate the human reviewed, so a newer one cut meanwhile is never finalized in its place');
2092
2103
  }
2104
+ // #627: an early final is a human's act alone — refused before anything is read without the whole bar.
2105
+ if (opts.early && !humanBar) {
2106
+ throw new UserError('--early finalizes before the test period elapses only as a human act: run it with COLAB_HUMAN=1, --tag <vX.Y.Z-rc.N> and --answered-by <your name>');
2107
+ }
2093
2108
  const repoAbs = resolveRepo(opts);
2094
2109
  if (!isGhUsable(repoAbs)) throw new UserError(`gh not usable (${ghUnusableWhy(repoAbs)}) — the tracking issue, runs and regression edges live on GitHub`);
2095
2110
  const doc = projectDoc(repoAbs);
@@ -2222,7 +2237,8 @@ function cmdReleaseFinalize(argv) {
2222
2237
  ci: conditions.ci, suite: conditions.suite, cutRun, deployReport, schema: conditions.schema, switches: conditions.switches,
2223
2238
  heavy: releaseHeavyFact(repoAbs, doc, cand), // #610
2224
2239
  manifests, ancestry, tags: tagNames, finalGrant, migrations,
2225
- human: { bar: humanBar, answeredBy: opts.answeredBy || null },
2240
+ human: { bar: humanBar, answeredBy: opts.answeredBy || null, early: !!opts.early },
2241
+ now, // #627: how much of the period an early final cut short
2226
2242
  });
2227
2243
  return { candidate: cand, verdict, period, tracking, trunk };
2228
2244
  };
@@ -2281,10 +2297,10 @@ function cmdReleaseFinalize(argv) {
2281
2297
  // #426: one "Released in vX.Y.Z" comment on every issue the version carries (release-finalize.js
2282
2298
  // carriedIssues — the closing references in (previous final, sha]). Idempotent by event marker.
2283
2299
  let announced = null;
2284
- const announceRelease = (version, sha) => announceCarried(repoAbs, { tagNames, exclude: records.map((r) => r.number), version, sha });
2300
+ const announceRelease = (version, sha, early = null) => announceCarried(repoAbs, { tagNames, exclude: records.map((r) => r.number), version, sha, early });
2285
2301
  if (!opts.dry) {
2286
2302
  if (verdict.state === 'finalized') {
2287
- const actor = humanBar && !verdict.grant ? `${opts.answeredBy} (human bar: COLAB_HUMAN=1)` : `automatic — clean test period (CONVENTIONS.md §6)${verdict.grant ? `, by the operator's grant (decision #${verdict.grant.issue})` : ''}${walk ? ', newest candidate clean on its own clock (--auto)' : ''}${selection.older ? `, an older candidate clean on its own clock (--tag; newest open: ${selection.newest})` : ''}`;
2303
+ const actor = humanBar && !verdict.grant ? `${opts.answeredBy} (human bar: COLAB_HUMAN=1${verdict.early ? ', --early' : ''})` : `automatic — clean test period (CONVENTIONS.md §6)${verdict.grant ? `, by the operator's grant (decision #${verdict.grant.issue})` : ''}${walk ? ', newest candidate clean on its own clock (--auto)' : ''}${selection.older ? `, an older candidate clean on its own clock (--tag; newest open: ${selection.newest})` : ''}`;
2288
2304
  const message = releaseFinalize.tagMessage(verdict, { candidate: cand, period, actor });
2289
2305
  const t = git.git(['tag', '-a', '--cleanup=verbatim', cand.version, cand.sha, '-m', message], repoAbs);
2290
2306
  if (!t.ok) throw new UserError(`git tag ${cand.version} failed: ${(t.stderr || '').split('\n')[0]}`);
@@ -2318,13 +2334,13 @@ function cmdReleaseFinalize(argv) {
2318
2334
  `**${cand.tag} is ready.** The final tag is a human act on this repo — the one command, run by a human:\n\n\`\`\`sh\n${verdict.handoff}\n\`\`\``);
2319
2335
  }
2320
2336
  if (tagged) {
2321
- comment(tracking.number, { state: 'finalized', tag: cand.version }, `**${cand.version}** tagged final on \`${shortSha(cand.sha)}\` (from ${cand.tag}).`);
2337
+ comment(tracking.number, { state: 'finalized', tag: cand.version }, `**${cand.version}** tagged final on \`${shortSha(cand.sha)}\` (from ${cand.tag}).${verdict.early ? `\n\nEarly final: ${releaseFinalize.earlyLine(verdict.early)}.` : ''}`);
2322
2338
  close(tracking.number);
2323
2339
  }
2324
2340
  }
2325
2341
  // #426: every issue the final carries hears which version has it — on the run that tags, and on
2326
2342
  // the already-final resume (a run that died between the tag push and these comments finishes them).
2327
- if (tagged) announced = announceRelease(cand.version, cand.sha);
2343
+ if (tagged) announced = announceRelease(cand.version, cand.sha, verdict.early || null);
2328
2344
  // Superseded records: only versions BELOW one just tagged, on every path (#548). Before #548 a run
2329
2345
  // without --auto closed every other open version at once, because only the newest candidate could
2330
2346
  // ever be finalized; now `--tag` may finalize any open candidate, so an older version's record has
@@ -2358,7 +2374,7 @@ function cmdReleaseFinalize(argv) {
2358
2374
  lastFinal, dry: !!opts.dry, auto: !!opts.auto, candidate: cand, tracking: trackingOut,
2359
2375
  periodStart: period ? period.start : null, periodEndsAt: period ? period.endsAt : null,
2360
2376
  state: verdict.state, tagged, finalTag: verdict.finalTag, checks: verdict.checks, handoff: verdict.handoff,
2361
- skipped: walk ? skipped : undefined, why, next: why ? why.next : null, announced, grant: verdict.grant || null, channel,
2377
+ skipped: walk ? skipped : undefined, why, next: why ? why.next : null, announced, grant: verdict.grant || null, early: verdict.early || null, channel,
2362
2378
  }, null, 2));
2363
2379
  } else {
2364
2380
  print(`colab release finalize${opts.auto ? ' --auto' : ''} — ${shortRepo(repoAbs)} (last final: ${lastFinal || 'none'}${cand ? `, candidate: ${cand.tag}` : ''})`);
@@ -2370,6 +2386,7 @@ function cmdReleaseFinalize(argv) {
2370
2386
  }
2371
2387
  print('');
2372
2388
  print(`state: ${verdict.state}${opts.dry ? ' [--dry: nothing written]' : ''}${tagged ? ` — tagged ${verdict.finalTag} and pushed it to ${remote}` : ''}`);
2389
+ if (verdict.early) print(`early final: ${releaseFinalize.earlyLine(verdict.early)}`);
2373
2390
  if (why) print(`why no final: ${why.line}`);
2374
2391
  if (announced && announced.issues.length) print(`released in ${verdict.finalTag || version0}: told ${announced.posted.length ? announced.posted.map((n) => `#${n}`).join(', ') : 'nobody new'} (carried: ${announced.issues.map((n) => `#${n}`).join(', ')}${announced.skipped.length ? `; unreadable: ${announced.skipped.map((n) => `#${n}`).join(', ')}` : ''})`);
2375
2392
  if (channel && channel.ok) print(`✓ ${channel.detail}`);
@@ -11817,13 +11834,15 @@ const DOCS_TIP_WALK = 50;
11817
11834
  function docsOnlyTipDoor(repoAbs, trunk, tipSha, readOpts) {
11818
11835
  if (!tipSha) return null;
11819
11836
  const setting = docsOnly.parseCiDocsSkip(projectDoc(repoAbs));
11837
+ const declared = docsOnly.parseDocsOnlyPaths(projectDoc(repoAbs));
11820
11838
  if (!setting.on) return null;
11821
11839
  const list = git.git(['rev-list', '--first-parent', `--max-count=${DOCS_TIP_WALK}`, tipSha], repoAbs);
11822
11840
  if (!list.ok) return null;
11823
11841
  let skipped = 0;
11824
11842
  let code = null;
11825
11843
  for (const sha of list.stdout.split('\n').map((x) => x.trim()).filter(Boolean)) {
11826
- const c = docsOnly.commitChanges(git, repoAbs, sha, { exclude: setting.exclude });
11844
+ // #626: the declared `docs-only-paths` widen this door (the no-CI-wait path), never autonomy.
11845
+ const c = docsOnly.commitChanges(git, repoAbs, sha, { exclude: setting.exclude, include: declared.include });
11827
11846
  if (!c.docsOnly) { code = sha; break; }
11828
11847
  skipped++;
11829
11848
  }
@@ -12,6 +12,9 @@ export function decodeTrackingMarker(body: string | null | undefined): string |
12
12
  export function encodeReleaseEvent(fields: Record<string, string | number>): string;
13
13
  export function decodeReleaseEvent(marker: string | null | undefined): Record<string, string> | null;
14
14
 
15
- export function encodeReleasedComment(c?: { version: string; sha: string }): string;
16
- /** `sha` is the 7-character form the comment carries. */
17
- export function decodeReleasedComment(body: string | null | undefined): { version: string; sha: string } | null;
15
+ /** #627: an early human final — who answered, and how much of the test period had elapsed. */
16
+ export interface EarlyFinal { answeredBy: string; elapsedHours: number; periodHours: number }
17
+
18
+ export function encodeReleasedComment(c?: { version: string; sha: string; early?: EarlyFinal | null }): string;
19
+ /** `sha` is the 7-character form the comment carries; `early` only when the comment names an early final. */
20
+ export function decodeReleasedComment(body: string | null | undefined): { version: string; sha: string; early?: EarlyFinal } | null;
@@ -11,7 +11,8 @@
11
11
  * event marker — `<!-- colab:release-event k=v … -->`, one per thing announced on the
12
12
  * tracking issue, keys in the order written. Its exact presence is what makes
13
13
  * a re-run post nothing twice, so key order is part of the wire format.
14
- * released comment — the event marker `released=vX.Y.Z` plus one visible line, posted once on
14
+ * released comment — the event marker `released=vX.Y.Z` plus one visible line (two after an early
15
+ * human final, #627), posted once on
15
16
  * each issue a release carried.
16
17
  *
17
18
  * Deciding which candidate, which period, and whether to finalize stays in
@@ -21,7 +22,7 @@
21
22
  const VERSION_RE = /^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/;
22
23
  const TRACKING_MARKER_RE = /^\s*<!--\s*colab:release\s+version=(v[0-9]+\.[0-9]+\.[0-9]+)\s*-->/;
23
24
  const RELEASE_EVENT_RE = /^<!-- colab:release-event((?: [^\s=]+=\S*)+) -->$/;
24
- const RELEASED_COMMENT_RE = /^<!-- colab:release-event released=(\S+) -->\nReleased in \*\*(\S+)\*\* \(`([^`]*)`\)\.$/;
25
+ const RELEASED_COMMENT_RE = /^<!-- colab:release-event released=(\S+) -->\nReleased in \*\*(\S+)\*\* \(`([^`]*)`\)\.(?:\nEarly final: answered by ([^\n]+) after ([0-9]+)h of the ([0-9]+)h test period\.)?$/;
25
26
 
26
27
  /** `vX.Y.Z` → the tracking marker. */
27
28
  function encodeTrackingMarker(version) { return `<!-- colab:release version=${version} -->`; }
@@ -52,16 +53,24 @@ function decodeReleaseEvent(marker) {
52
53
  return out;
53
54
  }
54
55
 
55
- /** `{version, sha}` → the "released in" comment; `sha` is shortened to 7 characters. */
56
- function encodeReleasedComment({ version, sha } = {}) {
57
- return `${encodeReleaseEvent({ released: version })}\nReleased in **${version}** (\`${String(sha || '').slice(0, 7)}\`).`;
56
+ /**
57
+ * `{version, sha, early?}` → the "released in" comment; `sha` is shortened to 7 characters. `early`
58
+ * ({answeredBy, elapsedHours, periodHours}, #627) adds one line naming an early human final; without
59
+ * it the comment is byte-identical to the two-line form every earlier final wrote.
60
+ */
61
+ function encodeReleasedComment({ version, sha, early = null } = {}) {
62
+ const base = `${encodeReleaseEvent({ released: version })}\nReleased in **${version}** (\`${String(sha || '').slice(0, 7)}\`).`;
63
+ if (!early || !Number.isInteger(early.elapsedHours) || !Number.isInteger(early.periodHours)) return base;
64
+ return `${base}\nEarly final: answered by ${String(early.answeredBy).replace(/\s+/g, ' ').trim()} after ${early.elapsedHours}h of the ${early.periodHours}h test period.`;
58
65
  }
59
66
 
60
- /** A "released in" comment → `{version, sha}` (sha as written, 7 characters), or null. */
67
+ /** A "released in" comment → `{version, sha}` (sha as written, 7 characters) plus `early` when it names one (#627), or null. */
61
68
  function decodeReleasedComment(body) {
62
69
  const m = RELEASED_COMMENT_RE.exec(String(body == null ? '' : body).replace(/\r\n/g, '\n').trim());
63
70
  if (!m || m[1] !== m[2]) return null;
64
- return { version: m[1], sha: m[3] };
71
+ const out = { version: m[1], sha: m[3] };
72
+ if (m[4] !== undefined) out.early = { answeredBy: m[4], elapsedHours: Number(m[5]), periodHours: Number(m[6]) };
73
+ return out;
65
74
  }
66
75
 
67
76
  module.exports = {
@@ -745,6 +745,19 @@
745
745
  "sha": "3e2f810"
746
746
  },
747
747
  "note": "synthetic: no final has announced on an issue yet"
748
+ },
749
+ {
750
+ "wire": "<!-- colab:release-event released=v2.4.0 -->\nReleased in **v2.4.0** (`9c1d2e3`).\nEarly final: answered by Ada Lovelace after 30h of the 72h test period.",
751
+ "decoded": {
752
+ "version": "v2.4.0",
753
+ "sha": "9c1d2e3",
754
+ "early": {
755
+ "answeredBy": "Ada Lovelace",
756
+ "elapsedHours": 30,
757
+ "periodHours": 72
758
+ }
759
+ },
760
+ "note": "synthetic: an early human final (#627) — no early final has announced yet"
748
761
  }
749
762
  ]
750
763
  },
@@ -16,6 +16,11 @@
16
16
  * (shipDocsOnly, below — on by default, narrowed by `ci-docs-skip`). So widening anything here
17
17
  * widens BOTH at once — the binary design-artifact rule below did exactly that: a PNG mockup under
18
18
  * `docs/design/` is now docs-only for the autonomy exception too (CONVENTIONS.md §2).
19
+ *
20
+ * #626: the ONE repo-declared widening, `docs-only-paths:`, reaches only the no-CI-wait path
21
+ * (shipDocsOnly and the trunk-tip door) through classify()'s `include` option. branchChanges and
22
+ * directChanges called without it — the #345 autonomy exception — are exactly as narrow as before:
23
+ * no project.yml field widens who may merge.
19
24
  */
20
25
 
21
26
  /** Extensions that count as documentation. Compared exactly (`README.MD` does not match). */
@@ -35,6 +40,22 @@ function docsBinaryOk(p) {
35
40
  const dot = base.lastIndexOf('.');
36
41
  return dot > 0 && DOCS_BINARY_EXTENSIONS.includes(base.slice(dot).toLowerCase());
37
42
  }
43
+ /**
44
+ * #626: under a path the repo declares in `docs-only-paths`, a file with one of these extensions is
45
+ * documentation — text or binary. Every other extension there is not. Case-insensitive.
46
+ */
47
+ const DECLARED_EXTENSIONS = Object.freeze([...DOC_EXTENSIONS, ...DOCS_BINARY_EXTENSIONS]);
48
+ function extOf(p) {
49
+ const s = String(p);
50
+ const base = s.slice(s.lastIndexOf('/') + 1);
51
+ const dot = base.lastIndexOf('.');
52
+ return dot > 0 ? base.slice(dot).toLowerCase() : '';
53
+ }
54
+ /** The declared `docs-only-paths` member a content file sits in, or null. */
55
+ function includedBy(p, include) {
56
+ const m = excludedBy(p, include);
57
+ return m && DECLARED_EXTENSIONS.includes(extOf(p)) ? m : null;
58
+ }
38
59
  /** Rules and agent instructions: never documentation, at any depth, even though they are `.md`. */
39
60
  const NEVER_BASENAMES = Object.freeze(['CLAUDE.md', 'CLAUDE.local.md', 'AGENTS.md']);
40
61
  /**
@@ -67,7 +88,7 @@ const MODE_GITLINK = '160000';
67
88
  * Classify ONE path by name alone. Returns `null` when the path is documentation, else the reason it
68
89
  * is not.
69
90
  */
70
- function pathReason(p) {
91
+ function pathReason(p, { include = [] } = {}) {
71
92
  const segs = String(p).split('/');
72
93
  const base = segs[segs.length - 1];
73
94
  if (NEVER_BASENAMES.includes(base)) return `${base} is agent rules, not documentation`;
@@ -82,6 +103,7 @@ function pathReason(p) {
82
103
  }
83
104
  }
84
105
  if (String(p).startsWith(DOCS_DIR)) return null;
106
+ if (includedBy(p, include)) return null;
85
107
  const dot = base.lastIndexOf('.');
86
108
  const ext = dot > 0 ? base.slice(dot) : '';
87
109
  if (DOC_EXTENSIONS.includes(ext)) return null;
@@ -95,18 +117,18 @@ function pathReason(p) {
95
117
  * Returns `{ docsOnly, files, offenders: [{ path, reason }], reason }`. `files` counts distinct paths.
96
118
  * `reason` is one line for a human, set on both outcomes.
97
119
  */
98
- function classify(entries, { exclude = [] } = {}) {
120
+ function classify(entries, { exclude = [], include = [] } = {}) {
99
121
  const paths = new Map();
100
122
  for (const e of entries || []) {
101
123
  const why = [];
102
- const nameWhy = pathReason(e.path);
124
+ const nameWhy = pathReason(e.path, { include });
103
125
  if (nameWhy) why.push(nameWhy);
104
126
  // #606: a path the repo's suite reads, listed in `ci-docs-skip` — documentation, but it needs CI.
105
127
  const listed = excludedBy(e.path, exclude);
106
128
  if (!nameWhy && listed) why.push(`listed in ci-docs-skip (${listed}) — the suite reads it`);
107
129
  if (e.oldMode === MODE_SYMLINK || e.newMode === MODE_SYMLINK) why.push('symlink change');
108
130
  if (e.oldMode === MODE_GITLINK || e.newMode === MODE_GITLINK) why.push('submodule change');
109
- if (e.binary && !docsBinaryOk(e.path)) why.push('binary change');
131
+ if (e.binary && !docsBinaryOk(e.path) && !includedBy(e.path, include)) why.push('binary change');
110
132
  const prev = paths.get(e.path) || [];
111
133
  paths.set(e.path, [...new Set([...prev, ...why])]);
112
134
  }
@@ -201,7 +223,8 @@ function commitChanges(git, repo, sha, opts = {}) {
201
223
  function shipDocsOnly(git, repo, base, branch, doc) {
202
224
  const setting = parseCiDocsSkip(doc);
203
225
  if (!setting.on) return { docsOnly: false, files: 0, offenders: [], reason: setting.reason, setting };
204
- return { ...branchChanges(git, repo, base, branch, { exclude: setting.exclude }), setting };
226
+ const declared = parseDocsOnlyPaths(doc);
227
+ return { ...branchChanges(git, repo, base, branch, { exclude: setting.exclude, include: declared.include }), setting, declared };
205
228
  }
206
229
 
207
230
  /**
@@ -265,8 +288,38 @@ function parseCiDocsSkip(doc) {
265
288
  reason: exclude.length ? `ci-docs-skip on, except ${exclude.join(', ')}` : 'ci-docs-skip on — colab ship lands a docs-only change without waiting for CI' };
266
289
  }
267
290
 
291
+ /**
292
+ * #626: `docs-only-paths:` in project.yml — extra repo paths whose content files (DECLARED_EXTENSIONS:
293
+ * the text types plus the design-artifact binaries) count as documentation FOR THE NO-CI-WAIT PATH
294
+ * ONLY (shipDocsOnly, the trunk-tip door). It never widens the autonomy exception. Shape: a list of
295
+ * plain repo paths, validated exactly as `ci-docs-skip` members are — no glob (write
296
+ * `public/images/blog`, not `public/images/blog/**`). Absent or `[]` = nothing added. An invalid
297
+ * value reads as absent (the stricter direction: nothing widened); the audit fails it.
298
+ * `ci-docs-skip` members still win over it, and so do the never-rules above.
299
+ */
300
+ const DOCS_ONLY_PATHS_KEY = 'docs-only-paths';
301
+ function parseDocsOnlyPaths(doc) {
302
+ const has = !!doc && Object.prototype.hasOwnProperty.call(doc, DOCS_ONLY_PATHS_KEY);
303
+ if (!has) return { declared: false, valid: true, include: [], reason: 'docs-only-paths absent — nothing added to the docs-only rule' };
304
+ const v = doc[DOCS_ONLY_PATHS_KEY];
305
+ const bad = (why) => ({ declared: true, valid: false, include: [],
306
+ reason: `docs-only-paths ${why} — it must be a list of plain repo paths (no glob, \`..\`, \`.\` or leading \`/\`); every reader takes anything else as absent, so the declaration silently adds nothing` });
307
+ if (!Array.isArray(v)) return bad(v === null || v === undefined ? 'is empty' : `is ${JSON.stringify(v)}`);
308
+ const include = [];
309
+ for (const m of v) {
310
+ const s = typeof m === 'string' ? m.replace(/\/+$/, '') : null;
311
+ if (!s || !/^[A-Za-z0-9._/-]+$/.test(s) || s.startsWith('/') || s.split('/').some((x) => x === '..' || x === '.' || x === '')) {
312
+ return bad(`lists ${JSON.stringify(m)}, which is not a plain repo path`);
313
+ }
314
+ include.push(s);
315
+ }
316
+ return { declared: true, valid: true, include,
317
+ reason: include.length ? `docs-only-paths: ${include.join(', ')} (content files there skip the CI wait)` : 'docs-only-paths: [] — nothing added' };
318
+ }
319
+
268
320
  module.exports = {
269
321
  DOC_EXTENSIONS, DOCS_DIR, DOCS_BINARY_EXTENSIONS, docsBinaryOk, NEVER_BASENAMES, NEVER_DIRS, NEVER_SUBDIRS,
270
322
  pathReason, classify, parseRaw, parseBinary, readEntries, branchChanges, directChanges,
271
323
  CI_DOCS_SKIP_KEY, parseCiDocsSkip, excludedBy, commitChanges, shipDocsOnly,
324
+ DECLARED_EXTENSIONS, includedBy, DOCS_ONLY_PATHS_KEY, parseDocsOnlyPaths,
272
325
  };
@@ -78,7 +78,7 @@ const STATES = Object.freeze([
78
78
  const CONDITIONS = Object.freeze([
79
79
  'release-policy', 'candidate', 'tracking-issue', 'release-hold', 'regressions', 'test-period', 'trunk-green',
80
80
  'ci-green', 'full-suite', 'heavy-lane', 'cut-run', 'deploy-report', 'schema-additive', 'switch-dependencies',
81
- ...releaseTag.PRE_TAG_CONDITIONS, 'final-grant', 'migration-grant', 'human',
81
+ ...releaseTag.PRE_TAG_CONDITIONS, 'final-grant', 'migration-grant', 'early-final', 'human',
82
82
  ]);
83
83
 
84
84
  // A completed run with one of these conclusions does not make trunk red.
@@ -660,14 +660,43 @@ function decide(facts) {
660
660
  }
661
661
  const reg = f.regressions || { ok: false, permanent: false, detail: 'not measured' };
662
662
  add('regressions', reg.ok, reg.detail);
663
+ const per = f.period || { elapsed: false, detail: 'not measured' };
664
+ // #627: an early human final. On a route whose final is automatic (and not by an operator's grant —
665
+ // a granted deploy-tag final is already a human act whenever a human runs it), the test-period floor
666
+ // binds the MACHINE: a human who answers for the release (the bar: COLAB_HUMAN=1 + --answered-by,
667
+ // and --early, all three) may finalize the newest candidate before its period elapses. test-period
668
+ // is then reported, not required; trunk-green stays required over the part of the window that has
669
+ // elapsed (the CLI reads it up to now); every other check applies unchanged. --auto never carries
670
+ // the bar, so nothing an agent sets alone shortens a period.
671
+ let early = null;
672
+ if (h.early) {
673
+ const why = !h.bar ? 'needs the human bar (COLAB_HUMAN=1 + --answered-by)'
674
+ : finalMode !== 'auto' ? 'applies only where the final is automatic — here the final is already a human act, and the test period is not required of it'
675
+ : granted ? `applies only where the final is automatic by the row — here it is automatic only by the operator's grant (release.final-grant #${granted.issue}), so a human final already skips the period`
676
+ : s.older ? 'applies only to the newest open candidate — an older one is finalized only once its own period elapsed clean (#548)'
677
+ : null;
678
+ if (why) add('early-final', false, `--early ${why}`);
679
+ else {
680
+ const startMs = Date.parse(per.start);
681
+ const nowMs = Date.parse(f.now);
682
+ const elapsedHours = Number.isNaN(startMs) || Number.isNaN(nowMs) ? null : Math.max(0, Math.floor((nowMs - startMs) / 3600000));
683
+ const periodHours = Number(per.days) * 24;
684
+ early = { answeredBy: h.answeredBy, elapsedHours, periodHours, at: f.now || null };
685
+ add('early-final', true, per.elapsed
686
+ ? `--early by ${h.answeredBy}, but the ${per.days}d test period has already elapsed — an ordinary human final`
687
+ : `early human final, answered by ${h.answeredBy}: ${elapsedHours === null ? 'an unknown part' : `${elapsedHours}h`} of the ${periodHours}h test period elapsed — the floor binds the machine, not a person who answers for the release (CONVENTIONS.md §6)`);
688
+ auto = false;
689
+ }
690
+ }
663
691
  // #548: an older candidate pinned by --tag is finalized only on its own clean clock — the rule
664
692
  // --auto applies to it — whatever the row: a newer candidate exists, so "the human is the test"
665
693
  // no longer explains why THIS one, and its own clean period is what does.
666
694
  const ownClock = auto || !!s.older;
667
- const per = f.period || { elapsed: false, detail: 'not measured' };
668
- add('test-period', per.elapsed, s.older && !auto ? `${per.detail} — required: an older candidate is finalized only once its own period elapsed clean (#548)` : per.detail, ownClock);
695
+ add('test-period', per.elapsed, s.older && !auto ? `${per.detail} — required: an older candidate is finalized only once its own period elapsed clean (#548)` : early && !per.elapsed ? `${per.detail} — reported, not required: an early human final (#627)` : per.detail, ownClock);
669
696
  const tr = f.trunk || { ok: false, permanent: false, pending: false, detail: 'not measured' };
670
- add('trunk-green', tr.ok, tr.detail, ownClock);
697
+ // #627: an early final keeps trunk-green REQUIRED — over the elapsed part of the window.
698
+ const trunkRequired = ownClock || !!early;
699
+ add('trunk-green', tr.ok, early ? `${tr.detail} (the elapsed part of the window, up to the early final)` : tr.detail, trunkRequired);
671
700
  // #565: a run that failed only in deploy jobs is a report on a human final (the human who decides
672
701
  // sees it), and stays a gate on an automatic one. `deployReport` carries the verdicts re-read with
673
702
  // those runs counted as passed; it is absent when no such run exists.
@@ -694,7 +723,7 @@ function decide(facts) {
694
723
  }
695
724
 
696
725
  if (held.length) return out('held');
697
- if ((reg.permanent) || (ownClock && tr.permanent)) return out('needs-new-candidate');
726
+ if ((reg.permanent) || (trunkRequired && tr.permanent)) return out('needs-new-candidate');
698
727
  const blocking = checks.filter((c) => c.required && !c.ok && !['test-period', 'trunk-green', 'human'].includes(c.condition)
699
728
  && !(c.condition === 'heavy-lane' && hv && hv.pending));
700
729
  if (blocking.length) return out('refused');
@@ -702,10 +731,14 @@ function decide(facts) {
702
731
  if (!tr.ok && !tr.pending) return out('refused');
703
732
  if (!per.elapsed || tr.pending) return out('testing');
704
733
  }
734
+ if (early) {
735
+ if (!tr.ok && !tr.pending) return out('refused');
736
+ if (tr.pending) return out('testing');
737
+ }
705
738
  if (hv && hv.pending) return out('testing'); // #610: the heavy lane is still to run or still running
706
739
  if (auto) return out('finalized', { finalTag: cand.version, grant: grantUsed });
707
740
  if (!h.bar) return out('candidate-ready', { handoff: handoffCommand(cand.tag) });
708
- return out('finalized', { finalTag: cand.version });
741
+ return out('finalized', { finalTag: cand.version, ...(early && !per.elapsed ? { early } : {}) });
709
742
  }
710
743
 
711
744
  // ---- announcing the final (#426) ----------------------------------------------------------------
@@ -742,8 +775,18 @@ function previousFinal(tagNames, version) {
742
775
  function releasedEvent(version) { return { released: version }; }
743
776
 
744
777
  /** The comment body posted on each carried issue (marker included) — codec `encodeReleasedComment`. */
745
- function releasedComment(version, sha) {
746
- return releaseCodec.encodeReleasedComment({ version, sha });
778
+ function releasedComment(version, sha, early = null) {
779
+ return releaseCodec.encodeReleasedComment({ version, sha, early });
780
+ }
781
+
782
+ /**
783
+ * #627: the one sentence an early human final is recorded with — on the tag, the tracking issue and
784
+ * every "Released in" comment: who answered, how much of the period had elapsed.
785
+ */
786
+ function earlyLine(early) {
787
+ const e = early || {};
788
+ const part = e.elapsedHours === null || e.elapsedHours === undefined ? 'an unknown part' : `${e.elapsedHours}h`;
789
+ return `answered by ${e.answeredBy} after ${part} of the ${e.periodHours}h test period${e.at ? ` (${e.at})` : ''} — a human final before the period elapsed (CONVENTIONS.md §6)`;
747
790
  }
748
791
 
749
792
  /** The final tag's annotated message: which candidate, which period, every condition, who. */
@@ -754,6 +797,7 @@ function tagMessage(verdict, { candidate, period, actor }) {
754
797
  `Candidate: ${candidate.tag}`,
755
798
  `Commit: ${candidate.sha}`,
756
799
  period ? (period.days === 0 ? 'Test period: none (release.test-period: 0d — the human final is the test)' : `Test period: ${period.start} -> ${period.endsAt}`) : null,
800
+ verdict.early ? `Early final: ${earlyLine(verdict.early)}` : null,
757
801
  `Finalized by: ${actor}`,
758
802
  verdict.grant ? `Automatic final granted by: release.final-grant -> decision #${verdict.grant.issue}${verdict.grant.ruledBy ? `, ruled by ${verdict.grant.ruledBy}` : ''} (an operator's per-repo grant; deleting it, or final: human, revokes it)` : null,
759
803
  '',
@@ -767,6 +811,6 @@ module.exports = {
767
811
  parseVersion, compareVersions, parseCandidate,
768
812
  parseReleaseMarker, releaseMarker, eventMarker, hasEvent, trackingTitle, trackingBody,
769
813
  selectCandidate, openCandidates, pickNewestClean, stateDetail, windowHasRed, whyNoFinal, periodVerdict, cutRunVerdict, isDeployJob, deployOnlyFailures, deployReportDetail, trunkGreenVerdict, windowBranches, mergeWindowRuns, regressionVerdict,
770
- handoffCommand, decide, tagMessage, migrationGrantVerdict,
814
+ handoffCommand, decide, tagMessage, earlyLine, migrationGrantVerdict,
771
815
  carriedIssues, previousFinal, releasedEvent, releasedComment,
772
816
  };