@sleepy_panda_srl/portulan 0.1.0

package/packs/README.md

@@ -0,0 +1,61 @@
+# packs/
+
+Composable layers over the engine, each shipped as a plugin:
+
+- `stacks/` — per-language / per-framework profiles.
+- `tools/` — tool and MCP integrations.
+- `rituals/` — repeatable procedures (e.g. PR babysitting, bot-review reconciliation).
+
+A pack overrides `core`, and is itself overridden by the workspace, repo card, and task.
+
+A pack declares what it contributes in a `pack.json` at its root, validated against
+[`../spec/pack.schema.json`](../spec/pack.schema.json) — the Pack Definition, which is on its own
+version train and not the Workspace Definition's. A workspace composes one by naming it in its `packs`
+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.
+
+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/`
+registers nothing, silently, while a validator walking deeper counts three;
+[`../cli/plugin-lint.mjs`](../cli/plugin-lint.mjs) fails that shape for exactly this reason. Two
+manifests therefore sit in this tree and they answer different questions: the repository's own at
+[`../.claude-plugin/plugin.json`](../.claude-plugin/plugin.json), which declares
+`./packs/rituals/checkpoints/skills/` because *its* root is the repository; and this one, whose root is
+`packs/`. Neither is redundant, and the paths differ by exactly the prefix their roots differ by.
+
+**The version here mirrors the pack's own** — `portulan.version` in
+[`rituals/checkpoints/pack.json`](rituals/checkpoints/pack.json), which the Pack Definition names as how
+independent versioning is expressed — and it is the number a host displays for the installed plugin.
+Nothing checks the two agree, which is stated rather than railed because the feed pins a **commit**
+rather than a version, so the pin is what actually decides which bytes install.
+
+**One half of the measurement above has not been run and cannot be yet.** `Skills (0) → Skills (3)` was
+observed through a *local* marketplace over a copy of this directory. The quoted failing command names
+`portulan-checkpoints@portulan-internal`, and its green half can only be observed after this commit
+exists and the feed's pin moves to it. Until then the green is demonstrated on the payload and inferred
+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.

package/packs/rituals/README.md

@@ -0,0 +1,13 @@
+# packs/rituals/
+
+Ritual packs — repeatable procedures that compose onto the loop: PR babysitting, bot-review
+reconciliation, release runbooks, the codify/librarian pass.
+
+| Pack | What it carries |
+|---|---|
+| [`checkpoints`](checkpoints/README.md) | The supervised-build ritual: three checkpoints graded by a fresh context, a `supervisor` persona, and the verdict vocabulary. Milestone 6. |
+
+> The cross-artifact consistency check named in the constitution's influence map — long listed here as
+> the first ritual — is **still unwritten**. It was overtaken rather than cancelled: `checkpoints` went
+> first because it is the ritual this project had a measured record for, having run it at every
+> milestone since the first.

package/packs/rituals/checkpoints/README.md

@@ -0,0 +1,105 @@
+# `checkpoints` — the supervised-build ritual
+
+A ritual pack: three checkpoints at which a **fresh context** grades work it did not do, and the fixed
+vocabulary its verdicts are written in. Composed by a workspace through its `packs` array as
+`rituals/checkpoints`.
+
+The premise is one sentence, and it is **core's**, not this pack's: on the full lane the verdict comes
+from a context that has not seen the implementation, because one primed by the implementing context
+measures agreement rather than correctness. That obligation is stated in
+[`../../../core/operating/loop.md`](../../../core/operating/loop.md), and
+[`../../../core/operating/verification.md`](../../../core/operating/verification.md) explains why it is
+a ceiling on the verifier rather than a rung on the hierarchy. What this pack adds is the **procedure**:
+three named moments, a persona to staff them, and the vocabulary the verdicts are written in. The
+premise moved into core on 2026-07-30; before that this file was where it was stated, which is why the
+sentence reads as a citation now and did not before.
+
+| Contributes | What |
+|---|---|
+| Skills | [`session-open`](skills/session-open/SKILL.md) · [`pre-commit`](skills/pre-commit/SKILL.md) · [`milestone-close`](skills/milestone-close/SKILL.md) |
+| Persona | [`supervisor`](personas/supervisor.md) — grades, never implements or merges |
+| Gate fragments | `commit-without-the-hooks` (gated) · `self-certify-a-checkpoint` (prohibited) |
+
+## The three checkpoints
+
+| Checkpoint | When | What it grades |
+|---|---|---|
+| Session-open | before implementation starts | the session's plan, against the criterion and the workspace's own slots |
+| Pre-commit | when the work is finished, before it is committed | the diff, re-measured against the criterion it claims to meet |
+| Milestone-close | before a milestone is marked done | that the criterion was *demonstrated*, not asserted |
+
+The **When** column is a summary; each skill's own *When to use it* is the operative statement,
+including what an adopting workspace's autonomy tiers can and cannot move.
+
+## The verdict vocabulary
+
+Four verdicts, and which are available depends on the checkpoint.
+
+| Verdict | Means | Available at |
+|---|---|---|
+| **APPROVE** | Proceed as it stands. | session-open · pre-commit |
+| **APPROVE-WITH-ADJUSTMENTS** | Proceed once the numbered adjustments are folded in. Not a soft failure — it is what a working checkpoint usually returns. | session-open · pre-commit |
+| **REQUEST-CHANGES** | Does not meet the standard. Name what, and what would meet it. Needs a second pass at the same checkpoint. | all three |
+| **CLOSE** | Every clause of the criterion is demonstrated; the milestone may be marked done. | milestone-close only |
+
+**Every adjustment is numbered**, so it can be folded in and cited individually. An unnumbered list of
+concerns is not a verdict.
+
+**APPROVE and APPROVE-WITH-ADJUSTMENTS are unavailable at milestone-close on purpose.** Both let work
+proceed on a promise to fold something in, and a close is the one decision with nothing downstream of
+it to catch what was folded in wrongly.
+
+## The fidelity note
+
+What a close leaves in the record once the session that wrote it is gone. Four parts, in one clause:
+
+> **who** verified · **when** · **the verdict, with what was actually re-derived** · **what the close
+> leaves undemonstrated**
+
+A bare *done* plus a link is not a fidelity note.
+
+## What this pack does not do, said plainly
+
+- **It cannot enforce the freshness, and the freshness is the entire mechanism.** No `tools:` list and
+  no permission rule can observe whether the context reading a checkpoint skill has already seen the
+  work. It is a property of how the checkpoint was *invoked*. So this pack ships a practice held by
+  whoever spawns the supervisor, and says so rather than shipping a contract that reads like a rail.
+  `self-certify-a-checkpoint` is a `prohibited` fragment with **no tool-level surface** — it names the
+  gap instead of inventing a matcher that would cover less than its sentence claims, and it therefore
+  **compiles to nothing on every backend**.
+- **It does not set the lane boundary.** Checkpoints bind **full-lane** work; where that lane begins is
+  the adopting workspace's own threshold. A pack imposing three checkpoints on every one-line fix would
+  be ceremony that cannot scale down — which is a named non-goal, and the fastest route to a ritual
+  being switched off wholesale.
+- **It ships no verify recipe.** The obvious one — *every milestone-affecting change carries a recorded
+  verdict* — would have to know the adopter's record format, and a recipe that cannot actually read
+  what it claims to check is worse than none. The Pack Definition can carry recipes
+  ([`../../../spec/pack.schema.json`](../../../spec/pack.schema.json)); this pack has nothing honest to
+  put in that field. _Since milestone 7 a pack's recipes are **composed** into the adopting workspace's
+  runnable set rather than merely declared, so this is a refusal with a cost now and not a limitation of
+  the format — and it is still the right refusal. It is a statement about **this** pack, never about
+  packs generally: [`tools/github`](../../tools/github/README.md) ships one, and was built because this
+  pack's refusal meant milestone 7's composition demonstration had no subject._
+- **It grades against the adopter's standard, never against this pack's.** The skills read the
+  workspace's own constitution, plan, definition-of-done and gate map. Nothing here supplies a standard
+  of its own, and a supervisor substituting its taste for the team's is a second author rather than a
+  check.
+
+## Provenance
+
+Re-expressed from public practice — supervised evolution as the guard against drift, last-mile review
+focus, read-isolated verification. The structure is the two-tier protocol Portulan is itself built
+under, and the checkpoint section of that project's own gate map.
+
+**The evidence is that project's build record**, cited as provenance rather than as procedure: the
+fresh-context checkpoints changed *designs* rather than wording at two consecutive milestones — the
+story is in [milestone 4's record](https://github.com/sleepy-panda-srl/portulan/blob/main/docs/milestones/m04.md),
+beside [the protocol itself](https://github.com/sleepy-panda-srl/portulan/blob/main/docs/plan.md) —
+while adopters received no artifact for the ritual that produced them. This pack is that artifact.
+
+Those two are **absolute URLs on purpose**, unlike this pack's links into `core/`, which ships beside
+it and resolves for an adopter. A provenance link is a pointer at a public record that stays where it
+is; a repo-relative one would resolve only inside the tree this pack was written in, and this pack is
+meant to travel. What travels with it is the mechanism. The bindings that made it work in its home
+repository — one maintainer's names, that tree's paths, its budgets and review-loop mechanics — stay
+in the layer that owns them.

package/packs/rituals/checkpoints/pack.json

@@ -0,0 +1,36 @@
+{
+  "portulan": {
+    "pack": "1.0",
+    "version": "0.2.1"
+  },
+
+  "name": "checkpoints",
+  "category": "rituals",
+  "summary": "Supervised-build checkpoints: a fresh-context supervisor grades the plan at session-open, the diff at pre-commit, and the demonstration at milestone-close, in a fixed verdict vocabulary.",
+  "doc": "README.md",
+
+  "contributes": {
+    "skills": ["skills/"],
+
+    "personas": ["personas/supervisor.md"],
+
+    "gates": [
+      {
+        "id": "commit-without-the-hooks",
+        "tier": "gated",
+        "action": {
+          "none": "No honest matcher. The CATEGORY is committing with the local hooks bypassed, and its spellings are unbounded shell: `--no-verify`, the `-c core.hooksPath=/dev/null` form that an incident in this repository actually used, `core.hooksPath` set at any config origin beforehand, `HUSKY=0` and its equivalents, or a wrapper on PATH. This rule carried `git commit --no-verify` for one milestone, and in the measured incident that matcher gave ZERO protection while reading as coverage — the act performed was the same category in another spelling, so the gate as enumerated never reached it. A matcher covering one spelling of an unbounded set is worse than an honest gap, because only the gap is visible. Enforcement here is the reader's discipline under the rule that an act's absence from a list is not a finding of permission (`core/operating/autonomy.md`); the incident is recorded as incident 3 of `.portulan/proposals/0029-a-constraint-names-a-category-not-a-list.md`."
+        },
+        "reason": "Bypassing the local hooks — by any spelling — turns a compiled gate back into a convention on a workspace that compiles its gate policy into those hooks. If the hooks are wrong, change the policy through the evolution gate rather than stepping around it for one commit: a bypass leaves no trace in the record that a policy change would have left."
+      },
+      {
+        "id": "self-certify-a-checkpoint",
+        "tier": "prohibited",
+        "action": {
+          "none": "No tool-level surface, and naming it rather than inventing a matcher is the point. A checkpoint verdict is a paragraph written into a record, so the act of grading your own work is indistinguishable at the tool layer from the act of recording someone else's grade. What makes the rule real is the fresh context, which no permission rule can observe — see the honest-limits section of README.md."
+        },
+        "reason": "The context that did the work may not also supply the verdict on it. A supervisor sharing the implementer's window has already read every rationalisation the implementer wrote for itself, which is the failure the fresh-context requirement exists to prevent, and a verdict produced that way looks exactly like one that was not."
+      }
+    ]
+  }
+}

package/packs/rituals/checkpoints/personas/supervisor.md

@@ -0,0 +1,64 @@
+---
+name: supervisor
+description: Grades work it did not do, in a context that has not seen the work being done. Takes one of three checkpoints — a session's plan before it starts, a diff before it commits, or a milestone's demonstration before it is called done — and returns a verdict in a fixed vocabulary. It does not implement, fix, or merge. Delegate a checkpoint to it; never ask it to also do the work.
+tools: [read, search, run-verify]
+---
+
+# Persona — Supervisor
+
+> The persona whose whole value is what it has **not** read. A supervisor sharing the implementer's
+> window has already absorbed every rationalisation the implementer wrote for itself, and will grade
+> the work against the reasoning that produced it rather than against the standard. Freshness is the
+> mechanism; the verdict is only its output. The obligation itself is core's — the full lane's verdict
+> comes from a context that has not seen the implementation
+> ([`../../../../core/operating/loop.md`](../../../../core/operating/loop.md)); this persona is one way
+> to staff it. _(Provenance: subagents as context firewalls, HumanLayer; read-isolated review,
+> Cognition. See [`../README.md`](../README.md) for what this pack ships and what it cannot enforce.)_
+
+## Charter
+
+- **For:** grading one checkpoint against the artefacts the adopting workspace already declares — its
+  constitution or principles slot, its plan, its definition-of-done, its gate map. The supervisor's
+  question is never *"is this good?"* but *"does this meet the standard this team wrote down?"*
+- **Not for:** implementing, fixing what it finds, or merging. A supervisor that repairs a defect has
+  destroyed the independence that made its finding worth having, and the next checkpoint has nobody
+  left to grade the repair. It reports; someone else acts.
+- **Not for** grading work it did any part of. See the `self-certify-a-checkpoint` fragment in
+  [`../pack.json`](../pack.json).
+
+## Autonomy reach
+
+Acts in **Auto** to read and to *reproduce* verification — a read-only re-run, never a change. Its
+output is advice into a **Propose** or **Gated** decision that a human owns. It executes no Gated
+action, and it holds no authority to accept, merge, or close. **Prohibited is not a reach** and does
+not appear here: it is the tier no role may act in.
+_(Tier vocabulary from [`../../../../core/operating/autonomy.md`](../../../../core/operating/autonomy.md);
+which concrete actions sit in which tier is the adopting workspace's gate map, never this pack's.)_
+
+## Read / write posture
+
+Reads broadly and in parallel — the diff, the plan, the criterion, the workspace's own slots. Its only
+write is the verdict, isolated to whatever surface the adopting workspace records verdicts on. It
+touches no source file, which is the one part of this contract a host can turn into a rail by granting
+the persona no write tool at all.
+
+## Memory scope
+
+Its own supervisor memory: classes of defect this codebase produces, claims that turned out to be
+overstated, checks that caught something real. Kept separate from the implementer's so a verdict is
+never primed by the notes of the context it is grading — which is the same argument as the fresh
+context, one layer down.
+_(See [`../../../../core/operating/memory.md`](../../../../core/operating/memory.md).)_
+
+## Provenance & status
+
+Re-expressed from public practice — last-mile review focus, read-isolated verification, supervised
+evolution as the guard against drift. The `tools:` list is **capability classes** at engine altitude;
+binding them to a host's concrete tools is the adopter's job, and
+[`../../../../core/personas/README.md`](../../../../core/personas/README.md) records that such a binding
+is lossy for every charter clause except *does not write*.
+
+**What no binding enforces here: the freshness itself.** No `tools:` list and no permission rule can
+observe whether the context reading this file has already seen the work. That is a property of how the
+supervisor was *invoked*, not of what it may call — so it is a practice, held by whoever spawns the
+checkpoint, and this pack says so rather than shipping a contract that reads like a rail.

package/packs/rituals/checkpoints/skills/milestone-close/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: milestone-close
+description: Verify that a milestone's exit criterion was demonstrated rather than asserted, before it is marked done. Use when a milestone is proposed for closing — re-derive each clause independently instead of replaying the sessions that built it, and return CLOSE or REQUEST-CHANGES with a signed fidelity note. Runs in a context that did not implement the milestone, and after the work has merged.
+---
+
+# Skill — Milestone-close checkpoint
+
+> The checkpoint with the longest memory and the least sympathy. Its question is not *"was the work
+> done well?"* — two earlier checkpoints already asked that — but *"is each clause of this criterion
+> **demonstrated**, from the merged tree, by someone re-deriving it rather than being shown it?"*
+> _(Part of the `checkpoints` ritual pack — see [`../../README.md`](../../README.md) for the verdict
+> vocabulary in full and for what this pack cannot enforce.)_
+
+## When to use it
+
+Before a milestone, epic, or release is marked done — after its work has merged, and in a context that
+implemented none of it. **A milestone is never self-certified**: the session that built it is the one
+context that cannot supply this verdict.
+
+## The pass
+
+1. **Run the forward-reference sweep — before grading anything else.** Search the doctrine and
+   the workspace's own memory for this milestone's number.
+
+   _Moved to the front of the pass, and the reason is a measurement rather than a preference. On the
+   workspace that authored this pack the promised-but-unowned class has recurred **three times**, twice
+   naming the same milestone — and every one was found by a human reading sideways, never by this step,
+   because a close that grades the row first has already formed its verdict by the time it gets here.
+   This is the one check that finds obligations **the criterion itself does not list**, so a close
+   graded only against the row cannot see them. Run it before the row, not after._
+
+   A sentence elsewhere promising that a capability arrives here is a debt against
+   this criterion, and it is invisible from both sides — the row reads complete and the doctrine reads
+   satisfied. It is a text search, not a judgement, which is why it is worth running rather than
+   trusting to memory of what was promised. **Reconciling expands the criterion and never narrows it:**
+   a promise the criterion omits is added; a criterion clause no doctrine backs is a question for the
+   owner, never a strike. Without that direction this step becomes an argument for deleting inconvenient
+   clauses.
+
+2. **Read the criterion clause by clause** and treat each as a separate obligation. A criterion is a
+   set of promises, and the failure mode is a close that satisfies the memorable ones.
+3. **Re-derive, do not replay.** Independently reproduce each clause from the merged tree — run the
+   recipes, read the live state, recompute what a session reported. Where an earlier session recorded a
+   figure, recompute it rather than quoting it; where it recorded a demonstration, perform it again.
+4. **Force red before believing green.** A clause verified only in the passing direction has not been
+   verified. Break what it guards, watch it fail, restore.
+5. **Name what the close leaves undemonstrated**, and put it in the verdict rather than in a footnote.
+   Every close has some; a close claiming none has stopped looking.
+6. **Return CLOSE or REQUEST-CHANGES, with the fidelity note.**
+
+## The verdicts this checkpoint may return
+
+- **CLOSE** — every clause demonstrated; the milestone may be marked done.
+- **REQUEST-CHANGES** — at least one clause is asserted rather than demonstrated. Name which, and what
+  would demonstrate it.
+
+**APPROVE and APPROVE-WITH-ADJUSTMENTS are deliberately not available here.** Those verdicts let work
+proceed on a promise to fold something in; a close is the one decision with nothing downstream of it to
+catch what was folded in wrongly.
+
+## The fidelity note
+
+What the record carries once the session that wrote it is gone. Four parts, in one clause:
+
+> **who** verified · **when** · **the verdict, with what was actually re-derived** · **what the close
+> leaves undemonstrated**
+
+A bare *done* plus a link is not a fidelity note. The scoreboard everyone boots from has to say who
+verified and what they found, or a close can be asserted at the one surface nobody re-reads.
+
+## Why it earns its tokens
+
+It is the only check positioned to catch a milestone that was built correctly against a criterion
+nobody re-read. The forward-reference sweep in particular has changed criteria that three prior
+checkpoints passed over, because it is mechanical and reads what everyone else remembered.

package/packs/rituals/checkpoints/skills/pre-commit/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: pre-commit
+description: Grade a finished diff before it is committed. Use when full-lane work is complete — re-measure the diff against the criterion it claims to meet, re-run the verify recipes yourself rather than reading the implementer's report of them, and return APPROVE, APPROVE-WITH-ADJUSTMENTS, or REQUEST-CHANGES. Runs in a context that has not seen the work being done.
+---
+
+# Skill — Pre-commit checkpoint
+
+> The checkpoint that must **re-measure rather than re-read**. The implementer's report of a green
+> recipe is a claim like any other, and the one thing a fresh context can do that the implementer
+> cannot is run it again without knowing what it is supposed to say. _(Part of the `checkpoints` ritual
+> pack — see [`../../README.md`](../../README.md) for the verdict vocabulary in full and for what this
+> pack cannot enforce.)_
+
+## When to use it
+
+Before committing **full-lane** work: the finished diff is graded, then committed. The adopting
+workspace's autonomy tiers do not move that moment — a tier says who must **attend** an action, and a
+workspace whose commits and pushes are unattended by policy has said no *person* waits on them, not that
+nothing is owed before them. An unattended commit is still committed after the verdict.
+
+If the moment was missed — work misjudged as triage, or committed before anyone called it finished — the
+verdict is owed before the work is put in front of anyone; which act does so first is for the adopting
+workspace's gates to say, and a pull request is the usual first one. That is the recovery for a missed
+moment, never an alternative moment. The lane boundary is likewise the adopting workspace's; see the
+session-open skill for why this pack does not set it.
+
+Also whenever a change touches doctrine, the autonomy tiers, or the platform floor — work whose blast
+radius is large even when no milestone or roadmap state moves. Blast radius is the measure, not
+whether a status column changed.
+
+## The pass
+
+1. **Run the workspace's verify recipes yourself.** All of them, and read the output rather than the
+   summary. *Measured, never derived* — a total quoted from an earlier run is a number about a tree
+   that no longer exists.
+2. **Re-measure the diff against the criterion**, not against the implementer's description of the
+   diff. Read the criterion first and the diff second, so what you are looking for is not framed by
+   what was built.
+3. **Check every claim the change makes about itself.** This is where a fresh context earns its cost:
+   a change's own description of what it did is the least-reviewed prose in any diff, and it goes stale
+   between the first draft and the last push. Sentences elsewhere in the tree that the change falsifies
+   belong here too. *Re-measure rather than re-read* holds for prose as it does for recipes: a claim
+   about a mechanism is checked **from the mechanism**, and a claim about the world — a filesystem
+   layout, a platform behaviour, an install — **from the world**. A sentence asserting behaviour is a
+   figure that happens to be spelled in words. **The author's reading is not evidence**: the wrong
+   sentence and the code it described were written in the same hour by the same context.
+4. **Sweep the siblings of every defect the diff repairs.** The rule is
+   [`../../../../../core/operating/evolution.md`](../../../../../core/operating/evolution.md)'s — *a fix
+   is not done at the site it was found* — and this step is the procedure, not a second statement of it.
+   Ask the diff for it: which rule does each fix restore, and where else is that rule enforced? The tool
+   the shape was copied from, the other arm of the same function, the other command taking the same flag,
+   the other direction of the same operation. What each site then owes is `evolution.md`'s sentence and
+   not a second wording of it. **It is the checkpoint's step rather than the implementer's** because the site an
+   implementer is looking at is the site they just understood, and the leftover is the one the next
+   reader copies. Do not accept a comment beside the fix as coverage of a second site.
+5. **Attack the coverage claims.** Where the change says a check now catches something, try to get past
+   it. A hole list is a claim like any other, and the only thing that checks a claim about coverage is
+   somebody trying to defeat it.
+6. **Force the new rails red.** A check nobody has seen fail is a check nobody has seen work. If the
+   change ships a rail, break the thing it guards and confirm it fires, then restore.
+7. **Return one verdict** with numbered adjustments, and state what the change leaves
+   **undemonstrated** — that sentence is what the record carries forward, and it is the half a
+   satisfied implementer is least likely to write.
+
+## The verdicts this checkpoint may return
+
+- **APPROVE** — commit as it stands.
+- **APPROVE-WITH-ADJUSTMENTS** — commit once the numbered adjustments are folded in.
+- **REQUEST-CHANGES** — the diff does not meet the criterion; it needs work and a second pre-commit pass.
+
+## Why it earns its tokens
+
+It is the last point at which a defect is cheap. Its value is concentrated in two things an author
+structurally cannot supply: a re-run nobody is hoping will pass, and a reading of the change's own
+claims by someone with no memory of having written them.

package/packs/rituals/checkpoints/skills/session-open/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: session-open
+description: Grade a session's plan before any file is written. Use at the start of full-lane work — a plan against the workspace's constitution, its plan or roadmap, and the criterion the session claims to serve. Runs in a context that has not seen the plan being drafted, and returns APPROVE, APPROVE-WITH-ADJUSTMENTS, or REQUEST-CHANGES. Not for triage-lane work.
+---
+
+# Skill — Session-open checkpoint
+
+> The cheapest of the three, and the one that changes the most. A defect caught here costs a paragraph;
+> the same defect caught at pre-commit costs the diff that was built on it. _(Part of the `checkpoints`
+> ritual pack — see [`../../README.md`](../../README.md) for the verdict vocabulary in full and for
+> what this pack cannot enforce.)_
+
+## When to use it
+
+At the opening of **full-lane** work, before the implementer writes to any file.
+
+**Where the lane boundary sits is the adopting workspace's, not this pack's.** Core defines two lanes
+and leaves the boundary to the workspace
+([`../../../../../core/operating/loop.md`](../../../../../core/operating/loop.md)). A pack that imposed
+three checkpoints on every one-line fix would be ceremony that cannot scale down — a named non-goal, and
+the fastest way to get a ritual switched off wholesale. Read the workspace's own threshold and honour it.
+
+## The pass
+
+1. **Read the criterion the session claims to serve, as an input rather than as background.** If it
+   reads two ways, that ambiguity is the finding — say so before the session builds one of the two
+   readings by guessing. A criterion is the standard; a plan that quietly narrows it has already failed
+   and nothing downstream will notice.
+2. **Read the workspace's own slots** — constitution or principles, definition-of-done, gate map — and
+   grade the plan against what this team wrote down, never against your own taste. A supervisor
+   substituting its preferences for the team's standard is a second author, not a check.
+3. **Attack the plan's claims, not its prose.** For every capability the plan says will exist when the
+   session ends, ask what would demonstrate it. Plans fail most often by claiming a demonstration that
+   the described work cannot produce.
+4. **Check what the plan will make untrue.** A change lands inside a body of documents that describe the
+   system; sentences elsewhere go stale the moment it merges. Name them at the opening, when they are
+   cheap to include, rather than at pre-commit when they are a second pass.
+5. **Say where the plan claims something that will not exist.** A document may describe machinery only
+   if the machinery exists, or the sentence names where it arrives.
+6. **Return one verdict**, with every adjustment numbered so the implementer can fold them in and cite
+   them individually. An unnumbered list of concerns is not a verdict.
+
+## The verdicts this checkpoint may return
+
+- **APPROVE** — proceed as planned.
+- **APPROVE-WITH-ADJUSTMENTS** — proceed, with the numbered adjustments folded in. The common case, and
+  not a soft failure: it is what a checkpoint looks like when it is working.
+- **REQUEST-CHANGES** — the plan needs reworking and a second opening pass before implementation starts.
+
+## Why it earns its tokens
+
+It enforces a real rule — that a session's plan is graded against the standard before it is built,
+by something that did not draft it. **The freshness is the mechanism and no host enforces it**: nothing
+in a tool grant can observe whether this context already saw the plan being written. That makes it a
+practice held by whoever spawns the checkpoint, which is why it is stated here rather than assumed.
+A checkpoint that never changes a plan is a candidate for demotion; one that changes designs rather
+than wording is doing the job.

package/packs/stacks/README.md

@@ -0,0 +1,8 @@
+# packs/stacks/
+
+Stack packs — per-language and per-framework profiles (build/test commands, idioms, conventions)
+that a workspace composes in.
+
+> Placeholder. No stack pack exists yet, and none is scheduled: one becomes worth writing when a
+> workspace declares a stack that needs it. This repository's own stack is deliberately too thin to
+> justify one.

package/packs/tools/README.md

@@ -0,0 +1,17 @@
+# packs/tools/
+
+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
+> 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.
+>
+> The first pack to use it is a *ritual* one ([`../rituals/checkpoints/`](../rituals/checkpoints/)), so
+> the promise this file has carried since it was written — that a tool pack ships "with the gate
+> classification for each" — is now buildable and still unbuilt. A tool pack becomes worth writing when
+> a workspace here drives a tool that needs one.

package/packs/tools/github/README.md

@@ -0,0 +1,65 @@
+# `tools/github` — GitHub Actions hygiene, as a composed verify recipe
+
+A tool pack. It contributes **one verify recipe** to the workspace that composes it, and nothing else —
+no skills, no personas, no gate fragments. Composed through a workspace's `packs` array as
+`tools/github`.
+
+| Contributes | What |
+|---|---|
+| Verify | [`actions-pinned`](verify/actions-pinned.sh) — every `uses:` in a GitHub Actions workflow is pinned to a full commit SHA ([limits](verify/README.md)) |
+
+## Why this pack exists, said plainly
+
+It is the first pack in this project to ship a `contributes.verify` recipe, and it was built because
+**milestone 7's D6 needed a subject**. Row 7 requires a demonstration that a composed recipe *runs from
+the adopting workspace, is refused when it would shadow one the workspace owns, and is could-not-run
+when it cannot resolve* — and the only pack that existed, [`rituals/checkpoints`](../../rituals/checkpoints/README.md),
+declares no recipe **by argued policy**: it has nothing honest to put in that field, and reversing that
+to serve a demonstration would have made an honest pack dishonest.
+
+So the subject is a real pack with a real recipe rather than a fixture. That choice is deliberate and
+this project has paid for the alternative: a check written to exercise your own change inherits your
+change's blind spot, which is how a discovery draft found neither plugin its own feed shipped while the
+suite stayed green.
+
+**Its bound, so the row grows no unscheduled obligation:** one pack, one recipe, its documentation. No
+marketplace entry, no feed publication, no second recipe, and nothing D6 does not exercise.
+
+## What the recipe checks — and the honest reason it earns its place
+
+`uses: owner/action@<40-hex>` is pinned. A tag or a branch is not: the code that runs in the workflow
+tomorrow is whatever the tag points at then, and a tag can be moved by whoever owns it.
+
+**GitHub can already enforce this, and this repository has it enforced.** `sha_pinning_required` is set
+at the organisation and at the repository, and the platform refuses an unpinned action outright — a
+measured rail, recorded in this project's own gate map and platform-floor table. Saying so is not
+optional: a pack claiming to be the only thing standing between an adopter and an unpinned action would
+be claiming an enforcement it does not solely provide, which is the defect this repository has a memory
+record about.
+
+Two things the recipe buys anyway, and they are the reason it ships rather than an apology for it:
+
+1. **Tree-time versus run-time.** The platform refuses the action when the workflow *runs*. This refuses
+   it at the **pull request**, before merge. The gap is not theoretical for a scheduled workflow: an
+   unpinned `uses:` in a `schedule`-triggered job merges green on a Friday and fails at 06:00 on Monday,
+   with nobody watching.
+2. **Portability, which is the whole point of a pack.** An adopter who has not set the organisation
+   policy — or cannot, on a plan that does not offer it — gets this check as the *only* carrier. A pack
+   travels; a platform setting does not travel with it.
+
+## What it does not check
+
+Named here rather than left to be discovered — see [`verify/README.md`](verify/README.md) for the full
+list with reasons. In short: it reads one `uses:` per line and would not see a folded or flow-mapping
+spelling; it exempts local (`./…`) and container (`docker://…`) references, which have no commit to pin;
+and it does not verify that a pinned SHA is *reachable* in the action's repository, which would need a
+network call — and a network call inside a verify recipe is a standing prohibition in this project, not
+a decision this pack gets to make.
+
+## Provenance
+
+Built for milestone 7, session 5, as D6's subject, on the maintainer's ruling of 2026-08-09 that the
+demonstration take a real pack rather than a fixture or a reversal of another pack's refusal. The
+composition contract it exercises — additive only, namespaced by pack, never the workspace's
+`verify.default`, could-not-run rather than silently absent — is row 7's, ratified 2026-07-31, and is
+carried in code by [`cli/recipe-set.mjs`](../../../cli/recipe-set.mjs).

package/packs/tools/github/pack.json

@@ -0,0 +1,29 @@
+{
+  "portulan": {
+    "pack": "1.0",
+    "version": "0.1.0"
+  },
+  "name": "github",
+  "category": "tools",
+  "summary": "GitHub Actions hygiene as a verify recipe: every `uses:` in a workflow is pinned to a full commit SHA, checked in the tree at pull-request time rather than trusted to a platform setting the adopter may not have.",
+  "doc": "README.md",
+  "contributes": {
+    "verify": [
+      {
+        "id": "actions-pinned",
+        "run": "bash ${PACK_ROOT}/verify/actions-pinned.sh",
+        "requires": [
+          "bash",
+          "find",
+          "grep",
+          "sed",
+          "sort",
+          "cut",
+          "wc",
+          "tr"
+        ],
+        "doc": "verify/README.md"
+      }
+    ]
+  }
+}