@transitrix/diagrams 1.8.20 → 1.9.18

package/src/fgca/parse-canonical.ts

@@ -17,7 +17,7 @@
  * historically but the layout code only uses IDs as opaque keys, so
  * string IDs work fine.
  *
- * Strategy hub #63: this lives at the input boundary so the library's
+ * This lives at the input boundary so the library's
  * internal types (currently using DSM-API form — numeric IDs and
  * singular cross-refs) can stay where they are. A follow-up task can
  * unify the internal types with the canonical form across all sister
@@ -354,7 +354,7 @@ export interface CanonicalFGAResult extends ValidationResult {
  * FGA-001..011). The resulting internal `FGCADoc` carries `activity.goal_id`,
  * which is exactly what the renderer needs to draw goal → activity edges —
  * the field whose absence produced the "FGA nodes render, no edges" bug
- * (transitrix/methodology#65 / vkgeorgia/strategy#65).
+ * (transitrix/methodology#65).
  *
  * Lives beside `parseCanonicalFGCA` (rather than inline in the extension) so
  * the canonical FGA path is unit-testable and the library owns the single

package/src/fgca/preview-layout.ts

@@ -49,7 +49,7 @@ export interface FGCAPreviewLayoutOptions {
   colGap?: number;
   /** Vertical gap (px) between stacked nodes within a column. Default matches the historical hardcoded value. */
   rowGap?: number;
-  /** Trim to a level cap or a single root goal (vkgeorgia/strategy#77). Defaults to 'all'. */
+  /** Trim to a level cap or a single root goal. Defaults to 'all'. */
   scope?: Scope;
   /** Entity node width (px). Default {@link FGCA_NODE_W}. */
   nodeWidth?: number;

package/src/goals/layout.ts

@@ -8,7 +8,7 @@ const DEFAULT_RANK_SEP = 80;
 const DEFAULT_NODE_SEP = 40;
 
 /**
- * Trims a flat goal list to a scope (vkgeorgia/strategy#77).
+ * Trims a flat goal list to a scope.
  *   - 'level' → goals with `level <= maxLevel`.
  *   - 'root'  → the root goal (matched by string id) plus all its descendants
  *               via `parent_id`; an empty list when the root is absent.

package/src/goals/parse-canonical.ts

@@ -15,7 +15,7 @@
  * mapped to internal sequential numbers, `parent: GOAL-X` becomes
  * `parent_id: <numeric>`, `parent_id: 0` denotes a root.
  *
- * Strategy hub #63: this lives at the input boundary so the library's
+ * This lives at the input boundary so the library's
  * internal types (numeric IDs) stay where they are. Convergence on
  * canonical typed-string IDs across all sister modules is a follow-up
  * task.

package/src/goals/types.ts

@@ -60,7 +60,7 @@ export interface LayoutOptions {
   nodeSep?: number;
   hideCollapsed?: number[];
   viewDepth?: number | null;
-  /** Trim the tree to a level cap or a subtree root (vkgeorgia/strategy#77). Defaults to 'all'. */
+  /** Trim the tree to a level cap or a subtree root. Defaults to 'all'. */
   scope?: Scope;
 }
 

package/src/goals/validate.ts

@@ -21,7 +21,7 @@ export function validateGoalTree(input: unknown): ValidationResult {
   const tree = raw as unknown as GoalTree;
 
   // GOALS-013 — goal_types[].level values must be contiguous starting from 0.
-  // Per the N+1 rule (decision in vkgeorgia/strategy#66), the level set must
+  // Per the N+1 rule, the level set must
   // be exactly {0, 1, …, N}; a gap breaks the parent→child level invariant
   // and means GOALS-012 cannot be enforced consistently.
   const levels = tree.goal_types
@@ -96,7 +96,7 @@ export function validateGoalTree(input: unknown): ValidationResult {
       continue;
     }
     // GOALS-012 — parent must be exactly one level above the child (N+1
-    // hierarchy, decision in vkgeorgia/strategy#66). Only enforced when the
+    // hierarchy). Only enforced when the
     // parent is resolvable; a missing parent is covered by BROKEN_PARENT_REF.
     if (g.parent_id !== 0) {
       const parentLevel = levelById.get(g.parent_id);

package/src/link-suspicion.ts

@@ -0,0 +1,181 @@
+// Link suspicion — methodology CONTRACT.md §16, reference implementation
+// `scripts/check-link-suspicion.mjs`. Pure: content-identity normalisation
+// (§16.1) and the suspicion verdict (§16.2 / §16.3's mechanical hatch) over
+// already-fetched file text. Git plumbing (finding the anchor commit,
+// reading a file at a ref) and the repo walk are IO and live in the CLI
+// (`src/repo-validate.ts`), same split as the rest of this package.
+//
+// Nothing here is stored: a caller re-derives the verdict on every check;
+// no file ever carries a `suspicious: true` flag (§16.2).
+
+// The administrative envelope (§16.1) — field names CONTRACT.md already
+// defines by name (§6 / §6.1 / §6.2 / §6.3 when present / §7). One list,
+// defined once; a spec revision that adds an envelope field extends this
+// list in the same revision rather than inventing a second mechanism.
+export const ENVELOPE_FIELDS = [
+  'zone', 'admitted_at', 'admitted_by', 'gate_checks', 'derived_from',
+  'admission_state', 'proposed_at', 'proposed_by', 'owner_to_confirm',
+  'rejected_at', 'rejected_by', 'rejection_reason',
+  'reviewer_authority',
+  'agreement', 'agreed_by', 'agreed_at',
+  'valid_from', 'valid_to',
+];
+
+function stripComment(line: string): string {
+  let inQuotes = false;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (ch === '"') inQuotes = !inQuotes;
+    else if (ch === '#' && !inQuotes) return line.slice(0, i);
+  }
+  return line;
+}
+
+/** Every non-blank, non-comment line of the file, except those belonging to
+ *  an `ENVELOPE_FIELDS` block (the key line and its more-indented
+ *  continuation lines), whitespace-normalised and sorted —
+ *  order-independent, formatting-independent, comment-independent. Not a
+ *  general YAML parser — a flat, line-oriented pass over the already-known
+ *  envelope field names, the same posture the methodology reference script
+ *  takes (its own header comment cites `baseline-manifest.mjs` /
+ *  `check-agreement.mjs` for precedent). */
+export function statementLines(text: string): string[] {
+  const kept: string[] = [];
+  let skipIndent: number | null = null;
+  for (const raw of text.split('\n')) {
+    const stripped = stripComment(raw).replace(/\s+$/, '');
+    if (!stripped.trim()) continue;
+    const indent = stripped.match(/^ */)?.[0].length ?? 0;
+    if (skipIndent !== null) {
+      if (indent > skipIndent) continue;
+      skipIndent = null;
+    }
+    const keyMatch = stripped.match(/^(\s*)([A-Za-z_][A-Za-z0-9_]*):/);
+    if (keyMatch && keyMatch[1].length === 0 && ENVELOPE_FIELDS.includes(keyMatch[2])) {
+      skipIndent = indent;
+      continue;
+    }
+    kept.push(stripped.trim().replace(/\s+/g, ' '));
+  }
+  return kept.sort();
+}
+
+function sameLines(a: string[], b: string[]): boolean {
+  return a.length === b.length && a.every((line, i) => line === b[i]);
+}
+
+export interface LineEdit {
+  from: string;
+  to: string;
+}
+
+/** A parsed `migrations/<slug>/TRANSFORM.yaml` manifest (§16.3). */
+export interface MigrationManifest {
+  slug: string;
+  mechanical: boolean;
+  appliesTo: string[];
+  lineEdits: LineEdit[];
+}
+
+function unquote(s: string): string {
+  const m = s.match(/^"(.*)"$/);
+  return m ? m[1] : s;
+}
+
+function normalizeEditLine(s: string): string {
+  return unquote(s.trim()).trim().replace(/\s+/g, ' ');
+}
+
+/** Minimal parse of the fixed `TRANSFORM.yaml` shape — `mechanical: true`,
+ *  `applies_to: [exact relative paths]`, `line_edits: [{from, to}]`. Not a
+ *  general YAML parser, same posture as {@link statementLines}. */
+export function parseMigrationManifest(text: string): Omit<MigrationManifest, 'slug'> {
+  const manifest: Omit<MigrationManifest, 'slug'> = { mechanical: false, appliesTo: [], lineEdits: [] };
+  let section: 'applies_to' | 'line_edits' | null = null;
+  let current: LineEdit | null = null;
+  for (const raw of text.split('\n')) {
+    const line = raw.replace(/\s+$/, '');
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+
+    const topMatch = line.match(/^(\w+):\s*(.*)$/);
+    if (topMatch) {
+      const [, key, val] = topMatch;
+      if (key === 'mechanical') {
+        manifest.mechanical = val.trim() === 'true';
+        section = null;
+      } else if (key === 'applies_to') {
+        section = 'applies_to';
+      } else if (key === 'line_edits') {
+        section = 'line_edits';
+      }
+      continue;
+    }
+
+    if (section === 'applies_to') {
+      const m = line.match(/^\s*-\s*(.+)$/);
+      if (m) manifest.appliesTo.push(unquote(m[1].trim()));
+    } else if (section === 'line_edits') {
+      const fromMatch = line.match(/^\s*-\s*from:\s*(.+)$/);
+      if (fromMatch) {
+        current = { from: normalizeEditLine(fromMatch[1]), to: '' };
+        manifest.lineEdits.push(current);
+        continue;
+      }
+      const toMatch = line.match(/^\s*to:\s*(.+)$/);
+      if (toMatch && current) current.to = normalizeEditLine(toMatch[1]);
+    }
+  }
+  return manifest;
+}
+
+/** Replay a manifest's declared `lineEdits` against the before-state and
+ *  check the result matches the after-state exactly — the independent
+ *  verification §16.3 requires: the tool's `mechanical: true` declaration is
+ *  never trusted on its own; only a replay that reproduces the after-state
+ *  suppresses suspicion. */
+function replayExplains(beforeLines: string[], afterLines: string[], lineEdits: LineEdit[]): boolean {
+  const working = [...beforeLines];
+  for (const edit of lineEdits) {
+    const idx = working.indexOf(edit.from);
+    if (idx === -1) return false;
+    working.splice(idx, 1, edit.to);
+  }
+  return sameLines([...working].sort(), [...afterLines].sort());
+}
+
+export interface SuspicionResult {
+  suspicious: boolean;
+  /** True when a manifest declared `mechanical: true` for this target but
+   *  its replay did not fully explain the change — the hatch does not
+   *  self-grant; suspicion stands regardless of the flag (§16.3). */
+  hatchRefused?: boolean;
+}
+
+/**
+ * §16.2: *Suspicious* ⟺ the target's content identity at the anchor commit
+ * differs from its content identity now, **and** §16.3's hatch does not
+ * explain the difference.
+ *
+ * `beforeText` / `afterText` are already-fetched (git IO lives in the
+ * caller); `undefined` for either (no anchor, or the target no longer
+ * exists) means nothing to compare — not suspicious, per the reference
+ * script's `target-absent-at-anchor` / `target-absent-now` cases.
+ */
+export function checkSuspicion(
+  beforeText: string | undefined,
+  afterText: string | undefined,
+  applicableManifests: Array<Omit<MigrationManifest, 'slug'>> = [],
+): SuspicionResult {
+  if (beforeText === undefined || afterText === undefined) return { suspicious: false };
+
+  const beforeLines = statementLines(beforeText);
+  const afterLines = statementLines(afterText);
+  if (sameLines(beforeLines, afterLines)) return { suspicious: false };
+
+  for (const manifest of applicableManifests) {
+    if (replayExplains(beforeLines, afterLines, manifest.lineEdits)) {
+      return { suspicious: false };
+    }
+  }
+  return { suspicious: true, hatchRefused: applicableManifests.some((m) => m.mechanical) };
+}

package/src/metric/index.ts

@@ -0,0 +1,4 @@
+export type { Metric, MetricDirectionOfGood } from './types.js';
+export { METRIC_DIRECTIONS_OF_GOOD } from './types.js';
+export { validateMetric } from './validate.js';
+export type { MetricValidateOptions } from './validate.js';

package/src/metric/types.ts

@@ -0,0 +1,38 @@
+// METRIC — motivation-layer managed indicator (no ArchiMate counterpart).
+// Schema: methodology notations/ELEMENT_PRIMITIVES.md §7.27.
+
+import type { GateChecks } from '../requirement/types.js';
+
+/** How to read movement relative to `target` (§7.27). */
+export type MetricDirectionOfGood = 'higher_is_better' | 'lower_is_better' | 'on_target';
+
+export const METRIC_DIRECTIONS_OF_GOOD: readonly MetricDirectionOfGood[] = [
+  'higher_is_better',
+  'lower_is_better',
+  'on_target',
+];
+
+export interface Metric {
+  notation: 'metric';
+  id: string;
+  name: string;
+  /** Typed IDs of what this metric tracks — GOAL, CAPABILITY, or PROCESS. Non-empty. */
+  measures: string[];
+  /** Free-form unit the value and `target` are expressed in (percent, days, …). */
+  unit: string;
+  target: number;
+  direction_of_good: MetricDirectionOfGood;
+  /** ROLE-… accountable for tracking this metric and acting on it. */
+  owner_role: string;
+  description?: string;
+
+  // Admission record (CONTRACT.md §6).
+  zone: 'canon';
+  admitted_at: string;
+  admitted_by: string;
+  gate_checks: GateChecks;
+
+  // Primitive lifecycle (CONTRACT.md §7).
+  valid_from: string;
+  valid_to: string | null;
+}

package/src/metric/validate.ts

@@ -0,0 +1,102 @@
+// METRIC validator — methodology ELEMENT_PRIMITIVES.md §7.27 / §9.
+//
+// Codes:
+//   METRIC-001 — shape / id grammar / required envelope + per-type fields
+//               (measures, unit, target, direction_of_good, owner_role).
+//   METRIC-002 — measures is empty, or an entry does not resolve to an
+//               admitted GOAL / CAPABILITY / PROCESS in canon.
+//   METRIC-003 — direction_of_good outside {higher_is_better, lower_is_better,
+//               on_target}.
+//   METRIC-004 — owner_role does not resolve to an admitted ROLE in canon.
+//
+// Resolution rules (METRIC-002/004) that need artefact *existence* run only
+// when a `CanonCatalog` is supplied; the TYPE checks are derivable from the
+// id prefix and run either way.
+
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+import { typeOfId, isCanonicalIdOfType, type CanonCatalog } from '../typed-id.js';
+import { METRIC_DIRECTIONS_OF_GOOD } from './types.js';
+
+export interface MetricValidateOptions {
+  /** When provided, METRIC-002/004 enforce artefact existence for cross-refs. */
+  catalog?: CanonCatalog;
+}
+
+const MEASURES_TYPES = ['GOAL', 'CAPABILITY', 'PROCESS'] as const;
+
+export function validateMetric(input: unknown, options: MetricValidateOptions = {}): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    errors.push({ code: 'METRIC-001', message: 'Metric must be a YAML mapping.' });
+    return { valid: false, errors, warnings };
+  }
+  const m = input as Record<string, unknown>;
+
+  // METRIC-001 — id grammar + notation tag + envelope + plain per-type fields.
+  if (!isCanonicalIdOfType(m.id, 'METRIC')) {
+    errors.push({ code: 'METRIC-001', message: `id "${String(m.id)}" must match METRIC-[<middle>-]<INTEGER>.`, path: 'id' });
+  }
+  if (m.notation !== 'metric') {
+    errors.push({ code: 'METRIC-001', message: 'notation must be the fixed value "metric".', path: 'notation' });
+  }
+  if (m.zone !== 'canon') {
+    errors.push({ code: 'METRIC-001', message: 'zone is required and must be "canon".', path: 'zone' });
+  }
+  for (const f of ['name', 'admitted_at', 'admitted_by', 'valid_from', 'unit', 'owner_role'] as const) {
+    if (typeof m[f] !== 'string' || (m[f] as string).trim() === '') {
+      errors.push({ code: 'METRIC-001', message: `${f} is required.`, path: f });
+    }
+  }
+  if (m.gate_checks === null || typeof m.gate_checks !== 'object') {
+    errors.push({ code: 'METRIC-001', message: 'gate_checks is required and must be a mapping.', path: 'gate_checks' });
+  }
+  if (!('valid_to' in m) || !(typeof m.valid_to === 'string' || m.valid_to === null)) {
+    errors.push({ code: 'METRIC-001', message: 'valid_to is required (an ISO date string or null).', path: 'valid_to' });
+  }
+  if (typeof m.target !== 'number' || Number.isNaN(m.target)) {
+    errors.push({ code: 'METRIC-001', message: 'target is required and must be a number.', path: 'target' });
+  }
+
+  // direction_of_good — required (METRIC-001) + enum (METRIC-003).
+  const dir = m.direction_of_good;
+  if (dir === undefined || dir === null || dir === '') {
+    errors.push({ code: 'METRIC-001', message: 'direction_of_good is required.', path: 'direction_of_good' });
+  } else if (!(METRIC_DIRECTIONS_OF_GOOD as readonly string[]).includes(dir as string)) {
+    errors.push({
+      code: 'METRIC-003',
+      message: `direction_of_good "${String(dir)}" must be one of ${METRIC_DIRECTIONS_OF_GOOD.join(', ')}.`,
+      path: 'direction_of_good',
+    });
+  }
+
+  // measures — required non-empty list (METRIC-001), each resolves to GOAL/CAPABILITY/PROCESS (METRIC-002).
+  const measures = m.measures;
+  if (!Array.isArray(measures) || measures.length === 0) {
+    errors.push({ code: 'METRIC-001', message: 'measures is required and must be a non-empty list of typed IDs.', path: 'measures' });
+  } else {
+    measures.forEach((ref, i) => {
+      const type = typeOfId(ref);
+      if (!type || !(MEASURES_TYPES as readonly string[]).includes(type as typeof MEASURES_TYPES[number])) {
+        errors.push({ code: 'METRIC-002', message: `measures[${i}] "${String(ref)}" must resolve to a GOAL, CAPABILITY, or PROCESS.`, path: `measures[${i}]` });
+        return;
+      }
+      if (options.catalog && options.catalog.typeOf(ref as string) === undefined) {
+        errors.push({ code: 'METRIC-002', message: `measures[${i}] "${String(ref)}" does not resolve to an admitted artefact.`, path: `measures[${i}]` });
+      }
+    });
+  }
+
+  // owner_role — must be a typed ROLE id (METRIC-004), and resolve when a catalog is supplied.
+  const ownerRole = m.owner_role;
+  if (typeof ownerRole === 'string' && ownerRole.trim() !== '') {
+    if (!isCanonicalIdOfType(ownerRole, 'ROLE')) {
+      errors.push({ code: 'METRIC-004', message: `owner_role "${ownerRole}" must be a typed ROLE id.`, path: 'owner_role' });
+    } else if (options.catalog && options.catalog.typeOf(ownerRole) === undefined) {
+      errors.push({ code: 'METRIC-004', message: `owner_role "${ownerRole}" does not resolve to an admitted artefact.`, path: 'owner_role' });
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}

package/src/need/index.ts

@@ -0,0 +1,3 @@
+export type { Need } from './types.js';
+export { validateNeed } from './validate.js';
+export type { NeedValidateOptions } from './validate.js';

package/src/need/types.ts

@@ -0,0 +1,31 @@
+// NEED — motivation-layer stakeholder/user need (no ArchiMate counterpart).
+// Upstream of REQUIREMENT — schema: methodology notations/ELEMENT_PRIMITIVES.md §7.28.
+
+import type { GateChecks } from '../requirement/types.js';
+import type { AgreementValue } from '../agreement.js';
+
+export interface Need {
+  notation: 'need';
+  id: string;
+  name: string;
+  /** Typed ID of the STAKEHOLDER whose need this is. */
+  stakeholder: string;
+  description?: string;
+
+  // Agreement axis (CONTRACT.md §6.3, when present) — independent of admission.
+  /** `draft` \| `agreed` \| `disputed`. Absent ⇒ `agreed` (back-compat). */
+  agreement?: AgreementValue;
+  /** Required whenever `agreement` is present (AGREE-003). Written only by a human when `agreement: agreed` (AGREE-002). */
+  agreed_by?: string;
+  agreed_at?: string;
+
+  // Admission record (CONTRACT.md §6).
+  zone: 'canon';
+  admitted_at: string;
+  admitted_by: string;
+  gate_checks: GateChecks;
+
+  // Primitive lifecycle (CONTRACT.md §7).
+  valid_from: string;
+  valid_to: string | null;
+}

package/src/need/validate.ts

@@ -0,0 +1,71 @@
+// NEED validator — methodology ELEMENT_PRIMITIVES.md §7.28 / §9.
+//
+// Codes:
+//   NEED-001 — shape / id grammar / required envelope fields, including the
+//              required per-type `stakeholder` field.
+//   NEED-002 — stakeholder does not resolve to an admitted STAKEHOLDER in canon.
+//
+// The cross-cutting NEED-COVERAGE-001 / NEED-VALIDATION-COVERAGE-001..002
+// reverse-trace rules are owned elsewhere (CONTRACT.md §8, the compliance
+// reverse-index) and are out of scope for this single-artefact validator —
+// same posture as `validateRequirement` / `validateVerification`.
+//
+// Resolution (NEED-002 existence) runs only when a `CanonCatalog` is
+// supplied; the TYPE check is derivable from the id prefix and runs either way.
+
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+import { isCanonicalIdOfType, type CanonCatalog } from '../typed-id.js';
+import { checkAgreement } from '../agreement.js';
+
+export interface NeedValidateOptions {
+  /** When provided, NEED-002 enforces artefact existence for `stakeholder`. */
+  catalog?: CanonCatalog;
+}
+
+export function validateNeed(input: unknown, options: NeedValidateOptions = {}): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    errors.push({ code: 'NEED-001', message: 'Need must be a YAML mapping.' });
+    return { valid: false, errors, warnings };
+  }
+  const n = input as Record<string, unknown>;
+
+  // NEED-001 — id grammar + notation tag + envelope.
+  if (!isCanonicalIdOfType(n.id, 'NEED')) {
+    errors.push({ code: 'NEED-001', message: `id "${String(n.id)}" must match NEED-[<middle>-]<INTEGER>.`, path: 'id' });
+  }
+  if (n.notation !== 'need') {
+    errors.push({ code: 'NEED-001', message: 'notation must be the fixed value "need".', path: 'notation' });
+  }
+  if (n.zone !== 'canon') {
+    errors.push({ code: 'NEED-001', message: 'zone is required and must be "canon".', path: 'zone' });
+  }
+  for (const f of ['name', 'admitted_at', 'admitted_by', 'valid_from'] as const) {
+    if (typeof n[f] !== 'string' || (n[f] as string).trim() === '') {
+      errors.push({ code: 'NEED-001', message: `${f} is required.`, path: f });
+    }
+  }
+  if (n.gate_checks === null || typeof n.gate_checks !== 'object') {
+    errors.push({ code: 'NEED-001', message: 'gate_checks is required and must be a mapping.', path: 'gate_checks' });
+  }
+  if (!('valid_to' in n) || !(typeof n.valid_to === 'string' || n.valid_to === null)) {
+    errors.push({ code: 'NEED-001', message: 'valid_to is required (an ISO date string or null).', path: 'valid_to' });
+  }
+
+  // stakeholder — required (NEED-001) + resolves to STAKEHOLDER (NEED-002).
+  const stakeholder = n.stakeholder;
+  if (typeof stakeholder !== 'string' || stakeholder.trim() === '') {
+    errors.push({ code: 'NEED-001', message: 'stakeholder is required.', path: 'stakeholder' });
+  } else if (!isCanonicalIdOfType(stakeholder, 'STAKEHOLDER')) {
+    errors.push({ code: 'NEED-002', message: `stakeholder "${stakeholder}" must be a typed STAKEHOLDER id.`, path: 'stakeholder' });
+  } else if (options.catalog && options.catalog.typeOf(stakeholder) === undefined) {
+    errors.push({ code: 'NEED-002', message: `stakeholder "${stakeholder}" does not resolve to an admitted artefact.`, path: 'stakeholder' });
+  }
+
+  // AGREE-001..003 — agreement axis (CONTRACT.md §6.3.1), optional; absent ⇒ agreed.
+  errors.push(...checkAgreement(n));
+
+  return { valid: errors.length === 0, errors, warnings };
+}

package/src/repo-validate/check-versioned-attributes.ts

@@ -0,0 +1,112 @@
+// Versioned-attribute sidecar checks (CONTRACT.md §9) — `VERSIONED-001..005`.
+//
+// A sidecar is any doc under `canon/elements/**` shaped like one (`target` +
+// `attribute_versions`, no `id` — same "no id -> not an element" convention
+// `docId` already uses to skip these docs everywhere else in this file's
+// sibling checks). Both halves of §9.3 live here:
+//   - VERSIONED-001 — a sidecar's `target` must resolve to an admitted
+//     primitive in this same model.
+//   - VERSIONED-002/003/005 — the sidecar's own array shape, delegated to
+//     the shared `../versioned-attribute` module (needs VERSIONED-005's
+//     bound: the target's own `valid_from`/`valid_to`, read from the
+//     resolved target doc).
+//   - VERSIONED-004 — a field declared `time_varying` present inline on its
+//     primitive, instead of only in the sidecar.
+//
+// `TIME_VARYING_FIELDS` is deliberately narrower than the full candidate
+// list in CONTRACT.md §9.4: it only enforces fields already `time_varying`
+// on methodology's *currently-merged* notation specs. `capability` covers
+// `current_maturity`, `target_maturity`, `owner_role`, `target_date` per
+// `05-capability-map.md` §13/§14. Applications-catalogue `maturity` (and its
+// sibling `owner_role`/`vendor`) is on the same 2026-08-02 maturity ADR but
+// is not enforced here yet — it lives on the `applications[]` list inside a
+// catalogue view document, not on a standalone element primitive, and this
+// check only walks `elements`.
+
+import { parseSidecar, validateSidecar } from '../versioned-attribute/index.js';
+import { docId } from './validate-repo.js';
+import type { RepoDoc, RepoFinding, RepoModelInput } from './types.js';
+
+const PScope: RepoFinding['scope'] = 'repo';
+
+const TIME_VARYING_FIELDS: Record<string, string[]> = {
+  capability: ['current_maturity', 'target_maturity', 'owner_role', 'target_date'],
+};
+
+function readString(data: Record<string, unknown>, key: string): string | undefined {
+  const v = data[key];
+  return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+
+/** VERSIONED-004 — a time_varying field present inline on its primitive. */
+function checkInlineTimeVarying(elements: RepoDoc[], findings: RepoFinding[]): void {
+  for (const doc of elements) {
+    if (!doc.data) continue;
+    const id = docId(doc);
+    if (!id) continue; // sidecars carry no id — not a primitive
+    const notation = doc.data['notation'];
+    if (typeof notation !== 'string') continue;
+    const fields = TIME_VARYING_FIELDS[notation];
+    if (!fields) continue;
+
+    for (const field of fields) {
+      if (doc.data[field] !== undefined) {
+        findings.push({
+          scope: PScope,
+          id,
+          ruleId: 'VERSIONED-004',
+          message:
+            `VERSIONED-004: '${id}' declares '${field}' inline; it is time_varying and belongs in ` +
+            `the sidecar '${id}.history.yaml' (CONTRACT.md §9), not on the primitive.`,
+        });
+      }
+    }
+  }
+}
+
+/** VERSIONED-001/002/003/005 — every sidecar doc found under `canon/elements/**`. */
+function checkSidecars(elements: RepoDoc[], findings: RepoFinding[]): void {
+  const elementById = new Map<string, RepoDoc>();
+  for (const doc of elements) {
+    const id = docId(doc);
+    if (id) elementById.set(id, doc);
+  }
+
+  for (const doc of elements) {
+    if (!doc.data || docId(doc)) continue; // sidecars have no id
+    const sidecar = parseSidecar(doc.data);
+    if (!sidecar) continue; // not shaped like a sidecar — ignore, same as docId's element/non-element split
+
+    const targetDoc = elementById.get(sidecar.target);
+    if (!targetDoc) {
+      findings.push({
+        scope: PScope,
+        id: sidecar.target,
+        ruleId: 'VERSIONED-001',
+        message: `VERSIONED-001: sidecar '${doc.path}' target '${sidecar.target}' does not resolve to an admitted primitive.`,
+      });
+      continue;
+    }
+
+    const targetValidFrom = targetDoc.data ? readString(targetDoc.data, 'valid_from') : undefined;
+    const validToRaw = targetDoc.data?.['valid_to'];
+    const targetValidTo = validToRaw === null ? null : typeof validToRaw === 'string' ? validToRaw : undefined;
+
+    for (const f of validateSidecar(sidecar, targetValidFrom, targetValidTo)) {
+      findings.push({
+        scope: PScope,
+        id: sidecar.target,
+        ruleId: f.code,
+        severity: f.severity,
+        message: `${f.code}: sidecar '${doc.path}' ${f.message}`,
+      });
+    }
+  }
+}
+
+/** Run the versioned-attribute sidecar checks (VERSIONED-001..005) over the
+ *  loaded element set and append findings. Pure, deterministic order. */
+export function checkVersionedAttributes(input: RepoModelInput, findings: RepoFinding[]): void {
+  checkInlineTimeVarying(input.elements, findings);
+  checkSidecars(input.elements, findings);
+}

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

@@ -29,6 +29,7 @@
 
 import { checkStrategyChainSemantics } from './check-strategy-chain.js';
 import { checkElementHygiene } from './check-element-hygiene.js';
+import { checkVersionedAttributes } from './check-versioned-attributes.js';
 import type { RepoDoc, RepoFinding, RepoModelInput } from './types.js';
 
 const PScope: RepoFinding['scope'] = 'repo';
@@ -428,5 +429,7 @@ export function validateRepoModel(input: RepoModelInput): RepoFinding[] {
   // Phase 8 — standalone-element envelope rules ported from DSM's Go
   // Validate*Element functions (GOAL-ELEM-001..003, ACTION-001/002/005).
   checkElementHygiene(input, findings);
+  // Phase 9 — versioned-attribute sidecar rules (CONTRACT.md §9, VERSIONED-001..005).
+  checkVersionedAttributes(input, findings);
   return findings;
 }

package/src/requirement/index.ts

@@ -1,4 +1,4 @@
-export type { Requirement, RequirementSeverity, GateChecks } from './types.js';
-export { REQUIREMENT_DERIVED_FROM_TYPES } from './types.js';
+export type { Requirement, RequirementSeverity, RequirementLevel, RequirementKind, GateChecks } from './types.js';
+export { REQUIREMENT_DERIVED_FROM_TYPES, REQUIREMENT_LEVELS, REQUIREMENT_KINDS } from './types.js';
 export { validateRequirement } from './validate.js';
 export type { RequirementValidateOptions } from './validate.js';