@transitrix/diagrams 1.0.0 → 1.0.1

package/dist/compliance/coverage-metric.js

@@ -6,38 +6,99 @@
 // thresholds.
 import { buildComplianceIndex } from './reverse-index.js';
 // ── Parser ───────────────────────────────────────────────────────────────────
+function parseRegimes(raw) {
+    const warnings = [];
+    const rawR = raw.regimes;
+    if (!rawR || typeof rawR !== 'object' || Array.isArray(rawR)) {
+        return { regimes: undefined, warnings };
+    }
+    const r = rawR;
+    const include = Array.isArray(r.include)
+        ? r.include.filter((x) => typeof x === 'string')
+        : undefined;
+    const rawF = r.filter;
+    const filter = rawF && typeof rawF === 'object' && !Array.isArray(rawF)
+        ? (() => {
+            const f = rawF;
+            return {
+                jurisdiction: Array.isArray(f.jurisdiction)
+                    ? f.jurisdiction.filter((x) => typeof x === 'string')
+                    : undefined,
+                codex_type: Array.isArray(f.codex_type)
+                    ? f.codex_type.filter((x) => typeof x === 'string')
+                    : undefined,
+            };
+        })()
+        : undefined;
+    if (include?.length && filter) {
+        warnings.push('COVMET-007: both regimes.include and regimes.filter are set; include takes precedence');
+    }
+    return { regimes: { include, filter }, warnings };
+}
+function parseSubjects(raw) {
+    const s = raw.subjects;
+    if (!s || typeof s !== 'object' || Array.isArray(s))
+        return undefined;
+    const obj = s;
+    return {
+        products: Array.isArray(obj.products)
+            ? obj.products.filter((x) => typeof x === 'string')
+            : undefined,
+    };
+}
 /**
- * Validate and normalise a raw (YAML-parsed) document into a
- * `CoverageMetricConfig`. Accepts both the bare top-level object and the
- * wrapped form (`{ coverage_metric: { … } }`).
+ * Parse and validate a raw (YAML-parsed) document into a `CoverageMetricConfig`.
+ *
+ * Accepts:
+ * - `{ view: { id, name, regimes, subjects, thresholds } }` — canonical (new spec)
+ * - `{ coverage_metric: { … } }` — deprecated; `scope.codex` → `regimes.include`
+ * - Bare top-level object — same as deprecated wrapper, no wrapper warning
  */
 export function parseCoverageMetricConfig(raw) {
     if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
         return { ok: false, errors: ['coverage-metric: expected an object at the document root'] };
     }
     const top = raw;
-    // Unwrap optional `coverage_metric:` wrapper.
-    const v = 'coverage_metric' in top &&
+    const errors = [];
+    const warnings = [];
+    let v;
+    let regimes;
+    let subjects;
+    if ('view' in top && top.view && typeof top.view === 'object' && !Array.isArray(top.view)) {
+        // Canonical format: view: { id, name, regimes, subjects, thresholds }
+        v = top.view;
+        const parsed = parseRegimes(v);
+        regimes = parsed.regimes;
+        warnings.push(...parsed.warnings);
+        subjects = parseSubjects(v);
+    }
+    else if ('coverage_metric' in top &&
         top.coverage_metric &&
         typeof top.coverage_metric === 'object' &&
-        !Array.isArray(top.coverage_metric)
-        ? top.coverage_metric
-        : top;
-    const errors = [];
+        !Array.isArray(top.coverage_metric)) {
+        // Deprecated wrapper: coverage_metric: { scope: { codex, jurisdictions, subjects }, … }
+        v = top.coverage_metric;
+        warnings.push('COVMET-DEPRECATED: coverage_metric: wrapper is deprecated; migrate to view:');
+        const r = migrateLegacyScope(v);
+        regimes = r.regimes;
+        subjects = r.subjects;
+    }
+    else {
+        // Bare object — accept as deprecated shape without extra warning
+        v = top;
+        const r = migrateLegacyScope(v);
+        regimes = r.regimes;
+        subjects = r.subjects;
+    }
     if (!v.id || typeof v.id !== 'string')
         errors.push('coverage_metric.id: required string');
     if (!v.name || typeof v.name !== 'string')
         errors.push('coverage_metric.name: required string');
     if (errors.length)
         return { ok: false, errors };
-    const rawScope = v.scope && typeof v.scope === 'object' && !Array.isArray(v.scope)
-        ? v.scope
-        : {};
-    const rawSubjects = rawScope.subjects && typeof rawScope.subjects === 'object' && !Array.isArray(rawScope.subjects)
-        ? rawScope.subjects
-        : {};
-    const rawThresholds = v.thresholds && typeof v.thresholds === 'object' && !Array.isArray(v.thresholds)
-        ? v.thresholds
+    const rawT = v.thresholds;
+    const rawThresholds = rawT && typeof rawT === 'object' && !Array.isArray(rawT)
+        ? rawT
         : {};
     const greenRaw = typeof rawThresholds.green === 'number' ? rawThresholds.green : 0.8;
     const amberRaw = typeof rawThresholds.amber === 'number' ? rawThresholds.amber : 0.5;
@@ -47,31 +108,51 @@ export function parseCoverageMetricConfig(raw) {
         description: typeof v.description === 'string' ? v.description : undefined,
         date: typeof v.date === 'string' ? v.date : undefined,
         version: typeof v.version === 'string' ? v.version : undefined,
-        scope: {
-            jurisdictions: Array.isArray(rawScope.jurisdictions)
-                ? rawScope.jurisdictions.filter((x) => typeof x === 'string')
-                : undefined,
-            codex: Array.isArray(rawScope.codex)
-                ? rawScope.codex.filter((x) => typeof x === 'string')
-                : undefined,
-            subjects: {
-                products: Array.isArray(rawSubjects.products)
-                    ? rawSubjects.products.filter((x) => typeof x === 'string')
-                    : undefined,
-            },
-        },
+        regimes,
+        subjects,
         thresholds: {
             green: Math.max(0, Math.min(1, greenRaw)),
             amber: Math.max(0, Math.min(1, amberRaw)),
         },
+        warnings: warnings.length > 0 ? warnings : undefined,
     };
     return { ok: true, config };
 }
+/** Translate old `scope.codex` / `scope.jurisdictions` / `scope.subjects` to new shape. */
+function migrateLegacyScope(v) {
+    const rawScope = v.scope && typeof v.scope === 'object' && !Array.isArray(v.scope)
+        ? v.scope
+        : {};
+    const codexList = Array.isArray(rawScope.codex)
+        ? rawScope.codex.filter((x) => typeof x === 'string')
+        : undefined;
+    const jurisdictionList = Array.isArray(rawScope.jurisdictions)
+        ? rawScope.jurisdictions.filter((x) => typeof x === 'string')
+        : undefined;
+    let regimes;
+    if (codexList && codexList.length > 0) {
+        regimes = { include: codexList };
+    }
+    else if (jurisdictionList && jurisdictionList.length > 0) {
+        regimes = { filter: { jurisdiction: jurisdictionList } };
+    }
+    const rawSubjectsObj = rawScope.subjects && typeof rawScope.subjects === 'object' && !Array.isArray(rawScope.subjects)
+        ? rawScope.subjects
+        : {};
+    const subjects = {
+        products: Array.isArray(rawSubjectsObj.products)
+            ? rawSubjectsObj.products.filter((x) => typeof x === 'string')
+            : undefined,
+    };
+    return { regimes, subjects };
+}
 // ── Builder ───────────────────────────────────────────────────────────────────
-const ADMITTED = new Set(['compliant', 'partial', 'non_compliant', 'under_review', 'n_a']);
-/** Worst-case aggregate across multiple assertions (excludes n_a when others exist). */
+const ADMITTED = new Set(['compliant', 'partial', 'non_compliant', 'under_review', 'pending_owner', 'n_a']);
+/** Worst-case aggregate across multiple assertions (excludes n_a when others exist).
+ *  Precedence: non_compliant > partial > pending_owner > under_review > compliant > n_a. */
 function aggregateStatus(assertions) {
     let sawPartial = false;
+    let sawPendingOwner = false;
     let sawUnderReview = false;
     let sawCompliant = false;
     for (const a of assertions) {
@@ -79,6 +160,8 @@ function aggregateStatus(assertions) {
             return 'non_compliant';
         if (a.status === 'partial')
             sawPartial = true;
+        else if (a.status === 'pending_owner')
+            sawPendingOwner = true;
         else if (a.status === 'under_review')
             sawUnderReview = true;
         else if (a.status === 'compliant')
@@ -86,6 +169,8 @@ function aggregateStatus(assertions) {
     }
     if (sawPartial)
         return 'partial';
+    if (sawPendingOwner)
+        return 'pending_owner';
     if (sawUnderReview)
         return 'under_review';
     if (sawCompliant)
@@ -101,12 +186,35 @@ function ragFromPct(pct, thresholds, hasData) {
         return 'amber';
     return 'red';
 }
+/**
+ * Resolve the ordered list of codex IDs from the config's `regimes` field:
+ * - `regimes.include` — explicit list, takes precedence.
+ * - `regimes.filter` — resolved against the canon's codex catalogue.
+ * - No `regimes` — all codex entries in the canon.
+ */
+function resolveCodexList(regimes, canon) {
+    if (regimes?.include && regimes.include.length > 0)
+        return regimes.include;
+    if (regimes?.filter) {
+        let docs = [...canon.codex];
+        if (regimes.filter.jurisdiction?.length) {
+            const jurs = regimes.filter.jurisdiction;
+            docs = docs.filter(c => c.jurisdiction != null && jurs.includes(c.jurisdiction));
+        }
+        if (regimes.filter.codex_type?.length) {
+            const types = regimes.filter.codex_type;
+            docs = docs.filter(c => c.type != null && types.includes(c.type));
+        }
+        return docs.map(c => c.id);
+    }
+    return canon.codex.map(c => c.id);
+}
 /**
  * Compute per-codex coverage statistics.
  *
- * For each law (codex ID) in `config.scope.codex`:
+ * For each law (codex ID) resolved from `config.regimes`:
  *  - Collect requirements whose `derived_from` includes that law.
- *  - Optionally restrict to assertions for `config.scope.subjects.products`.
+ *  - Optionally restrict to assertions for `config.subjects.products`.
  *  - Compute compliant / partial / non_compliant / under_review / gap counts.
  *  - Compute coverage % = (compliant + partial) / total and apply RAG.
  */
@@ -115,8 +223,8 @@ export function buildCoverageMatrix(canon, config) {
         requirements: canon.requirements,
         assertions: canon.assertions,
     });
-    const codexList = config.scope.codex ?? [];
-    const productList = config.scope.subjects?.products ?? [];
+    const codexList = resolveCodexList(config.regimes, canon);
+    const productList = config.subjects?.products ?? [];
     const rows = [];
     for (const codexId of codexList) {
         const reqs = index.requirementsByLaw.get(codexId) ?? [];
@@ -126,14 +234,13 @@ export function buildCoverageMatrix(canon, config) {
         let partial = 0;
         let non_compliant = 0;
         let under_review = 0;
+        let pending_owner = 0;
         let gap = 0;
         for (const req of reqs) {
             const allAssertions = index.assertionsByRequirement.get(req.id) ?? [];
             // Filter to admitted statuses, then optionally to scoped products.
             const admitted = allAssertions.filter(a => ADMITTED.has(a.status));
-            const scoped = productList.length > 0
-                ? admitted.filter(a => productList.includes(a.subject))
-                : admitted;
+            const scoped = productList.length > 0 ? admitted.filter(a => productList.includes(a.subject)) : admitted;
             // Exclude pure n_a assertions from counting as coverage.
             const active = scoped.filter(a => a.status !== 'n_a');
             if (active.length === 0) {
@@ -149,6 +256,8 @@ export function buildCoverageMatrix(canon, config) {
                 non_compliant++;
             else if (status === 'under_review')
                 under_review++;
+            else if (status === 'pending_owner')
+                pending_owner++;
             else
                 gap++;
         }
@@ -163,6 +272,7 @@ export function buildCoverageMatrix(canon, config) {
             partial,
             non_compliant,
             under_review,
+            pending_owner,
             gap,
             coveredCount,
             coveragePct,

package/dist/compliance/html.js

@@ -16,6 +16,7 @@ const STATUS_LABELS = {
     partial: 'Partial',
     non_compliant: 'Non-compliant',
     under_review: 'Under review',
+    pending_owner: 'Pending owner',
     n_a: 'N/A',
 };
 function escHtml(s) {
@@ -31,51 +32,52 @@ function badge(status) {
 // A4 portrait with 18mm margins — matches the WeasyPrint one-pager template
 // the site uses. Brand colour `#004d67` mirrors `--ts-brand-primary` from
 // extension/src/compliance-render.ts so the PDF and the Studio preview agree.
-const CSS = `
-@page {
-  size: A4 portrait;
-  margin: 18mm 16mm 22mm;
-  @bottom-left { content: "Transitrix — compliance report"; font: 9pt "Helvetica", "Arial", sans-serif; color: #475569; }
-  @bottom-right { content: "Page " counter(page) " / " counter(pages); font: 9pt "Helvetica", "Arial", sans-serif; color: #475569; }
-}
-html, body { margin: 0; padding: 0; }
-body { font-family: "Helvetica", "Arial", sans-serif; font-size: 10pt; color: #0f172a; line-height: 1.4; }
-.cmp-header { border-bottom: 2px solid #004d67; padding-bottom: 6pt; margin-bottom: 14pt; }
-.cmp-header .cmp-eyebrow { font-size: 8.5pt; letter-spacing: 0.08em; text-transform: uppercase; color: #004d67; font-weight: 700; }
-.cmp-header h1 { font-size: 17pt; margin: 2pt 0 4pt; color: #0f172a; }
-.cmp-header .cmp-stamp { font-size: 9pt; color: #475569; }
-h2 { font-size: 12pt; margin: 16pt 0 6pt; color: #0f172a; page-break-after: avoid; }
-h2 .cmp-count { color: #64748b; font-weight: 400; font-size: 10pt; }
-p.cmp-empty { color: #64748b; font-style: italic; }
-table { border-collapse: collapse; width: 100%; font-size: 9.5pt; margin-bottom: 10pt; }
-th, td { border: 0.5pt solid #cbd5e1; padding: 4pt 6pt; text-align: left; vertical-align: top; }
-th { background: #f1f5f9; font-weight: 700; color: #0f172a; }
-table.cmp-matrix th:first-child, table.cmp-matrix td:first-child { background: #f8fafc; font-weight: 600; }
-code, .cmp-id { font-family: "Menlo", "Consolas", monospace; font-size: 9pt; color: #475569; }
-.cmp-badge { display: inline-block; padding: 1pt 6pt; border-radius: 8pt; font-size: 8.5pt; font-weight: 700; }
-.cmp-compliant { background: #d1fae5; color: #065f46; }
-.cmp-partial { background: #fef9c3; color: #854d0e; }
-.cmp-non_compliant { background: #fee2e2; color: #991b1b; }
-.cmp-under_review { background: #e0f2fe; color: #0c4a6e; }
-.cmp-n_a { background: #f1f5f9; color: #64748b; }
-.cmp-cell-gap { color: #94a3b8; text-align: center; }
-.cmp-req { border: 0.5pt solid #cbd5e1; border-radius: 3pt; margin-bottom: 8pt; page-break-inside: avoid; }
-.cmp-req-head { background: #f1f5f9; padding: 5pt 8pt; }
-.cmp-req-head .cmp-req-name { font-weight: 700; color: #0f172a; }
-.cmp-req-head .cmp-req-id { margin-left: 6pt; color: #475569; font-size: 9pt; font-family: "Menlo", "Consolas", monospace; }
-.cmp-sev { font-size: 8pt; text-transform: uppercase; letter-spacing: 0.06em; margin-left: 8pt; }
-.cmp-sev-high { color: #b91c1c; }
-.cmp-sev-medium { color: #b45309; }
-.cmp-sev-low { color: #2563eb; }
-.cmp-assertions { list-style: none; margin: 0; padding: 0; }
-.cmp-assertions li { padding: 4pt 8pt 4pt 16pt; border-top: 0.5pt solid #e2e8f0; }
-.cmp-assertions li .cmp-meta { color: #475569; font-size: 8.5pt; margin-left: 6pt; }
-.cmp-section { margin-bottom: 12pt; }
-.cmp-rows { list-style: none; margin: 0; padding: 0; }
-.cmp-rows li { padding: 3pt 0 3pt 14pt; border-bottom: 0.5pt solid #e2e8f0; text-indent: -10pt; }
-.cmp-rows li::before { content: "☐"; color: #94a3b8; margin-right: 6pt; }
-.cmp-ok { color: #065f46; font-weight: 600; }
-.cmp-summary { font-size: 9pt; color: #475569; }
+const CSS = `
+@page {
+  size: A4 portrait;
+  margin: 18mm 16mm 22mm;
+  @bottom-left { content: "Transitrix — compliance report"; font: 9pt "Helvetica", "Arial", sans-serif; color: #475569; }
+  @bottom-right { content: "Page " counter(page) " / " counter(pages); font: 9pt "Helvetica", "Arial", sans-serif; color: #475569; }
+}
+html, body { margin: 0; padding: 0; }
+body { font-family: "Helvetica", "Arial", sans-serif; font-size: 10pt; color: #0f172a; line-height: 1.4; }
+.cmp-header { border-bottom: 2px solid #004d67; padding-bottom: 6pt; margin-bottom: 14pt; }
+.cmp-header .cmp-eyebrow { font-size: 8.5pt; letter-spacing: 0.08em; text-transform: uppercase; color: #004d67; font-weight: 700; }
+.cmp-header h1 { font-size: 17pt; margin: 2pt 0 4pt; color: #0f172a; }
+.cmp-header .cmp-stamp { font-size: 9pt; color: #475569; }
+h2 { font-size: 12pt; margin: 16pt 0 6pt; color: #0f172a; page-break-after: avoid; }
+h2 .cmp-count { color: #64748b; font-weight: 400; font-size: 10pt; }
+p.cmp-empty { color: #64748b; }
+table { border-collapse: collapse; width: 100%; font-size: 9.5pt; margin-bottom: 10pt; }
+th, td { border: 0.5pt solid #cbd5e1; padding: 4pt 6pt; text-align: left; vertical-align: top; }
+th { background: #f1f5f9; font-weight: 700; color: #0f172a; }
+table.cmp-matrix th:first-child, table.cmp-matrix td:first-child { background: #f8fafc; font-weight: 600; }
+code, .cmp-id { font-family: "Menlo", "Consolas", monospace; font-size: 9pt; color: #475569; }
+.cmp-badge { display: inline-block; padding: 1pt 6pt; border-radius: 8pt; font-size: 8.5pt; font-weight: 700; }
+.cmp-compliant { background: #d1fae5; color: #065f46; }
+.cmp-partial { background: #fef9c3; color: #854d0e; }
+.cmp-non_compliant { background: #fee2e2; color: #991b1b; }
+.cmp-under_review { background: #e0f2fe; color: #0c4a6e; }
+.cmp-pending_owner { background: #f3e8ff; color: #6b21a8; }
+.cmp-n_a { background: #f1f5f9; color: #64748b; }
+.cmp-cell-gap { color: #94a3b8; text-align: center; }
+.cmp-req { border: 0.5pt solid #cbd5e1; border-radius: 3pt; margin-bottom: 8pt; page-break-inside: avoid; }
+.cmp-req-head { background: #f1f5f9; padding: 5pt 8pt; }
+.cmp-req-head .cmp-req-name { font-weight: 700; color: #0f172a; }
+.cmp-req-head .cmp-req-id { margin-left: 6pt; color: #475569; font-size: 9pt; font-family: "Menlo", "Consolas", monospace; }
+.cmp-sev { font-size: 8pt; text-transform: uppercase; letter-spacing: 0.06em; margin-left: 8pt; }
+.cmp-sev-high { color: #b91c1c; }
+.cmp-sev-medium { color: #b45309; }
+.cmp-sev-low { color: #2563eb; }
+.cmp-assertions { list-style: none; margin: 0; padding: 0; }
+.cmp-assertions li { padding: 4pt 8pt 4pt 16pt; border-top: 0.5pt solid #e2e8f0; }
+.cmp-assertions li .cmp-meta { color: #475569; font-size: 8.5pt; margin-left: 6pt; }
+.cmp-section { margin-bottom: 12pt; }
+.cmp-rows { list-style: none; margin: 0; padding: 0; }
+.cmp-rows li { padding: 3pt 0 3pt 14pt; border-bottom: 0.5pt solid #e2e8f0; text-indent: -10pt; }
+.cmp-rows li::before { content: "☐"; color: #94a3b8; margin-right: 6pt; }
+.cmp-ok { color: #065f46; font-weight: 600; }
+.cmp-summary { font-size: 9pt; color: #475569; }
 `;
 function htmlDoc(title, today, body) {
     const stamp = today ? `Generated ${escHtml(today)}` : '';
@@ -203,7 +205,7 @@ export function renderComplianceHtml(canon, scope, options = {}) {
 export function renderImpactMatrixHtml(matrix, options = {}) {
     const STATUS_GLYPH = {
         compliant: 'OK', partial: 'PARTIAL', non_compliant: 'FAIL',
-        under_review: 'REVIEW', n_a: 'N/A',
+        under_review: 'REVIEW', pending_owner: 'PENDING', n_a: 'N/A',
     };
     const statusClass = (s) => s ?? 'gap';
     const colHeaders = matrix.columns.map(c => `<th>${escHtml(c.label)}</th>`).join('');
@@ -223,34 +225,35 @@ export function renderImpactMatrixHtml(matrix, options = {}) {
     }).join('');
     const snapshotLine = matrix.snapshotAt ? `<span>Snapshot: ${escHtml(matrix.snapshotAt)}</span>` : '';
     const desc = matrix.description ? `<p>${escHtml(matrix.description)}</p>` : '';
-    const extraCss = `
-table { border-collapse: collapse; width: 100%; font-size: 9pt; }
-th, td { border: 1px solid #cbd5e1; padding: 3pt 5pt; text-align: center; vertical-align: middle; }
-td.cmp-row-label { text-align: left; font-size: 8.5pt; max-width: 180pt; white-space: normal; }
-.cmp-compliant { background: #d1fae5; color: #065f46; font-weight: 700; }
-.cmp-partial { background: #fef9c3; color: #854d0e; font-weight: 700; }
-.cmp-non_compliant { background: #fee2e2; color: #991b1b; font-weight: 700; }
-.cmp-under_review { background: #e0f2fe; color: #0c4a6e; }
-.cmp-gap { background: #f8fafc; color: #94a3b8; font-size: 8pt; }
-.cmp-na { background: #f1f5f9; color: #94a3b8; font-size: 8pt; }
+    const extraCss = `
+table { border-collapse: collapse; width: 100%; font-size: 9pt; }
+th, td { border: 1px solid #cbd5e1; padding: 3pt 5pt; text-align: center; vertical-align: middle; }
+td.cmp-row-label { text-align: left; font-size: 8.5pt; max-width: 180pt; white-space: normal; }
+.cmp-compliant { background: #d1fae5; color: #065f46; font-weight: 700; }
+.cmp-partial { background: #fef9c3; color: #854d0e; font-weight: 700; }
+.cmp-non_compliant { background: #fee2e2; color: #991b1b; font-weight: 700; }
+.cmp-under_review { background: #e0f2fe; color: #0c4a6e; }
+.cmp-pending_owner { background: #f3e8ff; color: #6b21a8; }
+.cmp-gap { background: #f8fafc; color: #94a3b8; font-size: 8pt; }
+.cmp-na { background: #f1f5f9; color: #94a3b8; font-size: 8pt; }
 .cmp-dl { color: #b45309; font-size: 8pt; }`;
-    return `<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="UTF-8">
-<style>
-${CSS}
-${extraCss}
-</style>
-</head>
-<body>
-<div class="cmp-header">
-  <div class="cmp-eyebrow">Compliance Impact Matrix</div>
-  <h1>${escHtml(matrix.viewName)}</h1>
-  <div class="cmp-stamp">View: <code>${escHtml(matrix.viewId)}</code> ${snapshotLine}${options.today ? ` · Generated: ${escHtml(options.today)}` : ''}</div>
-</div>
-${desc}
-<table><thead>${head}</thead><tbody>${rows}</tbody></table>
-</body>
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<style>
+${CSS}
+${extraCss}
+</style>
+</head>
+<body>
+<div class="cmp-header">
+  <div class="cmp-eyebrow">Compliance Impact Matrix</div>
+  <h1>${escHtml(matrix.viewName)}</h1>
+  <div class="cmp-stamp">View: <code>${escHtml(matrix.viewId)}</code> ${snapshotLine}${options.today ? ` · Generated: ${escHtml(options.today)}` : ''}</div>
+</div>
+${desc}
+<table><thead>${head}</thead><tbody>${rows}</tbody></table>
+</body>
 </html>`;
 }

package/dist/compliance/impact.d.ts

@@ -10,6 +10,7 @@ export interface ImpactObligationFilter {
 export interface ImpactSubjects {
     products?: string[];
     processes?: string[];
+    capabilities?: string[];
 }
 export interface ImpactStatusDisplay {
     show?: AssertionStatus[];
@@ -28,30 +29,44 @@ export interface ImpactEmptyCellLabels {
  * single subject: `{ subjectId, label: subjectId }`.
  *
  * At `grouping.columns: 'product-stage'` a column represents one (product,
- * stage) pair: `{ subjectId: productId, stageId, label: productId + ':' + stageId }`.
+ * stage) pair: `{ subjectId, stageId, label: subjectId + ':' + stageId }`.
  * A cell is populated when an ASSERTION has `subject === subjectId` and
  * `stageId ∈ assertion.realised_via` (or `realised_via` is absent, meaning
  * the assertion covers the entire subject — it then contributes to every
  * stage column for that subject).
+ *
+ * At `grouping.columns: 'product-stage-task'` a column represents one
+ * (product, stage, task) triple: `{ subjectId, stageId, taskId,
+ * label: subjectId + ':' + stageId + ':' + taskId }`. A cell is populated
+ * when an ASSERTION's `realised_via` contains the `taskId` directly, OR
+ * contains the `stageId` (stage-level claim applies to all tasks in that stage),
+ * OR `realised_via` is absent (claim covers the entire subject).
  */
 export interface ImpactColumn {
     /** Subject (product / process / capability) the column belongs to. */
     subjectId: string;
-    /** Stage ID — present only when grouping.columns is not 'product'. */
+    /** Stage ID — present at product-stage and product-stage-task grain. */
     stageId?: string;
+    /** Task ID — present only at product-stage-task grain. */
+    taskId?: string;
     /** Human-readable column header. */
     label: string;
+    /** Display name for the subject (product/process name, not the id). */
+    subjectName?: string;
 }
 /**
  * Grouping options for matrix columns.
  *
- * `columns` controls the column grain:
+ * `columns` controls the column grain (COMPIMP-004 validates the value set):
  *   - `'product'` (default) — one column per subject.
- *   - `'product-stage'`     — one column per (subject, stage) pair derived
- *     from `objectDetails` passed to `buildImpactMatrix`.
+ *   - `'product-stage'`     — one column per (subject, stage) pair; pass
+ *     `objectDetails` (from `extractObjectDetails`) into `buildImpactMatrix`.
+ *   - `'product-stage-task'` — one column per (subject, stage, task) triple;
+ *     pass `objectDetails` with stages that carry `tasks[]` (built via
+ *     `extractObjectDetails` + `extractProcessFlowTasks` + `mergeStageTaskDetails`).
  */
 export interface ImpactGrouping {
-    columns: 'object' | 'object-details';
+    columns: 'product' | 'product-stage' | 'product-stage-task';
 }
 /**
  * Named, versioned view-config — the report *definition*.
@@ -99,7 +114,7 @@ export interface ImpactViewConfig {
  * are auditable ("what I assumed").
  */
 export declare const COMPLIANCE_IMPACT_DEFAULTS: {
-    /** Accept all four active statuses + n_a in cell aggregation. */
+    /** Accept all active statuses + n_a in cell aggregation. */
     readonly status_display: {
         readonly show: AssertionStatus[];
     };
@@ -119,10 +134,11 @@ export declare const COMPLIANCE_IMPACT_DEFAULTS: {
     readonly subjects: {
         readonly products: string[];
         readonly processes: string[];
+        readonly capabilities: string[];
     };
-    /** Column grain: one column per business object (no stage decomposition). */
+    /** Column grain: one column per subject (no stage/task decomposition). */
     readonly grouping: {
-        readonly columns: "object";
+        readonly columns: "product";
     };
 };
 export type ParseImpactViewConfigResult = {
@@ -216,18 +232,26 @@ export declare function computeDeadlineStatus(deadline: string | undefined, toda
  * Build the matrix per §5.2.
  *
  * At the default `grouping.columns: 'product'` grain, one column per subject.
- * At `grouping.columns: 'product-stage'`, pass `objectDetails` to expand each
- * subject into per-stage sub-columns (typically extracted from a
- * process-blueprint document via `extractObjectDetails`).  Subjects with no
- * stage mapping fall back to a single product-grain column automatically.
  *
- * Subjects are taken from `config.subjects.products` and
- * `config.subjects.processes` (in that order).  Subjects with no binding
+ * At `grouping.columns: 'product-stage'`, pass `objectDetails` (from
+ * `extractObjectDetails` on a process-blueprint) to expand each subject into
+ * per-stage sub-columns.  Subjects with no stage mapping fall back to a single
+ * product-grain column.
+ *
+ * At `grouping.columns: 'product-stage-task'`, pass `objectDetails` where each
+ * stage carries a `tasks[]` array (combine blueprint stages and process-flow
+ * tasks via `mergeStageTaskDetails`).  Each task becomes a
+ * `(subject, stage, task)` column.  Stages with no tasks fall back to
+ * stage-grain columns.
+ *
+ * Subjects are taken from `config.subjects.products`, `config.subjects.processes`,
+ * 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;
 /**
- * Extract `ObjectDetailInput` from a raw (YAML-parsed) process-blueprint document.
+ * Extract stage-level `ObjectDetailInput` from a raw (YAML-parsed)
+ * process-blueprint document.
  *
  * Accepts both the bare document object and the wrapped form
  * (`{ process_blueprint: { id, stages: […] } }`).
@@ -236,8 +260,45 @@ export declare function buildImpactMatrix(canon: ComplianceCanon, config: Impact
  *
  * Pass the returned value into `buildImpactMatrix` as part of the
  * `objectDetails` array when `grouping.columns: 'product-stage'` is configured.
+ * For `grouping.columns: 'product-stage-task'`, combine with
+ * `extractProcessFlowTasks` via `mergeStageTaskDetails`.
  */
 export declare function extractObjectDetails(doc: unknown): ObjectDetailInput | null;
+/**
+ * Extract task-type steps from a raw (YAML-parsed) PROCESS element document.
+ *
+ * Reads `notation: process` documents with an inline `flow.steps[]` array.
+ * Filters for task-type nodes (`task`, `userTask`, `serviceTask`) — start/end
+ * events and gateways are excluded.  Returns a flat `ObjectDetailInput` where
+ * `details` are the extracted task steps in declaration order.
+ *
+ * Returns `null` when the document is not a recognisable process element or
+ * has no `id` / `flow.steps` array.
+ *
+ * Use the returned value with `mergeStageTaskDetails` to embed tasks into
+ * blueprint stages for `grouping.columns: product-stage-task`.
+ */
+export declare function extractProcessFlowTasks(doc: unknown): ObjectDetailInput | null;
+/**
+ * Combine blueprint stage details (from `extractObjectDetails`) with
+ * process-flow task details (from `extractProcessFlowTasks`) into a
+ * stage-with-tasks hierarchy for `grouping.columns: product-stage-task`.
+ *
+ * All tasks from `taskInput.details` are distributed into their parent stage
+ * by matching the `stageOwner` map: `stageId → taskId[]`.  If `stageOwner` is
+ * omitted (no stage-to-task mapping is available), all tasks are placed into
+ * every stage (`undefined` key `→` all tasks).
+ *
+ * When `taskInput` is `null` or its `objectId` does not match `stageInput`,
+ * returns `stageInput` unchanged (callers can safely chain the result into
+ * `buildImpactMatrix` — it will degrade to stage-grain columns).
+ *
+ * @param stageInput   Stage-level detail (from `extractObjectDetails`).
+ * @param taskInput    Task-level detail  (from `extractProcessFlowTasks`).
+ * @param stageOwner   Optional mapping `stageId → taskId[]`. When provided,
+ *                     only tasks listed for a stage are embedded in it.
+ */
+export declare function mergeStageTaskDetails(stageInput: ObjectDetailInput, taskInput: ObjectDetailInput | null, stageOwner?: Record<string, string[]>): ObjectDetailInput;
 /**
  * Render the matrix as a GitHub-flavoured markdown table.
  *