@principled/cairn 1.0.0-beta

package/dist/validation/passes/coverage-pass.js

@@ -0,0 +1,99 @@
+import { createDiagnostic } from '../diagnostic.js';
+import { createRefParserRegistry } from '../../parsers/registry.js';
+import { findProjectRoot } from '../../utils/project-root.js';
+import { minimatch } from 'minimatch';
+import * as fs from 'fs';
+import * as path from 'path';
+const PASS_NAME = 'coverage';
+const EXCLUDE_PATTERNS = [
+    /node_modules/,
+    /\/dist\//,
+    /\.test\.[jt]sx?$/,
+    /\.spec\.[jt]sx?$/,
+    /__tests__\//,
+];
+/**
+ * Coverage pass — bidirectional ref coverage check (W012, W013).
+ * This is an optional pass, not part of the 5 canonical passes.
+ * Only runs when explicitly requested.
+ */
+export function coveragePass(catalog, config) {
+    const diagnostics = [];
+    const parsers = createRefParserRegistry();
+    // Build set of all referenced file::identifier pairs
+    const referencedPairs = new Set();
+    for (const element of catalog.getAllElements()) {
+        const refs = element.get('refs');
+        if (!refs)
+            continue;
+        for (const ref of refs) {
+            referencedPairs.add(`${ref.file}::${ref.identifier}`);
+        }
+    }
+    // W012: Orphan identifiers — parser-driven discovery
+    const excludePatterns = config.coverage?.exclude ?? [];
+    const projectRoot = findProjectRoot(catalog);
+    if (projectRoot) {
+        for (const parser of parsers) {
+            const files = collectFilesByExtension(projectRoot, parser.extensions);
+            for (const absFile of files) {
+                const relFile = path.relative(projectRoot, absFile);
+                if (EXCLUDE_PATTERNS.some(p => p.test(relFile)))
+                    continue;
+                if (excludePatterns.some(pattern => minimatch(relFile, pattern, { dot: true })))
+                    continue;
+                try {
+                    const content = fs.readFileSync(absFile, 'utf-8');
+                    const identifiers = parser.extractIdentifiers(content);
+                    for (const { identifier } of identifiers) {
+                        const key = `${relFile}::${identifier}`;
+                        if (!referencedPairs.has(key)) {
+                            diagnostics.push(createDiagnostic('W012', 'ORPHAN_IDENTIFIER', `Identifier '${identifier}' in ${relFile} is not referenced by any GVP element`, 'warning', PASS_NAME, { details: key }));
+                        }
+                    }
+                }
+                catch {
+                    // File read error — skip
+                }
+            }
+        }
+    }
+    // W013: Decision has no refs (scoped to decisions only)
+    for (const element of catalog.getAllElements()) {
+        if (element.status !== 'active')
+            continue;
+        if (element.categoryName !== 'decision')
+            continue;
+        const refs = element.get('refs');
+        if (!refs || !Array.isArray(refs) || refs.length === 0) {
+            diagnostics.push(createDiagnostic('W013', 'DECISION_NO_REFS', `Decision ${element.toLibraryId()} has no refs`, 'warning', PASS_NAME, { elementId: element.id, documentPath: element.documentPath, categoryName: element.categoryName }));
+        }
+    }
+    return diagnostics;
+}
+/**
+ * Recursively collect files matching given extensions, excluding test/dist/node_modules.
+ */
+function collectFilesByExtension(dir, extensions) {
+    const files = [];
+    try {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (EXCLUDE_PATTERNS.some(p => p.test(fullPath)))
+                continue;
+            if (entry.isDirectory()) {
+                files.push(...collectFilesByExtension(fullPath, extensions));
+            }
+            else if (entry.isFile()) {
+                const ext = path.extname(entry.name).toLowerCase();
+                if (extensions.includes(ext)) {
+                    files.push(fullPath);
+                }
+            }
+        }
+    }
+    catch { /* skip unreadable dirs */ }
+    return files;
+}
+//# sourceMappingURL=coverage-pass.js.map

package/dist/validation/passes/coverage-pass.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage-pass.js","sourceRoot":"","sources":["../../../src/validation/passes/coverage-pass.ts"],"names":[],"mappings":"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"}

package/dist/validation/passes/index.d.ts

@@ -0,0 +1,6 @@
+import type { ValidationPass } from '../runner.js';
+/** Built-in validation passes in canonical order (DEC-5.9) */
+export declare const builtinPasses: Map<string, ValidationPass>;
+/** Optional passes that only run when explicitly requested */
+export declare const optionalPasses: Map<string, ValidationPass>;
+//# sourceMappingURL=index.d.ts.map

package/dist/validation/passes/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/validation/passes/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAQnD,8DAA8D;AAC9D,eAAO,MAAM,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAMpD,CAAC;AAEH,8DAA8D;AAC9D,eAAO,MAAM,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAErD,CAAC"}

package/dist/validation/passes/index.js

@@ -0,0 +1,19 @@
+import { schemaPass } from './schema-pass.js';
+import { structuralPass } from './structural-pass.js';
+import { traceabilityPass } from './traceability-pass.js';
+import { semanticPass } from './semantic-pass.js';
+import { userRulesPass } from './user-rules-pass.js';
+import { coveragePass } from './coverage-pass.js';
+/** Built-in validation passes in canonical order (DEC-5.9) */
+export const builtinPasses = new Map([
+    ['schema', schemaPass],
+    ['structural', structuralPass],
+    ['traceability', traceabilityPass],
+    ['semantic', semanticPass],
+    ['user_rules', userRulesPass],
+]);
+/** Optional passes that only run when explicitly requested */
+export const optionalPasses = new Map([
+    ['coverage', coveragePass],
+]);
+//# sourceMappingURL=index.js.map

package/dist/validation/passes/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/validation/passes/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,8DAA8D;AAC9D,MAAM,CAAC,MAAM,aAAa,GAAgC,IAAI,GAAG,CAAC;IAChE,CAAC,QAAQ,EAAE,UAAU,CAAC;IACtB,CAAC,YAAY,EAAE,cAAc,CAAC;IAC9B,CAAC,cAAc,EAAE,gBAAgB,CAAC;IAClC,CAAC,UAAU,EAAE,YAAY,CAAC;IAC1B,CAAC,YAAY,EAAE,aAAa,CAAC;CAC9B,CAAC,CAAC;AAEH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,cAAc,GAAgC,IAAI,GAAG,CAAC;IACjE,CAAC,UAAU,EAAE,YAAY,CAAC;CAC3B,CAAC,CAAC"}

package/dist/validation/passes/schema-pass.d.ts

@@ -0,0 +1,12 @@
+import type { Catalog } from '../../catalog/catalog.js';
+import type { GVPConfig } from '../../config/schema.js';
+import type { Diagnostic } from '../diagnostic.js';
+/**
+ * Validates element content against Zod schemas (VAL-3).
+ *
+ * Schema validation happens at catalog construction via Zod schemas.
+ * This pass catches any elements that were loaded with passthrough
+ * and might have invalid dynamic fields after merge/inheritance.
+ */
+export declare function schemaPass(catalog: Catalog, config: GVPConfig): Diagnostic[];
+//# sourceMappingURL=schema-pass.d.ts.map

package/dist/validation/passes/schema-pass.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-pass.d.ts","sourceRoot":"","sources":["../../../src/validation/passes/schema-pass.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKnD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,GAAG,UAAU,EAAE,CAoC5E"}

package/dist/validation/passes/schema-pass.js

@@ -0,0 +1,38 @@
+import { createDiagnostic } from '../diagnostic.js';
+const PASS_NAME = 'schema';
+/**
+ * Validates element content against Zod schemas (VAL-3).
+ *
+ * Schema validation happens at catalog construction via Zod schemas.
+ * This pass catches any elements that were loaded with passthrough
+ * and might have invalid dynamic fields after merge/inheritance.
+ */
+export function schemaPass(catalog, config) {
+    const diagnostics = [];
+    for (const element of catalog.getAllElements()) {
+        let schema;
+        try {
+            schema = catalog.registry.getElementSchema(element.categoryName, {
+                defaultTimezone: config.default_timezone,
+            });
+        }
+        catch {
+            // Unknown category — structural pass handles this
+            continue;
+        }
+        const result = schema.safeParse(element.data);
+        if (!result.success) {
+            for (const issue of result.error.issues) {
+                const fieldPath = issue.path.join('.');
+                diagnostics.push(createDiagnostic('E004', 'SCHEMA_VALIDATION', `Element ${element.toLibraryId()} field '${fieldPath}': ${issue.message}`, 'error', PASS_NAME, {
+                    elementId: element.id,
+                    documentPath: element.documentPath,
+                    categoryName: element.categoryName,
+                    fieldName: fieldPath || undefined,
+                }));
+            }
+        }
+    }
+    return diagnostics;
+}
+//# sourceMappingURL=schema-pass.js.map

package/dist/validation/passes/schema-pass.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-pass.js","sourceRoot":"","sources":["../../../src/validation/passes/schema-pass.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,SAAS,GAAG,QAAQ,CAAC;AAE3B;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,OAAgB,EAAE,MAAiB;IAC5D,MAAM,WAAW,GAAiB,EAAE,CAAC;IAErC,KAAK,MAAM,OAAO,IAAI,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC;QAC/C,IAAI,MAAM,CAAC;QACX,IAAI,CAAC;YACH,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,OAAO,CAAC,YAAY,EAAE;gBAC/D,eAAe,EAAE,MAAM,CAAC,gBAAgB;aACzC,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,kDAAkD;YAClD,SAAS;QACX,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC9C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;gBACxC,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACvC,WAAW,CAAC,IAAI,CAAC,gBAAgB,CAC/B,MAAM,EACN,mBAAmB,EACnB,WAAW,OAAO,CAAC,WAAW,EAAE,WAAW,SAAS,MAAM,KAAK,CAAC,OAAO,EAAE,EACzE,OAAO,EACP,SAAS,EACT;oBACE,SAAS,EAAE,OAAO,CAAC,EAAE;oBACrB,YAAY,EAAE,OAAO,CAAC,YAAY;oBAClC,YAAY,EAAE,OAAO,CAAC,YAAY;oBAClC,SAAS,EAAE,SAAS,IAAI,SAAS;iBAClC,CACF,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/validation/passes/semantic-pass.d.ts

@@ -0,0 +1,8 @@
+import type { Catalog } from '../../catalog/catalog.js';
+import type { GVPConfig } from '../../config/schema.js';
+import type { Diagnostic } from '../diagnostic.js';
+/**
+ * Semantic warnings W001-W006 (VAL-4).
+ */
+export declare function semanticPass(catalog: Catalog, _config: GVPConfig): Diagnostic[];
+//# sourceMappingURL=semantic-pass.d.ts.map

package/dist/validation/passes/semantic-pass.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-pass.d.ts","sourceRoot":"","sources":["../../../src/validation/passes/semantic-pass.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAUnD;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,GAAG,UAAU,EAAE,CA6K/E"}

package/dist/validation/passes/semantic-pass.js

@@ -0,0 +1,126 @@
+import { createDiagnostic } from '../diagnostic.js';
+import { isStale } from '../../provenance/staleness.js';
+import { createRefParserRegistry, findParser } from '../../parsers/registry.js';
+import { findProjectRoot } from '../../utils/project-root.js';
+import * as fs from 'fs';
+import * as path from 'path';
+const PASS_NAME = 'semantic';
+/**
+ * Semantic warnings W001-W006 (VAL-4).
+ */
+export function semanticPass(catalog, _config) {
+    const diagnostics = [];
+    // Build lookup for resolving maps_to references
+    const elementLookup = new Map();
+    for (const el of catalog.getAllElements()) {
+        elementLookup.set(el.toLibraryId(), el);
+        elementLookup.set(el.hashKey(), el);
+    }
+    // W001: Empty maps_to on non-root active element (VAL-4)
+    for (const element of catalog.getAllElements()) {
+        if (element.status !== 'active')
+            continue;
+        if (element.maps_to.length > 0)
+            continue;
+        const catDef = catalog.registry.getByName(element.categoryName);
+        if (!catDef || catDef.is_root)
+            continue;
+        // Non-root active element with no maps_to
+        diagnostics.push(createDiagnostic('W001', 'EMPTY_MAPS_TO', `Element ${element.toLibraryId()} is a non-root active element with no maps_to references`, 'warning', PASS_NAME, { elementId: element.id, documentPath: element.documentPath, categoryName: element.categoryName }));
+    }
+    // W002: Empty document (no active elements)
+    for (const doc of catalog.documents) {
+        const activeElements = doc.getAllElements().filter(e => e.status === 'active');
+        if (activeElements.length === 0) {
+            diagnostics.push(createDiagnostic('W002', 'EMPTY_DOCUMENT', `Document '${doc.name}' contains no active elements`, 'warning', PASS_NAME, { documentPath: doc.documentPath }));
+        }
+    }
+    // W005: Self-document-only mapping (DEC-5.5: always fires, suppress via diagnostic system)
+    for (const element of catalog.getAllElements()) {
+        if (element.status !== 'active')
+            continue;
+        if (element.maps_to.length === 0)
+            continue;
+        const catDef = catalog.registry.getByName(element.categoryName);
+        if (catDef?.is_root)
+            continue;
+        const allSelfDocument = element.maps_to.every(ref => {
+            const target = elementLookup.get(ref);
+            return target && target.documentPath === element.documentPath;
+        });
+        if (allSelfDocument) {
+            diagnostics.push(createDiagnostic('W005', 'SELF_DOCUMENT_MAPPING', `Element ${element.toLibraryId()} maps only to elements within its own document`, 'warning', PASS_NAME, { elementId: element.id, documentPath: element.documentPath }));
+        }
+    }
+    // W006: Staleness — element has unreviewed non-skip-review updates (DEC-4.7)
+    for (const element of catalog.getAllElements()) {
+        if (element.status !== 'active')
+            continue;
+        if (isStale(element)) {
+            diagnostics.push(createDiagnostic('W006', 'STALE_ELEMENT', `Element ${element.toLibraryId()} has unreviewed updates`, 'warning', PASS_NAME, { elementId: element.id, documentPath: element.documentPath }));
+        }
+    }
+    // W004: Orphan element — truly isolated (no incoming AND no outgoing edges)
+    {
+        // Build a set of all elements that are targets of some maps_to
+        const mappedToSet = new Set();
+        for (const el of catalog.getAllElements()) {
+            for (const ref of el.maps_to) {
+                mappedToSet.add(ref);
+            }
+        }
+        for (const element of catalog.getAllElements()) {
+            if (element.status !== 'active')
+                continue;
+            const catDef = catalog.registry.getByName(element.categoryName);
+            if (!catDef || catDef.is_root)
+                continue;
+            const libId = element.toLibraryId();
+            const hKey = element.hashKey();
+            const hasIncoming = mappedToSet.has(libId) || mappedToSet.has(hKey);
+            const hasOutgoing = element.maps_to.length > 0;
+            // Only flag if truly isolated — no edges in either direction
+            if (!hasIncoming && !hasOutgoing) {
+                diagnostics.push(createDiagnostic('W004', 'ORPHAN_ELEMENT', `Element ${libId} is isolated — nothing maps to it and it maps to nothing`, 'warning', PASS_NAME, { elementId: element.id, documentPath: element.documentPath, categoryName: element.categoryName }));
+            }
+        }
+    }
+    // W010/W011: Ref file/identifier validation (DEC-10.5)
+    // Determine project root by walking up from first document's filePath looking for .git/
+    const projectRoot = findProjectRoot(catalog);
+    if (projectRoot) {
+        const parsers = createRefParserRegistry();
+        for (const element of catalog.getAllElements()) {
+            const refs = element.get('refs');
+            if (!refs || !Array.isArray(refs))
+                continue;
+            for (const ref of refs) {
+                const absPath = path.resolve(projectRoot, ref.file);
+                // W010: Ref file does not exist on disk
+                if (!fs.existsSync(absPath)) {
+                    diagnostics.push(createDiagnostic('W010', 'REF_FILE_MISSING', `Element ${element.toLibraryId()} ref file does not exist: ${ref.file}`, 'warning', PASS_NAME, { elementId: element.id, documentPath: element.documentPath, details: ref.file }));
+                    continue;
+                }
+                // W011: Ref identifier not found in file
+                if (ref.identifier) {
+                    const ext = path.extname(ref.file);
+                    const parser = findParser(ext, parsers);
+                    if (parser) {
+                        try {
+                            const content = fs.readFileSync(absPath, 'utf-8');
+                            const block = parser.extractBlock(content, ref.identifier);
+                            if (block === null) {
+                                diagnostics.push(createDiagnostic('W011', 'REF_IDENTIFIER_MISSING', `Element ${element.toLibraryId()} ref identifier not found in ${ref.file}: ${ref.identifier}`, 'warning', PASS_NAME, { elementId: element.id, documentPath: element.documentPath, details: `${ref.file}::${ref.identifier}` }));
+                            }
+                        }
+                        catch {
+                            // File read error — skip silently (W010 would have caught non-existent files)
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return diagnostics;
+}
+//# sourceMappingURL=semantic-pass.js.map

package/dist/validation/passes/semantic-pass.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-pass.js","sourceRoot":"","sources":["../../../src/validation/passes/semantic-pass.ts"],"names":[],"mappings":"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"}

package/dist/validation/passes/structural-pass.d.ts

@@ -0,0 +1,8 @@
+import type { Catalog } from '../../catalog/catalog.js';
+import type { GVPConfig } from '../../config/schema.js';
+import type { Diagnostic } from '../diagnostic.js';
+/**
+ * Broken references, undefined tags, ID gaps (VAL-1).
+ */
+export declare function structuralPass(catalog: Catalog, _config: GVPConfig): Diagnostic[];
+//# sourceMappingURL=structural-pass.d.ts.map

package/dist/validation/passes/structural-pass.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural-pass.d.ts","sourceRoot":"","sources":["../../../src/validation/passes/structural-pass.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKnD;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,GAAG,UAAU,EAAE,CA6LjF"}

package/dist/validation/passes/structural-pass.js

@@ -0,0 +1,150 @@
+import { createDiagnostic } from '../diagnostic.js';
+const PASS_NAME = 'structural';
+/**
+ * Broken references, undefined tags, ID gaps (VAL-1).
+ */
+export function structuralPass(catalog, _config) {
+    const diagnostics = [];
+    // Build a set of all known element identifiers for fast lookup
+    const knownIds = new Set();
+    for (const element of catalog.getAllElements()) {
+        knownIds.add(element.toLibraryId());
+        knownIds.add(element.hashKey());
+    }
+    // E001: Broken maps_to references
+    for (const element of catalog.getAllElements()) {
+        for (const ref of element.maps_to) {
+            if (!knownIds.has(ref)) {
+                diagnostics.push(createDiagnostic('E001', 'BROKEN_REFERENCE', `Element ${element.toLibraryId()} references '${ref}' in maps_to, but no matching element was found`, 'error', PASS_NAME, { elementId: element.id, documentPath: element.documentPath }));
+            }
+        }
+    }
+    // W007: Undefined tags — element uses a tag not defined in its own library's documents (DEC-2.10: within-library scope)
+    // Group tag definitions by source (library)
+    const tagsBySource = new Map();
+    for (const doc of catalog.documents) {
+        const docTags = doc.getTagDefinitions();
+        if (!tagsBySource.has(doc.source)) {
+            tagsBySource.set(doc.source, new Set());
+        }
+        const sourceTagSet = tagsBySource.get(doc.source);
+        for (const tagName of Object.keys(docTags)) {
+            sourceTagSet.add(tagName);
+        }
+    }
+    for (const element of catalog.getAllElements()) {
+        const sourceDefinedTags = tagsBySource.get(element.source) ?? new Set();
+        for (const tag of element.tags) {
+            if (!sourceDefinedTags.has(tag)) {
+                diagnostics.push(createDiagnostic('W007', 'UNDEFINED_TAG', `Element ${element.toLibraryId()} uses tag '${tag}' which is not defined in its library's tag definitions`, 'warning', PASS_NAME, { elementId: element.id, documentPath: element.documentPath }));
+            }
+        }
+    }
+    // W009: ID sequence gaps within a category in a document
+    for (const doc of catalog.documents) {
+        // Group elements by category within this document
+        const categoryElements = new Map();
+        for (const element of doc.getAllElements()) {
+            const catDef = catalog.registry.getByName(element.categoryName);
+            if (!catDef)
+                continue;
+            const prefix = catDef.id_prefix;
+            // Extract numeric suffix from ID (e.g., "G3" -> 3)
+            const match = element.id.match(new RegExp(`^${escapeRegex(prefix)}(\\d+)$`));
+            if (!match)
+                continue;
+            const ids = categoryElements.get(element.categoryName) ?? [];
+            ids.push(element.id);
+            categoryElements.set(element.categoryName, ids);
+        }
+        for (const [categoryName, ids] of categoryElements) {
+            const catDef = catalog.registry.getByName(categoryName);
+            if (!catDef)
+                continue;
+            const prefix = catDef.id_prefix;
+            // Extract and sort numeric suffixes
+            const nums = ids
+                .map(id => {
+                const m = id.match(new RegExp(`^${escapeRegex(prefix)}(\\d+)$`));
+                return m ? parseInt(m[1], 10) : null;
+            })
+                .filter((n) => n !== null)
+                .sort((a, b) => a - b);
+            if (nums.length < 2)
+                continue;
+            // Check for gaps
+            for (let i = 1; i < nums.length; i++) {
+                if (nums[i] - nums[i - 1] > 1) {
+                    const missingStart = nums[i - 1] + 1;
+                    const missingEnd = nums[i] - 1;
+                    const missingRange = missingStart === missingEnd
+                        ? `${prefix}${missingStart}`
+                        : `${prefix}${missingStart}-${prefix}${missingEnd}`;
+                    diagnostics.push(createDiagnostic('W009', 'ID_SEQUENCE_GAP', `Document '${doc.name}' has gap in ${categoryName} IDs: missing ${missingRange}`, 'warning', PASS_NAME, { documentPath: doc.documentPath, categoryName }));
+                }
+            }
+        }
+    }
+    // E002: Duplicate element ID within a category in a document
+    for (const doc of catalog.documents) {
+        const seenIds = new Map(); // category -> Set<id>
+        for (const el of doc.getAllElements()) {
+            if (!seenIds.has(el.categoryName))
+                seenIds.set(el.categoryName, new Set());
+            const ids = seenIds.get(el.categoryName);
+            if (ids.has(el.id)) {
+                diagnostics.push(createDiagnostic('E002', 'DUPLICATE_ELEMENT_ID', `Document '${doc.name}' has duplicate ${el.categoryName} element ID '${el.id}'`, 'error', PASS_NAME, { elementId: el.id, documentPath: doc.documentPath, categoryName: el.categoryName }));
+            }
+            ids.add(el.id);
+        }
+    }
+    // W008: Duplicate category definition within a single library (same source)
+    {
+        const catDefsBySource = new Map(); // source -> (catName -> docPaths[])
+        for (const doc of catalog.documents) {
+            const docCats = doc.getCategoryDefinitions();
+            for (const catName of Object.keys(docCats)) {
+                if (!catDefsBySource.has(doc.source))
+                    catDefsBySource.set(doc.source, new Map());
+                const sourceCats = catDefsBySource.get(doc.source);
+                if (!sourceCats.has(catName))
+                    sourceCats.set(catName, []);
+                sourceCats.get(catName).push(doc.documentPath);
+            }
+        }
+        for (const [, sourceCats] of catDefsBySource) {
+            for (const [catName, docPaths] of sourceCats) {
+                if (docPaths.length > 1) {
+                    diagnostics.push(createDiagnostic('W008', 'DUPLICATE_CATEGORY_DEF', `Category '${catName}' is defined in multiple documents within the same library: ${docPaths.join(', ')}`, 'warning', PASS_NAME, { categoryName: catName, details: docPaths.join(', ') }));
+                }
+            }
+        }
+    }
+    // E003: Broken inheritance — document references a parent that doesn't exist
+    const knownDocPaths = new Set();
+    for (const doc of catalog.documents) {
+        knownDocPaths.add(doc.documentPath);
+        knownDocPaths.add(doc.source + ':' + doc.documentPath);
+    }
+    for (const doc of catalog.documents) {
+        if (!doc.meta.inherits)
+            continue;
+        const inherits = doc.meta.inherits;
+        for (const parent of inherits) {
+            const parentPath = typeof parent === 'string' ? parent : parent.source;
+            // The parent should be in the catalog's documents if inheritance resolved correctly.
+            // If it's listed but not found, it's a broken reference.
+            const found = catalog.documents.some(d => d.documentPath === parentPath ||
+                d.source + ':' + d.documentPath === parentPath);
+            if (!found) {
+                diagnostics.push(createDiagnostic('E003', 'BROKEN_INHERITANCE', `Document '${doc.name}' inherits from '${parentPath}' which does not exist in the catalog`, 'error', PASS_NAME, { documentPath: doc.documentPath }));
+            }
+        }
+    }
+    return diagnostics;
+}
+/** Escape regex special characters in a string */
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=structural-pass.js.map

package/dist/validation/passes/structural-pass.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural-pass.js","sourceRoot":"","sources":["../../../src/validation/passes/structural-pass.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,SAAS,GAAG,YAAY,CAAC;AAE/B;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,OAAgB,EAAE,OAAkB;IACjE,MAAM,WAAW,GAAiB,EAAE,CAAC;IAErC,+DAA+D;IAC/D,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,KAAK,MAAM,OAAO,IAAI,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC;QAC/C,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;QACpC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAClC,CAAC;IAED,kCAAkC;IAClC,KAAK,MAAM,OAAO,IAAI,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC;QAC/C,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YAClC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBACvB,WAAW,CAAC,IAAI,CAAC,gBAAgB,CAC/B,MAAM,EACN,kBAAkB,EAClB,WAAW,OAAO,CAAC,WAAW,EAAE,gBAAgB,GAAG,iDAAiD,EACpG,OAAO,EACP,SAAS,EACT,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,CAC9D,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,wHAAwH;IACxH,4CAA4C;IAC5C,MAAM,YAAY,GAAG,IAAI,GAAG,EAAuB,CAAC;IACpD,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QACpC,MAAM,OAAO,GAAG,GAAG,CAAC,iBAAiB,EAAE,CAAC;QACxC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAClC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;QAC1C,CAAC;QACD,MAAM,YAAY,GAAG,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAE,CAAC;QACnD,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;YAC3C,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IACD,KAAK,MAAM,OAAO,IAAI,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC;QAC/C,MAAM,iBAAiB,GAAG,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,IAAI,GAAG,EAAU,CAAC;QAChF,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;YAC/B,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBAChC,WAAW,CAAC,IAAI,CAAC,gBAAgB,CAC/B,MAAM,EACN,eAAe,EACf,WAAW,OAAO,CAAC,WAAW,EAAE,cAAc,GAAG,yDAAyD,EAC1G,SAAS,EACT,SAAS,EACT,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,CAC9D,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,yDAAyD;IACzD,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QACpC,kDAAkD;QAClD,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAoB,CAAC;QACrD,KAAK,MAAM,OAAO,IAAI,GAAG,CAAC,cAAc,EAAE,EAAE,CAAC;YAC3C,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;YAChE,IAAI,CAAC,MAAM;gBAAE,SAAS;YAEtB,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC;YAChC,mDAAmD;YACnD,MAAM,KAAK,GAAG,OAAO,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,IAAI,WAAW,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;YAC7E,IAAI,CAAC,KAAK;gBAAE,SAAS;YAErB,MAAM,GAAG,GAAG,gBAAgB,CAAC,GAAG,CAAC,OAAO,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC;YAC7D,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YACrB,gBAAgB,CAAC,GAAG,CAAC,OAAO,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC;QAClD,CAAC;QAED,KAAK,MAAM,CAAC,YAAY,EAAE,GAAG,CAAC,IAAI,gBAAgB,EAAE,CAAC;YACnD,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;YACxD,IAAI,CAAC,MAAM;gBAAE,SAAS;YACtB,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC;YAEhC,oCAAoC;YACpC,MAAM,IAAI,GAAG,GAAG;iBACb,GAAG,CAAC,EAAE,CAAC,EAAE;gBACR,MAAM,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,IAAI,WAAW,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;gBACjE,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YACxC,CAAC,CAAC;iBACD,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC;iBACtC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAEzB,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;gBAAE,SAAS;YAE9B,iBAAiB;YACjB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBACrC,IAAI,IAAI,CAAC,CAAC,CAAE,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAE,GAAG,CAAC,EAAE,CAAC;oBAChC,MAAM,YAAY,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAE,GAAG,CAAC,CAAC;oBACtC,MAAM,UAAU,GAAG,IAAI,CAAC,CAAC,CAAE,GAAG,CAAC,CAAC;oBAChC,MAAM,YAAY,GAAG,YAAY,KAAK,UAAU;wBAC9C,CAAC,CAAC,GAAG,MAAM,GAAG,YAAY,EAAE;wBAC5B,CAAC,CAAC,GAAG,MAAM,GAAG,YAAY,IAAI,MAAM,GAAG,UAAU,EAAE,CAAC;oBACtD,WAAW,CAAC,IAAI,CAAC,gBAAgB,CAC/B,MAAM,EACN,iBAAiB,EACjB,aAAa,GAAG,CAAC,IAAI,gBAAgB,YAAY,iBAAiB,YAAY,EAAE,EAChF,SAAS,EACT,SAAS,EACT,EAAE,YAAY,EAAE,GAAG,CAAC,YAAY,EAAE,YAAY,EAAE,CACjD,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,6DAA6D;IAC7D,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QACpC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAuB,CAAC,CAAC,sBAAsB;QACtE,KAAK,MAAM,EAAE,IAAI,GAAG,CAAC,cAAc,EAAE,EAAE,CAAC;YACtC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,YAAY,CAAC;gBAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,YAAY,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;YAC3E,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,YAAY,CAAE,CAAC;YAC1C,IAAI,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;gBACnB,WAAW,CAAC,IAAI,CAAC,gBAAgB,CAC/B,MAAM,EACN,sBAAsB,EACtB,aAAa,GAAG,CAAC,IAAI,mBAAmB,EAAE,CAAC,YAAY,gBAAgB,EAAE,CAAC,EAAE,GAAG,EAC/E,OAAO,EACP,SAAS,EACT,EAAE,SAAS,EAAE,EAAE,CAAC,EAAE,EAAE,YAAY,EAAE,GAAG,CAAC,YAAY,EAAE,YAAY,EAAE,EAAE,CAAC,YAAY,EAAE,CACpF,CAAC,CAAC;YACL,CAAC;YACD,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;IAED,4EAA4E;IAC5E,CAAC;QACC,MAAM,eAAe,GAAG,IAAI,GAAG,EAAiC,CAAC,CAAC,oCAAoC;QACtG,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;YACpC,MAAM,OAAO,GAAG,GAAG,CAAC,sBAAsB,EAAE,CAAC;YAC7C,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC3C,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC;oBAAE,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;gBACjF,MAAM,UAAU,GAAG,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAE,CAAC;gBACpD,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC;oBAAE,UAAU,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;gBAC1D,UAAU,CAAC,GAAG,CAAC,OAAO,CAAE,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;YAClD,CAAC;QACH,CAAC;QACD,KAAK,MAAM,CAAC,EAAE,UAAU,CAAC,IAAI,eAAe,EAAE,CAAC;YAC7C,KAAK,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,UAAU,EAAE,CAAC;gBAC7C,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACxB,WAAW,CAAC,IAAI,CAAC,gBAAgB,CAC/B,MAAM,EACN,wBAAwB,EACxB,aAAa,OAAO,+DAA+D,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EACxG,SAAS,EACT,SAAS,EACT,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACxD,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,6EAA6E;IAC7E,MAAM,aAAa,GAAG,IAAI,GAAG,EAAU,CAAC;IACxC,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QACpC,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QACpC,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,GAAG,GAAG,GAAG,CAAC,YAAY,CAAC,CAAC;IACzD,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QACpC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ;YAAE,SAAS;QACjC,MAAM,QAAQ,GAAG,GAAG,CAAC,IAAI,CAAC,QAA2D,CAAC;QACtF,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;YAC9B,MAAM,UAAU,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC;YACvE,qFAAqF;YACrF,yDAAyD;YACzD,MAAM,KAAK,GAAG,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CACvC,CAAC,CAAC,YAAY,KAAK,UAAU;gBAC7B,CAAC,CAAC,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,YAAY,KAAK,UAAU,CAC/C,CAAC;YACF,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,WAAW,CAAC,IAAI,CAAC,gBAAgB,CAC/B,MAAM,EACN,oBAAoB,EACpB,aAAa,GAAG,CAAC,IAAI,oBAAoB,UAAU,uCAAuC,EAC1F,OAAO,EACP,SAAS,EACT,EAAE,YAAY,EAAE,GAAG,CAAC,YAAY,EAAE,CACnC,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,kDAAkD;AAClD,SAAS,WAAW,CAAC,GAAW;IAC9B,OAAO,GAAG,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;AACpD,CAAC"}

package/dist/validation/passes/traceability-pass.d.ts

@@ -0,0 +1,9 @@
+import type { Catalog } from '../../catalog/catalog.js';
+import type { GVPConfig } from '../../config/schema.js';
+import type { Diagnostic } from '../diagnostic.js';
+/**
+ * Mapping rules compliance (VAL-2).
+ * Checks that non-root elements map to appropriate categories per mapping_rules.
+ */
+export declare function traceabilityPass(catalog: Catalog, _config: GVPConfig): Diagnostic[];
+//# sourceMappingURL=traceability-pass.d.ts.map

package/dist/validation/passes/traceability-pass.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceability-pass.d.ts","sourceRoot":"","sources":["../../../src/validation/passes/traceability-pass.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKnD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,GAAG,UAAU,EAAE,CAqGnF"}

package/dist/validation/passes/traceability-pass.js

@@ -0,0 +1,87 @@
+import { createDiagnostic } from '../diagnostic.js';
+const PASS_NAME = 'traceability';
+/**
+ * Mapping rules compliance (VAL-2).
+ * Checks that non-root elements map to appropriate categories per mapping_rules.
+ */
+export function traceabilityPass(catalog, _config) {
+    const diagnostics = [];
+    // Build lookup: libraryId/hashKey -> element
+    const elementLookup = new Map();
+    for (const el of catalog.getAllElements()) {
+        elementLookup.set(el.toLibraryId(), el);
+        elementLookup.set(el.hashKey(), el);
+    }
+    for (const element of catalog.getAllElements()) {
+        if (element.status === 'deprecated' || element.status === 'rejected')
+            continue;
+        const catDef = catalog.registry.getByName(element.categoryName);
+        if (!catDef || catDef.is_root)
+            continue;
+        if (!catDef.mapping_rules || catDef.mapping_rules.length === 0)
+            continue;
+        // mapping_rules is OR of AND groups: [[goal, value], [principle]]
+        // means element must map to (goal AND value) OR (principle)
+        const mappedCategories = new Set();
+        for (const ref of element.maps_to) {
+            const target = elementLookup.get(ref);
+            if (target) {
+                mappedCategories.add(target.categoryName);
+            }
+        }
+        const satisfiesRules = catDef.mapping_rules.some(andGroup => andGroup.every(requiredCat => mappedCategories.has(requiredCat)));
+        // Note: elements with empty maps_to are handled by W001 (EMPTY_MAPS_TO) in the
+        // semantic pass, not W003 here. This is intentional delegation — W003 only fires
+        // when maps_to is non-empty but doesn't satisfy the mapping_rules for the category.
+        if (!satisfiesRules && element.maps_to.length > 0) {
+            diagnostics.push(createDiagnostic('W003', 'MAPPING_RULES_VIOLATION', `Element ${element.toLibraryId()} does not satisfy mapping_rules for category '${element.categoryName}'`, 'warning', PASS_NAME, { elementId: element.id, documentPath: element.documentPath, categoryName: element.categoryName }));
+        }
+    }
+    // W014: Transitive traceability — non-root active elements must trace to at least one root element (R3)
+    {
+        // Identify root categories
+        const rootCategories = new Set();
+        for (const catName of catalog.registry.categoryNames) {
+            const catDef = catalog.registry.getByName(catName);
+            if (catDef?.is_root)
+                rootCategories.add(catName);
+        }
+        for (const element of catalog.getAllElements()) {
+            if (element.status === 'deprecated' || element.status === 'rejected')
+                continue;
+            const catDef = catalog.registry.getByName(element.categoryName);
+            if (!catDef || catDef.is_root)
+                continue;
+            if (element.maps_to.length === 0)
+                continue; // W001 handles this
+            // BFS/DFS walk through maps_to graph to find a root element
+            const visited = new Set();
+            const queue = [element.hashKey()];
+            let foundRoot = false;
+            while (queue.length > 0) {
+                const current = queue.pop();
+                if (visited.has(current))
+                    continue;
+                visited.add(current);
+                const currentEl = elementLookup.get(current);
+                if (!currentEl)
+                    continue;
+                if (rootCategories.has(currentEl.categoryName)) {
+                    foundRoot = true;
+                    break;
+                }
+                for (const ref of currentEl.maps_to) {
+                    const target = elementLookup.get(ref);
+                    if (target && !visited.has(target.hashKey())) {
+                        queue.push(target.hashKey());
+                    }
+                }
+            }
+            if (!foundRoot) {
+                diagnostics.push(createDiagnostic('W014', 'NO_ROOT_TRACE', `Element ${element.toLibraryId()} cannot trace to any root element transitively`, 'warning', PASS_NAME, { elementId: element.id, documentPath: element.documentPath, categoryName: element.categoryName }));
+            }
+        }
+    }
+    return diagnostics;
+}
+//# sourceMappingURL=traceability-pass.js.map