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 (relation:TARGET[]) 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 preserve inline relationship macros (relation:TARGET[]) inside AsciiDoc verbatim blocks so they remain visible in the rendered output.

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

The system SHALL NOT register inline relationship macros (relation:ID[]) 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).

Source: openspec/specs/bidirectional-relationship-merge/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.

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

If a newly added relationship forms a complementary pair with an existing relationship, then the system 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).

Source: openspec/specs/bidirectional-relationship-merge/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 tracer: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 tracer: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 tracer: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 tracer: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 tracer:outgoing[] and tracer: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 tracer:outgoing[] or tracer: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 tracer:outgoing[] and tracer: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 tracer:outgoing[] and tracer: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 tracer: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 tracer: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 tracer: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 tracer: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 tracer:incoming[] output as it does for tracer: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

Relationship macro expansion SHALL produce xrefs only to items in the same component version as the enclosing page.

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

Relationship macro expansion SHALL produce xrefs only to items in the same version as the enclosing page, spanning components at that version.

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

The generated output from tracer: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 tracer:incoming[].

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

The generated output from tracer:outgoing[] and tracer: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 tracer:outgoing[] or tracer: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 correct Antora xref prefix: 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 tracer:outgoing[] and tracer: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

When excludeComponents names a component, that component’s .adoc pages and partials SHALL be excluded from traceability processing: their items do not enter the graph, their content is not rewritten by relation/graph/coverage macros, and no generated matrices, overview, or role-guidance attachments are registered for that component.

Source: openspec/specs/exclude-components/spec.md

Exclusion SHALL NOT fabricate stub items. A relationship macro authored in an included document whose target item lives only in an excluded component SHALL remain an unresolved "pending target" and be reported as such, exactly as if the target had never been defined.

Source: openspec/specs/exclude-components/spec.md

When a CLI command that harvests a playbook (export neo4j, seed, site-graph) reads the extension’s excludeComponents, the harvested files SHALL omit excluded components so the resulting graph matches the one the Antora build produces.

Source: openspec/specs/exclude-components/spec.md

An absent or empty excludeComponents SHALL leave behavior unchanged, and a component not named in the list SHALL be processed in full.

Source: openspec/specs/exclude-components/spec.md

excludeComponents entries SHALL match the Antora component name exactly; a component whose name merely contains or resembles an entry is not excluded.

Source: openspec/specs/exclude-components/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

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).

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

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 generate matrix links that resolve correctly regardless of where the matrix file is served within the Antora site output, resolving each item from the site root via its published URL so same-component and cross-component targets both resolve.

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

The system SHALL serialize each component version’s traceability graph to a JSON snapshot and register it as a site attachment at traceability/graph.json during the contentClassified event, before document conversion, so the published site carries a machine-readable graph per version.

Source: openspec/specs/graph-json-attachment/spec.md

The generated graph.json SHALL contain the item and relationship lists in the canonical snapshot format: a top-level format field, the component and version, and every item carrying its id, role, title, content, status, attributes, component, module, version, sourceFile, and sourceLine. The snapshot SHALL NOT include per-page pubUrl fields.

Source: openspec/specs/graph-json-attachment/spec.md

The graph JSON snapshot SHALL be emitted only when matrix generation is enabled, so it is produced wherever matrices are and nowhere matrices are not.

Source: openspec/specs/graph-json-attachment/spec.md

The system SHALL emit a graph.json snapshot for a component version with an empty-string version, matching how matrices and the overview are registered for unversioned content.

Source: openspec/specs/graph-json-attachment/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.

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

A preset SHALL NOT extend itself, directly or transitively.

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

When a preset inheritance chain forms a cycle, the system SHALL detect it and report 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

The system 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 traceability configuration SHALL support a roleGuidance section that maps a role name to a page (an AsciiDoc page path) and an optional idPrefix.

Source: openspec/specs/role-guidance/spec.md

The extension SHALL ship default guidance AsciiDoc pages with the built-in presets, so a project that extends a preset receives guidance without authoring its own.

Source: openspec/specs/role-guidance/spec.md

The roleGuidance section SHALL merge through the preset extends chain the same way relations does, with the more-derived config overriding the base.

Source: openspec/specs/role-guidance/spec.md

The CLI SHALL provide a role-guidance <role> command that resolves the guidance through the extends chain and reports the resolved page path and idPrefix.

Source: openspec/specs/role-guidance/spec.md

The extension SHALL register the resolved guidance pages into the content catalog at build time so they render in the consuming site.

Source: openspec/specs/role-guidance/spec.md

The idPrefix reported by the CLI SHALL be treated as advisory: it is a fallback for when the existing project content does not establish a convention, and it SHALL NOT override an established prefix.

Source: openspec/specs/role-guidance/spec.md

The system SHALL provide a tracer: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 tracer: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 tracer: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 tracer:graph[] and tracer: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 request the next ID from a remote allocator when idAllocation.endpoint is configured, instead of scanning local files.

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

A configured-but-unreachable allocator SHALL cause next-id to exit with an error, never silently fall back to a local scan.

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

A --local flag SHALL bypass a configured allocator and use the existing local max+1 scan.

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

An idAllocation.endpoint that is not a non-empty HTTP(S) URL SHALL cause configuration loading to fail.

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

The CLI SHALL provide a seed command that scans items and, for each ID prefix found, reports the numeric value one greater than the highest existing suffix.

Source: openspec/specs/seed-export/spec.md

The seed output SHALL be a YAML prefixes map whose entries carry a numeric start, directly consumable as the id-server’s prefixes configuration.

Source: openspec/specs/seed-export/spec.md

The seed command SHALL accept either -i <dir> to scan a single directory, or a playbook path to harvest every component and repository in that playbook.

Source: openspec/specs/seed-export/spec.md

The seed command SHALL require exactly one input — either -i <dir> or a playbook path — and SHALL exit with an error when neither is provided.

Source: openspec/specs/seed-export/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 isolated 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 orphaned that returns all effectively superseded items that have no incoming functional (non-history) relationships.

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, dangling references, 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 service SHALL respond to GET /next-id?prefix=<prefix> with 200 and a JSON body {"id": "<prefix>-NNN"}, where NNN is the next sequential value for that prefix.

Source: openspec/specs/id-allocation-server/spec.md

The service SHALL never return the same ID twice for the same tenant and prefix, even under concurrent requests, and SHALL never reuse a previously allocated ID.

Source: openspec/specs/id-allocation-server/spec.md

Counters SHALL be keyed by tenant, resolved from the Authorization: Bearer <token> header against projects persisted in the database. The tokens configuration SHALL seed the initial project set. When no admin token is configured and no projects exist, requests SHALL use a default tenant; otherwise an absent, malformed, or unrecognized token SHALL be rejected with 401.

Source: openspec/specs/id-allocation-server/spec.md

Generated IDs SHALL be zero-padded to the configured width for the tenant and prefix, resolving the width per tenant first and falling back to the global prefix width and then a default of 3, applied as a minimum so larger values grow rather than truncate.

Source: openspec/specs/id-allocation-server/spec.md

The service SHALL begin allocation for a tenant and prefix at the tenant’s configured start value for that prefix, falling back to the global prefix start, and defaulting to 1 when neither is configured.

Source: openspec/specs/id-allocation-server/spec.md

The system SHALL allocate collision-free item IDs across concurrent authoring through a shared monotonic allocation source, so that parallel work on the same prefix never produces duplicate IDs in the merged tree.

The local max+1 scan is best-effort and cannot guarantee uniqueness under parallel work; the shared allocator is the mechanism that satisfies this requirement.

Source: openspec/specs/id-allocation-server/spec.md

The admin endpoints SHALL require a bearer token matching the configured adminToken. When no adminToken is configured, the admin endpoints SHALL not exist and requests to them SHALL return 404.

Source: openspec/specs/id-server-project-management/spec.md

GET /admin/projects SHALL return the tenant names of all projects, without token values.

Source: openspec/specs/id-server-project-management/spec.md

POST /admin/projects with a tenant name and token SHALL create a project whose token immediately resolves to that tenant for GET /next-id.

Source: openspec/specs/id-server-project-management/spec.md

PUT /admin/projects/:tenant SHALL replace a project’s token; the old token SHALL immediately stop resolving.

Source: openspec/specs/id-server-project-management/spec.md

DELETE /admin/projects/:tenant SHALL remove a project; its token SHALL immediately stop resolving.

Source: openspec/specs/id-server-project-management/spec.md

Project tokens SHALL be stored as hashes so plaintext tokens are never persisted or returned by the API.

Source: openspec/specs/id-server-project-management/spec.md

The antora-id-server projects subcommand SHALL provide list, add, update, and remove operations that call the admin API.

Source: openspec/specs/id-server-project-management/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 traverse only elements within <article class="doc">.

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

When a traceable item replaces another item, the successor SHALL declare a supersedes relationship to the predecessor.

Source: openspec/specs/traceable-item-supersession/spec.md

When a successor declares a supersedes relationship, the predecessor’s superseded_by relationship SHALL be derivable from the graph.

Source: openspec/specs/traceable-item-supersession/spec.md

An item SHALL be effectively superseded when at least one valid incoming supersedes relationship targets it.

Source: openspec/specs/traceable-item-supersession/spec.md

An effectively superseded item SHALL be considered orphaned when no incoming functional (non-history) relationship targets it.

Source: openspec/specs/traceable-item-supersession/spec.md

If the supersession graph contains a self-reference, duplicate relationship, or cycle, then validation SHALL report an error.

Source: openspec/specs/traceable-item-supersession/spec.md

When a current-state matrix is generated, the system SHALL omit effectively superseded items from both rows and columns by default.

Source: openspec/specs/traceable-item-supersession/spec.md

When a relationship macro renders a functional relationship targeting a superseded item, the system SHALL retain the relationship and identify it as requiring review, naming every direct successor.

Source: openspec/specs/traceable-item-supersession/spec.md

Supersession history relationships SHALL NOT be classified as stale functional links.

Source: openspec/specs/traceable-item-supersession/spec.md

When a superseded item’s source block is rendered, the system SHALL display a superseded marker that links to every direct successor.

Source: openspec/specs/traceable-item-supersession/spec.md

When a supersession check is requested, the CLI SHALL report direct successors and incoming functional relationships requiring review.

Source: openspec/specs/traceable-item-supersession/spec.md

When a supersession check is requested, the CLI SHALL NOT modify any source file.

Source: openspec/specs/traceable-item-supersession/spec.md

When a functional relationship targets an effectively superseded item, validation SHALL emit a non-blocking warning naming the source item, relation type, predecessor, and all direct successors.

Source: openspec/specs/traceable-item-supersession/spec.md

The system SHALL support a display-only renderSuperseded option. When set to false, superseded item blocks and the supersedes-related links in their successors SHALL be omitted from rendered output, without affecting the graph or matrices.

Source: openspec/specs/traceable-item-supersession/spec.md

A dangling link whose type is supersedes or superseded_by SHALL be reported as an advisory worklist item, not a validation error. A dangling link of any other type SHALL remain a validation error.

Source: openspec/specs/traceable-item-supersession/spec.md

When generateOverview is enabled, the system SHALL register the overview as a content-catalog attachment at the configured overviewTarget (default traceability/overview.html), reporting supersession statistics and dangling references.

Source: openspec/specs/supersession-overview/spec.md

The overview page SHALL report the number of managed items, the number of active items, and the number of superseded items.

Source: openspec/specs/supersession-overview/spec.md

The overview page SHALL report a per-role table with columns role, total, active, and superseded.

Source: openspec/specs/supersession-overview/spec.md

The overview page SHALL list every dangling reference — a link whose target item does not exist — showing the source item as an xref, the relation type, and the missing target ID.

Source: openspec/specs/supersession-overview/spec.md

The CLI SHALL provide archive <ID> that moves a superseded item’s full block to a superseded.adoc page in the same module as the source file.

Source: openspec/specs/item-lifecycle/spec.md

The CLI SHALL provide remove <ID> that deletes an orphaned item’s block after a normal confirmation prompt.

Source: openspec/specs/item-lifecycle/spec.md

The CLI SHALL provide a path to delete an isolated item’s block only after the user types the item ID verbatim.

Source: openspec/specs/item-lifecycle/spec.md

Before mutating a file, the CLI SHALL locate the item’s full block from its [#ID, item, …] header to the matching closing -- delimiter, and SHALL refuse to mutate when the extent is ambiguous.

Source: openspec/specs/item-lifecycle/spec.md

When the extension generates matrices, coverage, and the supersession overview at sitePublished, it SHALL use a graph containing every item from every component and version of the site.

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

The contentClassified working graph SHALL include items from every component at the same version, so relationship macros resolve cross-component xrefs. Cross-version isolation is unchanged.

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

When two graph snapshots are compared, the diff SHALL classify each item as added, removed, or modified based on its stable ID, scoped to the item’s component and version when present.

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

A surviving item SHALL be reported as modified when its title, content, role, status, or attributes differs between the snapshots, and the delta SHALL name the changed fields.

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

The diff SHALL report relationship changes only between items that exist in both snapshots.

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

The diff SHALL NOT attempt content-similarity rename detection. A superseded predecessor SHALL appear as removed and its successor as added, with the supersedes relationship reported as a new relationship.

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

The diff SHALL NOT attempt content-similarity rename detection.

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

A superseded predecessor SHALL appear as removed and its successor as added, with the supersedes relationship reported as a new relationship.

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

The diff SHALL be exposed as a public function usable with any configured role or relation vocabulary, without hardcoding any role name.

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

A diff CLI command SHALL scan two source paths, build two graphs, and print the delta without modifying any source file.

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

The tooling SHALL build the complete traceability graph for a playbook’s aggregated content — spanning all content sources, components, and versions — without generating HTML, PDF, or DOCX output.

Source: openspec/specs/multi-source-diff/spec.md

When items are harvested from a playbook, each item SHALL record the component, module, and version of the content source it came from, so the diff can disambiguate same-ID items.

Source: openspec/specs/multi-source-diff/spec.md

A harvested graph SHALL serialize to a canonical JSON snapshot containing the item and relationship lists, with each item carrying its scope fields, so a snapshot can be stored and diffed later.

Source: openspec/specs/multi-source-diff/spec.md

The tooling SHALL diff two JSON snapshots — reporting added, removed, modified, and superseded items — without requiring either version’s sources to be checked out at diff time.

Source: openspec/specs/multi-source-diff/spec.md

The diff SHALL match items by component-qualified identity — component, version when present, and ID — so the same ID in different components or versions is not conflated, while items without a component continue to match by bare ID.

Source: openspec/specs/multi-source-diff/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 tracer:outgoing[] and tracer: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/core/antora-pdf).

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

The @antora-tracer/core npm package SHALL include lib/src/antora-pdf-extension.cjs and export it under the subpath @antora-tracer/core/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/core 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/core/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 keep every traceable [item] block in its current AsciiDoc file.

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

Every functional requirement (REQ) in the self-traceability example SHALL be addressed by at least one design concept (ARC item) via an addresses:REQ-NNN[] link.

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 main branch’s component version descriptor SHALL declare version: main with prerelease: true, so main serves the development docs at /main/ and is excluded from "latest stable" selection.

Source: openspec/specs/component-versioning/spec.md

A maintenance branch SHALL derive its component version from the git refname using a projection in the component version descriptor, so no hand-maintained literal version exists on release refs.

Source: openspec/specs/component-versioning/spec.md

The component version selector SHALL list the main prerelease and the released semantic versions in descending order.

Source: openspec/specs/component-versioning/spec.md

The playbook SHALL set latest_version_segment: stable, so the latest stable (non-prerelease) release is served at /stable/.

Source: openspec/specs/component-versioning/spec.md

The extension SHALL treat an unversioned component version (an empty string) as a valid version rather than substituting a placeholder, so generated attachments resolve via xref from unversioned content.

Source: openspec/specs/component-versioning/spec.md

The project SHALL provide a script that verifies the release invariants across package.json, git tags, maintenance branches, playbook content-source refs, and the changelog, and SHALL exit non-zero on any mismatch.

Source: openspec/specs/release-consistency/spec.md

The script SHALL require that the package.json version, the git tag name, and the changelog entry version all refer to the same major.minor.patch release.

Source: openspec/specs/release-consistency/spec.md

The script SHALL require a maintenance branch named v<major>.<minor>.x for the released v<major>.<minor>.0 tag.

Source: openspec/specs/release-consistency/spec.md

The script SHALL verify that every branch and tag referenced by the CI playbook content sources exists in the repository.

Source: openspec/specs/release-consistency/spec.md

Each published package SHALL carry a SLSA Level 3 provenance attestation linking the tarball to the source commit, workflow, and date that produced it.

Source: openspec/specs/publish-provenance/spec.md

Package releases SHALL be staged from the GitHub Actions release workflow, and approved by a maintainer with two-factor authentication.

Source: openspec/specs/publish-provenance/spec.md

Each release SHALL produce a CycloneDX SBOM for each package, signed with cosign using the workflow’s keyless identity.

Source: openspec/specs/publish-provenance/spec.md

Signing SHALL use Sigstore keyless identity, with no long-lived signing key stored in the repository or its secrets.

Source: openspec/specs/publish-provenance/spec.md

The extension SHALL compute the build version string using git describe --tags --always --dirty, run from the playbook directory, exactly once per Antora build.

Source: openspec/specs/git-describe/spec.md

The extension SHALL set site.keys.git_describe to the computed version string, making it available to HTML Handlebars templates.

Source: openspec/specs/git-describe/spec.md

The extension SHALL set asciidoc.attributes.git_describe to the computed version string, making it available to AsciiDoc content, the PDF theme, and the DOCX converter.

Source: openspec/specs/git-describe/spec.md

When the version string cannot be computed — the build directory is not inside a git repository, or the git command is unavailable or fails — the extension SHALL set neither key and SHALL NOT fail the build.

Source: openspec/specs/git-describe/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 tracer:outgoing[] and tracer: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 tracer: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