@intentius/chant-lexicon-gitlab 0.2.0 → 0.4.0

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "9bfe8386c57d5e1081398a3128f8c1ddde259e0ada0d4ec5e2ea4fafc3301eb1",
+    "manifest.json": "756eed0ed84a1582c77c4c21bbb21e0871f0aa098d602eb4d6ad7e51536b1b34",
     "meta.json": "931fc3246a55645b1493080bbeb160e5d205e42349e8bdca96ca243adb5f0da3",
     "types/index.d.ts": "5cd2e99f135a929b72bdd822d00d780d39b1cd407ba0cfb3d511c7ac9d667b58",
     "rules/artifact-no-expiry.ts": "3f3cabf9792cbf8207e53a25f506715466b19ec25e9c3b4d0d77fed6b2eb4542",
@@ -50,7 +50,7 @@
     "rules/yaml-helpers.ts": "5835982d5d088eb4788ebad8160b181bfdb6fc94d546eabee90a4c278a913988",
     "skills/chant-gitlab.md": "1e26a0c50ea891423479bd7fec3bc133f9185727c4a3eaadd525d7e7436056b6",
     "skills/chant-gitlab-migrate.md": "4853d04980560b379e5b0f7267dcb0a1e5d5879cb9e9931681ce76b2a5fe69d8",
-    "skills/chant-gitlab-patterns.md": "cefda1b656f222293d16381dfbf452b2b376b545a69f62e55dc38907fe8aa7fa"
+    "skills/chant-gitlab-patterns.md": "6d9a44e9e8de4c3820be9d65381b0d2ede4cb3626aaaf0011e21838a9fbf556e"
   },
-  "composite": "26728547d1b80d6bd7ac26734b9bc312b73971bc8a3238dcde789a85e1d83541"
+  "composite": "b9e5cdbd0ea6fcb5fc4229270fbc48219286f9f63703531806202eced8ff5c8f"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "gitlab",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "chantVersion": ">=0.1.0",
   "namespace": "GitLab",
   "intrinsics": [

package/dist/skills/chant-gitlab-patterns.md

@@ -197,6 +197,21 @@ export const app = NodePipeline({
 });
 ```
 
+### Publish the plan to the merge request
+
+`MrPlanReport` turns `chant lifecycle plan` into the MR plan widget (the `terraform` artifact type above). It runs the plan with `--report gitlab-mr`, writes the `{create,update,delete}` counts to `tfplan.json`, and declares it as `artifacts:reports:terraform`:
+
+```typescript
+import { MrPlanReport } from "@intentius/chant-lexicon-gitlab";
+
+export const plan = MrPlanReport({
+  environment: "prod",
+  before: ["aws sts get-caller-identity"], // credential setup — the plan reads live state
+});
+```
+
+The widget label always reads "Terraform" (GitLab's fixed string). Counts only — `adopt`/`noop` are excluded; run the plan in the job log for the per-resource breakdown.
+
 ## Rules and Conditional Execution
 
 ### Branch-Based Rules

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-gitlab",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "GitLab CI lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/codegen/docs.ts

@@ -30,7 +30,7 @@ npm install --save-dev @intentius/chant-lexicon-gitlab
 
 {{file:docs-snippets/src/quickstart.ts}}
 
-The lexicon provides **3 resources** (Job, Workflow, Default), **16 property types** (Image, Cache, Artifacts, Rule, Environment, Trigger, Need, Service, and more), the \`CI\` pseudo-parameter object for predefined variables, and the \`reference()\` intrinsic for YAML \`!reference\` tags.
+The lexicon provides **3 resources** (Job, Workflow, Default), **16 property types** (Image, Cache, Artifacts, Rule, Environment, Trigger, Need, Service, and more), the \`CI\` pseudo-parameter object for predefined variables, and the \`reference()\` intrinsic for YAML \`!reference\` tags. It also ships **4 lint rules** + **39 post-synth checks** (including a CI/CD supply-chain security pass, WGL029–048) and a [\`chant migrate\`](./migration) source for translating GitHub Actions workflows.
 `;
 
 const outputFormat = `The GitLab lexicon serializes resources into **\`.gitlab-ci.yml\` YAML**. Keys are
@@ -435,6 +435,90 @@ Flags jobs whose \`extends:\` references a template or hidden job not defined in
 
 Detects cycles in the \`needs:\` dependency graph. If job A needs B and B needs A (directly or transitively), GitLab rejects the pipeline. Reports the full cycle chain in the diagnostic message.
 
+### WGL016 — Secret in a variables block
+
+**Severity:** error
+
+Detects hardcoded passwords, tokens, or keys in a \`variables:\` block. Move them to CI/CD masked variables instead of committing them to the pipeline. The precursor to the WGL038–040 secret-scoping checks.
+
+### WGL017 — Insecure registry
+
+**Severity:** warning
+
+Flags Docker push/pull to a non-HTTPS registry in a job script. HTTP gives the registry traffic no transport integrity.
+
+### WGL018 — Missing timeout
+
+**Severity:** warning
+
+Flags jobs without an explicit \`timeout:\`. The instance default (often 1 hour) is too long for most jobs and lets a hung job hold a runner.
+
+### WGL019 — Missing retry on deploy jobs
+
+**Severity:** info
+
+Deploy-stage jobs benefit from a \`retry:\` strategy to ride out transient infrastructure failures. Informational, not required.
+
+### WGL020 — Duplicate job names
+
+**Severity:** error
+
+Detects multiple jobs that resolve to the same kebab-case key in the serialized YAML. GitLab silently merges duplicate keys, so one job's config quietly overwrites the other.
+
+### WGL021 — Unused variables
+
+**Severity:** warning
+
+Flags global \`variables:\` not referenced by any job script — usually stale configuration adding noise.
+
+### WGL022 — Missing artifacts expiry
+
+**Severity:** warning
+
+Flags \`artifacts:\` without \`expire_in:\`. Depending on instance config the default is "never expire," which bloats storage.
+
+### WGL023 — Overly broad rules
+
+**Severity:** info
+
+Flags a job whose only rule is \`when: always\` with no conditions (\`if:\`, \`changes:\`, …). That disables all pipeline filtering for the job, which is usually unintended.
+
+### WGL024 — Manual without allow_failure
+
+**Severity:** warning
+
+Flags \`when: manual\` jobs that don't set \`allow_failure: true\`. Without it the manual job blocks the pipeline from progressing past its stage until someone triggers it.
+
+### WGL025 — Missing cache key
+
+**Severity:** warning
+
+Flags \`cache:\` without a \`key:\`. GitLab falls back to the \`default\` key, causing cache collisions between unrelated jobs on the same runner.
+
+### WGL026 — Privileged services without TLS
+
+**Severity:** warning
+
+Flags Docker-in-Docker (DinD) services that don't set \`DOCKER_TLS_CERTDIR\`, leaving the Docker daemon on an unencrypted socket. Extended by WGL036 for the merge-request-reachable case.
+
+### WGL027 — Empty script
+
+**Severity:** error
+
+Detects jobs with \`script: []\` or only empty strings. GitLab rejects empty scripts at pipeline validation time.
+
+### WGL028 — Redundant needs
+
+**Severity:** info
+
+Detects \`needs:\` entries already implied by stage ordering. Not incorrect, but redundant needs add noise and make the pipeline harder to maintain.
+
+## Supply-chain security pass (WGL029–048)
+
+WGL029 onward are a CI/CD supply-chain security pass, the GitLab counterpart to the github lexicon's GHA029–058: pin & vet includes/components/images, scope \`CI_JOB_TOKEN\` and OIDC, guard trust boundaries against untrusted CI input, mask/protect/scope secrets, reject unsound \`rules:\` expressions, and keep artifacts/caches honest. They run statically on the emitted \`.gitlab-ci.yml\`.
+
+The checks that need a *moving external truth* — whether a pinned component/include ref still resolves, whether an upstream was archived or moved, whether a new advisory covers a component in use — live in the operational layer instead. Schedule the [\`PipelineAuditOp\`](/chant/guide/ops/#audit-supply-chain-drift) (temporal lexicon) for that live half; it reads the emitted \`include:\` / \`component:\` / \`image:\` references and reports drift via \`report | issue | merge-request\`.
+
 ### WGL029 — Unpinned include:project / component
 
 **Severity:** warning
@@ -705,6 +789,29 @@ The \`DockerBuild\` composite expands to a job with Docker-in-Docker service, re
 
 {{file:review-app/src/pipeline.ts}}
 
+## Merge-request plan widget
+
+The \`MrPlanReport\` composite turns \`chant lifecycle plan\` into the GitLab merge-request plan widget — the "N to add, M to change, K to delete" summary GitLab renders from an \`artifacts:reports:terraform\` artifact:
+
+\`\`\`typescript
+import { MrPlanReport } from "@intentius/chant-lexicon-gitlab";
+
+export const plan = MrPlanReport({
+  environment: "prod",
+  // credential setup — the plan queries the live system to classify drift
+  before: ["aws sts get-caller-identity"],
+});
+\`\`\`
+
+The job runs \`chant lifecycle plan prod --report gitlab-mr\`, writes the count JSON to \`tfplan.json\`, and declares it as \`artifacts:reports:terraform\`. On the merge request, GitLab shows the plan summary inline.
+
+Caveats worth knowing:
+
+- The widget label always reads **"Terraform"** — that is GitLab's fixed string for this report type, not a claim chant makes.
+- It is **counts only** (create/update/delete). \`adopt\` and \`noop\` are excluded, since the widget has no column for live-but-undeclared or no-change. There is no per-resource breakdown — run \`chant lifecycle plan\` in the job log for that.
+- It is a **GitLab-only** surface. The same plan JSON is portable, but the widget is GitLab's.
+- The plan reads the live system, so the job needs cloud credentials — wire them via \`before\` or CI variables.
+
 ## AWS ALB Deployment
 
 A cross-lexicon example showing how to deploy AWS CloudFormation stacks from GitLab CI. Three separate pipelines mirror the separate-project AWS ALB pattern:
@@ -779,7 +886,7 @@ The \`chant-gitlab\` skill covers the full deployment lifecycle:
 - **Status** — GitLab UI or pipelines API
 - **Retry** — retry failed jobs via UI or API
 - **Cancel** — cancel running pipelines via API
-- **Troubleshooting** — job logs, lint rule codes (WGL001–WGL004), post-synth checks (WGL010–WGL015)
+- **Troubleshooting** — job logs, lint rule codes (WGL001–WGL004), post-synth checks (WGL010–WGL048)
 
 The skill is invocable as a slash command: \`/chant-gitlab\`
 
@@ -802,6 +909,18 @@ The lexicon also provides MCP (Model Context Protocol) tools and resources that
 | \`search\` | Search available resource types |
 | \`gitlab:diff\` | Compare current build output against previous |
 | \`gitlab:migrate\` | Translate a GitHub Actions workflow into GitLab CI/CD (see [Migration](../migration)) |
+| \`gitlab:checks\` | Build and return the pipeline's security/correctness findings (the WGL checks) |
+| \`gitlab:pipeline\` | Build and return the pipeline's stages and jobs (name, stage, run order), as written |
+| \`gitlab:references\` | Build and list what the pipeline pulls in (includes, components, images) and whether each is pinned |
+| \`gitlab:affected\` | Given a job, list the jobs that would re-run because they depend on it |
+| \`gitlab:pipeline-yaml\` | Build and return the generated \`.gitlab-ci.yml\` |
+| \`gitlab:source\` | Given a job, where it came from in the TypeScript — the declaring file and the composite that expanded it, if any (entity-level, not a YAML-line source map) |
+| \`gitlab:owns\` | Given a job, whether it is declared (owned) by chant in this project. Pipeline jobs are not taggable cloud resources, so ownership here means "declared here" — live ownership markers apply to cloud lexicons |
+| \`gitlab:compare\` | Given a GitHub Actions workflow file, migrate it to GitLab CI and report which security properties survive (translated/approximated/needs-review/lost) — the migration safety view |
+
+The \`gitlab:checks\` / \`gitlab:pipeline\` / \`gitlab:references\` / \`gitlab:affected\` / \`gitlab:pipeline-yaml\` / \`gitlab:source\` / \`gitlab:owns\` / \`gitlab:compare\` tools are **read-only**: they build (or migrate) from source and never touch the live GitLab instance. They give an agent a *before-it-runs* view of the pipeline — what it does, what it pulls in, whether it is safe, where it came from, and what survives a migration — to complement the *after-it-ran* view it gets from the instance.
+
+> **Why no \`github:compare\`?** The GitHub → GitLab migration lives in the GitLab lexicon (the GitHub lexicon does not depend on GitLab). A \`github:compare\` would invert that dependency, so the migration safety view is exposed once, here, as \`gitlab:compare\`.
 
 | MCP resource | Description |
 |--------------|-------------|

package/src/composites/composites.test.ts

@@ -4,6 +4,7 @@ import { DockerBuild } from "./docker-build";
 import { NodePipeline, BunPipeline, PnpmPipeline } from "./node-pipeline";
 import { PythonPipeline } from "./python-pipeline";
 import { ReviewApp } from "./review-app";
+import { MrPlanReport } from "./mr-plan-report";
 
 // ---------------------------------------------------------------------------
 // DockerBuild
@@ -703,3 +704,60 @@ describe("ReviewApp", () => {
     expect(props.allow_failure).toBe(true);
   });
 });
+
+// ---------------------------------------------------------------------------
+// MrPlanReport (#329)
+// ---------------------------------------------------------------------------
+describe("MrPlanReport", () => {
+  test("returns a single plan member", () => {
+    const instance = MrPlanReport({ environment: "prod" });
+    expect(instance.plan).toBeDefined();
+    expect(Object.keys(instance.members)).toEqual(["plan"]);
+    expect(isCompositeInstance(instance)).toBe(true);
+  });
+
+  test("declares the terraform report artifact", () => {
+    const props = (MrPlanReport({ environment: "prod" }).plan as any).props;
+    const artifacts = (props.artifacts as any).props;
+    expect(artifacts.reports.terraform).toBe("tfplan.json");
+  });
+
+  test("runs the plan with --report gitlab-mr and redirects to the report file", () => {
+    const props = (MrPlanReport({ environment: "prod" }).plan as any).props;
+    expect(props.script).toContain("npx chant build");
+    expect(props.script.some((s: string) => s.includes("lifecycle plan prod --report gitlab-mr > tfplan.json"))).toBe(true);
+  });
+
+  test("default stage is plan", () => {
+    const props = (MrPlanReport({ environment: "prod" }).plan as any).props;
+    expect(props.stage).toBe("plan");
+  });
+
+  test("lexicon, owned, and custom report file flow into the command", () => {
+    const props = (MrPlanReport({
+      environment: "staging",
+      lexicon: "gitlab",
+      ownedOnly: true,
+      reportFile: "plan.json",
+    }).plan as any).props;
+    const cmd = props.script.find((s: string) => s.includes("lifecycle plan"));
+    expect(cmd).toContain("lifecycle plan staging gitlab --owned --report gitlab-mr > plan.json");
+    expect((props.artifacts as any).props.reports.terraform).toBe("plan.json");
+  });
+
+  test("before commands become before_script (credential setup)", () => {
+    const props = (MrPlanReport({
+      environment: "prod",
+      before: ["gcloud auth ..."],
+    }).plan as any).props;
+    expect(props.before_script).toEqual(["gcloud auth ..."]);
+  });
+
+  test("per-member defaults override the plan job", () => {
+    const props = (MrPlanReport({
+      environment: "prod",
+      defaults: { plan: { tags: ["plan-runner"] } },
+    }).plan as any).props;
+    expect(props.tags).toEqual(["plan-runner"]);
+  });
+});

package/src/composites/index.ts

@@ -6,3 +6,5 @@ export { PythonPipeline } from "./python-pipeline";
 export type { PythonPipelineProps } from "./python-pipeline";
 export { ReviewApp } from "./review-app";
 export type { ReviewAppProps } from "./review-app";
+export { MrPlanReport } from "./mr-plan-report";
+export type { MrPlanReportProps } from "./mr-plan-report";

package/src/composites/mr-plan-report.ts

@@ -0,0 +1,82 @@
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { Job, Image, Artifacts } from "../generated";
+
+export interface MrPlanReportProps {
+  /**
+   * Lifecycle environment to plan against — the `<environment>` argument of
+   * `chant lifecycle plan`.
+   */
+  environment: string;
+  /** Restrict the plan to one lexicon (the optional `[lexicon]` argument). */
+  lexicon?: string;
+  /** Stage for the plan job. Default: `"plan"` */
+  stage?: string;
+  /** Image to run chant in. Default: `"node:22-alpine"` */
+  image?: string;
+  /** Plan against chant-owned resources only (passes `--owned`). */
+  ownedOnly?: boolean;
+  /** Artifact filename the report is written to. Default: `"tfplan.json"` */
+  reportFile?: string;
+  /**
+   * Commands to run before the plan — typically cloud-credential setup, since
+   * the plan queries the live system to classify create/update/delete.
+   */
+  before?: string[];
+  /** Per-member defaults for customizing the generated job. */
+  defaults?: {
+    plan?: Partial<ConstructorParameters<typeof Job>[0]>;
+  };
+}
+
+/**
+ * A CI job that publishes `chant lifecycle plan` as the GitLab merge-request
+ * plan widget.
+ *
+ * The job runs the plan with `--report gitlab-mr`, writes the count JSON to a
+ * file, and declares it as `artifacts:reports:terraform`. GitLab then renders
+ * "N to add, M to change, K to delete" on the MR — the same widget Terraform
+ * uses. The label reads "Terraform" regardless of producer; that is GitLab's
+ * fixed string. Counts are create/update/delete only — `adopt` and `noop` do
+ * not appear.
+ *
+ * The plan reads the live system to classify drift, so wire cloud credentials
+ * via `before` or CI variables.
+ */
+export const MrPlanReport = Composite<MrPlanReportProps>((props) => {
+  const {
+    environment,
+    lexicon,
+    stage = "plan",
+    image = "node:22-alpine",
+    ownedOnly = false,
+    reportFile = "tfplan.json",
+    before,
+    defaults: defs,
+  } = props;
+
+  const planArgs = [
+    "lifecycle",
+    "plan",
+    environment,
+    ...(lexicon ? [lexicon] : []),
+    ...(ownedOnly ? ["--owned"] : []),
+    "--report",
+    "gitlab-mr",
+  ].join(" ");
+
+  const plan = new Job(mergeDefaults({
+    stage,
+    image: new Image({ name: image }),
+    ...(before ? { before_script: before } : {}),
+    script: [
+      "npx chant build",
+      `npx chant ${planArgs} > ${reportFile}`,
+    ],
+    artifacts: new Artifacts({
+      reports: { terraform: reportFile },
+      when: "always",
+    }),
+  }, defs?.plan));
+
+  return { plan };
+}, "MrPlanReport");

package/src/index.ts

@@ -15,8 +15,8 @@ export { CI } from "./variables";
 export * from "./generated/index";
 
 // Composites
-export { DockerBuild, NodePipeline, BunPipeline, PnpmPipeline, PythonPipeline, ReviewApp } from "./composites/index";
-export type { DockerBuildProps, NodePipelineProps, PythonPipelineProps, ReviewAppProps } from "./composites/index";
+export { DockerBuild, NodePipeline, BunPipeline, PnpmPipeline, PythonPipeline, ReviewApp, MrPlanReport } from "./composites/index";
+export type { DockerBuildProps, NodePipelineProps, PythonPipelineProps, ReviewAppProps, MrPlanReportProps } from "./composites/index";
 
 // Spec utilities (for tooling)
 export { fetchCISchema, fetchSchemas, GITLAB_SCHEMA_VERSION } from "./codegen/fetch";

package/src/mcp/context-tools.test.ts

@@ -0,0 +1,178 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { gitlabContextTools, downstreamJobs, componentPinned } from "./context-tools";
+
+const tools = Object.fromEntries(gitlabContextTools().map((t) => [t.name, t]));
+
+async function call(name: string, params: Record<string, unknown>): Promise<unknown> {
+  return tools[name].handler(params);
+}
+
+describe("downstreamJobs / componentPinned (#327)", () => {
+  test("downstreamJobs follows the needs chain transitively", () => {
+    const yaml = `build:
+  stage: build
+  script:
+    - echo build
+
+test:
+  stage: test
+  needs:
+    - build
+  script:
+    - echo test
+
+deploy:
+  stage: deploy
+  needs:
+    - test
+  script:
+    - echo deploy
+`;
+    expect(downstreamJobs(yaml, "build").sort()).toEqual(["deploy", "test"]);
+    expect(downstreamJobs(yaml, "test")).toEqual(["deploy"]);
+    expect(downstreamJobs(yaml, "deploy")).toEqual([]);
+  });
+
+  test("componentPinned recognises a fixed version", () => {
+    expect(componentPinned("gitlab.com/g/comp@1.2.3")).toBe(true);
+    expect(componentPinned("gitlab.com/g/comp@main")).toBe(false);
+  });
+});
+
+describe("gitlab context tools — end to end (#327/#328)", () => {
+  let dir: string;
+  beforeEach(async () => {
+    dir = join(tmpdir(), `chant-mcp-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await mkdir(dir, { recursive: true });
+    await writeFile(
+      join(dir, "pipeline.infra.ts"),
+      `const M = Symbol.for("chant.declarable");
+export const buildApp = { [M]: true, lexicon: "gitlab", entityType: "GitLab::CI::Job", kind: "resource",
+  props: { stage: "build", image: { name: "node:20" }, script: ["echo build"] } };
+export const testApp = { [M]: true, lexicon: "gitlab", entityType: "GitLab::CI::Job", kind: "resource",
+  props: { stage: "test", script: ["npm test"], needs: ["build-app"] } };
+`,
+    );
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  test("gitlab:pipeline returns stages and jobs", async () => {
+    const out = (await call("gitlab:pipeline", { path: dir })) as {
+      stages: string[];
+      jobs: Array<{ name: string; stage: string | null; runsAfter: string[] }>;
+    };
+    expect(out.stages).toEqual(expect.arrayContaining(["build", "test"]));
+    const names = out.jobs.map((j) => j.name);
+    expect(names).toEqual(expect.arrayContaining(["build-app", "test-app"]));
+    expect(out.jobs.find((j) => j.name === "test-app")?.runsAfter).toContain("build-app");
+  });
+
+  test("gitlab:references reports the unpinned image", async () => {
+    const out = (await call("gitlab:references", { path: dir })) as Array<{ kind: string; source: string; pinned: boolean | null }>;
+    const img = out.find((r) => r.kind === "image" && r.source === "node:20");
+    expect(img).toBeDefined();
+    expect(img?.pinned).toBe(false);
+  });
+
+  test("gitlab:checks returns the WGL findings (unpinned image trips WGL031)", async () => {
+    const out = (await call("gitlab:checks", { path: dir })) as { findings: Array<{ id: string; severity: string; job: string | null; message: string }> };
+    expect(Array.isArray(out.findings)).toBe(true);
+    expect(out.findings.some((f) => f.id === "WGL031")).toBe(true);
+    for (const f of out.findings) {
+      expect(typeof f.id).toBe("string");
+      expect(typeof f.message).toBe("string");
+    }
+  });
+
+  test("gitlab:affected lists downstream jobs", async () => {
+    const out = (await call("gitlab:affected", { path: dir, job: "build-app" })) as { job: string; wouldRerun: string[] };
+    expect(out.wouldRerun).toContain("test-app");
+  });
+
+  test("gitlab:pipeline-yaml returns the generated YAML for a path", async () => {
+    const out = (await call("gitlab:pipeline-yaml", { path: dir })) as { yaml: string };
+    expect(typeof out.yaml).toBe("string");
+    expect(out.yaml).toContain("stages:");
+  });
+
+  test("gitlab:source traces a job back to its declaring file", async () => {
+    const out = (await call("gitlab:source", { path: dir, job: "build-app" })) as {
+      job: string; found: boolean; entity: string; from: string | null; via: string | null;
+    };
+    expect(out.found).toBe(true);
+    expect(out.entity).toBe("buildApp");
+    expect(out.from).toMatch(/pipeline\.infra\.ts$/);
+    expect(out.via).toBeNull(); // plain declarable, not from a composite
+  });
+
+  test("gitlab:source reports not-found for an unknown job", async () => {
+    const out = (await call("gitlab:source", { path: dir, job: "nope" })) as { job: string; found: boolean };
+    expect(out.found).toBe(false);
+  });
+
+  test("gitlab:owns reports a declared job as owned, an unknown one as not", async () => {
+    const owned = (await call("gitlab:owns", { path: dir, job: "test-app" })) as { owned: boolean; basis: string };
+    expect(owned.owned).toBe(true);
+    expect(owned.basis).toBe("declared-in-source");
+    const foreign = (await call("gitlab:owns", { path: dir, job: "not-here" })) as { owned: boolean };
+    expect(foreign.owned).toBe(false);
+  });
+});
+
+describe("gitlab:compare — migration safety view (#327)", () => {
+  let dir: string;
+  let wf: string;
+  beforeEach(async () => {
+    dir = join(tmpdir(), `chant-mcp-cmp-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await mkdir(dir, { recursive: true });
+    wf = join(dir, "ci.yml");
+    await writeFile(
+      wf,
+      `name: CI
+on:
+  push:
+    branches: [main]
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@${"a".repeat(40)}
+      - run: npm ci
+`,
+    );
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  test("reports the SHA pin as lost across the migration edge", async () => {
+    const out = (await call("gitlab:compare", { file: wf })) as {
+      found: boolean;
+      properties: Array<{ property: string; fate: string }>;
+      summary: Record<string, number>;
+    };
+    expect(out.found).toBe(true);
+    const pin = out.properties.find((p) => p.property === "Pinned action SHA");
+    expect(pin?.fate).toBe("lost");
+    expect(out.summary.lost).toBeGreaterThanOrEqual(1);
+  });
+
+  test("not-found for a missing file", async () => {
+    const out = (await call("gitlab:compare", { file: join(dir, "nope.yml") })) as { found: boolean };
+    expect(out.found).toBe(false);
+  });
+
+  test("not-found for a non-workflow file", async () => {
+    const notWf = join(dir, "plain.yml");
+    await writeFile(notWf, "hello: world\n");
+    const out = (await call("gitlab:compare", { file: notWf })) as { found: boolean };
+    expect(out.found).toBe(false);
+  });
+});

package/src/mcp/context-tools.ts

@@ -0,0 +1,282 @@
+/**
+ * Read-only MCP tools that expose what `chant build` already computes about a
+ * GitLab pipeline — its stages and jobs, what it pulls in from outside, its
+ * security findings — so an agent can ask about a change *before it runs or
+ * merges* (#327, #328).
+ *
+ * Every tool here builds from source and returns data. None of them touch the
+ * live GitLab instance, read run history, or write anything — that boundary is
+ * what keeps chant a context producer and not a copy of the live tooling.
+ */
+
+import { build, type BuildResult } from "@intentius/chant/build";
+import { runPostSynthChecks, getPrimaryOutput } from "@intentius/chant/lint/post-synth";
+import { discoverPostSynthChecks } from "@intentius/chant/lint/discover";
+import { getProvenance } from "@intentius/chant/provenance";
+import type { McpToolContribution } from "@intentius/chant/mcp/types";
+import { dirname, join, relative, isAbsolute, resolve } from "path";
+import { readFile } from "fs/promises";
+import { fileURLToPath } from "url";
+import { gitlabSerializer } from "../serializer";
+import { transform, detectGitHubWorkflow } from "../migrate/from-github";
+import {
+  extractStages,
+  extractJobs,
+  extractIncludes,
+  extractImageRefs,
+  isPinnedRef,
+} from "../lint/post-synth/yaml-helpers";
+
+/** Build the project and return the emitted GitLab YAML plus the raw result. */
+async function buildGitlab(path: string): Promise<{ yaml: string; result: BuildResult }> {
+  const result = await build(path, [gitlabSerializer]);
+  const out = result.outputs.get("gitlab");
+  return { yaml: out ? getPrimaryOutput(out) : "", result };
+}
+
+/** Discover the lexicon's post-synth checks without depending on the plugin. */
+function gitlabPostSynthChecks() {
+  const dir = join(dirname(fileURLToPath(import.meta.url)), "..", "lint", "post-synth");
+  return discoverPostSynthChecks(dir, import.meta.url);
+}
+
+/** Is a component address (`host/group/comp@version`) pinned to a fixed version? */
+export function componentPinned(value: string): boolean {
+  const at = value.lastIndexOf("@");
+  return at !== -1 && isPinnedRef(value.slice(at + 1));
+}
+
+/** The YAML job name a build entity serializes to (camelCase → kebab-case). */
+export function jobNameOf(entityName: string): string {
+  return entityName.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+/** Find the build entity whose serialized job name matches `job`. */
+function entityForJob(result: BuildResult, job: string): { name: string; entity: object } | undefined {
+  for (const [name, entity] of result.entities) {
+    if (name === job || jobNameOf(name) === job) return { name, entity };
+  }
+  return undefined;
+}
+
+/** Render a source-file path relative to the project root, when possible. */
+function relSource(root: string, file: string | undefined): string | undefined {
+  if (!file) return undefined;
+  if (!isAbsolute(file)) return file;
+  const rel = relative(root, file);
+  return rel.startsWith("..") ? file : rel;
+}
+
+/** Jobs that would re-run because they depend (transitively) on `job`. */
+export function downstreamJobs(yaml: string, job: string): string[] {
+  const jobs = extractJobs(yaml);
+  // edge: upstream -> downstream (J depends on each of its needs)
+  const downstreamOf = new Map<string, string[]>();
+  for (const [name, j] of jobs) {
+    for (const dep of j.needs ?? []) {
+      const arr = downstreamOf.get(dep) ?? [];
+      arr.push(name);
+      downstreamOf.set(dep, arr);
+    }
+  }
+  const out = new Set<string>();
+  const queue = [job];
+  while (queue.length) {
+    const cur = queue.shift()!;
+    for (const next of downstreamOf.get(cur) ?? []) {
+      if (!out.has(next)) {
+        out.add(next);
+        queue.push(next);
+      }
+    }
+  }
+  return [...out];
+}
+
+const PATH_INPUT = {
+  type: "object" as const,
+  properties: {
+    path: { type: "string", description: "Path to the chant project directory (default: current directory)" },
+  },
+};
+
+/** The read-only context tools for the GitLab lexicon. */
+export function gitlabContextTools(): McpToolContribution[] {
+  return [
+    {
+      name: "gitlab:checks",
+      description:
+        "Build the pipeline and return its security and correctness findings (the WGL checks) as JSON. Read-only — does not touch the live GitLab instance.",
+      inputSchema: PATH_INPUT,
+      async handler(params: Record<string, unknown>): Promise<unknown> {
+        const { yaml, result } = await buildGitlab((params.path as string) ?? ".");
+        if (!yaml) return { findings: [], note: "no GitLab pipeline produced from this project" };
+        const scoped = { ...result, outputs: new Map([["gitlab", result.outputs.get("gitlab")!]]) };
+        const diags = runPostSynthChecks(gitlabPostSynthChecks(), scoped);
+        return {
+          findings: diags.map((d) => ({
+            id: d.checkId,
+            severity: d.severity,
+            job: d.entity ?? null,
+            message: d.message,
+          })),
+        };
+      },
+    },
+    {
+      name: "gitlab:pipeline",
+      description:
+        "Build the pipeline and return its stages and jobs as written (name, stage, and what each job runs after) — before anything runs. Read-only.",
+      inputSchema: PATH_INPUT,
+      async handler(params: Record<string, unknown>): Promise<unknown> {
+        const { yaml } = await buildGitlab((params.path as string) ?? ".");
+        const jobs = [...extractJobs(yaml).values()].map((j) => ({
+          name: j.name,
+          stage: j.stage ?? null,
+          runsAfter: j.needs ?? [],
+        }));
+        return { stages: extractStages(yaml), jobs };
+      },
+    },
+    {
+      name: "gitlab:references",
+      description:
+        "Build the pipeline and list everything it pulls in from outside (includes, components, images) and whether each is pinned to a fixed version. Read-only.",
+      inputSchema: PATH_INPUT,
+      async handler(params: Record<string, unknown>): Promise<unknown> {
+        const { yaml } = await buildGitlab((params.path as string) ?? ".");
+        const includes = extractIncludes(yaml).map((e) => ({
+          kind: e.kind,
+          source: e.value,
+          ref: e.ref ?? null,
+          pinned:
+            e.kind === "project" ? (e.ref ? isPinnedRef(e.ref) : false) : e.kind === "component" ? componentPinned(e.value) : null,
+        }));
+        const images = extractImageRefs(yaml).map((i) => ({
+          kind: "image" as const,
+          source: i.image,
+          ref: null,
+          pinned: i.image.includes("@sha256:"),
+        }));
+        return [...includes, ...images];
+      },
+    },
+    {
+      name: "gitlab:affected",
+      description:
+        "Build the pipeline and, given a job name, list the jobs that would re-run because they depend on it (the needs chain). Read-only.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          path: { type: "string", description: "Path to the chant project directory (default: current directory)" },
+          job: { type: "string", description: "Job name to trace downstream from" },
+        },
+        required: ["job"],
+      },
+      async handler(params: Record<string, unknown>): Promise<unknown> {
+        const { yaml } = await buildGitlab((params.path as string) ?? ".");
+        const job = params.job as string;
+        return { job, wouldRerun: downstreamJobs(yaml, job) };
+      },
+    },
+    {
+      name: "gitlab:pipeline-yaml",
+      description: "Build the project and return the generated .gitlab-ci.yml as a string. Read-only.",
+      inputSchema: PATH_INPUT,
+      async handler(params: Record<string, unknown>): Promise<unknown> {
+        const { yaml } = await buildGitlab((params.path as string) ?? ".");
+        return { yaml };
+      },
+    },
+    {
+      name: "gitlab:source",
+      description:
+        "Build the project and, given a job name, say where it came from in the TypeScript source — the file that declared it and the composite that expanded it, if any. Entity-level provenance (file + composite), not a YAML-line source map. Read-only.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          path: { type: "string", description: "Path to the chant project directory (default: current directory)" },
+          job: { type: "string", description: "Job name (as it appears in the generated YAML) to trace back to source" },
+        },
+        required: ["job"],
+      },
+      async handler(params: Record<string, unknown>): Promise<unknown> {
+        const root = (params.path as string) ?? ".";
+        const { result } = await buildGitlab(root);
+        const job = params.job as string;
+        const found = entityForJob(result, job);
+        if (!found) return { job, found: false, note: "no build entity serializes to that job name" };
+        const prov = getProvenance(found.entity);
+        return {
+          job,
+          found: true,
+          entity: found.name,
+          from: relSource(root, prov?.sourceFile) ?? null,
+          via: prov?.composite ?? null,
+        };
+      },
+    },
+    {
+      name: "gitlab:owns",
+      description:
+        "Build the project and report whether a job is declared (owned) by chant in this project's source. For pipeline config, ownership means \"declared here\" — GitLab CI jobs are not taggable cloud resources, so there is no live ownership marker as there is for cloud lexicons. Read-only.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          path: { type: "string", description: "Path to the chant project directory (default: current directory)" },
+          job: { type: "string", description: "Job name (as it appears in the generated YAML) to check" },
+        },
+        required: ["job"],
+      },
+      async handler(params: Record<string, unknown>): Promise<unknown> {
+        const root = (params.path as string) ?? ".";
+        const { result } = await buildGitlab(root);
+        const job = params.job as string;
+        const found = entityForJob(result, job);
+        return {
+          job,
+          owned: Boolean(found),
+          basis: "declared-in-source",
+          note: "GitLab CI jobs are not taggable cloud resources; ownership here means the job is declared by chant in this project. Live ownership markers apply to cloud lexicons (aws/azure/k8s).",
+        };
+      },
+    },
+    {
+      name: "gitlab:compare",
+      description:
+        "Given a GitHub Actions workflow file, migrate it to GitLab CI and report which security properties survive the move and which weaken or are lost (the migration safety view). Returns a per-property fate (translated/approximated/needs-review/lost). Read-only — builds and analyzes, never writes.",
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          file: { type: "string", description: "Path to a .github/workflows/*.yml workflow file to migrate and compare" },
+        },
+        required: ["file"],
+      },
+      async handler(params: Record<string, unknown>): Promise<unknown> {
+        const file = resolve((params.file as string) ?? "");
+        let content: string;
+        try {
+          content = await readFile(file, "utf8");
+        } catch {
+          return { file: params.file ?? null, found: false, note: "could not read the workflow file" };
+        }
+        if (!detectGitHubWorkflow(content)) {
+          return { file: params.file ?? null, found: false, note: "file does not look like a GitHub Actions workflow" };
+        }
+        const migration = await transform(content, { security: true, sourceFile: file });
+        const properties = migration.provenance
+          .filter((r) => r.security)
+          .map((r) => ({
+            property: r.security!.property,
+            fate: r.security!.fate,
+            severity: r.security!.severity,
+            reestablish: r.security!.reestablish ?? null,
+            note: r.note ?? null,
+          }));
+        const summary = { translated: 0, approximated: 0, "needs-review": 0, lost: 0 } as Record<string, number>;
+        for (const p of properties) summary[p.fate] = (summary[p.fate] ?? 0) + 1;
+        return { found: true, properties, summary };
+      },
+    },
+  ];
+}

package/src/plugin.test.ts

@@ -238,6 +238,15 @@ describe("gitlabPlugin", () => {
     const names = tools.map((t) => t.name);
     expect(names).toContain("gitlab:diff");
     expect(names).toContain("migrate");
+    // Read-only context tools (#327/#328)
+    expect(names).toContain("gitlab:checks");
+    expect(names).toContain("gitlab:pipeline");
+    expect(names).toContain("gitlab:references");
+    expect(names).toContain("gitlab:affected");
+    expect(names).toContain("gitlab:pipeline-yaml");
+    expect(names).toContain("gitlab:source");
+    expect(names).toContain("gitlab:owns");
+    expect(names).toContain("gitlab:compare");
     for (const t of tools) {
       expect(typeof t.handler).toBe("function");
     }

package/src/plugin.ts

@@ -12,6 +12,7 @@ import { createSkillsLoader, createDiffTool, createCatalogResource } from "@inte
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { gitlabSerializer } from "./serializer";
+import { gitlabContextTools } from "./mcp/context-tools";
 import { deprecatedOnlyExceptRule } from "./lint/rules/deprecated-only-except";
 import { missingScriptRule } from "./lint/rules/missing-script";
 import { missingStageRule } from "./lint/rules/missing-stage";
@@ -254,6 +255,9 @@ export const test = new Job({
   mcpTools() {
     return [
       createDiffTool(gitlabSerializer, "Compare current build output against previous output for GitLab CI", "gitlab"),
+      // Read-only context tools: what the pipeline does, what it pulls in, and
+      // its security findings — before anything runs (#327/#328).
+      ...gitlabContextTools(),
       {
         name: "migrate",
         description: "Translate a GitHub Actions workflow YAML into a GitLab CI/CD pipeline. Returns the rendered output plus diagnostic + provenance arrays.",

package/src/skills/chant-gitlab-patterns.md

@@ -197,6 +197,21 @@ export const app = NodePipeline({
 });
 ```
 
+### Publish the plan to the merge request
+
+`MrPlanReport` turns `chant lifecycle plan` into the MR plan widget (the `terraform` artifact type above). It runs the plan with `--report gitlab-mr`, writes the `{create,update,delete}` counts to `tfplan.json`, and declares it as `artifacts:reports:terraform`:
+
+```typescript
+import { MrPlanReport } from "@intentius/chant-lexicon-gitlab";
+
+export const plan = MrPlanReport({
+  environment: "prod",
+  before: ["aws sts get-caller-identity"], // credential setup — the plan reads live state
+});
+```
+
+The widget label always reads "Terraform" (GitLab's fixed string). Counts only — `adopt`/`noop` are excluded; run the plan in the job log for the per-resource breakdown.
+
 ## Rules and Conditional Execution
 
 ### Branch-Based Rules