@sleepy_panda_srl/portulan 0.1.1 → 0.1.2

package/cli/version-carriers.mjs

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+// Portulan — every prose statement of the CURRENT version agrees with `package.json`.
+//
+// ## The defect this exists for
+//
+// `README.md` and `.portulan/products/portulan/product.md` both said the newest release entry was
+// `0.2.0` while `package.json`, both plugin manifests and the registry said `0.1.0`. They were fixed
+// together — and then, one release later, the SAME PAIR drifted again: `README.md` still read
+// "Current release: `0.1.0`" inside the change that cut `0.1.1`. Twice, with the pairing already
+// written down in `docs/plan.md` both times.
+//
+// **A sibling list in prose is not a rail.** This is the rail.
+//
+// It matters more than a tidy number because `README.md` is in `package.json`'s `files`, and npm
+// FREEZES a README per published version: a wrong current-version sentence that reaches a publish
+// cannot be corrected by any edit to `main`, only by cutting another release. That is exactly what
+// `0.1.1` was for.
+//
+// ## Why the record layer is excluded, which is the whole design
+//
+// This repository writes about its own defects, so the retired sentences are QUOTED in the files that
+// record fixing them: `CHANGELOG.md` carries *"The newest release entry is `0.2.0`"* inside the entry
+// explaining that it was retired, and two handoffs plus `docs/plan.md` do the same. A matcher over
+// everything reds on the repository's own account of the repair — the failure mode #286 measured,
+// where both arms it proposed died on this repository's own review corpus.
+//
+// So the scan is scoped to LIVE prose and the record layer is excluded BY PATH. The exclusion is not
+// a convenience: a dated record is supposed to preserve a sentence that is no longer true, and a rail
+// that forbids that would forbid the record.
+//
+// ## What it cannot do, stated rather than discovered
+//
+// A current-version claim spelled a NEW way, in any file, is invisible to it. There is no way to tell
+// "this prose asserts the current version" from "this prose mentions a version" without a matcher, and
+// a matcher only knows the spellings it was given. The accepted practice for that residual is #286's,
+// ruled by the maintainer: **a new spelling gets a pattern here and a fixture first.**
+//
+// The half that IS closed beyond drift: every file in MUST_CARRY has to produce at least one match, so
+// deleting or rewording a known carrier reds instead of silently shrinking the rail's reach.
+//
+// Three further residuals, named because an unstated limit is the one a reader assumes away:
+//   · A live claim placed UNDER an excluded prefix is invisible. `.portulan/memory/` in particular
+//     holds doctrine-shaped notes rather than only dated records, so a current-version sentence
+//     written there would not be checked.
+//   · An UNTRACKED carrier is invisible: enumeration is `git ls-files`, deliberately, because a rail
+//     that reads the working tree grades files no commit will ever contain.
+//   · A NON-MARKDOWN carrier is invisible: the pathspec is `*.md`.
+//
+// Exit 0 green · 1 a finding · 2 could not run.
+
+import { readFileSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { execFileSync } from "node:child_process";
+
+/** Raised when a precondition fails. Always exit 2 — never a finding about the prose. */
+export class CouldNotRun extends Error {}
+
+// The spellings that assert a current version. Each must capture the version in group 1.
+export const PATTERNS = [
+    { id: "current-release", re: /\*\*Current release:\s*`([^`]+)`\*\*/g },
+    { id: "newest-entry", re: /newest release entry is\s*`([^`]+)`/g },
+    { id: "supported-current", re: /\|\s*`([^`]+)`\s*\|\s*Yes\s*—\s*the current release\s*\|/g },
+];
+
+// Files that MUST carry at least one claim. Losing one is a finding: it means a carrier was deleted
+// or reworded, which is how this rail would otherwise quietly stop covering what it was built for.
+export const MUST_CARRY = ["README.md", "SECURITY.md", ".portulan/products/portulan/product.md"];
+
+// The record layer. These files preserve sentences that are no longer true, on purpose.
+export const RECORD_PREFIXES = [
+    "CHANGELOG.md",
+    "docs/plan.md",
+    "docs/milestones/",
+    ".portulan/handoffs/",
+    ".portulan/proposals/",
+    ".portulan/tasks/",
+    ".portulan/memory/",
+];
+
+export const isRecord = (p) => RECORD_PREFIXES.some((r) => (r.endsWith("/") ? p.startsWith(r) : p === r));
+
+/** Every tracked Markdown file that is not part of the record layer. Derived, never a written list. */
+export function liveProseFiles(root) {
+    let out;
+    try {
+        out = execFileSync("git", ["-C", root, "ls-files", "-z", "--", "*.md"], { encoding: "utf8" });
+    } catch (e) {
+        throw new CouldNotRun(`could not enumerate tracked files: ${e.message}`);
+    }
+    const all = out.split("\0").filter(Boolean);
+    if (all.length === 0) throw new CouldNotRun("git listed no Markdown files — refusing to report green over an empty scan");
+    return all.filter((p) => !isRecord(p));
+}
+
+export function declaredVersion(root) {
+    let raw;
+    try {
+        // From the INDEX, like the prose it is compared against. Reading the version from the
+        // worktree while reading carriers from the index compares two different trees: a staged
+        // version bump with an unchanged worktree would grade staged prose against the OLD version,
+        // reporting drift that is not there — or, reversed, greening drift that is. Half a fix is
+        // how this rail's own index change first shipped.
+        raw = execFileSync("git", ["-C", root, "show", ":package.json"], { encoding: "utf8" });
+    } catch (e) {
+        throw new CouldNotRun(`could not read package.json from the index: ${e.message}`);
+    }
+    let v;
+    try {
+        v = JSON.parse(raw).version;
+    } catch (e) {
+        throw new CouldNotRun(`package.json is not valid JSON: ${e.message}`);
+    }
+    if (typeof v !== "string" || !v.trim()) throw new CouldNotRun("package.json declares no version string");
+    return v;
+}
+
+/** Every current-version claim in one file's text, with the line it sits on. */
+export function claimsIn(text) {
+    const found = [];
+    for (const { id, re } of PATTERNS) {
+        // A fresh RegExp per call: a `g` regex carries lastIndex, and a shared one skips matches.
+        const rx = new RegExp(re.source, re.flags);
+        let m;
+        while ((m = rx.exec(text)) !== null) {
+            found.push({ pattern: id, version: m[1], line: text.slice(0, m.index).split("\n").length });
+        }
+    }
+    return found;
+}
+
+export function inspect(root) {
+    const version = declaredVersion(root);
+    const files = liveProseFiles(root);
+    const findings = [];
+    const carried = new Set();
+    let claimCount = 0;
+
+    for (const rel of files) {
+        let text;
+        try {
+            // The INDEX, not the working tree — `pack-identity` reads the same way and for the same
+            // reason. Enumerating from the index and then reading the worktree lets a staged drift
+            // with a reverted worktree copy report green while the commit ships the drift.
+            text = execFileSync("git", ["-C", root, "show", `:${rel}`], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+        } catch (e) {
+            // NOT `continue`. `git ls-files` just named this path, so failing to read its blob means
+            // the rail could not examine live prose it is responsible for — and skipping it would
+            // report GREEN over a file never looked at. That is this session's defect class exactly,
+            // and it was sitting inside the rail built against it. Could-not-run, never a green.
+            throw new CouldNotRun(`could not read ${rel} from the index: ${e.message}`);
+        }
+        for (const c of claimsIn(text)) {
+            claimCount++;
+            carried.add(rel);
+            if (c.version !== version)
+                findings.push(`${rel}:${c.line} states the current version as \`${c.version}\`, but package.json declares \`${version}\` (${c.pattern})`);
+        }
+    }
+
+    for (const rel of MUST_CARRY) {
+        if (!carried.has(rel))
+            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.`);
+    }
+
+    return { version, filesScanned: files.length, claimCount, findings };
+}
+
+export function main(argv, stdout = process.stdout, stderr = process.stderr) {
+    const root = argv[0] ?? ".";
+    let r;
+    try {
+        r = inspect(root);
+    } catch (e) {
+        if (e instanceof CouldNotRun) {
+            stderr.write(`version-carriers: could not run — ${e.message}\n`);
+            return 2;
+        }
+        stderr.write(`version-carriers: could not run — unexpected failure: ${e.message}\n`);
+        return 2;
+    }
+    if (r.findings.length) {
+        for (const f of r.findings) stderr.write(`version-carriers: ${f}\n`);
+        return 1;
+    }
+    stdout.write(`ok  version-carriers — ${r.claimCount} current-version claim(s) across ${r.filesScanned} live prose file(s) all read \`${r.version}\`\n`);
+    return 0;
+}
+
+// The entry guard, in the ONE form `cli/rule-carriers.mjs` designates after this repository got it
+// wrong twice. `file://${argv[1]}` is NOT that form: `import.meta.url` percent-encodes, this working
+// copy lives under a path with spaces, and the comparison failed — so the tool exited 0 having run
+// nothing. **A green that is the tool never starting**, shipped inside the rail built against exactly
+// that. The realpath fallback covers the symlink case an npm `bin` produces, in a `try` because a
+// missing path must answer no rather than throw.
+function isMain() {
+    const invoked = process.argv[1];
+    if (!invoked) return false;
+    if (import.meta.url === pathToFileURL(invoked).href) return true;
+    try {
+        return import.meta.url === pathToFileURL(realpathSync(invoked)).href;
+    } catch {
+        return false;
+    }
+}
+
+// `process.exitCode` rather than `process.exit`, which `cli/control-chars.mjs:540` settled for this
+// repository: exiting outright can truncate a pipe that has not drained. It matters more here than
+// stylistically — a truncated `ok` line IS exit 0 with no output, which is the precise shape of the
+// false green this file's entry guard was fixed for. The same defect, one door along.
+if (isMain()) process.exitCode = main(process.argv.slice(2));

package/core/operating/memory.md

@@ -125,14 +125,13 @@ memory and an implementer's memory answer different questions; merging them spen
 on the other's concerns. _(Provenance: Letta; see `../personas/`.)_
 
 **The first instance is declared at milestone 6 and validated at milestone 7**, and it takes two rows
-because the scoping has two halves. **Milestone 6 declares:** the resolving pack's persona declares its
+because the scoping has two halves. **The declaring half:** the resolving pack's persona declares its
 memory scope, and the resolution demonstration shows that scope landing in the **adopting workspace's
 own layer** — declared by the pack, owned and populated only by the adopter, empty until earned. The
-deliverable there is the scoping *demonstrated*, never a populated store. **Milestone 7 validates:** that
-row already has `doctor` checking a persona against its five-part contract, and the memory scope is one
-of those parts, so it is where a declaration stops being prose a checker can read but not honour.
+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
+scope is one of those parts — where a declaration stops being prose a checker can read but not honour.
 
-**The declaration exists as of milestone 6, session 1**, and what it is *not* is the load-bearing half.
+**The declaration exists**, and what it is *not* is the load-bearing half.
 The `rituals/checkpoints` pack's supervisor persona declares its scope; a composed workspace lands one
 directory per declared scope in its own layer, generated into an index that is byte-compared, and the
 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
 for the slot and the generated index prints it on its own face, deliberately, because a limit stated only
 where a reader already knows to look is stated at the narrowest carrier.
 
-**Settled by the maintainer on 2026-07-29** — verbatim, *"row 6 declares, row 7 validates"* — after two
-sessions put the same question to him within the hour without knowing of each other and were given
-different answers. The record of both, and of the third option that reconciles them, is
+**Settled by the maintainer** — verbatim, *"row 6 declares, row 7 validates"* — after the same question
+was put to him twice and answered two different ways. The record of both, and of the third option that
+reconciles them, is
 [#98](https://github.com/sleepy-panda-srl/portulan/issues/98) and
 [`docs/milestones/m06.md`](../../docs/milestones/m06.md). Neither row needed a criterion edit to carry
 this: both already demanded their half. Said plainly because the

package/core/operating/verification.md

@@ -44,23 +44,15 @@ is the machine check that fires when an agent tries to end a task: it runs the t
 blocks "done" if the recipe is not green. The engine defines the contract — a task declares its verify
 recipe; the gate runs it on Stop. The recipe resolves down the cascade — the **workspace** sets the
 default, a **repo card** overrides it, a **task** may specialize — and the **compiler** wires the gate
-to the host. _(The cascade is the contract; the runner shipped in milestone 4 reads the **workspace
+to the host. _(The cascade is the contract; the runner reads the **workspace
 default only**. The repo-card and task steps are **not built, and no milestone owns them yet** — said in
 that form deliberately, because it is the honest one and this file is where the rule lives. Named here
 because a sentence describing resolution a runner does not perform is a capability claim, and this file
-is the one that legislates against those. Found at the milestone-4 close.
-**Re-pointed 2026-08-03, on the maintainer's ruling.** This sentence previously said the two steps
-"arrive with the CLI in milestone 7", which satisfied the rule in letter — it named a milestone — and
-failed it in fact: the milestone named never took the obligation on, and no later one carries it either,
-so the promise was carrier-less across the whole map. The two resolutions were to expand that row or to
-re-point this sentence; the maintainer took the second, on
-the ground that the runner shipped, at the time of that ruling, in no artifact an adopter received, so
-building more of it bought an adopter nothing. _(It ships now — milestone 7 moved both runners into the
-packaged CLI — which changes the premise and not the ruling: the two resolution steps are still unbuilt
-and still unowned.)_ The precedent for the wording is `spec/pack.schema.json`'s `verify` note, which held
+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
+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
 exactly this form until a ruling gave it an owner.)_
 
-The runner arrived in milestone 4, and two of its properties are contract rather than detail. A recipe
+Two of the runner's properties are contract rather than detail. A recipe
 that **could not run** blocks exactly as a red one does: "nothing looked" must never be read as "nothing
 wrong". And the gate carries an **iteration cap** — a host's end-of-turn event is not the same event as
 *the task is finished*, so a gate that blocked indefinitely would make a red working copy undriveable,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleepy_panda_srl/portulan",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Portulan — an agentic-engineering framework whose product is its files. The CLI wraps the file-based mechanics for hosts beyond Claude Code.",
   "license": "Apache-2.0",
   "type": "module",

package/packs/README.md

@@ -15,18 +15,14 @@ array, in the canonical `category/name` form.
 
 ## Why there is a `.claude-plugin/plugin.json` in *this* directory
 
-Because **this directory is itself a plugin payload**, and it had been shipping as one while declaring
-nothing. The private feed's `portulan-checkpoints` entry is a `git-subdir` source rooted here, so what a
-host installs is the contents of `packs/` — and until 2026-08-09 that payload carried no plugin manifest
-at all. The host had nothing to read, registered nothing, and said so only as a count nobody was
-watching: **`claude plugin details portulan-checkpoints@portulan-internal` → `Skills (0)`**, for the
-whole of milestone 6 and after.
-
-That is [#134](https://github.com/sleepy-panda-srl/portulan/issues/134)'s `Skills (0)` bullet, and the
-issue's own diagnosis of it was wrong: it attributed the zero to a declared path pointing one level too
-high, which is a real trap and a different one. Measured on Claude Code 2.1.226 by installing this
-directory both ways — **`Skills (0)` without the manifest, `Skills (3)` with it**, the same three
-`SKILL.md` files either way.
+Because **this directory is itself a plugin payload**. The private feed's
+`portulan-checkpoints` entry is a `git-subdir` source rooted here, so what a host installs is the
+contents of `packs/` — and a payload with no plugin manifest registers nothing, silently, reporting
+it only as a count nobody is watching: `claude plugin details` → `Skills (0)`.
+
+**Registration is a property of the plugin manifest and of nothing else.** Measured on Claude Code
+2.1.226 by installing this directory both ways — **`Skills (0)` without the manifest, `Skills (3)`
+with it**, the same three `SKILL.md` files either way.
 
 The manifest declares `./rituals/checkpoints/skills/` — the directory that actually holds them — because
 **a host expands a declared skills path exactly one level and no further**. Declaring `./rituals/`
@@ -50,12 +46,6 @@ exists and the feed's pin moves to it. Until then the green is demonstrated on t
 for the feed — a distinction this repository would rather write down than round off.
 
 > **Two packs exist.** [`rituals/checkpoints`](rituals/checkpoints/README.md), the supervised-build
-> ritual, as of milestone 6; and [`tools/github`](tools/github/README.md), one verify recipe, authored
-> at milestone 7 session 5 because a demonstration needed a real subject. `stacks/` is still empty and
-> says why. _(This said "One pack exists … `stacks/` and `tools/` are still empty" from milestone 6
-> until 2026-08-13, and the second half went false the day `tools/github` landed beside it.)_
->
-> This file read "Nothing here yet" for four milestones, and the pack it predicted — a cross-artifact
-> consistency check — is not the one that arrived. Recorded rather than quietly replaced: the first
-> pack was chosen by which ritual this project could show working evidence for, not by which was named
-> first.
+> ritual; and [`tools/github`](tools/github/README.md), one verify recipe. `stacks/` is still empty and
+> says why.
+

package/packs/tools/README.md

@@ -3,10 +3,7 @@
 Tool packs — integrations for the tools and MCP servers an agent drives (issue trackers, cloud
 CLIs, design tools, databases), with the how-to and the gate classification for each.
 
-> **One tool pack exists** — [`github/`](github/README.md), since milestone 7 session 5. _(This read
-> "No tool pack exists yet" until 2026-08-13, beside the directory that refutes it.)_ What changed at
-> milestone 6 was the machinery rather
-> than this directory. Milestone 4 built the thing that would read one — a gate policy in a
+> **One tool pack exists** — [`github/`](github/README.md). The machinery that reads one is a gate policy in a
 > host-neutral vocabulary, dispatched on by [`../../cli/compile.mjs`](../../cli/compile.mjs) — and the
 > cascade's missing middle (`core < pack < workspace`) is now bridged: a pack's `contributes.gates`
 > fragments are resolved and merged into the policy, **tighten-only**, by the same compiler.

package/spec/README.md

@@ -6,8 +6,7 @@ what makes both machine-readable instead of a folder convention.
 
 - [`workspace.schema.json`](workspace.schema.json) — the **Workspace Definition**: the manifest at a
   workspace root. Normative.
-- [`pack.schema.json`](pack.schema.json) — the **Pack Definition**: the manifest at a pack root, added at
-  milestone 6, declaring what the pack contributes to the cascade. Normative, and on **its own version
+- [`pack.schema.json`](pack.schema.json) — the **Pack Definition**: the manifest at a pack root, declaring what the pack contributes to the cascade. Normative, and on **its own version
   train** — see [Versioning](#versioning-and-migrations).
 - [`slots.md`](slots.md) — every workspace slot: what it holds, why it exists, where it was derived from,
   and what `doctor` checks about it. The rationale lives there; this file is the orientation.
@@ -64,7 +63,7 @@ read.
 The fourth, **`pointer`**, added at 2.7, governs nothing. It names the workspace that governs this
 repository and carries no slots of its own — a repository whose policy layer resides elsewhere says so in
 one thin manifest instead of keeping a second copy nothing holds in agreement. That is the maintainer's
-residence ruling of 2026-07-30 in the schema
+residence ruling in the schema
 ([proposal 0017](../.portulan/proposals/0017-one-repository-one-governing-workspace.md)):
 
 > A repository is governed by exactly one workspace. It carries its own full workspace, or a pointer to
@@ -76,11 +75,11 @@ makes that a property rather than a promise is that every feature keys to a work
 to a residence. Nothing in `doctor`, `compile` or `index` asks where the manifest lives. The proposal
 carries the one place where that was not yet true, and it was a discovery gap rather than a feature gap:
 the boot skill searched the project directory only, so a repository governed from a feed booted to a
-pointer's honest report rather than to a resolved workspace. **Closed at milestone 7** by
+pointer's honest report rather than to a resolved workspace. **Closed** by
 [`../cli/discover.mjs`](../cli/discover.mjs), which reads the host's installed-plugin record and
 dereferences a pointer's `governed_by` — from disk, never over the network. The other half of the same amendment — the **pack** root
 ([#123](https://github.com/sleepy-panda-srl/portulan/issues/123)) — landed beside it: `--pack-root
-auto` resolves one from that same record. It ran **only when asked** until 2026-08-13, which was narrower
+auto` resolves one from that same record. It ran **only when asked**, which was narrower
 than the row's *"optional where discovery finds a root"* and was recorded as a narrowing rather than read
 as compliance. **The narrowing is now lifted and the row's word is met**: discovery runs on the unasked
 path, and `auto` selects the strict degrade rather than unlocking anything. The narrowing's stated reason
@@ -159,10 +158,8 @@ real cost, stated here rather than discovered. The subset earns its narrowness b
 completely and honestly; the price is this list, and the list is the thing to watch if it keeps growing.
 **Four MINORs at +2 each** was the growth rate to hold the next bump against, and **2.3's, 2.5's and
 2.6's** pairs are the *same* pair three times over — a series needs a store and its index must sit outside
-it — which was an argument for generalising it rather than adding it again. _(2.4's pair is `librarian`'s
-and is a different one: a pass needs a store to age, and a proposal threshold needs a proposal series.
-An earlier draft of this sentence read "2.4's, 2.5's and 2.6's", which would have made the repeating pair
-four bumps old instead of three and misattributed `memory`'s contribution to `librarian`.)_
+it — which was an argument for generalising it rather than adding it again. _(2.4's pair is `librarian`'s and is a
+different one: a pass needs a store to age, and a proposal threshold needs a proposal series.)_
 
 **2.7 is the first MINOR since 2.2 that adds nothing to this list**, and that is the reason its pointer
 requirement went into the schema's `oneOf` instead. The generalisation the paragraph above kept asking for
@@ -198,7 +195,7 @@ number governing both would make a bump in either mean a change in the other:
 | Schema | Manifest key | Current | What it governs |
 |---|---|---|---|
 | [`workspace.schema.json`](workspace.schema.json) | `portulan.spec` | **2.8** | the Workspace Definition — the manifest at a workspace root |
-| [`pack.schema.json`](pack.schema.json) | `portulan.pack` | **1.0** | the Pack Definition — the manifest at a pack root, added at milestone 6 |
+| [`pack.schema.json`](pack.schema.json) | `portulan.pack` | **1.0** | the Pack Definition — the manifest at a pack root. |
 
 The rules below apply to each train independently. `portulan.spec` is `MAJOR.MINOR`, and the current
 Workspace Definition version is **2.8**. It did **not** move when the Pack Definition arrived, because
@@ -300,7 +297,7 @@ better, and not a fix.)_
 
 This migration is a paragraph and a version bump, and a directory holding a document that says "add one
 line" would be scaffolding pretending to be machinery. This paragraph therefore ended **"There is still
-no `migrations/` directory: one arrives when a migration needs code"** — and at milestone 7 session 9
+no `migrations/` directory: one arrives when a migration needs code"** — and
 one did, on that stated condition rather than because a tool wanted a home.
 
 **[`migrations/`](migrations/) is now the contract**, and its README is where a step is defined. What
@@ -328,24 +325,24 @@ workspace with no constitution slot and a green report.
 |---|---|---|
 | Every `.json` file parses | [`../.portulan/verify/json.sh`](../.portulan/verify/json.sh) | **Built.** Well-formedness only — it does not read the schema. |
 | Manifest conforms to the schema | [`../cli/doctor.mjs`](../cli/doctor.mjs) | **Built.** Names the violated constraint and its location. |
-| A declared pack **resolves** | `doctor` | **Built** (milestone 6). Roots are derived from `tree`, and named roots may be given with `--pack-root`, which **replace** the derived one rather than preceding it, so a from-a-feed demonstration cannot be satisfied by a copy in the local tree at all. A workspace with no `tree` and no named root has its packs reported *unverifiable* rather than failed. Resolution **from a feed is demonstrated** as of milestone 6, session 1: the checkpoint ritual pack installed from the private `portulan-internal` marketplace and resolved from the install root, which is the same code path the derived one takes. **Discovery landed at milestone 7** ([#123](https://github.com/sleepy-panda-srl/portulan/issues/123)): `--pack-root auto` reads the host's installed-plugin record — in **both** shapes a plugin lands in, packs under `packs/` for a repository-shaped one and categories at the install root for a flat one, which is what this project's own feed ships. **Amended 2026-08-12:** asked-for discovery is **unioned** with the tree-derived root, discovered first, so a workspace composing a cache-installed pack *and* one of its own resolves both — which no invocation could do before without naming a cache path by hand. The **named**-root property above is untouched: a named root still replaces the derived one, so a from-a-feed demonstration given one cannot be satisfied by a local copy. What the union trades is the weaker guarantee that `auto` *alone* implied provenance; it no longer does, and each pack's resolution states which root answered instead. Asking for a named root **and** `auto` together is refused (exit 2) rather than silently resolved to one of them. **Amended 2026-08-13 — the disposal:** discovery runs on the **unasked** path too, because the row's clause is that `--pack-root` is *optional where discovery finds a root* and it was not. `auto` now selects the strict degrade (asked-and-could-not-look is exit 2) rather than unlocking discovery. Two things bound it, and neither makes a bare run host-independent — `doctor` is a per-host capability report and a bare verdict does move with the machine. First, every **required** check **names** its root, which replaces every other source, so it cannot consult the host at all. Second, `doctor`'s note-vs-fail keying is on a root's **origin**, so discovery can turn a note into a **resolution** and never a **miss** into a failure — a miss under a root the workspace or the caller claimed stays a FAIL whatever is installed. It softens nothing: a discovered copy that resolves and is *invalid* still fails, with its origin named. |
-| A pack manifest conforms to the Pack Definition | `doctor` | **Built** (milestone 6). Same validator, same subset, a different schema and version train. |
-| A pack's skills and personas are opened and validated | `doctor` | **Built** (milestone 7 session 2), on the maintainer's ruling of 2026-08-03 that row 7's validation reads broad. A skill's frontmatter (`name` kebab-case, `description` non-empty — the two a host reads before loading a body); a persona against the five-part contract, **including the memory scope** `core/operating/memory.md` promised would be validated at this milestone; and the tier no role may claim. Containment is checked **after resolution**, because opening these paths is what made an escaping value stop being inert. Three honest limits, each measured rather than assumed. The skills walk stops **three levels down**, matching `cli/plugin-lint.mjs`'s bound so two walkers over the same key cannot disagree, and it **reports the directories it did not descend into** rather than counting a root it never opened as empty. The Prohibited check is a prose heuristic defeated by any negation **in the same block** — a bullet list counts as one block — and the structural fix is a declared reach *field*, a contract change that is not built. And the five-part check is **presence**, not content: a persona whose sections are all empty passes, so a declared memory scope is read and not honoured. |
-| Pack gate fragments merge **tighten-only** | [`../cli/compile.mjs`](../cli/compile.mjs) | **Built** (milestone 6). Two layers and two axes: `auto` is absent from the Pack Definition's tier enum, so a demotion to unattended is unexpressible; the comparison against the composed base is the compiler's, and both a weakened **tier** and a changed **action** throw rather than being dropped. The action half is the one a tier-only check misses — raising the tier while swapping the matcher removes the gate and still reads as a tightening. |
-| A pack declaring a version ahead of `doctor` | `doctor` | **Built** (milestone 6). Refused rather than graded, symmetric with the workspace train, and on the Pack Definition's own `$id`. |
+| A declared pack **resolves** | `doctor` | **Built**. Roots are derived from `tree`, and named roots may be given with `--pack-root`, which **replace** the derived one rather than preceding it, so a from-a-feed demonstration cannot be satisfied by a copy in the local tree at all. A workspace with no `tree` and no named root has its packs reported *unverifiable* rather than failed. Resolution **from a feed is demonstrated**: the checkpoint ritual pack installed from the private `portulan-internal` marketplace and resolved from the install root, which is the same code path the derived one takes. **Discovery is built** ([#123](https://github.com/sleepy-panda-srl/portulan/issues/123)): `--pack-root auto` reads the host's installed-plugin record — in **both** shapes a plugin lands in, packs under `packs/` for a repository-shaped one and categories at the install root for a flat one, which is what this project's own feed ships. Asked-for discovery is **unioned** with the tree-derived root, discovered first, so a workspace composing a cache-installed pack *and* one of its own resolves both. The **named**-root property above is untouched: a named root still replaces the derived one, so a from-a-feed demonstration given one cannot be satisfied by a local copy. What the union trades is the weaker guarantee that `auto` *alone* implied provenance; it no longer does, and each pack's resolution states which root answered instead. Asking for a named root **and** `auto` together is refused (exit 2) rather than silently resolved to one of them. Discovery runs on the **unasked** path too, because `--pack-root` is *optional where discovery finds a root*. `auto` now selects the strict degrade (asked-and-could-not-look is exit 2) rather than unlocking discovery. Two things bound it, and neither makes a bare run host-independent — `doctor` is a per-host capability report and a bare verdict does move with the machine. First, every **required** check **names** its root, which replaces every other source, so it cannot consult the host at all. Second, `doctor`'s note-vs-fail keying is on a root's **origin**, so discovery can turn a note into a **resolution** and never a **miss** into a failure — a miss under a root the workspace or the caller claimed stays a FAIL whatever is installed. It softens nothing: a discovered copy that resolves and is *invalid* still fails, with its origin named. |
+| A pack manifest conforms to the Pack Definition | `doctor` | **Built**. Same validator, same subset, a different schema and version train. |
+| A pack's skills and personas are opened and validated | `doctor` | **Built**, on the maintainer's ruling that row 7's validation reads broad. A skill's frontmatter (`name` kebab-case, `description` non-empty — the two a host reads before loading a body); a persona against the five-part contract, **including the memory scope** `core/operating/memory.md` promised would be validated at this milestone; and the tier no role may claim. Containment is checked **after resolution**, because opening these paths is what made an escaping value stop being inert. Three honest limits, each measured rather than assumed. The skills walk stops **three levels down**, matching `cli/plugin-lint.mjs`'s bound so two walkers over the same key cannot disagree, and it **reports the directories it did not descend into** rather than counting a root it never opened as empty. The Prohibited check is a prose heuristic defeated by any negation **in the same block** — a bullet list counts as one block — and the structural fix is a declared reach *field*, a contract change that is not built. And the five-part check is **presence**, not content: a persona whose sections are all empty passes, so a declared memory scope is read and not honoured. |
+| Pack gate fragments merge **tighten-only** | [`../cli/compile.mjs`](../cli/compile.mjs) | **Built**. Two layers and two axes: `auto` is absent from the Pack Definition's tier enum, so a demotion to unattended is unexpressible; the comparison against the composed base is the compiler's, and both a weakened **tier** and a changed **action** throw rather than being dropped. The action half is the one a tier-only check misses — raising the tier while swapping the matcher removes the gate and still reads as a tightening. |
+| A pack declaring a version ahead of `doctor` | `doctor` | **Built**. Refused rather than graded, symmetric with the workspace train, and on the Pack Definition's own `$id`. |
 | Path slots resolve to real files | `doctor` | **Built.** File-versus-directory too; a slot resolving outside the workspace is reported, never failed. |
 | Workspace claims match the tree | `doctor` | **Built, where a tree is declared** — repo-card build/test/run lines and layout, and the gate map's required-check claim. A workspace with no `tree` has those claims *reported unverifiable*. |
 | A rule's provenance is well-formed | `doctor` | **Built.** On `type: rule` records in the `memory` slot; the form only, never the truth. |
 | Sealed proportion reported | `doctor` | **Built.** Over rules, which is the denominator the mandate uses. |
-| The recipes a workspace declares actually run | Stop-gate runner | **Built** (milestone 4), for the **default** recipe only, and outside `doctor` — which still reads recipes and executes none. A non-default recipe declaring a tool it does not have still passes. |
-| The gate policy compiles to host enforcement | `compile` | **Built** (milestone 4). Two backends — the Claude Code host and the GitHub repository ruleset that is the platform floor. Every rule ends as compiled or refused-with-a-reason, **per backend**, and each emitted artifact is held to the policy by a verify recipe. That the *host* honours it is not checkable here — CI installs nothing. |
-| What each backend cannot enforce | `doctor` · `compile --matrix` | **Built** (milestone 4). Per-backend coverage, the gates no backend compiles, and the floor's declared status checks against the tree's workflow jobs — the last of those a failure, the rest reports. Exported-versus-live drift is **not** checked: `doctor` does not fetch settings, and no recipe here makes a network call. |
+| The recipes a workspace declares actually run | Stop-gate runner | **Built**, for the **default** recipe only, and outside `doctor` — which still reads recipes and executes none. A non-default recipe declaring a tool it does not have still passes. |
+| The gate policy compiles to host enforcement | `compile` | **Built**. Two backends — the Claude Code host and the GitHub repository ruleset that is the platform floor. Every rule ends as compiled or refused-with-a-reason, **per backend**, and each emitted artifact is held to the policy by a verify recipe. That the *host* honours it is not checkable here — CI installs nothing. |
+| What each backend cannot enforce | `doctor` · `compile --matrix` | **Built**. Per-backend coverage, the gates no backend compiles, and the floor's declared status checks against the tree's workflow jobs — the last of those a failure, the rest reports. Exported-versus-live drift is **not** checked: `doctor` does not fetch settings, and no recipe here makes a network call. |
 | One repository, one governing workspace | `doctor` | **Built** (2.7). Two refusals need only the manifest in hand: a `pointer` carrying governing slots, and a governing kind carrying a `governed_by`. Both print the ruling's own sentence, which is why they are `doctor`'s and not the schema's — a schema failure returns at *the manifest must conform first* and the sentence would never reach a reader. |
-| A repository named by one workspace and governed by another | `doctor --repo-root` | **Built** (2.7), **where visible**. Roots are named, never discovered — **and since milestone 7 this is the narrower limit of the two**: `--pack-root` gained `auto` and `--repo-root` did not, because what it would have to find is a *repository checkout*, which no host plugin record lists. The amendment that ordered discovery names the plugin cache in its own title, so this is outside its scope rather than owed by it. Without a root the check **reports that it did not run** rather than passing quietly. Visibility is one-way: the refusal runs from the naming workspace outward, so a repository carrying a full workspace cannot see a portfolio that claims it. A workspace that names its **own** repository finds itself and is not two managers; that identity is compared on the real path. |
-| A pointer resolves to the workspace it names | `discover` · `doctor` | **Built** (milestone 7). `governed_by` is dereferenced against the host's installed-plugin record — `<config>/plugins/installed_plugins.json`, `CLAUDE_CONFIG_DIR` overriding the config directory — and the match is on the **governing manifest's `name`**, never on a plugin's, with `governed_by.feed` constraining the marketplace where it is declared. Four answers, because three of them are not *no*: `resolved` (exactly one), `not-installed`, `ambiguous` (two or more — **refused and both named**, never ranked), `could-not-look` (a record that would not parse, which must never spend as absence). **Nothing is fetched**: the record is read from disk and no path here touches the network, so *discovery of anything not installed* stays out of scope as row 7 states. `doctor` **reports** the answer on a pointer and never grades it — a pointer whose governor is uninstalled is a correct pointer, and no discovery outcome moves this tool's exit code. The candidate locations inside a plugin payload are a **named pair** — `<installPath>/workspace.json` and `<installPath>/.portulan/workspace.json` — rather than a walk, which is what keeps this bundle's demo and drifted fixtures out of reach by construction — neither sits at one; the bundle's own `.portulan/` does, which is the correct answer to a pointer naming `portulan` rather than a hole. `init` **asks** the residence question and writes a pointer as of milestone 7 session 1; `vendor` **performs the switch in both directions** as of session 3, and both write pointers rather than resolving them. |
+| A repository named by one workspace and governed by another | `doctor --repo-root` | **Built** (2.7), **where visible**. Roots are named, never discovered — **and this is the narrower limit of the two**: `--pack-root` gained `auto` and `--repo-root` did not, because what it would have to find is a *repository checkout*, which no host plugin record lists. The amendment that ordered discovery names the plugin cache in its own title, so this is outside its scope rather than owed by it. Without a root the check **reports that it did not run** rather than passing quietly. Visibility is one-way: the refusal runs from the naming workspace outward, so a repository carrying a full workspace cannot see a portfolio that claims it. A workspace that names its **own** repository finds itself and is not two managers; that identity is compared on the real path. |
+| A pointer resolves to the workspace it names | `discover` · `doctor` | **Built**. `governed_by` is dereferenced against the host's installed-plugin record — `<config>/plugins/installed_plugins.json`, `CLAUDE_CONFIG_DIR` overriding the config directory — and the match is on the **governing manifest's `name`**, never on a plugin's, with `governed_by.feed` constraining the marketplace where it is declared. Four answers, because three of them are not *no*: `resolved` (exactly one), `not-installed`, `ambiguous` (two or more — **refused and both named**, never ranked), `could-not-look` (a record that would not parse, which must never spend as absence). **Nothing is fetched**: the record is read from disk and no path here touches the network, so *discovery of anything not installed* stays out of scope as row 7 states. `doctor` **reports** the answer on a pointer and never grades it — a pointer whose governor is uninstalled is a correct pointer, and no discovery outcome moves this tool's exit code. The candidate locations inside a plugin payload are a **named pair** — `<installPath>/workspace.json` and `<installPath>/.portulan/workspace.json` — rather than a walk, which is what keeps this bundle's demo and drifted fixtures out of reach by construction — neither sits at one; the bundle's own `.portulan/` does, which is the correct answer to a pointer naming `portulan` rather than a hole. `init` **asks** the residence question and writes a pointer; `vendor` **performs the switch in both directions** as of session 3, and both write pointers rather than resolving them. |
 | A feed-side repo card's claims against a repo-side tree | — | **Not built** — the cross-repo claims-lint gap, priced in [proposal 0017](../.portulan/proposals/0017-one-repository-one-governing-workspace.md). A portfolio workspace declares no `tree`, so its cards' build/test/run and layout claims are *reported unverifiable*; repo-side the tree is present and the cards are not. No single CI run sees both halves. In-session validation does work, and `--repo-root` narrows the governance question specifically — neither closes this. **Tracked as [#138](https://github.com/sleepy-panda-srl/portulan/issues/138)**, filed 2026-07-30 at the maintainer's instruction. This row states no *arrives-at*, unlike its neighbour below which says outright that it is not planned as a gate; which milestone owns it — milestone 9 has been proposed, since its criterion is the first that needs both halves green together — is **the maintainer's to decide**, and this row will name it once [`../docs/plan.md`](../docs/plan.md) does. Until then the honest state is *not built, tracked, undispositioned* rather than a milestone claimed here first. |
 | A rule's link resolves | — | Not built, and not planned as a gate: dereferencing needs the network, and a gate that fails for reasons unrelated to the change under test is worse than no gate. |
-| Agent-legibility scored | `doctor` | **Built** (milestone 7 session 7). **Seven** dimensions, each optional in this definition so it can genuinely be absent and none of them a restatement of a check that already fails — *executable verification* was an eighth for one checkpoint until that rule was applied to it, since form 0 of the `oneOf` above requires `verify` of every workspace the score can reach: recipes declaring `requires` · a machine-readable gate policy · a `dod` slot · a memory store with a generated index · a handoff series with a generated index · affordances reachable for every product (its own or the workspace-level default) · each of those documents naming what an agent must **not** assume. The `affordances` slot is the **named input, not the only one** — a score confined to it could not tell two workspaces apart. **It moves no exit code**: a measurement is not a verdict, and one that could fail a workspace would make conformance a function of prose volume. The last dimension is a **form** check over a named heading table, so a limits section with an empty body passes. |
+| Agent-legibility scored | `doctor` | **Built**. **Seven** dimensions, each optional in this definition so it can genuinely be absent and none of them a restatement of a check that already fails — *executable verification* was an eighth for one checkpoint until that rule was applied to it, since form 0 of the `oneOf` above requires `verify` of every workspace the score can reach: recipes declaring `requires` · a machine-readable gate policy · a `dod` slot · a memory store with a generated index · a handoff series with a generated index · affordances reachable for every product (its own or the workspace-level default) · each of those documents naming what an agent must **not** assume. The `affordances` slot is the **named input, not the only one** — a score confined to it could not tell two workspaces apart. **It moves no exit code**: a measurement is not a verdict, and one that could fail a workspace would make conformance a function of prose volume. The last dimension is a **form** check over a named heading table, so a limits section with an empty body passes. |
 
 As of milestone 2 the schema is a rail rather than only a specification — but read the right-hand column
 rather than the middle one. `doctor` checks that a workspace's claims are **well-formed and resolvable**;

package/spec/migrations/README.md

@@ -1,9 +1,8 @@
 # `spec/migrations/` — what a migration is
 
 > Part of the **Workspace Definition**. [`../README.md`](../README.md)'s *Versioning and migrations*
-> section is the contract this directory implements; it said *"There is still no `migrations/`
-> directory … **One arrives when a migration needs code**"* until milestone 7 session 9, and this
-> directory arrives on that stated condition rather than because a tool wanted a home. The runner is
+> section is the contract this directory implements, and this directory exists on that section's own
+> stated condition: a migration needed code. The runner is
 > [`../../cli/upgrade.mjs`](../../cli/upgrade.mjs).
 
 ## A step, and the two kinds

package/spec/slots.md

@@ -345,9 +345,7 @@ has a product-layer slot, which is what the criterion requires; *instances* may
 **What `doctor` checks:** each `product` path resolves; each `affordances` path **that is present**
 resolves; each `repos` entry names a card in the `repos` slot. Per-product `affordances` is optional
 because a product may inherit the workspace-level default — so the check is conditional, and `doctor`
-*reports* a product that has neither its own nor an inherited one rather than failing it. (An earlier
-draft of this line said `doctor` checks `affordances` unconditionally, which would have made the spec
-demand something the schema declares optional; caught in review of the change that introduced it.) The
+*reports* a product that has neither its own nor an inherited one rather than failing it. The
 claim it cannot check is whether the mission written there is still true.
 
 ## `affordances` — what the product offers an agent
@@ -465,12 +463,9 @@ workspace that cannot say which packs it composes leaves an agent to infer the m
 resolution order. The portfolio workspace at milestone 6 ships as a private-feed plugin composing a pack
 delivered by that feed — a manifest that cannot express that forces a MAJOR bump one milestone after v1.
 
-_(This sentence said **premium** packs until milestone 6, session 1, and no shipped pack is premium: the
-one the portfolio workspace composes is the universal checkpoint ritual, delivered by the private feed and
-authored in the public engine. The prediction was reasonable and turned out not to be what milestone 6
-built, so it is corrected to what the tree shows rather than left as a promise about a pack nobody wrote.
-Whether a premium pack should exist at all is a commercial question for the maintainer, not a gap this
-file may quietly keep open.)_
+_(No shipped pack is premium: the one the portfolio workspace composes is the universal checkpoint
+ritual, delivered by the private feed and authored in the public engine. Whether a premium pack should
+exist at all is a commercial question for the maintainer, not a gap this file may quietly keep open.)_
 
 An array of names in cascade order, empty by default. Each name is the canonical `category/name` form
 the Pack Definition owns ([`pack.schema.json`](pack.schema.json)) — but the items stay **free strings**