Repository navigation
Description
Task
T-006b· Milestone M1 — Foundation · Size S · Priority P1 · Epic #1Implements NFR-MNT-001
Branch
ci/t-006b-docs-workflow-markdownlint-mermaid-render— one task = one branch = one PR (doc 32 §6)
Summary
Automate documentation quality so the specification (the agents' source of truth) never silently breaks: every Mermaid block renders, links resolve, Markdown is linted and the ADR index lists every ADR.
Context / motivation
The docs are normative for AI agents (AGENTS.md). Broken diagrams or links directly degrade implementation quality.
Scope
In scope
scripts/check_docs.sh(alsomake docs-check): markdownlint-cli2 with.markdownlint.jsonc, mermaid-cli (mmdc) rendering every fencedmermaidblock (viascripts/check_mermaid.sh), lychee link check (offline mode for repo links, online for external with retries),scripts/check_adr_index.pycomparingdocs/adr/*.mdwith the index in doc 15 §2 /docs/adr/README.md..github/workflows/docs.ymltriggered ondocs/**,*.mdchanges.
Implementation guidance
- Mermaid CLI needs Chromium: use the
minlag/mermaid-clicontainer ornpx @mermaid-js/mermaid-cliwith puppeteer config--no-sandboxin CI. Make markdownlint rules pragmatic (allow long lines in tables). - Standards: respect the layering contracts (doc 16 §2) and conventions in doc 34; no hard-coded tunables — thresholds/defaults come from typed settings (doc 27); no magic numbers (ruff
PLR2004); public APIs typed (mypy strict) and documented.
Acceptance criteria
-
make docs-checkpasses on currentmain(fix any genuine issues found). - A broken Mermaid block or dead relative link fails the workflow.
- Duration ≤ 3 min.
- Tests listed below added and green in CI; coverage of new code meets the gate in doc 18 §3.
- Docs, config reference and CHANGELOG
Unreleasedupdated where behaviour, keys or interfaces changed. - Definition of Done (doc 32 §3) satisfied.
Tests required
- Workflow run on a PR touching docs.
Dependencies
Blocked by: #12 (T-001)
Blocks: no other task (leaf)
Parallelization notes
Files / paths owned by this task — avoid editing other paths; shared files (pyproject.toml entry points, cli/main.py, api/routers/__init__.py, router.tsx, docker/compose.yaml, ci.yml) are append-only:
scripts/check_docs.shscripts/check_mermaid.shscripts/check_adr_index.py.markdownlint.jsonclychee.toml.github/workflows/docs.yml- Makefile (docs-check)
Independent of all code tasks.
Definition of Done
Per doc 32 §3 and AGENTS.md §5: lint, format, mypy strict and import-linter green; tests added and passing; docs updated; PR template completed with Closes #<this issue>; Conventional Commit messages referencing T-006b (doc 16 §6); commits authored only by the repository owner identity (AGENTS.md §4); CI green; reviewer checklist (doc 32 §5.1) satisfied.
References
Design docs: doc 20 §1 · doc 18 §2 · doc 32 §7
Requirements: NFR-MNT-001 (traceability: doc 28)
External:
Metadata
Metadata
Assignees
Labels
Projects
- StatusShow more project fieldsDone
Activity
ci: address review - xargs -r, lychee path anchors, named status colu…
ci: render Mermaid files in parallel; move docs workflow to Node 24 a…
ci: resolve repo root from the script location so docs checks run fro…
16 remaining items
ci: render Mermaid files in parallel; move docs workflow to Node 24 a…
ci: resolve repo root from the script location so docs checks run fro…
docs: keep CHANGELOG markdownlint-clean after rebase (T-006b)
docs: markdownlint fix after rebase on T-003a (T-006b)
docs: fix Markdown rendering defects and markdownlint findings (T-006b)
ci: add docs quality gate - markdownlint, Mermaid render, lychee, ADR…
ci: address review - xargs -r, lychee path anchors, named status colu…
ci: render Mermaid files in parallel; move docs workflow to Node 24 a…
ci: resolve repo root from the script location so docs checks run fro…
docs: keep CHANGELOG markdownlint-clean after rebase (T-006b)
docs: markdownlint fix after rebase on T-003a (T-006b)