Specification — wf-08-01¶
US-08-01-01 — Initialize a Doc Package Deterministically and Safely¶
As a coding agent, I want to initialise a new doc package deterministically and without unsafe overwrites, so that I can create repository artefacts within scope and without ambiguity.
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-08-01-01-01 — Make Stop Conditions Actionable¶
Failure diagnostics SHOULD make the stop condition clear enough to act on without reading source code.
Coverage: verified.
REQ-08-01-01-02 — Keep Generated Packages Verification-Ready¶
The generated doc package SHOULD be usable directly in the verification loop without manual interpretation or repair.
Coverage: verified.
US-08-01-02 — Emit a Deterministic Assembly Log for Verification¶
As a coding agent, I want a machine-readable log during assembly, so that I can verify include structure and outputs without ambiguity.
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-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.
REQ-08-01-02-01 — Make Assembly Outcomes Machine-Interpretable¶
Assembly outcomes SHOULD be interpretable from the log and command result without human guesswork.
Coverage: verified.
US-08-01-05 — Create Documents Deterministically from Templates¶
As a coding agent, I want to create documents from templates, so that I can generate compliant artefacts deterministically without guessing kinds, placeholders, or file structure.
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.
REQ-08-01-05-01 — Fail Clearly on Unknown Kinds¶
If an unknown document kind is requested, then arqix SHALL fail with a clear, actionable error.
Coverage: uncovered.
US-08-01-14 — Scaffold Translations Deterministically from Source IDs¶
As a coding agent, I want to create a translation document by referencing its source document ID, so that I can generate correctly linked translation artefacts without guessing routing, metadata, or document shape.
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.
US-08-01-16 — Scan Traceability Deterministically within Verification Loops¶
As a coding agent, I want to scan traceability information, so that I can verify requirement links across documentation, code, and tests without ambiguity.
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.
US-08-01-19 — Detect Missing Trace Markers for a Requirement¶
As a coding agent, I want arqix to detect missing implements and verifies markers for a given requirement across code and tests, so that I can add only the missing annotations and avoid unnecessary edits.
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.
US-08-01-22 — Make Trace and Coverage Outputs Deterministic¶
As a coding agent, I want trace graphs, matrices, and coverage reports to be deterministic, so that I can produce clean diffs and reliably detect meaningful changes.
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.
US-08-01-24 — Scaffold Agent Instructions on Init¶
As a coding agent, I want doc init to scaffold an agent instruction document, so that any repository I enter through arqix tells me its gate commands and corpus entry points from the first commit.
REQ-08-01-24-01 — Scaffold Agent Instructions on Init¶
When arqix doc init initialises a repository without an agent instruction document, arqix SHALL scaffold an AGENTS.md that names the verification loop and the corpus entry points.
Coverage: verified.
REQ-08-01-24-02 — Never Overwrite Existing Agent Instructions¶
Where an agent instruction document already exists, arqix doc init SHALL leave it unchanged.
Coverage: verified.
US-08-01-25 — Create Documents in the Kinds Declared Directory¶
As a coding agent, I want doc new <kind> to create the document in the directory the kind's contract declares, so that a bounded context's documents land where its validation expects them instead of in a generic <root>/<kind>/ folder.
REQ-08-01-25-01 — Create Documents in the Declared Directory¶
When a [kinds.<family>] contract declares a dir, arqix SHALL create documents of that family under the declared directory.
Coverage: verified.
US-08-01-26 — Instantiate Declared Kind Templates¶
As a coding agent, I want a kind's contract to name its template file and the placeholder vocabulary to be validated, so that a bounded context's custom templates are first-class configuration instead of magic filenames, and a typo in a placeholder is a finding instead of a silent literal in the created document.
REQ-08-01-26-01 — Instantiate the Declared Template¶
When a [kinds.<family>] contract declares a template, arqix SHALL instantiate documents of that family from the declared template file.
Coverage: verified.
REQ-08-01-26-02 — Reject Unknown Template Placeholders¶
When a declared template contains a placeholder outside the documented vocabulary, arqix SHALL report the unknown placeholder as a finding and create no document.
Coverage: verified.
US-08-01-27 — Place Documents at an Explicit Target Directory¶
As a coding agent, I want to pass an explicit target directory to doc new, so that a term lands directly at a bounded-context path such as contexts/geo/terms/ without moving it after creation.
REQ-08-01-27-01 — Place Documents at the Given Directory¶
When the caller passes an explicit target directory, arqix SHALL create the document under that repository-contained directory.
Coverage: verified.
US-08-01-28 — Capture Sources as First-Class Records¶
As a coding agent, I want external sources captured as first-class source documents with URL-plus-local-copy provenance, so that every claim the corpus derives from an external source stays verifiable against what was actually read.
REQ-08-01-28-01 — Keep Source IRIs in the Sources Namespace¶
When arqix lint frontmatter runs, arqix SHALL report every source document whose iri does not lie in the sources namespace derived from its id.
Coverage: verified.
REQ-08-01-28-02 — Require Complete Provenance on Finalised Sources¶
When arqix lint frontmatter runs, arqix SHALL report every finalised source document that lacks the uri or the access date and every source document that carries only one of local-copy and sha256.
Coverage: verified.
REQ-08-01-28-03 — Validate Source Provenance Values¶
When arqix lint frontmatter runs, arqix SHALL report every source document whose accessed value is not a calendar date, whose sha256 value is not sixty-four lowercase hexadecimal characters, or whose local-copy path escapes the repository or lies inside a documentation root.
Coverage: verified.
US-08-01-29 — Configure the Frontmatter Vocabularies¶
As a repository owner, I want the section-kind vocabulary and the allowed external rdf types to be configuration, so that a project ontology can extend them without forking the checker.
REQ-08-01-29-01 — Validate Section Kinds Against the Effective Vocabulary¶
When arqix lint frontmatter runs, arqix SHALL validate properties.section-kind against the effective vocabulary — the configured [frontmatter].section-kinds when present, the built-in vocabulary otherwise.
Coverage: verified.
REQ-08-01-29-02 — Accept Configured External Rdf Types¶
When arqix lint frontmatter runs, arqix SHALL accept a non-arqix rdf.type only when it lies in the effective external-type vocabulary — the configured [frontmatter].allowed-external-types when present, the built-in list otherwise.
Coverage: verified.
US-08-01-30 — Resolve Every Declared Triple Target¶
As a knowledge engineer, I want every declared triple object resolved against the corpus, so that a reference to a document that does not exist is a finding instead of a silently green gate.
REQ-08-01-30-01 — Report Dangling Triple Objects¶
When arqix lint frontmatter runs, arqix SHALL report every declared triple whose object is an arqix: IRI that no corpus document carries as its iri.
Coverage: verified.
US-08-01-31 — Bind the Coupling Rules to the Story Module¶
As a repository owner, I want the story-workflow coupling rules bound to the story-driven process module, so that a corpus without stories and workflows can select its process instead of inheriting every rule.
REQ-08-01-31-01 — Run Coupling Rules Only With the Story Module¶
When arqix lint requirements runs, arqix SHALL apply the story-workflow coupling rules exactly when the story-driven process module is effective — listed in the configured [process].modules, or unconfigured entirely.
Coverage: verified.
US-08-01-32 — Fill Template Placeholders at Creation¶
As a coding agent, I want doc new to fill template placeholders from explicit arguments, so that a template-driven document needs no hand editing after creation.
REQ-08-01-32-01 — Fill Set Placeholders and Report Unused Keys¶
When arqix doc new runs with --set key=value arguments, arqix SHALL fill each named {key} template placeholder with its value and report every key the template does not use.
Coverage: verified.
US-08-01-33 — Derive Placement and Id From Kind Templates¶
As a repository owner, I want a kind to declare how its ids and target paths derive from creation arguments, so that the correct name and place are the default instead of a per-call chore.
REQ-08-01-33-01 — Mint Ids From the Declared Id Template¶
When arqix doc new runs without an explicit --id and the kind declares an id-template, arqix SHALL mint the id by filling the template from the --set values and the derived slug and report every placeholder no value covers.
Coverage: verified.
REQ-08-01-33-02 — Place Documents by the Declared Dir Template¶
When arqix doc new runs without an explicit --dir and the kind declares a dir-template, arqix SHALL place the document in the directory produced by filling the template from the --set values and the derived slug, containment-guarded like an explicit --dir.
Coverage: verified.
US-08-01-34 — Verify the Local Copy Against Its Digest¶
As a knowledge engineer, I want the recorded digest checked against the local copy's actual bytes, so that a source record pins what was really read instead of merely carrying a well-formed hash.
REQ-08-01-34-01 — Verify Local Copy Bytes Against the Recorded Digest¶
When arqix lint frontmatter checks a source record carrying a well-formed local-copy and sha256 pair, arqix SHALL report the record unless the file exists and its bytes hash to the recorded digest.
Coverage: verified.
US-08-01-35 — Declare Vocabularies for Named Property Fields¶
As a repository owner, I want a kind to declare controlled vocabularies for named properties fields, so that domain states are validated by the gate instead of by project scripts.
REQ-08-01-35-01 — Validate Declared Property Vocabularies¶
When arqix lint frontmatter checks a document whose kind declares a vocabulary for a properties field, arqix SHALL report every value of that field outside the declared vocabulary.
Coverage: verified.
US-08-01-36 — Validate the Ontology Against Itself¶
As a knowledge engineer, I want every declared edge checked against the properties' declared domains and ranges, so that a configured ontology is a validated contract instead of decoration.
REQ-08-01-36-01 — Check Edges Against Declared Domains and Ranges¶
When arqix lint frontmatter checks a declared triple whose predicate declares a domain or range, arqix SHALL report every subject or resolvable object whose types lie outside the declared classes, subclass closure included.
Coverage: verified.
REQ-08-01-36-02 — Report Subclass Cycles¶
When arqix lint frontmatter runs, arqix SHALL report every sub-class-of cycle that is longer than a class's own root self-reference.
Coverage: verified.
US-08-01-37 — Project the Source Catalog¶
As a knowledge engineer, I want the source records projected into one deterministic catalog table, so that the corpus's provenance inventory is a generated artifact under the drift gate instead of a hand-maintained file.
REQ-08-01-37-01 — Render the Source Catalog Unit¶
When arqix report snapshot runs, arqix SHALL render the source-catalog unit with one row per source document, sorted by id, projecting the provenance columns from the frontmatter.
Coverage: verified.
US-08-01-38 — Hold Documents to Their Kinds Placement Contract¶
As a repository owner, I want every document checked against its kind's declared placement, so that a document's path and its own frontmatter can never silently disagree.
REQ-08-01-38-01 — Check Paths Against the Rendered Dir Template¶
When arqix lint frontmatter checks a document whose kind declares a dir-template, arqix SHALL report the document unless its parent directory equals the template rendered from the document's own properties, slug, and kind.
Coverage: verified.
US-08-01-39 — Name Each Creation Defect Distinctly¶
As a coding agent, I want each creation defect under its own rule id, so that automation can branch on the id instead of parsing the message.
REQ-08-01-39-01 — Report Taken Ids as Their Own Rule¶
When arqix doc new is asked for an id another document already carries, arqix SHALL report it as TPL-004 naming the id and its holder.
Coverage: verified.
US-08-01-40 — Anchor Evidence in the Text and Derive the Edge¶
As a knowledge engineer, I want a statement's evidence anchored in the text and its edge derived into the graph, so that a claim is both position-exact and queryable without maintaining the connection twice.
REQ-08-01-40-01 — Validate Claim Markers¶
When arqix lint frontmatter checks a document body, arqix SHALL report every claim marker that misses supported-by or carries an unknown key, and every confidence value outside the effective vocabulary.
Coverage: verified.
REQ-08-01-40-02 — Lift Claim Markers Into Derived Triples¶
When arqix fmt rewrites a document, arqix SHALL derive the derived-triples section from the document's claim markers — targets deduplicated and sorted, the section absent without markers — and report the disagreement in check mode.
Coverage: verified.
REQ-08-01-40-03 — Let Derived Triples Join the Graph Checks¶
When arqix lint frontmatter checks a document carrying a derived-triples section, arqix SHALL validate its entries exactly like declared triples, including target resolution and the declared range of supported-by.
Coverage: verified.
US-08-01-41 — Export Claims and Report Evidence Coverage¶
As a knowledge engineer, I want the corpus's claims exported as data and their coverage reported as numbers, so that evidence is queryable and its growth observable without ever becoming a gate.
REQ-08-01-41-01 — Export Claims as Data¶
When arqix report claims runs, arqix SHALL print one deterministic CSV row per claim marker — file, supported-by target, confidence, and anchor — with the committed export held fresh by the snapshot check.
Coverage: verified.
REQ-08-01-41-02 — Report Evidence Coverage as Numbers¶
When arqix report snapshot runs, arqix SHALL render the evidence-coverage unit with the claim total, the documents carrying claims, and the distinct sources cited.
Coverage: verified.