Semantic Content Traceability

What Is Semantic Content Traceability?

In most architecture tools, documentation exists as free text alongside the constructs it describes. There is no formal relationship between the page and the thing it documents. When the construct changes, the documentation silently drifts out of date. Nobody knows which pages need updating until someone reads them and notices the discrepancy.

Semantic Content Traceability solves this by introducing documents edges in the Intent Graph. Each edge binds a page to a specific architectural construct (a model entity, schema, endpoint, graph node, or ADR) and asserts that the page provides meaningful documentation coverage for that construct. Unlike a simple reference that says "this page mentions X", a documents binding says "this page is responsible for documenting X".

Every documents edge carries metadata: a binding source (auto or manual), a structural hash of the target at the time the binding was last confirmed, and a confirmedAt timestamp. This metadata powers staleness detection, coverage reporting, and impact analysis.

Auto-Binding vs Manual Binding

Bindings originate from two sources, and both produce the same documents edge type in the Intent Graph. They differ only in how they are created.

Auto-Binding

Auto-bindings are inferred from content block signals within a page. When a page contains a block that directly references a construct, the system automatically creates a documents edge with bindingSource: 'auto'. No manual action is required.

The following content block types generate auto-bindings:

Manual Binding

Manual bindings are explicitly declared by the user through the page editor's document bindings panel. This is useful when a page provides documentation coverage for a construct that is not directly referenced by any content block. For example, a design principles page might document the rationale behind an entity's structure without embedding a direct entity link.

Manual bindings carry bindingSource: 'manual' and behave identically to auto-bindings for staleness detection, coverage reporting, and impact analysis.

Staleness Detection

The core value of Semantic Content Traceability is knowing when documentation has fallen out of date. The system detects this automatically through structural hashing.

How It Works

Each documents edge stores an FNV-1a structural hash of the target construct at the time the binding was last confirmed. During every Intent Graph rebuild, the system recomputes structural hashes for all constructs. If the current hash differs from the stored hash on the binding, that binding is marked as stale.

This reuses the same FNV-1a hashing infrastructure as governance drift detection. Only structurally significant fields are hashed. For a model entity, this means the label and property names and types. For a schema, it includes the name, extends references, and field definitions. Visual properties, IDs, and metadata are excluded because they do not affect the semantic meaning of the construct.

What Gets Hashed

The structural hash includes only the fields that affect the construct's meaning. Arrays are sorted before hashing for determinism.

Block-Level Indicators

In the page editor, each content block header shows a governance status indicator. Blocks with active documents bindings display a green linked icon with a count. When any referenced construct has changed since the last review, the block shows an orange stale indicator with a "Mark as Reviewed" button. Clicking this button stamps the current structural hash and timestamp on all references, resetting the binding to a fresh state.

The Content Traceability Report

The Content Traceability Report provides a workspace-level view of documentation coverage and freshness. It is available as Tab 19 in the Report Dashboard and supports PDF export through the standard report pipeline.

Report Sections

The report is divided into several sections, each addressing a different aspect of content traceability.

Task Board Integration

Semantic Content Traceability integrates with the Task Board through the standard impact analysis workflow. When a construct is renamed, deleted, or structurally changed, all pages with documents edges to that construct appear in the impact preview dialog.

The architect can choose one of two workflow paths. "Proceed and Track" executes the change immediately and creates task board cards for each affected page, placed in the appropriate severity column. "Track and Resolve First" defers the change and creates planning cards in the Needs Review column, giving the team time to update documentation before the structural change takes effect.

Each generated task card includes the severity level, the affected page and construct, a direct link to the file that needs updating, and the binding source (auto or manual). Cards created from content traceability impacts follow the same lifecycle as any other task board card, moving through columns from identification to completion.

Coverage Scope Configuration

Not every construct type requires documentation. A workspace with hundreds of model entities might only need coverage for schemas and endpoints. The traceabilityCoverageScope setting in project.neoarc defines which construct types are included in coverage calculations.

Supported construct types include model-entity, schema, rest-endpoint, and others registered in the Intent Graph. Only constructs matching the configured scope appear in the Coverage Overview and Unbound Constructs sections of the Content Traceability Report. This prevents coverage percentages from being diluted by construct types that your team does not intend to document.

Proactive Impact Preview

Before any destructive action executes in NeoArc Studio, the Intent Graph is traversed to identify every downstream resource that will be affected. Semantic Content Traceability extends this traversal to include documents edges. When you are about to rename an entity, delete a schema, or restructure an endpoint, the impact preview dialog shows not just the structural dependencies (diagrams, APIs, views) but also every page that documents the affected construct.

This provides proactive notification rather than reactive discovery. Instead of making a change and discovering weeks later that three documentation pages are now inaccurate, the architect sees the full documentation impact at the point of decision. They can update the pages immediately, defer the change until documentation is ready, or proceed with the change and track the documentation updates through the task board.

Summary

Semantic Content Traceability turns documentation from a disconnected artefact into a first-class participant in the architectural model. Bindings are structural and deterministic. Staleness is computed from cryptographic hashes, not estimates. Coverage is measured against a configurable scope that reflects organisational intent. And because traceability flows through the same Intent Graph, impact analysis, and task board infrastructure as every other architectural relationship, documentation maintenance becomes a managed process rather than an afterthought.