CI Quality Gate

docstats operates as an automated acceptance gate in continuous integration pipelines and pull request checks.

Recommended CI/CD Workflow

1. Authors draft and edit documentation against qualitative style guides.
2. The CI pipeline invokes docstats as an automated gate.
3. If either axis fails, authors resolve the specific diagnostic flags.
4. The pipeline re-evaluates the amended commit.

This workflow enforces post-hoc validation. In controlled studies, supplying live numeric scores during drafting produced no measurable quality gains ($p = 0.7253$) and encouraged gaming of superficial metrics. See Statistics & Evaluation.

Combined Acceptance Verdicts

Publication requires passing both Axis A and Axis B. Actionable remediation depends on which axis failed and document provenance:

Axis A (Audience Fit)	Axis B (Style Score)	Verdict	Provenance-Aware Action
Pass	Pass	Ship	Publication ready.
Pass	Warn / Fail	Revise for Voice	Raw AI drafts: Restructure sentences to eliminate synthetic tropes. Human-authored text: Address specific diagnostic flags while preserving authorial voice.
Warn / Fail	Pass	Revise for Complexity	Adjust sentence length and vocabulary for the target audience band.
Fail	Fail	Full Rewrite	Raw AI drafts: Re-author complexity and voice. Human-authored text: Decompose dense sections and address style lints.

Both axes must pass independently. See The Two-Axis Model for threshold criteria.

Sample CI Scorecard Output

DOCUMENT: migration-guide.md   (declared type: developer blog)

Axis A  Readability
  text_standard (consensus): grade 11    band: Dense       -> target Accessible-Dense  [PASS]
  flesch_reading_ease: 42.3   flesch_kincaid_grade: 11.2   word_count: 1840

Axis B  House-Style Conformity
  ai_tell_score: 6.4 / 10                                                            [WARN]
  em dashes in prose: 3   throat-clearing: 2   binary contrasts: 4   Wh- starts: high
  adverb rate: 3.1/100w   sentence-length CV: 0.18 (advisory rhythm hint)

VERDICT: REVISE
  Axis A acceptable. Axis B below floor (6.4 < 7.0): remove 3 em dashes,
  cut 2 throat-clearing openers, rewrite 4 binary-contrast frames.

Golden Set Drift Anchors

The samples/ directory holds four reference texts spanning complexity tiers (level_primary, level_middle, level_academic, level_legal). These serve as deterministic code-drift anchors: modifications to parsing, tokenization, or formula implementations must produce zero score variance against the committed baseline.

Verify baseline consistency locally or in CI:

uv run python baseline_analysis.py

Compare generated scores against samples/baseline_results.json.

CI Pipeline Commands

# Execute test suite
uv run pytest

# Verify code style and formatting
uv run ruff check .
uv run ruff format --check .

Anti-Circularity in External Evaluation

When evaluating text generated by AI models, avoid using docstats scores as the sole measure of writing quality. Rigorous evaluation requires decoupled benchmarks: blind multi-judge human or LLM scoring, held-out readability implementations, and non-parametric statistical tests (such as the Wilcoxon signed-rank test). docstats telemetry records diagnostic metrics without dictating external evaluative verdicts.