@sleepy_panda_srl/portulan 0.1.1 → 0.1.3
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/README.md +16 -19
- package/cli/README.md +155 -125
- package/cli/compile.mjs +797 -40
- package/cli/doctor.mjs +59 -2
- package/cli/drills.mjs +1541 -0
- package/cli/fuzz-shell.mjs +880 -0
- package/cli/gate.mjs +3 -2
- package/cli/goldens.mjs +469 -0
- package/cli/index.mjs +92 -42
- package/cli/init.mjs +4 -1
- package/cli/inside.mjs +38 -0
- package/cli/mutants.mjs +925 -0
- package/cli/pack-identity.mjs +9 -2
- package/cli/pack-version.mjs +7 -0
- package/cli/recipe-set.mjs +48 -1
- package/cli/release-eval.mjs +1068 -0
- package/cli/review-meter.mjs +741 -0
- package/cli/skill-goldens.mjs +590 -0
- package/cli/skills-set.mjs +166 -4
- package/cli/stop-gate.mjs +301 -28
- package/cli/telemetry.mjs +1047 -0
- package/cli/version-carriers.mjs +224 -0
- package/core/operating/memory.md +7 -8
- package/core/operating/verification.md +4 -12
- package/core/templates/gate-policy.md +27 -8
- package/evals/README.md +910 -0
- package/evals/releases/0.1.3.json +134 -0
- package/evals/releases/0.1.3.md +64 -0
- package/evals/releases/README.md +32 -0
- package/package.json +7 -2
- package/packs/README.md +11 -21
- package/packs/rituals/checkpoints/README.md +8 -1
- package/packs/rituals/checkpoints/pack.json +1 -1
- package/packs/rituals/checkpoints/skills/pre-commit/SKILL.md +32 -2
- package/packs/tools/README.md +1 -4
- package/spec/README.md +19 -22
- package/spec/migrations/README.md +2 -3
- package/spec/slots.md +30 -11
|
@@ -0,0 +1,224 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Portulan — every prose statement of the CURRENT version agrees with `package.json`.
|
|
3
|
+
//
|
|
4
|
+
// ## The defect this exists for
|
|
5
|
+
//
|
|
6
|
+
// `README.md` and `.portulan/products/portulan/product.md` both said the newest release entry was
|
|
7
|
+
// `0.2.0` while `package.json`, both plugin manifests and the registry said `0.1.0`. They were fixed
|
|
8
|
+
// together — and then, one release later, the SAME PAIR drifted again: `README.md` still read
|
|
9
|
+
// "Current release: `0.1.0`" inside the change that cut `0.1.1`. Twice, with the pairing already
|
|
10
|
+
// written down in `docs/plan.md` both times.
|
|
11
|
+
//
|
|
12
|
+
// **A sibling list in prose is not a rail.** This is the rail.
|
|
13
|
+
//
|
|
14
|
+
// It matters more than a tidy number because `README.md` is in `package.json`'s `files`, and npm
|
|
15
|
+
// FREEZES a README per published version: a wrong current-version sentence that reaches a publish
|
|
16
|
+
// cannot be corrected by any edit to `main`, only by cutting another release. That is exactly what
|
|
17
|
+
// `0.1.1` was for.
|
|
18
|
+
//
|
|
19
|
+
// ## Why the record layer is excluded, which is the whole design
|
|
20
|
+
//
|
|
21
|
+
// This repository writes about its own defects, so the retired sentences are QUOTED in the files that
|
|
22
|
+
// record fixing them: `CHANGELOG.md` carries *"The newest release entry is `0.2.0`"* inside the entry
|
|
23
|
+
// explaining that it was retired, and two handoffs plus `docs/plan.md` do the same. A matcher over
|
|
24
|
+
// everything reds on the repository's own account of the repair — the failure mode #286 measured,
|
|
25
|
+
// where both arms it proposed died on this repository's own review corpus.
|
|
26
|
+
//
|
|
27
|
+
// So the scan is scoped to LIVE prose and the record layer is excluded BY PATH. The exclusion is not
|
|
28
|
+
// a convenience: a dated record is supposed to preserve a sentence that is no longer true, and a rail
|
|
29
|
+
// that forbids that would forbid the record.
|
|
30
|
+
//
|
|
31
|
+
// ## What it cannot do, stated rather than discovered
|
|
32
|
+
//
|
|
33
|
+
// A current-version claim spelled a NEW way, in any file, is invisible to it. There is no way to tell
|
|
34
|
+
// "this prose asserts the current version" from "this prose mentions a version" without a matcher, and
|
|
35
|
+
// a matcher only knows the spellings it was given. The accepted practice for that residual is #286's,
|
|
36
|
+
// ruled by the maintainer: **a new spelling gets a pattern here and a fixture first.**
|
|
37
|
+
//
|
|
38
|
+
// The half that IS closed beyond drift: every file in MUST_CARRY has to produce at least one match, so
|
|
39
|
+
// deleting or rewording a known carrier reds instead of silently shrinking the rail's reach.
|
|
40
|
+
//
|
|
41
|
+
// Three further residuals, named because an unstated limit is the one a reader assumes away:
|
|
42
|
+
// · A live claim placed UNDER an excluded prefix is invisible. `.portulan/memory/` in particular
|
|
43
|
+
// holds doctrine-shaped notes rather than only dated records, so a current-version sentence
|
|
44
|
+
// written there would not be checked.
|
|
45
|
+
// · An UNTRACKED carrier is invisible: enumeration is `git ls-files`, deliberately, because a rail
|
|
46
|
+
// that reads the working tree grades files no commit will ever contain.
|
|
47
|
+
// · A NON-MARKDOWN carrier is invisible: the pathspec is `*.md`.
|
|
48
|
+
//
|
|
49
|
+
// Exit 0 green · 1 a finding · 2 could not run.
|
|
50
|
+
|
|
51
|
+
import { readFileSync, realpathSync } from "node:fs";
|
|
52
|
+
import { join } from "node:path";
|
|
53
|
+
import { pathToFileURL } from "node:url";
|
|
54
|
+
import { execFileSync } from "node:child_process";
|
|
55
|
+
|
|
56
|
+
/** Raised when a precondition fails. Always exit 2 — never a finding about the prose. */
|
|
57
|
+
export class CouldNotRun extends Error {}
|
|
58
|
+
|
|
59
|
+
// The spellings that assert a current version. Each must capture the version in group 1.
|
|
60
|
+
export const PATTERNS = [
|
|
61
|
+
{ id: "current-release", re: /\*\*Current release:\s*`([^`]+)`\*\*/g },
|
|
62
|
+
{ id: "newest-entry", re: /newest release entry is\s*`([^`]+)`/g },
|
|
63
|
+
{ id: "supported-current", re: /\|\s*`([^`]+)`\s*\|\s*Yes\s*—\s*the current release\s*\|/g },
|
|
64
|
+
];
|
|
65
|
+
|
|
66
|
+
// Files that MUST carry at least one claim. Losing one is a finding: it means a carrier was deleted
|
|
67
|
+
// or reworded, which is how this rail would otherwise quietly stop covering what it was built for.
|
|
68
|
+
export const MUST_CARRY = ["README.md", "SECURITY.md", ".portulan/products/portulan/product.md"];
|
|
69
|
+
|
|
70
|
+
// The record layer. These files preserve sentences that are no longer true, on purpose.
|
|
71
|
+
export const RECORD_PREFIXES = [
|
|
72
|
+
"CHANGELOG.md",
|
|
73
|
+
// **A release record is record-layer by nature**, and it was classified here deliberately rather
|
|
74
|
+
// than left to whether a pattern happens to match one. `evals/releases/<version>.md` is generated
|
|
75
|
+
// per release and preserves that release's conditions forever — so the moment `0.1.4` exists,
|
|
76
|
+
// `0.1.3`'s register is a document stating, correctly and permanently, facts about a version that
|
|
77
|
+
// is no longer current. That is precisely what this exclusion is for. Its own drift is held by the
|
|
78
|
+
// `release-eval` recipe, which byte-compares each register against the capture it was rendered
|
|
79
|
+
// from — so for `<version>.json` and `<version>.md` this moves coverage to the rail that can
|
|
80
|
+
// actually read them rather than removing it. **`evals/releases/README.md` is the exception and is
|
|
81
|
+
// named rather than glossed:** `release-eval` reads only the two version-keyed files, so that
|
|
82
|
+
// README now sits under an excluded prefix with nothing covering it. Harmless today — it states no
|
|
83
|
+
// current version — and it is exactly this module's own third named residual, a live claim under an
|
|
84
|
+
// excluded prefix, so it is recorded here instead of being discovered by the next reader.
|
|
85
|
+
"evals/releases/",
|
|
86
|
+
"docs/plan.md",
|
|
87
|
+
"docs/milestones/",
|
|
88
|
+
".portulan/handoffs/",
|
|
89
|
+
".portulan/proposals/",
|
|
90
|
+
".portulan/tasks/",
|
|
91
|
+
".portulan/memory/",
|
|
92
|
+
];
|
|
93
|
+
|
|
94
|
+
export const isRecord = (p) => RECORD_PREFIXES.some((r) => (r.endsWith("/") ? p.startsWith(r) : p === r));
|
|
95
|
+
|
|
96
|
+
/** Every tracked Markdown file that is not part of the record layer. Derived, never a written list. */
|
|
97
|
+
export function liveProseFiles(root) {
|
|
98
|
+
let out;
|
|
99
|
+
try {
|
|
100
|
+
out = execFileSync("git", ["-C", root, "ls-files", "-z", "--", "*.md"], { encoding: "utf8" });
|
|
101
|
+
} catch (e) {
|
|
102
|
+
throw new CouldNotRun(`could not enumerate tracked files: ${e.message}`);
|
|
103
|
+
}
|
|
104
|
+
const all = out.split("\0").filter(Boolean);
|
|
105
|
+
if (all.length === 0) throw new CouldNotRun("git listed no Markdown files — refusing to report green over an empty scan");
|
|
106
|
+
return all.filter((p) => !isRecord(p));
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
export function declaredVersion(root) {
|
|
110
|
+
let raw;
|
|
111
|
+
try {
|
|
112
|
+
// From the INDEX, like the prose it is compared against. Reading the version from the
|
|
113
|
+
// worktree while reading carriers from the index compares two different trees: a staged
|
|
114
|
+
// version bump with an unchanged worktree would grade staged prose against the OLD version,
|
|
115
|
+
// reporting drift that is not there — or, reversed, greening drift that is. Half a fix is
|
|
116
|
+
// how this rail's own index change first shipped.
|
|
117
|
+
raw = execFileSync("git", ["-C", root, "show", ":package.json"], { encoding: "utf8" });
|
|
118
|
+
} catch (e) {
|
|
119
|
+
throw new CouldNotRun(`could not read package.json from the index: ${e.message}`);
|
|
120
|
+
}
|
|
121
|
+
let v;
|
|
122
|
+
try {
|
|
123
|
+
v = JSON.parse(raw).version;
|
|
124
|
+
} catch (e) {
|
|
125
|
+
throw new CouldNotRun(`package.json is not valid JSON: ${e.message}`);
|
|
126
|
+
}
|
|
127
|
+
if (typeof v !== "string" || !v.trim()) throw new CouldNotRun("package.json declares no version string");
|
|
128
|
+
return v;
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/** Every current-version claim in one file's text, with the line it sits on. */
|
|
132
|
+
export function claimsIn(text) {
|
|
133
|
+
const found = [];
|
|
134
|
+
for (const { id, re } of PATTERNS) {
|
|
135
|
+
// A fresh RegExp per call: a `g` regex carries lastIndex, and a shared one skips matches.
|
|
136
|
+
const rx = new RegExp(re.source, re.flags);
|
|
137
|
+
let m;
|
|
138
|
+
while ((m = rx.exec(text)) !== null) {
|
|
139
|
+
found.push({ pattern: id, version: m[1], line: text.slice(0, m.index).split("\n").length });
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
return found;
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
export function inspect(root) {
|
|
146
|
+
const version = declaredVersion(root);
|
|
147
|
+
const files = liveProseFiles(root);
|
|
148
|
+
const findings = [];
|
|
149
|
+
const carried = new Set();
|
|
150
|
+
let claimCount = 0;
|
|
151
|
+
|
|
152
|
+
for (const rel of files) {
|
|
153
|
+
let text;
|
|
154
|
+
try {
|
|
155
|
+
// The INDEX, not the working tree — `pack-identity` reads the same way and for the same
|
|
156
|
+
// reason. Enumerating from the index and then reading the worktree lets a staged drift
|
|
157
|
+
// with a reverted worktree copy report green while the commit ships the drift.
|
|
158
|
+
text = execFileSync("git", ["-C", root, "show", `:${rel}`], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
|
|
159
|
+
} catch (e) {
|
|
160
|
+
// NOT `continue`. `git ls-files` just named this path, so failing to read its blob means
|
|
161
|
+
// the rail could not examine live prose it is responsible for — and skipping it would
|
|
162
|
+
// report GREEN over a file never looked at. That is this session's defect class exactly,
|
|
163
|
+
// and it was sitting inside the rail built against it. Could-not-run, never a green.
|
|
164
|
+
throw new CouldNotRun(`could not read ${rel} from the index: ${e.message}`);
|
|
165
|
+
}
|
|
166
|
+
for (const c of claimsIn(text)) {
|
|
167
|
+
claimCount++;
|
|
168
|
+
carried.add(rel);
|
|
169
|
+
if (c.version !== version)
|
|
170
|
+
findings.push(`${rel}:${c.line} states the current version as \`${c.version}\`, but package.json declares \`${version}\` (${c.pattern})`);
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
for (const rel of MUST_CARRY) {
|
|
175
|
+
if (!carried.has(rel))
|
|
176
|
+
findings.push(`${rel} carries no current-version claim this rail recognises — it was deleted or reworded, and the rail's reach shrank silently. Add a pattern in cli/version-carriers.mjs with a fixture, or restore the sentence.`);
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
return { version, filesScanned: files.length, claimCount, findings };
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
export function main(argv, stdout = process.stdout, stderr = process.stderr) {
|
|
183
|
+
const root = argv[0] ?? ".";
|
|
184
|
+
let r;
|
|
185
|
+
try {
|
|
186
|
+
r = inspect(root);
|
|
187
|
+
} catch (e) {
|
|
188
|
+
if (e instanceof CouldNotRun) {
|
|
189
|
+
stderr.write(`version-carriers: could not run — ${e.message}\n`);
|
|
190
|
+
return 2;
|
|
191
|
+
}
|
|
192
|
+
stderr.write(`version-carriers: could not run — unexpected failure: ${e.message}\n`);
|
|
193
|
+
return 2;
|
|
194
|
+
}
|
|
195
|
+
if (r.findings.length) {
|
|
196
|
+
for (const f of r.findings) stderr.write(`version-carriers: ${f}\n`);
|
|
197
|
+
return 1;
|
|
198
|
+
}
|
|
199
|
+
stdout.write(`ok version-carriers — ${r.claimCount} current-version claim(s) across ${r.filesScanned} live prose file(s) all read \`${r.version}\`\n`);
|
|
200
|
+
return 0;
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
// The entry guard, in the ONE form `cli/rule-carriers.mjs` designates after this repository got it
|
|
204
|
+
// wrong twice. `file://${argv[1]}` is NOT that form: `import.meta.url` percent-encodes, this working
|
|
205
|
+
// copy lives under a path with spaces, and the comparison failed — so the tool exited 0 having run
|
|
206
|
+
// nothing. **A green that is the tool never starting**, shipped inside the rail built against exactly
|
|
207
|
+
// that. The realpath fallback covers the symlink case an npm `bin` produces, in a `try` because a
|
|
208
|
+
// missing path must answer no rather than throw.
|
|
209
|
+
function isMain() {
|
|
210
|
+
const invoked = process.argv[1];
|
|
211
|
+
if (!invoked) return false;
|
|
212
|
+
if (import.meta.url === pathToFileURL(invoked).href) return true;
|
|
213
|
+
try {
|
|
214
|
+
return import.meta.url === pathToFileURL(realpathSync(invoked)).href;
|
|
215
|
+
} catch {
|
|
216
|
+
return false;
|
|
217
|
+
}
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
// `process.exitCode` rather than `process.exit`, which `cli/control-chars.mjs:540` settled for this
|
|
221
|
+
// repository: exiting outright can truncate a pipe that has not drained. It matters more here than
|
|
222
|
+
// stylistically — a truncated `ok` line IS exit 0 with no output, which is the precise shape of the
|
|
223
|
+
// false green this file's entry guard was fixed for. The same defect, one door along.
|
|
224
|
+
if (isMain()) process.exitCode = main(process.argv.slice(2));
|
package/core/operating/memory.md
CHANGED
|
@@ -125,14 +125,13 @@ memory and an implementer's memory answer different questions; merging them spen
|
|
|
125
125
|
on the other's concerns. _(Provenance: Letta; see `../personas/`.)_
|
|
126
126
|
|
|
127
127
|
**The first instance is declared at milestone 6 and validated at milestone 7**, and it takes two rows
|
|
128
|
-
because the scoping has two halves. **
|
|
128
|
+
because the scoping has two halves. **The declaring half:** the resolving pack's persona declares its
|
|
129
129
|
memory scope, and the resolution demonstration shows that scope landing in the **adopting workspace's
|
|
130
130
|
own layer** — declared by the pack, owned and populated only by the adopter, empty until earned. The
|
|
131
|
-
deliverable there is the scoping *demonstrated*, never a populated store. **
|
|
132
|
-
|
|
133
|
-
of those parts, so it is where a declaration stops being prose a checker can read but not honour.
|
|
131
|
+
deliverable there is the scoping *demonstrated*, never a populated store. **The validating half:** `doctor` checks a persona against its five-part contract, and the memory
|
|
132
|
+
scope is one of those parts — where a declaration stops being prose a checker can read but not honour.
|
|
134
133
|
|
|
135
|
-
**The declaration exists
|
|
134
|
+
**The declaration exists**, and what it is *not* is the load-bearing half.
|
|
136
135
|
The `rituals/checkpoints` pack's supervisor persona declares its scope; a composed workspace lands one
|
|
137
136
|
directory per declared scope in its own layer, generated into an index that is byte-compared, and the
|
|
138
137
|
location is **empty**. Nothing reads it, nothing recalls from it, nothing consolidates it, and no budget
|
|
@@ -142,9 +141,9 @@ condition 4 exists to catch. This is the **doctrine's** carrier of that limit; t
|
|
|
142
141
|
for the slot and the generated index prints it on its own face, deliberately, because a limit stated only
|
|
143
142
|
where a reader already knows to look is stated at the narrowest carrier.
|
|
144
143
|
|
|
145
|
-
**Settled by the maintainer
|
|
146
|
-
|
|
147
|
-
|
|
144
|
+
**Settled by the maintainer** — verbatim, *"row 6 declares, row 7 validates"* — after the same question
|
|
145
|
+
was put to him twice and answered two different ways. The record of both, and of the third option that
|
|
146
|
+
reconciles them, is
|
|
148
147
|
[#98](https://github.com/sleepy-panda-srl/portulan/issues/98) and
|
|
149
148
|
[`docs/milestones/m06.md`](../../docs/milestones/m06.md). Neither row needed a criterion edit to carry
|
|
150
149
|
this: both already demanded their half. Said plainly because the
|
|
@@ -44,23 +44,15 @@ is the machine check that fires when an agent tries to end a task: it runs the t
|
|
|
44
44
|
blocks "done" if the recipe is not green. The engine defines the contract — a task declares its verify
|
|
45
45
|
recipe; the gate runs it on Stop. The recipe resolves down the cascade — the **workspace** sets the
|
|
46
46
|
default, a **repo card** overrides it, a **task** may specialize — and the **compiler** wires the gate
|
|
47
|
-
to the host. _(The cascade is the contract; the runner
|
|
47
|
+
to the host. _(The cascade is the contract; the runner reads the **workspace
|
|
48
48
|
default only**. The repo-card and task steps are **not built, and no milestone owns them yet** — said in
|
|
49
49
|
that form deliberately, because it is the honest one and this file is where the rule lives. Named here
|
|
50
50
|
because a sentence describing resolution a runner does not perform is a capability claim, and this file
|
|
51
|
-
is the one that legislates against those.
|
|
52
|
-
|
|
53
|
-
"arrive with the CLI in milestone 7", which satisfied the rule in letter — it named a milestone — and
|
|
54
|
-
failed it in fact: the milestone named never took the obligation on, and no later one carries it either,
|
|
55
|
-
so the promise was carrier-less across the whole map. The two resolutions were to expand that row or to
|
|
56
|
-
re-point this sentence; the maintainer took the second, on
|
|
57
|
-
the ground that the runner shipped, at the time of that ruling, in no artifact an adopter received, so
|
|
58
|
-
building more of it bought an adopter nothing. _(It ships now — milestone 7 moved both runners into the
|
|
59
|
-
packaged CLI — which changes the premise and not the ruling: the two resolution steps are still unbuilt
|
|
60
|
-
and still unowned.)_ The precedent for the wording is `spec/pack.schema.json`'s `verify` note, which held
|
|
51
|
+
is the one that legislates against those. A promise naming a milestone that never took the obligation on is carrier-less, which is why this
|
|
52
|
+
sentence names no milestone at all rather than an unowned one. The precedent for the wording is `spec/pack.schema.json`'s `verify` note, which held
|
|
61
53
|
exactly this form until a ruling gave it an owner.)_
|
|
62
54
|
|
|
63
|
-
|
|
55
|
+
Two of the runner's properties are contract rather than detail. A recipe
|
|
64
56
|
that **could not run** blocks exactly as a red one does: "nothing looked" must never be read as "nothing
|
|
65
57
|
wrong". And the gate carries an **iteration cap** — a host's end-of-turn event is not the same event as
|
|
66
58
|
*the task is finished*, so a gate that blocked indefinitely would make a red working copy undriveable,
|
|
@@ -26,15 +26,15 @@
|
|
|
26
26
|
|
|
27
27
|
```json
|
|
28
28
|
{
|
|
29
|
-
"portulan": { "
|
|
29
|
+
"portulan": { "spec": "2.2" },
|
|
30
30
|
|
|
31
31
|
"why": "{Why this team gates what it gates — the sentence a new agent reads first. Name the blast radius you are protecting, not the tools you are restricting.}",
|
|
32
32
|
|
|
33
33
|
"floor": {
|
|
34
34
|
"branch": "{default branch}",
|
|
35
|
-
"
|
|
36
|
-
"
|
|
37
|
-
"
|
|
35
|
+
"checks": [],
|
|
36
|
+
"reviews": 0,
|
|
37
|
+
"resolve_conversations": true
|
|
38
38
|
},
|
|
39
39
|
|
|
40
40
|
"rules": [
|
|
@@ -45,11 +45,17 @@
|
|
|
45
45
|
"reason": "{Why, and what to do instead. Prohibited means no yes makes this acceptable — if a human could approve it, it is Gated, not Prohibited.}"
|
|
46
46
|
},
|
|
47
47
|
{
|
|
48
|
-
"id": "
|
|
48
|
+
"id": "force-push-without-a-lease",
|
|
49
49
|
"tier": "gated",
|
|
50
|
-
"action": { "shell": "
|
|
50
|
+
"action": { "shell": "git push --force" },
|
|
51
51
|
"reason": "{Why a human must approve each time. Prefer the undoability test: what does it cost if this was wrong and nobody noticed for a week?}"
|
|
52
52
|
},
|
|
53
|
+
{
|
|
54
|
+
"id": "delete-a-ref",
|
|
55
|
+
"tier": "gated",
|
|
56
|
+
"action": { "shell": "git push --delete" },
|
|
57
|
+
"reason": "{Why a deletion waits for a person. These two ids and actions are filled in already — they are the two destructive ref spellings the floor backend can express, and a `floor` block with no rule reaching it refuses to compile.}"
|
|
58
|
+
},
|
|
53
59
|
{
|
|
54
60
|
"id": "{rule-id}",
|
|
55
61
|
"tier": "propose",
|
|
@@ -60,6 +66,16 @@
|
|
|
60
66
|
}
|
|
61
67
|
```
|
|
62
68
|
|
|
69
|
+
> **`floor` is exactly four keys, and they are the four `compile` reads** — `branch`, `checks`,
|
|
70
|
+
> `reviews`, `resolve_conversations`. It is not a free-form block: `reviews` is a non-negative integer
|
|
71
|
+
> and `resolve_conversations` a boolean, both required, because a floor that omitted them would export
|
|
72
|
+
> one weaker than the one already in force. _(Until 2026-08-22 this skeleton emitted
|
|
73
|
+
> `require_pull_request` and `block_force_push` instead — two keys no version of the compiler has ever
|
|
74
|
+
> read — beside a `portulan.gates` version key it does not read either. A scaffold the next documented
|
|
75
|
+
> step refuses is the defect this template's own closing paragraph warns about, one layer up;
|
|
76
|
+
> [#329](https://github.com/sleepy-panda-srl/portulan/issues/329) reported it, and `new`'s test now
|
|
77
|
+
> scaffolds this file and compiles it rather than only checking that it was written.)_
|
|
78
|
+
>
|
|
63
79
|
> **`checks: []` is deliberate and you should probably leave it that way at first.** A floor requiring a
|
|
64
80
|
> status check that no workflow job reports is a red nobody caused — a fresh repository reports no checks,
|
|
65
81
|
> and a real one reports something else, so any name guessed here fails on the first run. Add the check
|
|
@@ -72,5 +88,8 @@
|
|
|
72
88
|
> print every rule against both rather than reasoning about it — the refusals are printed, never silent.
|
|
73
89
|
>
|
|
74
90
|
> **Start with the rules that destroy rather than create.** A ref deletion and a force-push are the two
|
|
75
|
-
> the floor backend can express
|
|
76
|
-
>
|
|
91
|
+
> **destructive ref spellings** the floor backend can express — it also emits `pull_request` and
|
|
92
|
+
> `required_status_checks` for a `propose` rule once `floor.checks` is non-empty, which is the paragraph
|
|
93
|
+
> above — and they are the two whose damage is hardest to undo, so they are a policy's
|
|
94
|
+
> honest first pair — so the skeleton above ships them filled in rather than as placeholders, which is
|
|
95
|
+
> also what keeps the `floor` block reachable. Their `reason` is still yours to write.
|