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>:

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

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:

   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).