Night Market Operations

Release runbook

The ecosystem ships as one version. .claude-plugin/marketplace.json is the version source of truth, fanned out to every plugin manifest. Gates and review policy are night-market-change-control territory. This is the mechanical sequence.

1. Preflight. Run Skill(sanctum:git-workspace-review) for a read-only workspace check. Confirm you are on a <topic>-<version> branch. Do not release from master.

2. Bump the version everywhere. Dry-run first:

   uv run python plugins/sanctum/scripts/update_versions.py 1.9.16 --dry-run
   uv run python plugins/sanctum/scripts/update_versions.py 1.9.16
   git diff --stat

   The script rejects any version that does not match ^\d+\.\d+\.\d+$. It then rewrites the version field in every match of these globs, and it skips cache and venv directories:

   • **/pyproject.toml
   • **/Cargo.toml
   • **/package.json
   • **/.claude-plugin/plugin.json
   • **/.claude-plugin/metadata.json
   • **/.claude-plugin/marketplace.json
   • **/openpackage.yml
   • any **/__init__.py that contains __version__

   Expect a large diff of roughly 100 files. That is the design.

3. Add the CHANGELOG entry. CHANGELOG.md follows Keep a Changelog 1.1.0 with SemVer. Keep ## [Unreleased] at the top. Insert ## [X.Y.Z] - YYYY-MM-DD directly below it. Do not rewrite or de-slop historical entries.

4. Sync the docs. Update the per-plugin version column in docs/api-overview.md. Then run:

   make docs-sync-check

   The check compares plugin.json registrations against the generated capabilities reference in book/src/reference/. If it reports drift, run /sanctum:sync-capabilities --fix.

5. Open the PR and clear the gates. Follow night-market-change-control. The gates are the pre-commit hooks, the slop check on docs, capabilities-sync, typecheck, and the security workflows.

6. Merge to master.

   trust-attestation.yml fires on the push. It runs make test. It writes trust-report.json. It attaches a SLSA provenance attestation with actions/attest-build-provenance@v4.

7. Tag the release. Run /sanctum:create-tag v1.9.16. The command pushes a v-prefixed annotated tag. It then confirms that the release pipeline started.

8. Let the release pipeline run.

   cross-framework-publish.yml fires on v* tags. It strips the v and validates the version against ^[0-9]+\.[0-9]+\.[0-9]+. It runs the cross-framework unit tests: clawhub_export, build_bridge, a2a_cards, and framework_detect. It runs make cross-framework. It packages four tarballs:

   • night-market-clawhub
   • night-market-openclaw-bridge
   • night-market-a2a-cards
   • night-market-cross-framework

   It then creates the GitHub release.

   One precondition applies. The publish job fails when clawhub/manifest.json does not exist. It also fails when total_exported is 0. The current count is 188.

   ClawHub submission after the release stays manual. Run ./scripts/clawhub-submit.sh v<version>.

Release checklist:

• make test, make lint, make typecheck all pass locally
• update_versions.py diff reviewed and marketplace.json shows the new version
• CHANGELOG has the new section, [Unreleased] still on top
• make docs-sync-check clean
• Tag pushed, both workflows green, release has 4 tarball assets

Book publishing

The mdBook under book/ deploys via deploy-book.yml:

• Triggers: push to master or main touching book/** or the workflow file itself, plus PRs on the same paths (build-only) and manual dispatch.
• Build: peaceiris/actions-mdbook@v2 with mdbook-version: 'latest', then mdbook build with working-directory book. Output book/build uploads via actions/upload-pages-artifact@v5 and deploys with actions/deploy-pages@v5, with one retry step if the first deploy fails.
• Known fragility: mdbook is unpinned ("latest"), so a new upstream mdbook release can break the build with no change in this repo. If the book job fails right after an mdbook release, suspect that first.

Local preview, if mdbook is installed:

cd book && mdbook build   # output in book/build/

Cross-framework export surface

make clawhub-export       # export all skills to clawhub/, then validate
make clawhub-export-top   # top 20 most marketable skills only
make clawhub-validate     # re-validate an existing export
make clawhub-stats        # export statistics, no writes
make bridge-build         # (depends on clawhub-export) build bridge/openclaw/
make a2a-cards            # generate A2A agent cards into bridge/a2a/
make a2a-list             # list agents eligible for card generation
make detect-framework     # detect the active agentic framework
make cross-framework      # all of the above: export + bridge + cards

make cross-framework is exactly what the release pipeline runs, so running it locally before tagging catches export failures early. It prints skill and agent counts and ends with framework detection.

When NOT to use

Exit Criteria

• The chosen make target ran and its per-plugin summary was read, beyond the exit code alone. For make validate-all and make plugin-check, output was scanned for embedded failure notes.
• Single-plugin or single-file test runs were executed from inside the plugin directory, never via root pytest.
• For a release: update_versions.py diff verified, CHANGELOG section added, make docs-sync-check clean, tag pushed, and the GitHub release shows all four tarball assets.
• Any generated artifact (htmlcov, coverage.xml, clawhub/, book/build) was identified as generated and not hand-edited.

Provenance and maintenance

Compiled 2026-07-02 against repo v1.9.15, branch discussions-fix-1.9.14. Coverage-threshold inventory delegated to night-market-validation-and-qa and the egregore stop cross-reference added on 2026-07-03. Volatile facts and how to re-verify them:

# Make target wiring
sed -n '60,150p' Makefile && sed -n '150,300p' Makefile

# Test runner behavior (delegation, coverage threshold, skip logic)
sed -n '1,110p' scripts/run-plugin-tests.sh

# Version bump globs and semver regex
rg -n "patterns|re.match" plugins/sanctum/scripts/update_versions.py

# Release pipeline gates
rg -n "tags|total_exported|tar -czf" \
  .github/workflows/cross-framework-publish.yml

# Attestation flow
rg -n "make test|attest|trust-report" \
  .github/workflows/trust-attestation.yml

# Book deploy and mdbook pin
rg -n "mdbook-version|deploy-pages|working-directory" \
  .github/workflows/deploy-book.yml

# Current export count (was 188 on 2026-07-02)
python3 -c "import json; \
  print(json.load(open('clawhub/manifest.json'))['total_exported'])"

# Coverage thresholds
rg -n "coverage_threshold" plugins/*/pyproject.toml
rg -n "fail_under" pyproject.toml