Specification — wf-01-01¶

US-01-01-01 — Initialise Standardised Doc Package¶

As a maintainer, I want to initialise a new doc package with a standardised directory structure, so that I can build documentation consistently and reproducibly.

REQ-00-00-00-04 — Deterministic IDs and Slugs¶

The arqix CLI SHALL derive document IDs and slugs deterministically from the configured policy.

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-01-01-01-01 — Create Standard Doc-Package Scaffold¶

When arqix doc init <path> is invoked, arqix SHALL create the standard doc-package scaffold with index.md, units/, pages/, artefacts/, logs/, and .arqix/.

Coverage: verified.

REQ-01-01-01-02 — Write Doc-Index Frontmatter on Init¶

When a doc package is initialised, arqix SHALL write index.md frontmatter containing id, kind=doc_index, and title.

Coverage: verified.

REQ-01-01-01-03 — Provide a Top-Level Init Alias¶

The arqix CLI SHOULD provide a top-level init alias that behaves exactly like doc init.

Coverage: verified.

US-01-01-02 — Create Governed Units¶

As a maintainer, I want to create units with governed metadata and uniqueness rules, so that I can keep modular documentation consistent and lintable across the repository.

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-02-01 — Create Unit Files in Configured Location¶

When arqix unit new is invoked, arqix SHALL create a unit file in the configured unit location.

Coverage: uncovered.

REQ-01-01-02-02 — Support Global Unit IDs¶

The arqix CLI SHALL support unit files that declare a global ID in frontmatter or via a supported directive.

Coverage: uncovered.

REQ-01-01-02-03 — Explain Unit Creation in Command Help¶

The unit new command help SHOULD explain where units are created, which metadata is optional, and how IDs are supplied.

Coverage: verified.

US-01-01-03 — Format Documents Canonically¶

As a maintainer, I want to format documents canonically, so that diffs stay small and conventions are applied automatically.

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.

US-01-01-04 — Lint Documents Deterministically¶

As a maintainer, I want to lint documents, so that errors in includes, metadata, and IDs are found early and deterministically.

REQ-00-00-00-04 — Deterministic IDs and Slugs¶

The arqix CLI SHALL derive document IDs and slugs deterministically from the configured policy.

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-01-01-04-01 — Check Include Targets Exist¶

When arqix lint run executes, arqix SHALL verify that include targets exist.

Coverage: verified.

REQ-01-01-04-02 — Report Forbidden Frontmatter Keys in Units¶

When arqix lint run executes, arqix SHALL report forbidden frontmatter keys in units according to the configured allowlist.

Coverage: uncovered.

REQ-01-01-04-03 — Report Duplicate IDs Globally¶

When arqix lint run executes, arqix SHALL report duplicate IDs globally across units, requirements, user stories, ADRs, and glossary entries.

Coverage: verified.

REQ-01-01-04-04 — Report Lint Findings with File and Line Context¶

When a lint check reports a finding, the diagnostic SHALL include precise file and line context.

Coverage: verified.

REQ-01-01-04-05 — Fail on Invalid Lint Input¶

If lint input is invalid, then arqix SHALL return a failing status.

Coverage: uncovered.

US-01-01-05 — Create Documents from Configured Templates¶

As a maintainer, I want to create documents from templates, so that new artefacts such as requirements, user stories, and ADRs are compliant from the start.

REQ-00-00-00-04 — Deterministic IDs and Slugs¶

The arqix CLI SHALL derive document IDs and slugs deterministically from the configured policy.

Coverage: verified.

REQ-00-00-00-05 — Template-Governed Document Creation¶

When a document is created, arqix SHALL instantiate the configured template for the requested kind.

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-01-01-05-01 — Accept Only Configured Document Kinds¶

The arqix CLI SHALL accept only <kind> values that are defined in configuration.

Coverage: uncovered.

REQ-01-01-05-02 — Provide Creation Aliases for Common Kinds¶

The arqix CLI SHOULD provide the aliases req new, us new, and adr new for template-based creation.

Coverage: verified.

REQ-01-01-05-03 — Substitute Template Placeholders¶

When a document is created from a template, arqix SHALL substitute the placeholders {title}, {slug}, and {id}.

Coverage: uncovered.

US-01-01-06 — Finalise Document Metadata Mechanically¶

As a maintainer, I want to mechanically finalise metadata, so that updated is set consistently without rewriting content.

REQ-01-01-06-01 — Set Updated as ISO Date on Finalise¶

When arqix finalise runs, arqix SHALL set updated to an ISO-8601 date in YYYY-MM-DD format.

Coverage: verified.

REQ-01-01-06-02 — Avoid Rewriting Current Metadata¶

If a metadata value is already current, then arqix finalise SHALL NOT rewrite it.

Coverage: verified.

REQ-01-01-06-03 — Fail Clearly on Unsupported Frontmatter¶

If a file has no supported frontmatter, then arqix finalise SHALL fail with a clear diagnostic.

Coverage: verified.

US-01-01-07 — Enforce Scope Guardrails for Automation Agents¶

As a maintainer, I want enforceable guardrails for automation agents that limit modifications to a declared scope such as files, directories, and story boundaries, so that agent contributions remain reviewable and do not cause opportunistic repository-wide churn.

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-01-01-07-01 — Declare Change Scope in Policy Files¶

The arqix CLI SHALL support a policy file in minimal YAML or TOML that declares the allowed change scope.

Coverage: verified.

REQ-01-01-07-02 — Evaluate Changed Files against Policy¶

When arqix policy check is invoked with a list of changed files, arqix SHALL evaluate them against the declared policy.

Coverage: verified.

REQ-01-01-07-03 — Support Warn-Only Policy Mode¶

Where warn-only mode is configured, arqix policy check SHALL report violations without failing.

Coverage: verified.

US-01-01-08 — Generate Governed Coverage Reports¶

As a maintainer, I want to generate coverage reports, so that missing links are surfaced early and documentation quality stays enforceable over time.

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-01-01-08-01 — Identify Requirements without Verifying Tests¶

When arqix trace coverage runs, arqix SHALL identify requirements without verifies tests.

Coverage: verified.

REQ-01-01-08-02 — Identify Requirements without Implementing Code¶

When arqix trace coverage runs, arqix SHALL identify requirements without implements code.

Coverage: uncovered.

REQ-01-01-08-03 — Support Markdown and JSON Coverage Output¶

The coverage report SHALL support at least Markdown and JSON output formats.

Coverage: verified.

US-01-01-09 — Govern Agent Workflow Document Standards¶

As a maintainer, I want the agent instruction and plan documents to follow a standardized structure and editing policy, so that automation workflows remain predictable, reviewable, and aligned with repository standards regardless of which coding agent executes them.

REQ-01-01-09-04 — Keep Workflow Documents Unambiguous¶

The agent instruction and plan document structures SHOULD be explicit enough that an agent can follow them without guessing process constraints.

Coverage: uncovered.

REQ-01-01-09-05 — Document Agent-Specific Extension Points¶

When a coding agent is supported, its agent-specific extension points SHALL be documented.

Coverage: uncovered.

US-01-01-10 — Define Schema-Backed Metadata Contracts¶

As a maintainer, I want schema-backed metadata contracts for each document kind, so that frontmatter drift is caught early and templates remain enforceable over time.

REQ-00-00-00-05 — Template-Governed Document Creation¶

When a document is created, arqix SHALL instantiate the configured template for the requested kind.

Coverage: verified.

REQ-01-01-10-01 — Declare Metadata Contracts per Document Kind¶

The arqix CLI SHALL support schema contracts that declare required and optional metadata fields per document kind.

Coverage: uncovered.

REQ-01-01-10-02 — Report Metadata Contract Violations¶

When lint validates metadata against a contract, arqix SHALL report missing, extra, and type-invalid fields.

Coverage: uncovered.

US-01-01-11 — Govern Architecture Documentation Standards¶

As a maintainer, I want architecture and governance documentation to follow the same standards and assembly rules as product documentation, so that documentation governance remains consistent across the repository.

REQ-01-01-11-04 — C4-Oriented Architecture Views¶

Architecture views SHOULD present the C4 model in a C4-oriented modelling style.

Coverage: verified.

REQ-01-01-11-05 — Document Consistency-Check Extension Path¶

The architecture documentation SHOULD record a future documentation consistency check as an extension path.

Coverage: verified.

REQ-01-01-11-06 — Validate Requirement Authoring Rules¶

When arqix lint requirements runs, arqix SHALL report every requirement document whose identity, kind, required metadata, or derivation links violate the corpus scheme and every normative sentence that departs from the RFC 2119 subset and EARS patterns of the requirements style guide.

Coverage: verified.

REQ-01-01-11-07 — Validate Frontmatter and Ontology Contracts¶

When arqix lint frontmatter runs, arqix SHALL report every architecture and ontology document whose frontmatter, canonical formatting, or ontology-vocabulary use violates the declared corpus contract.

Coverage: verified.

REQ-01-01-11-08 — Validate Story Workflow Membership¶

When arqix lint requirements runs, arqix SHALL report every user story whose id does not encode the workflow named by its is-part-of-workflow triple.

Coverage: verified.

REQ-01-01-11-09 — Validate Story Persona Workflow Coupling¶

When arqix lint requirements runs, arqix SHALL report every user story that names a persona which is neither declared on the story's workflow nor marked as a consolidation persona.

Coverage: verified.

US-01-01-12 — Govern Glossary Term Metadata and IDs¶

As a maintainer, I want glossary terms to be scaffolded with stable IDs and linted metadata, so that terminology artefacts remain compliant and traceable across the repository.

REQ-00-00-00-04 — Deterministic IDs and Slugs¶

The arqix CLI SHALL derive document IDs and slugs deterministically from the configured policy.

Coverage: verified.

REQ-01-01-12-01 — Scaffold Glossary Terms with Required Metadata¶

When arqix doc new glossary is invoked, arqix SHALL create a glossary term with the required metadata and route it to the configured location.

Coverage: uncovered.

REQ-01-01-12-02 — Reference Glossary Terms by Stable ID¶

The arqix CLI SHALL support referencing glossary terms by stable ID from ADRs and other documents.

Coverage: uncovered.

REQ-01-01-12-03 — Detect Duplicate or Malformed Glossary IDs¶

When arqix lint run executes, arqix SHALL detect duplicate or malformed glossary IDs.

Coverage: uncovered.

US-01-01-13 — Govern Deterministic Document Creation via Templates¶

As a maintainer, I want document creation to use deterministic template, ID, and routing rules, so that new artefacts remain compliant from the moment they are created.

REQ-00-00-00-05 — Template-Governed Document Creation¶

When a document is created, arqix SHALL instantiate the configured template for the requested kind.

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-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-01-01-13-01 — Generate Unique IDs from Configured Policy¶

When a document is created without an explicit ID, arqix SHALL generate an ID from the configured policy and verify its uniqueness.

Coverage: verified.

REQ-01-01-13-02 — Create Documents in Configured Kind Location¶

When arqix doc new <kind> is invoked, arqix SHALL create the document in the configured location for that kind.

Coverage: verified.

US-01-01-14 — Lint Translation Metadata and Drift¶

As a maintainer, I want an i18n lint profile that detects missing translations, outdated translations, and translation metadata mismatches, so that bilingual documentation quality can be enforced consistently.

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-10 — Translation Drift Detection¶

When translations exist for a document, arqix SHALL detect missing and outdated translations deterministically.

Coverage: verified.

REQ-01-01-14-01 — Configure Translation-Required Kinds¶

The set of translation-required kinds or domains SHALL be configurable in arqix.toml.

Coverage: uncovered.

US-01-01-15 — Operationalise the Release Process with SemVer¶

As a maintainer, I want a documented, coding-agent-friendly release process using SemVer, so that releases can be prepared traceably and executed safely.

US-01-01-16 — Validate Repository Configuration and Inspect Effective Config¶

As a maintainer, I want to validate repository configuration and inspect the effective config, so that documentation rules stay consistent and automation has a deterministic baseline.

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-16-01 — Validate Configuration against Schema¶

When arqix config validate runs, arqix SHALL report schema and contract violations.

Coverage: verified.

REQ-01-01-16-02 — Render Effective Configuration¶

When arqix config show runs, arqix SHALL render the effective configuration after defaults and overrides are applied.

Coverage: verified.

REQ-01-01-16-03 — Identify Failing Key in Config Diagnostics¶

Configuration diagnostics SHOULD identify the failing key and source file.

Coverage: verified.

US-01-01-17 — Configure Discovery Scope¶

As a maintainer, I want to configure which directories document discovery skips, so that repository layouts with vendored or generated directories under the roots stay clean without code changes.

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-17-01 — Exclude Configured Skip-Dirs from Discovery¶

Where skip-dirs is configured, arqix SHALL exclude the named directories from document discovery.

Coverage: verified.

REQ-01-01-17-02 — Exclude Default Skip-Dirs from Discovery¶

While no skip-dirs override is configured, arqix SHALL exclude .git, target, node_modules, __pycache__, and fixtures from document discovery.

Coverage: verified.

US-01-01-18 — Configure the ID Policy¶

As a maintainer, I want the document ID shapes declared in configuration and all relations resolved from the declared triples, so that a repository adopting arqix can bring its own numbering without forking the tool.

REQ-00-00-00-04 — Deterministic IDs and Slugs¶

The arqix CLI SHALL derive document IDs and slugs deterministically from the configured policy.

Coverage: verified.

REQ-01-01-18-01 — Apply Configured ID Patterns¶

When a document ID is generated or validated, arqix SHALL apply the ID pattern configured for the document's family.

Coverage: verified.

REQ-01-01-18-02 — Resolve Ownership from Declared Triples¶

When the trace graph resolves the owning story of a requirement, arqix SHALL read it from the requirement's first derived-from triple.

Coverage: verified.

REQ-01-01-18-03 — Preserve Current ID Shapes by Default¶

Where no ID policy is configured, arqix SHALL apply default patterns that reproduce the built-in ID shapes.

Coverage: verified.

REQ-01-01-18-04 — Check ID Consistency Where Groups Exist¶

Where the configured ID pattern declares semantic groups, arqix SHALL report inconsistencies between the values encoded in an ID and the document's declared triples.

Coverage: verified.

US-01-01-19 — Configure Frontmatter Contracts¶

As a maintainer, I want the per-family frontmatter contract — canonical key order and required meta keys — declared once in configuration, so that the formatter and the validators can never disagree about what a conforming document looks like.

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-19-01 — Order Frontmatter Keys from Configuration¶

When arqix fmt canonicalises frontmatter, arqix SHALL order keys by the per-family key order in the effective configuration.

Coverage: verified.

REQ-01-01-19-02 — Share One Frontmatter Contract Source¶

arqix SHALL validate frontmatter contracts against the same configured source the formatter reads.

Coverage: verified.

REQ-01-01-19-03 — Configure Required Meta Keys¶

When a document's meta block is validated, arqix SHALL require exactly the meta keys declared in the effective configuration.

Coverage: verified.

US-01-01-20 — Create Documents from Template Files¶

As a maintainer, I want doc new and doc init to instantiate template files from a configured directory, so that I can shape what a new document looks like by editing a file instead of forking string literals in the engine.

REQ-00-00-00-05 — Template-Governed Document Creation¶

When a document is created, arqix SHALL instantiate the configured template for the requested kind.

Coverage: verified.

REQ-01-01-20-01 — Instantiate Configured Template Files¶

When a document is created, arqix SHALL instantiate the template file configured for the document's kind.

Coverage: verified.

REQ-01-01-20-02 — Scaffold Default Templates on Init¶

When arqix doc init scaffolds a package, arqix SHALL write the default template files into the configured template directory.

Coverage: verified.

REQ-01-01-20-03 — Fail Clearly on Missing Template Files¶

If a configured template file is missing, then arqix SHALL fail with a diagnostic naming the expected path.

Coverage: verified.