night-market-architecture-contract
States load-bearing decisions, invariants, and weak points. Use when judging a design change. Do not use for gating; use night-market-change-control.
athola · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add athola/claude-night-market --skill night-market-architecture-contract技能说明
name: night-market-architecture-contract description: States load-bearing decisions, invariants, and weak points. Use when judging a design change. Do not use for gating; use night-market-change-control.
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:
| Rule | Why (evidence) |
|---|---|
| Hook code and every transitive import must be Python 3.9 compatible | datetime.UTC (a 3.11+ alias) broke the whole hook import chain repeatedly. ruff kept auto-reverting the fix until UP017 was globally ignored (pyproject.toml line 165) and an AST scan test held the line (plugins/leyline/tests/test_python39_compat.py) |
Read the hook payload as JSON on stdin, never from CLAUDE_TOOL_* env vars | Claude Code does not set those env vars, so env-reading hooks were silent no-ops for months (full record: night-market-failure-archaeology SB9). Canonical reader: read_hook_payload() in plugins/abstract/hooks/shared/hook_io.py |
| No relative paths in hooks | The cache directory is not the repo checkout. conserve's session-start hook broke on a relative path and now inlines its JSON utilities (CHANGELOG) |
| Hook entrypoints must import safely under a bare interpreter | An eager import yaml in gauntlet made every git commit emit ModuleNotFoundError. Guarded in 45dd77ef (#518), anthropic deferred in 9bfc0a7a |
Subprocess timeouts must sit below the budget registered in hooks.json | herald's LLM call once outlived its registered Stop-hook budget, so the harness killed the hook with no verdict at all (full record: night-market-failure-archaeology SB7). Guard test: plugins/herald/tests/unit/test_double_shot_latte.py |
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 thevalidate-description-budgetpre-commit hook backed byplugins/abstract/scripts/validate_budget.py. - The ecosystem-wide validator ceiling is 90,000 characters
(
DEFAULT_BUDGETinplugins/abstract/scripts/validate_budget.py, overridable viaSLASH_COMMAND_TOOL_CHAR_BUDGET). ADR-0004 anddocs/skill-description-guide.mdstill 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.