@transitrix/diagrams 1.13.3 → 1.14.0

package/src/products/validate.ts

@@ -1,3 +1,4 @@
+import { schemaFinding } from '../schema-finding.js';
 import type { ProductsCatalogueFile, ProductType, ProductStatus } from './types.js';
 import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
 
@@ -11,8 +12,8 @@ export function validateProductsCatalogue(input: unknown): ValidationResult {
   const errors: ValidationError[] = [];
   const warnings: ValidationWarning[] = [];
 
-  if (!input || typeof input !== 'object') {
-    return { valid: false, errors: [{ code: 'PROD-001', message: 'Input must be an object' }], warnings };
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    return { valid: false, errors: [schemaFinding('products inline', '$', 'mapping', input)], warnings };
   }
 
   const raw = input as Record<string, unknown>;
@@ -26,84 +27,89 @@ export function validateProductsCatalogue(input: unknown): ValidationResult {
 
   if (errors.length > 0) return { valid: false, errors, warnings };
 
+  if (('view_config' in raw || 'view' in raw) && !('products_catalogue' in raw)) {
+    return { valid: true, errors, warnings: [{ code: 'NOTATION-SKIP-001',
+      message: 'products projection form is unsupported and remains unvalidated.' }] };
+  }
+
   // PROD-002: catalogue header fields
   const cat = (raw['products_catalogue'] ?? {}) as Record<string, unknown>;
-  if (!raw['products_catalogue'] || typeof raw['products_catalogue'] !== 'object') {
-    errors.push({ code: 'PROD-002', message: 'Missing required field: products_catalogue' });
+  if (!raw['products_catalogue'] || typeof raw['products_catalogue'] !== 'object' || Array.isArray(raw['products_catalogue'])) {
+    errors.push(schemaFinding('products inline', 'products_catalogue', 'mapping', raw['products_catalogue']));
     return { valid: false, errors, warnings };
   }
   if (!cat['id'] || typeof cat['id'] !== 'string' || !(cat['id'] as string).trim()) {
-    errors.push({ code: 'PROD-002', message: 'products_catalogue.id is required' });
+    errors.push(schemaFinding('products inline', 'products_catalogue.id', 'nonempty string', cat['id']));
   }
   if (!cat['name'] || typeof cat['name'] !== 'string' || !(cat['name'] as string).trim()) {
-    errors.push({ code: 'PROD-002', message: 'products_catalogue.name is required' });
+    errors.push(schemaFinding('products inline', 'products_catalogue.name', 'nonempty string', cat['name']));
   }
   if (!cat['updated_at'] || typeof cat['updated_at'] !== 'string') {
-    errors.push({ code: 'PROD-002', message: 'products_catalogue.updated_at is required' });
+    errors.push(schemaFinding('products inline', 'products_catalogue.updated_at', 'YYYY-MM-DD string', cat['updated_at']));
   }
 
   if (errors.length > 0) return { valid: false, errors, warnings };
 
-  // PROD-007: updated_at format
+  // Schema: updated_at format
   if (!DATE_RE.test(cat['updated_at'] as string)) {
-    errors.push({ code: 'PROD-007', message: `products_catalogue.updated_at must be YYYY-MM-DD, got "${cat['updated_at']}"` });
+    errors.push(schemaFinding('products inline', 'products_catalogue.updated_at', 'YYYY-MM-DD string', cat['updated_at']));
   }
 
   const products = cat['products'];
   if (!Array.isArray(products)) {
-    errors.push({ code: 'PROD-002', message: 'products_catalogue.products must be an array' });
+    errors.push(schemaFinding('products inline', 'products_catalogue.products', 'array', cat['products']));
     return { valid: false, errors, warnings };
   }
 
-  // PROD-008: unique product_id
+  // Schema: unique product_id
   const seenIds = new Set<string>();
 
   for (let i = 0; i < products.length; i++) {
     const rawProduct = products[i];
     const idx = `products[${i}]`;
 
-    if (!rawProduct || typeof rawProduct !== 'object') {
-      errors.push({ code: 'PROD-003', message: `${idx} must be an object` });
+    if (!rawProduct || typeof rawProduct !== 'object' || Array.isArray(rawProduct)) {
+      errors.push(schemaFinding('products inline', `${idx}`, 'mapping', rawProduct));
       continue;
     }
     const p = rawProduct as Record<string, unknown>;
 
-    // PROD-003: required per-product fields
+    // Schema: required per-product fields
     if (!p['product_id'] || typeof p['product_id'] !== 'string' || !(p['product_id'] as string).trim()) {
-      errors.push({ code: 'PROD-003', message: `${idx}: product_id is required` });
+      errors.push(schemaFinding('products inline', `${idx}.product_id`, 'nonempty string', p['product_id']));
     } else {
       const pid = p['product_id'] as string;
       if (seenIds.has(pid)) {
-        errors.push({ code: 'PROD-008', message: `Duplicate product_id: "${pid}"` });
+        errors.push(schemaFinding('products inline', `${idx}.product_id`, 'unique identifier', p['product_id']));
       }
       seenIds.add(pid);
     }
 
     if (!p['name'] || typeof p['name'] !== 'string' || !(p['name'] as string).trim()) {
-      errors.push({ code: 'PROD-003', message: `${idx}: name is required` });
+      errors.push(schemaFinding('products inline', `${idx}.name`, 'nonempty string', p['name']));
     }
     if (!p['type']) {
-      errors.push({ code: 'PROD-003', message: `${idx}: type is required` });
+      errors.push(schemaFinding('products inline', `${idx}.type`, `one of ${[...VALID_TYPES].join(", ")}`, p['type']));
     }
     if (!p['status']) {
-      errors.push({ code: 'PROD-003', message: `${idx}: status is required` });
+      errors.push(schemaFinding('products inline', `${idx}.status`, `one of ${[...VALID_STATUSES].join(", ")}`, p['status']));
     }
 
-    // PROD-004: type enum
+    // Schema: type enum
     if (p['type'] && !VALID_TYPES.has(p['type'] as ProductType)) {
-      errors.push({ code: 'PROD-004', message: `${idx}: type "${p['type']}" must be one of: digital_product, service, platform, bundle` });
+      errors.push(schemaFinding('products inline', `${idx}.type`, `one of ${[...VALID_TYPES].join(", ")}`, p['type']));
     }
 
-    // PROD-005: status enum
+    // Schema: status enum
     if (p['status'] && !VALID_STATUSES.has(p['status'] as ProductStatus)) {
-      errors.push({ code: 'PROD-005', message: `${idx}: status "${p['status']}" must be one of: Draft, Active, Deprecated` });
+      errors.push(schemaFinding('products inline', `${idx}.status`, `one of ${[...VALID_STATUSES].join(", ")}`, p['status']));
     }
 
-    // PROD-006: maturity range
+    // Schema: maturity range
     if (p['maturity'] !== undefined) {
       const m = p['maturity'];
       if (typeof m !== 'number' || !Number.isInteger(m) || m < 1 || m > 5) {
-        errors.push({ code: 'PROD-006', message: `${idx}: maturity must be an integer 1–5, got "${m}"` });
+        errors.push(schemaFinding('products inline', `${idx}.maturity`, 'integer in 1–5', p['maturity']));
       }
     }
   }

package/src/repo-validate/check-strategy-chain.ts

@@ -1,3 +1,4 @@
+import { validateActionFields } from '../activities/action-fields.js';
 // Strategy-chain semantic checks — the error-severity subset of DSM's Go
 // `Validate*` functions (`api02/internal/importer/{goals,activities,fgca}.go`
 // in transitrix-dsm), ported onto the standalone-element repo shape
@@ -5,9 +6,8 @@
 // can drop those Go functions without regressing the checks they enforce
 // today.
 //
-// Rule codes are DSM's own (`GOALS-010`, `ACT-006`..`009`, `FGCA-008`..`011`)
-// — not invented here — so DSM can map a CLI finding straight back onto its
-// import-log taxonomy (`RepoFinding.ruleId`).
+// ACTION identities follow the versioned element contract; schedule ACT codes
+// remain separate. Stored historical findings must retain their original codes.
 //
 // Scope — DSM's full rule set is now ported except GOALS-008 (see below).
 // `RepoFinding` grew a `severity` field precisely so DSM's warn-severity
@@ -43,20 +43,20 @@
 //
 // Ported (error-severity, blocking):
 //   GOALS-010 — GOAL `parent` chain contains a cycle.
-//   ACT-006   — ACTION `predecessors` graph contains a cycle.
-//   ACT-007   — ACTION lists itself as its own predecessor.
-//   ACT-008   — ACTION `start_date`/`end_date` unparseable, or end before start.
-//   ACT-009   — ACTION numeric field (`duration`/`duration_days`, `labor_cost`,
+//   ACTION-008   — ACTION `predecessors` graph contains a cycle.
+//   ACTION-009   — ACTION lists itself as its own predecessor.
+//   ACTION-010   — ACTION `start_date`/`end_date` unparseable, or end before start.
+//   ACTION-011   — ACTION numeric field (`duration`/`duration_days`, `labor_cost`,
 //               `resources_cost`, `effort`, `score`) is negative.
-//   FGCA-008  — GOAL.factors references an undefined DRIVER.
-//   FGCA-009  — CHANGE.goals references an undefined GOAL.
-//   FGCA-010  — ACTION.delivers_changes references an undefined CHANGE.
-//   FGCA-011  — ACTION.goals references an undefined GOAL.
+//   DGCA-REPO-008  — GOAL.factors references an undefined DRIVER.
+//   DGCA-REPO-009  — CHANGE.goals references an undefined GOAL.
+//   DGCA-REPO-010  — ACTION.delivers_changes references an undefined CHANGE.
+//   DGCA-REPO-011  — ACTION.goals references an undefined GOAL.
 //
 // Ported (warning-severity, advisory):
 //   GOALS-009 — GOAL.parent is set but does not resolve to a known GOAL (orphan).
 //   GOALS-011 — GOAL has no `parent` and `level` >= 1 (backlog).
-//   ACT-005   — ACTION.predecessors entry or ACTION.parent does not resolve
+//   ACTION-007   — ACTION.predecessors entry or ACTION.parent does not resolve
 //               to a known ACTION (orphan).
 //   FGCA-012  — a DRIVER is not referenced by any GOAL.factors (unreferenced).
 //   FGCA-013  — a GOAL is not referenced by any CHANGE.goals or ACTION.goals
@@ -244,34 +244,34 @@ function checkGoalParentResolution(goals: ChainElement[], findings: RepoFinding[
   }
 }
 
-/** ACT-007 — an ACTION cannot list itself as its own predecessor. */
+/** ACTION-009 — an ACTION cannot list itself as its own predecessor. */
 function checkActionSelfPredecessor(actions: ChainElement[], findings: RepoFinding[]): void {
   for (const a of actions) {
     if (readStringArray(a.data, 'predecessors').includes(a.id)) {
       findings.push({
         scope: PScope,
         id: a.id,
-        ruleId: 'ACT-007',
-        message: `ACT-007: action '${a.id}' lists itself as a predecessor.`,
+        ruleId: 'ACTION-009',
+        message: `ACTION-009: action '${a.id}' lists itself as a predecessor.`,
       });
     }
   }
 }
 
-/** ACT-006 — the ACTION `predecessors` graph must not contain a cycle. */
+/** ACTION-008 — the ACTION `predecessors` graph must not contain a cycle. */
 function checkActionPredecessorCycle(actions: ChainElement[], findings: RepoFinding[]): void {
   const cyc = findPredecessorCycle(actions);
   if (cyc) {
     findings.push({
       scope: PScope,
       id: cyc,
-      ruleId: 'ACT-006',
-      message: `ACT-006: predecessor graph contains a cycle involving action '${cyc}'.`,
+      ruleId: 'ACTION-008',
+      message: `ACTION-008: predecessor graph contains a cycle involving action '${cyc}'.`,
     });
   }
 }
 
-/** ACT-005 — an ACTION `predecessors` entry or `parent` that does not resolve
+/** ACTION-007 — an ACTION `predecessors` entry or `parent` that does not resolve
  *  to a known ACTION is an orphan reference (warning — advisory in DSM, same
  *  as the goal-parent orphan checks above). */
 function checkActionOrphanReferences(actions: ChainElement[], findings: RepoFinding[]): void {
@@ -282,9 +282,9 @@ function checkActionOrphanReferences(actions: ChainElement[], findings: RepoFind
         findings.push({
           scope: PScope,
           id: a.id,
-          ruleId: 'ACT-005',
+          ruleId: 'ACTION-007',
           severity: 'warning',
-          message: `ACT-005: action '${a.id}' predecessor '${p}' does not resolve to a known action.`,
+          message: `ACTION-007: action '${a.id}' predecessor '${p}' does not resolve to a known action.`,
         });
       }
     }
@@ -293,9 +293,9 @@ function checkActionOrphanReferences(actions: ChainElement[], findings: RepoFind
       findings.push({
         scope: PScope,
         id: a.id,
-        ruleId: 'ACT-005',
+        ruleId: 'ACTION-007',
         severity: 'warning',
-        message: `ACT-005: action '${a.id}' parent '${parent}' does not resolve to a known action.`,
+        message: `ACTION-007: action '${a.id}' parent '${parent}' does not resolve to a known action.`,
       });
     }
   }
@@ -316,34 +316,34 @@ function parseIsoDate(value: string): Date | undefined {
   return dt;
 }
 
-/** ACT-008 — `start_date`/`end_date` must be valid ISO dates, and `end_date`
+/** ACTION-010 — `start_date`/`end_date` must be valid ISO dates, and `end_date`
  *  must not be before `start_date` (equal is allowed — e.g. a milestone). */
 function checkActionDates(actions: ChainElement[], findings: RepoFinding[]): void {
   for (const a of actions) {
-    const startRaw = readString(a.data, 'start_date');
-    const endRaw = readString(a.data, 'end_date');
+    const startRaw = a.data.start_date == null ? undefined : a.data.start_date;
+    const endRaw = a.data.end_date == null ? undefined : a.data.end_date;
     let start: Date | undefined;
     let end: Date | undefined;
 
     if (startRaw !== undefined) {
-      start = parseIsoDate(startRaw);
+      start = typeof startRaw === 'string' ? parseIsoDate(startRaw) : undefined;
       if (!start) {
         findings.push({
           scope: PScope,
           id: a.id,
-          ruleId: 'ACT-008',
-          message: `ACT-008: action '${a.id}' start_date '${startRaw}' is not a valid YYYY-MM-DD date.`,
+          ruleId: 'ACTION-010',
+          message: `ACTION-010: action '${a.id}' start_date '${startRaw}' is not a valid YYYY-MM-DD date.`,
         });
       }
     }
     if (endRaw !== undefined) {
-      end = parseIsoDate(endRaw);
+      end = typeof endRaw === 'string' ? parseIsoDate(endRaw) : undefined;
       if (!end) {
         findings.push({
           scope: PScope,
           id: a.id,
-          ruleId: 'ACT-008',
-          message: `ACT-008: action '${a.id}' end_date '${endRaw}' is not a valid YYYY-MM-DD date.`,
+          ruleId: 'ACTION-010',
+          message: `ACTION-010: action '${a.id}' end_date '${endRaw}' is not a valid YYYY-MM-DD date.`,
         });
       }
     }
@@ -351,36 +351,24 @@ function checkActionDates(actions: ChainElement[], findings: RepoFinding[]): voi
       findings.push({
         scope: PScope,
         id: a.id,
-        ruleId: 'ACT-008',
-        message: `ACT-008: action '${a.id}' end_date '${endRaw}' is before start_date '${startRaw}'.`,
+        ruleId: 'ACTION-010',
+        message: `ACTION-010: action '${a.id}' end_date '${endRaw}' is before start_date '${startRaw}'.`,
       });
     }
   }
 }
 
-/** ACT-009 — numeric scheduling/cost fields must not be negative. `duration`
- *  and `duration_days` are both checked — the canonical field is `duration`
- *  (elements/24-action.md §2), but `duration_days` is an accepted alias in
- *  this codebase's document-form validator (activities/validate.ts) and is
- *  the field acme_corp's own ACTION elements actually use. */
-function checkActionNegativeNumbers(actions: ChainElement[], findings: RepoFinding[]): void {
-  const fields = ['duration', 'duration_days', 'labor_cost', 'resources_cost', 'effort', 'score'] as const;
+/** Shared ACTION type and versioned numeric checks. */
+function checkActionFields(actions: ChainElement[], findings: RepoFinding[], version?: string): void {
   for (const a of actions) {
-    for (const field of fields) {
-      const v = readFiniteNumber(a.data, field);
-      if (v !== undefined && v < 0) {
-        findings.push({
-          scope: PScope,
-          id: a.id,
-          ruleId: 'ACT-009',
-          message: `ACT-009: action '${a.id}' field '${field}' is negative (${v}).`,
-        });
-      }
+    for (const error of validateActionFields(a.data, version)) {
+      findings.push({ scope: PScope, id: a.id, ruleId: error.code,
+        message: `${a.doc.path}: canonical action '${a.id}' ${error.message}` });
     }
   }
 }
 
-/** FGCA-008..011 — inline strategy-chain cross-references must resolve within
+/** DGCA-REPO-008..011 — inline strategy-chain cross-references must resolve within
  *  the repo: GOAL.factors -> DRIVER, CHANGE.goals -> GOAL, ACTION.goals ->
  *  GOAL, ACTION.delivers_changes -> CHANGE (ELEMENT_PRIMITIVES.md §7.1-§7.4). */
 function checkStrategyChainReferences(
@@ -400,8 +388,8 @@ function checkStrategyChainReferences(
         findings.push({
           scope: PScope,
           id: g.id,
-          ruleId: 'FGCA-008',
-          message: `FGCA-008: goal '${g.id}' references undefined driver '${f}'.`,
+          ruleId: 'DGCA-REPO-008',
+          message: `DGCA-REPO-008: goal '${g.id}' references undefined driver '${f}'.`,
         });
       }
     }
@@ -412,8 +400,8 @@ function checkStrategyChainReferences(
         findings.push({
           scope: PScope,
           id: c.id,
-          ruleId: 'FGCA-009',
-          message: `FGCA-009: change '${c.id}' references undefined goal '${g}'.`,
+          ruleId: 'DGCA-REPO-009',
+          message: `DGCA-REPO-009: change '${c.id}' references undefined goal '${g}'.`,
         });
       }
     }
@@ -424,8 +412,8 @@ function checkStrategyChainReferences(
         findings.push({
           scope: PScope,
           id: a.id,
-          ruleId: 'FGCA-010',
-          message: `FGCA-010: action '${a.id}' references undefined change '${c}'.`,
+          ruleId: 'DGCA-REPO-010',
+          message: `DGCA-REPO-010: action '${a.id}' references undefined change '${c}'.`,
         });
       }
     }
@@ -434,8 +422,8 @@ function checkStrategyChainReferences(
         findings.push({
           scope: PScope,
           id: a.id,
-          ruleId: 'FGCA-011',
-          message: `FGCA-011: action '${a.id}' references undefined goal '${g}'.`,
+          ruleId: 'DGCA-REPO-011',
+          message: `DGCA-REPO-011: action '${a.id}' references undefined goal '${g}'.`,
         });
       }
     }
@@ -505,8 +493,8 @@ function checkStrategyChainOrphans(
 }
 
 /**
- * Run the strategy-chain semantic checks (GOALS-009..011, ACT-005..009,
- * FGCA-008..014 except GOALS-008 — see the module header) over the loaded
+ * Run the strategy-chain semantic checks (GOALS-009..011, ACTION-007..011,
+ * DGCA-REPO-008..014 except GOALS-008 — see the module header) over the loaded
  * element set and append findings. Called from `validateRepoModel` after the
  * structural phases. Pure, deterministic order.
  */
@@ -522,7 +510,24 @@ export function checkStrategyChainSemantics(input: RepoModelInput, findings: Rep
   checkActionPredecessorCycle(actions, findings);
   checkActionOrphanReferences(actions, findings);
   checkActionDates(actions, findings);
-  checkActionNegativeNumbers(actions, findings);
+  checkActionFields(actions, findings, input.methodologyVersion);
   checkStrategyChainReferences(goals, actions, drivers, changes, findings);
-  checkStrategyChainOrphans(goals, actions, drivers, changes, findings);
+  if (!usesCoverageObservations(input)) checkStrategyChainOrphans(goals, actions, drivers, changes, findings);
+}
+
+
+function usesCoverageObservations(input: RepoModelInput): boolean {
+  return /^\d+\./.test(input.methodologyVersion ?? '') && Number(input.methodologyVersion!.split('.')[0]) >= 5;
+}
+
+/** Removed FGCA orphan rules become visible coverage observations, not new aliases. */
+export function collectStrategyCoverageObservations(input: RepoModelInput): Array<{id: string; kind: 'unreferenced'; message: string}> {
+  if (!usesCoverageObservations(input)) return [];
+  const findings: RepoFinding[] = [];
+  checkStrategyChainOrphans(
+    collectByNotation(input.elements, isGoalNotation),
+    collectByNotation(input.elements, isActionNotation),
+    collectByNotation(input.elements, isDriverNotation),
+    collectByNotation(input.elements, isChangeNotation), findings);
+  return findings.map(f => ({ id: f.id, kind: 'unreferenced', message: f.message.replace(/^FGCA-01[234]: /, '') }));
 }

package/src/repo-validate/types.ts

@@ -74,6 +74,8 @@ export interface RepoDoc {
  *  canon zone exactly as `lint.py` partitions them (`canon/elements/**` vs
  *  `canon/relations/**`). */
 export interface RepoModelInput {
+  /** Catalogue manifest version; document spec_version never selects compatibility. */
+  methodologyVersion?: string;
   /** Documents found under `canon/elements/**`. */
   elements: RepoDoc[];
   /** Documents found under `canon/relations/**`. */

package/src/repo-validate/validate-repo.ts

@@ -135,6 +135,7 @@ function checkReferentialIntegrity(input: RepoModelInput, findings: RepoFinding[
       findings.push({
         scope: PScope,
         id: relId,
+        ruleId: 'REL-002',
         message: `Referential integrity: relation '${relId || doc.path}' endpoint '${fromId}' (from) does not resolve to a known element.`,
       });
     }
@@ -142,6 +143,7 @@ function checkReferentialIntegrity(input: RepoModelInput, findings: RepoFinding[
       findings.push({
         scope: PScope,
         id: relId,
+        ruleId: 'REL-002',
         message: `Referential integrity: relation '${relId || doc.path}' endpoint '${toId}' (to) does not resolve to a known element.`,
       });
     }

package/src/risk/index.ts

@@ -1,4 +1,4 @@
-export type { Risk, RiskLevel } from './types.js';
+export type { Risk, RiskLevel, RiskScale } from './types.js';
 export { RISK_LEVELS } from './types.js';
 export { validateRisk } from './validate.js';
 export type { RiskValidateOptions } from './validate.js';

package/src/risk/types.ts

@@ -4,7 +4,14 @@
 import type { GateChecks } from '../requirement/types.js';
 
 /** Likelihood / impact / residual severity vocabulary (§7.26). */
-export type RiskLevel = 'low' | 'medium' | 'high';
+export type RiskLevel = 'low' | 'medium' | 'high' | number;
+
+export interface RiskScale {
+  id: string;
+  min: number;
+  max: number;
+  direction: 'higher' | 'lower';
+}
 
 export const RISK_LEVELS: readonly RiskLevel[] = ['low', 'medium', 'high'];
 
@@ -12,6 +19,7 @@ export interface Risk {
   notation: 'risk';
   id: string;
   name: string;
+  risk_scale?: RiskScale;
   likelihood: RiskLevel;
   impact: RiskLevel;
   residual: RiskLevel;

package/src/risk/validate.ts

@@ -3,7 +3,7 @@
 // Codes:
 //   RISK-001 — shape / id grammar / required envelope + per-type fields
 //              (likelihood, impact, residual, owner_role, threatens).
-//   RISK-002 — likelihood / impact / residual outside {low, medium, high}.
+//   RISK-002 — invalid qualitative/numeric degree or adopter scale.
 //   RISK-003 — threatens is empty, or an entry does not resolve to an
 //              admitted element in canon (no TYPE restriction — any core
 //              element may be threatened).
@@ -62,13 +62,27 @@ export function validateRisk(input: unknown, options: RiskValidateOptions = {}):
     errors.push({ code: 'RISK-001', message: 'valid_to is required (an ISO date string or null).', path: 'valid_to' });
   }
 
-  // likelihood / impact / residual — required (RISK-001) + enum (RISK-002).
-  for (const f of ['likelihood', 'impact', 'residual'] as const) {
+  // Authored numeric degrees use one explicitly declared adopter scale.
+  const fields = ['likelihood', 'impact', 'residual'] as const;
+  const scale = r.risk_scale as Record<string, unknown> | undefined;
+  const finite = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v);
+  const validScale = scale !== null && typeof scale === 'object' && !Array.isArray(scale)
+    && typeof scale.id === 'string' && scale.id.trim().length > 0
+    && finite(scale.min) && finite(scale.max) && scale.min < scale.max
+    && (scale.direction === 'higher' || scale.direction === 'lower');
+  if ((scale !== undefined || fields.some(f => typeof r[f] === 'number')) && !validScale) {
+    errors.push({ code: 'RISK-002', message: 'risk_scale requires id, finite min < max, and direction higher or lower.', path: 'risk_scale' });
+  }
+  for (const f of fields) {
     const v = r[f];
     if (v === undefined || v === null || v === '') {
       errors.push({ code: 'RISK-001', message: `${f} is required.`, path: f });
-    } else if (!(RISK_LEVELS as readonly string[]).includes(v as string)) {
-      errors.push({ code: 'RISK-002', message: `${f} "${String(v)}" must be one of ${RISK_LEVELS.join(', ')}.`, path: f });
+    } else if (typeof v === 'number') {
+      if (!finite(v) || (validScale && (v < (scale!.min as number) || v > (scale!.max as number)))) {
+        errors.push({ code: 'RISK-002', message: `${f} must be finite and within risk_scale bounds.`, path: f });
+      }
+    } else if (!(RISK_LEVELS as readonly unknown[]).includes(v)) {
+      errors.push({ code: 'RISK-002', message: `${f} must be low, medium, high, or a number with risk_scale.`, path: f });
     }
   }
 

package/src/scenarios/validate.ts

@@ -38,6 +38,11 @@ export function validateScenario(input: unknown): ValidationResult {
   }
   if (errors.length > 0) return { valid: false, errors, warnings };
 
+  if (('view_config' in raw || 'view' in raw || 'scenarios' in raw) && !('scenario' in raw)) {
+    return { valid: true, errors, warnings: [{ code: 'NOTATION-SKIP-001',
+      message: 'scenarios projection or scenario-set form is unsupported and remains unvalidated.' }] };
+  }
+
   const scn = raw['scenario'];
   if (!scn || typeof scn !== 'object') {
     errors.push({ code: 'SCN-002', message: 'Missing required field: scenario' });

package/src/schema-finding.ts

@@ -0,0 +1,8 @@
+import type { ValidationError } from './validation-types.js';
+
+/** Shared schema identity; callers supply the owning form and exact field. */
+export function schemaFinding(form: string, path: string, expected: string, actual: unknown): ValidationError {
+  const type = actual === null ? 'null' : Array.isArray(actual) ? 'array' : typeof actual;
+  return { code: 'SCHEMA_INVALID', path,
+    message: `${form} field '${path}': expected ${expected}; actual ${type} (${String(actual)}).` };
+}

package/src/webview/entry.ts

@@ -275,10 +275,14 @@ function dispatchValidate(kind: NotationKind, doc: unknown): RenderResult {
       return renderFromValidation('scenarios', validateScenario(doc), () =>
         renderScenarioHtml((doc as ScenarioFile).scenario),
       );
-    case 'capability-map':
-      return renderFromValidation('capability-map', validateCapabilityMap(doc), () =>
+    case 'capability-map': {
+      const validation = validateCapabilityMap(doc);
+      const unresolved = validation.warnings.find(w => w.code === 'NOTATION-SKIP-001');
+      if (validation.valid && unresolved) return errorResult('capability-map', unresolved.code, unresolved.message);
+      return renderFromValidation('capability-map', validation, () =>
         renderCapabilityMapHtml((doc as CapabilityMapFile).capability_map),
       );
+    }
     default:
       return errorResult(
         kind,

package/src/webview/render-goals.ts

@@ -56,7 +56,8 @@ export function renderGoalsSvg(tree: GoalTree, options: RenderGoalsOptions = {})
     ? `<text class="text-header" x="${PAD}" y="${PAD - 6}">${escXml(`Goal tree — ${treeName}`)}</text>`
     : '';
 
-  return renderGoalsLayoutSvg(layout, { curvature, entryCurvature, edgeStyle, title, embedCssTheme: 'transitrix' });
+  // Reserve a separate header row; the theme centers text on its y coordinate.
+  return renderGoalsLayoutSvg(layout, { curvature, entryCurvature, edgeStyle, title, topInset: title ? PAD : 0, embedCssTheme: 'transitrix' });
 }
 
 export interface RenderGoalsLayoutOptions {

package/src/webview/styles.css

@@ -70,6 +70,14 @@ body {
   margin-left: 6px;
 }
 
+/* The bundled SVG renderer uses its light palette independently of IDE chrome.
+ * Give transparent SVG titles and edges a matching canvas. */
+.tx-svg-host {
+  background: #ffffff;
+  color: #0d2b35;
+  min-height: calc(100vh - 24px);
+}
+
 .tx-svg-host svg {
   max-width: 100%;
   height: auto;