chore(release): promote codexclaw 0.2.28 to main

CHANGELOG.md

@@ -6,6 +6,51 @@ All notable changes to codexclaw are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.2.28] - 2026-09-14
+
+### Fixed
+
+- `cxc-loop` `references/durable-goalplan.md` documented mandatory goalplan
+  registration without documenting the command that performs it. `add-criterion`
+  was absent from the CLI surface list while the schema advertised `criteria[]`
+  field names, so the natural first call — `--id c1 --scenario ... --expected-evidence ...`
+  — failed with `--criterion "<scenario>" is required`, and `update_goal
+  {status:"complete"}` stayed hook-denied behind GOAL-COMPLETE-GATE-01. The real
+  signature is now listed (`--criterion <text> [--surface logic|web|tui]`), `init`
+  shows its repeatable `[--criterion <text>]...` form, and a duplicate scenario
+  text is documented as a rejection (#170).
+- Criterion ids are generated, not chosen. `meet-criterion --id <id>` read as if
+  the caller picks the id the way `add-work-phase --id wp1` does, so an agent that
+  assumed `c1` at registration would later record no evidence for a criterion it
+  believed it met. The reference now states that ids are assigned as `c-1`,
+  `c-2`, ... (max existing `c-N` + 1, in registration order) and are read back from
+  `cxc loop show` or the goalplan file. `criteria[]` also regains its missing
+  `surface` field, with per-field provenance: `scenario` and `surface` are
+  CLI-settable, `id` and `status` are derived, `expectedEvidence` has no
+  `add-criterion` flag, and `capturedEvidence` comes from `meet-criterion
+  --evidence` (#171).
+- DISPATCH-SURFACE-01 was correct in substance but ordered so that an orchestrator
+  over-rotated to threads for every unit of work. Four STRICT blocks pushed toward
+  threads while the correcting sentence — in-lane subagents cannot collide because
+  the worktrees differ — sat in the last paragraph of
+  `cxc-pabcd` `references/dispatch-surfaces.md`. The composition rule now sits
+  inside the invariant itself: a **lane** is thread work, a **worker inside a lane**
+  is subagent work. DISPATCH-ROUTE-01 gained the matching route line, `cxc-loop`
+  `SKILL.md` mirrors the clause, and `structure/20_pabcd_dispatch_doctrine.md`
+  gains the worker row in its translation table (#172).
+
+### Added
+
+- DELEGATE-MODEL-LIST-01 (STRICT) in `cxc-pabcd` `references/delegation.md`: the
+  model-override list advertised by the host `spawn_agent` description is a hint,
+  not an allowlist, and is known to be incomplete. A user-named model is passed
+  through as given; only a real spawn rejection is evidence of unavailability; a
+  genuine failure is reported rather than silently substituted. Measured
+  2026-09-14: `spawn_agent({ model: "devin/swe-2" })` spawned and ran to a final
+  message while the advertised list omitted that model, which had previously caused
+  a requested worker ratio to be re-planned around threads (#173).
+
+
 ## [0.2.27] - 2026-09-13
 
 ### Added

cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codexclaw/cli",
-  "version": "0.2.27",
+  "version": "0.2.28",
   "private": true,
   "type": "module",
   "description": "codexclaw CLI — status, subagent config, provider toggle, GUI launcher.",

devlog/_plan/260914_skill_doc_triage_release/000_plan.md

@@ -0,0 +1,68 @@
+# 000 — Ship the #170-#173 reference-doc fixes as codexclaw 0.2.28
+
+## Objective
+
+Take the four skill-reference fixes already green on PR #174 through the full
+promotion path — dev, then main, then a published Release — and close #170-#173.
+
+## Why this is a unit and not a fast-path record
+
+The code change itself is C1 (documentation only, no runtime behavior). The
+DELIVERY is not: it crosses two protected-ish integration lines, regenerates the
+release inventory, and ends in an irreversible publication whose gate fails closed.
+UNIT-RESIDENCE-01 applies to the release, and LOOP-DOCS-FIRST-01 is STRICT for a
+HOTL goal loop, so the roadmap is written to diff level before the first merge.
+
+## Constraints
+
+- User authorization (2026-09-14): run as cxc-loop, push dev, merge to main, and
+  deploy/release. Nothing wider.
+- No local product suite, typecheck, build or install. The only admissible proof is
+  hosted CI at the exact head SHA plus the Release workflow's own gate.
+- The release gate reads workflow conclusions BY SHA. A green run from a
+  neighbouring commit does not count.
+- Do not implement the #175 branch-deletion fix in this unit. Report only.
+
+## Starting state (measured 2026-09-14)
+
+| Fact | Value |
+|---|---|
+| PR #174 | base `dev`, head `7036f9b8`, MERGEABLE / CLEAN, 14/14 checks pass |
+| Version, every surface | `0.2.27` (manifest and inventory carry `+codex.20260913080217`) |
+| Measured suite, hosted | `tests 3150` — CI run 34790437740, job 103813520900 |
+| Published tests badge | `3,150` — already agrees, so the badge does not move |
+| `dev` | recreated this session at `main` tip `9e279a45` after it was deleted |
+| Open issues to close | #170, #171, #172, #173 |
+
+## Work-phase map
+
+| Phase | Deliverable | Doc | Depends on |
+|---|---|---|---|
+| wp1 | This roadmap, committed before any merge or version edit | `000` | — |
+| wp2 | #174 merged to `dev`; exact-SHA CI + WSL + Packed install green on the new `dev` head | `010` | wp1 |
+| wp3 | 0.2.28 prepared on `dev`: every version surface, CHANGELOG, regenerated inventory | `020` | wp2 |
+| wp4 | Promotion PR merged to `main`; Release workflow publishes v0.2.28; #170-#173 closed; `dev` restored | `030` | wp3 |
+
+## Release path (docs-site/src/content/docs/development/release.md)
+
+1. Land on `dev`, green on that exact commit.
+2. Bump every surface `check-versions.mjs` enumerates.
+3. Regenerate the inventory with the measured test count.
+4. Merge the `dev` -> `main` promotion PR.
+5. Run the Release workflow against `main`.
+
+## Known hazard carried through every phase
+
+`delete_branch_on_merge` is **true** on this repository, and `dev` is not
+protected. The promotion PR's head branch IS `dev`, so merging wp4 deletes `dev`
+immediately. This already happened once after PR #169 and is why `dev` was missing
+at the start of this session. wp4 therefore ends by recreating `dev` from `main`.
+Issue #175 tracks the permanent fix; it is out of scope here.
+
+## Terminal outcomes
+
+DONE requires all eight registered criteria met with proof captured this session.
+BLOCKED is a hosted check that fails and cannot be resolved in scope. NEEDS_HUMAN
+is a burned version tag or a gate demand outside the authorized scope. UNSAFE is
+any force-push of a shared branch or any fabricated receipt — never do either.
+

devlog/_plan/260914_skill_doc_triage_release/010_wp2_land_pr174_on_dev.md

@@ -0,0 +1,49 @@
+# 010 — wp2: land PR #174 on dev
+
+## Goal
+
+`dev` contains the four reference-doc fixes, and the resulting `dev` head SHA
+carries its own green CI, WSL and Packed install lifecycle conclusions.
+
+## Precondition
+
+PR #174 is MERGEABLE / CLEAN at head `7036f9b8` with 14/14 checks passing. Re-read
+it immediately before merging; do not trust the value recorded in `000`.
+
+## Action
+
+    gh pr merge 174 -R lidge-jun/codexclaw --merge
+
+Merge commit, not squash: the repository's integration history uses merge commits
+(`Merge pull request #169 from lidge-jun/dev`) and the promotion path reads that
+shape. `delete_branch_on_merge` removes the topic branch
+`codex/260914-skill-doc-triage-170-173` automatically, which is correct for a
+topic branch.
+
+## Why a separate CI generation is required
+
+The PR checks ran against `7036f9b8`. Merging produces a NEW commit on `dev`, and
+the release gate resolves conclusions by SHA. Workflow triggers:
+
+| Workflow | Runs on push to `dev` | Runs on PR |
+|---|---|---|
+| CI (`ci.yml`) | yes | yes |
+| WSL (`wsl.yml`) | yes | **no** |
+| Packed install (`packed-install.yml`) | yes | yes |
+
+WSL never ran for PR #174 by design, so the `dev` push is the FIRST evidence that
+lane produces for this change. It is also the longest lane at 13-14 minutes.
+
+## Verification
+
+    DEV_SHA=$(gh api repos/lidge-jun/codexclaw/commits/dev --jq .sha)
+    gh run list -R lidge-jun/codexclaw --commit "$DEV_SHA"
+
+Require conclusion `success` for CI, WSL and Packed install lifecycle at that SHA.
+Record the SHA and the run ids as c-2 evidence.
+
+## Exit
+
+wp2 closes when `dev` head is green on all three lanes. A failure here is fixed
+forward on `dev`; do not revert the merge.
+

devlog/_plan/260914_skill_doc_triage_release/020_wp3_prepare_0_2_28.md

@@ -0,0 +1,66 @@
+# 020 — wp3: prepare codexclaw 0.2.28 on dev
+
+## Goal
+
+Every version surface reads `0.2.28`, the CHANGELOG describes the change, and the
+inventory is regenerated from the measured hosted test count.
+
+## Version surfaces — the exact list `check-versions.mjs` enumerates
+
+`collectSurfaces()` builds this set. Build metadata (`+codex.<stamp>`) is permitted
+ONLY where marked; a plain surface carrying `+` is a violation.
+
+| # | Surface | Path | `0.2.27` -> `0.2.28` | Metadata |
+|---|---|---|---|---|
+| 1 | root package | `package.json` | `"version": "0.2.28"` | no |
+| 2 | plugin manifest | `plugins/codexclaw/.codex-plugin/plugin.json` | `"version": "0.2.28+codex.<stamp>"` | **yes** |
+| 3-11 | 9 components | `plugins/codexclaw/components/{bg-wake,config-guard,cxc-ops,messenger-bridge,pabcd-state,provider-bridge,recall,skill-search,subagent-config}/package.json` | `"version": "0.2.28"` | no |
+| 12 | inventory package | `plugins/codexclaw/inventory.json` -> `plugin.packageVersion` | `"0.2.28"` | no |
+| 13 | inventory manifest | `plugins/codexclaw/inventory.json` -> `plugin.manifestVersion` | `"0.2.28+codex.<stamp>"` | **yes** |
+
+`plugins/codexclaw/gui/package.json` and `cli/package.json` are declared workspaces
+(`workspaces: ["plugins/codexclaw/components/*", "plugins/codexclaw/gui", "cli"]`)
+but are NOT enumerated by `collectSurfaces()` — it walks `components/` only. Both
+read `0.2.27` today. Bump both to `0.2.28` for consistency with the rest of the
+workspace; the checker will not complain either way, so this is a tidiness rule,
+not a gate. Do not invent a surface the checker does not read.
+
+Verify with:
+
+    node plugins/codexclaw/scripts/check-versions.mjs 0.2.28
+
+## Inventory regeneration
+
+    node plugins/codexclaw/scripts/inventory.mjs --write --tests 3150
+
+`3150` is the `tests` line from hosted CI run 34790437740, job 103813520900, at
+head `7036f9b8` — NOT a local run and NOT the `pass` count, which is
+environment-dependent because CI skips the repo-map live smoke.
+
+The published badge in `README.md`, `README.ko.md` and `README.zh.md` already reads
+`3,150`, so this change adds no tests and the badge should not move. If
+`--write` moves it, the count is wrong — re-measure rather than editing by hand.
+`--write` also refreshes the inventory hash the release gate compares against.
+
+## CHANGELOG
+
+Insert a `## [0.2.28] - 2026-09-14` section directly under `## [Unreleased]`, in
+the existing `### Fixed` / `### Added` voice. It must name all four issues and say
+what an agent could not do before:
+
+- `add-criterion` missing from the documented CLI surface (#170)
+- generated `c-N` criterion ids vs. the `--id` the doc implies (#171)
+- in-lane workers are subagents, stated inside DISPATCH-SURFACE-01 (#172)
+- DELEGATE-MODEL-LIST-01: the advertised override list is a hint (#173)
+
+## Delivery
+
+A single commit on a topic branch off `dev`, PR to `dev`, merged once green.
+Do not commit directly to `dev`.
+
+    Title: chore(release): prepare codexclaw 0.2.28
+
+## Exit
+
+wp3 closes when the prep PR is merged and the new `dev` head is green on CI, WSL
+and Packed install.

devlog/_plan/260914_skill_doc_triage_release/030_wp4_promote_and_release.md

@@ -0,0 +1,84 @@
+# 030 — wp4: promote to main and publish v0.2.28
+
+## Goal
+
+`main` carries 0.2.28, the Release workflow publishes it, #170-#173 close, and
+`dev` survives.
+
+## Step 1 — promotion PR
+
+    gh pr create -R lidge-jun/codexclaw --base main --head dev \
+      --title "chore(release): promote codexclaw 0.2.28 to main"
+
+`enforce-target` requires PRs to target `dev`, with exactly one exemption: a
+`dev` -> `main` PR whose head repo is this repository. A fork branch merely named
+`dev` is not exempt, because the check compares `head.repo.full_name`. This PR
+qualifies, so no `[WRONG BRANCH]` prefix should appear. If one does, the exemption
+did not match and that is a real finding, not a cosmetic one.
+
+### `main` is ruleset-protected
+
+Ruleset `protect-main` (id 20884837, enforcement `active`, **no bypass actors**)
+applies `deletion`, `non_fast_forward` and `required_status_checks` to
+`refs/heads/main`. Six contexts are required:
+
+    ci
+    artifact (ubuntu-latest) / artifact (windows-latest) / artifact (macos-latest)
+    install (ubuntu-latest) / install (macos-latest)
+
+`strict_required_status_checks_policy` is **false**, so the PR does not have to be
+rebased onto the latest `main` before merging. No bypass actor exists, so
+`--admin` is not available here — the six contexts must genuinely pass. Note that
+WSL and the Windows `install` lane are NOT required contexts, so a red WSL lane
+does not block the merge even though wp2 still wants it green as release evidence.
+
+Merge once green. Record the merge commit SHA on `main` — that SHA is what the
+release dispatch must pin.
+
+## Step 2 — dev will be deleted; restore it
+
+`delete_branch_on_merge` is true and the promotion PR's head branch IS `dev`.
+Merging deletes it, exactly as happened after PR #169. Immediately after the merge:
+
+    git fetch origin --prune
+    git ls-remote --heads origin refs/heads/dev
+    # if absent:
+    git push origin origin/main:refs/heads/dev
+
+This satisfies c-8. The permanent fix is issue #175 and is out of scope here.
+
+## Step 3 — release dispatch
+
+Wait for CI, WSL and Packed install to conclude `success` on the `main` merge SHA
+first. `cxc release verify` reads those conclusions by SHA and fails closed; a
+dispatch before they finish reports `platform-ci is missing`.
+
+    gh workflow run release.yml -R lidge-jun/codexclaw --ref main \
+      -f version=0.2.28 -f prerelease=false -f dry_run=false \
+      -f expected_sha=<main merge SHA>
+
+`expected_sha` is mandatory and exists because branches move between the audit and
+the dispatch. Use `workflow_dispatch`, not the `push: tags` trigger.
+
+**Trap.** Ruleset `protect-release-tags` (id 20884836) applies `deletion`,
+`non_fast_forward` and `update` to `refs/tags/v*` with no bypass actors, so a
+version tag cannot be moved or removed once pushed. If a dispatch fails AFTER the
+tag is pushed, `v0.2.28` is burned and cannot be reused; that is a NEEDS_HUMAN
+outcome, not something to work around. Verified 2026-09-14: tags run to `v0.2.27`
+and `v0.2.28` is still free. This is why the gate runs before publication and why
+the dispatch is pinned to an audited SHA.
+
+## Step 4 — close the issues
+
+PR #174 carries `Closes #170`-`#173`, but it targeted `dev`. GitHub auto-closes
+only on merge into the DEFAULT branch, which is `main`, so the promotion merge is
+what closes them. Verify explicitly rather than assuming:
+
+    gh issue view 170 -R lidge-jun/codexclaw --json state
+
+If any remain open, close them with a comment pointing at the release.
+
+## Exit
+
+wp4 closes when the Release workflow concluded `success`, GitHub Release `v0.2.28`
+exists, #170-#173 are CLOSED, and `dev` resolves on the remote.