Specification — wf-02-01¶
US-02-01-03 — Format Documents During Implementation¶
As a developer, I want to format documents canonically, so that I can keep documentation clean during implementation without wasting time on formatting debates.
REQ-00-00-00-06 — Effective Configuration as Baseline¶
The arqix CLI SHALL resolve every command against the effective configuration.
Coverage: verified.
REQ-01-01-03-01 — Sort Frontmatter Keys Canonically¶
When arqix fmt runs, arqix SHALL sort frontmatter keys according to the configured key_order.
Coverage: verified.
REQ-01-01-03-02 — Normalise Directives without Semantic Changes¶
When arqix fmt runs, arqix SHALL normalise directives, including attribute order and whitespace, without semantic changes.
Coverage: verified.
REQ-02-01-03-01 — Keep Formatted Diffs Content-Focused¶
The formatting output SHOULD keep document diffs focused on content rather than incidental style changes.
Coverage: verified.
US-02-01-06 — Find and Read Documentation During Implementation¶
As a developer, I want to search and read documentation, so that I can quickly find relevant requirements, ADRs, and handbook content while implementing changes.
REQ-00-00-00-11 — Fast Documentation Retrieval¶
Search and read commands SHOULD return results within one second on a repository of one thousand documents.
Coverage: verified.
REQ-02-01-06-01 — Provide Full-Text Search¶
The arqix CLI SHALL provide full-text search over the documentation.
Coverage: verified.
REQ-02-01-06-02 — Read Documents by ID¶
When arqix doc read is invoked with a document ID, arqix SHALL return the document, optionally scoped to a section or anchor.
Coverage: uncovered.
REQ-02-01-06-03 — Fail Clearly on Missing Documents or Anchors¶
If a document or anchor cannot be found, then arqix SHALL fail with a diagnostic naming the missing element.
Coverage: uncovered.
US-02-01-09 — Use Include Directives During Implementation¶
As a developer, I want to use include directives in Markdown, so that I can create documentation incrementally during development and assemble it reliably into larger documents.
REQ-00-00-00-06 — Effective Configuration as Baseline¶
The arqix CLI SHALL resolve every command against the effective configuration.
Coverage: verified.
REQ-02-01-09-01 — Parse Include Directives with Level Arguments¶
The arqix CLI SHALL parse <!-- arqix:include ... --> directives, including their optional heading-level argument.
Coverage: verified.
REQ-02-01-09-03 — Expand Glob Includes with Configured Sorting¶
When a glob include is expanded, arqix SHALL apply the configured sorting.
Coverage: uncovered.
US-02-01-10 — Scaffold Translations During Implementation¶
As a developer, I want to create a translation document by referencing its source document ID, so that translations are created with correct routing, metadata, and structure without manual setup.
REQ-00-00-00-09 — Dry-Run Support¶
Where a command creates or modifies files, the command SHALL support a dry-run mode that reports planned changes without writing.
Coverage: verified.
REQ-02-01-10-01 — Create Translation Files at Layout Location¶
When a translation is scaffolded, arqix SHALL create the translation file at the location the chosen i18n layout defines.
Coverage: uncovered.
REQ-02-01-10-02 — Link Translations to Their Source ID¶
When a translation is scaffolded, arqix SHALL write metadata linking the translation to its source document ID.
Coverage: uncovered.
REQ-02-01-10-03 — Fail Clearly on Missing Translation Source¶
If the source document cannot be found, then the translation scaffolding SHALL fail with a clear diagnostic.
Coverage: uncovered.
REQ-02-01-10-04 — Preserve Markup in Translation Scaffolds¶
When a translation is scaffolded, arqix SHALL preserve arqix markup directives and structural elements according to the scaffold strategy.
Coverage: uncovered.
US-02-01-11 — Assemble Documentation During Implementation¶
As a developer, I want to assemble a doc package into pages, so that I can preview publishable documentation built from units while implementing changes.
REQ-00-00-00-06 — Effective Configuration as Baseline¶
The arqix CLI SHALL resolve every command against the effective configuration.
Coverage: verified.
REQ-02-01-11-01 — Generate Assembled Outputs under Pages¶
When arqix assemble build runs for a doc package, arqix SHALL generate the assembled outputs under pages/.
Coverage: verified.
REQ-02-01-11-02 — Strip Frontmatter on Include when Enabled¶
Where strip_frontmatter_on_include is enabled, arqix SHALL strip frontmatter from included content.
Coverage: uncovered.
REQ-02-01-11-03 — Fail Clearly on Include Cycles¶
If an include cycle is detected, then arqix SHALL fail with a clear error message.
Coverage: verified.
US-02-01-12 — Stitch Fragments at Declared Heading Levels¶
As a developer, I want an include directive to place the fragment's headings at a declared level, absolute or relative, so that units of any granularity compose into a coherent outline wherever they are included.
REQ-02-01-12-01 — Shift Included Headings to the Declared Level¶
When an include directive declares a heading level, arqix SHALL shift every heading of the included fragment by the delta between the declared level and the fragment's first heading.
Coverage: verified.
REQ-02-01-12-02 — Resolve Relative Levels at the Include Position¶
When an include directive declares a relative heading level, arqix SHALL resolve it against the heading level in effect at the include position.
Coverage: verified.
REQ-02-01-12-03 — Fail on Heading Overflow¶
If a heading shift would exceed level six, then arqix SHALL fail the assembly with a diagnostic naming the fragment and the heading.
Coverage: verified.
REQ-02-01-12-04 — Apply the Configured Heading Ownership Default¶
Where no heading level is declared on an include directive, arqix SHALL apply the configured heading-ownership default.
Coverage: verified.
REQ-02-01-12-05 — Omit Included Fragment Frontmatter¶
When arqix stitches an included fragment into a document, it SHALL omit the fragment's YAML frontmatter from the assembled output.
Coverage: verified.