@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.
@@ -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));
@@ -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. **Milestone 6 declares:** the resolving pack's persona declares its
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. **Milestone 7 validates:** that
132
- row already has `doctor` checking a persona against its five-part contract, and the memory scope is one
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 as of milestone 6, session 1**, and what it is *not* is the load-bearing half.
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 on 2026-07-29** — verbatim, *"row 6 declares, row 7 validates"* — after two
146
- sessions put the same question to him within the hour without knowing of each other and were given
147
- different answers. The record of both, and of the third option that reconciles them, is
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 shipped in milestone 4 reads the **workspace
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. Found at the milestone-4 close.
52
- **Re-pointed 2026-08-03, on the maintainer's ruling.** This sentence previously said the two steps
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
- The runner arrived in milestone 4, and two of its properties are contract rather than detail. A recipe
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": { "gates": "1.0" },
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
- "require_pull_request": true,
36
- "block_force_push": true,
37
- "checks": []
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": "{rule-id}",
48
+ "id": "force-push-without-a-lease",
49
49
  "tier": "gated",
50
- "action": { "shell": "{command prefix}" },
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, they are the two whose damage is hardest to undo, and they are a policy's
76
- > honest first pair.
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.