Add ratchet for reviewed Markdown documents

CHANGELOG.md

@@ -4,6 +4,13 @@ Notable changes to Agent Code Guard are recorded here.
 
 ## Unreleased
 
+### Added
+
+- Explicit source-controlled Markdown document-size ratchets: create accepted
+  physical-line allowances and update them only downward or by pruning. Accepted
+  documents pass without repeated REVIEW; growth returns REVIEW, while section
+  findings remain independent. Normal analysis never writes a baseline.
+
 ## 0.3.1 - 2026-08-29
 
 ### Changed

README.md

@@ -81,7 +81,7 @@ Copy this prompt to a coding agent:
 > skill directory. Do not guess a target or overwrite an existing export; verify
 > that `.agent-code-guard-version` matches the installed distribution. Follow the
 > [agent workflow](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md)
-> without creating a LOC baseline. After meaningful source or Markdown edits, run
+> without creating an adoption baseline. After meaningful source or Markdown edits, run
 > `code-guard . --changed-only --json --json-mode compact`; outside Git, pass the
 > exact edited files. Inspect REVIEW and FAIL findings, make only genuine
 > improvements, rerun the check, and report the result. Never weaken thresholds,
@@ -232,11 +232,18 @@ Its default `ratchetAt: "fail"` policy freezes files above `failAt`; choose
 `ratchetAt: "review"` only when every established file above `warnAt` must be
 non-increasing while ordinary findings in that range remain REVIEW.
 
+Reviewed oversized Markdown documents have a separate, explicit
+[document-size ratchet](https://github.com/stef-k/agent-code-guard/blob/main/docs/usage.md#reviewed-markdown-document-ratchet).
+`--create-markdown-baseline` records accepted physical-line counts;
+`--update-markdown-baseline` only lowers or prunes them. Documents within their
+allowance pass the document-size guard; growth produces REVIEW. Section
+findings remain active, and ordinary analysis never writes either baseline.
+
 ## Trust, CI, and platform support
 
 CI installs Agent Code Guard and analyzes its own real checkout. REVIEW findings
 remain visible but non-blocking, while FAIL findings and tool errors block the
-workflow; the repository intentionally uses no LOC baseline.
+workflow; the repository intentionally uses no adoption baseline.
 
 The maintained interpreter range is **CPython 3.10–3.14**. See
 [Platform support](https://github.com/stef-k/agent-code-guard/blob/main/docs/platform-support.md) for supported binary platforms and

docs/README.md

@@ -6,8 +6,8 @@ contract and the evidence behind it.
 ## User guides
 
 - [Human and agent workflow](agent-workflow.md) — installation, repeated changed-work checks, REVIEW judgment, and optional authorized hooks.
-- [Usage](usage.md) — installation, file selection, output, result states, and CI.
-- [Configuration](configuration.md) — zero-config defaults, guard settings, and exclusions.
+- [Usage](usage.md) — installation, file selection, output, adoption ratchets, result states, and CI.
+- [Configuration](configuration.md) — zero-config defaults, guard settings, exclusions, and baseline schemas.
 - [Language support](language-support.md) — applicable syntax languages, extensions, and mixed-content behavior.
 - [Platform support](platform-support.md) — maintained Python versions and native-wheel boundaries.
 - [Skill distribution](skill-distribution.md) — version-matched agent skill discovery and export.

docs/agent-workflow.md

@@ -17,7 +17,7 @@ code-guard doctor
 ```
 
 Ask your coding agent to locate the bundled version-matched skill with
-`code-guard --skill-path` and adopt the workflow below without creating a LOC
+`code-guard --skill-path` and adopt the workflow below without creating an adoption
 baseline. Decide whether checks remain manual or use an optional platform hook.
 Exporting a skill into a persistent directory, installing a hook, or changing
 persistent user or repository configuration requires your authorization.
@@ -26,6 +26,13 @@ Require the agent to report its final result and any REVIEW findings it accepts
 with justification. Use CI as the final gate, not as a substitute for checks
 during development.
 
+An explicitly reviewed, cohesive oversized Markdown document can use the
+[document-size ratchet](usage.md#reviewed-markdown-document-ratchet) after
+acceptance is authorized. Ordinary checks never create or update a baseline.
+Unchanged or smaller accepted documents pass the document guard; growth returns
+REVIEW, and section findings remain independent. Do not use baseline updates
+to hide new growth or treat document acceptance as a section exemption.
+
 ## The shared loop
 
 ```text

docs/configuration.md

@@ -147,6 +147,51 @@ only existing hard failures; choose `review` when established review-level files
 must also be non-increasing. Never change the policy, thresholds, exclusions,
 exemptions, or stored allowances merely to silence growth.
 
+## Source-controlled Markdown document ratchet
+
+Reviewed document allowances live separately from LOC in
+`<analysis-root>/.agent-tools/code-guard.markdown-baseline.json`:
+
+```json
+{
+  "version": 1,
+  "markdownDocumentSize": {
+    "files": [
+      {
+        "path": "docs/architecture.md",
+        "allowedLines": 845
+      }
+    ]
+  }
+}
+```
+
+The version must be integer `1`. Paths are exact, normalized root-relative `/`
+paths to `.md` documents (extension matching is case-insensitive); allowances
+are positive integer physical-line counts, including blank and comment lines.
+Keys are closed, entries must be sorted by path, and duplicate keys or paths,
+non-integer values, unsafe/absolute paths, and symlink traversal fail closed.
+Writers use UTF-8, two-space indentation, LF endings, and a final newline.
+Creation cannot overwrite a baseline; updates replace it atomically only after
+all entries in scope have been checked. A no-op update preserves the file.
+
+There are no new guard configuration keys. `markdownDocumentSize.reviewAt`
+remains 800 by default and `markdownSectionSize.reviewAt` remains 200.
+`guards.loc.ratchetAt` has no effect on Markdown. The document-size guard accepts
+an exact-path allowance while the document stays at or below that count;
+growth above the allowance reviews whenever it also exceeds `reviewAt`.
+Documents at or below `reviewAt` pass without needing a baseline.
+
+`--create-markdown-baseline` records only selected documents above the effective
+threshold. `--update-markdown-baseline` only lowers or prunes existing entries
+within positional bounds; it never adds or increases allowances. Normal
+analysis never mutates this file. Section analysis remains independent, and
+section baselines are not supported. These are explicit reviewed-document
+acceptances, not default setup or permission to hide growth with exclusions,
+threshold changes, or replacement allowances.
+
+See the [workflow and output contract](usage.md#reviewed-markdown-document-ratchet).
+
 ## Fail-closed validation
 
 Malformed JSON, invalid types or thresholds, unknown top-level properties,

docs/design-decisions.md

@@ -467,3 +467,21 @@ span. Style facts must use a separate family-specific pass over final
 discovery, or justify generic artifact/plugin infrastructure. Full corpus,
 provider, recovery, boundary, and gaming evidence is recorded in
 `docs/style-guard-evidence.md`.
+
+## D35 — Reviewed Markdown documents use a separate non-increasing ratchet
+
+A cohesive oversized Markdown document can retain an explicitly reviewed
+physical-line allowance at its exact root-relative path. The separate
+`.agent-tools/code-guard.markdown-baseline.json` keeps this acceptance independent
+of LOC policy: unchanged or smaller documents pass the document-size guard;
+growth above the allowance and ordinary threshold returns REVIEW, never FAIL.
+Normal analysis reads without writing. Explicit creation records current
+oversized documents; updates only lower or prune existing allowances.
+
+The baseline changes acceptance, not measurement, global thresholds, or scope.
+Section findings remain independent. Sections have headings and line ranges,
+but no stable identity across duplicate headings, renames, and edits. Section
+ratchets are deferred to avoid adding identity rules to this bounded feature.
+Both baselines share filesystem safety routines, while retaining separate
+schemas and guard-specific lifecycle rules. The original Markdown admission
+and threshold evidence remain historical records.

docs/usage.md

@@ -198,12 +198,80 @@ size-regression check. A ratchet entry may not overlap `allowedLargeFiles`.
 
 This workflow is only for adopting established legacy repositories. New
 projects, including Agent Code Guard itself, should meet policy directly and
-must not create a ratchet baseline.
+must not create a LOC ratchet baseline.
 
 Do not switch between `fail` and `review`, raise thresholds, add exclusions or
 exemptions, or edit allowances merely to silence a growth failure. Those are
 source-controlled policy changes and require their own substantive justification.
 
+## Reviewed Markdown document ratchet
+
+After reviewing an oversized, cohesive Markdown document, explicitly record its
+accepted physical-line count over a deliberately bounded scope:
+
+```bash
+code-guard docs/architecture.md --create-markdown-baseline
+git add .agent-tools/code-guard.markdown-baseline.json
+git diff --cached
+```
+
+This creates `<analysis-root>/.agent-tools/code-guard.markdown-baseline.json`.
+The analysis root is the enclosing Git top-level or, outside Git, the resolved
+invocation directory. Creation requires an enabled `markdownDocumentSize` guard
+and records only selected `.md` files strictly above its effective `reviewAt`.
+An existing baseline is never overwritten by create. Review and commit the
+baseline as the explicit acceptance decision; it is not part of ordinary setup.
+
+Normal analysis reads the baseline automatically without writing it. With the
+default 800-line threshold and an accepted allowance of 845 document lines:
+
+| Current document | Document-size result |
+| --- | --- |
+| Same path, 845 lines | PASS, within allowance |
+| Same path, 840 lines | PASS, within allowance |
+| Same path, 846 lines | REVIEW, allowance exceeded |
+| New or renamed path, 845 lines | REVIEW, no allowance |
+| Any document at or below 800 lines | PASS, no allowance needed |
+
+This ratchet applies only to `markdownDocumentSize`. It does not change the
+threshold, exclude Markdown from analysis, or suppress `markdownSectionSize`.
+An accepted document can still have section REVIEW findings. Growth remains
+REVIEW (exit `1`, or `0` with `--ci`), not FAIL.
+
+After shortening or deleting documents, explicitly lower or prune entries:
+
+```bash
+code-guard docs --update-markdown-baseline
+```
+
+Update requires an existing baseline and an enabled document guard. It lowers
+existing allowances within positional bounds, removes deleted or scope-excluded
+paths and entries at or below the effective threshold, and preserves entries
+outside those bounds. It never adds an entry or increases an allowance. Growth
+in a retained entry aborts the entire update without changing the baseline.
+A rename is a deletion plus an unaccepted new path. Manual baseline changes
+require source-control review; do not rebaseline merely to hide growth.
+
+Both write modes accept paths, `--config`, and repeated `--scope-exclude`.
+They reject other baseline modes, LOC counting/threshold options, Git selectors,
+JSON/CI analysis options, diagnostics, version reporting, and skill management.
+Writes do not run normal analysis. Successful writes exit `0`; invalid inputs
+or unsafe baselines produce tool errors (exit `3`, stderr, no completed report).
+Normal analysis and creation do not grant allowances through an explicitly
+supplied file symlink; updates reject symlink bounds. Baseline storage and
+entries must not traverse symlinks, and baseline-enabled scopes must stay
+inside the analysis root.
+
+Human output shows the accepted allowance and `within`, `exceeded`, or
+`no longer needed`. Full/debug JSON retains document measurements and the
+unchanged `thresholds.reviewAt`; entries matched by path add `baselineLines`
+and `ratchetStatus` (`within`, `exceeded`, or `notNeeded`). Unmatched findings
+retain their original shape. Compact JSON omits accepted PASS findings like
+other passes. Accepted documents do not require the document-size policy;
+independent section findings still require their own policy.
+
+See the [persisted schema](configuration.md#source-controlled-markdown-document-ratchet).
+
 ## Results and exit codes
 
 - `PASS` means no special action and exits `0`.

skills/code-guard/SKILL.md

@@ -148,8 +148,9 @@ reviews and never fails. Load `references/complexity-policy.md` only when
 
 Markdown document and direct-section size count all physical lines. Sections
 run from a supported heading through the line before the next heading of any
-level, or EOF. Exact effective thresholds pass; greater measurements review and
-never fail. Load `references/markdown-size-policy.md` when either
+level, or EOF. Exact effective thresholds pass; greater measurements normally
+review and never fail. A document measurement within an explicitly accepted
+Markdown document baseline passes the document-size guard. Load `references/markdown-size-policy.md` when either
 `markdownDocumentSize` or `markdownSectionSize` appears in `requiredPolicies`.
 Review navigation and responsibility without mechanically splitting coherent
 specifications or gaming headings/formatting.
@@ -161,3 +162,20 @@ REVIEW requires inspection and justification, not mandatory refactoring.
 Agent Code Guard is the canonical LOC implementation. Agent LOC Guard is the completed prototype/reference whose mature behavior was migrated from commit `75ab39d261dbc65f78815836fac90add16d265d1`.
 
 Project-specific architecture rules, framework-specific checks, arbitrary style preferences, security scanners, and dependency auditing are outside the universal core.
+
+## Reviewed Markdown document baselines
+
+After explicit acceptance of a cohesive oversized document, use
+`code-guard docs/architecture.md --create-markdown-baseline` to record its current
+physical-line count in `.agent-tools/code-guard.markdown-baseline.json` at the
+analysis root. Normal analysis reads this file without writing. Unchanged or
+smaller accepted documents pass `markdownDocumentSize`; growth above both the
+allowance and effective threshold returns REVIEW. `markdownSectionSize` remains
+independent and has no baseline support.
+
+`--update-markdown-baseline` only lowers or prunes existing allowances within
+positional bounds; it never adds or increases one. Neither write command is
+part of routine checks. Do not create, replace, remove, or increase allowances
+merely to silence findings. Review and commit explicit acceptance decisions.
+Human/full JSON output retains acceptance context; compact omits accepted PASS
+findings. Load the Markdown policy for actionable document or section reviews.

skills/code-guard/references/markdown-size-policy.md

@@ -14,3 +14,20 @@ mechanically split coherent material, compress formatting or remove useful
 blank lines, or hide content in fenced code. Agents must not raise thresholds or
 disable either guard merely to silence a finding; project or user authority is
 required for configuration changes.
+
+## Explicit document acceptance
+
+An explicitly reviewed, cohesive oversized document may use a source-controlled
+allowance created with `--create-markdown-baseline`. The separate
+`.agent-tools/code-guard.markdown-baseline.json` records exact root-relative paths
+and current physical-line counts. Within that allowance the document finding
+passes; growth above both the allowance and effective threshold is REVIEW,
+never FAIL. At or below the ordinary threshold, an allowance is no longer needed.
+
+This applies only to `markdownDocumentSize`. Inspect section REVIEW findings
+independently; document acceptance does not exempt sections. Normal analysis
+never changes a baseline. After reductions or deletions,
+`--update-markdown-baseline` can explicitly lower or prune existing entries but
+cannot add or increase allowances. Agents must not create or replace baselines,
+remove allowances, raise thresholds, or add exclusions merely to silence growth.
+Baseline acceptance requires explicit authority and source-control review.