@transitrix/diagrams 1.0.0

package/src/fgca/types.ts

@@ -0,0 +1,50 @@
+export interface FactorItem {
+  id: number;
+  name: string;
+}
+
+export interface GoalItem {
+  id: number;
+  name: string;
+  level?: number;
+  /** Goals may carry embedded factor links returned by the API. */
+  factor?: Array<{ id: number }>;
+}
+
+export interface BdnChangeWithActivities {
+  id: number;
+  name: string;
+  goal_id: number;
+  activity_ids: number[];
+}
+
+export interface ActivityItem {
+  id: number;
+  name: string;
+  goal_id?: number | null;
+  activity_type_id?: number;
+}
+
+export interface ActivityTypeItem {
+  id: number;
+  name?: string;
+}
+
+export interface DiagramStyle {
+  nodeBorderColor?: string;
+  nodeBorderWidth?: number;
+  edgeColor?: string;
+  edgeWidth?: number;
+}
+
+/** The four columns of the FGCA diagram. */
+export type FGCAColumn = "factor" | "goal" | "change" | "activity";
+
+export const ALL_FGCA_COLUMNS: FGCAColumn[] = ["factor", "goal", "change", "activity"];
+
+export const FGCA_COLUMN_LABELS: Record<FGCAColumn, string> = {
+  factor: "F",
+  goal: "G",
+  change: "C",
+  activity: "A",
+};

package/src/fgca/validate.ts

@@ -0,0 +1,126 @@
+import type { FactorItem, GoalItem, BdnChangeWithActivities, ActivityItem } from './types.js';
+import type {
+  ValidationError,
+  ValidationWarning,
+  ValidationResult,
+} from '../validation-types.js';
+
+// FGCA historically exposed PREFIXED validation type names. Keep them as
+// aliases of the shared shape so external consumers (preview, tests) keep
+// working without churn.
+export type FGCAValidationError = ValidationError;
+export type FGCAValidationWarning = ValidationWarning;
+export type FGCAValidationResult = ValidationResult;
+
+export interface FGCADoc {
+  notation: string;
+  spec_version?: string;
+  factors: FactorItem[];
+  goals: GoalItem[];
+  changes: BdnChangeWithActivities[];
+  activities: ActivityItem[];
+}
+
+export function validateFGCADoc(input: unknown): FGCAValidationResult {
+  const errors: FGCAValidationError[] = [];
+  const warnings: FGCAValidationWarning[] = [];
+
+  if (!input || typeof input !== 'object') {
+    return { valid: false, errors: [{ code: 'SCHEMA_INVALID', message: 'Input must be an object' }], warnings: [] };
+  }
+
+  const raw = input as Record<string, unknown>;
+
+  if (raw.notation === undefined) {
+    errors.push({ code: 'MISSING_NOTATION', message: 'notation field is required' });
+    return { valid: false, errors, warnings };
+  }
+  if (raw.notation !== 'fgca') {
+    errors.push({ code: 'WRONG_NOTATION', message: `notation must be "fgca", got "${String(raw.notation)}"` });
+    return { valid: false, errors, warnings };
+  }
+
+  if (!Array.isArray(raw.factors)) errors.push({ code: 'SCHEMA_INVALID', message: 'factors must be an array', path: 'factors' });
+  if (!Array.isArray(raw.goals)) errors.push({ code: 'SCHEMA_INVALID', message: 'goals must be an array', path: 'goals' });
+  if (!Array.isArray(raw.changes)) errors.push({ code: 'SCHEMA_INVALID', message: 'changes must be an array', path: 'changes' });
+  if (!Array.isArray(raw.activities)) errors.push({ code: 'SCHEMA_INVALID', message: 'activities must be an array', path: 'activities' });
+  if (errors.length > 0) return { valid: false, errors, warnings };
+
+  const doc = raw as unknown as FGCADoc;
+  const collectIds = (arr: unknown[]): Set<number> => {
+    const out = new Set<number>();
+    for (const el of arr) {
+      if (el && typeof el === 'object') {
+        const id = (el as { id?: unknown }).id;
+        if (typeof id === 'number') out.add(id);
+      }
+    }
+    return out;
+  };
+  const factorIds = collectIds(doc.factors as unknown as unknown[]);
+  const goalIds = collectIds(doc.goals as unknown as unknown[]);
+  const activityIds = collectIds(doc.activities as unknown as unknown[]);
+
+  for (let i = 0; i < doc.factors.length; i++) {
+    const f = doc.factors[i] as unknown;
+    if (!f || typeof f !== 'object') {
+      errors.push({ code: 'SCHEMA_INVALID', message: 'factor entry must be an object', path: `factors[${i}]` });
+      continue;
+    }
+    const factor = f as { id?: unknown; name?: unknown };
+    if (typeof factor.id !== 'number') errors.push({ code: 'SCHEMA_INVALID', message: 'factor id must be a number', path: `factors[${i}]` });
+    if (typeof factor.name !== 'string' || !factor.name.trim()) errors.push({ code: 'EMPTY_NAME', message: `Factor ${String(factor.id)} has empty name`, path: `factors[${i}]` });
+  }
+
+  for (let i = 0; i < doc.goals.length; i++) {
+    const g = doc.goals[i] as unknown;
+    if (!g || typeof g !== 'object') {
+      errors.push({ code: 'SCHEMA_INVALID', message: 'goal entry must be an object', path: `goals[${i}]` });
+      continue;
+    }
+    const goal = g as { id?: unknown; name?: unknown; factor?: unknown };
+    if (typeof goal.id !== 'number') errors.push({ code: 'SCHEMA_INVALID', message: 'goal id must be a number', path: `goals[${i}]` });
+    if (typeof goal.name !== 'string' || !goal.name.trim()) errors.push({ code: 'EMPTY_NAME', message: `Goal ${String(goal.id)} has empty name`, path: `goals[${i}]` });
+    const factorRefs = Array.isArray(goal.factor) ? (goal.factor as unknown[]) : [];
+    for (const fr of factorRefs) {
+      if (!fr || typeof fr !== 'object') continue;
+      const fid = (fr as { id?: unknown }).id;
+      if (typeof fid === 'number' && !factorIds.has(fid)) {
+        warnings.push({ code: 'BROKEN_REF', message: `Goal ${String(goal.id)} references missing factor ${fid}`, path: `goals[${i}].factor` });
+      }
+    }
+  }
+
+  for (let i = 0; i < doc.changes.length; i++) {
+    const c = doc.changes[i] as unknown;
+    if (!c || typeof c !== 'object') {
+      errors.push({ code: 'SCHEMA_INVALID', message: 'change entry must be an object', path: `changes[${i}]` });
+      continue;
+    }
+    const change = c as { id?: unknown; name?: unknown; goal_id?: unknown; activity_ids?: unknown };
+    if (typeof change.id !== 'number') errors.push({ code: 'SCHEMA_INVALID', message: 'change id must be a number', path: `changes[${i}]` });
+    if (typeof change.name !== 'string' || !change.name.trim()) errors.push({ code: 'EMPTY_NAME', message: `Change ${String(change.id)} has empty name`, path: `changes[${i}]` });
+    if (typeof change.goal_id === 'number' && !goalIds.has(change.goal_id)) {
+      warnings.push({ code: 'BROKEN_REF', message: `Change ${String(change.id)} references missing goal ${change.goal_id}`, path: `changes[${i}].goal_id` });
+    }
+    const aids = Array.isArray(change.activity_ids) ? (change.activity_ids as unknown[]) : [];
+    for (const aid of aids) {
+      if (typeof aid === 'number' && !activityIds.has(aid)) {
+        warnings.push({ code: 'BROKEN_REF', message: `Change ${String(change.id)} references missing activity ${aid}`, path: `changes[${i}].activity_ids` });
+      }
+    }
+  }
+
+  for (let i = 0; i < doc.activities.length; i++) {
+    const a = doc.activities[i] as unknown;
+    if (!a || typeof a !== 'object') {
+      errors.push({ code: 'SCHEMA_INVALID', message: 'activity entry must be an object', path: `activities[${i}]` });
+      continue;
+    }
+    const activity = a as { id?: unknown; name?: unknown };
+    if (typeof activity.id !== 'number') errors.push({ code: 'SCHEMA_INVALID', message: 'activity id must be a number', path: `activities[${i}]` });
+    if (typeof activity.name !== 'string' || !activity.name.trim()) errors.push({ code: 'EMPTY_NAME', message: `Activity ${String(activity.id)} has empty name`, path: `activities[${i}]` });
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}

package/src/geometry.ts

@@ -0,0 +1,9 @@
+/** Shared geometry primitives used across diagram layout modules. */
+
+export interface LayoutBounds {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+

package/src/goals/__tests__/layout.test.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect } from 'vitest';
+import { layoutGoalTree } from '../layout.js';
+import type { GoalTree } from '../types.js';
+
+const TREE: GoalTree = {
+  goal_types: [
+    { name: 'Strategy', level: 0 },
+    { name: 'Business Goal', level: 1 },
+    { name: 'Project', level: 2 },
+  ],
+  goals: [
+    { id: 1, name: 'North Star', type: 'Strategy', level: 0, parent_id: 0 },
+    { id: 2, name: 'EU Expansion', type: 'Business Goal', level: 1, parent_id: 1 },
+    { id: 3, name: 'Berlin Office', type: 'Project', level: 2, parent_id: 2 },
+    { id: 4, name: 'London Office', type: 'Project', level: 2, parent_id: 2 },
+  ],
+};
+
+describe('layoutGoalTree', () => {
+  it('returns nodes for all goals', () => {
+    const layout = layoutGoalTree(TREE);
+    expect(layout.nodes).toHaveLength(4);
+  });
+
+  it('returns edges for parent-child pairs', () => {
+    const layout = layoutGoalTree(TREE);
+    expect(layout.edges).toHaveLength(3); // 1→2, 2→3, 2→4
+  });
+
+  it('levels map to increasing x positions', () => {
+    const layout = layoutGoalTree(TREE);
+    const byId = new Map(layout.nodes.map(n => [n.id, n]));
+    expect(byId.get(1)!.x).toBeLessThan(byId.get(2)!.x);
+    expect(byId.get(2)!.x).toBeLessThan(byId.get(3)!.x);
+  });
+
+  it('siblings at same level have different y positions', () => {
+    const layout = layoutGoalTree(TREE);
+    const byId = new Map(layout.nodes.map(n => [n.id, n]));
+    expect(byId.get(3)!.y).not.toBe(byId.get(4)!.y);
+  });
+
+  it('returns non-zero bounds for non-empty tree', () => {
+    const layout = layoutGoalTree(TREE);
+    expect(layout.bounds.width).toBeGreaterThan(0);
+    expect(layout.bounds.height).toBeGreaterThan(0);
+  });
+
+  it('returns empty layout for empty goals', () => {
+    const layout = layoutGoalTree({ goal_types: [], goals: [] });
+    expect(layout.nodes).toHaveLength(0);
+    expect(layout.edges).toHaveLength(0);
+  });
+
+  it('nodes have default 250×80 size', () => {
+    const layout = layoutGoalTree(TREE);
+    expect(layout.nodes[0].width).toBe(250);
+    expect(layout.nodes[0].height).toBe(80);
+  });
+
+  it('respects custom nodeWidth/nodeHeight', () => {
+    const layout = layoutGoalTree(TREE, { nodeWidth: 200, nodeHeight: 60 });
+    expect(layout.nodes[0].width).toBe(200);
+    expect(layout.nodes[0].height).toBe(60);
+  });
+
+  // vkgeorgia/strategy#75 — configurable spacing. The preview maps
+  // horizontalGap → rankSep and verticalGap → nodeSep.
+  it('larger rankSep widens the column step', () => {
+    const tight = layoutGoalTree(TREE, { rankSep: 80 });
+    const wide = layoutGoalTree(TREE, { rankSep: 200 });
+    const stepOf = (l: ReturnType<typeof layoutGoalTree>) => {
+      const byId = new Map(l.nodes.map(n => [n.id, n]));
+      return byId.get(2)!.x - byId.get(1)!.x;
+    };
+    expect(stepOf(wide)).toBeGreaterThan(stepOf(tight));
+  });
+
+  it('larger nodeSep increases the gap between stacked siblings', () => {
+    const gapOf = (sep: number) => {
+      const l = layoutGoalTree(TREE, { nodeSep: sep });
+      const byId = new Map(l.nodes.map(n => [n.id, n]));
+      return Math.abs(byId.get(4)!.y - byId.get(3)!.y);
+    };
+    expect(gapOf(120)).toBeGreaterThan(gapOf(24));
+  });
+
+  it('each node carries original goal data', () => {
+    const layout = layoutGoalTree(TREE);
+    const node1 = layout.nodes.find(n => n.id === 1)!;
+    expect(node1.data.name).toBe('North Star');
+  });
+
+  it('viewDepth hides nodes beyond depth', () => {
+    const layout = layoutGoalTree(TREE, { viewDepth: 1 });
+    // Level 2 nodes (id 3, 4) should be hidden
+    expect(layout.nodes.every(n => n.data.level <= 1)).toBe(true);
+  });
+
+  it('compresses non-contiguous levels into adjacent columns (no phantom empty columns)', () => {
+    // Legacy / non-canonical input: goal_types skip levels 1 and 3, so
+    // goals sit at levels 0, 2, 4. Column x must advance by exactly one
+    // step per used level, not per absolute level value — otherwise the
+    // skipped levels open empty columns and double the horizontal spacing.
+    const gapped: GoalTree = {
+      goal_types: [
+        { name: 'Strategy', level: 0 },
+        { name: 'Strategic Goal', level: 2 },
+        { name: 'Project Goal', level: 4 },
+      ],
+      goals: [
+        { id: 1, name: 'Root', type: 'Strategy', level: 0, parent_id: 0 },
+        { id: 2, name: 'Mid', type: 'Strategic Goal', level: 2, parent_id: 1 },
+        { id: 3, name: 'Leaf', type: 'Project Goal', level: 4, parent_id: 2 },
+      ],
+    };
+    const layout = layoutGoalTree(gapped);
+    const byId = new Map(layout.nodes.map(n => [n.id, n]));
+    const step = byId.get(2)!.x - byId.get(1)!.x;
+    // Root→Mid and Mid→Leaf must use the same single-column step despite
+    // the level numbers jumping by 2 each time.
+    expect(byId.get(3)!.x - byId.get(2)!.x).toBe(step);
+    // And that step is one node width + one rank separator (250 + 80).
+    expect(step).toBe(250 + 80);
+  });
+
+  // Pre-release blocker regression (orchestrator review 2026-05-21).
+  it('[blocker] does not stack-overflow on a self-parent cycle', () => {
+    const cyclic: GoalTree = {
+      goal_types: [{ name: 'X', level: 0 }],
+      goals: [{ id: 1, name: 'self-parent', type: 'X', level: 0, parent_id: 1 }],
+    };
+    // Without a visited-set inside placeSubtree, this recurses forever.
+    expect(() => layoutGoalTree(cyclic)).not.toThrow();
+  });
+
+  it('[blocker] does not stack-overflow on a 2-node mutual cycle', () => {
+    const cyclic: GoalTree = {
+      goal_types: [{ name: 'X', level: 0 }, { name: 'Y', level: 1 }],
+      goals: [
+        { id: 1, name: 'A', type: 'X', level: 0, parent_id: 2 },
+        { id: 2, name: 'B', type: 'Y', level: 1, parent_id: 1 },
+      ],
+    };
+    expect(() => layoutGoalTree(cyclic)).not.toThrow();
+  });
+
+  // vkgeorgia/strategy#77 — scope filtering.
+  describe('scope', () => {
+    const ids = (l: ReturnType<typeof layoutGoalTree>) => l.nodes.map(n => n.id).sort((a, b) => a - b);
+
+    it("mode 'all' matches the baseline", () => {
+      expect(ids(layoutGoalTree(TREE, { scope: { mode: 'all' } }))).toEqual(ids(layoutGoalTree(TREE)));
+    });
+
+    it("mode 'level' trims goals strictly above the cap", () => {
+      // TREE: id1 level0, id2 level1, id3/id4 level2.
+      const layout = layoutGoalTree(TREE, { scope: { mode: 'level', maxLevel: 1 } });
+      expect(ids(layout)).toEqual([1, 2]);
+      expect(layout.nodes.every(n => n.data.level <= 1)).toBe(true);
+    });
+
+    it("mode 'root' keeps the chosen goal and its descendants", () => {
+      // root id2 → itself + children id3, id4.
+      const layout = layoutGoalTree(TREE, { scope: { mode: 'root', rootGoalId: '2' } });
+      expect(ids(layout)).toEqual([2, 3, 4]);
+    });
+
+    it("mode 'root' returns an empty layout when the root is absent", () => {
+      const layout = layoutGoalTree(TREE, { scope: { mode: 'root', rootGoalId: '999' } });
+      expect(layout.nodes).toHaveLength(0);
+      expect(layout.edges).toHaveLength(0);
+    });
+  });
+});

package/src/goals/__tests__/mutations.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect } from 'vitest';
+import { reparent, addChild, deleteWithDescendants, moveToBacklog, restoreFromBacklog } from '../mutations.js';
+import type { GoalTree } from '../types.js';
+
+const TREE: GoalTree = {
+  goal_types: [
+    { name: 'Strategy', level: 0 },
+    { name: 'Business Goal', level: 1 },
+    { name: 'Project', level: 2 },
+  ],
+  goals: [
+    { id: 1, name: 'North Star', type: 'Strategy', level: 0, parent_id: 0 },
+    { id: 2, name: 'EU Expansion', type: 'Business Goal', level: 1, parent_id: 1 },
+    { id: 3, name: 'Berlin Office', type: 'Project', level: 2, parent_id: 2 },
+  ],
+};
+
+describe('reparent', () => {
+  it('moves a goal to a new parent', () => {
+    const r = reparent(TREE, 3, 1);
+    expect(r.ok).toBe(true);
+    const moved = r.result!.goals.find(g => g.id === 3)!;
+    expect(moved.parent_id).toBe(1);
+    expect(moved.level).toBe(1);
+  });
+
+  it('refuses to create a cycle', () => {
+    const r = reparent(TREE, 1, 3);
+    expect(r.ok).toBe(false);
+    expect(r.error?.code).toBe('MUTATION_REFUSED');
+  });
+
+  it('refuses self-reparent', () => {
+    expect(reparent(TREE, 1, 1).ok).toBe(false);
+  });
+
+  it('refuses reparent that would exceed max level', () => {
+    const r = reparent(TREE, 1, 3); // would make level 3 which exceeds max 2
+    expect(r.ok).toBe(false);
+  });
+
+  it('preserves immutability — original tree unchanged', () => {
+    reparent(TREE, 3, 1);
+    expect(TREE.goals.find(g => g.id === 3)!.parent_id).toBe(2);
+  });
+});
+
+describe('addChild', () => {
+  it('adds a child with auto-assigned id and level', () => {
+    const r = addChild(TREE, 2, { name: 'Warsaw Office', type: 'Project', level: 2, parent_id: 2 });
+    expect(r.ok).toBe(true);
+    const newGoal = r.result!.goals.find(g => g.name === 'Warsaw Office')!;
+    expect(newGoal.id).toBeGreaterThan(3);
+    expect(newGoal.parent_id).toBe(2);
+    expect(newGoal.level).toBe(2);
+  });
+
+  it('adds root-level child when parentId is 0', () => {
+    const r = addChild(TREE, 0, { name: 'Second Strategy', type: 'Strategy', level: 0, parent_id: 0 });
+    expect(r.ok).toBe(true);
+    expect(r.result!.goals.find(g => g.name === 'Second Strategy')!.level).toBe(0);
+  });
+
+  it('refuses when parent not found', () => {
+    const r = addChild(TREE, 99, { name: 'X', type: 'Project', level: 2, parent_id: 99 });
+    expect(r.ok).toBe(false);
+  });
+
+  it('preserves immutability', () => {
+    const before = TREE.goals.length;
+    addChild(TREE, 1, { name: 'New', type: 'Business Goal', level: 1, parent_id: 1 });
+    expect(TREE.goals.length).toBe(before);
+  });
+});
+
+describe('deleteWithDescendants', () => {
+  it('deletes goal and all descendants', () => {
+    const r = deleteWithDescendants(TREE, 2);
+    expect(r.ok).toBe(true);
+    const ids = r.result!.goals.map(g => g.id);
+    expect(ids).not.toContain(2);
+    expect(ids).not.toContain(3);
+    expect(ids).toContain(1);
+  });
+
+  it('refuses when goal not found', () => {
+    expect(deleteWithDescendants(TREE, 99).ok).toBe(false);
+  });
+
+  it('preserves immutability', () => {
+    deleteWithDescendants(TREE, 2);
+    expect(TREE.goals.length).toBe(3);
+  });
+});
+
+describe('moveToBacklog', () => {
+  it('sets parent_id to 0', () => {
+    const r = moveToBacklog(TREE, 3);
+    expect(r.ok).toBe(true);
+    expect(r.result!.goals.find(g => g.id === 3)!.parent_id).toBe(0);
+  });
+});
+
+describe('restoreFromBacklog', () => {
+  it('reparents the goal to the new parent', () => {
+    const backlogged = moveToBacklog(TREE, 3).result!;
+    const r = restoreFromBacklog(backlogged, 3, 1);
+    expect(r.ok).toBe(true);
+    expect(r.result!.goals.find(g => g.id === 3)!.parent_id).toBe(1);
+  });
+});

package/src/goals/__tests__/parse-canonical.test.ts

@@ -0,0 +1,145 @@
+import { describe, it, expect } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import yaml from 'js-yaml';
+import { parseCanonicalGoals } from '../parse-canonical.js';
+
+const VALID = {
+  notation: 'goals',
+  spec_version: '0.1',
+  id: 'GOALS-SAMPLE-1',
+  name: 'Sample goals tree',
+  goal_types: [
+    { name: 'Strategy', level: 0 },
+    { name: 'Project', level: 1 },
+  ],
+  goals: [
+    { id: 'GOAL-1', name: 'Root', type: 'Strategy', level: 0 },
+    { id: 'GOAL-2', name: 'Child', type: 'Project', level: 1, parent: 'GOAL-1' },
+  ],
+};
+
+describe('parseCanonicalGoals', () => {
+  it('accepts a valid canonical document', () => {
+    const r = parseCanonicalGoals(VALID);
+    expect(r.valid).toBe(true);
+    expect(r.errors).toEqual([]);
+    expect(r.parsed?.goals).toHaveLength(2);
+  });
+
+  it('GOALS-001: rejects non-object input', () => {
+    expect(parseCanonicalGoals(null).errors[0].code).toBe('GOALS-001');
+  });
+
+  it('GOALS-001: rejects wrong notation', () => {
+    const r = parseCanonicalGoals({ ...VALID, notation: 'fga' });
+    expect(r.errors.some((e) => e.code === 'GOALS-001')).toBe(true);
+  });
+
+  it('GOALS-002: rejects malformed doc id', () => {
+    const r = parseCanonicalGoals({ ...VALID, id: 'goals-1' });
+    expect(r.errors.some((e) => e.code === 'GOALS-002')).toBe(true);
+  });
+
+  it('GOALS-003: rejects missing name', () => {
+    const { name: _, ...rest } = VALID;
+    const r = parseCanonicalGoals(rest);
+    expect(r.errors.some((e) => e.code === 'GOALS-003')).toBe(true);
+  });
+
+  it('GOALS-004: rejects empty goal_types', () => {
+    const r = parseCanonicalGoals({ ...VALID, goal_types: [] });
+    expect(r.errors.some((e) => e.code === 'GOALS-004')).toBe(true);
+  });
+
+  it('GOALS-007: rejects malformed goal id', () => {
+    const r = parseCanonicalGoals({
+      ...VALID,
+      goals: [{ id: 'goal-1', name: 'A', type: 'Strategy', level: 0 }],
+    });
+    expect(r.errors.some((e) => e.code === 'GOALS-007')).toBe(true);
+  });
+
+  it('GOALS-007: rejects duplicate goal ids', () => {
+    const r = parseCanonicalGoals({
+      ...VALID,
+      goals: [
+        { id: 'GOAL-1', name: 'A', type: 'Strategy', level: 0 },
+        { id: 'GOAL-1', name: 'B', type: 'Strategy', level: 0 },
+      ],
+    });
+    expect(r.errors.some((e) => e.code === 'GOALS-007')).toBe(true);
+  });
+
+  it('GOALS-008: rejects goal.type not in goal_types', () => {
+    const r = parseCanonicalGoals({
+      ...VALID,
+      goals: [{ id: 'GOAL-1', name: 'A', type: 'Unknown', level: 0 }],
+    });
+    expect(r.errors.some((e) => e.code === 'GOALS-008')).toBe(true);
+  });
+
+  it('GOALS-008: rejects goal.level mismatched with goal_types', () => {
+    const r = parseCanonicalGoals({
+      ...VALID,
+      goals: [{ id: 'GOAL-1', name: 'A', type: 'Strategy', level: 5 }],
+    });
+    expect(r.errors.some((e) => e.code === 'GOALS-008')).toBe(true);
+  });
+
+  it('GOALS-009: warns on broken parent ref', () => {
+    const r = parseCanonicalGoals({
+      ...VALID,
+      goals: [
+        { id: 'GOAL-1', name: 'Root', type: 'Strategy', level: 0 },
+        { id: 'GOAL-2', name: 'Orphan', type: 'Project', level: 1, parent: 'GOAL-99' },
+      ],
+    });
+    expect(r.valid).toBe(true);
+    expect(r.warnings.some((w) => w.code === 'GOALS-009')).toBe(true);
+  });
+
+  it('GOALS-010: detects parent-chain cycle', () => {
+    const r = parseCanonicalGoals({
+      ...VALID,
+      goals: [
+        { id: 'GOAL-1', name: 'A', type: 'Strategy', level: 0, parent: 'GOAL-2' },
+        { id: 'GOAL-2', name: 'B', type: 'Strategy', level: 0, parent: 'GOAL-1' },
+      ],
+    });
+    expect(r.errors.some((e) => e.code === 'GOALS-010')).toBe(true);
+  });
+
+  it('GOALS-011: warns when non-root goal has no parent', () => {
+    const r = parseCanonicalGoals({
+      ...VALID,
+      goals: [{ id: 'GOAL-1', name: 'A', type: 'Project', level: 1 }],
+    });
+    expect(r.valid).toBe(true);
+    expect(r.warnings.some((w) => w.code === 'GOALS-011')).toBe(true);
+  });
+
+  it('maps canonical IDs to internal numeric ids; parent_id is the parent\'s mapped id', () => {
+    const r = parseCanonicalGoals(VALID);
+    expect(r.parsed?.goals[0].id).toBe(1);
+    expect(r.parsed?.goals[0].parent_id).toBe(0);
+    expect(r.parsed?.goals[1].id).toBe(2);
+    expect(r.parsed?.goals[1].parent_id).toBe(1);
+  });
+});
+
+describe('parseCanonicalGoals — example file regression', () => {
+  const EXAMPLES_DIR = path.resolve(process.cwd(), '..', '..', 'tests', 'fixtures', 'notation-corpus', 'goals');
+  const files = fs.existsSync(EXAMPLES_DIR)
+    ? fs.readdirSync(EXAMPLES_DIR).filter((f) => f.endsWith('.transitrix.yaml'))
+    : [];
+  for (const file of files) {
+    it(`accepts tests/fixtures/notation-corpus/goals/${file}`, () => {
+      const text = fs.readFileSync(path.join(EXAMPLES_DIR, file), 'utf8');
+      const parsedYaml = yaml.load(text);
+      const r = parseCanonicalGoals(parsedYaml);
+      expect(r.errors).toEqual([]);
+      expect(r.valid).toBe(true);
+    });
+  }
+});