@futurelastic/colab-handbook 1.14.0-rc.8 → 1.14.0-rc.9

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
@@ -1485,6 +1485,18 @@ function auditRepoInner(target, ctx) {
1485
1485
  if (!tr.valid) fail(tr.reason);
1486
1486
  }
1487
1487
 
1488
+ // ---- instruction-files (#602) ---------------------------------------------
1489
+ // `instruction-files: upstream` — a fork whose CLAUDE.md/AGENTS.md belong to the upstream it
1490
+ // tracks; the instruction-file shape is then not judged (checkInstructionFileShape below, and
1491
+ // the shared gate the hook and the CI workflow run). tools/lib/instruction-file.js
1492
+ // parseInstructionFiles is the one reading. An invalid value fails: it reads as absent (judged —
1493
+ // the stricter direction), so the declaration silently does nothing.
1494
+ {
1495
+ const ifl = instructionFile.parseInstructionFiles(cfg);
1496
+ info.instructionFiles = ifl.declared ? ifl.value : null;
1497
+ if (!ifl.valid) fail(ifl.reason);
1498
+ }
1499
+
1488
1500
  // ---- ci-docs-skip (#570) ----------------------------------------------------
1489
1501
  // Opts the CI templates' guard into docs-only mode: a change whose every path is documentation
1490
1502
  // (tools/lib/docs-only.js, the rule colab ship applies), from a green base, skips the suite.
@@ -1816,7 +1828,7 @@ function auditRepoInner(target, ctx) {
1816
1828
  checkInstructionFileBlocks(src, warn, { self: isSelf });
1817
1829
  // #419: and prose left in CLAUDE.md / no AGENTS.md at all — same posture, same reason.
1818
1830
  // #588: and the same finding FAILS where the instruction-file ratchet trips (local repos only).
1819
- checkInstructionFileShape(src, warn, fail, { base: ctx.base, trunk: cfg?.trunk ?? null });
1831
+ checkInstructionFileShape(src, warn, fail, { base: ctx.base, trunk: cfg?.trunk ?? null, upstreamOwned: instructionFile.parseInstructionFiles(cfg).exempt });
1820
1832
  // #599: a caller of the reusable instruction-files workflow narrowed off session branches, or not
1821
1833
  // dispatchable, defeats the ratchet's point (fail on the branch) and the cure rule's way out.
1822
1834
  checkInstructionFilesCaller(src, workflows, cfg?.trunk ?? null, warn);
@@ -2734,7 +2746,12 @@ function instructionRatchet(src, opts) {
2734
2746
  return r;
2735
2747
  }
2736
2748
 
2749
+ //
2750
+ // #602: a fork declaring `instruction-files: upstream` is not judged at all — neither the ratchet's
2751
+ // failure nor the two warnings: its CLAUDE.md/AGENTS.md are the upstream's (CONVENTIONS.md §9, *A
2752
+ // fork of an upstream*), and the --json `instructionFiles` field says why nothing was reported.
2737
2753
  function checkInstructionFileShape(src, warn, fail = warn, opts = {}) {
2754
+ if (opts.upstreamOwned) return;
2738
2755
  const ratchet = instructionRatchet(src, opts);
2739
2756
  if (ratchet && !ratchet.ok) warn(`instruction-file ratchet not evaluated: ${ratchet.error} (#588)`);
2740
2757
  if (ratchet && ratchet.ok && ratchet.fail) {
package/package.json CHANGED
@@ -33,5 +33,5 @@
33
33
  "engines": {
34
34
  "node": ">=18"
35
35
  },
36
- "version": "1.14.0-rc.8"
36
+ "version": "1.14.0-rc.9"
37
37
  }
package/tools/colab CHANGED
@@ -87,6 +87,7 @@ const localAdopt = require('./lib/local-adopt'); // #393
87
87
  const ownerBranch = require('./lib/owner-branch'); // #394
88
88
  const humanDoor = require('./lib/ship-human-door'); // #525
89
89
  const instructionGate = require('./lib/instruction-gate'); // #588
90
+ const instructionFile = require('./lib/instruction-file'); // #602
90
91
  const {
91
92
  HOST, UserError, normIssueNum, issueTag, claimKey, today, nowISO, hoursSince, humanAge,
92
93
  parseArgs, table, shortRepo,
@@ -9315,6 +9316,13 @@ async function cmdAdopt(argv) {
9315
9316
  : `detected (the repo's default branch, ${nowDate})`;
9316
9317
  entries.push({ key: 'trunk', value: extra.trunk, comment: `# trunk: ${trunkNote}` });
9317
9318
  }
9319
+ // #602: on a fork, the instruction-file check cannot see the `upstream` remote in CI — so the
9320
+ // fork verdict above (adoptDetectFork, the one fork test) is recorded as the key CI reads.
9321
+ // Detected, never asked, like trunk and stack; never written over an existing declaration.
9322
+ if (extra.fork && !(instructionFile.INSTRUCTION_FILES_KEY in cfg)) {
9323
+ entries.push({ key: instructionFile.INSTRUCTION_FILES_KEY, value: 'upstream',
9324
+ comment: `# instruction-files: detected — a fork (${extra.fork.source === 'flag' ? '--fork' : `remote "${extra.fork.remote}"`}, ${nowDate}); CLAUDE.md/AGENTS.md are the upstream's, so the instruction-file check leaves them unjudged (CONVENTIONS.md §9, #602)` });
9325
+ }
9318
9326
  if (!('stack' in cfg)) {
9319
9327
  if (opts.stack !== undefined) {
9320
9328
  const stackNote = stackAnsweredInteractively
@@ -16087,6 +16095,10 @@ workflow \`.github/workflows/instruction-files.yml\`.
16087
16095
  --repo <path> repo to run in (default: cwd)
16088
16096
  --json { ok, error?, mode, base, fail, reason, files: [{ path, conforming, message }], changed }
16089
16097
 
16098
+ A fork whose CLAUDE.md/AGENTS.md belong to its upstream declares \`instruction-files: upstream\` in
16099
+ .github/project.yml (read on the judged side — HEAD, the index or the working tree): nothing is judged
16100
+ and the verdict is a pass (\`--json\`: \`exempt: "upstream"\`) — CONVENTIONS.md §9 "A fork of an upstream", #602.
16101
+
16090
16102
  Exit: 0 pass · 1 fail · 2 cannot judge (not a repo, base not fetched — never read as a pass).
16091
16103
  The fix for a failure is always the same: move the prose to AGENTS.md (handbook-sync's graft step
16092
16104
  does the move), keeping CLAUDE.md to \`@AGENTS.md\`, blank lines and tool blocks.
@@ -397,7 +397,7 @@ function remainingSteps(ctx = {}) {
397
397
  { n: 4, text: 'Optional: add the tier topic to the GitHub repo — `gh repo edit --add-topic tier-<b|c|a>`, step 4. Needs repo ADMIN (push access alone gets `HTTP 404 …/topics`); nothing in colab or the audit reads it, so skip it when you are not one (#522)' },
398
398
  );
399
399
  if (ctx.fork) {
400
- steps.push({ n: 5, text: `Fork of an upstream (${ctx.fork.source === 'flag' ? '--fork' : `remote "${ctx.fork.remote}"`}): do NOT make CLAUDE.md the thin shell — append templates/repo-CLAUDE-block.md at the END of the upstream's CLAUDE.md (create it only if upstream has none), record that append as a fork patch, leave AGENTS.md and the upstream prose untouched; CONVENTIONS.md §9 "A fork of an upstream", step 5` });
400
+ steps.push({ n: 5, text: `Fork of an upstream (${ctx.fork.source === 'flag' ? '--fork' : `remote "${ctx.fork.remote}"`}): do NOT make CLAUDE.md the thin shell — append templates/repo-CLAUDE-block.md at the END of the upstream's CLAUDE.md (create it only if upstream has none), record that append as a fork patch, leave AGENTS.md and the upstream prose untouched, and keep \`instruction-files: upstream\` in .github/project.yml (adopt writes it with the descriptor; add it by hand to one that predates #602) so the instruction-file check leaves the upstream's files unjudged; CONVENTIONS.md §9 "A fork of an upstream", step 5` });
401
401
  const agentFiles = ctx.upstreamAgentFiles || [];
402
402
  if (agentFiles.length) {
403
403
  steps.push({ n: 5, text: `Upstream ships its own agent workflow (${listShort(agentFiles)}): leave it in place, and say in the appended block that fork work runs code-start → code-wrap → code-ship, not that workflow — §9 "A fork of an upstream", step 5` });
@@ -328,6 +328,30 @@ function ratchetVerdict({ changed = [], head = [], base = null }) {
328
328
  return { fail: false, reason: null, bad };
329
329
  }
330
330
 
331
+ /**
332
+ * #602 — `instruction-files:` in .github/project.yml → `{ declared, exempt, valid, value, reason }`.
333
+ * `upstream` says this repo's CLAUDE.md/AGENTS.md belong to an upstream it tracks (a fork,
334
+ * CONVENTIONS.md §9 *A fork of an upstream*), so the shape is not judged here. Absent = judged.
335
+ * Any other value is invalid and read in the STRICTER direction — judged — while the audit fails
336
+ * the value. The committed record of `colab adopt`'s fork test, which reads a remote CI never has;
337
+ * never a second fork test.
338
+ */
339
+ const INSTRUCTION_FILES_KEY = 'instruction-files';
340
+ function parseInstructionFiles(doc) {
341
+ const has = !!doc && typeof doc === 'object' && Object.prototype.hasOwnProperty.call(doc, INSTRUCTION_FILES_KEY);
342
+ const v = has ? doc[INSTRUCTION_FILES_KEY] : null;
343
+ if (v === null || v === undefined) {
344
+ return { declared: false, exempt: false, valid: true, value: null, reason: 'instruction-files absent — every CLAUDE.md is judged (#588)' };
345
+ }
346
+ if (v === 'upstream') {
347
+ return { declared: true, exempt: true, valid: true, value: 'upstream', reason: 'instruction-files: upstream — CLAUDE.md/AGENTS.md are upstream-owned (a fork), so their shape is not judged here (CONVENTIONS.md §9, #602)' };
348
+ }
349
+ return {
350
+ declared: true, exempt: false, valid: false, value: v,
351
+ reason: `instruction-files is ${JSON.stringify(v)} — the only defined value is "upstream"; read as absent, so every CLAUDE.md is still judged (#602)`,
352
+ };
353
+ }
354
+
331
355
  module.exports = {
332
356
  stripCode,
333
357
  IMPORT_MAX_DEPTH,
@@ -349,4 +373,6 @@ module.exports = {
349
373
  judgeClaudeMd,
350
374
  RULE_FILE_RE,
351
375
  ratchetVerdict,
376
+ INSTRUCTION_FILES_KEY,
377
+ parseInstructionFiles,
352
378
  };
@@ -22,6 +22,7 @@ const fs = require('fs');
22
22
  const path = require('path');
23
23
  const { execFileSync } = require('child_process');
24
24
  const inst = require('./instruction-file.js');
25
+ const yaml = require('./yaml.js');
25
26
 
26
27
  const CLAUDE_RE = /(^|\/)CLAUDE\.md$/;
27
28
 
@@ -84,6 +85,26 @@ function judgeSide(cwd, side) {
84
85
  });
85
86
  }
86
87
 
88
+ /**
89
+ * #602 — the `instruction-files:` declaration on `side`, read from the SAME tree the CLAUDE.md
90
+ * files are judged on (head, index or working tree), never the merge base: a fork's adoption
91
+ * change adds the key, the CI caller and the appended Conventions block together, and the block
92
+ * touches CLAUDE.md — a base-side read would fail exactly the change that declares the exemption.
93
+ * An unreadable or unparseable descriptor reads as absent (judged — the stricter direction).
94
+ */
95
+ function declarationOn(cwd, side) {
96
+ const text = reader(cwd, side)('.github/project.yml');
97
+ if (text === null || text === undefined) return inst.parseInstructionFiles(null);
98
+ let doc = null;
99
+ try { doc = yaml.parse(text); } catch (_) { doc = null; }
100
+ return inst.parseInstructionFiles(doc);
101
+ }
102
+
103
+ /** The neutral verdict of a repo whose instruction files are upstream-owned. */
104
+ function exemptVerdict(mode, base, decl) {
105
+ return { ok: true, mode, base, exempt: decl.value, reason: null, fail: false, files: [], bad: [], changed: [] };
106
+ }
107
+
87
108
  /**
88
109
  * Run the gate. Options:
89
110
  * cwd repo (default process.cwd())
@@ -93,7 +114,10 @@ function judgeSide(cwd, side) {
93
114
  * With neither `staged` nor `base`, every CLAUDE.md at the head is judged with no ratchet:
94
115
  * any non-conforming file fails (`reason: 'strict'`).
95
116
  *
96
- * Returns `{ ok, error?, fail, reason, mode, base, files, bad, changed }`. `ok: false` means the
117
+ * A repo declaring `instruction-files: upstream` on the judged side (#602) is not judged: the
118
+ * verdict is `{ ok: true, exempt: 'upstream', fail: false, files: [] }`, whatever its CLAUDE.md says.
119
+ *
120
+ * Returns `{ ok, error?, exempt?, fail, reason, mode, base, files, bad, changed }`. `ok: false` means the
97
121
  * gate could not answer (not a repo, base unknown, merge base not reachable in a shallow clone)
98
122
  * — callers must refuse rather than read that as a pass.
99
123
  */
@@ -102,6 +126,8 @@ function gate({ cwd = process.cwd(), staged = false, base = null, head = null }
102
126
  const hasHead = git(cwd, ['rev-parse', '--verify', '-q', 'HEAD^{commit}']) !== null;
103
127
 
104
128
  if (staged) {
129
+ const decl = declarationOn(cwd, 'index');
130
+ if (decl.exempt) return exemptVerdict('staged', hasHead ? 'HEAD' : null, decl);
105
131
  const files = judgeSide(cwd, 'index');
106
132
  const changed = (git(cwd, ['diff', '--cached', '--name-only', '-z']) || '').split('\0').filter(Boolean);
107
133
  const baseFiles = hasHead ? judgeSide(cwd, { ref: 'HEAD' }) : [];
@@ -111,6 +137,8 @@ function gate({ cwd = process.cwd(), staged = false, base = null, head = null }
111
137
 
112
138
  const headSide = head === 'worktree' ? 'worktree' : { ref: head || 'HEAD' };
113
139
  if (headSide !== 'worktree' && !hasHead && !head) return { ok: false, error: 'HEAD has no commit yet' };
140
+ const decl = declarationOn(cwd, headSide);
141
+ if (decl.exempt) return exemptVerdict(base ? 'ratchet' : 'strict', null, decl);
114
142
  const files = judgeSide(cwd, headSide);
115
143
  if (files === null) return { ok: false, error: `cannot read ${head || 'HEAD'}` };
116
144
 
@@ -135,6 +163,7 @@ function gate({ cwd = process.cwd(), staged = false, base = null, head = null }
135
163
  /** One human line per verdict, naming the fix. */
136
164
  function describe(r) {
137
165
  if (!r.ok) return [`cannot judge: ${r.error}`];
166
+ if (r.exempt) return [`instruction files not judged: \`instruction-files: ${r.exempt}\` in .github/project.yml — CLAUDE.md/AGENTS.md are upstream-owned on this fork (CONVENTIONS.md §9 "A fork of an upstream", #602)`];
138
167
  if (!r.bad.length) return [`instruction files conform (${r.files.length} CLAUDE.md judged)`];
139
168
  const why = {
140
169
  touched: 'this change touches CLAUDE.md/AGENTS.md, so every CLAUDE.md must conform',
@@ -147,4 +176,4 @@ function describe(r) {
147
176
  return lines;
148
177
  }
149
178
 
150
- module.exports = { CLAUDE_RE, listClaude, reader, judgeSide, gate, describe };
179
+ module.exports = { CLAUDE_RE, listClaude, reader, judgeSide, declarationOn, gate, describe };