Skip to content

Specification — wf-04-01

US-04-01-01 — Emit a CI-Friendly Assembly Log

As a DevOps engineer, I want a machine-readable log during assembly, so that I can capture deterministic build evidence and diagnose include-related failures in CI.

REQ-00-00-00-03 — Machine-Readable Diagnostics

When arqix emits a diagnostic, arqix SHALL provide it in a documented machine-readable format.

Coverage: verified.

REQ-00-00-00-06 — Effective Configuration as Baseline

The arqix CLI SHALL resolve every command against the effective configuration.

Coverage: verified.

REQ-04-01-01-01 — Collect Assembly Log as CI Artefact

The assembly log SHOULD be collectable as a CI artefact without post-processing or field-name guessing.

Coverage: verified.

REQ-04-01-01-02 — Write JSONL Log during Assembly

When arqix assemble build runs, arqix SHALL write a JSONL log during assembly.

Coverage: verified.

REQ-04-01-01-03 — Configure Assembly Log Path

The assembly log path SHALL be configurable.

Coverage: uncovered.

REQ-04-01-01-04 — Emit One Record per Assembly Step

When an assembly step executes, arqix SHALL emit exactly one stable JSONL record for it.

Coverage: uncovered.

REQ-04-01-01-05 — Carry Required Fields in Log Records

Each assembly log record SHALL contain at least doc, chapter_id, out, include, sha256, bytes, and at_line.

Coverage: uncovered.

US-04-01-03 — Generate Publishing Outputs

As a DevOps engineer, I want to generate publishing outputs, so that documentation can be published as PDF and/or a website through deterministic automation.

REQ-00-00-00-06 — Effective Configuration as Baseline

The arqix CLI SHALL resolve every command against the effective configuration.

Coverage: verified.

REQ-04-01-03-01 — Generate Publishing Outputs

When arqix publish runs, arqix SHALL generate publishing outputs for the configured PDF or website targets.

Coverage: verified.

REQ-04-01-03-02 — Keep Assembled Pages Artefact-Ready

The assembled pages SHALL be artefact-ready for downstream publishing.

Coverage: verified.

REQ-04-01-03-03 — Orchestrate Site Builds when Configured

Where site build orchestration is configured, arqix SHALL orchestrate the site build.

Coverage: verified.

REQ-04-01-03-04 — Render PDF via Pandoc

When arqix render pdf runs, arqix SHALL invoke Pandoc on the assembled pages or the selected Markdown files.

Coverage: verified.

REQ-04-01-03-05 — Support Pandoc Defaults and Eisvogel

The arqix CLI SHALL support Pandoc --defaults files and the eisvogel template option when configured.

Coverage: verified.

REQ-04-01-03-06 — Store Render Artefacts per Artefact Mode

When render artefacts are produced, arqix SHALL store them according to the configured artefact mode.

Coverage: verified.

REQ-04-01-03-07 — Forward Render Tool Errors Transparently

If an external rendering tool fails, then arqix SHALL forward the tool error transparently.

Coverage: verified.

REQ-04-01-03-08 — Support per-Package Render Configuration

The arqix CLI SHALL support per-doc-package render configuration and overrides.

Coverage: verified.

REQ-04-01-03-09 — Render One PDF per Document

When rendering a PDF, arqix SHALL produce one artefact per top-level document.

Coverage: verified.

US-04-01-05 — Run a One-Command Verification Loop

As a DevOps engineer, I want a single arqix command to run the standard verification loop, so that automation and CI can validate changes with one deterministic invocation.

REQ-00-00-00-02 — Stable Exit Codes

The arqix CLI SHALL signal command outcomes through documented, stable exit codes.

Coverage: verified.

REQ-00-00-00-03 — Machine-Readable Diagnostics

When arqix emits a diagnostic, arqix SHALL provide it in a documented machine-readable format.

Coverage: verified.

REQ-00-00-00-06 — Effective Configuration as Baseline

The arqix CLI SHALL resolve every command against the effective configuration.

Coverage: verified.

REQ-00-00-00-12 — Bounded Verification Loop Time

The verification loop SHOULD complete within ten seconds on a repository of one thousand documents.

Coverage: verified.

REQ-04-01-05-01 — Run Configured Verification Sub-Steps

When arqix verify runs, arqix SHALL execute the configured sub-steps of format, lint, trace scan, and coverage.

Coverage: verified.

REQ-04-01-05-02 — Support Fail-Fast and Aggregate Modes

The verification loop SHALL support fail-fast and aggregate result modes, selected by configuration.

Coverage: verified.

REQ-04-01-05-03 — Emit per-Step Results in JSON Mode

Where JSON mode is enabled, the verification loop SHALL emit per-step results and diagnostic references.

Coverage: verified.

US-04-01-06 — Build Deterministic Page Artefacts in CI

As a DevOps engineer, I want to assemble a doc package into pages, so that stable publishable artefacts can be produced automatically in CI.

REQ-00-00-00-06 — Effective Configuration as Baseline

The arqix CLI SHALL resolve every command against the effective configuration.

Coverage: verified.

US-04-01-07 — Publish Language-Aware Sites

As a DevOps engineer, I want to publish documentation sites per language using arqix, with Zensical as the first supported site toolchain, so that bilingual documentation can be built and deployed deterministically in CI.

REQ-00-00-00-02 — Stable Exit Codes

The arqix CLI SHALL signal command outcomes through documented, stable exit codes.

Coverage: verified.

REQ-00-00-00-03 — Machine-Readable Diagnostics

When arqix emits a diagnostic, arqix SHALL provide it in a documented machine-readable format.

Coverage: verified.

REQ-00-00-00-06 — Effective Configuration as Baseline

The arqix CLI SHALL resolve every command against the effective configuration.

Coverage: verified.

REQ-04-01-07-01 — Publish Sites per Language

When arqix publish site is invoked with a language, arqix SHALL build the site from that language's configured root and write outputs to that language's artefact target.

Coverage: verified.

REQ-04-01-07-02 — Diagnose Site Toolchain Failures

If the site toolchain fails, then arqix SHALL return exit code 2 with diagnostics identifying the failing tool invocation context.

Coverage: verified.

REQ-04-01-07-03 — Omit Included Fragments from Standalone Staging

When publishing the site, arqix SHALL NOT stage a document that another published page includes and no corpus page links to; a linked include target stays a standalone page.

Coverage: verified.

REQ-04-01-07-04 — Stage Assets at Document-Relative Paths

When staging a configured asset that lives under a doc root's language directory, arqix SHALL place it at the same language-root-relative path as the staged pages.

Coverage: verified.

REQ-04-01-07-05 — Stage into a Clean Tree

When arqix publish site stages a language, arqix SHALL remove that language's previously staged tree first.

Coverage: verified.

US-04-01-08 — Provide Consistent Exit Codes for CI Gates

As a DevOps engineer, I want consistent exit codes and CI support, so that automation can react to arqix reliably.

REQ-00-00-00-02 — Stable Exit Codes

The arqix CLI SHALL signal command outcomes through documented, stable exit codes.

Coverage: verified.

REQ-04-01-08-01 — Pin the Exit-Code Contract

The arqix CLI SHALL use exit code 0 for success, 1 for lint or quality-gate failure, and 2 for usage error.

Coverage: uncovered.

REQ-04-01-08-02 — Separate Command Errors from Quality Failures

The stderr messaging SHALL let CI distinguish command errors from quality failures.

Coverage: uncovered.

REQ-04-01-08-03 — Ship a Minimal CI Workflow Template

The arqix CLI MAY ship a minimal GitHub Actions template for typical gates, aligned with supported commands only.

Coverage: uncovered.

US-04-01-10 — Emit Machine-Readable Diagnostics for CI

As a DevOps engineer, I want arqix commands to emit machine-readable diagnostics, so that CI can classify failures reliably and surface actionable build feedback without scraping human-oriented output.

REQ-00-00-00-02 — Stable Exit Codes

The arqix CLI SHALL signal command outcomes through documented, stable exit codes.

Coverage: verified.

REQ-00-00-00-03 — Machine-Readable Diagnostics

When arqix emits a diagnostic, arqix SHALL provide it in a documented machine-readable format.

Coverage: verified.

REQ-04-01-10-01 — Accept a JSON Format Option per Command

Each supported command SHALL accept --format json or an equivalent option to emit JSON diagnostics.

Coverage: verified.

REQ-04-01-10-02 — Carry Required Fields in JSON Diagnostics

JSON diagnostics SHALL include at least severity, code, message, source.path, and source.line where available.

Coverage: uncovered.

US-04-01-12 — Publish Stable Report Exports for Automation

As a DevOps engineer, I want stable compliance-ready report exports, so that CI and release automation can attach reviewable report packages without manual post-processing.

REQ-00-00-00-03 — Machine-Readable Diagnostics

When arqix emits a diagnostic, arqix SHALL provide it in a documented machine-readable format.

Coverage: verified.

REQ-04-01-12-01 — Support Audit Export Formats

Audit-oriented report exports SHALL support at least Markdown, CSV, and JSON where applicable.

Coverage: verified.

REQ-04-01-12-02 — Keep Export Schemas Stable

Export schemas and column ordering SHALL remain stable across runs.

Coverage: verified.

REQ-04-01-12-03 — Record Report Generation Metadata

Report metadata SHALL record the generation time, scope, and source inputs.

Coverage: verified.

REQ-04-01-12-04 — Snapshot and Gate Report Units

When arqix report snapshot runs, arqix SHALL regenerate the committed report units from the trace graph and exit non-zero under --check when any committed unit is stale.

Coverage: verified.

US-04-01-13 — Publish Navigable Architecture Views Deterministically

As a DevOps engineer, I want architecture narratives to assemble into a navigable documentation view, so that publish automation can validate and ship coherent architecture outputs deterministically.

REQ-04-01-13-01 — Assemble Architecture Units in Predictable Order

When architecture source units are assembled, arqix SHALL produce a predictable chapter order.

Coverage: uncovered.

Cross-links between ADRs, glossary terms, and architecture pages SHALL resolve consistently in assembled outputs.

Coverage: uncovered.

REQ-04-01-13-03 — Report Broken Architecture Navigation

When publish validation runs, arqix SHALL report broken architecture navigation paths.

Coverage: uncovered.

US-04-01-14 — Configure the Verification Loop

As a DevOps engineer, I want to configure which sub-steps arqix verify runs and how each result is treated, so that the loop fits the repository's lifecycle stage instead of blocking healthy spec-first states.

REQ-04-01-14-01 — Run Configured Verify Sub-Steps

When arqix verify is invoked, arqix SHALL run the sub-steps declared in the effective configuration in their configured order.

Coverage: verified.

REQ-04-01-14-02 — Report Informational Sub-Steps without Gating

Where a verify sub-step is configured as informational, arqix SHALL report its findings without affecting the exit code.

Coverage: verified.

REQ-04-01-14-03 — Default Coverage to Informational

The default verify configuration SHALL treat coverage as informational and every other sub-step as gating.

Coverage: verified.

REQ-04-01-14-04 — Run the Corpus Checks in Verify

When arqix verify runs, arqix SHALL run the requirements, frontmatter, trace-marker, and report-freshness corpus checks as sub-steps of the configured profile.

Coverage: verified.

REQ-04-01-14-05 — Gate Report Freshness by Snapshot Strategy

Where the configured snapshot strategy does not gate report freshness in the current context, arqix verify SHALL skip the report-freshness sub-step.

Coverage: verified.

US-04-01-15 — Gate Coverage as a Ratchet

As a DevOps engineer, I want changes that reduce verified coverage to fail the gate, so that specification growth stays free while regressions cannot land silently.

REQ-04-01-15-01 — Fail the Ratchet on Coverage Regression

When verified coverage decreases against the configured baseline, arqix SHALL fail the coverage ratchet with findings that name each regressed requirement.

Coverage: verified.

REQ-04-01-15-02 — Pass the Ratchet without Regression

When a change does not reduce the set of verified requirements, the coverage ratchet SHALL pass.

Coverage: verified.

US-04-01-16 — Configure the Snapshot Strategy

As a builder, I want the report snapshot strategy and the ratchet baseline source declared in configuration, so that parallel branches are not forced into a rebase-before-merge dance by committed snapshots unless the repository chooses that trade-off.

REQ-04-01-16-01 — Read the Ratchet Baseline from Configuration

Where the verify policy declares a ratchet baseline path, arqix SHALL compare the coverage ratchet against that baseline.

Coverage: verified.

US-04-01-17 — Publish the Specification as Catalogue Pages

As an assessor, I want the published site to carry the specification as bundled catalogue pages, so that I can read and link every story and requirement with its live coverage status without wading through hundreds of single source pages.

REQ-04-01-17-01 — Stage Catalogue Pages per Workflow Group

Where the publish policy enables the specification catalogue, arqix publish site SHALL stage generated catalogue pages that bundle the story and requirement sources one page per workflow group.

Coverage: verified.

REQ-04-01-17-02 — Anchor IDs and Carry Coverage Status

Each catalogue entry SHALL carry an anchor for its ID and, for requirements, the coverage status from the trace graph.

Coverage: verified.

REQ-04-01-17-03 — Generate the Catalogue Deterministically

When the corpus is unchanged, repeated staging SHALL produce byte-identical catalogue pages.

Coverage: verified.

US-04-01-18 — Render Architecture Views from the Model

As a builder, I want the C4 views generated from workspace.dsl as committed images and embedded in the docs, so that a view cannot drift from the model — there is no hand-authored diagram left to drift.

REQ-04-01-18-01 — Render Views from the Model

The published architecture views SHALL be rendered from the C4 model rather than hand-authored.

Coverage: verified.

REQ-04-01-18-02 — Gate Architecture-Image Freshness

When a committed architecture-view image differs from a fresh render of the model, the verification gate SHALL fail.

Coverage: planned.

US-04-01-19 — Publish CSV Artefacts as Readable Tables

As a builder, I want the corpus CSV artefacts published as readable table pages, so that the trace matrices and data exports are browsable on the site instead of missing from it.

REQ-04-01-19-01 — Stage CSV Artefacts as Table Pages

When arqix publish site stages the corpus, arqix SHALL stage every corpus CSV artefact as a Markdown page rendering the CSV rows as a table.

Coverage: verified.

When arqix publish site stages a corpus page, arqix SHALL rewrite the page's relative CSV links to the staged table pages.

Coverage: verified.