wowbagger 0.1.0-alpha.2 → 0.1.0-alpha.4

package/CHANGELOG.md

@@ -7,6 +7,35 @@ consolidation. The first tagged release inherits this file.
 
 ## Unreleased
 
+## 0.1.0-alpha.4 - 2026-08-14
+
+### Added
+
+- `report` validates a ledger and atomically writes a deterministic,
+  self-contained HTML report from `.wowbagger/report.json`. The report includes
+  canonical readiness, semantic-field search, filters, sorting, grouping,
+  three detail levels, terminal history, and optional area-diverse swarm
+  batches. This repository includes a local report configuration and ignores
+  the generated artifact.
+
+### Fixed
+
+- The Claude Code adapter now declares Darwin `supported`. Native Darwin
+  conformance passes all 183 common-vector assertions across all 15 cases, so
+  configured consumer workspaces can invoke the published adapter read path.
+
+## 0.1.0-alpha.3 - 2026-08-12
+
+### Fixed
+
+- Published install and upgrade guidance now names this release's immutable Git
+  tag and uses the prerelease `next` npm channel instead of the older `latest`
+  artifact. Item 62.
+- The installed plugin skill now requires the exact core distribution version
+  that shipped with it, in addition to core contract version 2. This detects an
+  older core that shares the contract number but lacks behavior required by the
+  newer skill. Item 64; item 63 records the rejected capability-schema change.
+
 ## 0.1.0-alpha.2 - 2026-08-12
 
 ### Fixed

package/README.md

@@ -14,13 +14,15 @@ putting a database or hosted service inside your repository.
 > scope is deliberately narrow: cooperative writers in one working copy, one
 > item at a time. A Claude Code adapter and plugin ship from this
 > repository; the adapter answers the negotiation surface of the harness-neutral
-> contract and passes all 183 assertions across all 15 cases on native Darwin,
-> although no manifest platform is claimed `supported` yet. The shipped core
-> mutation contract and adapter contract are version 2; their frozen version 1
-> definitions are not silently negotiated.
+> contract and passes all 183 assertions across all 15 cases on native Darwin.
+> The Claude Code adapter declares Darwin `supported`; all other shipped adapter
+> platform declarations remain `unverified`. The shipped core mutation contract
+> and adapter contract are version 2; their frozen version 1 definitions are not
+> silently negotiated.
 >
-> On Git-backed ledgers, work claims coordinate cooperating agents through a
-> durable journal in Git's shared common directory. `claim acquire` uses
+> A work claim is not a lock or an exclusive dispatch lease. On Git-backed
+> ledgers, claims coordinate cooperating agents through a durable journal in
+> Git's shared common directory. `claim acquire` uses
 > observed-state compare-and-swap. `publish-claimed` fences one item against
 > the active owner generation and expected revision. `claim-verify` reconciles
 > response-loss and post-merge outcomes. This is **merge-coordinated**, not
@@ -34,7 +36,7 @@ Install the core CLI, then verify it:
 ```sh
 npm install -g wowbagger@next   # public npm prerelease
 # or, from this release's Git tag:
-# npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.1
+# npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.4
 wowbagger capabilities --json
 ```
 
@@ -45,11 +47,12 @@ In Claude Code, add the plugin:
 /plugin install wowbagger@wowbagger
 ```
 
-The plugin drives the installed core rather than bundling one, so a version
-mismatch is detectable instead of silent: it reads `contract_version` from
-`capabilities` and refuses when the core is absent or reports anything it does
-not support. It will not fall back to editing ledger files by hand, because that
-would bypass validation and atomic publication.
+The plugin drives the installed core rather than bundling one, so a mismatch is
+detectable instead of silent. Its skill reads `wowbagger --version` and
+`capabilities`; it requires the same distribution version as the plugin and
+core contract version 2. It refuses an absent or incompatible core. It will not
+fall back to editing ledger files by hand, because that would bypass validation
+and atomic publication.
 
 For an isolated consumer pilot, create or select the disposable worktree before
 the agent starts. Then launch a new session with that worktree as its project
@@ -69,29 +72,30 @@ two supported install routes:
 - **npm registry** — `npm install -g wowbagger@next` installs the current
   prerelease.
 - **git tag** —
-  `npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.1` installs this
+  `npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.4` installs this
   release. Installing at a ref installs the core and every adapter that ref
   carries.
 
 Either route installs the core and the `wowbagger` command. The Claude Code
 plugin is a separate artifact (see [Start here](#start-here)); the core and the
-plugin are installed and versioned independently, and a mismatch is refused by
-`contract_version` rather than guessed.
+plugin are installed independently. Install their matching distribution
+versions.
 
 ### Compatibility
 
-The behavioural version is `contract_version`, reported by
+The contract version is top-level `contract_version`, reported by
 `wowbagger capabilities --json`. Contracts change it; refactors do not. The
-distribution version is the npm/git version, which names bytes, not behaviour.
-Match on `contract_version` — never on the package version — when you decide
-whether a core supports your request.
+npm/Git distribution version names release bytes. General API consumers
+negotiate the contract version. The shipped plugin skill additionally requires
+the exact core distribution version that shipped with it, because its
+instructions can depend on additive behavior from that release.
 
 - **Node.js:** 20 and later. The adapter conformance vectors run against Node
   20 and the current runtime before each release.
-- **Platforms:** the core runs wherever Node.js runs, but a formal `supported`
-  platform claim is still `unverified` (they become verified per-platform only
-  with release evidence). Do not assume a platform is officially supported just
-  because the CLI starts.
+- **Platforms:** the core runs wherever Node.js runs. The Claude Code adapter
+  declares Darwin `supported` from native common-vector evidence. Linux,
+  Windows, and the other shipped adapter targets remain `unverified`; do not
+  infer support only because the CLI starts.
 - **Other tooling:** `wowbagger` manages a Git-tracked Markdown ledger. It
   needs an accessible Git checkout for work-claim and namespace operations.
   Before `provision`, run
@@ -131,8 +135,8 @@ wowbagger core, this is how you move forward safely.
 Upgrade the pieces you installed:
 
 ```sh
-npm install -g wowbagger@latest                # public npm registry
-npm install -g github:lstutzman/wowbagger      # or: a direct git-tag install
+npm install -g wowbagger@next                  # public npm registry
+npm install -g github:lstutzman/wowbagger#v0.1.0-alpha.4  # immutable Git release
 git pull && npm ci                            # or: a direct checkout
 ```
 
@@ -143,15 +147,15 @@ In Claude Code, update the plugin the same way it was installed:
 /plugin update wowbagger@wowbagger
 ```
 
-Then verify, exactly as on first install:
-
 ```sh
+wowbagger --version
 wowbagger capabilities --json
 ```
 
-The top-level `contract_version` is the core compatibility gate. The plugin
-and adapter refuse a core that reports a version they do not support; if you
-automate against the core directly, do the same rather than guessing.
+The plugin requires its exact core distribution version and top-level core
+`contract_version: 2`. Direct API consumers must check the contract version
+they support; installed plugin users must also keep the plugin and core
+distribution versions equal.
 
 The shipped adapter selects only adapter contract version 2 and requires core
 contract version 2. A v1-only consumer receives
@@ -275,6 +279,7 @@ npm ci
 ./bin/wowbagger.js validate --ledger path/to/ledger --json
 ./bin/wowbagger.js ready --ledger path/to/ledger --as-of 2030-01-15 --json
 ./bin/wowbagger.js ready --ledger path/to/ledger --as-of 2030-01-15
+./bin/wowbagger.js report --ledger path/to/ledger --as-of 2030-01-15 --json
 ./bin/wowbagger.js capabilities --json
 ./bin/wowbagger.js mint-id --json
 ./bin/wowbagger.js inspect --ledger path/to/ledger --id wb_... --json
@@ -314,6 +319,39 @@ directories ending in `.md` remain containers and are traversed. These checks
 provide deterministic read hygiene; they are not a sandbox against a privileged
 process racing filesystem changes.
 
+`report` validates the complete ledger, reads `.wowbagger/report.json`, and
+atomically publishes one self-contained HTML file. The output must be outside
+the ledger. Relative configured output paths resolve from `.wowbagger/`;
+relative `--out` overrides resolve from the caller's working directory.
+
+```json
+{
+  "report_version": 1,
+  "repository": { "name": "Example repository", "logo": "logo.svg" },
+  "title": "Ledger report",
+  "output": "../../ledger-report.html",
+  "fields": {
+    "area": "/priority_area",
+    "complexity": "/complexity",
+    "rank": "/priority_rank"
+  },
+  "swarm": { "eligible_complexities": ["small", "medium"] }
+}
+```
+
+`repository.logo`, `fields`, and `swarm` are optional. Field values resolve
+from parsed frontmatter with RFC 6901 JSON Pointers. A swarm requires mapped
+`area` and `complexity` fields. The report shows canonical readiness, filters,
+sorting, grouping, three detail levels, terminal history, and area-diverse
+ready batches. It contains no external runtime dependency.
+
+This repository keeps its report configuration in
+`ledger/.wowbagger/report.json`. Generate the ignored local report with:
+
+```sh
+npm run report -- --as-of 2026-08-14
+```
+
 `inspect` returns a lossless raw-byte snapshot and its SHA-256 revision.
 `create` publishes only a caller-supplied canonical ID through atomic
 no-clobber publication — `mint-id` prints one, so no consumer writes base32
@@ -340,8 +378,9 @@ top-level `contract_version` from core `capabilities`. Read
 `result.operations.work_claim.api_version` from
 `claim capabilities --ledger <dir> --json`. A claim response's top-level
 `contract_version` is the legacy claim-envelope marker; do not compare it with
-the core version. A consumer that receives an unsupported version refuses
-rather than guessing. Direct checkout use—`./bin/wowbagger.js` from a
+the core version. A contract consumer that receives an unsupported version
+refuses rather than guessing. The shipped plugin skill also requires its exact
+core distribution version. Direct checkout use—`./bin/wowbagger.js` from a
 clone—remains supported and is what this repository's own ledger uses.
 
 ## Verify a checkout
@@ -446,9 +485,9 @@ It is the durable work ledger beneath those systems.
 - Separate optional reusable mechanisms from consumer-specific policy.
 - Stabilize the machine-readable command contract and compatibility evidence.
 - Ship Claude Code and Codex adapters. **Claude Code, Codex, and OpenCode
-  packages share the version 2 engine; the Claude Code Darwin target passes
-  all 183 assertions, while the other target reports and all manifest platform
-  declarations remain unverified.**
+  packages share the version 2 engine; the Claude Code manifest declares Darwin
+  `supported` after passing all 183 native assertions. Other adapter targets and
+  platform declarations remain unverified.**
 - Document the generic tool contract for other agent harnesses.
 - Implement merge-coordinated work claims for cooperating Git worktrees.
   **Implemented with durable claim operations, claim-protected single-item

package/adapters/claude-code/wowbagger-adapter.json

@@ -18,7 +18,7 @@
     }
   },
   "platforms": {
-    "darwin": "unverified",
+    "darwin": "supported",
     "linux": "unverified",
     "win32": "unverified"
   }