@intentius/chant-lexicon-gitlab 0.1.23 → 0.3.0

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,220 @@ 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
+
+Flags an \`include:project\` or CI/CD \`component:\` resolved by a moving ref — a branch, a missing \`ref:\` (defaults to the default branch), or a floating component version — instead of a pinned tag or commit SHA.
+
+### WGL030 — Mutable or insecure include:remote
+
+**Severity:** error (HTTP) / warning (HTTPS)
+
+Flags \`include:remote\` URLs fetched over HTTP (no transport integrity) or over HTTPS but inherently mutable. Prefer a pinned \`include:project\` or component. Generalizes WGL017 to includes.
+
+### WGL031 — Container image without a digest
+
+**Severity:** warning
+
+Flags \`image:\` and \`services:\` references not pinned to an immutable \`@sha256:\` digest. Variable-based references (e.g. \`$CI_REGISTRY_IMAGE:tag\`) are skipped.
+
+### WGL032 — Look-alike include/component source
+
+**Severity:** warning
+
+Flags an \`include:project\` / \`component:\` source that is a near-miss (edit distance 1–2) of a well-known GitLab CI source but not an exact match — a likely typo or impersonation. Backed by a vendored reference list.
+
+### WGL033 — OIDC id_token without a scoped audience
+
+**Severity:** warning
+
+Flags an \`id_tokens:\` declaration with no \`aud:\` or a wildcard audience. The audience binds the minted OIDC token to a relying party; without it a leaked token is accepted anywhere.
+
+### WGL034 — OIDC id_token mintable from a merge-request pipeline
+
+**Severity:** warning
+
+Flags a job that declares \`id_tokens:\` and is reachable from merge-request pipelines, which outside contributors can trigger. Restrict OIDC jobs to protected refs or require approval.
+
+> The project-level \`CI_JOB_TOKEN\` allowlist and a variable's protected status are project settings, not emitted pipeline YAML, so they are out of scope for these post-synth checks (see issue #298's caveat).
+
+### WGL035 — Untrusted CI variable in a script
+
+**Severity:** warning
+
+Flags an attacker-controllable predefined variable (branch/tag name, commit or MR title/description, author) referenced in a \`script:\` command, where a crafted value can inject shell commands. Quote it and avoid using it in sensitive commands.
+
+### WGL036 — Privileged DinD reachable from merge requests
+
+**Severity:** warning
+
+Flags a Docker-in-Docker (privileged) job reachable from merge-request pipelines, which outside contributors can trigger. Restrict privileged services to protected refs. Complements WGL026.
+
+### WGL037 — Regex gate on an untrusted ref
+
+**Severity:** warning
+
+Flags a \`rules:if\` that gates on a regex match (\`=~\`) over an attacker-controllable ref variable — a crafted branch/tag name can satisfy the pattern. Match the full ref with \`==\` or gate on a protected condition.
+
+### WGL038 — Secret reachable from a merge-request pipeline
+
+**Severity:** warning
+
+Flags a user-defined secret-like variable read by a job reachable from merge-request pipelines, which can run untrusted code. Gate the job to protected refs or mark the variable protected. (Built-in \`CI_*\` variables are excluded.)
+
+### WGL039 — Secret echoed to job logs
+
+**Severity:** warning
+
+Flags a \`script:\` command that prints a secret-like variable (\`echo\`/\`printf\`/\`cat\`). Logs are broadly readable and masking can be defeated by transforms.
+
+### WGL040 — Hardcoded registry credential
+
+**Severity:** error
+
+Flags a \`docker login\` (or compatible) passing a literal password via \`-p\`/\`--password\` instead of a variable or \`--password-stdin\`. Extends WGL016 to scripts.
+
+> Variable *masking* and *protected* status are GitLab project/CI-settings, not emitted YAML — WGL016 already nudges toward masked variables; this group covers the exposure paths visible in the pipeline.
+
+### WGL041 — Unsound rules:if condition
+
+**Severity:** warning
+
+Flags a tautological \`rules:if\` where both sides of \`==\`/\`!=\` are identical, so the condition is always true or always false. Generalizes WGL011 to conditions presented as gates.
+
+### WGL042 — Unreachable rules after an unconditional match
+
+**Severity:** warning
+
+Flags rules listed after an unconditional rule (no \`if:\`, not \`when: never\`). GitLab takes the first matching rule, so a catch-all makes everything after it dead. Put specific rules first.
+
+### WGL043 — Match-anything regex gate
+
+**Severity:** warning
+
+Flags a \`rules:if\` whose \`=~\` regex matches every value (empty, dot-star, anchored dot-star) — a filter that admits everything. Tighten the pattern or remove the gate.
+
+> The auto-fix acceptance item is N/A at the post-synth layer (PostSynthDiagnostic has no fix channel); it belongs to the declarative source-lint rules.
+
+### WGL044 — Public artifacts
+
+**Severity:** warning
+
+Flags \`artifacts:public: true\`, which makes build output downloadable by anyone. Keep artifacts private unless they are meant to be world-readable.
+
+### WGL045 — Credential-bearing artifact path
+
+**Severity:** error
+
+Flags an \`artifacts:paths:\` entry that looks like a credential or sensitive file (\`.env\`, \`*.pem\`, \`id_rsa\`, \`*.key\`, \`.npmrc\`, \`.netrc\`, \`credentials\`). Artifacts flow downstream and are downloadable — exclude the file.
+
+### WGL046 — Cache poisoning from a merge-request pipeline
+
+**Severity:** warning
+
+Flags a job that writes a cache (push policy) and is reachable from merge-request pipelines. An MR can poison the cache for a later protected run that restores the same key. Restrict cache writes to protected refs or scope the key.
+
+> Artifact / \`dependencies:\` flow across a *protected* boundary depends on a ref's protected status, a project setting not present in emitted YAML — out of scope here.
+
+### WGL047 — Software fetched and piped to a shell
+
+**Severity:** warning
+
+Flags a \`script:\` command that pipes a network download straight into a shell (\`curl ... | bash\`). The fetched code is unpinned and unverified — download to a file, verify a checksum/signature, then run it.
+
+### WGL048 — Pipeline without a name
+
+**Severity:** info
+
+Flags a pipeline that defines a \`workflow:\` block but no \`workflow:name\`. A pipeline name aids identification in the GitLab UI and audit output.
+
+> Two #304 items stay out of scope: a broad privileged-service / DinD check (already covered by WGL026 for DinD-TLS and WGL036 for MR-reachable DinD; a runner's privileged isolation is not in emitted YAML) and an optional include/component allowlist policy (configuration, overlapping WGL032's vendored source list).
+
 ## Running lint
 
 \`\`\`bash
@@ -575,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:
@@ -649,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\`
 
@@ -672,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/lint/post-synth/wgl029.test.ts

@@ -0,0 +1,77 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { wgl029 } from "./wgl029";
+
+function makeCtx(yaml: string): PostSynthContext {
+  return {
+    outputs: new Map([["gitlab", yaml]]),
+    entities: new Map(),
+    buildResult: {
+      outputs: new Map([["gitlab", yaml]]),
+      entities: new Map(),
+      warnings: [],
+      errors: [],
+      sourceFileCount: 1,
+    },
+  };
+}
+
+describe("WGL029: unpinned include:project / component", () => {
+  test("flags include:project on a branch ref", () => {
+    const yaml = `include:
+  - project: my-group/ci-templates
+    ref: main
+    file: /templates/build.yml
+
+stages:
+  - build
+`;
+    const diags = wgl029.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WGL029");
+    expect(diags[0].message).toContain("main");
+  });
+
+  test("flags include:project with no ref", () => {
+    const yaml = `include:
+  - project: my-group/ci-templates
+    file: /templates/build.yml
+
+stages:
+  - build
+`;
+    const diags = wgl029.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].message).toContain("default branch");
+  });
+
+  test("does not flag a pinned tag ref", () => {
+    const yaml = `include:
+  - project: my-group/ci-templates
+    ref: v1.2.3
+    file: /templates/build.yml
+
+stages:
+  - build
+`;
+    const diags = wgl029.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+
+  test("flags a floating component version and not a pinned one", () => {
+    const floating = `include:
+  - component: gitlab.example.com/my-group/my-comp@main
+
+stages:
+  - build
+`;
+    const pinned = `include:
+  - component: gitlab.example.com/my-group/my-comp@1.0.0
+
+stages:
+  - build
+`;
+    expect(wgl029.check(makeCtx(floating))).toHaveLength(1);
+    expect(wgl029.check(makeCtx(pinned))).toHaveLength(0);
+  });
+});

package/src/lint/post-synth/wgl029.ts

@@ -0,0 +1,59 @@
+/**
+ * WGL029: Unpinned include:project / component Reference
+ *
+ * Flags an `include:project` or CI/CD `component:` resolved by a moving ref — a
+ * branch, no `ref:` at all (defaults to the project's default branch), or a
+ * floating component version — instead of a pinned tag or commit SHA. A
+ * repointed ref turns the included configuration into a supply-chain entry point.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, extractIncludes, isPinnedRef } from "./yaml-helpers";
+
+export const wgl029: PostSynthCheck = {
+  id: "WGL029",
+  description: "include:project / component resolved by a moving ref instead of a pinned tag or SHA",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      for (const entry of extractIncludes(yaml)) {
+        if (entry.kind === "project") {
+          if (!entry.ref) {
+            diagnostics.push({
+              checkId: "WGL029",
+              severity: "warning",
+              message: `include:project "${entry.value}" has no ref: and resolves to the project's default branch (a moving target). Pin it to a tag or commit SHA.`,
+              entity: entry.value,
+              lexicon: "gitlab",
+            });
+          } else if (!isPinnedRef(entry.ref)) {
+            diagnostics.push({
+              checkId: "WGL029",
+              severity: "warning",
+              message: `include:project "${entry.value}" is pinned to the moving ref "${entry.ref}". Pin it to a tag or commit SHA.`,
+              entity: entry.value,
+              lexicon: "gitlab",
+            });
+          }
+        } else if (entry.kind === "component") {
+          const at = entry.value.lastIndexOf("@");
+          const version = at === -1 ? "" : entry.value.slice(at + 1);
+          if (!version || !isPinnedRef(version)) {
+            diagnostics.push({
+              checkId: "WGL029",
+              severity: "warning",
+              message: `component "${entry.value}" uses ${version ? `the moving version "${version}"` : "no pinned version"}. Pin it to a released version tag or commit SHA.`,
+              entity: entry.value,
+              lexicon: "gitlab",
+            });
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/wgl030.test.ts

@@ -0,0 +1,57 @@
+import { describe, test, expect } from "vitest";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { wgl030 } from "./wgl030";
+
+function makeCtx(yaml: string): PostSynthContext {
+  return {
+    outputs: new Map([["gitlab", yaml]]),
+    entities: new Map(),
+    buildResult: {
+      outputs: new Map([["gitlab", yaml]]),
+      entities: new Map(),
+      warnings: [],
+      errors: [],
+      sourceFileCount: 1,
+    },
+  };
+}
+
+describe("WGL030: mutable or insecure include:remote", () => {
+  test("errors on an HTTP remote include", () => {
+    const yaml = `include:
+  - remote: http://example.com/ci.yml
+
+stages:
+  - build
+`;
+    const diags = wgl030.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WGL030");
+    expect(diags[0].severity).toBe("error");
+  });
+
+  test("warns on an HTTPS remote include", () => {
+    const yaml = `include:
+  - remote: https://example.com/ci.yml
+
+stages:
+  - build
+`;
+    const diags = wgl030.check(makeCtx(yaml));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].severity).toBe("warning");
+  });
+
+  test("does not flag a project include", () => {
+    const yaml = `include:
+  - project: my-group/ci-templates
+    ref: v1.0.0
+    file: /x.yml
+
+stages:
+  - build
+`;
+    const diags = wgl030.check(makeCtx(yaml));
+    expect(diags).toHaveLength(0);
+  });
+});