spec-kitty / spec-kitty/spec-kitty
Tiered coding standards by domain importance (DDD): per-tier coverage/duplication/smell/lint/typing rigour in doctrine + CI + agent effort
- Dominant language
- Python
- Stars
- 1.6k
- Forks
- 165
- Avg merge
- 14h 52m
- Merged PRs (30d)
- 303
Description
## Intent (operator decision, 2026-06-11)
Not every part of the codebase is equal, and it should not be treated equally. Per DDD ideology: **core domain / shared kernels / multi-consumer libraries** are held to a HIGHER standard of rigour (coverage, duplication, smells, lint, typing) than **supporting/glue/duct-tape/POC** code. This must reflect in:
1. **How CI treats the code** — tier-aware quality gates, and
2. **How much effort agents put into it** — implementers/reviewers calibrate depth to the tier of what they touch.
## Delivery surfaces
### A. Doctrine: a set of related built-in artifacts
- A **tier taxonomy artifact** (e.g. `core` / `supporting` / `generic` / `experimental`, names TBD) with per-tier standards declarations (min coverage, mypy strictness, smell budget, duplication budget, review depth).
- A **module→tier map** declared per project (charter-resolved; likely DRG-linked so tier assignments are first-class governed artifacts with `requires`/`suggests` edges to the standards they imply).
- **Directives/tactics** consuming the tier: implementer profiles ("tier=core ⇒ mypy --strict, property tests where applicable"), reviewer profiles ("tier=generic glue ⇒ don't demand core-tier polish"), and the WP-prompt generator threading the tier of `owned_files` into prompts (effort calibration, both directions — prevents BOTH under-rigour on the kernel AND gold-plating of glue).
### B. Enforcement: spec-kitty repo CI as first consumer (dogfood)
- **Coverage:** per-tier thresholds (e.g. core ≥90%, supporting ≥75%, experimental advisory-only) — per-path coverage gating likely needs a CI-side check over coverage.xml, since SonarCloud quality gates are project-scoped (feasibility note below).
- **mypy:** strict-mode module list = core-tier modules (mypy supports per-module config natively).
- **ruff:** per-tier rule sets via per-path configuration.
- **Sonar:** investigate per-path issue severity/exclusion mapping vs a CI-side tier report; smell budget per tier.
- Tier map seed for this repo (illustrative, needs analysis): `core/commit_guard`, `mission_runtime/*`, `status/*` reducer+store, DRG/merge = **core**; CLI command shells, render helpers = **supporting**; scripts/, demos = **generic/experimental**.
## Open questions (for the in-depth analysis)
1. SonarCloud cannot gate per-path natively — is the tier gate a CI-side script over coverage.xml/sonar issues export, or do we drop Sonar for tier purposes and gate locally?
2. Where does the tier map live: charter section, standalone doctrine artifact kind, or DRG node attributes on existing module artifacts?
3. Migration story: existing code grandfathering vs ratchet-on-touch (boy-scout tiering).
4. Interaction with the existing architectural ratchets (they are effectively tier enforcement for boundaries already — reuse the pattern?).
## Scope / promotion note
**Promotion to feature-epic is DEFERRED until someone analyzes this in depth** (operator instruction). The surface area suggests epic scale (doctrine schema + DRG + CI mechanics + agent-profile threading + per-tool config — likely 3-5 child slices: ① taxonomy+map artifact kind, ② CI tier gates, ③ tool config plumbing, ④ agent effort threading, ⑤ this-repo tier map + dogfood), but the Sonar feasibility unknown (Q1) materially affects shape. Whoever picks this up: do the analysis, then decide promote-vs-slice and restructure accordingly.
Related: #1799 (charter & doctrine governance — parent), #1839 (deterministic diagrams — same "give maintainers structural insight" family; hotspot overlay could feed tier-map review), the architectural-ratchet suite (existing precedent for tiered structural enforcement).
Contributor guide
Assessment
This issue has not been assessed yet.