doc-standard

# Doc-Standard

Answer in the USER'S language; keep technical terms, commands, paths, and check ids verbatim.

Find what a doc is MISSING versus the standard for its kind. Report CONFIRMED gaps only.

## Parameters
- **SCOPE:** named files (default when given) | touched doc files this session | whole repo docs (confirm first if > 20 files).
- **TIER:** Quick = mechanical presence checks (~free) · Full = semantic completeness judgment (paid). Default from `.coalledger.json` `quickVsFull`; Full is always a separate consent.

## The standard (resolve in this order — never invent one)
1. **The project's own** — a style guide, template, pattern doc, or stated convention in the repo binds first.
2. **The kind's accepted standard** — verified REAL-TIME, MULTI-source (cross-check several authoritative sources, never one), language-aware. Offline → `⚠️ unverified: check [source]`, never asserted from memory.
3. **No resolvable standard** → say so; report only self-evident gaps (an empty required field, a heading with no body).

## Method
1. **Identify the doc's kind** (README, policy, reference, report, letter, ...) and resolve its standard (above).
2. **Mechanical layer:** required parts PRESENT — detect sections by AST structure, position, and meaning, NEVER by an English keyword (a section may carry its heading in any language).
3. **Semantic layer (Full):** completeness of substance — is the public surface the source ships actually covered (commands, config keys, exported APIs, the steps a reader needs); are stated sections empty shells.
4. **Severity by CONTEXT** (never a fixed map), then honor `severityFloor`: a missing security-reporting channel or install step = HIGH-CRITICAL; an undocumented public key = MEDIUM-HIGH; a nice-to-have section = LOW.

## Escalation boundary
Whether content is CORRECT is doc-grounding's job; whether a judgment call needs formal verification is CoalBoard's (`/coalboard`). This canary only answers "is it all THERE".

## Output
| # | path | gap | standard source | severity | fix |

CONFIRMED table only; `⚠️ unverified` standards and SUSPECTED gaps in separate lists.

## Fix mode (choice-gated)
After any report in an interactive session you **MUST** present this menu via your question tool (skip only when findings are zero or no user is present). NEVER auto-fix a live doc.

- **Draft the missing parts:** propose section drafts for the user to review — content is ALWAYS the user's call; drafts are applied only after approval, with a checkpoint first (git stash/commit in a git repo; else copy the file aside — never assume git exists).
- **Let me pick:** list gaps; the user selects which to draft.
- **Report only:** exit unchanged.

## Multilingual
The mechanical layer is language-agnostic (AST/position/semantics, no keyword matching). Semantic judgment works in the doc's language and degrades to low-confidence flags on a poorly-handled language, never false alarms.

## Problem report
If this canary misbehaves, OFFER to file it at <https://github.com/TheColliery/CoalLedger/issues> with a user-reviewed summary — never auto-submit.