Skip to content

DOCUMENTATION-AUDIT.md

Latest commit

 

History

History
141 lines (113 loc) · 5.92 KB

DOCUMENTATION-AUDIT.md

File metadata and controls

141 lines (113 loc) · 5.92 KB
Raw

Documentation Audit

Last reviewed: 2026-07-08. Base branch: main.

This audit records the documentation sweep and remediation loop for this repository. It checks the docs as a system: entry points, root-level process and legal files, project scope, setup and validation notes, safety and privacy posture, architecture and planning docs, local links, and the places where code, tests, workflows, and docs meet.

Audit Results

Area Result Evidence
Entry docs pass README.md present
Security/process docs pass CONTRIBUTING.md, SECURITY.md, CHANGELOG.md
Architecture/planning docs pass 7 architecture/interface docs; 2 planning/research docs
Safety/privacy/audit docs pass 8 safety/privacy/accessibility/audit docs
Validation surface pass 35 test files; 6 workflow files
Local doc links pass 64 authored-doc links checked; 0 unresolved

Root-Level Documentation Audit

This section covers hand-authored documentation at the repository root and root-adjacent GitHub templates. It is separate from the docs/ inventory so README, process, legal, release, and project-specific root files do not get hidden inside the larger docs tree.

Surface Result Evidence
Root README pass Present: README.md
Root process docs pass Present: CONTRIBUTING.md, SECURITY.md, CHANGELOG.md
Root legal, citation, and conduct docs pass Present: LICENSE, NOTICE, CITATION.cff, CODE_OF_CONDUCT.md
Other root project docs info DEFINITION_OF_DONE.md
Root-adjacent GitHub templates pass .github/PULL_REQUEST_TEMPLATE.md, .github/CODEOWNERS
Root/template doc links pass 36 root-level/template links checked; 0 unresolved

Root-level files checked:

  • CHANGELOG.md
  • CITATION.cff
  • CODE_OF_CONDUCT.md
  • CONTRIBUTING.md
  • DEFINITION_OF_DONE.md
  • LICENSE
  • NOTICE
  • README.md
  • SECURITY.md

Root-adjacent template files checked:

  • .github/PULL_REQUEST_TEMPLATE.md
  • .github/CODEOWNERS

Remediation In This PR

  • Added missing root-level remediation docs found by the audit loop, including legal, conduct, contribution, or security files where absent.
  • Added docs/PROJECT-SCOPE.md as the plain-language project and boundary map.
  • Added this audit record so future doc changes have a dated baseline.
  • Added or refreshed the docs index so scope, audit, and primary docs are easy to find.
  • Fixed or added root/doc remediation files: NOTICE, docs/RESPONSIBLE-TECH-AUDITS.md.

Repo Surfaces Checked

Package and workspace metadata:

  • Python package queer-the-stacks (>=3.14).

Source and operations surfaces seen at the repo root:

  • app/
  • data/
  • docker-compose.yml
  • Dockerfile
  • Makefile
  • pyproject.toml
  • scripts/
  • tests/
  • uv.lock

Workflow files checked:

  • .github/workflows/ci.yml
  • .github/workflows/codeql.yml
  • .github/workflows/container-scan.yml
  • .github/workflows/scorecard.yml
  • .github/workflows/standards.yml
  • .github/workflows/zizmor.yml

Documentation Inventory

Category Count Representative files
architecture and interfaces 7 docs/adr/0000-record-architecture-decisions.md, docs/adr/0001-static-render-audited-by-structural-checker.md, docs/adr/0002-calibre-koreader-join-key.md, docs/adr/0003-auth-fails-closed.md, docs/adr/0004-python-314-floor.md, docs/adr/0005-flat-non-src-layout.md, docs/adr/0006-i18n-and-ai-evaluation-not-applicable.md
entry points and repo process 11 .github/CODEOWNERS, .github/PULL_REQUEST_TEMPLATE.md, .github/rulesets/README.md, CHANGELOG.md, CITATION.cff, CODE_OF_CONDUCT.md, CONTRIBUTING.md, LICENSE, plus 3 more
other docs 5 DEFINITION_OF_DONE.md, docs/I18N.md, docs/PROJECT-SCOPE.md, docs/README.md, docs/ethical-book-data-sources.md
planning and research 2 docs/ROADMAP-FUTURE.md, docs/ROADMAP.md
safety, privacy, accessibility, and audits 8 docs/DOCUMENTATION-AUDIT.md, docs/RESPONSIBLE-TECH-AUDITS.md, docs/audits/accessibility-2026-06-05.md, docs/audits/library-safety.md, docs/audits/reading-privacy.md, docs/audits/residual-risk.md, docs/audits/scorecard-2026-07.md, docs/audits/source-ethics.md

Full hand-authored doc inventory checked by this pass:

  • .github/CODEOWNERS
  • .github/PULL_REQUEST_TEMPLATE.md
  • .github/rulesets/README.md
  • CHANGELOG.md
  • CITATION.cff
  • CODE_OF_CONDUCT.md
  • CONTRIBUTING.md
  • DEFINITION_OF_DONE.md
  • LICENSE
  • NOTICE
  • README.md
  • SECURITY.md
  • docs/DOCUMENTATION-AUDIT.md
  • docs/I18N.md
  • docs/PROJECT-SCOPE.md
  • docs/README.md
  • docs/RESPONSIBLE-TECH-AUDITS.md
  • docs/ROADMAP-FUTURE.md
  • docs/ROADMAP.md
  • docs/adr/0000-record-architecture-decisions.md
  • docs/adr/0001-static-render-audited-by-structural-checker.md
  • docs/adr/0002-calibre-koreader-join-key.md
  • docs/adr/0003-auth-fails-closed.md
  • docs/adr/0004-python-314-floor.md
  • docs/adr/0005-flat-non-src-layout.md
  • docs/adr/0006-i18n-and-ai-evaluation-not-applicable.md
  • docs/audits/accessibility-2026-06-05.md
  • docs/audits/library-safety.md
  • docs/audits/reading-privacy.md
  • docs/audits/residual-risk.md
  • docs/audits/scorecard-2026-07.md
  • docs/audits/source-ethics.md
  • docs/ethical-book-data-sources.md

Link Check

  • Checked 64 local links in authored Markdown and MDX docs.
  • Unresolved authored-doc links after remediation: 0.
  • Root-level/template unresolved links after remediation: 0.

Validation Notes

  • The audit was generated from a clean worktree based on origin/main for this PR branch.
  • Ran a local relative-link check over hand-authored Markdown and MDX docs.
  • Ran an explicit root-level documentation presence and link check for README, process, legal, project, and template docs.
  • Ran git diff --check across the PR worktrees after remediation.
  • Product test suites remain the authority for runtime behavior; this PR changes documentation only.