How-To: Run the Spec Cross-Check System

Overview

The Spec Cross-Check system validates documentation consistency, reference integrity, and governance invariant compliance. It catches broken links, missing authority references, prohibited terminology, and SBVR runtime dependencies before they reach production.

Reference: See REF-019: Spec Cross-Check for the complete specification and SDS-035: Governance Invariants for the list of enforced invariants.

Prerequisites

• Node.js 18.x or later
• Access to the repository root directory

Quick Start

Run in Warning Mode (Staging)

1
node scripts/spec-cross-check.js --mode staging --dir docs/specs --output report.json

Run in Error Mode (Production)

1
node scripts/spec-cross-check.js --mode production --dir docs/specs --output report.json

Command Line Options

What Gets Checked

Understanding the Output

Console Output

1
2
3
4
5
6
7
8
9
10
11
12
13
14
🔍 Spec Cross-Check (mode: staging)
   Directory: docs/specs

⚠️  [WARN] shared/sds/042-new-service.md: Privileged actions found without Authority Boundaries reference
❌ [ERROR] cognitive-extension/sds/015-token-service.md: Broken markdown references found

📊 Summary:
   Files scanned: 128
   Checks run: 768
   ❌ Errors: 1
   ⚠️  Warnings: 3
   ✅ Passed: 764

   Report: report.json

JSON Report Structure

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "timestamp": "2025-12-22T16:30:00Z",
  "mode": "staging",
  "filesScanned": 128,
  "checksRun": 768,
  "errors": [
    {
      "file": "cognitive-extension/sds/015-token-service.md",
      "checkId": "CHECK-REF-001",
      "checkName": "Reference Integrity",
      "message": "Broken markdown references found",
      "broken": [
        { "text": "Old Spec", "target": "../sds/999-nonexistent.md" }
      ],
      "fix": "Update file paths or remove dead references"
    }
  ],
  "warnings": [
    {
      "file": "shared/sds/042-new-service.md",
      "checkId": "CHECK-AUTH-001",
      "checkName": "Authority Reference",
      "message": "Privileged actions found without Authority Boundaries reference",
      "triggers": ["key rotation", "break-glass"],
      "fix": "Add reference to SDS-031: Authority & Ownership Boundaries"
    }
  ],
  "passed": [ /* ... */ ]
}

Enforcement Modes

Staging Mode (Default)

• Broken links: Error (blocks build)
• All other checks: Warning (allows build)

Use during development and feature branches.

Production Mode

• Broken links, authority, workflow, SBVR, economics: Error (blocks build)
• Identity references: Warning

Use for PRs targeting main or production branches.

Fixing Common Issues

Issue: Missing Authority Reference

Message: Privileged actions found without Authority Boundaries reference

Fix: Add a reference to SDS-031 somewhere in your document:

1
2
> **Authority Reference**: For role definitions and approval requirements, see 
> **[SDS-031: Authority & Ownership Boundaries](../sds/031-authority-ownership-boundaries.md)**.

Issue: SBVR Runtime Detected

Message: SBVR referenced as runtime dependency

Fix: Replace “SBVR rule” with “SEA™ DSL Policy” or add context indicating import/export:

1
2
3
4
5
6
7
8
<!-- ❌ Wrong -->
The system executes SBVR rules at runtime.

<!-- ✅ Correct -->
The system enforces SEA™ DSL policies at runtime.

<!-- ✅ Also correct (import context) -->
SBVR rules can be imported from external sources and projected to SEA™ DSL.

Issue: Prohibited Economics Term

Message: Prohibited economics/public-chain terminology found

Fix: Remove the term or add explicit disclaimer context:

1
2
3
4
5
6
7
8
<!-- ❌ Wrong -->
Users pay gas fees to mint tokens.

<!-- ✅ Correct -->
There are no gas fees; attestation is free.

<!-- ✅ Also correct (disclaimer context) -->
Unlike public blockchains, there are no gas fees in the IFL.

Issue: Broken Reference

Message: Broken markdown references found

Fix: Update the link to point to an existing file:

1
2
3
4
5
<!-- ❌ Wrong (file doesn't exist) -->
See [Old Spec](../sds/999-nonexistent.md)

<!-- ✅ Correct -->
See [Current Spec](../sds/034-ifl-federated-ledger.md)

CI Integration

The cross-check runs automatically on pull requests affecting docs/specs/**/*.md. See .github/workflows/spec-cross-check.yml for configuration.

Manual CI Trigger

To re-run the check on an existing PR, comment:

1
/rerun-spec-check

Excluding Files

Some files are automatically excluded:

• **/z_conflict_log.md — Conflict tracking
• **/analysis/** — Historical analysis
• **/tutorial/** — Tutorials use simplified language
• **/_archive/** — Archived specs

Check-specific exclusions are defined in REF-019.

Troubleshooting

Script not found

1
Error: Cannot find module 'scripts/spec-cross-check.js'

Fix: Run from the repository root:

1
2
cd /path/to/NewSea
node scripts/spec-cross-check.js --mode staging --dir docs/specs

Node.js Not Installed

1
'node' is not recognized as a command

Fix: Install Node.js 18.x or later from https://nodejs.org/

Permission Denied

1
Error: EACCES: permission denied, open 'report.json'

Fix: Specify a writable output path:

1
node scripts/spec-cross-check.js --output ./tmp/report.json

Related Documentation

• REF-019: Spec Cross-Check — Full specification
• SDS-035: Governance Invariants — Invariant definitions
• SDS-031: Authority & Ownership — Role definitions
• REF-003: Markdown Linting — Complementary linting

Last updated: 2025-12-22