Night Market Change Control

Night Market Change Control

Every change to this repo passes through a fixed law stack, a classification step, and a gauntlet of automated gates. This skill tells you which class your change is, which gates it must pass, and which rules are non-negotiable because a past incident made them so. Nothing here may be routed around: if a gate fails, fix the cause, never the gate.

Jargon used below: a "gate" is any automated check that can block a commit, PR, or release. An "ADR" is an Architecture Decision Record in docs/adr/. The "Iron Law" is constitution rule 3: no implementation without a failing test first.

The law stack

When two documents conflict, the higher one wins.

A skill, hook, or agent instruction that says "skip rule N" without an explicit user grant or a merged amendment is itself a defect (CONSTITUTION.md, Override mechanism section).

The ten constitution rules

One line each. Where a rule was written in blood, the incident column names the blood.

Change classification

Classify before the first commit. The class decides the paperwork.

The change lifecycle

1. Branch

Branch from master (the main branch) using <topic>-<version>:

bashCopy code
git checkout master && git pull
git checkout -b my-topic-1.9.16

Live examples in git branch -a: ai-slop-1.9.4, bugfixes-1.9.5, discussions-fix-1.9.14. Never delete backup/unbloat-* branches. They are the recovery points for past deletion campaigns (backup/unbloat-20260328 is how the 2026-03-28 over-deletion was undone).

2. Local gates before committing

bashCopy code
make lint          # ruff format + ruff check --fix + bandit
make typecheck     # per-plugin strict mypy (all plugins)
make test          # per-plugin pytest via scripts/run-plugin-tests.sh
make validate-all  # plugin structure validation

Plugin tests MUST run per plugin (make <plugin>-test or make -C plugins/<plugin> test). Root pytest excludes plugins/* to avoid import-path collisions.

3. The pre-commit gauntlet

git commit runs .pre-commit-config.yaml hooks in this order (verified 2026-07-02):

1. Suppression guards: check-noqa (blocks bare inline lint suppressions), check-docstring-quality, check-json-utils-drift, check-per-file-ignores.
2. Hook registration: check-hook-registrations, check-plugin-hooks.
3. Code gates: run-plugin-typecheck --all (strict mypy on every plugin, not just changed ones), run-plugin-tests --changed.
4. Skill and plugin validation: validate-skill-descriptions, one validate-<plugin>-plugin hook per plugin, check-context-optimization, validate-description-budget, check-markdown-links, capabilities-sync-check, check-skill-graph-drift, check-skill-exit-criteria-drift.
5. Standard file hygiene (trailing whitespace, YAML/TOML/JSON syntax, merge conflicts, debug statements).
6. bandit security scan.
7. ruff-format, ruff-fix, ruff-check.
8. Pin freshness: check-ruff-version, check-pinned-versions.

The typecheck gate runs --all deliberately. It used to run --changed, and a global mirrors-mypy hook silently disabled 13 error codes. Both were fixed in 1.9.12 (CHANGELOG). Do not weaken either setting.

4. PR flow

Run in this order (all are sanctum slash commands):

1. /sanctum:prepare-pr updates docs, runs tests, drafts the PR.
2. /sanctum:pr-review reviews scope, requirements, and code.
3. /sanctum:validate-pr builds and executes a diff-derived test plan, and proves revert-tests are genuine guards.
4. /sanctum:fix-pr and /sanctum:resolve-threads handle feedback.

For plugin-touching changes, add abstract:plugin-review at the matching tier:

5. Release

1. Bump the ecosystem version. .claude-plugin/marketplace.json is the source of truth; the bumper fans it out to every plugin's plugin.json, metadata.json, openpackage.yml, pyproject.toml, and __init__.py:

   bashCopy code
   python3 plugins/sanctum/scripts/update_versions.py 1.9.16
   

   Or use the sanctum:version-updates skill, which runs a git-workspace-review preflight first.

2. Move [Unreleased] entries in CHANGELOG.md into a dated version section (Keep a Changelog 1.1.0, SemVer). Never rewrite or de-slop historical entries.

3. Update the docs of record: docs/api-overview.md version reference, plugin READMEs, and the generated capabilities reference via /sanctum:sync-capabilities.

4. Run abstract:plugin-review --tier release.

5. /sanctum:create-tag pushes a v-prefixed tag. The tag matching v* triggers .github/workflows/cross-framework-publish.yml (semver validation, cross-framework build, tarballs, GitHub release). Pushes to master separately trigger trust-attestation.yml (full test run plus SLSA attestation).

Landing a change: checklist

Non-negotiables

Each row is a settled battle. Re-litigating one requires new evidence stronger than the incident that settled it.

When NOT to use

• A gate is failing and you need to diagnose why: use night-market-debugging-playbook.
• You want the full story behind an incident named above: use night-market-failure-archaeology.
• You need the mechanics of running tests, lint, or the release scripts (flags, artifacts, environments): use night-market-operations.
• You are judging whether a design fits the architecture: use night-market-architecture-contract.
• You are deciding what evidence a test must provide: use night-market-validation-and-qa.

Exit Criteria

• The change is classified against the classification table, and any over-200-line AI diff has a spec, ADR, or plan doc committed before the implementation.
• make lint, make typecheck, and make test pass locally, and no bypass flag (--no-verify, SKIP=, force push) appears in the branch history.
• The branch name matches <topic>-<version> and is based on master.
• The PR description discloses AI involvement (authored, co-authored, or reviewed).
• For a release: marketplace.json, the dated CHANGELOG.md section, and the pushed v* tag all carry the same version.
• Any constitution change is in a PR titled constitution: amend rule N with repo-owner sign-off.

Provenance and maintenance

Compiled 2026-07-02 against repo v1.9.15 (10 constitution rules, 8 project rules, 17 ADRs). Re-verify volatile facts before relying on them:

bashCopy code
rg -c '^### [0-9]' CONSTITUTION.md          # expect 10
ls .claude/rules/ | wc -l                    # expect 8
ls docs/adr/ | wc -l                         # expect 17
rg -n '"version"' .claude-plugin/marketplace.json | head -1
rg -n '      - id:' .pre-commit-config.yaml  # current gate order
rg -n 'v\*' .github/workflows/cross-framework-publish.yml
rg -n 'amend rule' CONSTITUTION.md           # amendment title convention

Commit hashes cited above were verified with git log --oneline -1 <hash> on 2026-07-02. Unverified/candidate: the exact count of files restored after the unbloat incident (commit subjects confirm the delete and restore, not the restored-file count), and whether docs/api-overview.md holds a version table or a single version reference (one version mention verified).