AZ-013 — Documentation, translations and boundary gates

Status

Done

Context

Read README, documentation/CI/testing/DoD. Redocly, TypeDoc and marked generation already block defects in their configured scopes, but not comprehensive Markdown links, locale completeness, spelling, generated tracked files or layer imports. AZ-001 has translation parity tests, AZ-011 responsive/axe checks, and AZ-012 a new supply-chain gate. Normal project guides must now describe the implemented Application Zero rather than leave intentions only in specs.

Goal

Make documentation/resources and key repository boundaries verifiable with low-maintenance blocking checks, and leave a clear developer workflow for future ordering vertical slices.

Requirements

• Introduce offline root scripts i18n:check, docs:links:check, spellcheck and architecture:check, plus docs:site:check for generated-site completeness/links. Every check exits nonzero on actual violations or checker failure, never just emits a report. Put narrow scripts/tests in existing scripts/ and tests/ci/; reuse existing libraries or established tools rather than adding a documentation framework.
• i18n:check validates registered locales' exact key coverage, nonempty values and interpolation compatibility, including registered navigation/page keys. Reuse/extract AZ-001 validation, no second inconsistent locale policy. Include backend recovery template locale pairs only where their actual representation permits meaningful comparison. Detect typos in declared label keys through typing/resource validation, not regex-parsing arbitrary TSX calls.
• docs:links:check checks tracked Markdown targets/fragments and relevant document image paths against actual repo files/headings, respecting fenced code and normal relative links. Include original spec/DoD forwarding pointer, new epic/task dependency links and existing project docs. Use a maintained Markdown parser/link tool where it meets local-target needs; do not invent a heading algorithm inconsistent with GitHub/generated marked anchors. Narrow documented exemptions for special symbol URLs are acceptable, blanket spec exclusions are not.
• docs:site:check runs after pnpm docs:build, verifies required landing/project/API/reference outputs are nonempty and local generated links/fragments resolve (including raw spec paths). Test generation helpers/completeness with good/missing/broken fixtures. Generated HTML/vendor assets are checked as output, not copied into a new source of truth. Check rendered pages and raw sources appropriately; .md fragments in raw Markdown are not HTML fragments.
• Spelling uses compatible pinned CSpell with scoped English docs/code comments/UI resources, Swedish translation dictionary and small project terms. Exclude generated output, vendor assets, lockfile and credentials, not entire authored spec/docs trees. Preserve the original vertical-slice prose; legitimate historic spelling can receive a narrow documented exception. Spellcheck is not translation-quality proof or a reason to alter brand/technical vocabulary.
• Architecture check enforces actual boundaries with ESLint import restrictions or a maintained dependency-graph tool, not a bespoke regex rule engine. Reject frontend imports of backend/db, application/domain imports of Fastify/provider/DB implementations, and page/component direct fetch/URL handling bypassing app/api. Permit composition root/API/integration/repository responsibilities and test fakes deliberately. Configure actual current files/aliases, not nonexistent layer directories. Add negative/positive fixtures exercising the gate; don't just assert that a config file exists.
• Extend repository hygiene to reject tracked/force-added dist, coverage, docs-site, browser test results, local env and secrets-bearing previews while explicitly allowing committed Drizzle SQL/journal. Use Git tracked-file inventory, not .gitignore alone. Include this behavior in architecture:check or one explicitly introduced repository:check script; document actual choice, with fixtures for valid migrations and invalid tracked output.
• Wire offline i18n/links/spelling/boundary/hygiene checks into pnpm quality; keep its db-build, format/lint/type/OpenAPI/TypeDoc ordering and failure propagation. Static gate still needs no network/DB/Docker/secrets. Wire docs:site:check into the existing docs job after generation, before artifact upload. Docs publishing must run the same generated-site check before upload. Avoid adding a parallel job duplicating the complete quality command.
• External HTTP links are a weekly/manual non-blocking-for-PR check in the AZ-012 diagnostics workflow, with bounded timeout/retries and clear unavailable-versus-broken results. Pin any network link checker; don't break offline local quality on provider/network outages. An external-link diagnostics execution failure remains visible in that workflow.
• Preserve existing required jobs/artifacts and new AZ-012 gate; update fixture tests if upload preflight semantics change. No extra artifact mandatory just to store every tool's console text.
• Review normal guides against actual finished code, especially page workflow (create component, one declaration, icon, locale keys, tests), preference ownership, auth/provisioning/recovery, config/secrets/startup, integration/mock boundaries, logs and responsive testing. Amend relevant docs rather than copy the epic README wholesale. Keep source-of-truth responsibilities and significant ADRs intact. Update current-state/handover with remaining hosted evidence/next epic.
• Surface unresolved acceptance/verification issues honestly. This task does not certify all task semantics through file/checklist existence, call hosted deployment done without evidence, or add tests merely enforcing handover edit timestamps.

Non-goals

No new docs site framework, generated output in Git, complete semantic documentation automation, arbitrary coverage changes, generic architectural layer hierarchy, license policy, production deployment or new ordering functionality. JSX source is not standalone HTML; existing a11y/browser checks are the useful baseline, not a separate false-positive HTML source validator.

Implementation guidance

Respect marked's existing heading/link rewriting and TypeDoc public-entry-point policy. Resolve relative paths from their source doc, not checker process cwd; link fixtures should include nested specs, hashes, raw copies and same-heading duplicates. Architectural enforcement may integrate with ESLint and use an aggregate script to avoid a second lint ecosystem. Narrow exceptions must explain concrete current boundaries and cannot hide a real shortcut in production code.

Acceptance criteria

• Missing locale/navigation keys/interpolation defects, broken local links/anchors, scoped spelling errors, forbidden imports/API bypass and tracked generated output fail fixtures.
• Valid nested spec/forwarder/migration/public-API relationships pass without broad ignores.
• Offline pnpm quality runs the new checks; docs CI/publishing validate outputs before upload; scheduled external links remain out of blocking offline/PR gates.
• Existing checks/artifact/staging contracts remain intact and documented with the expanded gate inventory; actual frontend/auth/integration development workflows are clear.
• Current-state/handover distinguishes implemented capabilities, local evidence, hosted verification, remaining issues and the recommended next explicitly scoped domain epic.

Verification

pnpm quality
pnpm test:ci
pnpm i18n:check
pnpm docs:links:check
pnpm spellcheck
pnpm architecture:check
pnpm docs:build
pnpm docs:site:check

New commands are introduced here; constituent standalone executions are useful during development, not a requirement to repeat checks after final combined quality succeeds. If a separate repository:check is introduced, execute/document it too. Run pnpm test/affected builds/coverage only if executable source changes beyond checker tooling. Run periodic external checker on safe docs URLs once and record exact introduced script/results. Inspect generated epic/spec links and page-workflow docs with pnpm docs:serve. Hosted CI and Cloudflare upload evidence are required when publishing workflow changes; do not deploy manually without authorization.

Documentation

Update documentation (checks/heading/source ownership), development (aggregate/new commands and page recipe), CI/DoD enforcement mapping (actual new gates and limits), architecture/techstack, testing (checker fixture responsibility), current-state/handover. Other guide changes depend on facts found in the final consistency review; keep historic spec requirements separate from current implemented conventions.

Dependencies

AZ-011 and AZ-012 (therefore the complete prior feature and supply-chain branches).

Future considerations

With this foundation complete and verified, select a small Foodtruck Order domain slice explicitly. Do not add tenancy, a generic CRUD layer or another vendor as a documentation completeness exercise.