The audit map

Source chain

Every published artefact derives from a versioned source file in the public repository at github.com/SpeyTech/axilog.io (the site infrastructure) and github.com/SpeyTech/axioma-spec (the canonical specification source the Vault imports from). The repository is the audit-stable source of truth; every visible page corresponds to one or more files in version-controlled history.

For specifications specifically, three audit-trail surfaces align:

• Frontmatter date — the spec's effective date.
• Frontmatter changelog — the revision history declared by the author. Surfaced at /specs/<slug>/changelog/.
• Git commit history — every change to the spec file, accessible via the repository's blame and log views.

The build emits a warning when these surfaces disagree (a spec file's last git mtime exceeds its newest frontmatter changelog entry by more than one day). The check is informational; the discipline is editorial.

Build pipeline

The deploy is orchestrated by a single shell script, build.sh, which executes the steps below in order. Each step is gated:

• abort-deploy — failure prevents the atomic swap; the live site is unchanged.
• rollback — failure swaps the previous build back into place after the deploy has already happened.
• informational — failure is logged but the deploy continues. Used for non-correctness paths (e.g. IndexNow crawl-acceleration).

1. 1

   Compliance frontmatter lint

   abort-deploy

   scripts/compliance_lint.js

   Produces: Verified resolution of every spec's `compliance` frontmatter array against the canonical taxonomy at src/lib/compliance-taxonomy.ts.

   Walks every spec markdown file, extracts the compliance array, and verifies each value resolves to a canonical entry (matching id, displayName, or any alias). Runs before any rendering so unresolved values surface as data errors rather than as silent 404s on /compliance/<slug>/ pages. The taxonomy module is the single source of truth; adding a new standard requires adding a canonical entry there.

2. 2

   AEO frontmatter lint

   abort-deploy

   scripts/aeo_lint.js

   Produces: Verified `defines` and `answers` fields on every insight; Definition-block linter check for core concepts.

   Scoped to src/content/insights/ — specs are SHALL-bound formal prose and would fire false positives on every check. The linter enforces the AEO contract: every insight that defines a CORE_CONCEPT must include that concept verbatim in body text, and every insight must provide a 40–60-word `answers` field for llms-full.txt extraction.

3. 3

   Changelog drift check

   informational

   scripts/changelog_drift_check.js

   Produces: Warning report comparing each spec's git mtime against its frontmatter changelog's newest entry date.

   Per-spec, runs `git log -1 --format=%aI` against the file and compares against the maximum date in the frontmatter `changelog` array. Drift beyond one day surfaces as a build-log warning. Skipped (with explicit warning) on shallow clones — `git rev-parse --is-shallow-repository` returning `true` means the file-mtime data would be the shallow ceiling, producing false positives across the corpus.

4. 4

   Astro static build

   abort-deploy

   npx astro build --outDir ./dist.new

   Produces: The full static site under dist.new/: HTML for every route, the JSON-LD blocks, sitemap.xml, dynamic llms.txt and llms-full.txt, the compressed CSS and JS bundle.

   Output is written to dist.new/ rather than dist/ — the live build is untouched until the atomic swap step succeeds. Build into a staging directory means an Astro failure (broken schema, missing import, malformed markdown) leaves the production deploy intact.

5. 5

   Per-spec OG card generation

   abort-deploy

   scripts/generate-og-cards.mjs

   Produces: 15 PNG images at dist.new/og/specs/<slug>.png, each ~1200×630 with the spec id, title, layer pill, and dclass pill rendered from the brand woff2 fonts via the woff2→wawoff2→TTF→resvg pipeline.

   Pre-decompresses Inter Variable and JetBrains Mono Variable from woff2 to TTF (resvg-js does not natively decompress woff2; see operational lesson #23). Composes SVG with inline presentation attributes per text element (resvg <style> blocks are unreliable; see lesson #24). Failure on zero cards produced — would silently downgrade every spec's social-share preview to the splash default.

6. 6

   Per-spec PDF generation

   abort-deploy

   scripts/generate-pdfs.mjs

   Produces: 15 PDFs at dist.new/specs/<slug>.pdf, each with populated outline tree, tagged-PDF mode for accessibility, universal TOC with per-entry-correct page numbers, and pdf-lib metadata (Title, Author, Subject, Keywords, CreationDate, ModificationDate).

   Starts a transient HTTP server on 127.0.0.1:<ephemeral> over dist.new/, launches Playwright Chromium, navigates each spec page through the proxy origin to avoid file:// resolution failures on fonts and stylesheets. Cross-reference hyperlinks are rewritten from the navigation origin back to https://axilog.io before page.pdf() — without rewriting, every cross-ref in the PDF would embed the build-time loopback URL (operational lesson #34). TOC convergence is per-entry-equal via converge-loop algorithm; non-convergence within MAX_TOC_ITER=3 is a hard failure (shipping a wrong-page-number TOC is worse than no TOC).

7. 7

   Pagefind static search index

   abort-deploy

   npx pagefind --site ./dist.new

   Produces: WASM-indexed search payload under dist.new/pagefind/, including the index files, pagefind-ui.js, pagefind-ui.css, and the per-page chunks the browser fetches lazily.

   Runs after the PDF step so the corpus is final. Pagefind walks dist.new/, indexes the rendered HTML (post-Astro, post-compress), and writes the search payload alongside the rest of the site. The /search/ route consumes pagefind-ui.js at runtime; the index itself is fetched on first query. Failure aborts the build because shipping /search/ without a Pagefind index would mean a working search box returning zero results — worse than no search box.

8. 8

   Permission set

   abort-deploy

   sudo chown -R www-data:www-data dist.new

   Produces: dist.new/ owned by www-data:www-data, the nginx user. Required for the production server to read the swapped directory after the atomic swap.

   Runs after every output-producing step so no late-arriving file slips past the chown. The atomic swap step that follows performs a filesystem-level rename, preserving ownership.

9. 9

   Atomic swap

   rollback

   sudo mv dist dist.old && sudo mv dist.new dist

   Produces: Production dist/ now contains the new build; the previous build is preserved at dist.old/ for rollback.

   Filesystem-level rename. Single inode operation per `mv` call; no partial state visible to nginx. The rollback step on validation failure reverses the second `mv` first (preserving the new build at dist.failed/ for inspection), then restores dist.old/ as the live dist/.

10. 10

    Live-site SEO validator

    rollback

    scripts/seo_validator.py --domain axilog.io --nginx-config /etc/nginx/sites-available/axilog.io

    Produces: Verified live HTTP responses for every sitemap-listed URL, redirect-rule conformance, image-asset path validation, and CSP header presence. The validator runs against the newly-swapped dist/ — a post-deploy verification step, not a pre-build check.

    Both --domain and --nginx-config flags are required: the validator is shared across multiple vhosts and would mis-scope sections 20 and 21 (image redirects, redirect set verification) without explicit per-site arguments. Failure rolls back to dist.old/ via the script's explicit rollback branch, keeping the failed build at dist.failed/ for inspection. (Operational lesson #7.)

11. 11

    IndexNow change notification

    informational

    scripts/notify_indexnow.py

    Produces: Per-changed-URL notifications submitted to the IndexNow protocol endpoints (Bing, Yandex, others) so the new content is crawled promptly.

    Compares the new build's sitemap lastmod fields against dist.old/'s sitemap (preserved through the swap). URLs with newer lastmod are submitted as a single batch request. Failures are non-fatal — IndexNow is an acceleration, not a correctness path; search engines will discover the new content via normal crawl regardless.

12. 12

    Old-build cleanup

    informational

    sudo rm -rf dist.old

    Produces: dist.old/ removed. The rollback window for this deploy closes at this point.

    Runs in the background (`&` suffix). The previous build's footprint is freed; if a defect is detected after this step, recovery is by re-deploy of the previous commit from git, not by directory restoration.

13. 13

    Git push to GitHub

    informational

    git push

    Produces: Public commit on the SpeyTech/axilog.io repository recording the build state and any content changes from this deploy.

    Records the deploy in the public history. A failed push (network, auth, divergent remote) does not undo the deploy — the live site is already updated. Recovery is to investigate and push manually.

Artefact lineage

The orthogonal cut: for every output the site publishes, the source it derives from, the pipeline step that produces it, and the audit-stable property that holds for the artefact.

Compliance chain

Every compliance claim in any spec's frontmatter resolves to a canonical entry in src/lib/compliance-taxonomy.ts. The taxonomy is the audit-stable identifier; the per-spec declaration is the audit evidence. The chain that takes a frontmatter declaration to a published claim:

1. 1. Spec author declares compliance in frontmatter: e.g. `compliance: [DO-178C, IEC 62304]`.
2. 2. Build-time linter (scripts/compliance_lint.js) verifies every value resolves to a canonical entry in src/lib/compliance-taxonomy.ts — by id, displayName, or alias. Build aborts on any unresolved value.
3. 3. SpecHeader renders the resolved displayName as a link to /compliance/<slug>/, using the canonical taxonomy's slug.
4. 4. TechArticle JSON-LD emits each as a DefinedTerm with inDefinedTermSet pointing at the on-site /compliance/<slug>/ page.
5. 5. /compliance/ index emits a card per declared standard; /compliance/<slug>/ lists every declaring spec, layer-grouped.
6. 6. llms.txt emits a Compliance section enumerating each standard with the count and IDs of declaring specs; llms-full.txt emits a `Compliance:` line per spec.

The shipped surface: see /compliance/ for the standards declared across the corpus today, and any specific spec's meta-list for the per-spec declarations.

Cryptographic chain

This section is honest about what is and is not anchored cryptographically in the published form. Aspirational claims here would damage the project's reputation more than their absence does.

• Git commit history shipped

  Every source change to the spec corpus is committed to the SpeyTech/axilog.io repository. Commits are signed where the maintainer has signing keys configured for the relevant remote.

• PDF /CreationDate and /ModificationDate metadata shipped

  /CreationDate is taken from the spec's frontmatter date (the document's effective date); /ModificationDate is the build time at which the PDF was rendered. Both written by pdf-lib at PDF assembly time. Verifiable with any PDF reader's metadata inspector.

• PDF cryptographic signing (PAdES/PKCS#7) planned

  Tracked as roadmap item pdf-archival-hardening. The signing infrastructure (signing key generation, key custody, certificate chain) is not yet established; published PDFs are reproducible from source but not cryptographically anchored in the published form. The honest claim today is "PDF integrity is verifiable by re-rendering against the corresponding commit".

• Substrate audit chain (libaxilog ledger) shipped

  The Axioma substrate itself maintains a SHA-256-rooted audit ledger across L6 (SRS-001). The site documents this; the verification of any specific run's ledger is via the substrate, not via the site.

Reproducibility

The site build is deterministic in the engineering sense: the same source, the same dependency set, and the same build.sh invocation produce byte-identical output. The only inputs that vary between builds at the same commit are:

• The build time. Surfaced in PDF /ModificationDate, the per-PDF attribution footer, and the sitemap's build-time-fallback <lastmod> for aggregated views.
• Per-page <lastmod> in the sitemap — derived from each artefact's source frontmatter, so the value at any given commit is also deterministic.

To reproduce a published spec's HTML, clone the repository at the commit identified by the spec page's blame, run npm ci against the lock-file at that commit, and run build.sh in an equivalent environment. The resulting dist/specs/<slug>/index.html should match the live page modulo the build-time fields named above.