@sleepy_panda_srl/portulan 0.4.0 → 0.4.1

package/README.md

@@ -20,13 +20,13 @@ workspaces and premium packs delivered as private-marketplace plugins.
 
 ## Status
 
-**Current release: `0.4.0`** — recorded in [`CHANGELOG.md`](CHANGELOG.md), which is also the honest
+**Current release: `0.4.1`** — recorded in [`CHANGELOG.md`](CHANGELOG.md), which is also the honest
 account of what the release does *not* contain.
 
 This is pre-release software. The leading `0.` is meant literally: nothing here is stable yet, and
 the surface may change between minor versions. What is authored today is the engine in [`core/`](core/),
 the Workspace Definition in [`spec/`](spec/), two complete workspaces, the CLI in [`cli/`](cli/) with
-all eight subcommands, the enforcement compiler, the memory lifecycle and the plugin packaging. The remaining directories
+every subcommand, the enforcement compiler, the memory lifecycle and the plugin packaging. The remaining directories
 fill in milestone by milestone; [`docs/plan.md`](docs/plan.md) is the living map of that work.
 
 The repository is **public** — reading, cloning, forking and installing the plugin need no account of
@@ -131,8 +131,9 @@ commit, refusing any packed file that differs from its source.
 | [`upgrade`](cli/upgrade.mjs) | Migrate a workspace across Workspace Definition versions |
 | [`new`](cli/new.mjs) | Scaffold a skill, persona, pack, workspace, gate policy or repo card |
 | [`feedback`](cli/feedback.mjs) | File a bug, improvement or feedback issue you previewed first |
+| [`finish`](cli/finish.mjs) | Close a change in one call: commit and push only when every verify recipe passes |
 
-Beside the eight sit tools that are deliberately not subcommands, and the compiled-hook runners, which
+Beside these sit tools that are deliberately not subcommands, and the compiled-hook runners, which
 are not subcommands at all. [`cli/README.md`](cli/README.md), rendered from the code, lists that wider roster.
 
 ## Repository layout

package/cli/README.md

@@ -29,6 +29,7 @@ in [`../.portulan/verify/`](../.portulan/verify/), and its operator tooling in
 | [`upgrade.mjs`](upgrade.mjs) | `portulan upgrade`: migrate a workspace: the Workspace Definition steps it owes, and the repairs a rewriter owes it. |
 | [`new.mjs`](new.mjs) | `portulan new`: scaffold a skill, persona, pack, workspace, gate policy or repo card from a core template. |
 | [`feedback.mjs`](feedback.mjs) | `portulan feedback`: file an issue from a report you previewed, seam-scanned before it leaves the machine. |
+| [`finish.mjs`](finish.mjs) | `portulan finish`: close a change in one call, committing and pushing only when every verify recipe passes. |
 
 ### Hook runners
 
@@ -58,7 +59,6 @@ Run as `node cli/<file>.mjs`, or imported by the files above.
 | [`discover.mjs`](discover.mjs) | Host plugin-cache discovery: reads a host's installed-plugin record to resolve a pointer and find pack roots. |
 | [`drills.mjs`](drills.mjs) | The forced-red drill harness — every rail broken on purpose, and required to fire. |
 | [`eval-bundle.mjs`](eval-bundle.mjs) | Cut a named-recipient evaluation bundle of Portulan from a commit. Not shipped. |
-| [`finish.mjs`](finish.mjs) | The finishing command — one call closes a change: its recipes, its changelog fragment, its commit, its push. |
 | [`form.mjs`](form.mjs) | `form` — which form a consumer's records and boot are in, and the files that move them to the new one. |
 | [`frontmatter.mjs`](frontmatter.mjs) | Flat frontmatter for plugin components and host bindings. |
 | [`fuzz-shell.mjs`](fuzz-shell.mjs) | Grammar-aware fuzzing over this repository's two shell segmenters. |

package/cli/drills.mjs

@@ -271,7 +271,7 @@ export const DRILLS = [
         rail: "pack-identity",
         perturb: {
             file: "README.md",
-            find: "**Current release: `0.4.0`**",
+            find: "**Current release: `0.4.1`**",
             replace: "**Current release: `0.1.3`** <!-- the drill edited this and did not stage it -->",
         },
         stage: false,
@@ -355,7 +355,7 @@ export const DRILLS = [
         rail: "version-carriers",
         perturb: {
             file: "README.md",
-            find: "**Current release: `0.4.0`**",
+            find: "**Current release: `0.4.1`**",
             replace: "**Current release: `0.1.3`**",
         },
         // Staged: this rail reads the index (`git show :<path>`), so an unstaged edit is invisible to it.

package/cli/finish.mjs

@@ -28,6 +28,7 @@ const GIT_TIMEOUT_MS = 2 * 60 * 1000;
 const USAGE = [
     "usage: node cli/finish.mjs -m <subject> [-m <paragraph>]... [options]",
     "       node cli/finish.mjs -F <file | -> [options]",
+    "       portulan finish <the same arguments>, where the package is installed",
     "",
     "  -m <text>            a paragraph of the commit message, the first its subject, as git takes -m",
     "  -F <file | ->        the whole commit message, from a file or from standard input",

package/cli/form.mjs

@@ -543,7 +543,7 @@ export function draftCard(manifest, read, { workspace, inTree, repoCards = [] })
     }
     section(
         "Records",
-        'Close a change with `git add <new files> && node <plugin root>/cli/finish.mjs -m "<subject>" -m "<why>"` after writing its changelog entry, a one-bullet file `changes/<slug>.<section>.md`: it commits and pushes only when every verify recipe passes.',
+        'Close a change with `git add <new files> && portulan finish -m "<subject>" -m "<why>"` after writing its changelog entry, a one-bullet file `changes/<slug>.<section>.md`: it commits and pushes only when every verify recipe passes. Where `portulan` is not on the path, run `npx @sleepy_panda_srl/portulan finish` instead, and do not search the disk for it.',
         ...(slots.handoffs ? [`A session ending with work not committed and pushed leaves a dated handoff in ${shown(slots.handoffs)}.`] : []),
     );
     section(

package/cli/portulan.mjs

@@ -55,6 +55,11 @@ export const SUBCOMMANDS = [
         module: "feedback.mjs",
         summary: "file an issue from a report you previewed, seam-scanned before it leaves the machine",
     },
+    {
+        name: "finish",
+        module: "finish.mjs",
+        summary: "close a change in one call, committing and pushing only when every verify recipe passes",
+    },
 ];
 
 export function find(name) {
@@ -77,8 +82,8 @@ export function usage() {
         "",
         "Exit codes: 0 succeeded · 1 a red verdict · 2 could not run.",
         "",
-        "Other tools live in cli/ and are deliberately not here — docs/vision.md names these eight",
-        "subcommands and is human-owned, so a ninth is the maintainer's call. cli/README.md lists them.",
+        "Other tools live in cli/ and are deliberately not here — docs/vision.md names these subcommands",
+        "and is human-owned, so another is the maintainer's call. cli/README.md lists them.",
     );
     return lines.join("\n");
 }

package/cli/vendor.mjs

@@ -540,7 +540,9 @@ export function agentsMd(manifest, host, kernel = null, guidance = null) {
         "- **A resolved pointer.** Nothing here fetches anything.",
         ...(cardText?.includes("<plugin root>")
             ? ["- **The Portulan package.** The card's `<plugin root>` is where it is installed, which this copy is not."]
-            : []),
+            : cardText?.includes("portulan finish")
+              ? ["- **The Portulan package.** The card's `portulan finish` runs from it, and this copy does not carry it."]
+              : []),
         "",
         "Run `portulan doctor .portulan` to see where this stands.",
         "",

package/evals/releases/0.4.1.json

@@ -0,0 +1,154 @@
+{
+    "portulan": {
+        "releaseEval": "1"
+    },
+    "version": "0.4.1",
+    "captured": "2026-11-11",
+    "source": {
+        "commit": "a83966a56af78bd76a63c48afdce457aa3c5b0d5",
+        "clean": true
+    },
+    "host": {
+        "node": "v26.13.0",
+        "platform": "darwin"
+    },
+    "recipes": [
+        {
+            "id": "cache-stability",
+            "exit": 0
+        },
+        {
+            "id": "docs",
+            "exit": 0
+        },
+        {
+            "id": "json",
+            "exit": 0
+        },
+        {
+            "id": "doctor",
+            "exit": 0
+        },
+        {
+            "id": "tests",
+            "exit": 0
+        },
+        {
+            "id": "plugin",
+            "exit": 0
+        },
+        {
+            "id": "compile",
+            "exit": 0
+        },
+        {
+            "id": "workflow-filters",
+            "exit": 0
+        },
+        {
+            "id": "index",
+            "exit": 0
+        },
+        {
+            "id": "context",
+            "exit": 0
+        },
+        {
+            "id": "ledger",
+            "exit": 0
+        },
+        {
+            "id": "control-chars",
+            "exit": 0
+        },
+        {
+            "id": "comments",
+            "exit": 0
+        },
+        {
+            "id": "rule-carriers",
+            "exit": 0
+        },
+        {
+            "id": "pack-version",
+            "exit": 0
+        },
+        {
+            "id": "pack-identity",
+            "exit": 0
+        },
+        {
+            "id": "payload",
+            "exit": 0
+        },
+        {
+            "id": "eval-bundle",
+            "exit": 0
+        },
+        {
+            "id": "goldens",
+            "exit": 0
+        },
+        {
+            "id": "mutants",
+            "exit": 0
+        },
+        {
+            "id": "fuzz-shell",
+            "exit": 0
+        },
+        {
+            "id": "version-carriers",
+            "exit": 0
+        },
+        {
+            "id": "skill-goldens",
+            "exit": 0
+        },
+        {
+            "id": "review-loop",
+            "exit": 0
+        },
+        {
+            "id": "telemetry",
+            "exit": 0
+        },
+        {
+            "id": "drills",
+            "exit": 0
+        },
+        {
+            "id": "ab",
+            "exit": 0
+        },
+        {
+            "id": "ab-grade",
+            "exit": 0
+        },
+        {
+            "id": "ab-run",
+            "exit": 0
+        },
+        {
+            "id": "tools/github:actions-pinned",
+            "exit": 0
+        },
+        {
+            "id": "tools/local-llm:runner-rails",
+            "exit": 0
+        }
+    ],
+    "excluded": [
+        {
+            "id": "release-eval",
+            "why": "a capture cannot be accurate about the record it is inside — captured before the record is written it is red for the record's absence, and captured after it is stale the moment the register is rendered. Its verdict for this release is the rail's own run on the pull request carrying this file."
+        }
+    ],
+    "abBaseline": {
+        "snapshot": "evals/ab/baseline.json",
+        "register": "evals/ab/baseline.md",
+        "captured": "2026-08-31T09:05:32.699Z",
+        "commit": "a642d551eec6c146c67ef0acfe3f8ba535c5ce6e",
+        "clean": false
+    }
+}

package/evals/releases/0.4.1.md

@@ -0,0 +1,69 @@
+# Eval result — Portulan 0.4.1
+
+> **Generated. Do not edit.** Rendered from [`evals/releases/0.4.1.json`](0.4.1.json) by [`cli/release-eval.mjs`](../../cli/release-eval.mjs) and byte-compared by the `release-eval` verify recipe. This is the eval result milestone 8 requires a release to carry — `docs/plan.md`, Protocol → Versioning.
+
+## What this release was measured at
+
+| | |
+|---|---|
+| Version | `0.4.1` |
+| Captured | 2026-11-11 |
+| Commit | `a83966a56af78bd76a63c48afdce457aa3c5b0d5` |
+| Tree at capture | clean |
+| Node | `v26.13.0` |
+| Platform | `darwin` |
+
+## The rails, and what each returned
+
+31 of the 32 recipes this workspace yielded at capture. The set is derived from [`cli/recipe-set.mjs`](../../cli/recipe-set.mjs) and never listed by hand.
+
+| Recipe | Verdict |
+|---|---|
+| `cache-stability` | green |
+| `docs` | green |
+| `json` | green |
+| `doctor` | green |
+| `tests` | green |
+| `plugin` | green |
+| `compile` | green |
+| `workflow-filters` | green |
+| `index` | green |
+| `context` | green |
+| `ledger` | green |
+| `control-chars` | green |
+| `comments` | green |
+| `rule-carriers` | green |
+| `pack-version` | green |
+| `pack-identity` | green |
+| `payload` | green |
+| `eval-bundle` | green |
+| `goldens` | green |
+| `mutants` | green |
+| `fuzz-shell` | green |
+| `version-carriers` | green |
+| `skill-goldens` | green |
+| `review-loop` | green |
+| `telemetry` | green |
+| `drills` | green |
+| `ab` | green |
+| `ab-grade` | green |
+| `ab-run` | green |
+| `tools/github:actions-pinned` | green |
+| `tools/local-llm:runner-rails` | green |
+
+**`release-eval` is excluded**, and the reason is printed rather than the row silently dropped: a capture cannot be accurate about the record it is inside — captured before the record is written it is red for the record's absence, and captured after it is stale the moment the register is rendered. Its verdict for this release is the rail's own run on the pull request carrying this file.
+
+## The A/B baseline this release ships against
+
+[`evals/ab/baseline.md`](https://github.com/sleepy-panda-srl/portulan/blob/v0.4.1/evals/ab/baseline.md), rendered from `evals/ab/baseline.json` — captured 2026-08-31T09:05:32.699Z at `a642d551eec6c146c67ef0acfe3f8ba535c5ce6e`, over a tree that was **not clean**.
+
+**Its figures are not repeated here.** They have one carrier and this is not it.
+
+## What this record does not establish
+
+- **A green says this record agrees with its own capture — never that the release is good.** Every line below is what the recipes returned at one commit, and a recipe's own green establishes only what that recipe's documentation says it establishes.
+- **The recipes were not run at the tag.** They ran at `a83966a56af78bd76a63c48afdce457aa3c5b0d5`, and this record is committed *in* the cut change — so the tagged tree is this commit plus whatever that change still adds after the capture, the record itself at minimum. A record cannot be captured at a commit that does not exist yet, and printing the one it was captured at is the only honest form.
+- **`release-eval` is excluded from the rows above**, because a capture cannot be accurate about the record it is inside. Its verdict for this release is the rail's own run on the pull request that carries this file.
+- **This record measures the Portulan repository's own build**, at the commit named above — never the workspace, project or package this release is installed into. Nothing here has looked at your tree.
+- **The tree was clean at capture**, so the commit named above is what was measured.
+- **The A/B baseline's figures are NOT restated here.** This record names which baseline the release ships against; the figures and everything that may not be concluded from them live in that register alone.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleepy_panda_srl/portulan",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "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",