Night Market Architecture Contract

Night Market Architecture Contract

This skill records the design decisions that hold claude-night-market together, the invariants that enforcement code keeps true, and the weak points that are known and accepted. Read it before proposing a change that crosses a plugin boundary, touches a hook, adds a skill, or bumps a version. Every claim cites in-repo evidence: an ADR (Architecture Decision Record, in docs/adr/), a commit hash, or a checked-in enforcement file. Verify a citation before relying on it:

git log --oneline -1 <hash>
rg -n "Status" docs/adr/<file>.md

Load-bearing decisions

1. Plugins are self-contained deployables

Each of the 23 plugins under plugins/ must install and run alone. There is no shared registry and no root-level shared library that plugins import at runtime (ADR-0001, Accepted). Plugins detect each other at runtime via filesystem checks and must degrade gracefully when a sibling is absent.

Cross-plugin DRY is an anti-pattern here, and that is settled by experiment, not taste. Commit 054e2679 consolidated 1164 lines of duplicated tasks_manager.py from attune, sanctum, and spec-kit into a shared root script. It broke plugin self-containment and was reverted in 29961cd2. The durable fix, d89a55c7, made the copies per-plugin and intentionally different. docs/dependency-audit.md records the per-plugin copies as the approved state. Do not re-propose the consolidation.

Practical test before you extract shared code: if a user installs only one plugin from the marketplace, does your change still work? If not, duplicate the code into each plugin instead.

2. Hooks run under host Python from a cache directory

Claude Code copies an installed plugin into a cache directory and runs its hooks under the host system Python, which can be as old as 3.9. The repo itself is Python 3.12 (root pyproject.toml, requires-python >= 3.12). Only hook scripts and their transitive import chains carry the 3.9 constraint. Five contract rules follow, each purchased with an outage:

CI enforcement: .github/workflows/python39-compat.yml runs two gates with uneven coverage. Gate 1 (ruff UP007, flags 3.10+ union syntax) covers 12 plugins' hooks/ dirs. Gate 2 (hook test suites inside a real Python 3.9 venv) covers only 7 plugins: abstract, conserve, egregore, imbue, leyline, memory-palace, sanctum. herald ships a Stop hook yet appears in neither gate.

3. One ecosystem version, fanned out to every manifest

.claude-plugin/marketplace.json is the version source of truth (1.9.15 as of 2026-07-02). Each plugin carries three manifests that must stay in sync with it and with each other:

• .claude-plugin/plugin.json (name, version, component arrays)
• .claude-plugin/metadata.json (version plus dependency hints)
• openpackage.yml (cross-framework manifest)

Plus pyproject.toml and any __init__.py carrying __version__. Never hand-edit versions across files. Use the bumper, which finds and rewrites all of them:

uv run python plugins/sanctum/scripts/update_versions.py <version>

One trap: metadata.json dependencies (for example imbue declaring "abstract": ">=2.0.0") is a separate semver namespace for capability compatibility. It does not track the marketplace version and a 2.0.0 there does not mean marketplace 2.0.0 exists.

4. Skill discovery budget is finite and overflow is silent

Claude Code loads every installed skill's description into context at 2% of the context window, with a 16,000-character fallback (ADR-0004, Accepted, updated 2026-05-21). Descriptions that exceed the budget make skills invisible with no error anywhere. That is why:

• Each description is capped at 160 characters (docs/skill-description-guide.md), enforced by the validate-description-budget pre-commit hook backed by plugins/abstract/scripts/validate_budget.py.
• The ecosystem-wide validator ceiling is 90,000 characters (DEFAULT_BUDGET in plugins/abstract/scripts/validate_budget.py, overridable via SLASH_COMMAND_TOOL_CHAR_BUDGET). ADR-0004 and docs/skill-description-guide.md still cite a stale 60,000 figure; the script is the enforcer. Flag the ADR for an update through change control.

When adding a skill, spend the 160 characters on trigger phrases, not on restating the name.

5. Collective memory and trust are external services

Decisions, learnings, and audit syntheses are posted to GitHub Discussions, which act as agent collective memory across sessions (ADR-0007, Accepted). There is no gh discussion subcommand: all Discussions access goes through gh api graphql. Release trust is established by SLSA attestation (Supply-chain Levels for Software Artifacts) of trust-report.json on master pushes (.github/workflows/trust-attestation.yml). The original blockchain design (ERC-8004) was dropped for cost. ADR-0008 is marked Superseded 2026-03-15 and now points at GitHub Attestations. See night-market-collective-memory for the Discussions workflow.

6. Every skill has one of three roles

docs/skill-integration-guide.md defines the role taxonomy used when judging whether a skill is an orphan or a hub:

A skill with zero inbound Skill() references is only a problem if it also has no command path and no hook that loads it. Check the role before archiving anything.

Invariants

Each row names the enforcement that keeps the invariant true. If you weaken the enforcement, you own the failure mode in the third column.

The two ratchet scripts share one mechanic: they fail a commit only when the violation count rises above the committed baseline, and they ask you to lower the baseline when the count drops. Never raise a baseline to get a commit through. That is routing around change control. One documented exception: a brand-new library skill legitimately starts uncalled, and scripts/check_skill_graph_drift.py (plus the _comment in scripts/skill_graph_baseline.json) instructs you to raise max_uncalled_libraries to record the 30-day consumer grace period that .claude/rules/shared-utility-consumer-rule.md grants. See night-market-change-control.