Requirements

The system SHALL NOT register item declarations ([#ID, item, role=…​]) found inside AsciiDoc verbatim blocks (listing blocks delimited by ---- and literal blocks delimited by …​.) as traceability items.

Source: openspec/specs/parser-verbatim-skip/spec.md

The system SHALL NOT register inline relationship macros (``) whose enclosing item was skipped because it fell inside a verbatim block.

Source: openspec/specs/parser-verbatim-skip/spec.md

The system SHALL detect verbatim blocks by matching opening and closing fence lines consisting of exactly ---- or …​. (with optional trailing whitespace), ignoring style prefix lines like [source,asciidoc].

Source: openspec/specs/parser-verbatim-skip/spec.md

The system SHALL NOT strip inline relationship macros (``) from inside AsciiDoc verbatim blocks during the content substitution pass. Such macros are example code and SHALL remain visible in the rendered output.

Source: openspec/specs/parser-verbatim-skip/spec.md

The system SHALL NOT register inline relationship macros (``) that appear inside backtick-enclosed code spans as traceability relationships.

Source: openspec/specs/parser-verbatim-skip/spec.md

The system SHALL process items defined in AsciiDoc partial files alongside page files, registering them in the traceability graph.

Source: openspec/specs/partial-file-processing/spec.md

Items from partial files SHALL use the file’s view URL as their source file reference, enabling traceability matrix links to resolve to the source repository.

Source: openspec/specs/partial-file-processing/spec.md

The system SHALL apply graph population, macro expansion, and link substitution passes to partial files in the same way as page files, because partial content is inlined into pages and reaches the browser.

Source: openspec/specs/partial-file-processing/spec.md

The system SHALL detect when a newly added relationship is authored with the reverse of an existing relationship’s type — the existing edge goes from B to A with a type whose declared reverse equals the new edge’s type — and SHALL NOT store a second edge. The canonical primary edge is retained with its original metadata (sourceFile, line), and no warning is emitted. Merging is driven by the reverse declaration in relations (config), not by inverseLabels or the compile-time INVERSE_MAP.

Source: openspec/specs/bidirectional-relationship-merge/spec.md

The system SHALL detect circular references in the traceability graph during validation. A circular reference is a cycle in the directed relationship graph (e.g., A → B → A, or A → B → C → A). Self-referencing relationships (A → A) SHALL also be detected as cycles. Auto-generated inverse relationships SHALL be skipped during cycle detection to avoid false positives. Relationships marked as bidirectional SHALL also be skipped during cycle detection.

Source: openspec/specs/circular-reference-detection/spec.md

The system SHALL compute file content, document attributes, and item block positions exactly once per page file, and SHALL reuse the computed values across all macro-expansion passes for that file.

Source: openspec/specs/file-preparation-cache/spec.md

The system SHALL cache the parsed state of each source file — including its full content, document attributes, item block positions, and normalized source-file metadata — so that subsequent processing steps within the same file pass do not reparse it.

Source: openspec/specs/file-preparation-cache/spec.md

The system SHALL provide a traceability:outgoing[] macro that expands to a formatted list of all outgoing relationships for the enclosing item.

Source: openspec/specs/traceability-links-macro/spec.md

If the enclosing item has no outgoing relationships, then the traceability:outgoing[] macro SHALL render a configurable empty-state message controlled by the :traceability-empty: document attribute.

Source: openspec/specs/traceability-links-macro/spec.md

The system SHALL provide a traceability:incoming[] macro that expands to a formatted list of all relationships pointing to the enclosing item (reverse relationships).

Source: openspec/specs/incoming-links-macro/spec.md

The system SHALL provide a traceability:links[] macro that expands to a combined list of all outgoing and incoming relationships for the enclosing item, with outgoing groups rendered first followed by incoming groups.

Source: openspec/specs/traceability-links-macro/spec.md

The system SHALL only expand traceability:outgoing[] and traceability:incoming[] when the :traceability-links: document attribute is set to a truthy value.

Source: openspec/specs/traceability-links-macro/spec.md

When :traceability-links: is enabled, the system SHALL suppress the individual rendering of inline relationship macros within item blocks that contain a traceability:outgoing[] or traceability:incoming[] macro.

Source: openspec/specs/traceability-links-macro/spec.md

The system SHALL support configurable display styles via the :traceability-style: document attribute for both traceability:outgoing[] and traceability:incoming[] macros.

Source: openspec/specs/traceability-links-macro/spec.md

The system SHALL support configurable sort order via the :traceability-order: document attribute for both traceability:outgoing[] and traceability:incoming[] macros, defaulting to sort by target ID for outgoing and source ID for incoming.

Source: openspec/specs/traceability-links-macro/spec.md

The system SHALL support a :traceability-collapsible: document attribute that, when set to a truthy value, wraps each relation-type group in list-style output in a [%collapsible] AsciiDoc block.

Source: openspec/specs/traceability-links-macro/spec.md

The system SHALL gate traceability:incoming[] expansion on the same :traceability-links: document attribute as the outgoing macro.

Source: openspec/specs/incoming-links-macro/spec.md

The system SHALL support the same display styles for traceability:incoming[] as for the outgoing macro, via the :traceability-style: document attribute.

Source: openspec/specs/incoming-links-macro/spec.md

The system SHALL support the same sort orders for traceability:incoming[] as for the outgoing macro, via the :traceability-order: document attribute, defaulting to sort by source ID.

Source: openspec/specs/incoming-links-macro/spec.md

The system SHALL group incoming relationships in traceability:incoming[] by the reverse relation type — the declared reverse of the relationship’s type — so each group heading names the relation from the target item’s perspective.

Source: openspec/specs/incoming-links-macro/spec.md

The system SHALL apply the same :traceability-collapsible: document attribute to traceability:incoming[] output as it does for traceability:outgoing[]. When enabled, each inverse relation-type group in list-style incoming output SHALL be wrapped in a [%collapsible] block.

Source: openspec/specs/incoming-links-macro/spec.md

When building a site with multiple component versions, relationship macro expansion SHALL be scoped per version. Items from one component version SHALL NOT appear in xrefs generated for pages in a different component version.

Source: openspec/specs/traceability-links-macro/spec.md

The generated output from traceability:incoming[] SHALL be standard AsciiDoc constructs — not raw HTML — ensuring compatibility with both HTML and PDF backends.

Source: openspec/specs/incoming-links-macro/spec.md

The system SHALL NOT modify the .adoc source file on disk when expanding traceability:incoming[].

Source: openspec/specs/incoming-links-macro/spec.md

The generated output from traceability:outgoing[] and traceability:incoming[] SHALL use standard AsciiDoc constructs, ensuring compatibility with both HTML and PDF rendering backends.

Source: openspec/specs/traceability-links-macro/spec.md

The system SHALL NOT modify the .adoc source file on disk when expanding traceability:outgoing[] or traceability:incoming[].

Source: openspec/specs/traceability-links-macro/spec.md

When processing .adoc files through the Antora extension, the system SHALL store the Antora component and module names on each Item so that downstream xref and link generation can distinguish same-module from cross-module and cross-component references.

Source: openspec/specs/cross-module-xref/spec.md

When buildXref generates an Antora xref for an item in a different module or component than the current page, the system SHALL include the appropriate prefix matching Antora’s xref resolution hierarchy: component:module: for cross-component, module: for cross-module, and no prefix for same-module.

Source: openspec/specs/cross-module-xref/spec.md

When an item in one module has relationships to items in other modules or components, the traceability:outgoing[] and traceability:incoming[] macros SHALL generate xrefs with the correct Antora prefix (component:module: or module:) so Antora can resolve them correctly.

Source: openspec/specs/traceability-links-macro/spec.md

The system SHALL support labels in the traceability configuration YAML, mapping each relation type to a human-readable display name used for rendering (incoming/outgoing lists, matrix headers, graph labels). labels SHALL NOT affect graph structure, merge behavior, or validation.

Source: openspec/specs/inverse-labels/spec.md

If a relation type has no entry in labels, the system SHALL display the type name humanized: underscores replaced with spaces and the result sentence-cased.

Source: openspec/specs/inverse-labels/spec.md

The system SHALL NOT consult a compile-time inverse map for display names; the pairing between primary and reverse types is derived solely from the reverse declaration in relations, and display text comes solely from labels or the humanized default.

Source: openspec/specs/inverse-labels/spec.md

The matrix SHALL render row item IDs as hyperlinks that navigate to the item’s definition in the rendered HTML documentation.

Source: openspec/specs/matrix-item-linking/spec.md

The matrix SHALL render cell item IDs as hyperlinks that navigate to the item’s definition in the rendered HTML documentation.

Source: openspec/specs/matrix-item-linking/spec.md

The matrix SHALL display the source file name as a tooltip when users hover over item links.

Source: openspec/specs/matrix-item-linking/spec.md

The system SHALL generate matrix links that resolve correctly regardless of where the matrix file is served within the Antora site output.

Source: openspec/specs/matrix-item-linking/spec.md

The system SHALL normalize item source file references so that matrix links resolve to the rendered page URL rather than the AsciiDoc source file path.

Source: openspec/specs/matrix-item-linking/spec.md

The system SHALL maintain existing matrix rendering behaviour when link resolution is not configured.

Source: openspec/specs/matrix-item-linking/spec.md

The system SHALL NOT modify CSV and JSON matrix outputs to include links.

Source: openspec/specs/matrix-item-linking/spec.md

When an item has module information, the system SHALL generate HTML links that include the module name so the link navigates to the correct module page.

Source: openspec/specs/matrix-item-linking/spec.md

The system SHALL register generated matrix files (HTML, CSV, JSON) as site attachments before document conversion, so that attachment$traceability/…​ xrefs in pages and navigation resolve correctly. Registration SHALL occur per component version and under every module that has AsciiDoc content. A committed copy, if present, SHALL have its contents refreshed in place.

Source: openspec/specs/matrix-attachment-sync/spec.md

When Antora’s indexify URL style is active (root-level pages are served as pagename/index.html), the system SHALL generate matrix links that include index.html in the path for root-level pages so links from traceability matrices resolve to the correct page.

Source: openspec/specs/matrix-generation/spec.md

The HTML matrix template SHALL be split into a main template and four reusable partial fragments (styles, header, matrix-row, footer) loaded from the partials/ subdirectory.

Source: openspec/specs/template-partials/spec.md

The HTML matrix SHALL render exactly one per-row status column, and SHALL NOT render a separate per-row coverage percentage column.

Source: openspec/specs/matrix-status/spec.md

The matrix SHALL still render a top-level coverage summary with the counts of done/partial/missing rows and an overall percentage of done rows.

Source: openspec/specs/matrix-status/spec.md

The CSV export SHALL NOT render a per-row status or coverage column, matching its current behavior.

Source: openspec/specs/matrix-status/spec.md

The requirements-engineering preset SHALL include a matrix named requirements-to-design with requirement rows and a single design column.

Source: openspec/specs/pairwise-matrices-preset/spec.md

The requirements-engineering preset SHALL include a matrix named design-to-implementation with design rows and a single implementation column.

Source: openspec/specs/pairwise-matrices-preset/spec.md

The requirements-engineering preset SHALL include a matrix named requirements-to-tests with requirement rows and a single test column.

Source: openspec/specs/pairwise-matrices-preset/spec.md

The requirements-engineering preset SHALL NOT define matrices with more than one column role.

Source: openspec/specs/pairwise-matrices-preset/spec.md

A preset SHALL declare its parent with a top-level extends field (sibling of name, version, description). When a preset declares extends, the resolved preset SHALL include the parent’s traceability deep-merged under the child’s own traceability.

Source: openspec/specs/preset-inheritance/spec.md

Preset inheritance SHALL use the same merge rules as a config file extending a preset: roles are unioned, relations are deep-merged by source and target role, matrices are overridden by name, and labels are overridden key-by-key.

Source: openspec/specs/preset-inheritance/spec.md

Inheritance SHALL resolve transitively: a preset extending a preset that itself extends another SHALL include the roles, relations, and matrices of the full chain.

Source: openspec/specs/preset-inheritance/spec.md

When a preset’s extends names a preset that cannot be resolved, loading SHALL fail with an error that names the missing preset.

Source: openspec/specs/preset-inheritance/spec.md

A preset SHALL NOT extend itself, directly or transitively. Any inheritance cycle SHALL be detected and rejected with a clear error rather than looping indefinitely.

Source: openspec/specs/preset-inheritance/spec.md

The relations config SHALL map sourceRole → targetRole → relationType → { reverse }, where reverse is required and names the authorable reverse relation type.

Source: openspec/specs/reverse-relations/spec.md

When an item authors a relationship using a reverse type, the graph SHALL store the canonical primary edge (primary direction and primary type), not the reverse-authored form.

Source: openspec/specs/reverse-relations/spec.md

isRelationAllowed SHALL allow a relation type that is the reverse of a relation declared in the opposite role direction, without an explicit relations entry for that direction.

Source: openspec/specs/reverse-relations/spec.md

A matrix coverageRelations entry SHALL name the canonical primary type, and a single entry SHALL count a relationship regardless of which name was authored.

Source: openspec/specs/reverse-relations/spec.md

The system SHALL provide a traceability:graph[] inline macro that renders a relationship diagram for the enclosing item. The diagram SHALL show the item and its related items as labeled nodes and edges, colored by role. An optional depth parameter SHALL control the number of relationship hops shown.

Source: openspec/specs/graph-visualization/spec.md

The system SHALL provide a traceability:graph-coverage[] inline macro that renders a coverage chart. When used inside an item block, it SHALL show per-relationship-type coverage for that item. When used outside an item block, it SHALL show global coverage by role.

Source: openspec/specs/graph-visualization/spec.md

The graph model SHALL support producing a traversal-bounded relationship subgraph for a given item, traversing both outgoing and incoming directions. Bidirectional relationships SHALL be visually distinguishable from one-directional relationships in the rendered output. The graph model SHALL also support producing coverage data for a given item, or globally across all items.

Source: openspec/specs/graph-visualization/spec.md

The example site SHALL include a dashboard page with a global coverage chart and select per-item relationship graphs, gated by the :traceability-graph: attribute.

Source: openspec/specs/graph-visualization/spec.md

The krokiImageFormat extension config option SHALL control the image format (svg or png) used in rendered relationship diagram images. When not set, the format SHALL default to svg. The configured krokiServerUrl (or its default https://kroki.io) SHALL be used as the base URL for diagram rendering requests.

Source: openspec/specs/graph-visualization/spec.md

The system SHALL provide a traceability:config-graph[] macro that renders the effective traceability configuration as a Kroki GraphViz diagram. The diagram SHALL show each configured role as a node colored by role and each declared relation as a labeled edge, using declared directions only.

Source: openspec/specs/graph-visualization/spec.md

The system SHALL provide a DOT generator for the traceability configuration that renders roles as nodes and declared relations as labeled edges.

Source: openspec/specs/graph-visualization/spec.md

The krokiServerUrl extension config option SHALL set the base URL used by traceability:graph[] and traceability:graph-coverage[] macros when generating Kroki image URLs. When set, the system SHALL use this URL instead of the default https://kroki.io.

Source: openspec/specs/kroki-server-url-config/spec.md

The KROKI_SERVER_URL environment variable SHALL override the krokiServerUrl extension config option. When set, the system SHALL use its value as the Kroki server base URL.

Source: openspec/specs/kroki-server-url-config/spec.md

The CLI SHALL provide a next-id command that accepts a --prefix and -i/--input and returns the next available sequential ID for items matching that prefix.

Source: openspec/specs/next-id/spec.md

The CLI SHALL provide a query subcommand that reads AsciiDoc source files and answers one structural question about items and their relationships per invocation. No Antora build SHALL be required.

Source: openspec/specs/cli-query/spec.md

The CLI SHALL provide query reverse <id> that returns all items whose relationship macros reference the given item ID.

Source: openspec/specs/cli-query/spec.md

The CLI SHALL provide query impact <id> that returns all items transitively connected to the given item (its connected component, excluding the item itself), following relationships in both directions.

Source: openspec/specs/cli-query/spec.md

The CLI SHALL provide query orphaned that returns all items that have neither incoming nor outgoing relationships in the graph.

Source: openspec/specs/cli-query/spec.md

The CLI SHALL provide query path <from-id> <to-id> that returns the shortest relationship path between two items in the graph.

Source: openspec/specs/cli-query/spec.md

All query subcommands SHALL accept a --json flag that switches output to a machine-readable JSON array.

Source: openspec/specs/cli-query/spec.md

The CLI SHALL provide a validate command that reads AsciiDoc source files and reports validation errors — invalid relation types, orphaned relationships, duplicate item IDs, and circular references — with diagnostics naming the source and target item IDs with roles, the invalid relation type, and the allowed alternatives. No Antora build SHALL be required. The command SHALL exit with a non-zero code when errors are found and code 0 when the input is valid.

Source: openspec/specs/cli-validate/spec.md

The search index SHALL include every non-heading HTML element inside <article class="doc"> that has an id attribute as a separate searchable chunk. Each chunk SHALL use the element’s id as its hash, enabling search result links to navigate directly to the element’s anchor.

Source: openspec/specs/lunr-item-anchor-indexing/spec.md

When an element has a child element with CSS class title, the extension SHALL use the text content of that child as the chunk’s title field. If no .title child exists, the element’s id SHALL be used as the title.

Source: openspec/specs/lunr-item-anchor-indexing/spec.md

Elements that are HTML headings (h1 through h6) SHALL be skipped by the item anchor indexing pass, as they are already indexed by the existing heading-based section chunking.

Source: openspec/specs/lunr-item-anchor-indexing/spec.md

The item anchor indexing SHALL only traverse elements within <article class="doc">. Elements outside the article body (navigation, TOC, footer) SHALL NOT be indexed.

Source: openspec/specs/lunr-item-anchor-indexing/spec.md

The extension SHALL validate every relationship against configured role-relation rules. Error messages SHALL include file path, line number, source and target item IDs with roles, the invalid relation type, and the list of allowed alternatives. Cross-file references SHALL be re-validated after all files are loaded.

Source: openspec/changes/archive/2026-07-28-add-pdf-output/specs/pdf-output/spec.md

All content transformations SHALL operate on in-memory buffers. Source .adoc files SHALL never be modified by the extension. Processing the same file twice SHALL produce the same result.

Source: openspec/changes/archive/2026-07-28-add-pdf-output/specs/pdf-output/spec.md

The traceability graph SHALL provide forward, reverse, and inverse relationship indexes enabling O(1) lookup by item ID. Path finding SHALL use BFS with configurable maxDepth. Result caching SHALL be used with invalidation on mutation to avoid redundant computation during repeated queries within a single processing session.

Source: examples/tracer/modules/ROOT/partials/04-solution-strategy.adoc (ARC-011)

Each module SHALL accept dependencies via constructor parameters. Each module SHALL have a dedicated test file. The traceability graph SHALL expose internal state for test access. The full test suite SHALL complete in under 500 ms.

Source: openspec/changes/archive/2026-07-28-add-pdf-output/specs/pdf-output/spec.md

Generated output from traceability:outgoing[] and traceability:incoming[] SHALL be standard AsciiDoc constructs — not raw HTML — ensuring compatibility with both HTML and PDF backends.

Source: openspec/specs/traceability-links-macro/spec.md

The extension SHALL use ESM ("type": "module"), TypeScript strict mode, and target Node.js 20+ as the baseline runtime. The zero-framework policy SHALL avoid dependencies on libraries with short upgrade cycles, ensuring the extension remains maintainable and runnable without forced migrations.

Source: examples/tracer/modules/ROOT/partials/04-solution-strategy.adoc (ARC-010)

The extension SHALL operate without requiring external services, databases, or runtime dependencies beyond Node.js standard library and a minimal set of npm packages. Optional features such as Neo4j export SHALL degrade gracefully when not configured.

Source: openspec/changes/archive/2026-07-28-add-pdf-output/specs/pdf-output/spec.md

The extension SHALL allow users to define roles, relations, and matrices entirely in YAML configuration. Built-in presets SHALL be overridable via the extends mechanism. Items with roles not yet in the configuration SHALL generate warnings rather than errors.

Source: openspec/changes/archive/2026-07-28-add-pdf-output/specs/pdf-output/spec.md

The devbox.json configuration SHALL include ruby, bundler, and nodejs packages so that devbox shell provides a complete PDF build environment. The init hook SHALL run npm install and bundle install automatically.

Source: openspec/specs/pdf-output/spec.md

The project SHALL include a Gemfile that specifies asciidoctor-pdf and asciidoctor-kroki gems so the PDF converter and diagram renderer are installed consistently across environments.

Source: openspec/specs/pdf-output/spec.md

A separate antora-playbook-pdf.yml SHALL exist that uses @antora/pdf-extension to generate a single PDF from the example site’s content. The playbook SHALL use the same content sources as the HTML playbook but output to public/pdf/.

Source: openspec/specs/pdf-output/spec.md

The @antora/pdf-extension npm package SHALL be listed as a peerDependency (with optional: true in peerDependenciesMeta) so consumers who want PDF output are signalled to install it explicitly. It SHALL also remain in devDependencies for local development.

Source: openspec/specs/pdf-output/spec.md

The component descriptor SHALL define assembler profiles with dedicated nav files so that the assembler produces separate PDFs for requirements, architecture, and test-plan documents.

Source: openspec/specs/split-pdf-documents/spec.md

Each profile SHALL reference a custom nav file that contains a single xref to the target document, so only that page is included in the assembly.

Source: openspec/specs/split-pdf-documents/spec.md

The existing single-PDF configuration SHALL remain available via antora-assembler-pdf.yml and the existing antora-playbook-pdf.yml SHALL continue to produce a single merged PDF.

Source: openspec/specs/split-pdf-documents/spec.md

The project documentation SHALL include a how-to guide for generating DOCX output and reference documentation for the DOCX assembler configuration.

Source: openspec/specs/docx-output/spec.md

The antora-playbook-pdf.yml example playbook SHALL reference the PDF extension using a local path (./lib/src/antora-pdf-extension.cjs) since it is the project’s own development playbook. Consumer documentation SHALL show the package subpath pattern (antora-tracer/antora-pdf).

Source: openspec/specs/pdf-output/spec.md

The antora-tracer npm package SHALL include lib/src/antora-pdf-extension.cjs and export it under the subpath antora-tracer/antora-pdf so consumers can reference it in their playbooks without copying files from the repository.

Source: openspec/specs/published-extensions/spec.md

The antora-tracer npm package SHALL include lib/src/antora-docx-extension.cjs and lib/src/antora-docx-converter.cjs and export the extension under the subpath antora-tracer/antora-docx.

Source: openspec/specs/published-extensions/spec.md

The package.json SHALL declare @antora/assembler and @antora/pdf-extension as peerDependencies with optional: true in peerDependenciesMeta so npm signals the requirement to consumers who use PDF or DOCX output without requiring them for consumers who do not. These packages SHALL also remain in devDependencies for local development builds.

Source: openspec/specs/published-extensions/spec.md

The assembler config YMLs and adoc-to-docx script SHALL reside in examples/ as reference consumer configuration, not at the project root and not in the npm package. The how-to documentation SHALL explain that consumers create their own configs modelled on these examples.

Source: openspec/specs/published-extensions/spec.md

The system SHALL run Vale against the source AsciiDoc content of every page and partial file in the content catalog when the extension is enabled.

Source: openspec/specs/vale-build-integration/spec.md

The system SHALL fail the build when Vale reports a finding at or above the configured minimum severity, and SHALL log findings below that severity without failing.

Source: openspec/specs/vale-build-integration/spec.md

The system SHALL load Vale’s configuration from the path supplied in the playbook configuration, so users control which styles and rules apply.

Source: openspec/specs/vale-build-integration/spec.md

When the extension is enabled, if the vale or asciidoctor executable is unavailable, the system SHALL fail the build with a message naming the missing executable.

Source: openspec/specs/vale-build-integration/spec.md

The system SHALL NOT run Vale unless the extension is explicitly registered in the playbook, so existing builds are unaffected.

Source: openspec/specs/vale-build-integration/spec.md

The system SHALL NOT enforce source line layout such as one sentence per line; that concern belongs to the source-layout checker.

Source: openspec/specs/vale-build-integration/spec.md

The system SHALL provide a set of Vale rule files that encode the machine-checkable parts of the documentation style guide, including filler-word avoidance, inclusive language, non-militaristic language, and the instead-of/use substitutions.

Source: openspec/specs/documentation-style-rules/spec.md

The system SHALL ship the rule files and a sample configuration with the npm package, while remaining optional for users.

Source: openspec/specs/documentation-style-rules/spec.md

Item block examples in the documentation SHALL use the -- open-block delimiter as the canonical form. The ==== example-block delimiter SHALL be documented as a valid alternative with its rendering difference.

Source: openspec/specs/documentation-style-rules/spec.md

The example site SHALL include a single Tutorial page (getting-started.adoc) that guides a first-time user from zero to a working traceability setup in numbered, sequential steps.

Source: openspec/specs/doc-tutorial/spec.md

The example site navigation SHALL include a "Tutorial" section as the first top-level item, containing the Getting Started page.

Source: openspec/specs/doc-tutorial/spec.md

The example site SHALL include How-to guide pages covering the following tasks:

Source: openspec/specs/doc-howto-guides/spec.md

Each How-to guide page SHALL include links to relevant Reference pages for option details and syntax specifications.

Source: openspec/specs/doc-howto-guides/spec.md

The example site navigation SHALL include a "How-to Guides" section containing all how-to pages, ordered by typical usage frequency.

Source: openspec/specs/doc-howto-guides/spec.md

The example site SHALL include Reference pages exhaustively documenting:

Source: openspec/specs/doc-reference/spec.md

Reference pages SHALL include links to relevant How-to guides, Explanation pages, and other Reference pages.

Source: openspec/specs/doc-reference/spec.md

The example site navigation SHALL include a "Reference" section containing all reference pages, ordered from most-used to least-used.

Source: openspec/specs/doc-reference/spec.md

The example site SHALL include Explanation pages covering:

Source: openspec/specs/doc-explanation/spec.md

Explanation pages SHALL include links to relevant Reference pages and How-to guides for readers who want to act on the understanding gained.

Source: openspec/specs/doc-explanation/spec.md

The example site navigation SHALL include an "Explanation" section containing all explanation pages.

Source: openspec/specs/doc-explanation/spec.md

The example site navigation SHALL include a "Self-Traceability" section containing the pages that demonstrate the extension tracing its own development artifacts:

Source: openspec/specs/doc-self-traceability/spec.md

The Self-Traceability section SHALL be clearly separated from the user-facing documentation sections, signaling to readers that these are demonstration artifacts, not documentation about using the tool.

Source: openspec/specs/doc-self-traceability/spec.md

The restructuring SHALL NOT move any traceable [item] blocks out of their source files. All existing requirements (REQ), architecture (ARC), test (TST), use case (UC), and quality (QA) items SHALL remain in their current AsciiDoc files.

Source: openspec/specs/doc-self-traceability/spec.md

The system SHALL provide a check that extracts [item] blocks from the example site’s prose documentation pages and validates them against the example traceability configuration (examples/traceability.yml). The check SHALL fail on unknown roles, disallowed relations, and item blocks that fail to parse.

Source: openspec/specs/doc-example-validation/spec.md

The GitHub Pages workflow SHALL include Ruby setup and PDF generation steps so that requirements, architecture, and test-plan PDFs are built and deployed alongside the HTML site on every push to main.

Source: openspec/specs/ci-pdf-deploy/spec.md

The example site’s index page SHALL include download links to the three core PDF documents.

Source: openspec/specs/ci-pdf-deploy/spec.md

The existing local PDF build workflow (devbox shell + npx antora antora-playbook-pdf.yml) SHALL continue to work unchanged.

Source: openspec/specs/ci-pdf-deploy/spec.md

The system SHALL serve a landing page at the GitHub Pages root URL (/) that introduces the antora-tracer project before visitors enter the documentation, while the Antora documentation site remains accessible at /docs/.

Source: openspec/specs/landing-page/spec.md

The landing page SHALL present project features in a way that resonates with both developers/architects (docs-as-code natives) and requirements engineers/project managers (traceability/compliance focused users).

Source: openspec/specs/landing-page/spec.md

The landing page SHALL include a visual preview of traceability output that links to the live traceability matrices in the documentation site.

Source: openspec/specs/landing-page/spec.md

The GitHub Pages deployment workflow SHALL place the landing page at the root and the Antora documentation in a /docs/ subdirectory, with both built and deployed from the same repository.

Source: openspec/specs/landing-page/spec.md

The landing page SHALL require no build step or installed dependencies to deploy — it SHALL be served as static HTML.

Source: openspec/specs/landing-page/spec.md

The landing page SHALL use a consistent brand color palette for all brand-colored elements. Primary brand elements (buttons, links, icons, section backgrounds) SHALL use the primary brand color for interactive elements and a darker variant for headings and dark backgrounds.

Source: openspec/specs/landing-page/spec.md

The landing page SHALL use a consistent font family matching the documentation site theme for all text content.

Source: openspec/specs/landing-page/spec.md

The architecture document SHALL include a class-level diagram showing the public interface of each major component.

Source: openspec/specs/architecture-diagram-checklist/spec.md

The architecture document SHALL include an activity diagram showing the parser’s step-by-step pipeline: verbatim block pre-scanning, item block extraction with quote-aware bracket matching, body delimiter detection, relationship macro scanning with inline-code exclusion, and result assembly.

Source: openspec/specs/architecture-diagram-checklist/spec.md

The architecture document SHALL include a state diagram showing the graph lifecycle: empty → populated (items added) → complete (relationships added, ready for queries), including which operations are valid in each state.

Source: openspec/specs/architecture-diagram-checklist/spec.md

The architecture document SHALL include an activity diagram showing the file-state caching flow: file content, document attributes, and block positions computed once per file, then reused across all macro-expansion passes.

Source: openspec/specs/architecture-diagram-checklist/spec.md

The update-example-site skill SHALL include a diagram checklist per arc42 section, guidance on when to add each diagram type (class, sequence, activity, state), and conventions for diagram file placement in the examples/ directory.

Source: openspec/specs/architecture-diagram-checklist/spec.md

The example site SHALL demonstrate config extension by adding a use_case role not present in any built-in preset, with a directional leads_to relation to requirement.

Source: openspec/specs/use-case-example/spec.md

The use-cases.adoc page SHALL render traceability:outgoing[] and traceability:incoming[] macros for each use-case item, showing its requirement links.

Source: openspec/specs/use-case-example/spec.md

The example site SHALL generate a usecase-requirements matrix with use-case rows, requirement columns, and leads_to coverage.

Source: openspec/specs/use-case-example/spec.md

The example site SHALL include a delivery-process.adoc document containing process requirements with the process_requirement role. Each process requirement SHALL trace to the product requirements it validates via a validates relation and to the architectural decisions it implements via a deploys relation.

Source: openspec/specs/delivery-process-traceability/spec.md

The delivery-process.adoc SHALL use the same [item] macro format, [#PRQ-XXX, item, role=process_requirement] IDs, and traceability:links[] rendering macros as other example documents.

Source: openspec/specs/delivery-process-traceability/spec.md

The example site configuration SHALL define a process-to-product matrix with process_requirement as rows, requirement as columns, and validates as the coverage relation.

Source: openspec/specs/delivery-process-traceability/spec.md

The unused design-matrix HTML template and its associated partials SHALL be removed, as they are not rendered by any code path.

Source: openspec/specs/template-partials/spec.md

The unused matrix generation methods (generateRequirementsMatrix, generateDesignMatrix, generateAllMatrices) SHALL be removed, as they are not called by any code path.

Source: openspec/specs/template-partials/spec.md