known-issues-format

# Known Issues Format **Purpose:** The single source of truth for the **format** of `docs/KNOWN_ISSUES.md` — a living, hand-maintained **thin index** where each issue is its own file under `docs/issues/`. `artifact-management` owns the *lifecycle* (it is a living Global Artifact, never archived, create-if-absent) and **delegates the format to this skill** — mirroring how it delegates `ARCHITECTURE.md` structure to `architecture-format-core`. This framework ships **no `wiki-index-render` tooling**, so the index is maintained **by hand**: adding, resolving, or re-categorizing an issue means editing **both** the per-issue file *and* its index line, in lockstep. Do **NOT** append flat `- [ ]` items to the ledger. ## Execution Mode - **Mode:** hybrid — a prompt-first format contract, plus one maintenance gate script. ## Script Contract - **Command:** `python3 scripts/check_contract_sync.py` - **Purpose:** fail if the format contract drifts between this `SKILL.md` (the authority) and the seed template — it compares the status/severity vocabularies, the frontmatter key set, and the index-line format. - **Outputs / failure semantics:** exit `0` in sync · `1` drift (prints the diverging field) · `2` extraction error. - **Idempotent**, read-only, no args, no dry-run needed. CI-gateable alongside `System/scripts/validate_skills.py`. ## Format Contract **Per-issue file** — `docs/issues/<slug>.md`, YAML frontmatter then an H1 title and body: ```yaml --- id: L-1 #...