@neuraloom/contracts 0.0.0-stage → 0.1.22

package/dist/schemas/workflow/code-reality-read-model.schema.js

@@ -0,0 +1,237 @@
+"use strict";
+/**
+ * Code Reality Graph read-model API responses (#1252).
+ * Bounded payloads from knowledge_nodes/knowledge_edges + snapshot artifact.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CodeRealityReadModelResponseSchema = exports.CodeRealityEvidenceReadModelResponseSchema = exports.CodeRealityEvidenceResponseSchema = exports.CodeRealityEvidenceNodeSchema = exports.CodeRealityEvidenceMatchedBySchema = exports.CodeRealityEvidenceOmissionSchema = exports.CodeRealityEvidenceQuerySchema = exports.CODE_REALITY_EVIDENCE_MAX_NODES = exports.CodeRealityStepContextResponseSchema = exports.CodeRealityEdgeSelectionSchema = exports.CodeRealityRegisterResponseSchema = exports.CodeRealityInventoryResponseSchema = exports.CodeRealityOverviewResponseSchema = exports.CodeRealityReadModelBaseSchema = exports.CodeRealityAvailabilitySchema = exports.CodeRealityInventorySliceSchema = exports.CodeRealityRegisterSliceSchema = exports.CodeRealityRegisterItemSchema = exports.CodeRealityEdgeRowSchema = exports.CodeRealityNodeRowSchema = exports.CodeRealityNotApplicableSchema = exports.CodeRealityFreshnessSchema = exports.CodeRealityStepContextStepIdSchema = exports.CodeRealityReadSliceSchema = exports.CODE_REALITY_READ_MODEL_MAX_ROWS = void 0;
+exports.selectBoundedEdges = selectBoundedEdges;
+const zod_1 = require("zod");
+const code_reality_artifacts_schema_1 = require("./code-reality-artifacts.schema");
+exports.CODE_REALITY_READ_MODEL_MAX_ROWS = 200;
+exports.CodeRealityReadSliceSchema = zod_1.z.enum([
+    'overview',
+    'routes',
+    'api',
+    'schema',
+    'ui',
+    'workflow',
+    'governance',
+    'build',
+    'ship',
+    'findings',
+    'duplicates',
+    'orphans',
+    'split-brain',
+    'performance',
+    'security',
+]);
+exports.CodeRealityStepContextStepIdSchema = zod_1.z.enum([
+    'specify',
+    'plan',
+    'schema',
+    'api',
+    'ui',
+    'constitution',
+    'tasks',
+    'implement',
+    'ci',
+    'deploy',
+    'review',
+    'knowledge',
+]);
+exports.CodeRealityFreshnessSchema = zod_1.z.object({
+    commitSha: zod_1.z.string().nullable(),
+    scannedAt: zod_1.z.string().nullable(),
+    snapshotArtifactId: zod_1.z.string().uuid().nullable(),
+    snapshotGeneratedAt: zod_1.z.string().datetime().nullable(),
+    /**
+     * Commit the persisted graph rows are bound to (knowledge_nodes.data.scan_commit_sha).
+     * null when rows carry no binding; compare with `commitSha` to detect a graph that
+     * does not correspond to the advertised snapshot revision.
+     */
+    graphCommitSha: zod_1.z.string().nullable().optional(),
+    /** true when graphCommitSha === commitSha; false on mismatch; null when unknown. */
+    revisionConsistent: zod_1.z.boolean().nullable().optional(),
+});
+exports.CodeRealityNotApplicableSchema = zod_1.z.object({
+    applicable: zod_1.z.literal(false),
+    reason: zod_1.z.literal('build-new'),
+});
+exports.CodeRealityNodeRowSchema = zod_1.z.object({
+    id: zod_1.z.string().uuid(),
+    stableKey: zod_1.z.string().nullable(),
+    ontologyType: code_reality_artifacts_schema_1.CodeRealityOntologyTypeSchema,
+    label: zod_1.z.string(),
+    path: zod_1.z.string().nullable(),
+    evidenceRefs: zod_1.z.array(zod_1.z.string()),
+});
+exports.CodeRealityEdgeRowSchema = zod_1.z.object({
+    id: zod_1.z.string().uuid(),
+    sourceId: zod_1.z.string().uuid(),
+    targetId: zod_1.z.string().uuid(),
+    relation: zod_1.z.string(),
+});
+exports.CodeRealityRegisterItemSchema = zod_1.z.object({
+    key: zod_1.z.string(),
+    label: zod_1.z.string(),
+});
+exports.CodeRealityRegisterSliceSchema = zod_1.z.object({
+    totalCount: zod_1.z.number().int().min(0),
+    items: zod_1.z.array(exports.CodeRealityRegisterItemSchema).max(exports.CODE_REALITY_READ_MODEL_MAX_ROWS),
+    truncated: zod_1.z.boolean(),
+});
+exports.CodeRealityInventorySliceSchema = zod_1.z.object({
+    totalCount: zod_1.z.number().int().min(0),
+    nodes: zod_1.z.array(exports.CodeRealityNodeRowSchema).max(exports.CODE_REALITY_READ_MODEL_MAX_ROWS),
+    truncated: zod_1.z.boolean(),
+});
+exports.CodeRealityAvailabilitySchema = zod_1.z.object({
+    applicable: zod_1.z.boolean(),
+    reason: zod_1.z.string().optional(),
+    snapshotArtifactId: zod_1.z.string().uuid().nullable(),
+    totalNodes: zod_1.z.number().int().min(0).optional(),
+    commitSha: zod_1.z.string().nullable().optional(),
+    scannedAt: zod_1.z.string().nullable().optional(),
+    missingEvidenceWarnings: zod_1.z.array(zod_1.z.string()),
+    /**
+     * False when the AST/content index is missing, capped (legacy 80-file), or incomplete.
+     * Tree `lastScannedAt` alone must not be treated as mapped.
+     */
+    semanticMapped: zod_1.z.boolean().optional(),
+    /** Snapshot inventory counts for per-step slice gates (#1254). */
+    sliceInventoryCounts: zod_1.z
+        .object({
+        schema: zod_1.z.number().int().min(0).optional(),
+        api: zod_1.z.number().int().min(0).optional(),
+        ui: zod_1.z.number().int().min(0).optional(),
+        governance: zod_1.z.number().int().min(0).optional(),
+    })
+        .optional(),
+});
+exports.CodeRealityReadModelBaseSchema = zod_1.z.object({
+    applicable: zod_1.z.literal(true),
+    projectId: zod_1.z.string().uuid(),
+    slice: exports.CodeRealityReadSliceSchema,
+    freshness: exports.CodeRealityFreshnessSchema,
+    missingEvidenceWarnings: zod_1.z.array(zod_1.z.string()),
+    snapshot: code_reality_artifacts_schema_1.CodeRealityGraphSnapshotPayloadSchema.nullable(),
+});
+exports.CodeRealityOverviewResponseSchema = exports.CodeRealityReadModelBaseSchema.extend({
+    slice: zod_1.z.literal('overview'),
+    totalNodes: zod_1.z.number().int().min(0),
+    totalEdges: zod_1.z.number().int().min(0),
+    nodeCountByType: zod_1.z.record(zod_1.z.string(), zod_1.z.number().int().min(0)),
+    edgeCountByRelation: zod_1.z.record(zod_1.z.string(), zod_1.z.number().int().min(0)),
+    astExtracted: zod_1.z.boolean(),
+});
+exports.CodeRealityInventoryResponseSchema = exports.CodeRealityReadModelBaseSchema.extend({
+    inventory: exports.CodeRealityInventorySliceSchema,
+    edges: zod_1.z.array(exports.CodeRealityEdgeRowSchema).max(exports.CODE_REALITY_READ_MODEL_MAX_ROWS),
+});
+exports.CodeRealityRegisterResponseSchema = exports.CodeRealityReadModelBaseSchema.extend({
+    register: exports.CodeRealityRegisterSliceSchema,
+});
+// ─── Bounded edge selection (single canonical algorithm; used by step context) ─
+exports.CodeRealityEdgeSelectionSchema = zod_1.z.object({
+    edges: zod_1.z.array(exports.CodeRealityEdgeRowSchema).max(exports.CODE_REALITY_READ_MODEL_MAX_ROWS),
+    totalCount: zod_1.z.number().int().min(0),
+    omittedCount: zod_1.z.number().int().min(0),
+    truncated: zod_1.z.boolean(),
+    continuationOffset: zod_1.z.number().int().min(0).nullable(),
+});
+function scoreEdgeForFocus(edge, focusNodeIds) {
+    return (focusNodeIds.has(edge.sourceId) ? 1 : 0) + (focusNodeIds.has(edge.targetId) ? 1 : 0);
+}
+/**
+ * Rank edges by how many endpoints sit in the focus set, then slice to `limit`.
+ * Deterministic (stable sort on score, then id) and never silent about truncation.
+ */
+function selectBoundedEdges(edges, focusNodeIds, limit) {
+    const ranked = [...edges].sort((left, right) => {
+        const delta = scoreEdgeForFocus(right, focusNodeIds) - scoreEdgeForFocus(left, focusNodeIds);
+        return delta !== 0 ? delta : left.id.localeCompare(right.id);
+    });
+    const selected = ranked.slice(0, Math.max(0, limit));
+    const omittedCount = Math.max(0, ranked.length - selected.length);
+    return {
+        edges: selected,
+        totalCount: ranked.length,
+        omittedCount,
+        truncated: omittedCount > 0,
+        continuationOffset: omittedCount > 0 ? selected.length : null,
+    };
+}
+exports.CodeRealityStepContextResponseSchema = zod_1.z.object({
+    applicable: zod_1.z.literal(true),
+    projectId: zod_1.z.string().uuid(),
+    step: exports.CodeRealityStepContextStepIdSchema,
+    slices: zod_1.z.array(exports.CodeRealityReadSliceSchema),
+    freshness: exports.CodeRealityFreshnessSchema,
+    missingEvidenceWarnings: zod_1.z.array(zod_1.z.string()),
+    snapshot: code_reality_artifacts_schema_1.CodeRealityGraphSnapshotPayloadSchema.nullable(),
+    inventories: zod_1.z.record(exports.CodeRealityReadSliceSchema, exports.CodeRealityInventorySliceSchema).optional(),
+    registers: zod_1.z.record(exports.CodeRealityReadSliceSchema, exports.CodeRealityRegisterSliceSchema).optional(),
+    /**
+     * Bounded relationships among inventory nodes (who calls what, who consumes
+     * which contract) with explicit omission counts and a continuation offset.
+     */
+    edgeSelection: exports.CodeRealityEdgeSelectionSchema.optional(),
+    overview: exports.CodeRealityOverviewResponseSchema.omit({
+        applicable: true,
+        projectId: true,
+        slice: true,
+        freshness: true,
+        missingEvidenceWarnings: true,
+        snapshot: true,
+    }).optional(),
+});
+// ─── Task-targeted evidence (exact selection + relationship traversal) ─────────
+exports.CODE_REALITY_EVIDENCE_MAX_NODES = 60;
+exports.CodeRealityEvidenceQuerySchema = zod_1.z.object({
+    /** Exact symbol/label/stable-key terms (case-insensitive exact match, not keyword). */
+    terms: zod_1.z.array(zod_1.z.string().min(1)).max(50).default([]),
+    /** Repo-relative file paths or path prefixes. */
+    paths: zod_1.z.array(zod_1.z.string().min(1)).max(50).default([]),
+    maxNodes: zod_1.z
+        .number()
+        .int()
+        .min(1)
+        .max(exports.CODE_REALITY_READ_MODEL_MAX_ROWS)
+        .default(exports.CODE_REALITY_EVIDENCE_MAX_NODES),
+    /** 0 = matched nodes only; 1 = include direct neighbours through knowledge_edges. */
+    hops: zod_1.z.union([zod_1.z.literal(0), zod_1.z.literal(1)]).default(1),
+    continuationToken: zod_1.z.string().nullable().default(null),
+});
+exports.CodeRealityEvidenceOmissionSchema = zod_1.z.object({
+    totalCount: zod_1.z.number().int().min(0),
+    omittedCount: zod_1.z.number().int().min(0),
+    continuationToken: zod_1.z.string().nullable(),
+});
+exports.CodeRealityEvidenceMatchedBySchema = zod_1.z.enum(['path', 'label', 'stable_key', 'neighbour']);
+exports.CodeRealityEvidenceNodeSchema = exports.CodeRealityNodeRowSchema.extend({
+    matchedBy: exports.CodeRealityEvidenceMatchedBySchema,
+});
+exports.CodeRealityEvidenceResponseSchema = zod_1.z.object({
+    applicable: zod_1.z.literal(true),
+    projectId: zod_1.z.string().uuid(),
+    freshness: exports.CodeRealityFreshnessSchema,
+    nodes: zod_1.z.array(exports.CodeRealityEvidenceNodeSchema).max(exports.CODE_REALITY_READ_MODEL_MAX_ROWS),
+    edges: zod_1.z.array(exports.CodeRealityEdgeRowSchema).max(exports.CODE_REALITY_READ_MODEL_MAX_ROWS),
+    omitted: zod_1.z.object({
+        nodes: exports.CodeRealityEvidenceOmissionSchema,
+        edges: exports.CodeRealityEvidenceOmissionSchema,
+    }),
+    missingEvidenceWarnings: zod_1.z.array(zod_1.z.string()),
+});
+exports.CodeRealityEvidenceReadModelResponseSchema = zod_1.z.union([
+    exports.CodeRealityNotApplicableSchema,
+    exports.CodeRealityEvidenceResponseSchema,
+]);
+exports.CodeRealityReadModelResponseSchema = zod_1.z.union([
+    exports.CodeRealityNotApplicableSchema,
+    exports.CodeRealityOverviewResponseSchema,
+    exports.CodeRealityInventoryResponseSchema,
+    exports.CodeRealityRegisterResponseSchema,
+    exports.CodeRealityStepContextResponseSchema,
+]);

package/dist/schemas/workflow/code-reality-task-traceability.schema.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Code-reality task traceability — tasks generated from Plan + findings register (#1255).
+ * Persisted on public.tasks columns + task graph artifact payload.
+ */
+import { z } from 'zod';
+export declare const CodeRealityTaskRiskLevelSchema: z.ZodEnum<["low", "medium", "high", "critical"]>;
+export type CodeRealityTaskRiskLevel = z.infer<typeof CodeRealityTaskRiskLevelSchema>;
+export declare const CodeRealityTaskPrGroupingSchema: z.ZodEnum<["solo", "cohort", "infra", "api", "ui", "schema"]>;
+export type CodeRealityTaskPrGrouping = z.infer<typeof CodeRealityTaskPrGroupingSchema>;
+export declare const CodeRealityAffectedComponentSchema: z.ZodObject<{
+    stableKey: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    ontologyType: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    stableKey: string;
+    label?: string | undefined;
+    ontologyType?: string | undefined;
+}, {
+    stableKey: string;
+    label?: string | undefined;
+    ontologyType?: string | undefined;
+}>;
+export type CodeRealityAffectedComponent = z.infer<typeof CodeRealityAffectedComponentSchema>;
+export declare const CodeRealityTaskTraceabilitySchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<"1.0.0">;
+    sourceFindingIds: z.ZodArray<z.ZodString, "many">;
+    affectedNodeIds: z.ZodArray<z.ZodString, "many">;
+    affectedFiles: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    affectedRoutes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    affectedApis: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    affectedTables: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    affectedComponents: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        stableKey: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        ontologyType: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        stableKey: string;
+        label?: string | undefined;
+        ontologyType?: string | undefined;
+    }, {
+        stableKey: string;
+        label?: string | undefined;
+        ontologyType?: string | undefined;
+    }>, "many">>;
+    acceptanceCriteria: z.ZodArray<z.ZodString, "many">;
+    testEvidenceRequirement: z.ZodArray<z.ZodString, "many">;
+    prGrouping: z.ZodEnum<["solo", "cohort", "infra", "api", "ui", "schema"]>;
+    riskLevel: z.ZodEnum<["low", "medium", "high", "critical"]>;
+    planArtifactId: z.ZodOptional<z.ZodString>;
+    findingsRegisterArtifactId: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    schemaVersion: "1.0.0";
+    sourceFindingIds: string[];
+    acceptanceCriteria: string[];
+    affectedNodeIds: string[];
+    affectedFiles: string[];
+    affectedRoutes: string[];
+    affectedApis: string[];
+    affectedTables: string[];
+    affectedComponents: {
+        stableKey: string;
+        label?: string | undefined;
+        ontologyType?: string | undefined;
+    }[];
+    riskLevel: "critical" | "low" | "medium" | "high";
+    testEvidenceRequirement: string[];
+    prGrouping: "schema" | "api" | "ui" | "infra" | "solo" | "cohort";
+    planArtifactId?: string | undefined;
+    findingsRegisterArtifactId?: string | undefined;
+}, {
+    schemaVersion: "1.0.0";
+    sourceFindingIds: string[];
+    acceptanceCriteria: string[];
+    affectedNodeIds: string[];
+    riskLevel: "critical" | "low" | "medium" | "high";
+    testEvidenceRequirement: string[];
+    prGrouping: "schema" | "api" | "ui" | "infra" | "solo" | "cohort";
+    planArtifactId?: string | undefined;
+    affectedFiles?: string[] | undefined;
+    affectedRoutes?: string[] | undefined;
+    affectedApis?: string[] | undefined;
+    affectedTables?: string[] | undefined;
+    affectedComponents?: {
+        stableKey: string;
+        label?: string | undefined;
+        ontologyType?: string | undefined;
+    }[] | undefined;
+    findingsRegisterArtifactId?: string | undefined;
+}>;
+export type CodeRealityTaskTraceability = z.infer<typeof CodeRealityTaskTraceabilitySchema>;
+/** Prefixes for encoding traceability ids in tasks.requirement_ids (no new DB column). */
+export declare const CODE_REALITY_FINDING_REQ_PREFIX: "cr-finding:";
+export declare const CODE_REALITY_NODE_REQ_PREFIX: "cr-node:";
+export declare const CODE_REALITY_PR_GROUP_TAG_PREFIX: "neuraloom:pr-group:";
+export declare function encodeFindingIdsForRequirementIds(findingIds: readonly string[]): string[];
+export declare function encodeNodeIdsForRequirementIds(nodeIds: readonly string[]): string[];
+export declare function decodeCodeRealityRequirementIds(requirementIds: readonly string[] | null | undefined): {
+    sourceFindingIds: string[];
+    affectedNodeIds: string[];
+};
+export declare function traceabilityToTaskEvidenceColumns(trace: CodeRealityTaskTraceability): {
+    requirement_ids: string[];
+    expected_files: Array<{
+        path: string;
+        required: boolean;
+    }>;
+    expected_routes: Array<{
+        method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+        path: string;
+        required: boolean;
+    }>;
+    expected_tables: Array<{
+        name: string;
+        required: boolean;
+    }>;
+    expected_tests: Array<{
+        path: string;
+        required: boolean;
+    }>;
+    acceptance_criteria: string[];
+    tags: string[];
+    complexity: string | null;
+    source_artifact_ids: string[];
+};

package/dist/schemas/workflow/code-reality-task-traceability.schema.js

@@ -0,0 +1,107 @@
+"use strict";
+/**
+ * Code-reality task traceability — tasks generated from Plan + findings register (#1255).
+ * Persisted on public.tasks columns + task graph artifact payload.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CODE_REALITY_PR_GROUP_TAG_PREFIX = exports.CODE_REALITY_NODE_REQ_PREFIX = exports.CODE_REALITY_FINDING_REQ_PREFIX = exports.CodeRealityTaskTraceabilitySchema = exports.CodeRealityAffectedComponentSchema = exports.CodeRealityTaskPrGroupingSchema = exports.CodeRealityTaskRiskLevelSchema = void 0;
+exports.encodeFindingIdsForRequirementIds = encodeFindingIdsForRequirementIds;
+exports.encodeNodeIdsForRequirementIds = encodeNodeIdsForRequirementIds;
+exports.decodeCodeRealityRequirementIds = decodeCodeRealityRequirementIds;
+exports.traceabilityToTaskEvidenceColumns = traceabilityToTaskEvidenceColumns;
+const zod_1 = require("zod");
+exports.CodeRealityTaskRiskLevelSchema = zod_1.z.enum(['low', 'medium', 'high', 'critical']);
+exports.CodeRealityTaskPrGroupingSchema = zod_1.z.enum([
+    'solo',
+    'cohort',
+    'infra',
+    'api',
+    'ui',
+    'schema',
+]);
+exports.CodeRealityAffectedComponentSchema = zod_1.z.object({
+    stableKey: zod_1.z.string().min(1),
+    label: zod_1.z.string().min(1).optional(),
+    ontologyType: zod_1.z.string().min(1).optional(),
+});
+exports.CodeRealityTaskTraceabilitySchema = zod_1.z
+    .object({
+    schemaVersion: zod_1.z.literal('1.0.0'),
+    sourceFindingIds: zod_1.z.array(zod_1.z.string().min(1)).min(1),
+    affectedNodeIds: zod_1.z.array(zod_1.z.string().min(1)).min(1),
+    affectedFiles: zod_1.z.array(zod_1.z.string().min(1)).default([]),
+    affectedRoutes: zod_1.z.array(zod_1.z.string().min(1)).default([]),
+    affectedApis: zod_1.z.array(zod_1.z.string().min(1)).default([]),
+    affectedTables: zod_1.z.array(zod_1.z.string().min(1)).default([]),
+    affectedComponents: zod_1.z.array(exports.CodeRealityAffectedComponentSchema).default([]),
+    acceptanceCriteria: zod_1.z.array(zod_1.z.string().min(1)).min(1),
+    testEvidenceRequirement: zod_1.z.array(zod_1.z.string().min(1)).min(1),
+    prGrouping: exports.CodeRealityTaskPrGroupingSchema,
+    riskLevel: exports.CodeRealityTaskRiskLevelSchema,
+    planArtifactId: zod_1.z.string().uuid().optional(),
+    findingsRegisterArtifactId: zod_1.z.string().uuid().optional(),
+})
+    .strict();
+/** Prefixes for encoding traceability ids in tasks.requirement_ids (no new DB column). */
+exports.CODE_REALITY_FINDING_REQ_PREFIX = 'cr-finding:';
+exports.CODE_REALITY_NODE_REQ_PREFIX = 'cr-node:';
+exports.CODE_REALITY_PR_GROUP_TAG_PREFIX = 'neuraloom:pr-group:';
+function encodeFindingIdsForRequirementIds(findingIds) {
+    return findingIds.map((id) => `${exports.CODE_REALITY_FINDING_REQ_PREFIX}${id}`);
+}
+function encodeNodeIdsForRequirementIds(nodeIds) {
+    return nodeIds.map((id) => `${exports.CODE_REALITY_NODE_REQ_PREFIX}${id}`);
+}
+function decodeCodeRealityRequirementIds(requirementIds) {
+    const finding = [];
+    const nodes = [];
+    for (const raw of requirementIds ?? []) {
+        if (raw.startsWith(exports.CODE_REALITY_FINDING_REQ_PREFIX)) {
+            finding.push(raw.slice(exports.CODE_REALITY_FINDING_REQ_PREFIX.length));
+        }
+        else if (raw.startsWith(exports.CODE_REALITY_NODE_REQ_PREFIX)) {
+            nodes.push(raw.slice(exports.CODE_REALITY_NODE_REQ_PREFIX.length));
+        }
+    }
+    return { sourceFindingIds: finding, affectedNodeIds: nodes };
+}
+function parseRouteExpectation(raw) {
+    const match = /^(GET|POST|PUT|PATCH|DELETE)\s+(.+)$/i.exec(raw.trim());
+    const methodRaw = match?.[1];
+    const pathRaw = match?.[2];
+    if (methodRaw !== undefined && pathRaw !== undefined) {
+        return {
+            method: methodRaw.toUpperCase(),
+            path: pathRaw,
+            required: true,
+        };
+    }
+    return { method: 'GET', path: raw.trim(), required: true };
+}
+function traceabilityToTaskEvidenceColumns(trace) {
+    const requirement_ids = [
+        ...encodeFindingIdsForRequirementIds(trace.sourceFindingIds),
+        ...encodeNodeIdsForRequirementIds(trace.affectedNodeIds),
+    ];
+    const artifactIds = [];
+    if (trace.findingsRegisterArtifactId !== undefined) {
+        artifactIds.push(trace.findingsRegisterArtifactId);
+    }
+    if (trace.planArtifactId !== undefined) {
+        artifactIds.push(trace.planArtifactId);
+    }
+    return {
+        requirement_ids,
+        expected_files: trace.affectedFiles.map((path) => ({ path, required: true })),
+        expected_routes: trace.affectedRoutes.map((path) => parseRouteExpectation(path)),
+        expected_tables: trace.affectedTables.map((name) => ({ name, required: true })),
+        expected_tests: trace.testEvidenceRequirement.map((path) => ({
+            path,
+            required: true,
+        })),
+        acceptance_criteria: trace.acceptanceCriteria,
+        tags: [`${exports.CODE_REALITY_PR_GROUP_TAG_PREFIX}${trace.prGrouping}`],
+        complexity: trace.riskLevel,
+        source_artifact_ids: artifactIds,
+    };
+}

package/dist/schemas/workflow/command-center-spine.schema.d.ts

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+/** Origin label for Command Center spine pills — one truth per source. */
+export declare const SpineDataSourceSchema: z.ZodEnum<["github", "neuraloom", "vercel", "kg"]>;
+export type SpineDataSource = z.infer<typeof SpineDataSourceSchema>;
+export declare const BuildSpineNodeIdSchema: z.ZodEnum<["specify", "plan", "schema", "tasks", "implement", "pr", "ci", "merge", "deploy", "review", "kg"]>;
+export type BuildSpineNodeId = z.infer<typeof BuildSpineNodeIdSchema>;
+export declare const BuildSpineNodeStatusSchema: z.ZodEnum<["idle", "running", "success", "warning", "failed", "blocked"]>;
+export type BuildSpineNodeStatus = z.infer<typeof BuildSpineNodeStatusSchema>;
+export declare const BuildSpineNodeSchema: z.ZodObject<{
+    id: z.ZodEnum<["specify", "plan", "schema", "tasks", "implement", "pr", "ci", "merge", "deploy", "review", "kg"]>;
+    label: z.ZodString;
+    source: z.ZodEnum<["github", "neuraloom", "vercel", "kg"]>;
+    status: z.ZodEnum<["idle", "running", "success", "warning", "failed", "blocked"]>;
+    href: z.ZodOptional<z.ZodString>;
+    detail: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    id: "specify" | "plan" | "schema" | "tasks" | "implement" | "ci" | "review" | "merge" | "deploy" | "pr" | "kg";
+    status: "success" | "warning" | "running" | "failed" | "blocked" | "idle";
+    source: "vercel" | "github" | "neuraloom" | "kg";
+    label: string;
+    detail?: string | undefined;
+    href?: string | undefined;
+}, {
+    id: "specify" | "plan" | "schema" | "tasks" | "implement" | "ci" | "review" | "merge" | "deploy" | "pr" | "kg";
+    status: "success" | "warning" | "running" | "failed" | "blocked" | "idle";
+    source: "vercel" | "github" | "neuraloom" | "kg";
+    label: string;
+    detail?: string | undefined;
+    href?: string | undefined;
+}>;
+export type BuildSpineNode = z.infer<typeof BuildSpineNodeSchema>;
+export declare const CommandCenterActivityKindSchema: z.ZodEnum<["artifact", "pr", "ci", "deploy", "review", "gate", "orchestration"]>;
+export type CommandCenterActivityKind = z.infer<typeof CommandCenterActivityKindSchema>;
+export declare const CommandCenterActivityEventSchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<["artifact", "pr", "ci", "deploy", "review", "gate", "orchestration"]>;
+    source: z.ZodEnum<["github", "neuraloom", "vercel", "kg"]>;
+    title: z.ZodString;
+    detail: z.ZodOptional<z.ZodString>;
+    occurredAt: z.ZodString;
+    href: z.ZodOptional<z.ZodString>;
+    tone: z.ZodOptional<z.ZodEnum<["neutral", "success", "warning", "destructive"]>>;
+}, "strict", z.ZodTypeAny, {
+    id: string;
+    title: string;
+    source: "vercel" | "github" | "neuraloom" | "kg";
+    kind: "ci" | "review" | "deploy" | "artifact" | "pr" | "gate" | "orchestration";
+    occurredAt: string;
+    tone?: "success" | "warning" | "neutral" | "destructive" | undefined;
+    detail?: string | undefined;
+    href?: string | undefined;
+}, {
+    id: string;
+    title: string;
+    source: "vercel" | "github" | "neuraloom" | "kg";
+    kind: "ci" | "review" | "deploy" | "artifact" | "pr" | "gate" | "orchestration";
+    occurredAt: string;
+    tone?: "success" | "warning" | "neutral" | "destructive" | undefined;
+    detail?: string | undefined;
+    href?: string | undefined;
+}>;
+export type CommandCenterActivityEvent = z.infer<typeof CommandCenterActivityEventSchema>;

package/dist/schemas/workflow/command-center-spine.schema.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandCenterActivityEventSchema = exports.CommandCenterActivityKindSchema = exports.BuildSpineNodeSchema = exports.BuildSpineNodeStatusSchema = exports.BuildSpineNodeIdSchema = exports.SpineDataSourceSchema = void 0;
+const zod_1 = require("zod");
+/** Origin label for Command Center spine pills — one truth per source. */
+exports.SpineDataSourceSchema = zod_1.z.enum(['github', 'neuraloom', 'vercel', 'kg']);
+exports.BuildSpineNodeIdSchema = zod_1.z.enum([
+    'specify',
+    'plan',
+    'schema',
+    'tasks',
+    'implement',
+    'pr',
+    'ci',
+    'merge',
+    'deploy',
+    'review',
+    'kg',
+]);
+exports.BuildSpineNodeStatusSchema = zod_1.z.enum([
+    'idle',
+    'running',
+    'success',
+    'warning',
+    'failed',
+    'blocked',
+]);
+exports.BuildSpineNodeSchema = zod_1.z
+    .object({
+    id: exports.BuildSpineNodeIdSchema,
+    label: zod_1.z.string(),
+    source: exports.SpineDataSourceSchema,
+    status: exports.BuildSpineNodeStatusSchema,
+    href: zod_1.z.string().optional(),
+    detail: zod_1.z.string().optional(),
+})
+    .strict();
+exports.CommandCenterActivityKindSchema = zod_1.z.enum([
+    'artifact',
+    'pr',
+    'ci',
+    'deploy',
+    'review',
+    'gate',
+    'orchestration',
+]);
+exports.CommandCenterActivityEventSchema = zod_1.z
+    .object({
+    id: zod_1.z.string(),
+    kind: exports.CommandCenterActivityKindSchema,
+    source: exports.SpineDataSourceSchema,
+    title: zod_1.z.string(),
+    detail: zod_1.z.string().optional(),
+    occurredAt: zod_1.z.string(),
+    href: zod_1.z.string().optional(),
+    tone: zod_1.z.enum(['neutral', 'success', 'warning', 'destructive']).optional(),
+})
+    .strict();