@topogram/cli 0.3.34

package/src/generator/runtime/smoke.js

@@ -0,0 +1,219 @@
+import {
+  buildVerificationSummary,
+  getDefaultEnvironmentProjections,
+  resolveRuntimeTopology,
+  runtimeUrls,
+  selectChecksByVerification
+} from "./shared.js";
+import { getExampleImplementation } from "../../example-implementation.js";
+
+function buildRuntimeSmokePlan(graph, options = {}) {
+  const implementation = getExampleImplementation(graph, options);
+  const runtimeReference = implementation.runtime.reference;
+  const runtimeChecks = implementation.runtime.checks;
+  const topology = resolveRuntimeTopology(graph, options);
+  const { apiProjection, uiProjection } = getDefaultEnvironmentProjections(graph, options);
+  const verification = buildVerificationSummary(graph, ["smoke", "journey"]);
+  const smokeSelection = selectChecksByVerification(graph, runtimeChecks.smokeChecks, ["smoke", "journey"], {
+    keepWebChecks: true
+  });
+  return {
+    type: "runtime_smoke_plan",
+    name: runtimeReference.smoke.name,
+    projections: {
+      api: apiProjection.id,
+      ui: uiProjection.id
+    },
+    topology: {
+      components: topology.components.map((component) => ({
+        id: component.id,
+        type: component.type,
+        projection: component.projection.id,
+        generator: component.generator
+      }))
+    },
+    ...(verification ? { verification } : {}),
+    ...(smokeSelection.selection ? { selection: smokeSelection.selection } : {}),
+    env: {
+      apiBase: "TOPOGRAM_API_BASE_URL",
+      webBase: "TOPOGRAM_WEB_BASE_URL"
+    },
+    checks: smokeSelection.checks
+  };
+}
+
+function renderRuntimeSmokeEnvExample(graph, options = {}) {
+  const runtimeReference = getExampleImplementation(graph, options).runtime.reference;
+  const urls = runtimeUrls(runtimeReference, resolveRuntimeTopology(graph, options));
+  return `TOPOGRAM_API_BASE_URL=${urls.api}
+TOPOGRAM_WEB_BASE_URL=${urls.web}
+${runtimeReference.environment.envExample || ""}
+`;
+}
+
+function renderRuntimeSmokeReadme(graph, options = {}) {
+  const runtimeReference = getExampleImplementation(graph, options).runtime.reference;
+  const verification = buildVerificationSummary(graph, ["smoke", "journey"]);
+  const verificationLines = verification
+    ? `\n## Canonical Verification\n\n- Sources: ${verification.sources.map((entry) => `\`${entry.id}\``).join(", ")}\n- Scenarios: ${verification.scenarios.map((entry) => entry.label).join(", ")}\n`
+    : "";
+  return `# ${runtimeReference.smoke.bundleTitle}
+
+This bundle gives you lightweight runtime verification for the generated stack.
+
+Use it when you want a fast, minimal confidence check that the generated stack is basically up and responding.
+
+## Usage
+
+1. Set \`TOPOGRAM_API_BASE_URL\`
+2. Set \`TOPOGRAM_WEB_BASE_URL\`
+3. Run \`bash ./scripts/smoke.sh\`
+
+The smoke test will:
+- confirm the web UI responds on \`${runtimeReference.smoke.webPath}\`
+- assume the generated demo seed data has been applied
+- create a primary resource through the API
+- fetch the created primary resource
+- confirm the list endpoint responds
+
+If you want staged readiness checks, richer API verification, and a machine-readable report, use the runtime-check bundle instead.
+${verificationLines}`;
+}
+
+function renderRuntimeSmokeScript() {
+  return `#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+ENV_FILE="\${TOPOGRAM_ENV_FILE:-$ROOT_DIR/.env}"
+
+if [[ -f "$ENV_FILE" ]]; then
+  set -a
+  . "$ENV_FILE"
+  set +a
+fi
+
+node "$SCRIPT_DIR/smoke.mjs"
+`;
+}
+
+function renderRuntimeSmokeModule(graph, options = {}) {
+  const runtimeReference = getExampleImplementation(graph, options).runtime.reference;
+  const containerField = runtimeReference.smoke.createPayload.containerField;
+  const payloadEntries = [
+    ["title", runtimeReference.smoke.createPayload.title],
+    [containerField, "__DEMO_CONTAINER_ID__"],
+    ...Object.entries(runtimeReference.smoke.createPayload.extraFields || {})
+  ];
+  const payloadLines = payloadEntries.map(([key, value]) => {
+    if (value === "__DEMO_CONTAINER_ID__") {
+      return `    ${key}: demoContainerId`;
+    }
+    if (value === "__DEMO_USER_ID__") {
+      return `    ${key}: demoUserId`;
+    }
+    return `    ${key}: ${JSON.stringify(value)}`;
+  }).join(",\n");
+  return `function reportFatal(error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}
+
+process.on("uncaughtException", reportFatal);
+process.on("unhandledRejection", reportFatal);
+
+const apiBase = process.env.TOPOGRAM_API_BASE_URL || "";
+const webBase = process.env.TOPOGRAM_WEB_BASE_URL || "";
+const demoContainerId = process.env.${runtimeReference.smoke.defaultContainerEnvVar} || "${runtimeReference.demoEnv.containerId}";
+const demoUserId = process.env.TOPOGRAM_DEMO_USER_ID || "${runtimeReference.demoEnv.userId}";
+const authToken = process.env.TOPOGRAM_AUTH_TOKEN || "";
+
+if (!apiBase || !webBase) {
+  throw new Error("TOPOGRAM_API_BASE_URL and TOPOGRAM_WEB_BASE_URL are required");
+}
+
+function stackStartHint() {
+  return "Start the generated stack with 'npm run dev' from the app bundle, or 'npm run app:dev' from the project root, then rerun this command.";
+}
+
+function describeFetchError(error) {
+  if (error?.cause?.code) {
+    return error.cause.code;
+  }
+  if (Array.isArray(error?.cause?.errors) && error.cause.errors.length > 0) {
+    return [...new Set(error.cause.errors.map((entry) => entry.code).filter(Boolean))].join(", ");
+  }
+  return error instanceof Error ? error.message : String(error);
+}
+
+async function fetchWithStackHint(url, init, label) {
+  try {
+    return await fetch(url, init);
+  } catch (error) {
+    throw new Error(\`\${label} is not reachable at \${url.toString()}. \${stackStartHint()} Original error: \${describeFetchError(error)}\`);
+  }
+}
+
+async function expectStatus(response, expected, label) {
+  if (response.status !== expected) {
+    const body = await response.text();
+    throw new Error(\`\${label} expected \${expected}, got \${response.status}: \${body}\`);
+  }
+}
+
+const webResponse = await fetchWithStackHint(new URL("${runtimeReference.smoke.webPath}", webBase), undefined, "web app");
+await expectStatus(webResponse, 200, "web page");
+const webText = await webResponse.text();
+if (!webText.includes("${runtimeReference.smoke.expectText}")) {
+  throw new Error("web page did not include expected page text");
+}
+
+const createResponse = await fetchWithStackHint(new URL("${runtimeReference.smoke.createPath}", apiBase), {
+  method: "POST",
+  headers: {
+    "content-type": "application/json",
+    "Idempotency-Key": crypto.randomUUID(),
+    ...(authToken ? { Authorization: \`Bearer \${authToken}\` } : {})
+  },
+  body: JSON.stringify({
+${payloadLines}
+  })
+}, "api service");
+await expectStatus(createResponse, 201, "create resource");
+const created = await createResponse.json();
+if (!created.id) {
+  throw new Error("create resource response did not include id");
+}
+
+const getResponse = await fetchWithStackHint(new URL(\`${runtimeReference.smoke.getPathPrefix}\${created.id}\`, apiBase), {
+  headers: authToken ? { Authorization: \`Bearer \${authToken}\` } : undefined
+}, "api service");
+await expectStatus(getResponse, 200, "get resource");
+
+const listResponse = await fetchWithStackHint(new URL("${runtimeReference.smoke.listPath}", apiBase), {
+  headers: authToken ? { Authorization: \`Bearer \${authToken}\` } : undefined
+}, "api service");
+await expectStatus(listResponse, 200, "list resources");
+
+console.log(JSON.stringify({
+  ok: true,
+  createdPrimaryId: created.id
+}, null, 2));
+`;
+}
+
+export function generateRuntimeSmokeBundle(graph, options = {}) {
+  const plan = buildRuntimeSmokePlan(graph, options);
+  return {
+    ".env.example": renderRuntimeSmokeEnvExample(graph, options),
+    "README.md": renderRuntimeSmokeReadme(graph, options),
+    "runtime-smoke-plan.json": `${JSON.stringify(plan, null, 2)}\n`,
+    "scripts/smoke.sh": renderRuntimeSmokeScript(),
+    "scripts/smoke.mjs": renderRuntimeSmokeModule(graph, options)
+  };
+}
+
+export function generateRuntimeSmokePlan(graph, options = {}) {
+  return buildRuntimeSmokePlan(graph, options);
+}

package/src/generator/schema.js

@@ -0,0 +1,204 @@
+import { fieldSignature, symbolList } from "./shared.js";
+
+const JSON_SCHEMA_DRAFT = "https://json-schema.org/draft/2020-12/schema";
+
+function indexStatements(graph) {
+  const byId = new Map();
+  for (const statement of graph.statements) {
+    byId.set(statement.id, statement);
+  }
+  return byId;
+}
+
+function scalarSchema(typeName, byId) {
+  switch (typeName) {
+    case "string":
+    case "text":
+      return { type: "string" };
+    case "integer":
+      return { type: "integer" };
+    case "number":
+      return { type: "number" };
+    case "boolean":
+      return { type: "boolean" };
+    case "datetime":
+      return { type: "string", format: "date-time" };
+    case "uuid":
+      return { type: "string", format: "uuid" };
+    default: {
+      const target = byId.get(typeName);
+      if (target?.kind === "enum") {
+        return { type: "string", enum: target.values };
+      }
+      return { type: "string", "x-topogram-type": typeName };
+    }
+  }
+}
+
+function coerceDefaultValue(value, schema) {
+  if (value == null) {
+    return undefined;
+  }
+
+  if (schema.type === "integer") {
+    const parsed = Number.parseInt(value, 10);
+    return Number.isNaN(parsed) ? value : parsed;
+  }
+
+  if (schema.type === "number") {
+    const parsed = Number.parseFloat(value);
+    return Number.isNaN(parsed) ? value : parsed;
+  }
+
+  if (schema.type === "boolean") {
+    if (value === "true") {
+      return true;
+    }
+    if (value === "false") {
+      return false;
+    }
+  }
+
+  return value;
+}
+
+function schemaForField(field, byId) {
+  const schema = scalarSchema(field.fieldType, byId);
+  const defaultValue = coerceDefaultValue(field.defaultValue, schema);
+  return defaultValue === undefined ? schema : { ...schema, default: defaultValue };
+}
+
+function generateShapeJsonSchema(shape, byId) {
+  const fields = shape.projectedFields || shape.fields || [];
+  const properties = {};
+  const required = [];
+
+  for (const field of fields) {
+    properties[field.name] = schemaForField(field, byId);
+    if (field.requiredness === "required") {
+      required.push(field.name);
+    }
+  }
+
+  const schema = {
+    $schema: JSON_SCHEMA_DRAFT,
+    $id: `topogram:shape:${shape.id}`,
+    title: shape.name || shape.id,
+    description: shape.description || undefined,
+    type: "object",
+    properties,
+    additionalProperties: false
+  };
+
+  if (required.length > 0) {
+    schema.required = required;
+  }
+
+  return schema;
+}
+
+function getShape(graph, shapeId) {
+  const byId = indexStatements(graph);
+  const shape = byId.get(shapeId);
+  if (!shape || shape.kind !== "shape") {
+    throw new Error(`No shape found with id '${shapeId}'`);
+  }
+  return shape;
+}
+
+export function generateJsonSchema(graph, options = {}) {
+  const byId = indexStatements(graph);
+  const shapes = graph.byKind.shape || [];
+
+  if (options.shapeId) {
+    return generateShapeJsonSchema(getShape(graph, options.shapeId), byId);
+  }
+
+  const output = {};
+  for (const shape of shapes) {
+    output[shape.id] = generateShapeJsonSchema(shape, byId);
+  }
+
+  return output;
+}
+
+export function generateShapeTransformGraph(graph, options = {}) {
+  const shapes = graph.byKind.shape || [];
+
+  if (options.shapeId) {
+    return getShape(graph, options.shapeId).transformGraph;
+  }
+
+  const output = {};
+  for (const shape of shapes) {
+    output[shape.id] = shape.transformGraph;
+  }
+  return output;
+}
+
+export function generateShapeTransformDebug(graph, options = {}) {
+  const shapes = options.shapeId ? [getShape(graph, options.shapeId)] : graph.byKind.shape || [];
+  const lines = [];
+
+  lines.push("# Shape Transform Debug");
+  lines.push("");
+  lines.push(`Generated from \`${graph.root}\``);
+  lines.push("");
+
+  for (const shape of shapes) {
+    lines.push(`## \`${shape.id}\` - ${shape.name || shape.id}`);
+    lines.push("");
+    if (shape.description) {
+      lines.push(shape.description);
+      lines.push("");
+    }
+
+    lines.push(`Selection mode: \`${shape.transformGraph.selection.mode}\``);
+    if (shape.transformGraph.selection.source?.id) {
+      lines.push(`Source: \`${shape.transformGraph.selection.source.id}\``);
+    }
+    lines.push(`Include: ${symbolList(shape.include)}`);
+    lines.push(`Exclude: ${symbolList(shape.exclude)}`);
+    lines.push("");
+
+    lines.push("Selected fields:");
+    for (const field of shape.transformGraph.selection.selectedFields) {
+      lines.push(`- ${fieldSignature(field)}`);
+    }
+    lines.push("");
+
+    lines.push("Transforms:");
+    if (shape.transformGraph.transforms.length === 0) {
+      lines.push("- _none_");
+    } else {
+      for (const transform of shape.transformGraph.transforms) {
+        if (transform.type === "rename_field") {
+          lines.push(`- rename \`${transform.from}\` -> \`${transform.to}\``);
+          continue;
+        }
+        if (transform.type === "override_field") {
+          const changes = [];
+          if (transform.changes.requiredness) {
+            changes.push(transform.changes.requiredness);
+          }
+          if (transform.changes.fieldType) {
+            changes.push(`type \`${transform.changes.fieldType}\``);
+          }
+          if (transform.changes.defaultValue != null) {
+            changes.push(`default \`${transform.changes.defaultValue}\``);
+          }
+          lines.push(`- override \`${transform.field}\`: ${changes.join(", ")}`);
+        }
+      }
+    }
+    lines.push("");
+
+    lines.push("Result fields:");
+    for (const field of shape.transformGraph.resultFields) {
+      lines.push(`- ${fieldSignature(field)}`);
+    }
+    lines.push("");
+  }
+
+  return `${lines.join("\n").trimEnd()}\n`;
+}

package/src/generator/sdlc/board.js

@@ -0,0 +1,66 @@
+// Kanban-style status board for SDLC artifacts.
+//
+// Output shape: rows = status columns, columns = artifact summaries.
+// Filter to a single kind via `--kind pitch|task|bug`. Default lists all
+// SDLC kinds in parallel. Archived entries are hidden by default (callers
+// pass `includeArchived: true` to surface them).
+
+import {
+  summarizeBug,
+  summarizePitch,
+  summarizeRequirement,
+  summarizeTask
+} from "../context/shared.js";
+import {
+  defaultActiveStatuses,
+  filterStatements
+} from "../../sdlc/status-filter.js";
+
+const SUMMARIZERS = {
+  pitch: summarizePitch,
+  requirement: summarizeRequirement,
+  task: summarizeTask,
+  bug: summarizeBug
+};
+
+const SUPPORTED_KINDS = Object.keys(SUMMARIZERS);
+
+function buildLanesForKind(graph, kind, options) {
+  const all = graph.byKind?.[kind] || [];
+  const visible = filterStatements(all, options);
+  const lanes = {};
+  const statuses = defaultActiveStatuses(kind);
+  if (statuses) {
+    for (const status of statuses) {
+      lanes[status] = [];
+    }
+  }
+  const summarize = SUMMARIZERS[kind];
+  for (const item of visible) {
+    if (!lanes[item.status]) lanes[item.status] = [];
+    lanes[item.status].push(summarize(item));
+  }
+  return lanes;
+}
+
+export function generateSdlcBoard(graph, options = {}) {
+  const wantedKinds = options.kind ? [options.kind] : SUPPORTED_KINDS;
+  const board = {};
+  const counts = {};
+  for (const kind of wantedKinds) {
+    if (!SUMMARIZERS[kind]) {
+      throw new Error(`Unsupported board kind '${kind}' (allowed: ${SUPPORTED_KINDS.join(", ")})`);
+    }
+    board[kind] = buildLanesForKind(graph, kind, options);
+    counts[kind] = Object.fromEntries(
+      Object.entries(board[kind]).map(([status, items]) => [status, items.length])
+    );
+  }
+  return {
+    type: "sdlc_board",
+    version: 1,
+    kinds: wantedKinds,
+    counts,
+    board
+  };
+}

package/src/generator/sdlc/doc-page.js

@@ -0,0 +1,53 @@
+// Render a single document as a published-page markdown artifact with a
+// cross-reference sidebar (related entities, capabilities, projections,
+// rules pulled from the doc's frontmatter back-links).
+
+import { documentById } from "../context/shared.js";
+
+function bulletList(label, ids) {
+  if (!ids || ids.length === 0) return "";
+  const sorted = [...ids].sort();
+  const items = sorted.map((id) => `- \`${id}\``).join("\n");
+  return `### ${label}\n${items}\n\n`;
+}
+
+export function generateSdlcDocPage(graph, options = {}) {
+  if (!options.documentId) {
+    throw new Error("sdlc-doc-page requires --document <id>");
+  }
+  const doc = documentById(graph, options.documentId);
+  if (!doc) {
+    throw new Error(`No document found with id '${options.documentId}'`);
+  }
+
+  const headerLines = [
+    `# ${doc.title || doc.id}`,
+    "",
+    `**Status:** ${doc.status || "draft"}  `,
+    doc.kind ? `**Kind:** ${doc.kind}  ` : null,
+    doc.summary ? `**Summary:** ${doc.summary}  ` : null,
+    doc.domain ? `**Domain:** \`${doc.domain}\`  ` : null,
+    "",
+    "---",
+    ""
+  ].filter((l) => l !== null);
+
+  let sidebar = "";
+  sidebar += bulletList("Related entities", doc.relatedEntities);
+  sidebar += bulletList("Related capabilities", doc.relatedCapabilities);
+  sidebar += bulletList("Related projections", doc.relatedProjections);
+  sidebar += bulletList("Related rules", doc.relatedRules);
+  sidebar += bulletList("Related actors", doc.relatedActors);
+  sidebar += bulletList("Related roles", doc.relatedRoles);
+
+  const body = doc.body || "";
+  const markdown = headerLines.join("\n") + body + (sidebar ? "\n\n## Cross-references\n\n" + sidebar : "");
+
+  return {
+    type: "sdlc_doc_page",
+    version: 1,
+    document_id: doc.id,
+    output_path: `topogram/docs-generated/sdlc/${doc.id}.md`,
+    markdown
+  };
+}

package/src/generator/sdlc/index.js

@@ -0,0 +1,23 @@
+// Dispatch for SDLC generator targets.
+
+import { generateSdlcBoard } from "./board.js";
+import { generateSdlcDocPage } from "./doc-page.js";
+import { generateSdlcReleaseNotes } from "./release-notes.js";
+import { generateSdlcTraceabilityMatrix } from "./traceability-matrix.js";
+
+export function generateSdlcTarget(target, graph, options = {}) {
+  switch (target) {
+    case "sdlc-board":
+      return generateSdlcBoard(graph, options);
+    case "sdlc-doc-page":
+      return generateSdlcDocPage(graph, options);
+    case "sdlc-release-notes":
+      return generateSdlcReleaseNotes(graph, options);
+    case "sdlc-traceability-matrix":
+      return generateSdlcTraceabilityMatrix(graph, options);
+    default:
+      throw new Error(`Unsupported SDLC target '${target}'`);
+  }
+}
+
+export { generateSdlcBoard, generateSdlcDocPage, generateSdlcReleaseNotes, generateSdlcTraceabilityMatrix };

package/src/generator/sdlc/release-notes.js

@@ -0,0 +1,62 @@
+// Release notes generator.
+//
+// Assembles the changes that landed in a release window from:
+//   - Approved pitches whose `affects` was touched
+//   - Tasks in `done` status (or archived in this window)
+//   - Bugs in `verified` or `wont-fix` (or archived in this window)
+//
+// Inputs:
+//   options.appVersion   — required; release version label
+//   options.sinceTag     — optional; ISO date or git-tag-like marker for window start
+//   options.includeArchived — optional; default true (release notes need archived data)
+//
+// Output: structured JSON the caller can render to markdown or a board.
+
+function withinWindow(updated, sinceIso) {
+  if (!sinceIso) return true;
+  if (!updated) return false;
+  return updated >= sinceIso;
+}
+
+function summarizeMinimal(s) {
+  return {
+    id: s.id,
+    name: s.name,
+    status: s.status,
+    priority: s.priority || null,
+    severity: s.severity || null,
+    domain: s.resolvedDomain ? s.resolvedDomain.id : null,
+    updated: s.updated || null,
+    archived: !!s.archived
+  };
+}
+
+export function generateSdlcReleaseNotes(graph, options = {}) {
+  if (!options.appVersion) {
+    throw new Error("sdlc-release-notes requires --app-version <label>");
+  }
+  const sinceIso = options.sinceTag || options.since || null;
+
+  const pitches = (graph.byKind?.pitch || [])
+    .filter((p) => p.status === "approved" && withinWindow(p.updated, sinceIso))
+    .map(summarizeMinimal);
+
+  const tasks = (graph.byKind?.task || [])
+    .filter((t) => (t.status === "done" || t.archived) && withinWindow(t.updated, sinceIso))
+    .map(summarizeMinimal);
+
+  const bugs = (graph.byKind?.bug || [])
+    .filter((b) => (b.status === "verified" || b.status === "wont-fix" || b.archived) && withinWindow(b.updated, sinceIso))
+    .map(summarizeMinimal);
+
+  return {
+    type: "sdlc_release_notes",
+    version: 1,
+    app_version: options.appVersion,
+    since: sinceIso,
+    counts: { pitches: pitches.length, tasks: tasks.length, bugs: bugs.length },
+    pitches,
+    tasks,
+    bugs
+  };
+}

package/src/generator/sdlc/traceability-matrix.js

@@ -0,0 +1,65 @@
+// Pitch → Requirement → AC → (Task | Bug) → Verification table.
+//
+// Each row is one acceptance criterion; columns are the chain anchored on
+// it. This is the canonical "did everything we shipped have a reason and a
+// verification?" report.
+
+export function generateSdlcTraceabilityMatrix(graph, options = {}) {
+  const acs = graph.byKind?.acceptance_criterion || [];
+  const requirementsById = new Map((graph.byKind?.requirement || []).map((r) => [r.id, r]));
+  const pitchesById = new Map((graph.byKind?.pitch || []).map((p) => [p.id, p]));
+  const tasksById = new Map((graph.byKind?.task || []).map((t) => [t.id, t]));
+  const bugsById = new Map((graph.byKind?.bug || []).map((b) => [b.id, b]));
+  const verificationsById = new Map((graph.byKind?.verification || []).map((v) => [v.id, v]));
+
+  const rows = [];
+  for (const ac of acs) {
+    const requirement = ac.requirement?.id ? requirementsById.get(ac.requirement.id) : null;
+    const pitchId = requirement?.pitch?.id || null;
+    const pitch = pitchId ? pitchesById.get(pitchId) : null;
+
+    const taskIds = (ac.tasks || []).slice().sort();
+    const verificationIds = (ac.verifications || []).slice().sort();
+
+    const linkedBugIds = [];
+    for (const bug of bugsById.values()) {
+      const linkedTask = (bug.fixedIn || []).some((ref) => taskIds.includes(typeof ref === "string" ? ref : ref?.id));
+      if (linkedTask) linkedBugIds.push(bug.id);
+    }
+
+    rows.push({
+      pitch: pitch
+        ? { id: pitch.id, status: pitch.status, name: pitch.name }
+        : null,
+      requirement: requirement
+        ? { id: requirement.id, status: requirement.status, name: requirement.name }
+        : null,
+      acceptance_criterion: { id: ac.id, status: ac.status, name: ac.name },
+      tasks: taskIds.map((id) => {
+        const t = tasksById.get(id);
+        return t ? { id, status: t.status, work_type: t.workType } : { id, status: "missing" };
+      }),
+      bugs: linkedBugIds.sort().map((id) => {
+        const b = bugsById.get(id);
+        return { id, status: b?.status, severity: b?.severity };
+      }),
+      verifications: verificationIds.map((id) => {
+        const v = verificationsById.get(id);
+        return v ? { id, method: v.method, status: v.status } : { id, status: "missing" };
+      }),
+      gap: !verificationIds.length || !taskIds.length
+    });
+  }
+
+  rows.sort((a, b) => (a.acceptance_criterion.id || "").localeCompare(b.acceptance_criterion.id || ""));
+
+  return {
+    type: "sdlc_traceability_matrix",
+    version: 1,
+    counts: {
+      rows: rows.length,
+      gaps: rows.filter((r) => r.gap).length
+    },
+    rows
+  };
+}