@intentius/chant-lexicon-temporal 0.1.23 → 0.3.0

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "be50b6b3e6c2467ddd9da5f937e94d0f3c603738b46d50b7ebb70fd76a7d609d",
+    "manifest.json": "00501339bf04a016acd73f1c72f824939d582205f76136151c07b57f369fe563",
     "meta.json": "c77a3c415993bed3865e07fa6db4fb7b9e87de0afa8d8675f64eadf50f914077",
     "types/index.d.ts": "5216f5256321f084a7c8211ef66ab599f621c74751cc3485cfc2a62502b81e2f",
     "rules/tmp001.ts": "689222211a93716a7e4432f6dd6a2a2ab54020b232049fb602893872585f9978",
@@ -11,5 +11,5 @@
     "skills/chant-temporal.md": "ff929983b33bb420c49ab61851f3799c5610256cb972d6c584792bb98b0cfb22",
     "skills/chant-temporal-ops.md": "7e83bc3e6e63af4ab14b8dc07aa00132d51991cf35b1bca29560d48934bff6dc"
   },
-  "composite": "5710604f04c18eb3940d4d13ff8d0e39978fd56fcb325ea535de929b29c675cf"
+  "composite": "b5882b2c1e4f6a745e759e3263027720abe90f077b9293df7c85688f0d0754ee"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "temporal",
-  "version": "0.1.23",
+  "version": "0.3.0",
   "chantVersion": ">=0.1.0",
   "namespace": "Temporal",
   "intrinsics": [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-temporal",
-  "version": "0.1.23",
+  "version": "0.3.0",
   "description": "Temporal lexicon for chant — server deployment, namespaces, search attributes, and schedules",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/composites/pipeline-audit-op.test.ts

@@ -0,0 +1,23 @@
+import { describe, test, expect } from "vitest";
+import { PipelineAuditOp } from "./pipeline-audit-op";
+
+describe("PipelineAuditOp composite (#303)", () => {
+  test("one-shot form: op only, no schedule", () => {
+    const { op, schedule } = PipelineAuditOp({ name: "pipeline-audit" });
+    expect(op).toBeDefined();
+    expect(schedule).toBeUndefined();
+  });
+
+  test("scheduled form: op + TemporalSchedule with merge-request finding mode", () => {
+    const { op, schedule } = PipelineAuditOp({
+      name: "pipeline-audit",
+      schedule: "0 6 * * *",
+      onFinding: "merge-request",
+    });
+    expect(op).toBeDefined();
+    expect(schedule).toBeDefined();
+    const props = (schedule as unknown as { props: Record<string, unknown> }).props;
+    expect(props.scheduleId).toBe("pipeline-audit-schedule");
+    expect((props.action as { workflowType: string }).workflowType).toBe("pipelineAuditWorkflow");
+  });
+});

package/src/composites/pipeline-audit-op.ts

@@ -0,0 +1,100 @@
+/**
+ * PipelineAuditOp composite — the live include/component audit of GitLab
+ * pipelines as a chant Op + an optional TemporalSchedule (#303).
+ *
+ * The gitlab post-synth checks (#297) own everything answerable from the
+ * deterministic build. This Op owns *only* the checks that require live
+ * resolution against a moving upstream truth — a pinned component/include ref
+ * that no longer resolves, an archived or moved upstream project, or a new
+ * advisory covering a component/image in use. It sits at **observe** on the
+ * lifecycle dial, with a finding-mode (`report | issue | merge-request`) as the
+ * **reconcile** step — for GitLab the PR mode is a merge request.
+ *
+ * Runs one-shot on the local Op executor via `chant run`; on Temporal when a
+ * `schedule` is given.
+ *
+ * @example
+ * ```typescript
+ * export const { op, schedule } = PipelineAuditOp({
+ *   name: "pipeline-audit",
+ *   schedule: "0 6 * * *",
+ *   onFinding: "merge-request",
+ * });
+ * ```
+ *
+ * @see #297 — the deterministic counterpart this freshens.
+ */
+
+import { Op, phase, OpResource } from "@intentius/chant/op";
+import { TemporalSchedule } from "../resources";
+import type { PipelineAuditMode } from "../op/activities/pipeline-audit";
+
+function kebabToCamel(s: string): string {
+  return s.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+export interface PipelineAuditOpConfig {
+  /** Op name (kebab-case). Used as workflow function name, task queue, schedule id base. */
+  name: string;
+  /** Cron expression. When set, a TemporalSchedule fires the workflow; omit for one-shot. */
+  schedule?: string;
+  /**
+   * Path to the emitted `.gitlab-ci.yml` to audit at run time.
+   * @default ".gitlab-ci.yml"
+   */
+  pipelineFile?: string;
+  /**
+   * What to produce on findings. Default: "report".
+   * @default "report"
+   */
+  onFinding?: PipelineAuditMode;
+  /** Override the task queue. Defaults to `name`. */
+  taskQueue?: string;
+}
+
+export interface PipelineAuditOpResources {
+  /** Op resource — generates the audit workflow on `chant build`. */
+  op: InstanceType<typeof OpResource>;
+  /** Temporal schedule, present only when `schedule` was given. */
+  schedule?: InstanceType<typeof TemporalSchedule>;
+}
+
+export function PipelineAuditOp(config: PipelineAuditOpConfig): PipelineAuditOpResources {
+  const taskQueue = config.taskQueue ?? config.name;
+  const onFinding = config.onFinding ?? "report";
+
+  const op = Op({
+    name: config.name,
+    overview: "Resolve pipeline include/component/image references against live upstreams and report drift",
+    taskQueue,
+    searchAttributes: {
+      Audit: "true",
+      Surface: "gitlab-pipeline",
+    },
+    phases: [
+      phase("Audit", [
+        {
+          kind: "activity",
+          fn: "pipelineSupplyChainAudit",
+          args: { pipelineFile: config.pipelineFile ?? ".gitlab-ci.yml", mode: onFinding },
+          outcomeAttribute: { name: "Findings", from: "findings" },
+        },
+      ]),
+    ],
+  });
+
+  if (!config.schedule) {
+    return { op };
+  }
+
+  const schedule = new TemporalSchedule({
+    scheduleId: `${config.name}-schedule`,
+    spec: { cronExpressions: [config.schedule] },
+    action: {
+      workflowType: kebabToCamel(config.name) + "Workflow",
+      taskQueue,
+    },
+  } as Record<string, unknown>);
+
+  return { op, schedule };
+}

package/src/composites/workflow-audit-op.test.ts

@@ -0,0 +1,24 @@
+import { describe, test, expect } from "vitest";
+import { WorkflowAuditOp } from "./workflow-audit-op";
+
+describe("WorkflowAuditOp composite (#292)", () => {
+  test("one-shot form: op only, no schedule", () => {
+    const { op, schedule } = WorkflowAuditOp({ name: "actions-audit" });
+    expect(op).toBeDefined();
+    expect(schedule).toBeUndefined();
+  });
+
+  test("scheduled form: op + TemporalSchedule on the given cron", () => {
+    const { op, schedule } = WorkflowAuditOp({
+      name: "actions-audit",
+      schedule: "0 6 * * *",
+      onFinding: "pull-request",
+    });
+    expect(op).toBeDefined();
+    expect(schedule).toBeDefined();
+    const props = (schedule as unknown as { props: Record<string, unknown> }).props;
+    expect(props.scheduleId).toBe("actions-audit-schedule");
+    expect((props.spec as { cronExpressions: string[] }).cronExpressions).toEqual(["0 6 * * *"]);
+    expect((props.action as { workflowType: string }).workflowType).toBe("actionsAuditWorkflow");
+  });
+});

package/src/composites/workflow-audit-op.ts

@@ -0,0 +1,108 @@
+/**
+ * WorkflowAuditOp composite — the live supply-chain audit of GitHub workflows
+ * as a chant Op + an optional TemporalSchedule (#292).
+ *
+ * The github post-synth checks (#286-#291) own everything answerable from the
+ * deterministic build. This Op owns *only* the checks that require live
+ * resolution against a moving upstream truth — stale SHA pins, impostor refs,
+ * symbolic-ref confusion, pin/comment mismatch, advisories, archived upstreams.
+ * It sits at **observe** on the lifecycle dial, with a finding-mode (mirroring
+ * `ReconcileOp`: `report | issue | pull-request`) as the **reconcile** step.
+ *
+ * Runs one-shot on the local Op executor via `chant run`; on Temporal when a
+ * `schedule` is given, for continuous re-audit between change windows.
+ *
+ * @example
+ * ```typescript
+ * // one-shot, local executor
+ * export const { op } = WorkflowAuditOp({ name: "actions-audit" });
+ *
+ * // scheduled daily on Temporal, open a PR that bumps a stale pin
+ * export const { op, schedule } = WorkflowAuditOp({
+ *   name: "actions-audit",
+ *   schedule: "0 6 * * *",
+ *   onFinding: "pull-request",
+ * });
+ * ```
+ *
+ * @see #286 — the deterministic counterpart this freshens.
+ */
+
+import { Op, phase, activity, OpResource } from "@intentius/chant/op";
+import { TemporalSchedule } from "../resources";
+import type { WorkflowAuditMode } from "../op/activities/workflow-audit";
+
+function kebabToCamel(s: string): string {
+  return s.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+export interface WorkflowAuditOpConfig {
+  /** Op name (kebab-case). Used as workflow function name, task queue, schedule id base. */
+  name: string;
+  /**
+   * Cron expression. When set, a TemporalSchedule fires the workflow for
+   * continuous re-audit; omit for one-shot `chant run` on the local executor.
+   */
+  schedule?: string;
+  /**
+   * Directory of emitted workflow files to audit at run time.
+   * @default ".github/workflows"
+   */
+  workflowsDir?: string;
+  /**
+   * What to produce on findings. Default: "report".
+   * @default "report"
+   */
+  onFinding?: WorkflowAuditMode;
+  /** Override the task queue. Defaults to `name`. */
+  taskQueue?: string;
+}
+
+export interface WorkflowAuditOpResources {
+  /** Op resource — generates the audit workflow on `chant build`. */
+  op: InstanceType<typeof OpResource>;
+  /** Temporal schedule, present only when `schedule` was given. */
+  schedule?: InstanceType<typeof TemporalSchedule>;
+}
+
+export function WorkflowAuditOp(config: WorkflowAuditOpConfig): WorkflowAuditOpResources {
+  const taskQueue = config.taskQueue ?? config.name;
+  const onFinding = config.onFinding ?? "report";
+
+  const op = Op({
+    name: config.name,
+    overview: "Resolve workflow action references against live upstreams and report supply-chain drift",
+    taskQueue,
+    searchAttributes: {
+      Audit: "true",
+      Surface: "github-workflows",
+    },
+    phases: [
+      phase("Audit", [
+        {
+          kind: "activity",
+          fn: "workflowSupplyChainAudit",
+          args: { workflowsDir: config.workflowsDir ?? ".github/workflows", mode: onFinding },
+          // Surface the finding count as a workflow-level search attribute so
+          // "show me audits that found drift" is a one-filter UI query.
+          outcomeAttribute: { name: "Findings", from: "findings" },
+        },
+      ]),
+    ],
+  });
+
+  if (!config.schedule) {
+    return { op };
+  }
+
+  const schedule = new TemporalSchedule({
+    scheduleId: `${config.name}-schedule`,
+    spec: { cronExpressions: [config.schedule] },
+    action: {
+      workflowType: kebabToCamel(config.name) + "Workflow",
+      taskQueue,
+    },
+  } as Record<string, unknown>);
+
+  return { op, schedule };
+}

package/src/index.ts

@@ -31,6 +31,10 @@ export { WatchOp } from "./composites/watch-op";
 export type { WatchOpConfig, WatchOpResources } from "./composites/watch-op";
 export { ReconcileOp } from "./composites/reconcile-op";
 export type { ReconcileOpConfig, ReconcileOpResources } from "./composites/reconcile-op";
+export { WorkflowAuditOp } from "./composites/workflow-audit-op";
+export type { WorkflowAuditOpConfig, WorkflowAuditOpResources } from "./composites/workflow-audit-op";
+export { PipelineAuditOp } from "./composites/pipeline-audit-op";
+export type { PipelineAuditOpConfig, PipelineAuditOpResources } from "./composites/pipeline-audit-op";
 export { ApplyOp } from "./composites/apply-op";
 export type { ApplyOpConfig, ApplyOpResources } from "./composites/apply-op";
 

package/src/op/activities/index.ts

@@ -33,3 +33,26 @@ export type { WaitForArgoSyncArgs, ArgoAppStatus, ArgoStatusFetcher } from "./ar
 
 export { policyGate } from "./policy";
 export type { PolicyGateArgs } from "./policy";
+
+export { workflowSupplyChainAudit, collectAuditRefs, defaultActionRefResolver } from "./workflow-audit";
+export type {
+  WorkflowAuditArgs,
+  WorkflowAuditResult,
+  WorkflowAuditMode,
+  WorkflowAuditFinding,
+  WorkflowAuditFindingKind,
+  ActionRefResolver,
+  ActionRefResolution,
+} from "./workflow-audit";
+
+export { pipelineSupplyChainAudit, collectPipelineRefs, defaultGitlabRefResolver } from "./pipeline-audit";
+export type {
+  PipelineAuditArgs,
+  PipelineAuditResult,
+  PipelineAuditMode,
+  PipelineAuditFinding,
+  PipelineAuditFindingKind,
+  PipelineRefKind,
+  GitlabRefResolver,
+  PipelineRefResolution,
+} from "./pipeline-audit";

package/src/op/activities/pipeline-audit.test.ts

@@ -0,0 +1,67 @@
+import { describe, test, expect } from "vitest";
+import {
+  pipelineSupplyChainAudit,
+  collectPipelineRefs,
+  type PipelineRefResolution,
+  type GitlabRefResolver,
+} from "./pipeline-audit";
+
+const PIPELINE = `include:
+  - project: my-group/ci-templates
+    ref: v1.2.3
+    file: /build.yml
+  - component: gitlab.example.com/my-group/my-comp@1.0.0
+
+build:
+  image:
+    name: node:20
+  script:
+    - npm ci
+`;
+
+function recordedResolver(records: Record<string, PipelineRefResolution>): GitlabRefResolver {
+  return async (kind, identifier, ref) =>
+    records[`${kind}:${identifier}@${ref}`] ?? { exists: true, archived: false, advisories: [] };
+}
+
+describe("collectPipelineRefs (#303)", () => {
+  test("collects include:project, component, and image refs", () => {
+    const refs = collectPipelineRefs(PIPELINE);
+    const ids = refs.map((r) => `${r.refKind}:${r.identifier}`);
+    expect(ids).toContain("include:my-group/ci-templates");
+    expect(ids).toContain("component:gitlab.example.com/my-group/my-comp");
+    expect(ids).toContain("image:node:20");
+    expect(refs.find((r) => r.refKind === "include")?.ref).toBe("v1.2.3");
+    expect(refs.find((r) => r.refKind === "component")?.ref).toBe("1.0.0");
+  });
+
+  test("skips variable-based images", () => {
+    const refs = collectPipelineRefs(`build:\n  image:\n    name: $CI_REGISTRY_IMAGE:latest\n`);
+    expect(refs.filter((r) => r.refKind === "image")).toHaveLength(0);
+  });
+});
+
+describe("pipelineSupplyChainAudit (#303)", () => {
+  test("flags unresolved, archived, and moved references", async () => {
+    const resolver = recordedResolver({
+      "include:my-group/ci-templates@v1.2.3": { exists: true, archived: true, advisories: [] },
+      "component:gitlab.example.com/my-group/my-comp@1.0.0": { exists: false, archived: false, advisories: [] },
+      "image:node:20@20": { exists: true, archived: false, advisories: ["GHSA-img"], movedTo: undefined },
+    });
+    const result = await pipelineSupplyChainAudit({ yaml: PIPELINE, resolver, mode: "merge-request" });
+    const kinds = result.findings.map((f) => `${f.identifier}:${f.kind}`);
+
+    expect(kinds).toContain("my-group/ci-templates:archived");
+    expect(kinds).toContain("gitlab.example.com/my-group/my-comp:unresolved");
+    expect(kinds).toContain("node:20:advisory");
+    expect(result.mode).toBe("merge-request");
+    expect(result.summary).toContain("Pipeline include/component audit");
+  });
+
+  test("clean pipeline yields no findings", async () => {
+    const resolver = recordedResolver({});
+    const result = await pipelineSupplyChainAudit({ yaml: PIPELINE, resolver });
+    expect(result.findings).toHaveLength(0);
+    expect(result.summary).toContain("No live drift");
+  });
+});

package/src/op/activities/pipeline-audit.ts

@@ -0,0 +1,201 @@
+/**
+ * pipelineSupplyChainAudit — the live counterpart to the gitlab post-synth
+ * include/component/image checks (#297).
+ *
+ * Some include/component checks can only be answered against a moving external
+ * truth: whether a pinned component/include ref still resolves upstream, whether
+ * the upstream project was archived or moved, or whether a new advisory now
+ * covers a component/image already in use. These change independent of the
+ * source, so they cannot live in the deterministic build — this activity owns
+ * *only* the checks that require live resolution.
+ *
+ * Dependency-free and primitives-only: it reads the emitted `.gitlab-ci.yml`
+ * (passed as a string) and resolves references through an injectable
+ * `GitlabRefResolver`, so Temporal/`chant run` can schedule it and tests can run
+ * it against recorded responses with no live network.
+ */
+
+/** What the audit produces on findings. For GitLab the PR mode is a merge request. */
+export type PipelineAuditMode = "report" | "issue" | "merge-request";
+
+/** The kind of reference being resolved. */
+export type PipelineRefKind = "include" | "component" | "image";
+
+/** Live resolution of a single pipeline reference against its upstream. */
+export interface PipelineRefResolution {
+  /** Does the project/component/image (at this ref/version) still resolve? */
+  exists: boolean;
+  /** Has the upstream project been archived? */
+  archived: boolean;
+  /** Has the upstream project moved (new path), if known. */
+  movedTo?: string;
+  /** Disclosed advisory identifiers affecting this reference. */
+  advisories: string[];
+}
+
+/** Pluggable upstream resolver — overridden in tests with recorded responses. */
+export type GitlabRefResolver = (kind: PipelineRefKind, identifier: string, ref: string) => Promise<PipelineRefResolution>;
+
+export type PipelineAuditFindingKind = "unresolved" | "archived" | "moved" | "advisory";
+
+export interface PipelineAuditFinding {
+  kind: PipelineAuditFindingKind;
+  refKind: PipelineRefKind;
+  /** project path / component address / image. */
+  identifier: string;
+  /** ref / version / tag. */
+  ref: string;
+  detail: string;
+}
+
+export interface PipelineAuditArgs {
+  /** One emitted `.gitlab-ci.yml` document. */
+  yaml?: string;
+  /** Several emitted documents. */
+  yamls?: string[];
+  /** Path to an emitted `.gitlab-ci.yml` to read at run time (default `.gitlab-ci.yml`). */
+  pipelineFile?: string;
+  /** What to produce. Default: report. */
+  mode?: PipelineAuditMode;
+  /** Injectable upstream resolver. Defaults to the live GitLab REST resolver. */
+  resolver?: GitlabRefResolver;
+}
+
+export interface PipelineAuditResult {
+  mode: PipelineAuditMode;
+  findings: PipelineAuditFinding[];
+  summary: string;
+}
+
+interface CollectedRef {
+  refKind: PipelineRefKind;
+  identifier: string;
+  ref: string;
+}
+
+/**
+ * Collect `include:project` (+ ref), `component:` (with @version), and `image:`
+ * references from a `.gitlab-ci.yml`.
+ */
+export function collectPipelineRefs(yaml: string): CollectedRef[] {
+  const out: CollectedRef[] = [];
+
+  // include:\n  - project: group/proj\n    ref: main
+  const projectRe = /-\s+project:\s*['"]?([^\s'"]+)['"]?[\s\S]*?ref:\s*['"]?([^\s'"]+)['"]?/g;
+  let m: RegExpExecArray | null;
+  while ((m = projectRe.exec(yaml)) !== null) {
+    out.push({ refKind: "include", identifier: m[1], ref: m[2] });
+  }
+
+  // - component: host/group/comp@1.0.0
+  const componentRe = /-\s+component:\s*['"]?([^\s'"@]+)@([^\s'"]+)['"]?/g;
+  while ((m = componentRe.exec(yaml)) !== null) {
+    out.push({ refKind: "component", identifier: m[1], ref: m[2] });
+  }
+
+  // Images: inline `image: name` or block `image:\n  name: ...` (and services).
+  const lines = yaml.split("\n");
+  const imgSeen = new Set<string>();
+  const addImage = (raw: string) => {
+    const image = raw.trim().replace(/^['"]|['"]$/g, "");
+    if (!image || image.includes("$") || imgSeen.has(image)) return;
+    imgSeen.add(image);
+    const at = image.lastIndexOf("@");
+    const colon = image.lastIndexOf(":");
+    const ref = at !== -1 ? image.slice(at + 1) : colon > image.lastIndexOf("/") ? image.slice(colon + 1) : "latest";
+    out.push({ refKind: "image", identifier: image, ref });
+  };
+  for (let i = 0; i < lines.length; i++) {
+    const inline = lines[i].match(/^\s+image:[ \t]+(\S.*)$/);
+    if (inline) { addImage(inline[1]); continue; }
+    if (/^\s+image:\s*$/.test(lines[i]) || /^\s+-\s+name:[ \t]+(\S.*)$/.test(lines[i])) {
+      const svcName = lines[i].match(/^\s+-\s+name:[ \t]+(\S.*)$/);
+      if (svcName) { addImage(svcName[1]); continue; }
+      const nameLine = lines.slice(i + 1, i + 4).find((l) => /^\s+name:[ \t]+/.test(l));
+      if (nameLine) addImage(nameLine.replace(/^\s+name:[ \t]+/, ""));
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Default resolver: query the GitLab REST API for project existence / archive /
+ * move status. Best-effort and resilient — errors yield an "unknown" resolution
+ * (exists=true, no findings) rather than a false positive. Component/image
+ * advisory lookups are left to a configured resolver.
+ */
+export const defaultGitlabRefResolver: GitlabRefResolver = async (kind, identifier) => {
+  const unknown: PipelineRefResolution = { exists: true, archived: false, advisories: [] };
+  if (kind === "image") return unknown; // image advisory feeds are resolver-specific
+  const host = "https://gitlab.com";
+  const project = kind === "component" ? identifier.split("/").slice(1, 3).join("/") : identifier;
+  try {
+    const resp = await fetch(`${host}/api/v4/projects/${encodeURIComponent(project)}`, {
+      headers: process.env.GITLAB_TOKEN ? { "PRIVATE-TOKEN": process.env.GITLAB_TOKEN } : {},
+    });
+    if (resp.status === 404) return { exists: false, archived: false, advisories: [] };
+    if (!resp.ok) return unknown;
+    const p = (await resp.json()) as { archived?: boolean };
+    return { exists: true, archived: !!p.archived, advisories: [] };
+  } catch {
+    return unknown;
+  }
+};
+
+function renderSummary(findings: PipelineAuditFinding[]): string {
+  if (findings.length === 0) return "## Pipeline include/component audit\n\nNo live drift detected against upstream references.\n";
+  let out = `## Pipeline include/component audit\n\n${findings.length} finding(s) against live upstream truth:\n\n`;
+  out += "| Reference | Ref | Finding | Detail |\n|---|---|---|---|\n";
+  for (const f of findings) out += `| ${f.identifier} (${f.refKind}) | ${f.ref} | ${f.kind} | ${f.detail} |\n`;
+  return out;
+}
+
+async function readFileBestEffort(path: string): Promise<string[]> {
+  try {
+    const { readFile } = await import("node:fs/promises");
+    return [await readFile(path, "utf-8")];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Resolve each include/component/image reference in the emitted pipeline against
+ * live upstreams and report drift.
+ */
+export async function pipelineSupplyChainAudit(args: PipelineAuditArgs): Promise<PipelineAuditResult> {
+  const resolver = args.resolver ?? defaultGitlabRefResolver;
+  const mode = args.mode ?? "report";
+  let yamls = args.yamls ?? (args.yaml ? [args.yaml] : []);
+  if (yamls.length === 0) {
+    yamls = await readFileBestEffort(args.pipelineFile ?? ".gitlab-ci.yml");
+  }
+
+  const findings: PipelineAuditFinding[] = [];
+  const seen = new Set<string>();
+  for (const yaml of yamls) {
+    for (const { refKind, identifier, ref } of collectPipelineRefs(yaml)) {
+      const key = `${refKind}:${identifier}@${ref}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      const res = await resolver(refKind, identifier, ref);
+      if (!res.exists) {
+        findings.push({ kind: "unresolved", refKind, identifier, ref, detail: `${refKind} "${identifier}@${ref}" no longer resolves upstream` });
+        continue;
+      }
+      if (res.archived) {
+        findings.push({ kind: "archived", refKind, identifier, ref, detail: `${identifier} has been archived upstream` });
+      }
+      if (res.movedTo) {
+        findings.push({ kind: "moved", refKind, identifier, ref, detail: `${identifier} moved to ${res.movedTo}` });
+      }
+      for (const adv of res.advisories) {
+        findings.push({ kind: "advisory", refKind, identifier, ref, detail: `disclosed advisory ${adv} covers ${identifier}` });
+      }
+    }
+  }
+
+  return { mode, findings, summary: renderSummary(findings) };
+}

package/src/op/activities/workflow-audit.test.ts

@@ -0,0 +1,90 @@
+import { describe, test, expect } from "vitest";
+import {
+  workflowSupplyChainAudit,
+  collectAuditRefs,
+  type ActionRefResolution,
+  type ActionRefResolver,
+} from "./workflow-audit";
+
+const SHA = "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b";
+
+const WORKFLOW = `name: CI
+on:
+  push:
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@${SHA} # v4.1.0
+      - uses: evil/typo-action@v1
+      - uses: archived/old-action@v2
+`;
+
+/** Recorded upstream responses — no live network. */
+function recordedResolver(records: Record<string, ActionRefResolution>): ActionRefResolver {
+  return async (slug, ref) =>
+    records[`${slug}@${ref}`] ?? { exists: true, tags: [], archived: false, advisories: [] };
+}
+
+describe("collectAuditRefs (#292)", () => {
+  test("collects external refs with version comments, skipping local/docker", () => {
+    const yaml = `jobs:
+  a:
+    steps:
+      - uses: actions/checkout@${SHA} # v4.1.0
+      - uses: ./.github/actions/local
+      - uses: docker://alpine:3.19
+      - uses: org/reusable/.github/workflows/x.yml@v1
+`;
+    const refs = collectAuditRefs(yaml);
+    const slugs = refs.map((r) => r.slug);
+    expect(slugs).toContain("actions/checkout");
+    expect(slugs).toContain("org/reusable");
+    expect(slugs).not.toContain("./.github");
+    expect(refs.find((r) => r.slug === "actions/checkout")?.comment).toBe("v4.1.0");
+  });
+});
+
+describe("workflowSupplyChainAudit (#292)", () => {
+  test("flags stale pin, impostor, archived, and pin/comment mismatch", async () => {
+    const resolver = recordedResolver({
+      // SHA no longer on any tag → stale; actual tag differs from comment → mismatch
+      [`actions/checkout@${SHA}`]: { exists: true, tags: ["v4.2.0"], archived: false, advisories: [] },
+      "evil/typo-action@v1": { exists: false, tags: [], archived: false, advisories: [] },
+      "archived/old-action@v2": { exists: true, tags: ["v2"], archived: true, advisories: ["GHSA-xxxx"] },
+    });
+    const result = await workflowSupplyChainAudit({ yaml: WORKFLOW, resolver, mode: "issue" });
+    const kinds = result.findings.map((f) => `${f.slug}:${f.kind}`);
+
+    expect(kinds).toContain("evil/typo-action:impostor");
+    expect(kinds).toContain("archived/old-action:archived");
+    expect(kinds).toContain("archived/old-action:advisory");
+    expect(kinds).toContain("actions/checkout:pin-comment-mismatch");
+    expect(result.mode).toBe("issue");
+    expect(result.summary).toContain("Workflow supply-chain audit");
+  });
+
+  test("flags a stale SHA pin with no upstream tag", async () => {
+    const resolver = recordedResolver({
+      [`actions/checkout@${SHA}`]: { exists: true, tags: [], archived: false, advisories: [] },
+      "evil/typo-action@v1": { exists: true, tags: ["v1"], archived: false, advisories: [] },
+      "archived/old-action@v2": { exists: true, tags: ["v2"], archived: false, advisories: [] },
+    });
+    const result = await workflowSupplyChainAudit({ yaml: WORKFLOW, resolver });
+    expect(result.findings.some((f) => f.slug === "actions/checkout" && f.kind === "stale-pin")).toBe(true);
+  });
+
+  test("clean workflow yields no findings", async () => {
+    const yaml = `jobs:
+  build:
+    steps:
+      - uses: actions/checkout@${SHA}
+`;
+    const resolver = recordedResolver({
+      [`actions/checkout@${SHA}`]: { exists: true, tags: ["v4"], archived: false, advisories: [] },
+    });
+    const result = await workflowSupplyChainAudit({ yaml, resolver });
+    expect(result.findings).toHaveLength(0);
+    expect(result.summary).toContain("No live drift");
+  });
+});

package/src/op/activities/workflow-audit.ts

@@ -0,0 +1,203 @@
+/**
+ * workflowSupplyChainAudit — the live counterpart to the github post-synth
+ * supply-chain checks (#286-#291).
+ *
+ * Some workflow-reference checks can only be answered against a moving external
+ * truth: whether a pinned SHA still corresponds to a real tag/release upstream,
+ * whether a referenced commit exists in the repo it claims, whether a ref is
+ * confusable as both a tag and a branch, whether a pin matches its version
+ * comment, or whether a new advisory now covers an action already in use. These
+ * change over time independent of the source, so they cannot live in the
+ * deterministic build — this activity owns *only* the checks that require live
+ * resolution.
+ *
+ * It is dependency-free and primitives-only: it reads the emitted workflow YAML
+ * (passed as a string) and resolves references through an injectable
+ * `ActionRefResolver`, so Temporal/`chant run` can schedule it and tests can run
+ * it against recorded responses with no live network.
+ */
+
+/** What the audit produces on findings, mirroring ReconcileOp's modes. */
+export type WorkflowAuditMode = "report" | "issue" | "pull-request";
+
+/** Live resolution of a single action reference against its upstream. */
+export interface ActionRefResolution {
+  /** Does the ref/SHA exist in the claimed repo? */
+  exists: boolean;
+  /** Tag/release names that point at this commit (empty for a SHA ⇒ stale pin). */
+  tags: string[];
+  /** Is the upstream repository archived? */
+  archived: boolean;
+  /** Disclosed advisory identifiers affecting this action. */
+  advisories: string[];
+  /** Is the ref resolvable as BOTH a tag and a branch upstream? */
+  ambiguousRef?: boolean;
+}
+
+/** Pluggable upstream resolver — overridden in tests with recorded responses. */
+export type ActionRefResolver = (slug: string, ref: string) => Promise<ActionRefResolution>;
+
+export type WorkflowAuditFindingKind =
+  | "stale-pin"
+  | "impostor"
+  | "ambiguous-ref"
+  | "pin-comment-mismatch"
+  | "advisory"
+  | "archived";
+
+export interface WorkflowAuditFinding {
+  /** owner/repo slug. */
+  slug: string;
+  /** The pinned ref/SHA. */
+  ref: string;
+  kind: WorkflowAuditFindingKind;
+  detail: string;
+}
+
+export interface WorkflowAuditArgs {
+  /** One emitted workflow YAML document. */
+  yaml?: string;
+  /** Several emitted workflow YAML documents. */
+  yamls?: string[];
+  /**
+   * Directory of emitted workflow files (`*.yml`/`*.yaml`) to read at run time
+   * when no `yaml`/`yamls` is given — the form used inside a scheduled Op.
+   * Default `.github/workflows`.
+   */
+  workflowsDir?: string;
+  /** What to produce. Default: report. */
+  mode?: WorkflowAuditMode;
+  /** Injectable upstream resolver. Defaults to the live GitHub REST resolver. */
+  resolver?: ActionRefResolver;
+}
+
+/** Read `*.yml`/`*.yaml` files from a directory (best-effort). */
+async function readWorkflowDir(dir: string): Promise<string[]> {
+  try {
+    const { readdir, readFile } = await import("node:fs/promises");
+    const { join } = await import("node:path");
+    const files = (await readdir(dir)).filter((f) => f.endsWith(".yml") || f.endsWith(".yaml"));
+    return Promise.all(files.map((f) => readFile(join(dir, f), "utf-8")));
+  } catch {
+    return [];
+  }
+}
+
+export interface WorkflowAuditResult {
+  mode: WorkflowAuditMode;
+  findings: WorkflowAuditFinding[];
+  /** Markdown summary used as the PR/issue body or printed in report mode. */
+  summary: string;
+}
+
+interface CollectedRef {
+  slug: string;
+  ref: string;
+  /** Adjacent `# vX.Y.Z` comment, when present. */
+  comment?: string;
+}
+
+const SHA_RE = /^[0-9a-f]{40}$/;
+
+/**
+ * Collect external action references (`uses: owner/repo@ref`, with an optional
+ * trailing version comment) from a workflow YAML. Local (`./`) and `docker://`
+ * references are excluded.
+ */
+export function collectAuditRefs(yaml: string): CollectedRef[] {
+  const out: CollectedRef[] = [];
+  const re = /uses:\s*['"]?([\w.-]+\/[\w.-]+(?:\/[\w./-]+)?)@([\w.-]+)['"]?\s*(?:#\s*(\S+))?/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(yaml)) !== null) {
+    out.push({ slug: m[1].split("/").slice(0, 2).join("/"), ref: m[2], comment: m[3] });
+  }
+  return out;
+}
+
+/**
+ * Default resolver: query the GitHub REST API for whether the ref exists, what
+ * tags point at it, archive status, and advisories. Best-effort and resilient —
+ * a network/HTTP error yields an "unknown" resolution (exists=true, no findings)
+ * rather than a false positive.
+ */
+export const defaultActionRefResolver: ActionRefResolver = async (slug, ref) => {
+  const base = `https://api.github.com/repos/${slug}`;
+  const headers: Record<string, string> = { Accept: "application/vnd.github+json" };
+  if (process.env.GITHUB_TOKEN) headers.Authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
+  const unknown: ActionRefResolution = { exists: true, tags: [], archived: false, advisories: [] };
+  try {
+    const repoResp = await fetch(base, { headers });
+    if (repoResp.status === 404) return { exists: false, tags: [], archived: false, advisories: [] };
+    if (!repoResp.ok) return unknown;
+    const repo = (await repoResp.json()) as { archived?: boolean };
+
+    const refResp = await fetch(`${base}/commits/${ref}`, { headers });
+    if (refResp.status === 404) return { exists: false, tags: [], archived: !!repo.archived, advisories: [] };
+
+    let tags: string[] = [];
+    if (SHA_RE.test(ref)) {
+      const tagsResp = await fetch(`${base}/tags?per_page=100`, { headers });
+      if (tagsResp.ok) {
+        const tagList = (await tagsResp.json()) as Array<{ name: string; commit?: { sha?: string } }>;
+        tags = tagList.filter((t) => t.commit?.sha === ref).map((t) => t.name);
+      }
+    }
+    return { exists: refResp.ok, tags, archived: !!repo.archived, advisories: [] };
+  } catch {
+    return unknown;
+  }
+};
+
+function renderSummary(findings: WorkflowAuditFinding[]): string {
+  if (findings.length === 0) return "## Workflow supply-chain audit\n\nNo live drift detected against upstream references.\n";
+  let out = `## Workflow supply-chain audit\n\n${findings.length} finding(s) against live upstream truth:\n\n`;
+  out += "| Action | Ref | Finding | Detail |\n|---|---|---|---|\n";
+  for (const f of findings) out += `| ${f.slug} | ${f.ref} | ${f.kind} | ${f.detail} |\n`;
+  return out;
+}
+
+/**
+ * Resolve each pinned external reference in the emitted workflows against live
+ * upstreams and report drift.
+ */
+export async function workflowSupplyChainAudit(args: WorkflowAuditArgs): Promise<WorkflowAuditResult> {
+  const resolver = args.resolver ?? defaultActionRefResolver;
+  const mode = args.mode ?? "report";
+  let yamls = args.yamls ?? (args.yaml ? [args.yaml] : []);
+  if (yamls.length === 0) {
+    yamls = await readWorkflowDir(args.workflowsDir ?? ".github/workflows");
+  }
+
+  const findings: WorkflowAuditFinding[] = [];
+  const seen = new Set<string>();
+  for (const yaml of yamls) {
+    for (const { slug, ref, comment } of collectAuditRefs(yaml)) {
+      const key = `${slug}@${ref}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      const res = await resolver(slug, ref);
+      if (!res.exists) {
+        findings.push({ slug, ref, kind: "impostor", detail: `ref does not exist in ${slug} — possible impostor or deleted ref` });
+        continue;
+      }
+      if (SHA_RE.test(ref) && res.tags.length === 0) {
+        findings.push({ slug, ref, kind: "stale-pin", detail: "pinned SHA is no longer on any tag/release upstream" });
+      }
+      if (res.ambiguousRef) {
+        findings.push({ slug, ref, kind: "ambiguous-ref", detail: "ref resolves as both a tag and a branch upstream (symbolic-ref confusion)" });
+      }
+      if (comment && res.tags.length > 0 && !res.tags.includes(comment)) {
+        findings.push({ slug, ref, kind: "pin-comment-mismatch", detail: `pin comment "${comment}" does not match the SHA's actual tag(s): ${res.tags.join(", ")}` });
+      }
+      if (res.archived) {
+        findings.push({ slug, ref, kind: "archived", detail: `${slug} has been archived upstream since pinning` });
+      }
+      for (const adv of res.advisories) {
+        findings.push({ slug, ref, kind: "advisory", detail: `disclosed advisory ${adv} covers ${slug}` });
+      }
+    }
+  }
+
+  return { mode, findings, summary: renderSummary(findings) };
+}