Content & Attribution Validation

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• diagram_inventory.json
• build_story_artifact.py
• docs/SOURCE_PROVENANCE.md
• tests/test_story_artifact.py

Content and attribution validation ensures that every visual and narrative element in the Interactive Storytelling Layer (GestaltView Visual Story) accurately reflects its source material. The system uses a strict inventory and automated testing framework to verify that 54 specific visuals remain traceable to the GestaltView Master Wiki v4.0. This validation prevents drift between the architectural claims and the actual code or documentation state.

Sources: README.md

Validation Architecture

The validation system relies on a central inventory file and a Python-based builder that enforces strict counts and metadata checks. The system distinguishes between "Curated" diagrams (which lack original Mermaid source text) and "Capitoned Figures" or "Mermaid Source Snippets" (which are rendered from text found in the PDF).

The diagram shows the data flow from the source PDF through the builder and inventory into the final artifact and validation tests.

Sources: build_story_artifact.py, diagram_inventory.json

Inventory Constraints

The diagram_inventory.json file serves as the source of truth for all content validation. It records the provenance, page numbers, and confidence levels for every item in the visual story. Any discrepancy in the total count of visuals triggers a build failure.

Visual Category	Required Count	Description
Total Visuals	54	The sum of all unique architectural diagrams and figures.
Curated Diagrams	13	Opening diagrams preserved as PDF page crops.
Captioned Figures	39	Later figures preserved as source-page crops.
Mermaid Snippets	2	Visuals rendered directly from raw Mermaid source text.

Sources: diagram_inventory.json:5-10, build_story_artifact.py:344-347

Confidence and Provenance

Each item in the inventory includes a confidence rating and a confidence_note. For curated diagrams, high confidence is established by matching titles and page numbers against the opening visual index of the source PDF. For captioned figures, the system preserves the region between the section header and the figure caption to maintain original context.

Sources: diagram_inventory.json:69-70, build_story_artifact.py:270-275

Automated Verification

The project includes an acceptance test suite to enforce coverage and attribution rules. You run these checks from the repository root using the following command:

python3 -m unittest discover -s tests -v

The tests validate:

1. Coverage: Ensuring all 54 visuals are present and correctly categorized.
2. Attribution: Verifying that every visual links back to its specific source page in the 116-page PDF.
3. Lenses: Confirming that depth-specific explanations (Orientation, System, Architecture) exist for curated items.
4. Asset Integrity: Checking that image crops and renders match the expected paths in story_assets/.

Sources: README.md, diagram_inventory.json:11-15

Build-Time Validation Logic

The build_story_artifact.py script contains hard-coded validation checks that prevent the creation of an invalid index.html. If the builder detects more or fewer than the expected number of visuals, it raises a RuntimeError.

# build_story_artifact.py:344-347
if (curated_count, figure_count, mermaid_count) != (13, 39, 2):
    raise RuntimeError(
        f"Source inventory changed; found curated={curated_count}, "
        f"figures={figure_count}, mermaid snippets={mermaid_count}; "
        f"verify before publishing."
    )

The script also normalizes text to handle PDF extraction artifacts, such as broken ligatures (e.g., "fi", "ffi") and inconsistent whitespace, ensuring that textual attributions remain searchable and accurate.

Sources: build_story_artifact.py:126-135, build_story_artifact.py:344-347

Source Provenance Standards

Every piece of information is mapped to a specific source_ref string. This string combines the document title, the page number, and, where applicable, the nature of the source (e.g., "Mermaid text reproduced from the printed source snippet"). This granular attribution allows developers to trace any claim in the guide back to the original documentation.

Sources: diagram_inventory.json:79, build_story_artifact.py:302-303

The validation system ensures the Interactive Storytelling Layer remains a "source-traceable" artifact. By enforcing strict inventory counts and automated acceptance checks, the project guarantees that the high-level architectural story accurately represents the underlying technical documentation.

Sources: README.md, build_story_artifact.py:2