@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 +18 -1
- package/package.json +1 -1
- package/tools/colab +12 -0
- package/tools/lib/adopt.js +1 -1
- package/tools/lib/instruction-file.js +26 -0
- package/tools/lib/instruction-gate.js +31 -2
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
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.
|
package/tools/lib/adopt.js
CHANGED
|
@@ -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
|
-
*
|
|
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 };
|