@transitrix/diagrams 1.9.18 → 1.11.0

package/dist/activities/resolver.d.ts

@@ -39,6 +39,9 @@ export interface ActionCanonSources {
      *  to each element's inline `goals[]`. */
     relations?: unknown[];
 }
+/** In-memory bag of ACTION ids dropped by `root_action` scoping. Consumed by
+ *  `validateActivities` as `ACT-021`. Not part of the notation. */
+export declare const ACT_021_OMITTED_KEY = "__act021_omitted";
 /**
  * Returns true when the parsed view document uses the canon-projection form
  * (`view_config` key present, no inline `actions[]`). Used by the preview and

package/dist/activities/resolver.js

@@ -11,7 +11,10 @@
  * field name; `type` is the canonical element field per elements/24-action.md
  * §2). Filesystem-free — callable from unit tests without vscode.
  */
-import { isObject, str, strArray, descendantsOf, stripEnvelope } from '../canon-resolver-utils.js';
+import { isObject, str, strArray, stripEnvelope, reachesRootViaParent } from '../canon-resolver-utils.js';
+/** In-memory bag of ACTION ids dropped by `root_action` scoping. Consumed by
+ *  `validateActivities` as `ACT-021`. Not part of the notation. */
+export const ACT_021_OMITTED_KEY = '__act021_omitted';
 /** ACTION elements by id. `notation: action` is canonical; `notation: activity`
  *  is the deprecated pre-2026-06-25 alias (elements/24-action.md §"Deprecated
  *  alias") — accepted the same way `collectByNotation` callers elsewhere do. */
@@ -93,39 +96,32 @@ export function resolveAction(viewDoc, sources) {
         const relGoals = activeActionGoalRelations(relations, id);
         return relGoals.length > 0 ? relGoals : strArray(el['goals']);
     }
-    // 1. Scope by root_action (this action + its descendants), or the full
-    // catalogue when omitted (§5.1: "Omit to include elements from the full
-    // catalogue (or use goals/type_filter for other scoping)").
-    const rootAction = str(scope['root_action']);
-    let candidateIds;
-    if (rootAction) {
-        candidateIds = allActions.has(rootAction) ? descendantsOf(rootAction, allActions) : new Set();
-    }
-    else {
-        candidateIds = new Set(allActions.keys());
-    }
-    // 2. Narrow by goals — only actions linked to at least one listed GOAL
+    // 1. Other scope fields first — the set the view would otherwise select
+    // (07-action.md §5.1). `root_action` then omits (and warns) rather than
+    // silently intersecting first.
+    let otherwiseIds = new Set(allActions.keys());
+    // Narrow by goals — only actions linked to at least one listed GOAL
     // (via an active action_goal relation, or inline goals[] when no relation
     // exists for that action).
     const goalsFilter = strArray(scope['goals']);
     if (goalsFilter.length > 0) {
-        candidateIds = new Set([...candidateIds].filter((id) => effectiveGoals(id, allActions.get(id)).some((g) => goalsFilter.includes(g))));
+        otherwiseIds = new Set([...otherwiseIds].filter((id) => effectiveGoals(id, allActions.get(id)).some((g) => goalsFilter.includes(g))));
     }
-    // 3. Narrow by type_filter — only actions of a listed type.
+    // Narrow by type_filter — only actions of a listed type.
     const typeFilter = strArray(scope['type_filter']);
     if (typeFilter.length > 0) {
-        candidateIds = new Set([...candidateIds].filter((id) => {
+        otherwiseIds = new Set([...otherwiseIds].filter((id) => {
             const el = allActions.get(id);
             const t = str(el?.['type']) ?? str(el?.['activity_type']);
             return t !== undefined && typeFilter.includes(t);
         }));
     }
-    // 4. Narrow by valid_at — only actions in effect on that date. Actions with
+    // Narrow by valid_at — only actions in effect on that date. Actions with
     // no valid_from are not lifecycle-tracked and are kept (permissive default,
     // matching the resolver's general "missing = not excluded" stance).
     const validAt = str(scope['valid_at']);
     if (validAt) {
-        candidateIds = new Set([...candidateIds].filter((id) => {
+        otherwiseIds = new Set([...otherwiseIds].filter((id) => {
             const el = allActions.get(id);
             const from = str(el?.['valid_from']);
             const to = str(el?.['valid_to']);
@@ -136,6 +132,29 @@ export function resolveAction(viewDoc, sources) {
             return true;
         }));
     }
+    const rootAction = str(scope['root_action']);
+    let candidateIds;
+    const omittedOutsideRoot = [];
+    if (rootAction) {
+        if (!allActions.has(rootAction)) {
+            candidateIds = new Set();
+        }
+        else {
+            candidateIds = new Set();
+            for (const id of otherwiseIds) {
+                if (reachesRootViaParent(id, rootAction, allActions)) {
+                    candidateIds.add(id);
+                }
+                else {
+                    omittedOutsideRoot.push(id);
+                }
+            }
+            omittedOutsideRoot.sort();
+        }
+    }
+    else {
+        candidateIds = otherwiseIds;
+    }
     // Element fields map onto Activity fields unchanged, except the canonical
     // `type` (elements/24-action.md §2) which becomes the internal `activity_type`
     // (types.ts `Activity.activity_type`), and `goals` which is resolved via
@@ -168,5 +187,7 @@ export function resolveAction(viewDoc, sources) {
     };
     if (Object.keys(project).length > 0)
         out['project'] = project;
+    if (omittedOutsideRoot.length > 0)
+        out[ACT_021_OMITTED_KEY] = { root: rootAction, ids: omittedOutsideRoot };
     return out;
 }

package/dist/activities/validate.js

@@ -1,5 +1,59 @@
+import { isObject, str, reachesRootViaParent } from '../canon-resolver-utils.js';
+import { ACT_021_OMITTED_KEY } from './resolver.js';
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 const VALID_WEEKDAYS = new Set(['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']);
+function act021Message(actionId, rootId) {
+    return `ACTION "${actionId}" is not "${rootId}" and is not reachable from it via parent`;
+}
+function collectAct021FromProjection(raw) {
+    const bag = raw[ACT_021_OMITTED_KEY];
+    delete raw[ACT_021_OMITTED_KEY];
+    if (!isObject(bag))
+        return [];
+    const root = str(bag['root']);
+    const ids = Array.isArray(bag['ids']) ? bag['ids'] : [];
+    if (!root)
+        return [];
+    const out = [];
+    for (const id of ids) {
+        if (typeof id !== 'string' || !id.trim())
+            continue;
+        out.push({
+            code: 'ACT-021',
+            message: act021Message(id, root),
+            path: 'view_config.scope.root_action',
+        });
+    }
+    return out;
+}
+function collectAct021FromAuthored(raw, actions) {
+    const vc = isObject(raw['view_config']) ? raw['view_config'] : undefined;
+    const scope = vc && isObject(vc['scope']) ? vc['scope'] : undefined;
+    const root = scope ? str(scope['root_action']) : undefined;
+    if (!root)
+        return [];
+    const byId = new Map();
+    for (const el of actions) {
+        if (!isObject(el))
+            continue;
+        const id = str(el['id']);
+        if (id)
+            byId.set(id, el);
+    }
+    if (!byId.has(root))
+        return [];
+    const out = [];
+    for (const id of byId.keys()) {
+        if (reachesRootViaParent(id, root, byId))
+            continue;
+        out.push({
+            code: 'ACT-021',
+            message: act021Message(id, root),
+            path: 'view_config.scope.root_action',
+        });
+    }
+    return out;
+}
 export function validateActivities(input) {
     const errors = [];
     const warnings = [];
@@ -33,6 +87,11 @@ export function validateActivities(input) {
     // Normalise onto raw.activities for the rest of this function (avoids touching downstream code)
     if (!Array.isArray(raw.activities))
         raw.activities = raw.actions;
+    const fromProjection = collectAct021FromProjection(raw);
+    warnings.push(...fromProjection);
+    if (fromProjection.length === 0) {
+        warnings.push(...collectAct021FromAuthored(raw, rawArray));
+    }
     // ACT-014 / ACT-015: project.calendar validation (run before per-activity loop;
     // surfaces clearly even when activities also have issues).
     if (raw.project && typeof raw.project === 'object') {

package/dist/canon-resolver-utils.d.ts

@@ -13,6 +13,9 @@ export declare function strArray(v: unknown): string[];
  *  per the element map's own `parent` field. Used to scope a projection to a
  *  root element and its transitive descendants (WBS / goal hierarchy / etc). */
 export declare function descendantsOf(rootId: string, all: Map<string, Record<string, unknown>>): Set<string>;
+/** Walk `parent` from `id` toward its ancestors until `rootId` or the chain
+ *  ends. Cycle-safe: a cycle is not a path to the root. */
+export declare function reachesRootViaParent(id: string, rootId: string, all: Map<string, Record<string, unknown>>): boolean;
 /** Depth of `id` in its `parent` chain within `all` (root = 0, each step up
  *  adds 1). Cycle-safe (a cycle resolves the entering node to depth 0) and
  *  memoized across calls via the shared `memo` map. */

package/dist/canon-resolver-utils.js

@@ -45,6 +45,22 @@ export function descendantsOf(rootId, all) {
     }
     return result;
 }
+/** Walk `parent` from `id` toward its ancestors until `rootId` or the chain
+ *  ends. Cycle-safe: a cycle is not a path to the root. */
+export function reachesRootViaParent(id, rootId, all) {
+    const seen = new Set();
+    let current = id;
+    while (current) {
+        if (current === rootId)
+            return true;
+        if (seen.has(current))
+            return false;
+        seen.add(current);
+        const el = all.get(current);
+        current = el ? str(el['parent']) : undefined;
+    }
+    return false;
+}
 /** Depth of `id` in its `parent` chain within `all` (root = 0, each step up
  *  adds 1). Cycle-safe (a cycle resolves the entering node to depth 0) and
  *  memoized across calls via the shared `memo` map. */

package/dist/codex/index.d.ts

@@ -1,4 +1,4 @@
-export { CODEX_ARTEFACT_TYPES, EXTERNAL_CODEX_TYPES, INTERNAL_CODEX_TYPES } from './types.js';
+export { CODEX_ARTEFACT_TYPES, EXTERNAL_CODEX_TYPES, INTERNAL_CODEX_TYPES, PRINCIPLE_CODEX_TYPES } from './types.js';
 export type { CodexArtefactType } from './types.js';
 export { validateCodex, isCodexDoc, folderJurisdictionFromPath } from './validate.js';
 export type { CodexValidateOptions } from './validate.js';

package/dist/codex/index.js

@@ -1,2 +1,2 @@
-export { CODEX_ARTEFACT_TYPES, EXTERNAL_CODEX_TYPES, INTERNAL_CODEX_TYPES } from './types.js';
+export { CODEX_ARTEFACT_TYPES, EXTERNAL_CODEX_TYPES, INTERNAL_CODEX_TYPES, PRINCIPLE_CODEX_TYPES } from './types.js';
 export { validateCodex, isCodexDoc, folderJurisdictionFromPath } from './validate.js';

package/dist/codex/types.d.ts

@@ -1,7 +1,14 @@
 /** TYPE prefixes admitted in the codex zone (REQ-003 / 14-codex.md). */
-export declare const CODEX_ARTEFACT_TYPES: readonly ["LAW", "REGULATION", "POLICY", "INTERNAL_STANDARD"];
+export declare const CODEX_ARTEFACT_TYPES: readonly ["LAW", "REGULATION", "POLICY", "INTERNAL_STANDARD", "PRINCIPLE"];
 export type CodexArtefactType = (typeof CODEX_ARTEFACT_TYPES)[number];
 /** External codex artefacts (codex/external/<jurisdiction>/). */
 export declare const EXTERNAL_CODEX_TYPES: readonly CodexArtefactType[];
-/** Internal codex artefacts (codex/internal/). */
+/** Internal codex artefacts (codex/internal/) that carry a named issuing authority (§4). */
 export declare const INTERNAL_CODEX_TYPES: readonly CodexArtefactType[];
+/**
+ * Internal codex artefacts (codex/internal/) with the `PRINCIPLE` shape (§4.1) —
+ * `statement` + `rationale` required, `issuing_authority`/`effective_date`/`established_by`
+ * optional. Kept distinct from {@link INTERNAL_CODEX_TYPES} because the required-field set
+ * differs; both share the same file location.
+ */
+export declare const PRINCIPLE_CODEX_TYPES: readonly CodexArtefactType[];

package/dist/codex/types.js

@@ -1,8 +1,15 @@
-// Codex artefact — external laws/regulations and internal policies/standards.
+// Codex artefact — external laws/regulations and internal policies/standards/principles.
 // Schema: methodology notations/elements/14-codex.md §3–§4.
 /** TYPE prefixes admitted in the codex zone (REQ-003 / 14-codex.md). */
-export const CODEX_ARTEFACT_TYPES = ['LAW', 'REGULATION', 'POLICY', 'INTERNAL_STANDARD'];
+export const CODEX_ARTEFACT_TYPES = ['LAW', 'REGULATION', 'POLICY', 'INTERNAL_STANDARD', 'PRINCIPLE'];
 /** External codex artefacts (codex/external/<jurisdiction>/). */
 export const EXTERNAL_CODEX_TYPES = ['LAW', 'REGULATION'];
-/** Internal codex artefacts (codex/internal/). */
+/** Internal codex artefacts (codex/internal/) that carry a named issuing authority (§4). */
 export const INTERNAL_CODEX_TYPES = ['POLICY', 'INTERNAL_STANDARD'];
+/**
+ * Internal codex artefacts (codex/internal/) with the `PRINCIPLE` shape (§4.1) —
+ * `statement` + `rationale` required, `issuing_authority`/`effective_date`/`established_by`
+ * optional. Kept distinct from {@link INTERNAL_CODEX_TYPES} because the required-field set
+ * differs; both share the same file location.
+ */
+export const PRINCIPLE_CODEX_TYPES = ['PRINCIPLE'];

package/dist/codex/validate.js

@@ -3,11 +3,22 @@
 // CODEX-001 — shape, zone, id grammar, admission envelope.
 // CODEX-002 — `type` field matches the id TYPE prefix when present.
 // CODEX-003 — external artefact frontmatter (jurisdiction, effective_date).
-// CODEX-004 — internal artefact frontmatter (issuing_authority, effective_date).
+// CODEX-004 — internal artefact frontmatter (issuing_authority, effective_date for
+//             POLICY/INTERNAL_STANDARD; statement, rationale for PRINCIPLE — §4.1).
 // CODEX-005 — jurisdiction must match the parent folder under codex/external/
 //             (when `folderJurisdiction` is supplied by the repo sweep).
+// CODEX-006 — a PRINCIPLE artefact does not declare `established_by` (§4.1). The spec
+//             marks this "info" severity; this module has no info tier, so it is
+//             surfaced as a warning — the nearest existing severity that does not fail
+//             `valid`.
+//
+// Note: this file's CODEX-00x numbering predates the spec's own v0.2 renumbering
+// (14-codex.md §6, §8.2) and does not track it code-for-code — e.g. the spec's current
+// CODEX-001 is a folder/jurisdiction check this file assigns to CODEX-005. Realigning the
+// full scheme is out of scope here; this change only adds the purely-additive PRINCIPLE
+// TYPE (§4.1) under the existing local numbering.
 import { isCanonicalId, typeOfId } from '../typed-id.js';
-import { CODEX_ARTEFACT_TYPES, EXTERNAL_CODEX_TYPES, INTERNAL_CODEX_TYPES, } from './types.js';
+import { CODEX_ARTEFACT_TYPES, EXTERNAL_CODEX_TYPES, INTERNAL_CODEX_TYPES, PRINCIPLE_CODEX_TYPES, } from './types.js';
 function isCodexType(type) {
     return type !== null && CODEX_ARTEFACT_TYPES.includes(type);
 }
@@ -31,7 +42,7 @@ export function validateCodex(input, options = {}) {
     if (!isCanonicalId(c.id) || !isCodexType(idType)) {
         errors.push({
             code: 'CODEX-001',
-            message: `id "${String(c.id)}" must be a typed codex id (LAW, REGULATION, POLICY, or INTERNAL_STANDARD).`,
+            message: `id "${String(c.id)}" must be a typed codex id (LAW, REGULATION, POLICY, INTERNAL_STANDARD, or PRINCIPLE).`,
             path: 'id',
         });
     }
@@ -84,6 +95,21 @@ export function validateCodex(input, options = {}) {
             errors.push({ code: 'CODEX-004', message: 'effective_date is required for internal codex artefacts.', path: 'effective_date' });
         }
     }
+    if (artefactType && PRINCIPLE_CODEX_TYPES.includes(artefactType)) {
+        if (typeof c.statement !== 'string' || c.statement.trim() === '') {
+            errors.push({ code: 'CODEX-004', message: 'statement is required for a PRINCIPLE artefact.', path: 'statement' });
+        }
+        if (typeof c.rationale !== 'string' || c.rationale.trim() === '') {
+            errors.push({ code: 'CODEX-004', message: 'rationale is required for a PRINCIPLE artefact.', path: 'rationale' });
+        }
+        if (typeof c.established_by !== 'string' || c.established_by.trim() === '') {
+            warnings.push({
+                code: 'CODEX-006',
+                message: 'established_by is not declared on this PRINCIPLE artefact — admissible, but a review finding for whoever admits it.',
+                path: 'established_by',
+            });
+        }
+    }
     return { valid: errors.length === 0, errors, warnings };
 }
 /** True when a parsed document is a codex-zone artefact candidate. */

package/dist/compliance/classify.d.ts

@@ -30,6 +30,14 @@ export interface ComplianceCanon {
     /** VALIDATION artefacts (28-validation.md) — the validation-domain peer of
      *  `verifications`, anchored on NEED instead of REQUIREMENT. */
     validations: IndexValidation[];
+    /**
+     * Ids rejected by `ingestComplianceDoc` because that id was already present
+     * in the same bucket (two documents claiming one id — transitrix-hq#218).
+     * The second and any later document is dropped rather than silently
+     * duplicating a matrix column; callers that scan a filesystem can surface
+     * this list as a diagnostic.
+     */
+    duplicateIds: string[];
 }
 export declare function emptyCanon(): ComplianceCanon;
 /**
@@ -37,6 +45,8 @@ export declare function emptyCanon(): ComplianceCanon;
  * pushes its projection into `canon`. Products / requirements / assertions are
  * identified by their `notation` tag; codex source documents by `zone: codex`.
  * Returns the artefact id when ingested (so the caller can record its path), or
- * null when the document is not a (well-formed) compliance artefact.
+ * null when the document is not a (well-formed) compliance artefact, or when
+ * its id duplicates one already ingested into the same bucket (see
+ * `canon.duplicateIds`).
  */
 export declare function ingestComplianceDoc(canon: ComplianceCanon, doc: unknown): string | null;

package/dist/compliance/classify.js

@@ -12,16 +12,33 @@ export function emptyCanon() {
         subjects: [],
         needs: [],
         validations: [],
+        duplicateIds: [],
     };
 }
 const str = (v) => (typeof v === 'string' ? v : undefined);
 const strArray = (v) => Array.isArray(v) ? v.filter((x) => typeof x === 'string') : undefined;
+/**
+ * Pushes `item` onto `list` unless `list` already holds an entry with the same
+ * id, in which case the id is recorded in `canon.duplicateIds` and the item is
+ * dropped — two documents claiming one id is a defect (transitrix-hq#218), not
+ * a second matrix column.
+ */
+function pushUnique(canon, list, item) {
+    if (list.some(existing => existing.id === item.id)) {
+        canon.duplicateIds.push(item.id);
+        return false;
+    }
+    list.push(item);
+    return true;
+}
 /**
  * Classifies one parsed YAML document and, if it is a compliance artefact,
  * pushes its projection into `canon`. Products / requirements / assertions are
  * identified by their `notation` tag; codex source documents by `zone: codex`.
  * Returns the artefact id when ingested (so the caller can record its path), or
- * null when the document is not a (well-formed) compliance artefact.
+ * null when the document is not a (well-formed) compliance artefact, or when
+ * its id duplicates one already ingested into the same bucket (see
+ * `canon.duplicateIds`).
  */
 export function ingestComplianceDoc(canon, doc) {
     if (doc === null || typeof doc !== 'object' || Array.isArray(doc))
@@ -31,19 +48,17 @@ export function ingestComplianceDoc(canon, doc) {
     if (!id)
         return null;
     if (d.notation === 'product') {
-        canon.products.push({ id, name: str(d.name) ?? id });
-        return id;
+        return pushUnique(canon, canon.products, { id, name: str(d.name) ?? id }) ? id : null;
     }
     if (d.notation === 'capability' ||
         d.notation === 'process' ||
         d.notation === 'application' ||
         d.notation === 'system') {
-        canon.subjects.push({ id, name: str(d.name) ?? id });
-        return id;
+        return pushUnique(canon, canon.subjects, { id, name: str(d.name) ?? id }) ? id : null;
     }
     if (d.notation === 'requirement' || d.notation === 'constraint') {
         const origin = str(d.origin);
-        canon.requirements.push({
+        const ok = pushUnique(canon, canon.requirements, {
             id,
             name: str(d.name) ?? id,
             severity: str(d.severity),
@@ -57,11 +72,10 @@ export function ingestComplianceDoc(canon, doc) {
             next_review_at: str(d.next_review_at),
             serves: str(d.serves),
         });
-        return id;
+        return ok ? id : null;
     }
     if (d.notation === 'need') {
-        canon.needs.push({ id, name: str(d.name) ?? id });
-        return id;
+        return pushUnique(canon, canon.needs, { id, name: str(d.name) ?? id }) ? id : null;
     }
     if (d.notation === 'validation') {
         const validates = str(d.validates);
@@ -69,13 +83,13 @@ export function ingestComplianceDoc(canon, doc) {
         const outcome = str(d.outcome);
         if (!validates || !method || !outcome)
             return null;
-        canon.validations.push({
+        const ok = pushUnique(canon, canon.validations, {
             id, validates, method, outcome,
             performed_at: str(d.performed_at),
             evidenceCount: Array.isArray(d.evidence) ? d.evidence.length : 0,
             admitted_at: str(d.admitted_at),
         });
-        return id;
+        return ok ? id : null;
     }
     if (d.notation === 'assertion') {
         const about = str(d.about);
@@ -83,7 +97,7 @@ export function ingestComplianceDoc(canon, doc) {
         const status = str(d.status);
         if (!about || !subject || !status)
             return null;
-        canon.assertions.push({
+        const ok = pushUnique(canon, canon.assertions, {
             id, about, subject, status,
             assessed_at: str(d.assessed_at),
             next_review_at: str(d.next_review_at),
@@ -92,7 +106,7 @@ export function ingestComplianceDoc(canon, doc) {
             realised_via: strArray(d.realised_via),
             owner_to_confirm: str(d.owner_to_confirm),
         });
-        return id;
+        return ok ? id : null;
     }
     if (d.notation === 'verification') {
         const verifies = str(d.verifies);
@@ -100,17 +114,17 @@ export function ingestComplianceDoc(canon, doc) {
         const outcome = str(d.outcome);
         if (!verifies || !method || !outcome)
             return null;
-        canon.verifications.push({
+        const ok = pushUnique(canon, canon.verifications, {
             id, verifies, method, outcome,
+            protocol: str(d.protocol),
             performed_at: str(d.performed_at),
             evidenceCount: Array.isArray(d.evidence) ? d.evidence.length : 0,
             admitted_at: str(d.admitted_at),
         });
-        return id;
+        return ok ? id : null;
     }
     if (d.zone === 'codex') {
-        canon.codex.push({ id, name: str(d.name) ?? id, type: str(d.type), jurisdiction: str(d.jurisdiction) });
-        return id;
+        return pushUnique(canon, canon.codex, { id, name: str(d.name) ?? id, type: str(d.type), jurisdiction: str(d.jurisdiction) }) ? id : null;
     }
     return null;
 }

package/dist/compliance/impact.d.ts

@@ -277,7 +277,9 @@ export declare function computeDeadlineStatus(deadline: string | undefined, toda
  * and `config.subjects.capabilities` (in that order).  Subjects with no binding
  * obligation still appear as columns so the gap is visible.
  */
-export declare function buildImpactMatrix(canon: ComplianceCanon, config: ImpactViewConfig, objectDetails?: ObjectDetailInput[]): ImpactMatrix;
+export declare function buildImpactMatrix(canon: ComplianceCanon, config: ImpactViewConfig, objectDetails?: ObjectDetailInput[], join?: {
+    stepHomeProcess?: ReadonlyMap<string, string>;
+}): ImpactMatrix;
 /**
  * Extract stage-level `ObjectDetailInput` from a raw (YAML-parsed)
  * process-blueprint document.

package/dist/compliance/impact.js

@@ -7,6 +7,7 @@
 // (`product` columns × `obligation` rows). Stage / task grouping is planned
 // for CV-3a and intentionally out of scope here.
 import { buildComplianceIndex } from './reverse-index.js';
+import { isStageColumnId } from '../process-blueprint/resolve-columns.js';
 /**
  * Repo-scope cross-reference checks for a parsed compliance-impact view config
  * (#518 Phase C3). Surfaces unresolved subject, obligation, and regime ids before
@@ -390,25 +391,51 @@ function buildTaskColumns(config, objectDetails, isCombined) {
  *
  * At `'product'` grain: `a.subject` must match `col.subjectId`.
  * At `'product-stage'` grain: `a.subject` must match AND either
- * `a.realised_via` is absent (claim covers the whole subject) OR
- * `col.stageId` ∈ `a.realised_via`.
- * At `'product-stage-task'` grain: as above for stage, plus `col.taskId` ∈
- * `a.realised_via` counts as a match (task-level claim covers this task column).
- * A stage-level claim (`col.stageId` ∈ `a.realised_via`) covers all task columns
- * in that stage.
+ * `a.realised_via` is absent (claim covers the whole subject) OR the token
+ * pins this column: a `PROCESS-…` id matching `col.stageId`, or a STEP whose
+ * home process is that column. Sketch `STAGE-…` ids are never a join key.
+ * At `'product-stage-task'` grain: a task-id hit covers that task column; a
+ * process-level claim covers every task column of that process.
  */
-function assertionMatchesColumn(a, col) {
+function assertionMatchesColumn(a, col, stepHomeProcess) {
     if (a.subject !== col.subjectId)
         return false;
     if (!col.stageId)
         return true;
     if (!a.realised_via || a.realised_via.length === 0)
         return true;
-    if (col.taskId) {
-        // Task grain: match on taskId OR on stageId (stage claim covers all tasks).
-        return a.realised_via.includes(col.taskId) || a.realised_via.includes(col.stageId);
+    const stageId = col.stageId;
+    if (isStageColumnId(stageId)) {
+        // Sketch column: only a task-id hit counts — never the STAGE- key.
+        return col.taskId != null && a.realised_via.includes(col.taskId);
     }
-    return a.realised_via.includes(col.stageId);
+    for (const ref of a.realised_via) {
+        if (typeof ref !== 'string')
+            continue;
+        if (isStageColumnId(ref))
+            continue;
+        if (col.taskId && ref === col.taskId)
+            return true;
+        if (ref === stageId)
+            return true;
+        if (!col.taskId && stepHomeProcess?.get(ref) === stageId)
+            return true;
+    }
+    return false;
+}
+function stepHomeFromObjectDetails(objectDetails) {
+    const out = new Map();
+    if (!objectDetails)
+        return out;
+    for (const od of objectDetails) {
+        for (const d of od.details ?? []) {
+            for (const t of d.tasks ?? []) {
+                if (typeof t?.id === 'string' && t.id.length > 0)
+                    out.set(t.id, d.id);
+            }
+        }
+    }
+    return out;
 }
 /**
  * Build the matrix per §5.2.
@@ -430,7 +457,7 @@ function assertionMatchesColumn(a, col) {
  * and `config.subjects.capabilities` (in that order).  Subjects with no binding
  * obligation still appear as columns so the gap is visible.
  */
-export function buildImpactMatrix(canon, config, objectDetails) {
+export function buildImpactMatrix(canon, config, objectDetails, join) {
     const index = buildComplianceIndex({
         requirements: canon.requirements,
         assertions: canon.assertions,
@@ -485,6 +512,7 @@ export function buildImpactMatrix(canon, config, objectDetails) {
     const allowedStatuses = new Set(config.status_display?.show ?? ['compliant', 'partial', 'non_compliant', 'under_review', 'pending_owner', 'n_a']);
     const rowIndex = new Set(obligations.map(r => r.id));
     const cells = obligations.map(() => columns.map(() => emptyCell()));
+    const stepHome = join?.stepHomeProcess ?? stepHomeFromObjectDetails(objectDetails);
     for (let c = 0; c < columns.length; c++) {
         const col = columns[c];
         const subjectAssertions = index.assertionsBySubject.get(col.subjectId) ?? [];
@@ -493,7 +521,7 @@ export function buildImpactMatrix(canon, config, objectDetails) {
                 continue;
             if (!allowedStatuses.has(a.status))
                 continue;
-            if (!assertionMatchesColumn(a, col))
+            if (!assertionMatchesColumn(a, col, stepHome))
                 continue;
             const rowIdx = obligations.findIndex(r => r.id === a.about);
             if (rowIdx < 0)

package/dist/compliance/types.d.ts

@@ -116,6 +116,12 @@ export interface IndexVerification {
     verifies: string;
     method: VerificationMethod;
     outcome: VerificationOutcome;
+    /**
+     * The verification procedure (27-verification.md §2). VERIFICATION carries
+     * no `name` field of its own; `protocol` is the closest human-readable
+     * description and is what a matrix/list view shows as the row's label.
+     */
+    protocol?: string;
     performed_at?: string;
     /** Number of evidence entries — feeds the VERIF-006 gap. */
     evidenceCount?: number;

package/dist/compliance-verification-matrix/build.d.ts

@@ -0,0 +1,17 @@
+import type { ComplianceIndex } from '../compliance/types.js';
+import type { RequirementVerificationMatrix, RequirementVerificationMatrixOptions } from './types.js';
+/**
+ * Builds the repository-wide requirement -> verification matrix.
+ *
+ * Pure projection over an already-built `ComplianceIndex`
+ * (`compliance/reverse-index.ts`) — no I/O, no revalidation. Reuses
+ * `buildGapReport`'s `REQ-VERIF-COVERAGE-001`/`-002` verdicts verbatim rather
+ * than recomputing a competing coverage status.
+ *
+ * Ordering: requirements sorted by id; within a requirement, its verification
+ * rows sorted by verification id. Both are explicit sorts over the index's
+ * values, so the result is independent of the Map's insertion order (which —
+ * for a caller that built the index from a filesystem walk — would otherwise
+ * track directory enumeration order).
+ */
+export declare function buildRequirementVerificationMatrix(index: ComplianceIndex, options?: RequirementVerificationMatrixOptions): RequirementVerificationMatrix;