@intentius/chant-lexicon-github 0.57.0 → 0.58.0

package/dist/components/generate-op-pipeline.d.ts

@@ -4,21 +4,27 @@
  * The Op counterpart to `./generate-pipeline.ts` (#891): that module
  * synthesizes a `workflow_dispatch`-triggered pipeline from a deploy-time
  * component graph, this one synthesizes a cron-triggered workflow per
- * stateless Op — the CI-native alternative to a Temporal `TemporalSchedule`
- * for downstream projects that don't run Temporal (`WorkflowAuditOp`,
- * `PipelineAuditOp`, `ReconcileOp`, … all accept an optional `schedule`
- * precisely for this).
+ * stateless Op. An Op's cadence is an `OpSchedule` on the Op itself
+ * (`packages/core/src/op/types.ts`), runtime-neutral data each reader
+ * interprets; this module is the reader that turns it into a cron a GitHub
+ * runner fires (`WorkflowAuditOp`, `PipelineAuditOp`, `ReconcileOp`, … all
+ * accept an optional `schedule` precisely for this).
  *
  * GitHub Actions' `on.schedule` is workflow-scoped, not job-scoped, so unlike
  * the component generator (one combined pipeline for the whole graph) this
  * emits one workflow file per `ScheduledOpSpec`. Each workflow:
- *  - triggers on `schedule` (the Op's cron) and `workflow_dispatch` (manual
- *    runs stay available for testing/dry-runs);
- *  - declares only the `permissions:` its `findingMode` needs — `report`
- *    stays read-only, `issue`/`pull-request` add the write scope the Op's own
- *    activity uses (`gh issue create` / `gh pr create`, see
- *    `@intentius/chant-lexicon-temporal`'s `reconcilePr` activity) — never a
- *    blanket `write-all`;
+ *  - triggers on its `ScheduledOpSpec`'s trigger (#2084): `cron` (the Op's
+ *    schedule, plus `workflow_dispatch` so manual runs stay available for
+ *    testing/dry-runs), `pull_request` (optionally filtered to `branches`,
+ *    no `workflow_dispatch` — a PR event needs no manual escape hatch), or
+ *    `push` (filtered to `branches`, defaulting to the repository's default
+ *    branch);
+ *  - declares only the `permissions:` its `findingMode` (and, for a
+ *    `pull_request` trigger, whether that mode posts a comment) needs —
+ *    `report` stays read-only, `issue`/`pull-request` add the write scope
+ *    the Op's own activity uses (`gh issue create` / `gh pr create`, see
+ *    `@intentius/chant/op`'s `reconcilePr` activity) — never a blanket
+ *    `write-all`;
  *  - runs exactly one invocation, `chant run <name>` by default — never
  *    inlined audit/reconcile logic. The finding-mode itself is already baked
  *    into the Op's own activity args at build time by the composite that
@@ -34,7 +40,11 @@ export type { GenerateGithubOpOptions, GenerateGithubOpResult };
  * `./generate-pipeline.ts`'s `GithubPipelineDoc` split.
  */
 export interface GithubOpPipelineDoc {
-    /** The `on:` trigger mapping (`schedule` + `workflow_dispatch`). */
+    /**
+     * The `on:` trigger mapping, per {@link ScheduledOpSpec}'s trigger kind
+     * (#2084): `{ schedule, workflow_dispatch }` for cron, `{ pull_request }`
+     * for `pull_request`, `{ push }` for `push`.
+     */
     on: Record<string, unknown>;
     /** The `env:` mapping, when `options.variables` is set. */
     env?: Record<string, unknown>;

package/dist/components/generate-op-pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-op-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,KAAK,EACV,wBAAwB,IAAI,uBAAuB,EAEnD,aAAa,EACb,gBAAgB,IAAI,sBAAsB,EAC1C,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAElC,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,CAAC;AAEhE;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,oEAAoE;IACpE,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5B,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,qFAAqF;AACrF,MAAM,WAAW,oBAAoB;IACnC,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,mBAAmB,CAAC;CAC1B;AA4BD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC;IAAE,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAAC,IAAI,EAAE,aAAa,EAAE,CAAA;CAAE,CA8C1D;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,mBAAmB,GAAG,MAAM,CAQnE;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CAMxB"}
+{"version":3,"file":"generate-op-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-op-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAIH,OAAO,KAAK,EACV,wBAAwB,IAAI,uBAAuB,EAEnD,aAAa,EACb,gBAAgB,IAAI,sBAAsB,EAE1C,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAElC,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,CAAC;AAEhE;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5B,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,qFAAqF;AACrF,MAAM,WAAW,oBAAoB;IACnC,4FAA4F;IAC5F,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,mBAAmB,CAAC;CAC1B;AA+DD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC;IAAE,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAAC,IAAI,EAAE,aAAa,EAAE,CAAA;CAAE,CA+C1D;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,mBAAmB,GAAG,MAAM,CAQnE;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,eAAe,EAAE,EACtB,OAAO,GAAE,uBAA4B,GACpC,sBAAsB,CAMxB"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "6ed02140e5bbb599e6a2c400adf6b320e3ea45a57969e4d9d13969b372eb02b9",
+    "manifest.json": "dd75f9469a0b8058a7620ebef4b937fd9a6a60e0912e3afd1a0e2a3631685773",
     "meta.json": "dc3977afc2b6ddc4904de906d1b1e448b786b2aced9d82f8eade2ff915203344",
     "types/index.d.ts": "f207946d7ab52f712d0c09995366440a6bba8b39358057b0da38ff9c0acca429",
     "rules/deprecated-action-version.ts": "d41e6e532ab7f623af1bee4ac5279fcb2baada7defa1c5d022a5bc71983e8797",
@@ -77,5 +77,5 @@
     "skills/chant-github-patterns.md": "bb3abef289a8fdfcf07d6bb2d7289dcb2f38bc0cb0321ea320b78b45a6f548c0",
     "skills/chant-github-security.md": "aab111cb0871cad30281ce48d7da23663689619351029219e2be019a1a61e394"
   },
-  "composite": "2eb54e808eb76cc1fc7a94ee7fd6ead00c1d25bb0f776b8a360261224b8ff8e2"
+  "composite": "f6bd3cec37abf68646e70479861823f42af9002b807edda16bf4c873c0e3273a"
 }

package/dist/lint/audit-catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit-catalog.d.ts","sourceRoot":"","sources":["../../src/lint/audit-catalog.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAA4H,KAAK,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAEzL,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CA6DvD,CAAC"}
+{"version":3,"file":"audit-catalog.d.ts","sourceRoot":"","sources":["../../src/lint/audit-catalog.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAA4H,KAAK,QAAQ,EAAgB,MAAM,gCAAgC,CAAC;AAGvM,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CA6DvD,CAAC"}

package/dist/lint/audit-lineage.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Prior art for these audit rules: the open-source tools whose checks cover the
+ * same condition, credited per rule. See packages/core/src/audit/prior-art.ts for
+ * the registry, the relation vocabulary, and why this is credit rather than
+ * authority. Kept by hand; the prior-art sweep (scripts/prior-art-sweep.ts) reports
+ * when a credited tool's index no longer lists a rule cited here.
+ */
+import type { Lineage } from "@intentius/chant/audit/catalog";
+export declare const githubAuditLineage: Record<string, Lineage[]>;
+//# sourceMappingURL=audit-lineage.d.ts.map

package/dist/lint/audit-lineage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-lineage.d.ts","sourceRoot":"","sources":["../../src/lint/audit-lineage.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAC;AAE9D,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAuKxD,CAAC"}

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "github",
-  "version": "0.57.0",
+  "version": "0.58.0",
   "chantVersion": ">=0.1.0",
   "namespace": "GitHub",
   "intrinsics": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-github",
-  "version": "0.57.0",
+  "version": "0.58.0",
   "description": "GitHub Actions lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -61,7 +61,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.57.0",
+    "@intentius/chant": "^0.58.0",
     "typescript": "^5.9.3"
   }
 }

package/src/components/generate-op-pipeline.test.ts

@@ -108,6 +108,84 @@ describe("generateGithubOpPipeline: least-privilege permissions per finding-mode
   });
 });
 
+describe("generateGithubOpPipeline: trigger kinds (#2084)", () => {
+  test("a legacy `{ schedule }` spec with no `trigger` is unchanged", () => {
+    const specs: ScheduledOpSpec[] = [{ name: "actions-audit", schedule: "0 6 * * *", findingMode: "issue" }];
+    const result = generateGithubOpPipeline(specs);
+    const doc = parseFile(result.files[0].yaml);
+
+    expect(doc.on).toEqual({ schedule: [{ cron: "0 6 * * *" }], workflow_dispatch: {} });
+    expect(doc.permissions).toEqual({ contents: "read", issues: "write" });
+    expect(result.jobs[0].trigger).toEqual({ kind: "cron", schedule: "0 6 * * *" });
+  });
+
+  test("pull_request trigger: filters to branches, has no workflow_dispatch", () => {
+    const specs: ScheduledOpSpec[] = [
+      { name: "tf-plan", trigger: { kind: "pull_request", branches: ["main"] } },
+    ];
+    const result = generateGithubOpPipeline(specs);
+    const doc = parseFile(result.files[0].yaml);
+
+    expect(doc.on).toEqual({ pull_request: { branches: ["main"] } });
+    expect(doc.on).not.toHaveProperty("workflow_dispatch");
+    expect(result.jobs[0].trigger).toEqual({ kind: "pull_request", branches: ["main"] });
+  });
+
+  test("pull_request trigger with no branches filter triggers on every PR", () => {
+    const result = generateGithubOpPipeline([{ name: "tf-plan", trigger: { kind: "pull_request" } }]);
+    const doc = parseFile(result.files[0].yaml);
+    expect(doc.on).toEqual({ pull_request: {} });
+  });
+
+  test("pull_request trigger with a comment-posting finding mode gets pull-requests: write", () => {
+    const specs: ScheduledOpSpec[] = [
+      { name: "tf-plan", trigger: { kind: "pull_request" }, findingMode: "issue" },
+    ];
+    const result = generateGithubOpPipeline(specs);
+    const doc = parseFile(result.files[0].yaml);
+    expect(doc.permissions).toEqual({ contents: "read", issues: "write", "pull-requests": "write" });
+  });
+
+  test("pull_request trigger stays read-only when findingMode is report", () => {
+    const result = generateGithubOpPipeline([{ name: "tf-plan", trigger: { kind: "pull_request" } }]);
+    const doc = parseFile(result.files[0].yaml);
+    expect(doc.permissions).toEqual({ contents: "read" });
+  });
+
+  test("push trigger: filters to branches", () => {
+    const specs: ScheduledOpSpec[] = [
+      { name: "tf-apply", trigger: { kind: "push", branches: ["release"] } },
+    ];
+    const result = generateGithubOpPipeline(specs);
+    const doc = parseFile(result.files[0].yaml);
+
+    expect(doc.on).toEqual({ push: { branches: ["release"] } });
+    expect(doc.on).not.toHaveProperty("workflow_dispatch");
+    expect(result.jobs[0].trigger).toEqual({ kind: "push", branches: ["release"] });
+  });
+
+  test("push trigger defaults to the repository default branch (main) when branches is omitted", () => {
+    const result = generateGithubOpPipeline([{ name: "tf-apply", trigger: { kind: "push" } }]);
+    const doc = parseFile(result.files[0].yaml);
+    expect(doc.on).toEqual({ push: { branches: ["main"] } });
+  });
+
+  test("push trigger is read-only by default", () => {
+    const result = generateGithubOpPipeline([{ name: "tf-apply", trigger: { kind: "push" } }]);
+    const doc = parseFile(result.files[0].yaml);
+    expect(doc.permissions).toEqual({ contents: "read" });
+  });
+
+  test("push trigger honors an elevated findingMode, same as cron", () => {
+    const specs: ScheduledOpSpec[] = [
+      { name: "tf-apply", trigger: { kind: "push" }, findingMode: "pull-request" },
+    ];
+    const result = generateGithubOpPipeline(specs);
+    const doc = parseFile(result.files[0].yaml);
+    expect(doc.permissions).toEqual({ contents: "write", "pull-requests": "write" });
+  });
+});
+
 describe("generateGithubOpPipeline: concurrency guards against overlapping runs", () => {
   test("each file's concurrency group is scoped to its own job", () => {
     const result = generateGithubOpPipeline([{ name: "actions-audit", schedule: "0 6 * * *" }]);
@@ -123,7 +201,7 @@ describe("generateGithubOpPipeline: a cross-cutting change is one generator edit
       { name: "prod-reconcile", schedule: "0 * * * *" },
     ];
     const result = generateGithubOpPipeline(specs, {
-      runCommand: ["chant", "run", "{name}", "--temporal"],
+      runCommand: ["chant", "run", "{name}", "--json"],
       beforeScript: ["npm ci"],
       extraScript: ["echo done"],
     });
@@ -133,7 +211,7 @@ describe("generateGithubOpPipeline: a cross-cutting change is one generator edit
       const jobName = Object.keys(doc.jobs!)[0];
       const runLines = doc.jobs![jobName].steps.filter((s) => typeof s.run === "string").map((s) => s.run as string);
       expect(runLines[0]).toBe("npm ci");
-      expect(runLines[1]).toContain("--temporal");
+      expect(runLines[1]).toContain("--json");
       expect(runLines[2]).toBe("echo done");
     }
   });
@@ -144,3 +222,38 @@ describe("generateGithubOpPipeline: a cross-cutting change is one generator edit
     expect(result.jobs).toEqual([]);
   });
 });
+
+describe("generateGithubOpPipeline: the Op's own schedule (#2120)", () => {
+  test("an Op that declares its cadence needs no cron on the spec — opSchedule supplies it", () => {
+    const specs: ScheduledOpSpec[] = [{ name: "prod-watch", opSchedule: { cron: "*/10 * * * *", overlap: "skip" } }];
+    const result = generateGithubOpPipeline(specs);
+    const doc = parseFile(result.files[0].yaml);
+
+    expect(doc.on).toEqual({ schedule: [{ cron: "*/10 * * * *" }], workflow_dispatch: {} });
+    expect(result.jobs[0].trigger).toEqual({ kind: "cron", schedule: "*/10 * * * *" });
+  });
+
+  test("an explicit spec `schedule` still wins over the Op's own", () => {
+    const specs: ScheduledOpSpec[] = [
+      { name: "prod-watch", schedule: "0 6 * * *", opSchedule: { cron: "*/10 * * * *" } },
+    ];
+    const doc = parseFile(generateGithubOpPipeline(specs).files[0].yaml);
+    expect(doc.on).toEqual({ schedule: [{ cron: "0 6 * * *" }], workflow_dispatch: {} });
+  });
+
+  test("an explicit `trigger` overrides the Op's own cadence entirely", () => {
+    const specs: ScheduledOpSpec[] = [
+      { name: "tf-plan", trigger: { kind: "pull_request" }, opSchedule: { cron: "*/10 * * * *" } },
+    ];
+    const result = generateGithubOpPipeline(specs);
+    const doc = parseFile(result.files[0].yaml);
+    expect(doc.on).toEqual({ pull_request: {} });
+    expect(result.jobs[0].trigger).toEqual({ kind: "pull_request" });
+  });
+
+  test("an Op with no cadence anywhere is still an error naming the Op", () => {
+    expect(() => generateGithubOpPipeline([{ name: "no-cadence" }])).toThrow(
+      /Scheduled Op "no-cadence" has neither/,
+    );
+  });
+});

package/src/components/generate-op-pipeline.ts

@@ -4,21 +4,27 @@
  * The Op counterpart to `./generate-pipeline.ts` (#891): that module
  * synthesizes a `workflow_dispatch`-triggered pipeline from a deploy-time
  * component graph, this one synthesizes a cron-triggered workflow per
- * stateless Op — the CI-native alternative to a Temporal `TemporalSchedule`
- * for downstream projects that don't run Temporal (`WorkflowAuditOp`,
- * `PipelineAuditOp`, `ReconcileOp`, … all accept an optional `schedule`
- * precisely for this).
+ * stateless Op. An Op's cadence is an `OpSchedule` on the Op itself
+ * (`packages/core/src/op/types.ts`), runtime-neutral data each reader
+ * interprets; this module is the reader that turns it into a cron a GitHub
+ * runner fires (`WorkflowAuditOp`, `PipelineAuditOp`, `ReconcileOp`, … all
+ * accept an optional `schedule` precisely for this).
  *
  * GitHub Actions' `on.schedule` is workflow-scoped, not job-scoped, so unlike
  * the component generator (one combined pipeline for the whole graph) this
  * emits one workflow file per `ScheduledOpSpec`. Each workflow:
- *  - triggers on `schedule` (the Op's cron) and `workflow_dispatch` (manual
- *    runs stay available for testing/dry-runs);
- *  - declares only the `permissions:` its `findingMode` needs — `report`
- *    stays read-only, `issue`/`pull-request` add the write scope the Op's own
- *    activity uses (`gh issue create` / `gh pr create`, see
- *    `@intentius/chant-lexicon-temporal`'s `reconcilePr` activity) — never a
- *    blanket `write-all`;
+ *  - triggers on its `ScheduledOpSpec`'s trigger (#2084): `cron` (the Op's
+ *    schedule, plus `workflow_dispatch` so manual runs stay available for
+ *    testing/dry-runs), `pull_request` (optionally filtered to `branches`,
+ *    no `workflow_dispatch` — a PR event needs no manual escape hatch), or
+ *    `push` (filtered to `branches`, defaulting to the repository's default
+ *    branch);
+ *  - declares only the `permissions:` its `findingMode` (and, for a
+ *    `pull_request` trigger, whether that mode posts a comment) needs —
+ *    `report` stays read-only, `issue`/`pull-request` add the write scope
+ *    the Op's own activity uses (`gh issue create` / `gh pr create`, see
+ *    `@intentius/chant/op`'s `reconcilePr` activity) — never a blanket
+ *    `write-all`;
  *  - runs exactly one invocation, `chant run <name>` by default — never
  *    inlined audit/reconcile logic. The finding-mode itself is already baked
  *    into the Op's own activity args at build time by the composite that
@@ -26,11 +32,13 @@
  */
 
 import { emitYAML } from "@intentius/chant/yaml";
+import { resolveOpTrigger } from "@intentius/chant/lexicon";
 import type {
   ComponentPipelineOptions as GenerateGithubOpOptions,
   OpFindingMode,
   OpPipelineJob,
   OpPipelineResult as GenerateGithubOpResult,
+  OpTrigger,
   ScheduledOpSpec,
 } from "@intentius/chant/lexicon";
 
@@ -44,7 +52,11 @@ export type { GenerateGithubOpOptions, GenerateGithubOpResult };
  * `./generate-pipeline.ts`'s `GithubPipelineDoc` split.
  */
 export interface GithubOpPipelineDoc {
-  /** The `on:` trigger mapping (`schedule` + `workflow_dispatch`). */
+  /**
+   * The `on:` trigger mapping, per {@link ScheduledOpSpec}'s trigger kind
+   * (#2084): `{ schedule, workflow_dispatch }` for cron, `{ pull_request }`
+   * for `pull_request`, `{ push }` for `push`.
+   */
   on: Record<string, unknown>;
   /** The `env:` mapping, when `options.variables` is set. */
   env?: Record<string, unknown>;
@@ -75,13 +87,40 @@ function toJobName(opName: string): string {
 const DEFAULT_IMAGE = "node:22-slim";
 
 /**
- * Least-privilege `permissions:` for a scheduled Op's finding-mode. `report`
- * needs no write access; `issue` needs only `issues: write`; `pull-request`
- * (and `merge-request`, generated the same way when a GitLab-authored spec is
- * targeted at github) needs `contents: write` to push the reconcile branch
- * plus `pull-requests: write` to open the PR.
+ * Default branch assumed for a `push` trigger with no `branches` override
+ * (#2084). There is no generator constant for a downstream project's actual
+ * default branch — this operates on a `ScheduledOpSpec`, not a git checkout
+ * — so "main" is the documented default; set `trigger.branches` explicitly
+ * for a project whose default branch is something else (e.g. "master").
+ */
+const DEFAULT_PUSH_BRANCH = "main";
+
+/** This trigger's `on:` mapping (#2084): cron unchanged, `pull_request`/`push` new. */
+function onFor(trigger: OpTrigger): Record<string, unknown> {
+  switch (trigger.kind) {
+    case "cron":
+      return { schedule: [{ cron: trigger.schedule }], workflow_dispatch: {} };
+    case "pull_request":
+      // No `workflow_dispatch`: a PR trigger needs no manual-dispatch escape
+      // hatch (revisit in review if that's wrong).
+      return { pull_request: trigger.branches ? { branches: trigger.branches } : {} };
+    case "push":
+      return { push: { branches: trigger.branches ?? [DEFAULT_PUSH_BRANCH] } };
+  }
+}
+
+/**
+ * Least-privilege `permissions:` for a scheduled Op's finding-mode and
+ * trigger. `report` needs no write access; `issue` needs only `issues:
+ * write`; `pull-request` (and `merge-request`, generated the same way when a
+ * GitLab-authored spec is targeted at github) needs `contents: write` to
+ * push the reconcile branch plus `pull-requests: write` to open the PR. A
+ * `pull_request` trigger reports its finding as a comment on the triggering
+ * PR itself (#2084): any mode but `report` posts something to act on a
+ * finding, so on that trigger every such mode also gets `pull-requests:
+ * write` for the comment, whether or not its own scope already included it.
  */
-function permissionsFor(mode: OpFindingMode): Record<string, "read" | "write"> {
+function permissionsForMode(mode: OpFindingMode): Record<string, "read" | "write"> {
   switch (mode) {
     case "issue":
       return { contents: "read", issues: "write" };
@@ -93,6 +132,14 @@ function permissionsFor(mode: OpFindingMode): Record<string, "read" | "write"> {
   }
 }
 
+function permissionsFor(mode: OpFindingMode, trigger: OpTrigger): Record<string, "read" | "write"> {
+  const base = permissionsForMode(mode);
+  if (trigger.kind === "pull_request" && mode !== "report") {
+    return { ...base, "pull-requests": "write" };
+  }
+  return base;
+}
+
 /**
  * Build one `GithubOpPipelineDoc` per scheduled Op: cron trigger,
  * least-privilege `permissions:` for its finding-mode, one job that runs
@@ -113,8 +160,9 @@ export function buildGithubOpPipelineDocs(
 
   for (const spec of ops) {
     const findingMode = spec.findingMode ?? "report";
+    const trigger = resolveOpTrigger(spec);
     const jobName = toJobName(spec.name);
-    jobs.push({ jobName, op: spec.name, schedule: spec.schedule, findingMode });
+    jobs.push({ jobName, op: spec.name, trigger, findingMode });
 
     const runParts = runCommand.map((part) => part.replace("{name}", spec.name));
 
@@ -129,12 +177,12 @@ export function buildGithubOpPipelineDocs(
     for (const line of extraScript) steps.push({ run: line });
 
     const doc: GithubOpPipelineDoc = {
-      on: { schedule: [{ cron: spec.schedule }], workflow_dispatch: {} },
+      on: onFor(trigger),
       ...(options.variables && Object.keys(options.variables).length > 0 ? { env: options.variables } : {}),
       // One run at a time per Op — a slow audit must not overlap its own next
       // scheduled trigger.
       concurrency: { group: jobName, "cancel-in-progress": false },
-      permissions: permissionsFor(findingMode),
+      permissions: permissionsFor(findingMode, trigger),
       jobsDoc: {
         [jobName]: {
           "runs-on": "ubuntu-latest",

package/src/components/generate-pipeline.test.ts

@@ -222,7 +222,7 @@ describe("generateGithubPipeline: a cross-cutting change is one generator edit,
   test("changing the trigger command (runCommand) updates every job's script uniformly", () => {
     const components = pilotComponents();
     const result = generateGithubPipeline(components, {
-      runCommand: ["chant", "run", "--components", "{name}", "--env", "staging", "--temporal"],
+      runCommand: ["chant", "run", "--components", "{name}", "--env", "staging", "--verbose"],
     });
     const jobs = parsedJobs(result.yaml);
 
@@ -230,7 +230,7 @@ describe("generateGithubPipeline: a cross-cutting change is one generator edit,
       const lines = runLines(jobs[job.jobName]);
       // The runCommand prefix reflects in every job; output-threading flags
       // (--seed-outputs/--dump-outputs) may be appended per the dependency graph.
-      expect(lines[0].startsWith(`chant run --components ${job.component} --env staging --temporal`)).toBe(true);
+      expect(lines[0].startsWith(`chant run --components ${job.component} --env staging --verbose`)).toBe(true);
     }
   });
 

package/src/lint/audit-catalog.ts

@@ -2,7 +2,8 @@
  * The github lexicon's chant audit catalog — metadata for its post-synth rules
  * (GHA GitHub Actions rules). Contributed via githubPlugin.auditCatalog() (#687).
  */
-import { auditRule, GH_INJECTION, GH_PWN, GH_SECRETS, GH_THIRD_PARTY, GH_TOKEN, SCORECARD_PINNED, SCORECARD_TOKEN, SCORECARD_VULN, type RuleMeta } from "@intentius/chant/audit/catalog";
+import { auditRule, GH_INJECTION, GH_PWN, GH_SECRETS, GH_THIRD_PARTY, GH_TOKEN, SCORECARD_PINNED, SCORECARD_TOKEN, SCORECARD_VULN, type RuleMeta, applyLineage } from "@intentius/chant/audit/catalog";
+import { githubAuditLineage } from "./audit-lineage";
 
 export const githubAuditCatalog: Record<string, RuleMeta> = {
   GHA006: auditRule("GHA006", "report-only", "guidance", "Duplicate workflow name", "Give each workflow a unique `name:`.", { category: "correctness" }),
@@ -66,3 +67,6 @@ export const githubAuditCatalog: Record<string, RuleMeta> = {
   GHA067: auditRule("GHA067", "report-only", "guidance", "Unconditional heavy step with no path filter", "Scope the trigger's paths, or add an if: guard to the step.", { category: "efficiency" }),
   GHA068: auditRule("GHA068", "report-only", "guidance", "Pull-request workflow missing a concurrency group", "Add a concurrency group with cancel-in-progress: true.", { category: "efficiency" }),
 };
+
+// Prior art credits live beside the rules in ./audit-lineage.ts (see core audit/prior-art.ts).
+applyLineage(githubAuditCatalog, githubAuditLineage);

package/src/lint/audit-lineage.ts

@@ -0,0 +1,177 @@
+/**
+ * Prior art for these audit rules: the open-source tools whose checks cover the
+ * same condition, credited per rule. See packages/core/src/audit/prior-art.ts for
+ * the registry, the relation vocabulary, and why this is credit rather than
+ * authority. Kept by hand; the prior-art sweep (scripts/prior-art-sweep.ts) reports
+ * when a credited tool's index no longer lists a rule cited here.
+ */
+import type { Lineage } from "@intentius/chant/audit/catalog";
+
+export const githubAuditLineage: Record<string, Lineage[]> = {
+  GHA009: [
+    { tool: "actionlint", rule: "Unexpected empty mappings", url: "https://github.com/rhysd/actionlint/blob/main/docs/checks.md#unexpected-empty-mappings", relation: "overlaps" },
+  ],
+  GHA011: [
+    { tool: "actionlint", rule: "Job dependencies validation", url: "https://github.com/rhysd/actionlint/blob/main/docs/checks.md#job-dependencies-validation", relation: "equivalent" },
+  ],
+  GHA013: [
+    { tool: "poutine", rule: "default_permissions_on_risky_events", url: "https://boostsecurityio.github.io/poutine/rules/default_permissions_on_risky_events/", relation: "overlaps" },
+    { tool: "zizmor", rule: "excessive-permissions", url: "https://docs.zizmor.sh/audits/#excessive-permissions", relation: "overlaps" },
+    { tool: "scorecard", rule: "Token-Permissions", url: "https://github.com/ossf/scorecard/blob/main/docs/checks.md#token-permissions", relation: "overlaps" },
+  ],
+  GHA017: [
+    { tool: "zizmor", rule: "excessive-permissions", url: "https://docs.zizmor.sh/audits/#excessive-permissions", relation: "overlaps" },
+    { tool: "scorecard", rule: "Token-Permissions", url: "https://github.com/ossf/scorecard/blob/main/docs/checks.md#token-permissions", relation: "overlaps" },
+  ],
+  GHA018: [
+    { tool: "scorecard", rule: "Dangerous-Workflow", url: "https://github.com/ossf/scorecard/blob/main/docs/checks.md#dangerous-workflow", relation: "overlaps" },
+    { tool: "octoscan", rule: "dangerous-checkout", url: "https://github.com/synacktiv/octoscan#dangerous-checkout", relation: "overlaps" },
+    { tool: "poutine", rule: "untrusted_checkout_exec", url: "https://boostsecurityio.github.io/poutine/rules/untrusted_checkout_exec/", relation: "overlaps" },
+  ],
+  GHA019: [
+    { tool: "actionlint", rule: "Job dependencies validation", url: "https://github.com/rhysd/actionlint/blob/main/docs/checks.md#job-dependencies-validation", relation: "equivalent" },
+  ],
+  GHA021: [
+    { tool: "zizmor", rule: "unpinned-uses", url: "https://docs.zizmor.sh/audits/#unpinned-uses", relation: "overlaps" },
+    { tool: "scorecard", rule: "Pinned-Dependencies", url: "https://github.com/ossf/scorecard/blob/main/docs/checks.md#pinned-dependencies", relation: "overlaps" },
+  ],
+  GHA023: [
+    { tool: "actionlint", rule: "Check deprecated workflow commands", url: "https://github.com/rhysd/actionlint/blob/main/docs/checks.md#check-deprecated-workflow-commands", relation: "overlaps" },
+  ],
+  GHA024: [
+    { tool: "zizmor", rule: "concurrency-limits", url: "https://docs.zizmor.sh/audits/#concurrency-limits", relation: "overlaps" },
+  ],
+  GHA025: [
+    { tool: "zizmor", rule: "dangerous-triggers", url: "https://docs.zizmor.sh/audits/#dangerous-triggers", relation: "overlaps" },
+  ],
+  GHA026: [
+    { tool: "zizmor", rule: "secrets-outside-env", url: "https://docs.zizmor.sh/audits/#secrets-outside-env", relation: "equivalent" },
+  ],
+  GHA028: [
+    { tool: "actionlint", rule: "Missing required keys and key duplicates", url: "https://github.com/rhysd/actionlint/blob/main/docs/checks.md#missing-required-keys-and-key-duplicates", relation: "overlaps" },
+  ],
+  GHA029: [
+    { tool: "zizmor", rule: "unpinned-uses", url: "https://docs.zizmor.sh/audits/#unpinned-uses", relation: "overlaps" },
+    { tool: "scorecard", rule: "Pinned-Dependencies", url: "https://github.com/ossf/scorecard/blob/main/docs/checks.md#pinned-dependencies", relation: "overlaps" },
+  ],
+  GHA030: [
+    { tool: "zizmor", rule: "unpinned-images", url: "https://docs.zizmor.sh/audits/#unpinned-images", relation: "overlaps" },
+  ],
+  GHA031: [
+    { tool: "zizmor", rule: "typosquat-uses", url: "https://docs.zizmor.sh/audits/#typosquat-uses", relation: "equivalent" },
+  ],
+  GHA032: [
+    { tool: "zizmor", rule: "archived-uses", url: "https://docs.zizmor.sh/audits/#archived-uses", relation: "overlaps" },
+    { tool: "zizmor", rule: "known-vulnerable-actions", url: "https://docs.zizmor.sh/audits/#known-vulnerable-actions", relation: "overlaps" },
+  ],
+  GHA033: [
+    { tool: "zizmor", rule: "excessive-permissions", url: "https://docs.zizmor.sh/audits/#excessive-permissions", relation: "overlaps" },
+    { tool: "scorecard", rule: "Token-Permissions", url: "https://github.com/ossf/scorecard/blob/main/docs/checks.md#token-permissions", relation: "overlaps" },
+  ],
+  GHA034: [
+    { tool: "zizmor", rule: "excessive-permissions", url: "https://docs.zizmor.sh/audits/#excessive-permissions", relation: "overlaps" },
+    { tool: "scorecard", rule: "Token-Permissions", url: "https://github.com/ossf/scorecard/blob/main/docs/checks.md#token-permissions", relation: "overlaps" },
+  ],
+  GHA036: [
+    { tool: "zizmor", rule: "template-injection", url: "https://docs.zizmor.sh/audits/#template-injection", relation: "equivalent" },
+    { tool: "poutine", rule: "injection", url: "https://boostsecurityio.github.io/poutine/rules/injection/", relation: "equivalent" },
+    { tool: "actionlint", rule: "Script injection by potentially untrusted inputs", url: "https://github.com/rhysd/actionlint/blob/main/docs/checks.md#script-injection-by-potentially-untrusted-inputs", relation: "equivalent" },
+    { tool: "octoscan", rule: "expression-injection", url: "https://github.com/synacktiv/octoscan#expression-injection", relation: "equivalent" },
+    { tool: "scorecard", rule: "Dangerous-Workflow", url: "https://github.com/ossf/scorecard/blob/main/docs/checks.md#dangerous-workflow", relation: "overlaps" },
+  ],
+  GHA037: [
+    { tool: "zizmor", rule: "github-env", url: "https://docs.zizmor.sh/audits/#github-env", relation: "equivalent" },
+    { tool: "octoscan", rule: "dangerous-write", url: "https://github.com/synacktiv/octoscan#dangerous-write", relation: "overlaps" },
+  ],
+  GHA038: [
+    { tool: "scorecard", rule: "Dangerous-Workflow", url: "https://github.com/ossf/scorecard/blob/main/docs/checks.md#dangerous-workflow", relation: "overlaps" },
+    { tool: "octoscan", rule: "dangerous-checkout", url: "https://github.com/synacktiv/octoscan#dangerous-checkout", relation: "overlaps" },
+  ],
+  GHA039: [
+    { tool: "zizmor", rule: "bot-conditions", url: "https://docs.zizmor.sh/audits/#bot-conditions", relation: "overlaps" },
+    { tool: "octoscan", rule: "bot-check", url: "https://github.com/synacktiv/octoscan#bot-check", relation: "overlaps" },
+    { tool: "poutine", rule: "confused_deputy_auto_merge", url: "https://boostsecurityio.github.io/poutine/rules/confused_deputy_auto_merge/", relation: "overlaps" },
+  ],
+  GHA040: [
+    { tool: "poutine", rule: "pr_runs_on_self_hosted", url: "https://boostsecurityio.github.io/poutine/rules/pr_runs_on_self_hosted/", relation: "equivalent" },
+    { tool: "zizmor", rule: "self-hosted-runner", url: "https://docs.zizmor.sh/audits/#self-hosted-runner", relation: "overlaps" },
+    { tool: "octoscan", rule: "runner-label", url: "https://github.com/synacktiv/octoscan#runner-label", relation: "overlaps" },
+  ],
+  GHA041: [
+    { tool: "zizmor", rule: "secrets-inherit", url: "https://docs.zizmor.sh/audits/#secrets-inherit", relation: "equivalent" },
+  ],
+  GHA042: [
+    { tool: "zizmor", rule: "overprovisioned-secrets", url: "https://docs.zizmor.sh/audits/#overprovisioned-secrets", relation: "equivalent" },
+    { tool: "poutine", rule: "job_all_secrets", url: "https://boostsecurityio.github.io/poutine/rules/job_all_secrets/", relation: "equivalent" },
+  ],
+  GHA043: [
+    { tool: "zizmor", rule: "secrets-outside-env", url: "https://docs.zizmor.sh/audits/#secrets-outside-env", relation: "equivalent" },
+  ],
+  GHA044: [
+    { tool: "zizmor", rule: "hardcoded-container-credentials", url: "https://docs.zizmor.sh/audits/#hardcoded-container-credentials", relation: "equivalent" },
+    { tool: "actionlint", rule: "Hardcoded credentials", url: "https://github.com/rhysd/actionlint/blob/main/docs/checks.md#hardcoded-credentials", relation: "equivalent" },
+    { tool: "octoscan", rule: "credentials", url: "https://github.com/synacktiv/octoscan#credentials", relation: "equivalent" },
+  ],
+  GHA046: [
+    { tool: "actionlint", rule: "Constant conditions at `if:`", url: "https://github.com/rhysd/actionlint/blob/main/docs/checks.md#constant-conditions-at-if", relation: "equivalent" },
+    { tool: "zizmor", rule: "unsound-condition", url: "https://docs.zizmor.sh/audits/#unsound-condition", relation: "overlaps" },
+    { tool: "poutine", rule: "if_always_true", url: "https://boostsecurityio.github.io/poutine/rules/if_always_true/", relation: "overlaps" },
+  ],
+  GHA047: [
+    { tool: "zizmor", rule: "unsound-contains", url: "https://docs.zizmor.sh/audits/#unsound-contains", relation: "equivalent" },
+  ],
+  GHA048: [
+    { tool: "zizmor", rule: "obfuscation", url: "https://docs.zizmor.sh/audits/#obfuscation", relation: "overlaps" },
+  ],
+  GHA049: [
+    { tool: "zizmor", rule: "artipacked", url: "https://docs.zizmor.sh/audits/#artipacked", relation: "equivalent" },
+    { tool: "octoscan", rule: "dangerous-artefact", url: "https://github.com/synacktiv/octoscan#dangerous-artefact", relation: "overlaps" },
+  ],
+  GHA050: [
+    { tool: "zizmor", rule: "cache-poisoning", url: "https://docs.zizmor.sh/audits/#cache-poisoning", relation: "overlaps" },
+  ],
+  GHA051: [
+    { tool: "zizmor", rule: "use-trusted-publishing", url: "https://docs.zizmor.sh/audits/#use-trusted-publishing", relation: "overlaps" },
+  ],
+  GHA052: [
+    { tool: "poutine", rule: "unverified_script_exec", url: "https://boostsecurityio.github.io/poutine/rules/unverified_script_exec/", relation: "equivalent" },
+    { tool: "scorecard", rule: "Pinned-Dependencies", url: "https://github.com/ossf/scorecard/blob/main/docs/checks.md#pinned-dependencies", relation: "overlaps" },
+  ],
+  GHA053: [
+    { tool: "zizmor", rule: "insecure-commands", url: "https://docs.zizmor.sh/audits/#insecure-commands", relation: "equivalent" },
+    { tool: "octoscan", rule: "unsecure-commands", url: "https://github.com/synacktiv/octoscan#unsecure-commands", relation: "equivalent" },
+  ],
+  GHA054: [
+    { tool: "zizmor", rule: "misfeature", url: "https://docs.zizmor.sh/audits/#misfeature", relation: "overlaps" },
+  ],
+  GHA055: [
+    { tool: "zizmor", rule: "superfluous-actions", url: "https://docs.zizmor.sh/audits/#superfluous-actions", relation: "overlaps" },
+  ],
+  GHA056: [
+    { tool: "zizmor", rule: "anonymous-definition", url: "https://docs.zizmor.sh/audits/#anonymous-definition", relation: "overlaps" },
+  ],
+  GHA057: [
+    { tool: "zizmor", rule: "dependabot-execution", url: "https://docs.zizmor.sh/audits/#dependabot-execution", relation: "equivalent" },
+  ],
+  GHA058: [
+    { tool: "zizmor", rule: "dependabot-cooldown", url: "https://docs.zizmor.sh/audits/#dependabot-cooldown", relation: "equivalent" },
+  ],
+  GHA059: [
+    { tool: "zizmor", rule: "ref-version-mismatch", url: "https://docs.zizmor.sh/audits/#ref-version-mismatch", relation: "equivalent" },
+  ],
+  GHA060: [
+    { tool: "zizmor", rule: "github-app", url: "https://docs.zizmor.sh/audits/#github-app", relation: "overlaps" },
+  ],
+  GHA061: [
+    { tool: "zizmor", rule: "forbidden-uses", url: "https://docs.zizmor.sh/audits/#forbidden-uses", relation: "equivalent" },
+  ],
+  GHA062: [
+    { tool: "zizmor", rule: "known-vulnerable-actions", url: "https://docs.zizmor.sh/audits/#known-vulnerable-actions", relation: "equivalent" },
+    { tool: "poutine", rule: "known_vulnerability_in_build_component", url: "https://boostsecurityio.github.io/poutine/rules/known_vulnerability_in_build_component/", relation: "equivalent" },
+    { tool: "octoscan", rule: "known-vulnerability", url: "https://github.com/synacktiv/octoscan#known-vulnerability", relation: "equivalent" },
+    { tool: "scorecard", rule: "Vulnerabilities", url: "https://github.com/ossf/scorecard/blob/main/docs/checks.md#vulnerabilities", relation: "overlaps" },
+  ],
+  GHA068: [
+    { tool: "zizmor", rule: "concurrency-limits", url: "https://docs.zizmor.sh/audits/#concurrency-limits", relation: "overlaps" },
+  ],
+};