@sleepy_panda_srl/portulan 0.1.1 → 0.1.2
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 +15 -18
- package/cli/README.md +88 -125
- package/cli/compile.mjs +242 -3
- package/cli/doctor.mjs +54 -1
- package/cli/index.mjs +92 -42
- package/cli/inside.mjs +38 -0
- package/cli/recipe-set.mjs +42 -1
- package/cli/skills-set.mjs +166 -4
- package/cli/stop-gate.mjs +194 -24
- package/cli/version-carriers.mjs +211 -0
- package/core/operating/memory.md +7 -8
- package/core/operating/verification.md +4 -12
- package/package.json +1 -1
- package/packs/README.md +11 -21
- package/packs/tools/README.md +1 -4
- package/spec/README.md +19 -22
- package/spec/migrations/README.md +2 -3
- package/spec/slots.md +4 -9
package/README.md
CHANGED
|
@@ -20,13 +20,13 @@ workspaces and premium packs delivered as private-marketplace plugins.
|
|
|
20
20
|
|
|
21
21
|
## Status
|
|
22
22
|
|
|
23
|
-
**Current release: `0.1.
|
|
23
|
+
**Current release: `0.1.2`** — recorded in [`CHANGELOG.md`](CHANGELOG.md), which is also the honest
|
|
24
24
|
account of what the release does *not* contain.
|
|
25
25
|
|
|
26
26
|
This is pre-release software. The leading `0.` is meant literally: nothing here is stable yet, and
|
|
27
27
|
the surface may change between minor versions. What is authored today is the engine in [`core/`](core/),
|
|
28
|
-
the Workspace Definition in [`spec/`](spec/), two complete workspaces, the
|
|
29
|
-
the enforcement compiler, the memory lifecycle and the plugin packaging. The remaining directories
|
|
28
|
+
the Workspace Definition in [`spec/`](spec/), two complete workspaces, the CLI in [`cli/`](cli/) with
|
|
29
|
+
all eight subcommands, the enforcement compiler, the memory lifecycle and the plugin packaging. The remaining directories
|
|
30
30
|
fill in milestone by milestone; [`docs/plan.md`](docs/plan.md) is the living map of that work.
|
|
31
31
|
|
|
32
32
|
The repository is **public** — reading, cloning, forking and installing the plugin need no account of
|
|
@@ -86,7 +86,8 @@ the file.
|
|
|
86
86
|
The npmjs path above needs no account of ours and remains the documented one; this is an additional
|
|
87
87
|
route for people already inside GitHub's authentication. The two registries serve the same tree under
|
|
88
88
|
two names, so the tarballs are *not* byte-identical: packed both ways they differ in exactly one line
|
|
89
|
-
of one file — `package.json`'s `name
|
|
89
|
+
of one file — `package.json`'s `name`. The roster is the same on both sides; `npm pack --dry-run`
|
|
90
|
+
derives it, which is why no count is written here.
|
|
90
91
|
|
|
91
92
|
## Quick start
|
|
92
93
|
|
|
@@ -103,20 +104,16 @@ host enforcement.
|
|
|
103
104
|
|
|
104
105
|
## Command-line interface
|
|
105
106
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
The [`portulan`](cli/portulan.mjs) entry point arrived at milestone 7 and has dispatched every name
|
|
117
|
-
[`docs/vision.md`](docs/vision.md) gives it since session 9. The table below is the enumeration, and
|
|
118
|
-
`portulan --help` is the tree's own answer — a count written here in words would be one more
|
|
119
|
-
hand-maintained figure, which is the defect this cell has already shipped twice:
|
|
107
|
+
Two invocations, and they run the same code. `npx @sleepy_panda_srl/portulan <command>` needs no
|
|
108
|
+
checkout; `node cli/<tool>.mjs` runs from a clone, and is how this repository measures itself.
|
|
109
|
+
|
|
110
|
+
**There is no build step, so the package is not a compiled artifact.** Every file the npmjs package
|
|
111
|
+
ships is byte-identical to its tracked source at the commit it was cut from — a property you can check
|
|
112
|
+
rather than take on trust, and one a compiled artifact could not offer. The GitHub Packages copy is
|
|
113
|
+
the one documented exception, and differs in exactly the one line named above. A verify recipe holds it on every
|
|
114
|
+
commit, refusing any packed file that differs from its source.
|
|
115
|
+
|
|
116
|
+
`portulan --help` is the tree's own answer, and the table below is the enumeration:
|
|
120
117
|
|
|
121
118
|
| Command | What it does |
|
|
122
119
|
|---|---|
|
package/cli/README.md
CHANGED
|
@@ -3,91 +3,73 @@
|
|
|
3
3
|
The `npx` CLI that wraps the file-based mechanics for hosts beyond Claude Code:
|
|
4
4
|
`init` (interview + codebase scan → drafted workspace) · `doctor` · `compile` (gates/verify → host
|
|
5
5
|
enforcement) · `vendor` (materialise a workspace where it is needed — into a host, and the reverse) ·
|
|
6
|
-
`index` · `upgrade` · `new` · `feedback`.
|
|
7
|
-
entry point exists:
|
|
6
|
+
`index` · `upgrade` · `new` · `feedback`. The entry point is
|
|
8
7
|
[`portulan.mjs`](portulan.mjs), reached as `portulan <subcommand>` through the `bin` in the
|
|
9
8
|
repository's `package.json`.
|
|
10
9
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
`
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
_(Two counts moved at milestone 7 session 8 and both were wrong before it. The runnable tools read
|
|
60
|
-
**four** while `rule-carriers` had been one since 2026-08-10 and appeared in this file **zero** times;
|
|
61
|
-
the line below it read **two** while naming four. Corrected in the change that added a sibling rather
|
|
62
|
-
than left to the next reader — the rule this repository applies to
|
|
63
|
-
[`../.portulan/identity.md`](../.portulan/identity.md)'s rosters, and the one a first draft of this very
|
|
64
|
-
parenthetical broke by invoking it while leaving `rule-carriers` uncounted. Found at the pre-commit
|
|
65
|
-
checkpoint. A count is a claim, which is [#187](https://github.com/sleepy-panda-srl/portulan/issues/187)'s
|
|
66
|
-
subject; the missing table rows are [#203](https://github.com/sleepy-panda-srl/portulan/issues/203)'s.
|
|
67
|
-
**And it happened again**: the sentence above read **five** while `pack-version` had been runnable since
|
|
68
|
-
2026-08-14 and appeared in it zero times — the session-open checkpoint for the change that added
|
|
69
|
-
`eval-bundle` found the arrear, and the count moved six-then-seven in that one change rather than
|
|
70
|
-
leaving the five for the next reader.)_
|
|
10
|
+
**Two invocations, one behaviour.** `npx @sleepy_panda_srl/portulan <subcommand>` needs no checkout;
|
|
11
|
+
`node cli/<tool>.mjs` runs from a clone, and is the invocation this repository measures itself
|
|
12
|
+
through. [`../.portulan/identity.md`](../.portulan/identity.md) carries what the `npx` path buys —
|
|
13
|
+
**the same bytes**. There is no build step, so every file the package ships is byte-identical to its
|
|
14
|
+
tracked source — held on every commit by the `pack-identity` recipe, which refuses any packed file
|
|
15
|
+
that differs from its staged blob. _(The roster the package
|
|
16
|
+
ships is narrower than the tree and is not restated here as a number — `npm pack --dry-run` derives
|
|
17
|
+
it, and a hand-copied count is the thing that keeps going wrong in this file.)_
|
|
18
|
+
|
|
19
|
+
**All eight dispatch.** The entry point calls each one's exported `run` and returns the code
|
|
20
|
+
unchanged.
|
|
21
|
+
|
|
22
|
+
_A subcommand may be named by `docs/vision.md` before the tree carries it, and while that holds the
|
|
23
|
+
honest answer is to **list it and refuse** — exit 2, naming where it arrives. A stub exiting 0 would be
|
|
24
|
+
a fail-open where a user is most likely to trust silence. `portulan.mjs` carries that machinery
|
|
25
|
+
(`module: null` plus `arrives`) and its suite exercises the refusal on a synthetic entry, nothing
|
|
26
|
+
real being unbuilt today._
|
|
27
|
+
|
|
28
|
+
**Why eight.** `docs/vision.md` names all eight and is human-owned, so the roster of subcommands is
|
|
29
|
+
the constitution's to set and not an implementer's. A subcommand can be licensed by a milestone row
|
|
30
|
+
before the constitution catches up; while that holds, the tool says which document names it.
|
|
31
|
+
|
|
32
|
+
<!-- roster:begin -->
|
|
33
|
+
<!-- THE PARTITION BELOW IS RAILED. `cli-roster.live.test.mjs` reads the bare backticked names
|
|
34
|
+
between these two markers and holds them against the tracked NON-TEST `cli/*.mjs` modules, in
|
|
35
|
+
both directions — a test file belongs in the table below, never in this block: a
|
|
36
|
+
file classified by none of the three — this prose, `portulan.mjs`'s `SUBCOMMANDS`, or
|
|
37
|
+
`portulan.mjs` itself as the entry point — fails, and a name here matching no file fails.
|
|
38
|
+
Rewrite the prose freely — the markers are the anchor, not the sentences. A name may leave
|
|
39
|
+
only when the file does. **No count is written here**, for the reason this file gives about
|
|
40
|
+
every other hand-maintained figure. -->
|
|
41
|
+
Beside those eight sit the runnable tools that are on none of the lists — `plugin-lint`,
|
|
42
|
+
`librarian`, `control-chars`, `discover`, `rule-carriers`, `pack-version`, `eval-bundle`,
|
|
43
|
+
`pack-identity` and `version-carriers`. Each exists because a verify recipe or a packaging check
|
|
44
|
+
needed it; none is reachable as `portulan <subcommand>`.
|
|
45
|
+
The remaining files in this directory are neither subcommands nor tools: `gate` and `stop-gate` are
|
|
46
|
+
the **compiled-hook runners**, invoked by generated host configuration rather than by a person, and
|
|
47
|
+
`recipe-set`, `skills-set`, `manifest` and `inside` are modules other tools import — the first two
|
|
48
|
+
runnable in their own right, each printing the set it carries, and `inside` a single predicate that
|
|
49
|
+
lives alone so two large modules can both use it without importing each other.
|
|
50
|
+
<!-- roster:end -->
|
|
51
|
+
|
|
52
|
+
_(Those sentences carried hand-maintained counts, and the counts went wrong five times before
|
|
53
|
+
[#204](https://github.com/sleepy-panda-srl/portulan/issues/204) retired them — each correction right
|
|
54
|
+
on the day it landed, each stale within weeks. That is the argument for deriving the membership
|
|
55
|
+
rather than correcting it once more, which is
|
|
56
|
+
[#187](https://github.com/sleepy-panda-srl/portulan/issues/187)'s subject.)_
|
|
71
57
|
|
|
72
58
|
Being off the list is a fact about `docs/vision.md`, which names these eight subcommands and is
|
|
73
|
-
human-owned: whether any of the
|
|
59
|
+
human-owned: whether any of the others ever joins them is the maintainer's call and not an implementer's,
|
|
74
60
|
so none is described here as *coming to the CLI* — and none is wired behind the entry point, which is
|
|
75
61
|
the same rule expressed in code rather than in a sentence.
|
|
76
62
|
|
|
77
|
-
**This paragraph is the one carrier of that roster
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
a row, and every row names a file that exists — save two,
|
|
86
|
-
|
|
87
|
-
[#203](https://github.com/sleepy-panda-srl/portulan/issues/203) is closed — and the figure is not
|
|
88
|
-
stated here any more, because a number maintained by hand is the thing that kept going wrong. It is
|
|
89
|
-
checked by [`../.portulan/verify/docs.sh`](../.portulan/verify/docs.sh), in **both directions**, on
|
|
90
|
-
every run.
|
|
63
|
+
**This paragraph is the one carrier of that roster**, and `portulan.mjs` and the root
|
|
64
|
+
[`../README.md`](../README.md) both cite it rather than repeating it. One rule with three carriers is
|
|
65
|
+
obeyed at the narrowest — the repair
|
|
66
|
+
[`0020`](../.portulan/proposals/0020-a-fix-is-not-done-at-the-site-it-was-found.md) prescribes where
|
|
67
|
+
a rule cannot be a function: state it once, and let the others cite.
|
|
68
|
+
|
|
69
|
+
The table below is checked against this directory by
|
|
70
|
+
[`../.portulan/verify/docs.sh`](../.portulan/verify/docs.sh) in **both directions**, on every run:
|
|
71
|
+
every file here has a row, and every row names a file that exists — save two, declared to the rail
|
|
72
|
+
rather than left as quiet exceptions.
|
|
91
73
|
|
|
92
74
|
**Two exceptions are deliberate and are declared to the rail rather than worked around it.** This
|
|
93
75
|
`README.md` has no row, because a file does not list itself; `fixtures/` has a row and is a directory
|
|
@@ -95,59 +77,43 @@ rather than a file, because what the table owes a reader there is one sentence a
|
|
|
95
77
|
directory. A rail with an undeclared exception teaches the next person to widen the pattern until it
|
|
96
78
|
stops complaining, so both are named in the recipe and either one disappearing is itself a failure.
|
|
97
79
|
|
|
98
|
-
_(What this replaced is worth keeping, because it is the argument for the rail. The count read
|
|
99
|
-
**eleven** at milestone 7 session 6, then **nine** for three sessions — each session adding rows for
|
|
100
|
-
what it introduced and leaving the rest, correctly, rather than growing an unscheduled sweep inside a
|
|
101
|
-
feature change. The number was also wrong twice in one session. It read **seven**, omitting
|
|
102
|
-
`rule-carriers` and its suite; a first correction said **eight** and claimed to have been "re-derived by
|
|
103
|
-
walking `cli/*.mjs` against the table" — but the walk matched the filename **anywhere in the table**, so
|
|
104
|
-
`stop-gate.mjs` counted as having a row on the strength of a link inside `stop-gate.test.mjs`'s
|
|
105
|
-
description. **A row is an anchor at the start of a line**, which is why the rail's pattern is anchored
|
|
106
|
-
and why it extracts one subject per row rather than searching for names.
|
|
107
|
-
And by the time this change came to clear the arrears, the figure was wrong once more: the tree held
|
|
108
|
-
**ten** unrowed files against the nine this paragraph named and listed. The tenth was
|
|
109
|
-
`pinned-roots.live.test.mjs`, which landed at session 12 and reached neither the table nor the sentence
|
|
110
|
-
that counts the table's arrears — so the paragraph warning that a table falsified by its own directory
|
|
111
|
-
is a claim not worth making had become one. That is the whole case for a rail: the count and the table
|
|
112
|
-
drift by the same mechanism, so a hand-maintained figure about a hand-maintained table cannot be the
|
|
113
|
-
check on it.)_
|
|
114
|
-
|
|
115
80
|
## What is here today
|
|
116
81
|
|
|
117
82
|
| File | What it is |
|
|
118
83
|
|---|---|
|
|
119
|
-
| [`portulan.mjs`](portulan.mjs) | **The entry point** `package.json`'s `bin`
|
|
84
|
+
| [`portulan.mjs`](portulan.mjs) | **The entry point** `package.json`'s `bin` exposes as `portulan`, which is how `npx @sleepy_panda_srl/portulan <subcommand>` reaches these tools. It dispatches and adds nothing: each subcommand's module is imported **on demand** — so `portulan --help` does not pay for `doctor`, and a tool that fails to parse takes down only its own subcommand — and the tool's exit code is returned **unchanged**, because re-mapping it here would put a second opinion about a workspace between the tool and its user. Verified byte-identical to direct invocation, and exercised through the entry point as well as directly. |
|
|
120
85
|
| [`portulan.test.mjs`](portulan.test.mjs) | Its test suite, written first. **Dispatch only**: which module is reached, that arguments arrive unchanged, that exit codes come back unchanged, and that every refusal exits `2`. It injects the loader rather than shelling out, because re-asserting what `doctor` or `index` already prove would make this file a second carrier of it — with one deliberate exception, a case that imports the real modules to check they still export `run`, since that is the single assumption the entry point rests on. **Two cases spawn the real binary** — `init --help` and `feedback --help` — because injection can show that the dispatcher *would* reach a module and never that the module is reachable. The second of the two earned its place the hour it was written: it caught an import cycle that made `portulan feedback` exit 13 printing nothing, invisible to every injected case. |
|
|
121
86
|
| [`manifest.mjs`](manifest.mjs) | The two facts read out of `package.json` — the `version` it declares, which is what a publish would carry rather than anything a registry has seen, and the repository derived from `bugs.url` that `feedback` files into. It exists as its own file rather than living in the entry point because a subcommand importing the entry point back is a **cycle**, and that cycle hung the command line on an unsettled top-level await. It imports nothing of ours, which is the property that makes it safe for anything here to import. |
|
|
122
|
-
| [`init.mjs`](init.mjs) | **The onboarding subcommand
|
|
87
|
+
| [`init.mjs`](init.mjs) | **The onboarding subcommand**: it drafts a workspace for a repository that has none. It **asks** where that workspace resides — in the repository, or in a workspace that names it — and has **no default**, because a repository is governed by exactly one workspace and that answer is the one that cannot be guessed. It refuses ahead of the first byte written: never over an existing residence, and never a name, governor or pack id a validator would misread. What it emits is a **draft** — including a verify recipe that exits 2 until the adopting team declares what green means for them. |
|
|
123
88
|
| [`init.test.mjs`](init.test.mjs) | Its test suite, written first. Its last group is the one that matters: it runs the real `doctor` against real drafted directories, in both residences, because a workspace nothing validated is a workspace nobody can trust. That group is what caught a drafted gate policy that parsed cleanly and compiled to a floor no rule reached. |
|
|
124
|
-
| [`doctor.mjs`](doctor.mjs) | The Workspace Definition validator. Zero dependencies, no install step, run from the repository root. Two repeatable roots, one of which **is discovered unasked
|
|
89
|
+
| [`doctor.mjs`](doctor.mjs) | The Workspace Definition validator. Zero dependencies, no install step, run from the repository root. Two repeatable roots, one of which **is discovered unasked**: `--pack-root` is where declared packs are looked up, and `--repo-root` (2.7) is where the repositories a workspace's cards NAME are checked out, so the residence ruling's cross-repository refusal has somewhere to look. Without a `--repo-root` that check reports that it did not run rather than passing quietly. **One thing IS discovered — a pointer's `governed_by`**, through [`discover.mjs`](discover.mjs). It is **reported and never graded**, so no host's install state moves this tool's verdict *through that channel* — a scope this row used to be able to leave implicit, because the pack root was discovered only when asked and nothing else here read a host. A pack root also accepts `auto` — `--pack-root auto` reads that record too, and `./auto` still names a directory. **A pack root is discovered whether or not `auto` is passed**, because row 7 makes `--pack-root` *optional where discovery finds a root* and it was not: on the workspace `init` drafts by default plus one pack of the adopter's own, this tool exited **1** bare and **0** under `auto`. What `auto` still changes is the degrade — asked-and-could-not-look is exit 2, unasked keeps the derived root and reports the diagnostic. A **discovered** root cannot turn a **miss** into a FAIL, only into a resolution — though a discovered copy that resolves and is invalid does fail, with its origin named. So a bare run's verdict does move with the host, which is what a per-host capability report is for; what does not is a **required** check's, because those name their roots and a named root replaces every other source. `--repo-root` stays named-only: a repository checkout is not something a plugin record lists. |
|
|
125
90
|
| [`doctor.test.mjs`](doctor.test.mjs) | Its test suite, on node's own runner. Written before the validator. |
|
|
126
|
-
| [`discover.mjs`](discover.mjs) | **Host plugin-cache discovery
|
|
91
|
+
| [`discover.mjs`](discover.mjs) | **Host plugin-cache discovery**: it reads `<config>/plugins/installed_plugins.json` and dereferences a pointer's `governed_by` to the directory the governing workspace was installed to. Four verdicts — `resolved`, `not-installed`, `ambiguous` (two or more answering to one name: **refused and both named**, never ranked) and `could-not-look` — because a resolver with two answers spends *could not look* as *not installed*. It matches on the governing **manifest's** `name`, constrained by the pointer's `feed` where it declares one, and looks in a **named pair** of locations inside a payload rather than walking it. Nothing is fetched: the record is read from disk and no path here touches the network. Also runnable — `node cli/discover.mjs [--json] <workspace-dir>` — which is the seam [`../plugin/skills/portulan/SKILL.md`](../plugin/skills/portulan/SKILL.md) reads at the boot, and **deliberately not a ninth `portulan` subcommand**: `docs/vision.md` names eight and is human-owned, so this sits beside `plugin-lint` and `librarian` and joins that list only if the maintainer says so. |
|
|
127
92
|
| [`discover.test.mjs`](discover.test.mjs) | Its test suite. Every case builds a whole fake host in a temp directory and points `CLAUDE_CONFIG_DIR` at it, because a suite that consulted the real machine would be green on the author's laptop and meaningless anywhere else. |
|
|
128
|
-
| [`plugin-lint.mjs`](plugin-lint.mjs) | The packaging validator: the plugin and marketplace manifests, the skills they declare, and the agents at `./agents/` that nothing declares.
|
|
93
|
+
| [`plugin-lint.mjs`](plugin-lint.mjs) | The packaging validator: the plugin and marketplace manifests, the skills they declare, and the agents at `./agents/` that nothing declares. It also holds **`core/personas/` and `agents/` to each other** — both directions fail, because a persona this bundle ships and does not bind is doctrine the host never registers, and a binding whose persona is gone registers a role with no charter. It is the one location a host loads agents from, exported here as `AGENT_DIR` and imported by `doctor` rather than spelled twice. |
|
|
129
94
|
| [`plugin-lint.test.mjs`](plugin-lint.test.mjs) | Its test suite, likewise written first. |
|
|
130
|
-
| [`skills-set.mjs`](skills-set.mjs) | **The registrable set
|
|
95
|
+
| [`skills-set.mjs`](skills-set.mjs) | **The registrable set**: the one carrier of *what a plugin manifest must declare so a composed pack's skills register*. It reads each composed pack's `contributes.skills` and derives the paths, relativised to the plugin root — `--check` reports drift (1) and `--write` derives the key rather than leaving it hand-typed. Row 7 clause (b)'s adopter half, [#184](https://github.com/sleepy-panda-srl/portulan/issues/184): until it landed, registration was a property of `.claude-plugin/plugin.json` **alone**, so a composed pack's skill was invocable by coincidence of a path someone typed. It holds `HOST_SKILL_DEPTH` — the platform fact the derivation rests on, measured in `plugin-lint` and moved here when that file became a consumer. **Deliberately not a ninth `portulan` subcommand**, on `discover`'s precedent above. |
|
|
131
96
|
| [`skills-set.test.mjs`](skills-set.test.mjs) | Its test suite, written first. Every refusal has a sibling in `recipe-set.test.mjs`, because those were found by review rather than by design and a second carrier of the same shape should not have to rediscover them. |
|
|
132
97
|
| [`skills-set.live.test.mjs`](skills-set.live.test.mjs) | The same derivation against **this** repository rather than against fixtures — the guard for *a harness you write to check your own change inherits your change's blind spot*, which this project has now measured seven times, two of them in the session that added this file. Its load-bearing assertion is that the derived set equals what `.claude-plugin/plugin.json` already declares. |
|
|
133
|
-
| [`new.mjs`](new.mjs) | **The authoring subcommand
|
|
98
|
+
| [`new.mjs`](new.mjs) | **The authoring subcommand**: it scaffolds a skill · persona · pack · workspace · gate-policy · repo-card from a core template **into a layer you own, never into `core/`**. The refusal is resolution-based rather than pattern-based, because every interesting escape — `packs/../core`, a symlinked destination — parses fine and only fails once resolved. Two codes, `0` wrote and `2` could not run: it renders no verdict, so it has no red. |
|
|
134
99
|
| [`new.test.mjs`](new.test.mjs) | Its test suite, written first. It establishes *never into `core/`* against the filesystem rather than against an argument check, and runs the real `doctor` and `plugin-lint` over what was scaffolded — a scaffold nothing validates is one nobody can trust. |
|
|
135
|
-
| [`vendor.mjs`](vendor.mjs) | **Materialises a workspace where it is needed
|
|
100
|
+
| [`vendor.mjs`](vendor.mjs) | **Materialises a workspace where it is needed, in either direction** — the constitution's gloss covers both. `--host` writes a self-contained `AGENTS.md` — core's kernel inlined, the workspace's slots named, packs named-not-composed — beside a copied `.portulan/`, for a host that cannot install the plugin. `--switch` changes residence, feed-side ↔ in-repo, under proposal [`0017`](../.portulan/proposals/0017-one-repository-one-governing-workspace.md): materialise at the new residence, leave a pointer or nothing at the old, `doctor` green at **both** ends before the old one is retired. Every handled failure leaves exactly one governing workspace; the residence is **never inferred** from a path, which is `init`'s rule for `init`'s reason. |
|
|
136
101
|
| [`vendor.test.mjs`](vendor.test.mjs) | Its test suite, written first. The group that matters *forces* a failure after each named write step, because the property this tool exists to protect is what a failure partway leaves on disk — an ordering nothing can interrupt is an ordering nobody has checked. Every end state is graded by the real `doctor`, never by a second opinion about what valid means. |
|
|
137
102
|
| [`collisions.test.mjs`](collisions.test.mjs) | **The collision contract — one rule, three carriers, pinned together.** Three tools here write into a tree somebody else owns, and all three answer the same question first: *is something already at the path I am about to write?* [`init.mjs`](init.mjs), [`new.mjs`](new.mjs) and [`vendor.mjs`](vendor.mjs) each export a `collisions()` that answers it with a different signature, a different return shape and a different refusal vocabulary, because each was copied from the last and adapted. This suite pins the three to the one question rather than to one another's spellings. |
|
|
138
|
-
| [`upgrade.mjs`](upgrade.mjs) | **The migration runner**,
|
|
103
|
+
| [`upgrade.mjs`](upgrade.mjs) | **The migration runner**, the last of the eight to be built. It reads [`../spec/migrations/`](../spec/migrations/) — the chain lives in the **spec**, because a migration is part of the Workspace Definition rather than part of a tool — and applies what a workspace owes. **Two kinds of step**, on the maintainer's ruling of 2026-08-12: a `version` step migrates a MAJOR, and a `repair` fixes what a rewriter owes a workspace it touched. Owedness is derived from the workspace's **state**, never from a stamp, so every step is idempotent and an interrupted run is recovered by re-running. It refuses in **both** directions: a workspace ahead of this bundle is could-not-run (upgrade the CLI, not the workspace), and one behind by a MAJOR that no step reaches is could-not-run too — either would otherwise plan to nothing and exit 0. `--write` applies, then grades with the real `doctor` and **rolls back on a red**, reporting what it could not put back rather than claiming the tree is clean. |
|
|
139
104
|
| [`upgrade.test.mjs`](upgrade.test.mjs) | Its test suite, written first, against `ws` views built in memory — the honest way to force a step's own branches red. Every case in it was **forced red by mutating the code it guards** before being trusted; the pass that did so found a guard with no test at all, where the arithmetic was covered and the tool's response to it was not. |
|
|
140
105
|
| [`upgrade.live.test.mjs`](upgrade.live.test.mjs) | The other half, and the one that matters: workspaces the **real `init`** drafts, from a real second bundle that is then deleted, with the drafted rail **run** before and after — exit 2 with its bundle gone, a verdict once repaired. Behaviour, not a string comparison on a script. It also pins that `.portulan` and `examples/` owe nothing, so `examples/` staying four MINORs back at 2.4 cannot be quietly restamped. Written because running the step over `.portulan` found what no fixture could: a handoff that *documents* the marker was read as a malformed marked line. |
|
|
141
|
-
| [`feedback.mjs`](feedback.mjs) | **The inbound half
|
|
106
|
+
| [`feedback.mjs`](feedback.mjs) | **The inbound half**: it files an issue from a report the user previewed, seam-scanned before it leaves the machine, under the Gated tier. Three verbs — `draft` writes a report into the workspace's `feedback/` directory, `preview` prints the exact bytes, `send --approve` files them through the user's own `gh` login. The payload is assembled from a **closed list** rather than filtered, so nothing here reads a workspace name, a repo card, a gate map, memory, a remote or a path. It ships **no seam terms** — the list is the adopter's and is looked for at `--seam-terms`, `$PORTULAN_SEAM_TERMS`, then `<workspace>/seam-terms.txt`; a hit refuses the send with **1**, a named list that cannot be read refuses it with **2**, and no list at all is *stated in the sentence the user approves* rather than passed over. Approval is per send and is never inherited from a draft or a preview. |
|
|
142
107
|
| [`feedback.test.mjs`](feedback.test.mjs) | Its test suite, written first, against `.portulan/tasks/0012-a-feedback-pipe-points-out-of-the-seam.md`'s *Done when* list. Nothing here reaches the network: `gh` arrives injected. The one property injection cannot prove — that the approved bytes are the sent bytes — is not proven by comparison but held by construction, and the suite asserts the construction: the previewed body **is** `payload()`'s return value, not a second rendering that agrees with it today. |
|
|
143
108
|
| [`feedback.live.test.mjs`](feedback.live.test.mjs) | The rail on the pair that cannot be collapsed. `package.json`'s `files` does not ship `.github/ISSUE_TEMPLATE/`, so the sender must carry the forms' field ids, labels, required flags, dropdown options and acknowledgement texts — one fact, two carriers, and the repair is `0020`'s: one carrier plus a rail. This reads the real forms and fails when the two disagree. Its own instrument is guarded first: if the reader stops understanding a form and returns nothing, the test goes **red** rather than vacuously green. |
|
|
144
|
-
| [`compile.mjs`](compile.mjs) | The enforcement compiler: a workspace's gate policy becomes host enforcement. Two backends — Claude Code `permissions` + `hooks`, and a GitHub repository ruleset for the platform floor — and the vocabulary it reads stays the workspace's, so a third backend translates the same policy instead of forcing it to be rewritten. `--workspace` takes a repository root **or the workspace directory itself**, which is how a feed-side workspace is reachable at all: it keyed on `.portulan` until
|
|
109
|
+
| [`compile.mjs`](compile.mjs) | The enforcement compiler: a workspace's gate policy becomes host enforcement. Two backends — Claude Code `permissions` + `hooks`, and a GitHub repository ruleset for the platform floor — and the vocabulary it reads stays the workspace's, so a third backend translates the same policy instead of forcing it to be rewritten. `--workspace` takes a repository root **or the workspace directory itself**, which is how a feed-side workspace is reachable at all: it keyed on `.portulan` until the parity demonstration found it exiting 2 on the feed-side end of a switch. |
|
|
145
110
|
| [`compile.test.mjs`](compile.test.mjs) | Its test suite, likewise written first. Emission fidelity only — nothing in here can establish that a host *honours* what the compiler emits, which is a fact about a running host. |
|
|
111
|
+
| [`inside.mjs`](inside.mjs) | **Is one path inside another** — one predicate, one file, no imports. It began in [`index.mjs`](index.mjs) and moved here when [`compile.mjs`](compile.mjs) needed it too: taking it from there would have closed an import cycle, and this repository has already had one exit **13** in silence. Copying it instead is what its own docblock forbids — two copies of this rule drifted into the identical defect before either shipped. `index.mjs` re-exports it, so every existing importer is untouched. |
|
|
146
112
|
| [`index.mjs`](index.mjs) | The index generator, over **two** series since Workspace Definition 2.5: the memory store, which is size-budgeted so a breach is a red, and the handoff series, which is not — an append-only series has no consolidation to offer, so every remedy a budget could ask for is already barred. Every field on every line is derived from what it points at, so neither file has a hand-maintained half; the *carriers* differ per series and on evidence, a record's title being its filename and a handoff's its H1. It writes an over-budget index rather than refusing to — the remedy is consolidation, and consolidating needs the artifact to consolidate from. |
|
|
147
113
|
| [`index.test.mjs`](index.test.mjs) | Its test suite, written first. Derivation, drift and cost only — nothing in here can establish that the index is any good at *recall*, which is an eval question. |
|
|
148
|
-
| [`gate.mjs`](gate.mjs) | **The PreToolUse gate runner** — the *explanation* half of the enforcement compiler, wired by [`compile.mjs`](compile.mjs) into `.claude/settings.json`. It reads the host's hook payload on stdin, finds which rule of the policy the workspace **yields** the attempted action matches, and returns that rule's own sentence as the decision reason. *Yields*, not *declares*: [`../.portulan/gates.json`](../.portulan/gates.json) **plus the fragments its packs contribute**, composed through `compile`'s own `packContributions`/`composeFragments` so there is no second composer to drift
|
|
114
|
+
| [`gate.mjs`](gate.mjs) | **The PreToolUse gate runner** — the *explanation* half of the enforcement compiler, wired by [`compile.mjs`](compile.mjs) into `.claude/settings.json`. It reads the host's hook payload on stdin, finds which rule of the policy the workspace **yields** the attempted action matches, and returns that rule's own sentence as the decision reason. *Yields*, not *declares*: [`../.portulan/gates.json`](../.portulan/gates.json) **plus the fragments its packs contribute**, composed through `compile`'s own `packContributions`/`composeFragments` so there is no second composer to drift. Where two rules match one call it answers with the **strongest** tier, not the first listed — composition makes that systematic, since added rules are appended and so always lose a first-match tie, but a single-file policy listing the weaker rule first diverged too. Strengthen-only: `ask` may become `deny`, never the reverse. **This file is not the gate** — the host's own matcher is; this says *why*, so a refusal arrives as a reason rather than a wall. |
|
|
149
115
|
| [`gate.test.mjs`](gate.test.mjs) | Its test suite, and the exception to "written first" for the same reason [`stop-gate.test.mjs`](stop-gate.test.mjs) is: it arrived with [#269](https://github.com/sleepy-panda-srl/portulan/issues/269), on a runner nothing had tested directly. **Every case spawns the real binary** with a payload on stdin, because the defect it closes was never in `decide` — it was in which rules reached `decide`, and a unit test would have passed on every day the hook was blind. |
|
|
150
|
-
| [`stop-gate.mjs`](stop-gate.mjs) | **The Stop-gate runner** — *done* is not a thing an agent may simply declare. Wired by [`compile.mjs`](compile.mjs) into `.claude/settings.json` as a `Stop` hook: when an agent tries to end its turn, this runs the workspace's default verify recipe and blocks the ending if the recipe is not green. [`../core/operating/verification.md`](../core/operating/verification.md)
|
|
116
|
+
| [`stop-gate.mjs`](stop-gate.mjs) | **The Stop-gate runner** — *done* is not a thing an agent may simply declare. Wired by [`compile.mjs`](compile.mjs) into `.claude/settings.json` as a `Stop` hook: when an agent tries to end its turn, this runs the workspace's default verify recipe and blocks the ending if the recipe is not green. [`../core/operating/verification.md`](../core/operating/verification.md) specifies the contract; this is that runner. |
|
|
151
117
|
| [`stop-gate.test.mjs`](stop-gate.test.mjs) | The exception to "written first": it covers the Stop-gate runner ([`stop-gate.mjs`](stop-gate.mjs)), and it exists because a supervisor found a fail-open and a forever-block in a runner nothing tested at all. Its cap arithmetic and date handling, and — since [#220](https://github.com/sleepy-panda-srl/portulan/issues/220) — the **did-work signals**, which spawn the real binary against real git fixtures for the reason [`gate.test.mjs`](gate.test.mjs) gives: the defect was that real git in a rebase-merging repository behaves otherwise than the signal assumed, and a stubbed runner is a copy of that assumption. What still has no directed case: a recipe that reds or cannot run, driven through the spawned binary, and the handoff-listing edge shapes — both are exercised here only as preconditions of the cases above. |
|
|
152
118
|
| [`librarian.mjs`](librarian.mjs) | The scheduled librarian's pass: reindex over both series, record age from git, the sealed-stamp re-validation nag, proposal nagging, demotion drafts, **mining** — incidents nothing in the curated layer points back at, and paths pull-request reviewers keep leaving findings on — and **consolidation**, read as budget distance plus the records citing one incident. The one tool here that reads **history** — `doctor` reads the tree and says so — which is why it belongs to a scheduled job rather than to a verify recipe: a check that reads history is a false-red generator in a shallow checkout. It renders no verdict, so it has no exit 1, and it **writes nothing itself**: the command writes, and only after the pass's own handoff is on disk, because that handoff is a member of the series one of the indexes covers. |
|
|
153
119
|
| [`control-chars.mjs`](control-chars.mjs) | **The rail on bytes a reader cannot see**, added for [#68](https://github.com/sleepy-panda-srl/portulan/issues/68): no tracked file may carry a byte in the C0 range other than TAB and LF, nor DEL. It reads a `Buffer` and **never decodes**, because decoding invalid UTF-8 yields U+FFFD — which both hides bytes and invents a character that was not there. That rule holds end to end and cost three review rounds to make true: the file contents, the file list on stdin, and a symlink's target all arrive as bytes, and a path is kept only if it round-trips through UTF-8. A binary asset is exempt **by name**, never by a content test: every binary sniff in use is keyed on NUL, so a sniff would have skipped the one file this exists to catch. The declaration is audited three ways — stale, never-read, or dead — each exit `2`. |
|
|
@@ -155,6 +121,8 @@ check on it.)_
|
|
|
155
121
|
| [`pack-version.mjs`](pack-version.mjs) | **A change to a pack's `contributes` must move that pack's `portulan.version`** — the maintainer's ruling on [#265](https://github.com/sleepy-panda-srl/portulan/issues/265), arm 3, including that a **prose-only** edit to a fragment's `reason` counts. The **second** tool here that reads history rather than the tree, and the comparison is **three-dot** — the merge-base of the base ref and `HEAD` — so work that landed on the base is never attributed to this branch. Manifests are compared as **values**, so reindenting or reordering keys is correctly not a change. The bundle version in `packs/.claude-plugin/plugin.json` is out of scope by measurement: it is one field and the packs are many. |
|
|
156
122
|
| [`pack-identity.mjs`](pack-identity.mjs) | **Every file `npm pack` would emit is byte-identical to its staged blob (`git show :<path>`), and every one is tracked at all** — the rail [#149](https://github.com/sleepy-panda-srl/portulan/issues/149) asked for, built 2026-08-18 after the first publish measured the property by hand. It compares against the **tree**, not the registry: the registry form needs the network and a published version, so it cannot run before a first publish or offline, and a recipe that cannot run stops being run. This owns the half that can drift silently on any commit; the registry half stays a hand measurement recorded on #149 at each publish. `package.json` is compared like every other file rather than exempted, because the 2026-08-13 measurement asserted identity "`package.json` included, with no exemption" and an exemption here would quietly retire that claim. Could-not-run is **exit 2** — npm absent or unusable is not a finding about the bytes. |
|
|
157
123
|
| [`pack-identity.test.mjs`](pack-identity.test.mjs) | The rail's suite, added on a Copilot note that it had shipped without one while every comparable rail here has a suite. Exercises all four contracted states **positively** — green, a drifted byte, an untracked packed file, and could-not-run — because a failure path nobody has run is a failure path nobody has seen work. Two of its cases are the review's own findings turned into tests: a **staged** edit must compare clean, or the rail is red before every commit and contradicts [`../.portulan/dod.md`](../.portulan/dod.md); and a filename beginning with `-` must be compared rather than read as an option, which the `cat` shell-out this rail first shipped with would have done. |
|
|
124
|
+
| [`version-carriers.mjs`](version-carriers.mjs) | **Every prose statement of the CURRENT version equals `package.json`'s** — the rail for a defect this repository shipped **twice with the sibling pairing already written down**: `README.md` and `.portulan/products/portulan/product.md` said `0.2.0` while everything machine-read said `0.1.0`, and one release later `README.md` said `0.1.0` inside the change cutting `0.1.1`. It matters past tidiness because `README.md` is in `package.json`'s `files` and **npm freezes a README per version**, so a wrong sentence that reaches a publish needs another release to correct — which is what `0.1.1` was. The **record layer is excluded by path**, and that is the design: this repository quotes retired sentences in the files recording their repair, so a matcher over everything reds on the account of the fix. `MUST_CARRY` closes the other half — a carrier deleted or reworded is a finding, so the rail cannot shrink in silence. What it does **not** close is a claim spelled a new way, and the accepted practice for that is #286's ruling: new spelling ⇒ a pattern here and a fixture first. |
|
|
125
|
+
| [`version-carriers.test.mjs`](version-carriers.test.mjs) | The rail's suite. Some cases run the CLI as a **subprocess whose SCRIPT PATH contains a space** — the property the entry guard turns on, and not the same thing as a spaced working directory; the rest exercise the module in process. **No count is written here on purpose.** A hand-maintained figure beside a list that grows is the defect this whole rail exists for, and `node --test` derives it. Every contracted state is exercised **positively** — green, drift in each of the three carriers, a carrier reworded away, could-not-run in three causes, and the record layer ignored. Two cases exist only because this repository's own corpus refutes the naive design: **the record must be ignored**, since `CHANGELOG.md` and two handoffs quote that retired sentence while explaining that it was retired — **despelled here on purpose**: written out in the matched spelling, this very row is a live current-version claim and the rail reds on it, which is how it was found; and **a `g` regex must not carry `lastIndex` between files**, which would find the first claim and then resume past it, reporting a clean scan over a drifted file. |
|
|
158
126
|
| [`pack-version.test.mjs`](pack-version.test.mjs) | Its test suite, written first, on **real `git init` repositories** rather than a stubbed `execFileSync` — the three-dot property cannot be observed at all without two branches and a merge-base. The shallow-clone refusal is asserted on **both** shapes a shallow clone takes, and is guarded by a full-depth clone of the same fixture reaching the red, so the `2` is the depth rather than the fixture. |
|
|
159
127
|
| [`eval-bundle.mjs`](eval-bundle.mjs) | **The evaluation-bundle cutter** — a named-recipient stamped copy of the shippable payload, cut from an explicitly named commit, ported into the tree on the maintainer's ruling of 2026-08-17. The payload partition and the machine-read license census are **pinned in both directions**, and **two different steps refuse two different things**, which is worth keeping straight because each sends an operator somewhere else: the **census** runs on the freshly materialised cut and refuses an Apache assertion in a file that is not rostered in `APACHE_MANIFESTS`, or a rostered file that has stopped asserting; the **guard** runs on the finished cut and — **inverted on the maintainer's ruling of 2026-08-18 ([#284](https://github.com/sleepy-panda-srl/portulan/issues/284))** — refuses any machine-read `license` value that is **not** Apache-2.0, plus any issuer-machinery path that leaked in, diagnosing a drifted rostered manifest separately from an unrostered one and from a failed self-exclusion. Nothing rewrites licence metadata and `LICENSE` ships: the bundle is the public tree's bytes under the public tree's licence, so the README's own License section is correct as written and its link resolves. The issuance ledger, and all recipient data, stay OUTSIDE this repository; evaluation terms render from [`eval-license.template.md`](eval-license.template.md) **at the payload commit**, pinning payload and terms to one sha; `--check` (what [`../.portulan/verify/eval-bundle.sh`](../.portulan/verify/eval-bundle.sh) runs) cuts the **index**, wrapped as an unreferenced probe commit, for a fixture recipient into scratch it always deletes. **Deliberately not a ninth `portulan` subcommand**, on `discover`'s precedent above — and deliberately **self-excluded from the payload**, so an evaluee never receives the issuer's machinery. |
|
|
160
128
|
| [`eval-bundle.test.mjs`](eval-bundle.test.mjs) | Its test suite. The rosters are pinned with the suite's **own** instruments — `git ls-tree` and `git grep`, never the module's helpers — because a pin that asks the subject to measure itself tests agreement, not truth; the self-exclusion is exercised **positively** on a fixture repository that plants files at exactly the excluded paths; the terms pin is **demonstrated** (an old commit stamps its old template whatever the tree says now); and the plumbing transport is asserted byte-identical, modes included, to `git archive \| tar -x`, so the port's one mechanical delta is demonstrated rather than trusted. |
|
|
@@ -168,6 +136,9 @@ check on it.)_
|
|
|
168
136
|
| [`pinned-roots.live.test.mjs`](pinned-roots.live.test.mjs) | **The required checks name their resolution root, and this is what makes that a rail.** A pre-commit checkpoint stripped all six `--pack-root packs` from the tree at once and everything stayed green: eleven recipes, 1535 tests, nothing red. The pins were shell prose. Removing the one in `doctor.sh` silently reverts `examples/` to green-by-not-looking, which is the exact fail-open the pins were added to close — **a containment nothing enforces is a comment**. |
|
|
169
137
|
| [`list-quoting.live.test.mjs`](list-quoting.live.test.mjs) | **Every recipe that enumerates the tree reads the pathname git carries, not a quoted spelling of it** — the rail from [#209](https://github.com/sleepy-panda-srl/portulan/issues/209), which reported the wrong mechanism. Without `-z`, git C-quotes a control character *regardless of `core.quotePath`*, so a newline never mis-splits a list; it arrives as one line, `"we\nird.md"`. What the line-based form loses is the **spelling**, and that reaches `café.mjs` and not only exotic names. Both directions were live: three recipes turned a quoted path into a **false red**, and `docs.sh`'s cli-table enumeration silently dropped the file and passed — **the only false green of the class**. It accepts `-z` *or* `core.quotePath=false` because the two fail differently, and `docs.sh` cannot take `-z` without arming the `\001` sentinel collision its links `awk` depends on. |
|
|
170
138
|
| [`test-isolation.live.test.mjs`](test-isolation.live.test.mjs) | **A test that substitutes a shared object hands the restore to the runner** — the rail from [#254](https://github.com/sleepy-panda-srl/portulan/issues/254), whose own instrument swept for the NAME `fs.*Sync =` and so could not see the same shape wearing another. Sweeping by SHAPE found fourteen sites, not six: `process.stdout.write` and `process.stderr.write` too. Eleven converted to `t.mock.method`; **three deliberately not**, because the runner scopes a mock to the TEST and those mean a helper call, a loop iteration, or a `process.env` restore — and `t.mock.property` *cannot* take that last one, throwing `ERR_INVALID_OBJECT_DEFINE_PROPERTY` on `process.env` because it installs an accessor pair. It binds the uniform half using the issue's own retire-when as its matcher, so the rule and the rail cannot drift. |
|
|
139
|
+
| [`cli-roster.live.test.mjs`](cli-roster.live.test.mjs) | **The roster beside the eight is a partition of this directory, and no part of it is counted by hand** — the rail from [#204](https://github.com/sleepy-panda-srl/portulan/issues/204), whose reporter had read three carriers that disagreed and concluded a tool had been removed. Two of the three now cite the third; what stayed unrailed was the surviving sentence, and it drifted again — `version-carriers.mjs` and `inside.mjs` reached the table and neither roster sentence. The eight come from a real import of `SUBCOMMANDS`, never a copied list; everything else must be named between the roster markers. Both directions, because both have failed. The **numerals are gone rather than corrected**, on this file's own convention about hand-maintained figures — a count nobody writes cannot go stale. |
|
|
140
|
+
| [`shadowed-pack.test.mjs`](shadowed-pack.test.mjs) | **Two roots answered for one declared pack, and the compiler refuses rather than picking** — the rail from [#316](https://github.com/sleepy-panda-srl/portulan/issues/316). Discovered-first resolution meant a bare `compile` emitted the installed copy's policy while `verify/compile.sh` read the tree's; on this project's own host that re-introduced a `git commit --no-verify` matcher the tree had deliberately removed as false coverage. Hermetic by **injecting the discovery thunk** rather than faking a plugin cache, since a fake host would re-test `discover.mjs`'s record reader and tie these cases to a schema they say nothing about. The edge that keeps the refusal honest is **elected** discovery: refusing `--pack-root auto` would refuse a caller for answering the very question the refusal asks. |
|
|
141
|
+
| [`shadowed-resolution.test.mjs`](shadowed-resolution.test.mjs) | **The same refusal in the two tools `compile`'s could not reach** — `index` and `recipe-set` resolve packs without going through `packContributions`, so [#316](https://github.com/sleepy-panda-srl/portulan/issues/316)'s guard was structurally out of range. Its first two cases are the demonstration [#318](https://github.com/sleepy-panda-srl/portulan/issues/318) was filed owing: the two worlds digesting a different memory scope, and composing run lines that point at different files. Both are shown through the **elected** spellings, because the bare path now refuses — a fixture claiming to show divergence there would be showing the refusal instead. |
|
|
171
142
|
| [`gh-bot.test.mjs`](gh-bot.test.mjs) | The agent identity's wrapper refuses the endpoints it is not for. Its subject, [`../.portulan/tools/gh-bot`](../.portulan/tools/gh-bot), is customer-zero operator tooling and not part of the product — but the suite lives here anyway, because [`../.portulan/verify/tests.sh`](../.portulan/verify/tests.sh) runs exactly `cli/**/*.test.mjs` and that recipe's stated design is that **a new suite joins by existing rather than by being named**. |
|
|
172
143
|
| [`fixtures/`](fixtures/) | Known-bad manifests, and a workspace whose repo card has drifted from its tree. |
|
|
173
144
|
|
|
@@ -190,11 +161,8 @@ not · `2` could not run. `compile`: exit `0` when it wrote, or agreed under `--
|
|
|
190
161
|
`--check`, when the artifact is missing or has drifted · `2` could not run — writing never returns `1`,
|
|
191
162
|
because a run that rewrites the artifact has nothing to disagree with. `init` and `new` have only **two** codes —
|
|
192
163
|
`0` it wrote · `2` it wrote nothing — and the missing `1` is the point: they render no verdict about
|
|
193
|
-
anybody's workspace, so they have no red to report. _(
|
|
194
|
-
|
|
195
|
-
at all: a human declining at the confirmation, or ending the input. The code is unchanged and the gloss
|
|
196
|
-
now covers every way of reaching it — widening the sentence rather than minting a third code, since `0`
|
|
197
|
-
must keep meaning **it wrote** for anything chaining on it. `new`'s two are unaffected.)_ `vendor` **does** have a `1`, and the asymmetry is
|
|
164
|
+
anybody's workspace, so they have no red to report. _(`2` covers every way of writing nothing, a human declining at the confirmation included — `0`
|
|
165
|
+
must keep meaning **it wrote** for anything chaining on it.)_ `vendor` **does** have a `1`, and the asymmetry is
|
|
198
166
|
worth a sentence: it runs the real validator at both ends of a switch and reports its verdict, so
|
|
199
167
|
collapsing *the workspace I materialised is invalid* into *I could not run* would leave a caller unable
|
|
200
168
|
to tell a bad workspace from a missing flag. `index` uses the same three
|
|
@@ -251,8 +219,7 @@ recipe the manifest **yields** — the workspace's own, plus those the packs it
|
|
|
251
219
|
constant dressed as a measurement. The `affordances` slot is the named input and not the only one — six manifest keys are
|
|
252
220
|
read beside it, because a score confined to the slot could not tell two workspaces apart. What it
|
|
253
221
|
cannot do is judge the prose: the limits dimension is a **form** check over a named heading table, so
|
|
254
|
-
a section with an empty body passes it.
|
|
255
|
-
from milestone 2 until milestone 7 session 7.)_
|
|
222
|
+
a section with an empty body passes it.
|
|
256
223
|
- **It cannot see live settings.** The gate-map lint compares a claimed status-check name against job ids
|
|
257
224
|
in the tree. Whether branch protection actually requires that check, and which app it is pinned to, are
|
|
258
225
|
API facts `doctor` does not fetch.
|
|
@@ -313,17 +280,11 @@ this repository owns and others may run, not as a contract shipped to them.
|
|
|
313
280
|
[`../.portulan/tools/`](../.portulan/tools/) holds operator tooling. Putting a universal validator in
|
|
314
281
|
either would have made it look local to the one workspace it happened to be written beside.
|
|
315
282
|
|
|
316
|
-
Zero-dependency ESM on Node rather than TypeScript
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
adds declares no dependencies and exists to carry the `bin`; `npm install` fetches nothing, and every
|
|
322
|
-
tool here still runs as `node cli/<tool>.mjs` from a fresh clone.
|
|
323
|
-
|
|
324
|
-
_(This paragraph previously closed with "the CLI at milestone 7 absorbs this file and takes the build
|
|
325
|
-
with it" — a sentence whose "this file" had no clear referent and which predicted the opposite of
|
|
326
|
-
what was ruled. Replaced rather than annotated, since nothing in it survived.)_
|
|
283
|
+
Zero-dependency ESM on Node rather than TypeScript, and that is **a ruling rather than a "for
|
|
284
|
+
now"**: a build step would mean this repository could no longer be checked by cloning it. So the CLI
|
|
285
|
+
does **not** bring a build with it. `package.json` declares no dependencies and exists to carry the
|
|
286
|
+
`bin`; `npm install` fetches nothing, and every tool here still runs as `node cli/<tool>.mjs` from a
|
|
287
|
+
fresh clone.
|
|
327
288
|
|
|
328
289
|
## Environment the compiled runners read
|
|
329
290
|
|
|
@@ -336,6 +297,8 @@ package at all (before milestone 7 they resolved `HERE/..`, which is true in exa
|
|
|
336
297
|
| `CLAUDE_PROJECT_DIR` | the repository the policy governs; the host sets it, and the emitted hook interpolates it | falls back to the process's working directory, which is where a hook runs |
|
|
337
298
|
| `PORTULAN_WORKSPACE` | the workspace directory's **name** inside that repository | `.portulan` |
|
|
338
299
|
|
|
300
|
+
**`stop-gate` reads one thing the table cannot show: the Stop payload's `cwd`.** `CLAUDE_PROJECT_DIR` names the repository the hook governs, which is not always the working tree the session used — a session in a git worktree has both. Since [#220](https://github.com/sleepy-panda-srl/portulan/issues/220) the gate asks its did-work and handoff questions about the session's own tree when `cwd` resolves inside the **same** repository, and falls back to `CLAUDE_PROJECT_DIR` — saying so — when it does not. The same-repository condition is the difference between a fix and a bypass: `cwd` is the one input a gated agent can steer, and any tree it named would otherwise excuse work in the governed one. The refusal counter and the verify recipe deliberately do not follow the session's tree.
|
|
301
|
+
|
|
339
302
|
**Two honest limits.** `PORTULAN_WORKSPACE` is read and nothing sets it — it exists so a workspace under
|
|
340
303
|
another name is not unreachable, not because anything ships that way. And the two runners **differ** when
|
|
341
304
|
no workspace is found: `stop-gate.mjs` blocks loudly, because a Stop-gate that cannot read the workspace
|