@veleads/gtm 0.4.0 → 0.6.0

package/dist/cli.js

@@ -16,6 +16,8 @@ var IsoDate = z.iso.date();
 var IsoDateTime = z.iso.datetime({ offset: true });
 var Domain = z.string().regex(/^(?!-)[a-z0-9-]+(\.[a-z0-9-]+)+$/, "bare lowercase domain, e.g. acme.com");
 var Tier = z.enum(["A", "B", "C"]);
+var GitHubHandle = z.string().regex(/^@[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/, "GitHub handle like @username");
+var isGitHubHandle = (value) => !!value && GitHubHandle.safeParse(value).success;
 var Stage = z.enum([
   "intake",
   "icp",
@@ -33,7 +35,8 @@ var Approval = z.object({
   approved_by: z.string().min(1).nullable(),
   approved_at: IsoDate.nullable(),
   notes: z.string().optional(),
-  content_hash: z.string().regex(/^sha256:[0-9a-f]{16}$/).optional().describe("Fingerprint of the approved content, written by `gtm approve`. Never edit by hand.")
+  content_hash: z.string().regex(/^sha256:[0-9a-f]{16}$/).optional().describe("Fingerprint of the approved content, written by `gtm approve`. Never edit by hand."),
+  approved_via: z.string().url().optional().describe("Pull request whose review is the approval (GitHub mode). Written by `gtm approve --pr`.")
 }).refine(
   (a) => a.status !== "approved" || a.approved_by !== null && a.approved_at !== null,
   "approved requires approved_by and approved_at"
@@ -63,26 +66,43 @@ var ProjectFile = z2.object({
   status: z2.enum(["onboarding", "active", "paused", "closed"]),
   started_at: IsoDate,
   owners: z2.object({
-    gtm_engineer: z2.string().min(1),
-    sdrs: z2.array(z2.string().min(1)),
-    approver: z2.string().min(1).describe("Person who signs off ICP and copy for this project")
+    gtm_engineer: z2.string().min(1).describe("GitHub handle (@user) or name"),
+    sdrs: z2.array(z2.string().min(1)).describe("GitHub handles (@user) or names"),
+    approver: z2.string().min(1).describe("Signs off ICP and copy. A GitHub handle (@user) makes approvals PR reviews enforced by GitHub; a name records them by name")
   }),
   regions: z2.array(z2.string().min(2)).min(1).describe("Target regions, e.g. EU, UK, US"),
-  features: z2.record(z2.string(), z2.boolean()).default({}).describe("Opt-in core features, see FEATURES")
+  features: z2.record(z2.string(), z2.boolean()).default({}).describe("Opt-in core features, see FEATURES"),
+  tracker: z2.object({ kind: z2.enum(["github", "none"]) }).default({ kind: "none" }).describe("Where `gtm track` mirrors stages and gates. Git files stay the source of truth")
 });
 
 // ../schemas/src/icp.ts
 import { z as z3 } from "zod";
+var FirmographicFilters = z3.object({
+  industries: z3.array(z3.string()).optional(),
+  employee_count: IntRange.optional(),
+  revenue_usd: IntRange.optional(),
+  hq_countries: z3.array(z3.string().length(2)).optional().describe("ISO 3166-1 alpha-2"),
+  technologies_any: z3.array(z3.string()).optional(),
+  technologies_none: z3.array(z3.string()).optional(),
+  keywords_any: z3.array(z3.string()).optional(),
+  keywords_none: z3.array(z3.string()).optional()
+});
 var Firmographics = z3.object({
   industries: z3.array(z3.string()).default([]),
   employee_count: IntRange.optional(),
   revenue_usd: IntRange.optional(),
-  hq_countries: z3.array(z3.string().length(2)).default([]).describe("ISO 3166-1 alpha-2"),
+  hq_countries: z3.array(z3.string().length(2)).default([]),
   technologies_any: z3.array(z3.string()).default([]),
   technologies_none: z3.array(z3.string()).default([]),
   keywords_any: z3.array(z3.string()).default([]),
   keywords_none: z3.array(z3.string()).default([])
 });
+var IcpSegmentSpec = z3.object({
+  id: Slug,
+  description: z3.string().min(1),
+  firmographics: FirmographicFilters.default({}),
+  personas: z3.array(Slug).min(1).optional().describe("Restrict to these persona ids; default: all personas")
+});
 var IcpSegment = z3.object({
   id: Slug,
   description: z3.string().min(1),
@@ -96,11 +116,22 @@ var IcpPersona = z3.object({
   seniorities: z3.array(z3.enum(["c_level", "vp", "head", "director", "manager", "senior", "entry"])).default([]),
   departments: z3.array(z3.string()).default([])
 });
+var FILTER_KEYS = Object.keys(FirmographicFilters.shape);
+function mergeFilters(core, segment) {
+  const merged = {};
+  for (const key of FILTER_KEYS) {
+    const value = segment?.[key] !== void 0 ? segment[key] : core?.[key];
+    if (value !== void 0) merged[key] = value;
+  }
+  return Firmographics.parse(merged);
+}
+var hasAnyFilter = (f) => f.industries.length + f.hq_countries.length + f.technologies_any.length + f.keywords_any.length > 0 || !!f.employee_count || !!f.revenue_usd;
 var IcpFile = z3.object({
   version: z3.literal(FILE_VERSIONS.icp),
   project_id: Slug,
   approval: Approval,
-  segments: z3.array(IcpSegment).min(1),
+  core: z3.object({ firmographics: FirmographicFilters.default({}) }).optional().describe("Profile every segment shares. Segments only add or replace what differs"),
+  segments: z3.array(IcpSegmentSpec).min(1),
   personas: z3.array(IcpPersona).min(1),
   exclusions: z3.object({
     domains: z3.array(Domain).default([]),
@@ -113,7 +144,39 @@ var IcpFile = z3.object({
     const dupes = ids.filter((id, i) => ids.indexOf(id) !== i);
     if (dupes.length) ctx.addIssue({ code: "custom", path: [key], message: `duplicate ids: ${dupes.join(", ")}` });
   }
+  const personaIds = new Set(icp.personas.map((p) => p.id));
+  icp.segments.forEach((s, i) => {
+    for (const p of s.personas ?? []) {
+      if (!personaIds.has(p)) ctx.addIssue({ code: "custom", path: ["segments", i, "personas"], message: `unknown persona "${p}"` });
+    }
+    let resolved;
+    try {
+      resolved = mergeFilters(icp.core?.firmographics, s.firmographics);
+    } catch {
+      return;
+    }
+    if (!hasAnyFilter(resolved)) {
+      ctx.addIssue({ code: "custom", path: ["segments", i, "firmographics"], message: `segment "${s.id}" has no filters (core + segment): it would match every company` });
+    }
+    const range = resolved.employee_count;
+    if (range?.min !== void 0 && range.max !== void 0 && range.min > range.max) {
+      ctx.addIssue({ code: "custom", path: ["segments", i, "firmographics", "employee_count"], message: `segment "${s.id}" resolves to min > max` });
+    }
+  });
 });
+function resolveIcp(icp) {
+  const allPersonas = icp.personas.map((p) => p.id);
+  return {
+    exclusions: icp.exclusions,
+    segments: icp.segments.map((s) => ({
+      id: s.id,
+      description: s.description,
+      firmographics: mergeFilters(icp.core?.firmographics, s.firmographics),
+      personas: s.personas ?? allPersonas,
+      overrides: FILTER_KEYS.filter((k) => s.firmographics?.[k] !== void 0)
+    }))
+  };
+}
 
 // ../schemas/src/signals-config.ts
 import { z as z4 } from "zod";
@@ -148,6 +211,10 @@ var Enrichment = z5.object({
   max_contacts_per_account: z5.number().int().min(1).max(10),
   cache_ttl_days: z5.number().int().positive()
 });
+var Tam = z5.object({
+  source: Slug.describe("Account source adapter (mock-accounts for local proofs; real providers in .gtm/providers/)"),
+  max_accounts_per_segment: z5.number().int().positive().max(1e5).default(500)
+});
 var Budget = z5.object({
   currency: z5.literal("USD"),
   max_total: z5.number().positive().describe("Hard cap for this campaign; jobs stop when reached"),
@@ -194,6 +261,7 @@ var CampaignConfig = z5.object({
   owner: z5.string().min(1),
   stage: Stage.describe("The stage currently being worked on"),
   tam_id: Slug,
+  tam: Tam.optional().describe("How `gtm job tam` builds the TAM"),
   segments: z5.array(Slug).min(1).describe("Segment ids from icp.yaml"),
   personas: z5.array(Slug).min(1).describe("Persona ids from icp.yaml"),
   enrichment: Enrichment,
@@ -343,10 +411,155 @@ function copyContentHash(markdown) {
   return `sha256:${createHash("sha256").update(normalized).digest("hex").slice(0, 16)}`;
 }
 
+// ../schemas/src/jobs.ts
+import { z as z10 } from "zod";
+var JOB_NAMES = { tam: "gtm-tam" };
+var JobContext = z10.object({
+  project_id: Slug,
+  campaign_id: Slug,
+  triggered_by: z10.string().min(1),
+  core_version: z10.string().min(1),
+  git_sha: z10.string().nullable(),
+  config_hash: z10.string().min(1)
+});
+var TamJobInput = z10.object({
+  ctx: JobContext,
+  tam_id: Slug,
+  source: Slug.describe("Account source adapter, e.g. mock-accounts"),
+  max_accounts_per_segment: z10.number().int().positive().max(1e5),
+  segments: z10.array(IcpSegment).min(1),
+  exclusions: z10.object({ domains: z10.array(Domain), industries: z10.array(z10.string()), hq_countries: z10.array(z10.string()) }),
+  budget_usd: z10.number().nonnegative()
+});
+var TamJobResult = z10.object({
+  run_id: z10.uuid(),
+  segments: z10.array(z10.object({
+    segment_id: Slug,
+    found: z10.number().int(),
+    inserted: z10.number().int(),
+    updated: z10.number().int(),
+    excluded: z10.number().int(),
+    reachable: z10.number().int(),
+    active: z10.number().int()
+  })),
+  totals: z10.object({ tam: z10.number().int(), reachable: z10.number().int(), active: z10.number().int() }),
+  cost_usd: z10.number().nonnegative()
+});
+
+// src/commands/approve.ts
+import { parse } from "yaml";
+
+// src/github.ts
+import { spawnSync } from "child_process";
+function repoFromGit(root2) {
+  const res = spawnSync("git", ["remote", "get-url", "origin"], { cwd: root2, encoding: "utf8" });
+  return res.status === 0 ? parseRepoUrl(res.stdout.trim()) : null;
+}
+function parseRepoUrl(url) {
+  const m = url.match(/github\.com[/:]([^/]+)\/([^/]+?)(?:\.git)?\/?$/);
+  return m ? { owner: m[1], repo: m[2] } : null;
+}
+function githubToken() {
+  const env = process.env.GH_TOKEN ?? process.env.GITHUB_TOKEN;
+  if (env) return env;
+  const gh = spawnSync("gh", ["auth", "token"], { encoding: "utf8" });
+  return gh.status === 0 && gh.stdout.trim() ? gh.stdout.trim() : null;
+}
+var login = (handle) => handle.replace(/^@/, "").toLowerCase();
+var GitHubError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "GitHubError";
+  }
+  status;
+};
+var GitHubApi = class _GitHubApi {
+  constructor(repo, token, fetchImpl = fetch) {
+    this.repo = repo;
+    this.token = token;
+    this.fetchImpl = fetchImpl;
+  }
+  repo;
+  token;
+  fetchImpl;
+  /** Resolves repo + token from the working copy and environment; null with a reason if unavailable. */
+  static fromRepo(root2, fetchImpl = fetch) {
+    const repo = repoFromGit(root2);
+    if (!repo) return "no GitHub remote: `git remote get-url origin` must point to github.com";
+    const token = githubToken();
+    if (!token) return "no GitHub token: run `gh auth login`, or set GH_TOKEN / GITHUB_TOKEN";
+    return new _GitHubApi(repo, token, fetchImpl);
+  }
+  /** Path relative to /repos/{owner}/{repo} when it starts with "repo:", else absolute (e.g. /user). */
+  async request(method, path, body) {
+    const url = path.startsWith("repo:") ? `https://api.github.com/repos/${this.repo.owner}/${this.repo.repo}${path.slice(5)}` : `https://api.github.com${path}`;
+    const res = await this.fetchImpl(url, {
+      method,
+      headers: {
+        Accept: "application/vnd.github+json",
+        Authorization: `Bearer ${this.token}`,
+        "X-GitHub-Api-Version": "2022-11-28",
+        ...body ? { "Content-Type": "application/json" } : {}
+      },
+      body: body ? JSON.stringify(body) : void 0
+    });
+    if (!res.ok) throw new GitHubError(res.status, `GitHub ${method} ${path.replace(/^repo:/, "")}: ${res.status} ${await res.text()}`);
+    return res.status === 204 ? void 0 : await res.json();
+  }
+  /** Blob URL for a repo file on the default branch, for links in issue bodies. */
+  fileUrl(path) {
+    return `https://github.com/${this.repo.owner}/${this.repo.repo}/blob/HEAD/${path}`;
+  }
+};
+
+// src/github-approval.ts
+function prNumber(ref) {
+  const m = ref.match(/(?:^#?|\/pull\/)(\d+)\/?$/);
+  return m ? Number(m[1]) : null;
+}
+function latestStateBy(reviews, approver) {
+  return reviews.filter((r) => r.user && login(r.user.login) === login(approver) && r.state !== "COMMENTED").at(-1);
+}
+async function verifyPrApproval(api, ref, approver, path) {
+  const n = prNumber(ref);
+  if (!n) return `--pr must be a pull request number or URL (got "${ref}")`;
+  const pr = await api.request("GET", `repo:/pulls/${n}`);
+  const files = await api.request("GET", `repo:/pulls/${n}/files?per_page=100`);
+  if (!files.some((f) => f.filename === path)) return `PR #${n} does not change ${path}`;
+  if (login(pr.user.login) === login(approver)) {
+    return `PR #${n} was opened by ${approver}, and GitHub doesn't let authors approve their own PRs. The PR must be opened by someone else (e.g. the GTM engineer or the agent's account) and approved by ${approver}.`;
+  }
+  const reviews = await api.request("GET", `repo:/pulls/${n}/reviews?per_page=100`);
+  const review = latestStateBy(reviews, approver);
+  if (!review || review.state !== "APPROVED") return `${approver} has not approved PR #${n} (latest review: ${review?.state ?? "none"})`;
+  if (review.commit_id !== pr.head.sha) return `${approver} approved an older commit of PR #${n}; the PR changed since. Ask for a fresh approval.`;
+  const file = await api.request("GET", `repo:/contents/${path}?ref=${pr.head.sha}`);
+  return {
+    prUrl: pr.html_url,
+    reviewer: `@${review.user.login}`,
+    approvedAt: review.submitted_at.slice(0, 10),
+    approvedContent: Buffer.from(file.content, file.encoding).toString("utf8")
+  };
+}
+async function verifyRecordedApproval(api, prUrl, approver, path, pinnedHash, hashOf) {
+  const n = prNumber(prUrl);
+  if (!n) return `approved_via is not a pull request URL: ${prUrl}`;
+  if (!prUrl.includes(`/${api.repo.owner}/${api.repo.repo}/pull/`)) return `approved_via points to another repository: ${prUrl}`;
+  const reviews = await api.request("GET", `repo:/pulls/${n}/reviews?per_page=100`);
+  const review = latestStateBy(reviews, approver);
+  if (review?.state !== "APPROVED") return `${approver}'s latest review on PR #${n} is ${review?.state ?? "missing"}, not APPROVED`;
+  const file = await api.request("GET", `repo:/contents/${path}?ref=${review.commit_id}`);
+  const reviewed = hashOf(Buffer.from(file.content, file.encoding).toString("utf8"));
+  return reviewed === pinnedHash ? true : `${path} at the commit ${approver} approved (${review.commit_id.slice(0, 7)}) has content ${reviewed}, but ${pinnedHash ?? "no hash"} is pinned`;
+}
+
 // src/commands/approve.ts
 var USAGE = `Usage:
-  gtm approve icp --by "<Name (role)>" [--notes "<what was approved>"] [--date YYYY-MM-DD]
-  gtm approve copy <campaign> --by "<Name (role)>" [--notes "<what was approved>"] [--date YYYY-MM-DD]`;
+  gtm approve icp --pr <number> [--notes ".."]                   (approver is a GitHub @handle)
+  gtm approve copy <campaign> --pr <number> [--notes ".."]
+  gtm approve icp --by "<Name (role)>" [--notes ".."] [--date YYYY-MM-DD]   (approver is a name)
+  gtm approve copy <campaign> --by "<Name (role)>" [--notes ".."] [--date YYYY-MM-DD]`;
 function load(file) {
   if (!existsSync(file)) {
     console.error(`${file} not found: run this from the root of a project repo`);
@@ -362,6 +575,7 @@ function load(file) {
 function pin(file, doc, path, schema, hash, opts) {
   const approval = { status: "approved", approved_by: opts.by, approved_at: opts.date, content_hash: hash };
   if (opts.notes) approval.notes = opts.notes;
+  if (opts.via) approval.approved_via = opts.via;
   const candidate = doc.toJS();
   let target = candidate;
   for (const key of path.slice(0, -1)) target = target[key] ??= {};
@@ -373,94 +587,469 @@ function pin(file, doc, path, schema, hash, opts) {
     return false;
   }
   for (const [key, value] of Object.entries(approval)) doc.setIn([...path, key], value);
+  if (!opts.via) doc.deleteIn([...path, "approved_via"]);
   writeFileSync(file, doc.toString({ flowCollectionPadding: false, lineWidth: 0 }));
   return true;
 }
-function runApprove(root2, args2, opts) {
+async function runApprove(root2, args2, opts) {
   const [gate, campaign] = args2;
   if (gate !== "icp" && gate !== "copy") {
     console.error(USAGE);
     if (gate) console.error(`The "${gate}" gate is recorded by hand in config.yaml \u2192 gates (AGENTS.md section 4).`);
     return false;
   }
-  const by = opts.by?.trim();
-  if (!by) {
-    console.error('--by is required: the human who approved, e.g. --by "Maria Chen (VP Marketing)"');
+  if (gate === "copy" && !campaign) {
+    console.error(USAGE);
     return false;
   }
-  const date = opts.date ?? (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
-  if (!IsoDate.safeParse(date).success) {
-    console.error(`--date must be YYYY-MM-DD (got "${date}")`);
+  const approver = (existsSync(join(root2, "project.yaml")) ? parse(readFileSync(join(root2, "project.yaml"), "utf8")) : null)?.owners?.approver;
+  const githubMode = isGitHubHandle(approver);
+  const contentPath = gate === "icp" ? "context/icp.yaml" : `campaigns/${campaign}/copy.md`;
+  const contentFile = join(root2, contentPath);
+  if (!existsSync(contentFile)) {
+    console.error(`${contentPath} not found`);
     return false;
   }
-  if (gate === "icp") {
-    const file2 = join(root2, "context", "icp.yaml");
-    const doc2 = load(file2);
-    if (!doc2) return false;
-    const hash2 = icpContentHash(doc2.toJS());
-    if (!pin(file2, doc2, ["approval"], IcpFile, hash2, { ...opts, by, date })) return false;
-    console.log(`ICP approved by ${by} on ${date} (content ${hash2}).`);
-    console.log("Commit context/icp.yaml together with the run log that quotes the approval.");
-    return true;
+  const local = readFileSync(contentFile, "utf8");
+  if (gate === "copy" && !local.split("\n").some((l) => l.trim() && !/^\s*(>|#)/.test(l))) {
+    console.error(`${contentPath} has no copy yet`);
+    return false;
   }
-  if (!campaign) {
-    console.error(USAGE);
+  const hashOf = (text) => gate === "icp" ? icpContentHash(parse(text)) : copyContentHash(text);
+  let by, date, via;
+  if (githubMode) {
+    if (!opts.pr) {
+      console.error(`The approver is ${approver} (GitHub mode): the approval is their APPROVED review on a pull request.`);
+      console.error(`Open a PR with ${contentPath}, have ${approver} approve it on GitHub, then run: npx gtm approve ${gate}${campaign ? ` ${campaign}` : ""} --pr <number>`);
+      return false;
+    }
+    const api = GitHubApi.fromRepo(root2, opts.fetchImpl);
+    if (typeof api === "string") {
+      console.error(`Cannot verify on GitHub: ${api}`);
+      return false;
+    }
+    const verified = await verifyPrApproval(api, opts.pr, approver, contentPath);
+    if (typeof verified === "string") {
+      console.error(verified);
+      return false;
+    }
+    if (hashOf(verified.approvedContent) !== hashOf(local)) {
+      console.error(`Your local ${contentPath} differs from the version ${approver} approved on the PR. Check out / pull the PR's latest commit, then run this again.`);
+      return false;
+    }
+    by = verified.reviewer;
+    date = verified.approvedAt;
+    via = verified.prUrl;
+  } else {
+    if (opts.pr) {
+      console.error(`--pr needs a GitHub approver: set project.yaml \u2192 owners.approver to their @handle, or record with --by.`);
+      return false;
+    }
+    by = opts.by?.trim() ?? "";
+    if (!by) {
+      console.error('--by is required: the human who approved, e.g. --by "Maria Chen (VP Marketing)"');
+      return false;
+    }
+    date = opts.date ?? (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+    if (!IsoDate.safeParse(date).success) {
+      console.error(`--date must be YYYY-MM-DD (got "${date}")`);
+      return false;
+    }
+  }
+  const hash = hashOf(local);
+  const file = gate === "icp" ? contentFile : join(root2, "campaigns", campaign, "config.yaml");
+  const doc = load(file);
+  if (!doc) return false;
+  const path = gate === "icp" ? ["approval"] : ["gates", "copy"];
+  if (!pin(file, doc, path, gate === "icp" ? IcpFile : CampaignConfig, hash, { ...opts, by, date, via })) return false;
+  const what = gate === "icp" ? "ICP" : `Copy for ${campaign}`;
+  console.log(`${what} approved by ${by} on ${date}${via ? ` via ${via}` : ""} (content ${hash}).`);
+  console.log(`Commit ${gate === "icp" ? "context/icp.yaml" : `campaigns/${campaign}/config.yaml and copy.md`} together with the run log that quotes the approval${via ? "" : ""}.`);
+  if (via) console.log(`Then close the tracker item: npx gtm track gate-done ${gate}${campaign ? ` ${campaign}` : ""}`);
+  return true;
+}
+
+// src/commands/icp.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { join as join2 } from "path";
+import { parse as parse2 } from "yaml";
+var LABELS = {
+  industries: "industries",
+  employee_count: "employees",
+  revenue_usd: "revenue (USD)",
+  hq_countries: "HQ countries",
+  technologies_any: "tech (any of)",
+  technologies_none: "tech (none of)",
+  keywords_any: "keywords (any)",
+  keywords_none: "keywords (none)"
+};
+function show(value) {
+  if (Array.isArray(value)) return value.length ? value.join(", ") : null;
+  if (value && typeof value === "object") {
+    const r = value;
+    return r.min !== void 0 && r.max !== void 0 ? `${r.min}\u2013${r.max}` : r.min !== void 0 ? `\u2265 ${r.min}` : r.max !== void 0 ? `\u2264 ${r.max}` : null;
+  }
+  return null;
+}
+function runIcp(root2) {
+  const file = join2(root2, "context", "icp.yaml");
+  if (!existsSync2(file)) {
+    console.error("context/icp.yaml not found: run this from the root of a project repo");
     return false;
   }
-  const dir = join(root2, "campaigns", campaign);
-  const copyFile = join(dir, "copy.md");
-  if (!existsSync(copyFile)) {
-    console.error(`campaigns/${campaign}/copy.md not found`);
+  const parsed = IcpFile.safeParse(parse2(readFileSync2(file, "utf8")));
+  if (!parsed.success) {
+    console.error("context/icp.yaml is not valid (run `npx gtm validate` for details):");
+    for (const i of parsed.error.issues) console.error(`  \u2717 ${i.path.join(".") || "(root)"}: ${i.message}`);
     return false;
   }
-  const copy = readFileSync(copyFile, "utf8");
-  if (!copy.split("\n").some((l) => l.trim() && !/^\s*(>|#)/.test(l))) {
-    console.error(`campaigns/${campaign}/copy.md has no copy yet`);
+  const icp = parsed.data;
+  const resolved = resolveIcp(icp);
+  console.log(`ICP for ${icp.project_id} \xB7 approval: ${icp.approval.status}${icp.approval.approved_by ? ` by ${icp.approval.approved_by}` : ""}`);
+  const core = icp.core?.firmographics ?? {};
+  const coreLines = Object.keys(LABELS).map((k) => [LABELS[k], show(core[k])]).filter((line) => line[1] !== null);
+  console.log(`
+Core (every segment): ${coreLines.length ? "" : "none (each segment defines its own filters)"}`);
+  for (const [label, v] of coreLines) console.log(`  ${label.padEnd(16)}${v}`);
+  for (const s of resolved.segments) {
+    console.log(`
+Segment ${s.id}: ${s.description}`);
+    for (const k of Object.keys(LABELS)) {
+      const v = show(s.firmographics[k]);
+      if (v) console.log(`  ${LABELS[k].padEnd(16)}${v}${s.overrides.includes(k) ? core[k] !== void 0 ? "   \u2190 segment (replaces core)" : "   \u2190 segment" : ""}`);
+    }
+    console.log(`  ${"personas".padEnd(16)}${s.personas.join(", ")}${s.personas.length < icp.personas.length ? "   \u2190 restricted" : ""}`);
+  }
+  const x = resolved.exclusions;
+  const ex = [x.domains.length && `${x.domains.length} domain(s)`, x.industries.length && `industries: ${x.industries.join(", ")}`, x.hq_countries.length && `countries: ${x.hq_countries.join(", ")}`].filter(Boolean);
+  console.log(`
+Exclusions (all segments): ${ex.length ? ex.join(" \xB7 ") : "none"}`);
+  return true;
+}
+
+// src/commands/github.ts
+var LABELS2 = [
+  { name: "gtm", color: "5319e7", description: "Managed by gtm track" },
+  { name: "campaign", color: "1d76db", description: "gtm campaign tracker" },
+  { name: "gate", color: "d93f0b", description: "gtm approval gate (hard stop)" },
+  ...["icp", "copy", "launch"].map((g) => ({ name: `gate:${g}`, color: "d93f0b", description: `gtm ${g} gate` })),
+  ...Stage.options.map((s) => ({ name: `stage:${s}`, color: "c5def5", description: `gtm stage ${s}` }))
+];
+var RULESET_NAME = "gtm: approvals";
+function rulesetBody() {
+  return {
+    name: RULESET_NAME,
+    target: "branch",
+    enforcement: "active",
+    conditions: { ref_name: { include: ["~DEFAULT_BRANCH"], exclude: [] } },
+    rules: [
+      { type: "deletion" },
+      { type: "non_fast_forward" },
+      {
+        type: "pull_request",
+        parameters: {
+          required_approving_review_count: 0,
+          require_code_owner_review: true,
+          // Off on purpose: `gtm approve --pr` commits the approval record to the PR after the review.
+          // Content after approval is guarded by the pinned hash, re-checked by `gtm validate
+          // --verify-github` against the exact reviewed commit (a required CI check).
+          dismiss_stale_reviews_on_push: false,
+          require_last_push_approval: false,
+          required_review_thread_resolution: false
+        }
+      },
+      { type: "required_status_checks", parameters: { strict_required_status_checks_policy: false, required_status_checks: [{ context: "check" }] } }
+    ]
+  };
+}
+async function runGithub(root2, args2, opts) {
+  if (args2[0] !== "setup") {
+    console.error("Usage: gtm github setup [--apply]");
     return false;
   }
-  const file = join(dir, "config.yaml");
-  const doc = load(file);
-  if (!doc) return false;
-  const hash = copyContentHash(copy);
-  if (!pin(file, doc, ["gates", "copy"], CampaignConfig, hash, { ...opts, by, date })) return false;
-  console.log(`Copy for ${campaign} approved by ${by} on ${date} (content ${hash}).`);
-  console.log(`Commit campaigns/${campaign}/config.yaml and copy.md together with the run log that quotes the approval.`);
+  const api = GitHubApi.fromRepo(root2, opts.fetchImpl);
+  if (typeof api === "string") {
+    console.error(api);
+    return false;
+  }
+  const repo = `${api.repo.owner}/${api.repo.repo}`;
+  console.log(`GitHub setup for ${repo}${opts.apply ? "" : " (plan only: re-run with --apply)"}:`);
+  console.log(`  \u2022 labels: ${LABELS2.map((l) => l.name).join(", ")}`);
+  console.log(`  \u2022 ruleset "${RULESET_NAME}" on the default branch: PR required, review from CODEOWNERS required, CI job "check" must pass, no force-push or deletion`);
+  console.log("  \u2022 CODEOWNERS is maintained by `npx gtm sync` from project.yaml \u2192 owners.approver");
+  if (!opts.apply) return true;
+  const existing = new Set((await api.request("GET", "repo:/labels?per_page=100")).map((l) => l.name));
+  for (const label of LABELS2) {
+    if (existing.has(label.name)) continue;
+    await api.request("POST", "repo:/labels", label);
+    console.log(`  + label ${label.name}`);
+  }
+  try {
+    const rulesets = await api.request("GET", "repo:/rulesets");
+    const found = rulesets.find((r) => r.name === RULESET_NAME);
+    if (found) await api.request("PUT", `repo:/rulesets/${found.id}`, rulesetBody());
+    else await api.request("POST", "repo:/rulesets", rulesetBody());
+    console.log(`  ${found ? "~ updated" : "+ created"} ruleset "${RULESET_NAME}"`);
+  } catch (e) {
+    if (e instanceof GitHubError && (e.status === 403 || e.status === 404)) {
+      console.error(`  \u2717 could not create the ruleset (${e.status}). Rulesets on private repos need a paid GitHub plan (Team/Pro), and the token needs admin rights.`);
+      console.error("    Without it GitHub still requests the approver's review via CODEOWNERS, and `gtm validate --verify-github` in CI still verifies every approval.");
+      return false;
+    }
+    throw e;
+  }
+  console.log("Done. In CI, `npx gtm validate --verify-github` checks each recorded approval against GitHub.");
+  return true;
+}
+
+// src/commands/track.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
+import { join as join3 } from "path";
+import { parse as parse3 } from "yaml";
+
+// src/tracker/github.ts
+var marker = (key) => `<!-- gtm-key: ${key} -->`;
+var BASE_LABEL = "gtm";
+var GitHubTracker = class {
+  constructor(api) {
+    this.api = api;
+  }
+  api;
+  kind = "github";
+  async find(key) {
+    for (let page = 1; page <= 10; page++) {
+      const issues = await this.api.request("GET", `repo:/issues?labels=${BASE_LABEL}&state=all&per_page=100&page=${page}`);
+      const hit = issues.find((i) => !i.pull_request && i.body?.includes(marker(key)));
+      if (hit) return hit;
+      if (issues.length < 100) return null;
+    }
+    return null;
+  }
+  async upsert(item) {
+    const body = `${item.body}
+
+${marker(item.key)}`;
+    const wanted = [.../* @__PURE__ */ new Set([BASE_LABEL, ...item.labels])];
+    const existing = await this.find(item.key);
+    if (!existing) {
+      const created = await this.api.request("POST", "repo:/issues", { title: item.title, body, labels: wanted, assignees: item.assignees ?? [] });
+      return { key: item.key, url: created.html_url, created: true };
+    }
+    const exclusive = item.exclusiveLabelPrefixes ?? [];
+    const kept = existing.labels.map((l) => l.name).filter((n) => !exclusive.some((p) => n.startsWith(p)) || wanted.includes(n));
+    await this.api.request("PATCH", `repo:/issues/${existing.number}`, {
+      title: item.title,
+      body,
+      state: "open",
+      labels: [.../* @__PURE__ */ new Set([...kept, ...wanted])],
+      ...item.assignees ? { assignees: item.assignees } : {}
+    });
+    return { key: item.key, url: existing.html_url, created: false };
+  }
+  async comment(key, text) {
+    const issue = await this.find(key);
+    if (!issue) throw new Error(`no tracked issue for "${key}"`);
+    await this.api.request("POST", `repo:/issues/${issue.number}/comments`, { body: text });
+  }
+  async close(key, text) {
+    const issue = await this.find(key);
+    if (!issue) throw new Error(`no tracked issue for "${key}"`);
+    if (text) await this.api.request("POST", `repo:/issues/${issue.number}/comments`, { body: text });
+    await this.api.request("PATCH", `repo:/issues/${issue.number}`, { state: "closed", state_reason: "completed" });
+  }
+};
+
+// src/tracker/none.ts
+var noneTracker = {
+  kind: "none",
+  async upsert(item) {
+    return { key: item.key, url: "", created: false };
+  },
+  async comment() {
+  },
+  async close() {
+  }
+};
+
+// src/tracker/index.ts
+function createTracker(kind, root2, fetchImpl = fetch) {
+  if (kind === "none") return noneTracker;
+  if (kind === "github") {
+    const api = GitHubApi.fromRepo(root2, fetchImpl);
+    return typeof api === "string" ? `tracker github: ${api}` : new GitHubTracker(api);
+  }
+  return `unknown tracker kind "${kind}" (supported: github, none)`;
+}
+
+// src/commands/track.ts
+var GATES = ["icp", "copy", "launch"];
+var USAGE2 = `Usage:
+  gtm track stage <campaign>
+  gtm track gate-open <icp|copy|launch> [campaign] [--pr <number>]
+  gtm track gate-done <icp|copy|launch> [campaign]`;
+function readYaml(file) {
+  return existsSync3(file) ? parse3(readFileSync3(file, "utf8")) : null;
+}
+var handles = (...values2) => values2.filter(isGitHubHandle).map((h) => h.slice(1));
+async function upsert(ctx, item) {
+  try {
+    const res = await ctx.tracker.upsert(item);
+    return res.url;
+  } catch (e) {
+    if (e instanceof GitHubError && e.status === 422 && item.assignees?.length) {
+      console.log(`  ! could not assign ${item.assignees.map((a) => "@" + a).join(", ")} (not a collaborator?): created unassigned`);
+      return (await ctx.tracker.upsert({ ...item, assignees: [] })).url;
+    }
+    throw e;
+  }
+}
+function gateKey(gate, campaign) {
+  return gate === "icp" ? "gate:icp" : `gate:${gate}:${campaign}`;
+}
+function gateFile(gate, campaign) {
+  return gate === "icp" ? "context/icp.yaml" : `campaigns/${campaign}/config.yaml`;
+}
+function gateApproval(root2, gate, campaign) {
+  const doc = readYaml(join3(root2, gateFile(gate, campaign)));
+  return gate === "icp" ? doc?.approval : doc?.gates?.[gate];
+}
+async function trackStage(ctx, campaign) {
+  const cfg = campaign ? readYaml(join3(ctx.root, "campaigns", campaign, "config.yaml")) : null;
+  if (!campaign || !cfg) {
+    console.error(campaign ? `campaigns/${campaign}/config.yaml not found` : USAGE2);
+    return false;
+  }
+  const current = Stage.safeParse(cfg.stage).success ? cfg.stage : null;
+  if (!current) {
+    console.error(`campaigns/${campaign}/config.yaml has no valid stage`);
+    return false;
+  }
+  const idx = Stage.options.indexOf(current);
+  const checklist = Stage.options.map((s, i) => `- [${i < idx ? "x" : " "}] ${s}${s === current ? "  \u2190 current" : ""}`).join("\n");
+  const url = await upsert(ctx, {
+    key: `campaign:${campaign}`,
+    title: `Campaign: ${campaign}`,
+    body: `**Stage: \`${current}\`** (source of truth: \`campaigns/${campaign}/config.yaml\`)
+
+${checklist}
+
+Brief: \`campaigns/${campaign}/brief.md\`. Counts and decisions only in this issue: never lead data.`,
+    labels: ["campaign", `stage:${current}`],
+    exclusiveLabelPrefixes: ["stage:"],
+    assignees: handles(cfg.owner, ctx.project?.owners?.gtm_engineer)
+  });
+  if (url) await ctx.tracker.comment(`campaign:${campaign}`, `Stage \u2192 \`${current}\``);
+  console.log(url ? `tracked campaign ${campaign} at stage ${current}: ${url}` : `tracker none: skipped (campaign ${campaign} at ${current})`);
   return true;
 }
+var GATE_TEXT = {
+  icp: { title: "ICP sign-off", review: "segments + filters, personas, exclusions, signals with weights, expected TAM range (`context/icp.md`, `context/icp.yaml`, `context/signals.yaml`)" },
+  copy: { title: "Copy sign-off", review: "every step of every variant in `copy.md`, rendered with one realistic fictional example" },
+  launch: { title: "Launch go/no-go", review: "`qa.md` result, leads by tier, daily volume, spend so far, paused sender campaign" }
+};
+async function gateOpen(ctx, gate, campaign, pr) {
+  if (gate !== "icp" && !campaign) {
+    console.error(USAGE2);
+    return false;
+  }
+  const owners = ctx.project?.owners ?? {};
+  const approver = gate === "launch" ? owners.gtm_engineer : owners.approver;
+  const how = isGitHubHandle(approver) ? `**${approver}**: review and approve the pull request${pr ? ` #${pr}` : ""} on GitHub. Then the agent records it with \`npx gtm approve ${gate === "icp" ? "icp" : `${gate} ${campaign}`} --pr <number>\`.` : `Approver **${approver ?? "(not set)"}**: reply with an explicit approval; it is recorded with \`npx gtm approve ... --by "<name (role)>"\`.`;
+  const key = gateKey(gate, campaign);
+  const url = await upsert(ctx, {
+    key,
+    title: `${GATE_TEXT[gate].title}${campaign ? `: ${campaign}` : ""}`,
+    body: `**Hard stop.** Nothing moves past this gate until it is approved.
+
+Review: ${GATE_TEXT[gate].review}.
+
+${how}
+
+Source of truth: \`${gateFile(gate, campaign)}\`.`,
+    labels: ["gate", `gate:${gate}`],
+    assignees: handles(approver)
+  });
+  console.log(url ? `opened ${GATE_TEXT[gate].title}: ${url}` : `tracker none: skipped (${key})`);
+  return true;
+}
+async function gateDone(ctx, gate, campaign) {
+  if (gate !== "icp" && !campaign) {
+    console.error(USAGE2);
+    return false;
+  }
+  const approval = gateApproval(ctx.root, gate, campaign);
+  if (approval?.status !== "approved") {
+    console.error(`${gateFile(gate, campaign)} says this gate is "${approval?.status ?? "missing"}": record the approval first; the tracker only mirrors it.`);
+    return false;
+  }
+  const via = approval.approved_via ? ` via ${approval.approved_via}` : "";
+  if (ctx.tracker.kind === "none") {
+    console.log(`tracker none: skipped (${gateKey(gate, campaign)})`);
+    return true;
+  }
+  await ctx.tracker.close(gateKey(gate, campaign), `\u2705 Approved by ${approval.approved_by} on ${approval.approved_at}${via}.`);
+  console.log(`closed ${GATE_TEXT[gate].title}${campaign ? `: ${campaign}` : ""}`);
+  return true;
+}
+async function runTrack(root2, args2, opts = {}) {
+  const [action, a1, a2] = args2;
+  const project = readYaml(join3(root2, "project.yaml"));
+  if (!project) {
+    console.error("project.yaml not found: run this from the root of a project repo");
+    return false;
+  }
+  const tracker = createTracker(project.tracker?.kind ?? "none", root2, opts.fetchImpl);
+  if (typeof tracker === "string") {
+    console.error(tracker);
+    return false;
+  }
+  const ctx = { root: root2, project, tracker };
+  try {
+    if (action === "stage") return await trackStage(ctx, a1);
+    if ((action === "gate-open" || action === "gate-done") && GATES.includes(a1)) {
+      return action === "gate-open" ? await gateOpen(ctx, a1, a2, opts.pr) : await gateDone(ctx, a1, a2);
+    }
+    console.error(USAGE2);
+    return false;
+  } catch (e) {
+    console.error(`tracker error: ${e.message}`);
+    return false;
+  }
+}
 
 // src/commands/init.ts
-import { spawnSync } from "child_process";
-import { appendFileSync, existsSync as existsSync4, readFileSync as readFileSync5 } from "fs";
-import { basename, join as join6, relative as relative2, resolve } from "path";
+import { spawnSync as spawnSync2 } from "child_process";
+import { appendFileSync, existsSync as existsSync6, readFileSync as readFileSync7 } from "fs";
+import { basename, join as join8, relative as relative2, resolve } from "path";
 
 // src/paths.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
-import { dirname, join as join2 } from "path";
+import { existsSync as existsSync4, readFileSync as readFileSync4 } from "fs";
+import { dirname, join as join4 } from "path";
 import { fileURLToPath } from "url";
-var pkgRoot = join2(dirname(fileURLToPath(import.meta.url)), "..");
+var pkgRoot = join4(dirname(fileURLToPath(import.meta.url)), "..");
 var PACKAGE_NAME = "@veleads/gtm";
-var GTM_VERSION = JSON.parse(readFileSync2(join2(pkgRoot, "package.json"), "utf8")).version;
+var GTM_VERSION = JSON.parse(readFileSync4(join4(pkgRoot, "package.json"), "utf8")).version;
 function firstExisting(candidates) {
-  return candidates.find((p) => existsSync2(p)) ?? null;
+  return candidates.find((p) => existsSync4(p)) ?? null;
 }
-var kit = firstExisting([join2(pkgRoot, "kit"), join2(pkgRoot, "..", "..", "kit")]);
+var kit = firstExisting([join4(pkgRoot, "kit"), join4(pkgRoot, "..", "..", "kit")]);
 if (!kit) throw new Error("gtm: kit/ not found next to the package; reinstall @veleads/gtm");
 var KIT_DIR = kit;
-var CHANGELOG_FILE = firstExisting([join2(pkgRoot, "CHANGELOG.md"), join2(pkgRoot, "..", "..", "CHANGELOG.md")]);
+var CHANGELOG_FILE = firstExisting([join4(pkgRoot, "CHANGELOG.md"), join4(pkgRoot, "..", "..", "CHANGELOG.md")]);
 
 // src/template.ts
-import { mkdirSync, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
-import { dirname as dirname2, join as join4 } from "path";
+import { mkdirSync, readFileSync as readFileSync5, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname2, join as join6 } from "path";
 
 // src/fsutil.ts
 import { readdirSync, statSync } from "fs";
-import { join as join3, relative } from "path";
+import { join as join5, relative } from "path";
 function walk(dir, skip = []) {
   const out = [];
   const visit = (d) => {
     for (const name of readdirSync(d)) {
       if (skip.includes(name)) continue;
-      const p = join3(d, name);
+      const p = join5(d, name);
       if (statSync(p).isDirectory()) visit(p);
       else out.push(relative(dir, p));
     }
@@ -470,7 +1059,7 @@ function walk(dir, skip = []) {
 }
 function subdirs(dir) {
   try {
-    return readdirSync(dir).filter((n) => !n.startsWith(".") && statSync(join3(dir, n)).isDirectory()).sort();
+    return readdirSync(dir).filter((n) => !n.startsWith(".") && statSync(join5(dir, n)).isDirectory()).sort();
   } catch {
     return [];
   }
@@ -507,7 +1096,7 @@ function destName(rel) {
 }
 function planTemplate(src, vars, rename = destName) {
   return walk(src).map((rel) => {
-    const raw = readFileSync3(join4(src, rel));
+    const raw = readFileSync5(join6(src, rel));
     if (!/\.(md|ya?ml|json|txt|example)$|gitignore$/.test(rel)) return { rel: rename(rel), content: raw };
     let text = raw.toString("utf8");
     for (const [k, v] of Object.entries(vars)) text = text.replaceAll(`__${k}__`, v);
@@ -515,7 +1104,7 @@ function planTemplate(src, vars, rename = destName) {
   });
 }
 function writePlanned(root2, file) {
-  const out = join4(root2, file.rel);
+  const out = join6(root2, file.rel);
   mkdirSync(dirname2(out), { recursive: true });
   writeFileSync2(out, file.content);
 }
@@ -524,25 +1113,41 @@ function copyTemplate(src, dest, vars, opts = {}) {
 }
 
 // src/commands/sync.ts
-import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync4, rmSync, writeFileSync as writeFileSync3 } from "fs";
-import { dirname as dirname3, join as join5 } from "path";
-var SHIPPED_DIRS = ["skills", "templates", "providers", "schemas"];
+import { existsSync as existsSync5, mkdirSync as mkdirSync2, readFileSync as readFileSync6, rmSync, writeFileSync as writeFileSync3 } from "fs";
+import { parse as parse4 } from "yaml";
+import { dirname as dirname3, join as join7 } from "path";
+var SHIPPED_DIRS = ["skills", "templates", "providers", "schemas", "guides"];
+var CODEOWNERS = join7(".github", "CODEOWNERS");
+var BLOCK_START = "# BEGIN gtm: generated by `gtm sync` from project.yaml \u2192 owners.approver. Edit owners there, not here.";
+var BLOCK_END = "# END gtm";
+function expectedCodeowners(root2) {
+  const projectFile = join7(root2, "project.yaml");
+  const approver = existsSync5(projectFile) ? parse4(readFileSync6(projectFile, "utf8"))?.owners?.approver : void 0;
+  const path = join7(root2, CODEOWNERS);
+  const current = existsSync5(path) ? readFileSync6(path, "utf8") : "";
+  const outside = current.replace(new RegExp(`\\n?${BLOCK_START.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${BLOCK_END}\\n?`), "\n").trim();
+  const block = isGitHubHandle(approver) ? [BLOCK_START, `/context/icp.yaml ${approver}`, `/context/signals.yaml ${approver}`, `/campaigns/*/copy.md ${approver}`, BLOCK_END].join("\n") : "";
+  const next = [outside, block].filter(Boolean).join("\n\n");
+  if (!next) return current ? "" : null;
+  return `${next}
+`;
+}
 function agentsMd() {
   const header = `<!-- GENERATED by \`gtm sync\` from ${PACKAGE_NAME} v${GTM_VERSION}. Do not edit: it is overwritten on upgrade.
      Project-specific rules go in PROJECT.md. Process changes go to the Veleads/gtm-core repo. -->
 
 `;
-  return header + readFileSync4(join5(KIT_DIR, "AGENTS.md"), "utf8").replaceAll("{{GTM_VERSION}}", GTM_VERSION);
+  return header + readFileSync6(join7(KIT_DIR, "AGENTS.md"), "utf8").replaceAll("{{GTM_VERSION}}", GTM_VERSION);
 }
 function expectedFiles() {
   const files = /* @__PURE__ */ new Map();
   for (const dir of SHIPPED_DIRS) {
-    for (const rel of walk(join5(KIT_DIR, dir))) files.set(join5(".gtm", dir, rel), readFileSync4(join5(KIT_DIR, dir, rel), "utf8"));
+    for (const rel of walk(join7(KIT_DIR, dir))) files.set(join7(".gtm", dir, rel), readFileSync6(join7(KIT_DIR, dir, rel), "utf8"));
   }
-  files.set(join5(".gtm", "VERSION"), `${GTM_VERSION}
+  files.set(join7(".gtm", "VERSION"), `${GTM_VERSION}
 `);
   files.set(
-    join5(".gtm", "README.md"),
+    join7(".gtm", "README.md"),
     `# .gtm/
 
 Copied from ${PACKAGE_NAME} v${GTM_VERSION} by \`gtm sync\`. Read-only: CI fails if it differs from the
@@ -556,13 +1161,16 @@ function checkSync(root2) {
   const expected = expectedFiles();
   const diffs = [];
   for (const [rel, content] of expected) {
-    const p = join5(root2, rel);
-    if (!existsSync3(p)) diffs.push(`missing  ${rel}`);
-    else if (readFileSync4(p, "utf8") !== content) diffs.push(`changed  ${rel}`);
+    const p = join7(root2, rel);
+    if (!existsSync5(p)) diffs.push(`missing  ${rel}`);
+    else if (readFileSync6(p, "utf8") !== content) diffs.push(`changed  ${rel}`);
   }
-  if (existsSync3(join5(root2, ".gtm"))) {
-    for (const rel of walk(join5(root2, ".gtm"))) if (!expected.has(join5(".gtm", rel))) diffs.push(`extra    ${join5(".gtm", rel)}`);
+  if (existsSync5(join7(root2, ".gtm"))) {
+    for (const rel of walk(join7(root2, ".gtm"))) if (!expected.has(join7(".gtm", rel))) diffs.push(`extra    ${join7(".gtm", rel)}`);
   }
+  const owners = expectedCodeowners(root2);
+  const ownersPath = join7(root2, CODEOWNERS);
+  if (owners !== null && (existsSync5(ownersPath) ? readFileSync6(ownersPath, "utf8") : "") !== owners) diffs.push(`changed  ${CODEOWNERS} (gtm block)`);
   return diffs;
 }
 function runSync(root2, opts = {}) {
@@ -576,18 +1184,23 @@ function runSync(root2, opts = {}) {
     for (const d of diffs) console.log(`  ${d}`);
     return false;
   }
-  rmSync(join5(root2, ".gtm"), { recursive: true, force: true });
+  rmSync(join7(root2, ".gtm"), { recursive: true, force: true });
   for (const [rel, content] of expectedFiles()) {
-    mkdirSync2(dirname3(join5(root2, rel)), { recursive: true });
-    writeFileSync3(join5(root2, rel), content);
+    mkdirSync2(dirname3(join7(root2, rel)), { recursive: true });
+    writeFileSync3(join7(root2, rel), content);
+  }
+  if (!existsSync5(join7(root2, "CLAUDE.md"))) writeFileSync3(join7(root2, "CLAUDE.md"), "@AGENTS.md\n");
+  const owners = expectedCodeowners(root2);
+  if (owners !== null) {
+    mkdirSync2(join7(root2, ".github"), { recursive: true });
+    writeFileSync3(join7(root2, CODEOWNERS), owners);
   }
-  if (!existsSync3(join5(root2, "CLAUDE.md"))) writeFileSync3(join5(root2, "CLAUDE.md"), "@AGENTS.md\n");
   console.log(`synced .gtm/ and AGENTS.md to ${PACKAGE_NAME} v${GTM_VERSION}`);
   return true;
 }
 
 // src/commands/init.ts
-var USAGE2 = `Usage:
+var USAGE3 = `Usage:
   gtm init <project-slug> --name "<Project Name>" [--dir <path>]   create ./gtm-project-<slug> (or <path>)
   gtm init . --name "<Project Name>" [--slug <project-slug>]        set up the current folder
 Slugs: lowercase letters, digits and hyphens.`;
@@ -604,26 +1217,26 @@ function runInit(target, opts) {
   const root2 = resolve(opts.cwd, here ? opts.dir ?? "." : opts.dir ?? `gtm-project-${target ?? ""}`);
   const slug = target && target !== "." ? target : opts.slug ?? slugFromFolder(root2);
   if (!opts.name || !slug || !Slug.safeParse(slug).success) {
-    console.error(USAGE2);
+    console.error(USAGE3);
     if (!slug && here) console.error(`Couldn't derive a slug from the folder name "${basename(root2)}": pass one with --slug`);
     else if (slug && !Slug.safeParse(slug).success) console.error(`"${slug}" is not a valid slug: pass one with --slug`);
     return false;
   }
-  if (existsSync4(join6(root2, "project.yaml")) || existsSync4(join6(root2, "client.yaml"))) {
+  if (existsSync6(join8(root2, "project.yaml")) || existsSync6(join8(root2, "client.yaml"))) {
     console.error(`${root2} is already a gtm project. Use \`npx gtm sync\` or \`npx gtm upgrade\` instead.`);
     return false;
   }
   const vars = { PROJECT_ID: slug, PROJECT_NAME: opts.name, TODAY: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10), GTM_VERSION };
-  const tpl = join6(KIT_DIR, "templates");
+  const tpl = join8(KIT_DIR, "templates");
   const planned = [
-    ...planTemplate(join6(tpl, "repo"), vars),
-    ...planTemplate(join6(tpl, "project"), vars, (rel) => rel === "project.yaml" ? rel : join6("context", rel)),
+    ...planTemplate(join8(tpl, "repo"), vars),
+    ...planTemplate(join8(tpl, "project"), vars, (rel) => rel === "project.yaml" ? rel : join8("context", rel)),
     { rel: "campaigns/.gitkeep", content: "" },
     { rel: "tam/.gitkeep", content: "" }
   ];
   const coreOwned = [...expectedFiles().keys()];
-  const conflicts = [...planned.map((f) => f.rel), ...coreOwned].filter((rel) => existsSync4(join6(root2, rel)) && !MERGEABLE.has(rel));
-  if (existsSync4(join6(root2, ".gtm"))) conflicts.unshift(".gtm/");
+  const conflicts = [...planned.map((f) => f.rel), ...coreOwned].filter((rel) => existsSync6(join8(root2, rel)) && !MERGEABLE.has(rel));
+  if (existsSync6(join8(root2, ".gtm"))) conflicts.unshift(".gtm/");
   if (conflicts.length) {
     console.error(`Cannot set up ${root2}: these files already exist and belong to gtm. Nothing was written.`);
     for (const c of [...new Set(conflicts)].slice(0, 15)) console.error(`  \u2717 ${c}`);
@@ -632,13 +1245,13 @@ function runInit(target, opts) {
   }
   const notes = [];
   for (const file of planned) {
-    const path = join6(root2, file.rel);
-    if (!existsSync4(path)) {
+    const path = join8(root2, file.rel);
+    if (!existsSync6(path)) {
       writePlanned(root2, file);
       continue;
     }
     if (file.rel === ".gitignore") {
-      const add = missingIgnoreLines(readFileSync5(path, "utf8"), file.content.toString());
+      const add = missingIgnoreLines(readFileSync7(path, "utf8"), file.content.toString());
       if (add.length) {
         appendFileSync(path, `
 # gtm-brain
@@ -650,15 +1263,15 @@ ${add.join("\n")}
       notes.push("README.md: kept yours (see .gtm/templates/repo/README.md for the gtm version)");
     }
   }
-  const claude = join6(root2, "CLAUDE.md");
-  const hadClaude = existsSync4(claude);
+  const claude = join8(root2, "CLAUDE.md");
+  const hadClaude = existsSync6(claude);
   runSync(root2);
-  if (hadClaude && !readFileSync5(claude, "utf8").includes("@AGENTS.md")) {
+  if (hadClaude && !readFileSync7(claude, "utf8").includes("@AGENTS.md")) {
     appendFileSync(claude, "\n@AGENTS.md\n");
     notes.push("CLAUDE.md: added @AGENTS.md so Claude Code loads the operating manual");
   }
-  const inRepo = spawnSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd: root2, encoding: "utf8" }).stdout?.trim() === "true";
-  const gitNote = inRepo ? "existing git repository kept" : spawnSync("git", ["init", "-q", "-b", "main"], { cwd: root2 }).status === 0 ? "git initialised" : "git not initialised";
+  const inRepo = spawnSync2("git", ["rev-parse", "--is-inside-work-tree"], { cwd: root2, encoding: "utf8" }).stdout?.trim() === "true";
+  const gitNote = inRepo ? "existing git repository kept" : spawnSync2("git", ["init", "-q", "-b", "main"], { cwd: root2 }).status === 0 ? "git initialised" : "git not initialised";
   const where = relative2(opts.cwd, root2) || ".";
   console.log(`
 Set up project "${opts.name}" (${slug}) in ${root2} (core v${GTM_VERSION}; ${gitNote}).`);
@@ -672,30 +1285,52 @@ Next:
 }
 
 // src/commands/job.ts
-var JOBS = ["tam", "enrich", "suppression:import", "signals", "qualify", "qa", "push", "activate", "results", "status"];
-function runJob(name) {
-  console.error(
-    `gtm job ${name ?? "<name>"}: not available yet (planned for Phase 2). Known jobs: ${JOBS.join(", ")}.
-Per AGENTS.md this is a mandatory stop: do not improvise the job with ad-hoc scripts.`
-  );
-  return false;
+import { createHash as createHash4 } from "crypto";
+import { spawnSync as spawnSync3 } from "child_process";
+import { existsSync as existsSync10, readFileSync as readFileSync11 } from "fs";
+import { join as join12 } from "path";
+import { parse as parse6 } from "yaml";
+
+// ../core/src/cache.ts
+import { createHash as createHash2 } from "crypto";
+
+// ../core/src/stack-env.ts
+import { existsSync as existsSync7, readFileSync as readFileSync8 } from "fs";
+import { homedir } from "os";
+import { join as join9 } from "path";
+var STACK_ENV_FILE = process.env.GTM_STACK_ENV ?? join9(homedir(), ".gtm", "stack.env");
+function loadStackEnv(file = STACK_ENV_FILE) {
+  if (!existsSync7(file)) return false;
+  for (const line of readFileSync8(file, "utf8").split("\n")) {
+    const m = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/);
+    if (m && process.env[m[1]] === void 0) process.env[m[1]] = m[2].replace(/^["']|["']$/g, "");
+  }
+  return true;
 }
 
+// ../core/src/adapters/mock-account-source.ts
+import { createHash as createHash3 } from "crypto";
+
+// src/commands/validate.ts
+import { existsSync as existsSync9, readdirSync as readdirSync2, readFileSync as readFileSync10 } from "fs";
+import { join as join11 } from "path";
+import { parse as parse5 } from "yaml";
+
 // src/commands/migrate.ts
-import { existsSync as existsSync5, readFileSync as readFileSync6, renameSync, writeFileSync as writeFileSync4 } from "fs";
-import { join as join7, relative as relative3 } from "path";
+import { existsSync as existsSync8, readFileSync as readFileSync9, renameSync, writeFileSync as writeFileSync4 } from "fs";
+import { join as join10, relative as relative3 } from "path";
 import { parseDocument as parseDocument2 } from "yaml";
 function projectYamlFiles(root2) {
   const files = [
-    { kind: "project", file: join7(root2, "project.yaml") },
-    { kind: "icp", file: join7(root2, "context", "icp.yaml") },
-    { kind: "signals", file: join7(root2, "context", "signals.yaml") },
-    ...subdirs(join7(root2, "campaigns")).map((c) => ({ kind: "campaign-config", file: join7(root2, "campaigns", c, "config.yaml") }))
+    { kind: "project", file: join10(root2, "project.yaml") },
+    { kind: "icp", file: join10(root2, "context", "icp.yaml") },
+    { kind: "signals", file: join10(root2, "context", "signals.yaml") },
+    ...subdirs(join10(root2, "campaigns")).map((c) => ({ kind: "campaign-config", file: join10(root2, "campaigns", c, "config.yaml") }))
   ];
-  return files.filter((f) => existsSync5(f.file));
+  return files.filter((f) => existsSync8(f.file));
 }
 function pendingRenames(root2) {
-  return FILE_RENAMES.filter((r) => existsSync5(join7(root2, r.from)) && !existsSync5(join7(root2, r.to)));
+  return FILE_RENAMES.filter((r) => existsSync8(join10(root2, r.from)) && !existsSync8(join10(root2, r.to)));
 }
 function runMigrate(root2, opts = {}) {
   let ok = true;
@@ -704,10 +1339,10 @@ function runMigrate(root2, opts = {}) {
     changed++;
     console.log(`  ${opts.dryRun ? "would rename" : "renamed"} ${from} \u2192 ${to}`);
     if (opts.dryRun) continue;
-    renameSync(join7(root2, from), join7(root2, to));
+    renameSync(join10(root2, from), join10(root2, to));
     if (to.endsWith(".md")) {
-      const p = join7(root2, to);
-      writeFileSync4(p, readFileSync6(p, "utf8").replace(new RegExp(`^# ${from.replace(".", "\\.")}`, "m"), `# ${to}`));
+      const p = join10(root2, to);
+      writeFileSync4(p, readFileSync9(p, "utf8").replace(new RegExp(`^# ${from.replace(".", "\\.")}`, "m"), `# ${to}`));
     }
   }
   if (opts.dryRun && changed) {
@@ -716,7 +1351,7 @@ function runMigrate(root2, opts = {}) {
   }
   for (const { kind, file } of projectYamlFiles(root2)) {
     const rel = relative3(root2, file);
-    const doc = parseDocument2(readFileSync6(file, "utf8"));
+    const doc = parseDocument2(readFileSync9(file, "utf8"));
     if (doc.errors.length) {
       console.log(`  \u2717 ${rel}: invalid YAML: ${doc.errors[0].message}`);
       ok = false;
@@ -743,96 +1378,7 @@ function runMigrate(root2, opts = {}) {
   return ok;
 }
 
-// src/commands/new-campaign.ts
-import { existsSync as existsSync6, mkdirSync as mkdirSync3, readFileSync as readFileSync7, writeFileSync as writeFileSync5 } from "fs";
-import { join as join8 } from "path";
-import { parse } from "yaml";
-function runNewCampaign(root2, campaign) {
-  if (!campaign || !Slug.safeParse(campaign).success) {
-    console.error("Usage: gtm new-campaign <campaign-slug>");
-    return false;
-  }
-  const projectFile = join8(root2, "project.yaml");
-  if (!existsSync6(projectFile)) {
-    console.error("project.yaml not found: run this from the root of a project repo");
-    return false;
-  }
-  const dest = join8(root2, "campaigns", campaign);
-  if (existsSync6(dest)) {
-    console.error(`campaigns/${campaign} already exists`);
-    return false;
-  }
-  const projectId = parse(readFileSync7(projectFile, "utf8"))?.project_id ?? "TODO";
-  copyTemplate(join8(KIT_DIR, "templates", "campaign"), dest, { PROJECT_ID: projectId, CAMPAIGN_ID: campaign, OWNER: process.env.GTM_USER ?? "TODO" });
-  mkdirSync3(join8(dest, "runs"), { recursive: true });
-  writeFileSync5(join8(dest, "runs", ".gitkeep"), "");
-  console.log(`Created campaigns/${campaign}. Branch: git switch -c campaign/${campaign}`);
-  return true;
-}
-
-// src/commands/status.ts
-import { existsSync as existsSync7, readdirSync as readdirSync2, readFileSync as readFileSync8 } from "fs";
-import { join as join9 } from "path";
-import { parse as parse2 } from "yaml";
-function readYaml(file) {
-  try {
-    return parse2(readFileSync8(file, "utf8"));
-  } catch {
-    return null;
-  }
-}
-function campaignStages(root2) {
-  return subdirs(join9(root2, "campaigns")).map((id) => ({ id, stage: readYaml(join9(root2, "campaigns", id, "config.yaml"))?.stage ?? "?" }));
-}
-function runStatus(root2) {
-  const project = readYaml(join9(root2, "project.yaml"));
-  const icp = readYaml(join9(root2, "context", "icp.yaml"));
-  console.log(`${project?.name ?? "?"} (${project?.project_id ?? "?"}) \xB7 status ${project?.status ?? "?"} \xB7 core v${GTM_VERSION}`);
-  console.log(`ICP gate: ${icp?.approval?.status ?? "?"}${icp?.approval?.approved_by ? ` by ${icp.approval.approved_by} on ${icp.approval.approved_at}` : ""}
-`);
-  const rows = subdirs(join9(root2, "campaigns")).map((id) => {
-    const cfg = readYaml(join9(root2, "campaigns", id, "config.yaml")) ?? {};
-    const runsDir = join9(root2, "campaigns", id, "runs");
-    const last = existsSync7(runsDir) ? readdirSync2(runsDir).filter((f) => f.endsWith(".md")).sort().at(-1) ?? "-" : "-";
-    return [id, cfg.stage ?? "?", cfg.gates?.copy?.status ?? "?", cfg.gates?.launch?.status ?? "?", cfg.owner ?? "?", last];
-  });
-  if (!rows.length) {
-    console.log("no campaigns yet: npx gtm new-campaign <campaign-slug>");
-    return true;
-  }
-  const header = ["campaign", "stage", "copy gate", "launch gate", "owner", "latest run log"];
-  const widths = header.map((h, i) => Math.max(h.length, ...rows.map((r) => String(r[i]).length)));
-  const line = (r) => r.map((c, i) => String(c).padEnd(widths[i])).join("  ");
-  console.log(line(header));
-  console.log(widths.map((w) => "-".repeat(w)).join("  "));
-  for (const r of rows) console.log(line(r));
-  return true;
-}
-
-// src/commands/upgrade.ts
-import { spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync9, readFileSync as readFileSync10 } from "fs";
-import { join as join11 } from "path";
-
-// src/changelog.ts
-function compareVersions(a, b) {
-  const pa = a.replace(/^[^\d]*/, "").split(/[.-]/).slice(0, 3).map(Number);
-  const pb = b.replace(/^[^\d]*/, "").split(/[.-]/).slice(0, 3).map(Number);
-  for (let i = 0; i < 3; i++) if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) - (pb[i] ?? 0);
-  return 0;
-}
-function changelogBetween(text, from, to) {
-  const parts = text.split(/^(?=## )/m);
-  return parts.filter((p) => {
-    const m = p.match(/^## \[?(\d+\.\d+\.\d+)/);
-    return m && compareVersions(m[1], from) > 0 && compareVersions(m[1], to) <= 0;
-  }).join("").trim();
-}
-
 // src/commands/validate.ts
-import { existsSync as existsSync8, readdirSync as readdirSync3, readFileSync as readFileSync9 } from "fs";
-import { join as join10 } from "path";
-import { parse as parse3 } from "yaml";
 var REQUIRED_CONTEXT = ["intake.md", "icp.md", "icp.yaml", "signals.yaml", "personas.md", "offer.md", "proof.md", "voice.md"];
 var REQUIRED_CAMPAIGN = ["brief.md", "config.yaml", "copy.md"];
 var DATA_FILES = /\.(csv|tsv|xlsx?|parquet|jsonl|ndjson)$/i;
@@ -842,21 +1388,21 @@ var ALLOWED_EMAIL = /@(example\.(com|org|net)|[a-z0-9-]+\.example)$/i;
 var SKIP_DIRS = ["node_modules", ".git", ".gtm"];
 var stageIndex = (s) => Stage.options.indexOf(s);
 function readPackageJson(root2) {
-  const p = join10(root2, "package.json");
-  return existsSync8(p) ? JSON.parse(readFileSync9(p, "utf8")) : null;
+  const p = join11(root2, "package.json");
+  return existsSync9(p) ? JSON.parse(readFileSync10(p, "utf8")) : null;
 }
 function pinnedVersion(root2) {
   const pkg = readPackageJson(root2);
   return pkg?.devDependencies?.[PACKAGE_NAME] ?? pkg?.dependencies?.[PACKAGE_NAME] ?? null;
 }
 function loadVersioned(r, file, kind, schema) {
-  if (!existsSync8(file)) {
+  if (!existsSync9(file)) {
     r.err(file, "missing");
     return null;
   }
   let raw;
   try {
-    raw = parse3(readFileSync9(file, "utf8"));
+    raw = parse5(readFileSync10(file, "utf8"));
   } catch (e) {
     r.err(file, `invalid YAML: ${e.message}`);
     return null;
@@ -878,22 +1424,22 @@ function loadVersioned(r, file, kind, schema) {
 function checkCoreSync(r, root2) {
   const pinned = pinnedVersion(root2);
   if (!pinned) return;
-  if (!/^\d+\.\d+\.\d+/.test(pinned)) r.err(join10(root2, "package.json"), `${PACKAGE_NAME} must be pinned exactly (got "${pinned}")`);
-  const versionFile = join10(root2, ".gtm", "VERSION");
-  const synced = existsSync8(versionFile) ? readFileSync9(versionFile, "utf8").trim() : null;
+  if (!/^\d+\.\d+\.\d+/.test(pinned)) r.err(join11(root2, "package.json"), `${PACKAGE_NAME} must be pinned exactly (got "${pinned}")`);
+  const versionFile = join11(root2, ".gtm", "VERSION");
+  const synced = existsSync9(versionFile) ? readFileSync10(versionFile, "utf8").trim() : null;
   if (synced !== GTM_VERSION) r.err(versionFile, `is ${synced ?? "missing"}, installed core is ${GTM_VERSION}: run \`npx gtm sync\``);
-  if (!existsSync8(join10(root2, "AGENTS.md"))) r.err(join10(root2, "AGENTS.md"), "missing: run `npx gtm sync`");
+  if (!existsSync9(join11(root2, "AGENTS.md"))) r.err(join11(root2, "AGENTS.md"), "missing: run `npx gtm sync`");
 }
 function checkNoLeadData(r, root2) {
   for (const rel of walk(root2, SKIP_DIRS)) {
-    const file = join10(root2, rel);
+    const file = join11(root2, rel);
     if (DATA_FILES.test(rel)) {
       r.err(file, "data files are not allowed in a project repo (lead data belongs in Postgres)");
       continue;
     }
     if (!/\.(md|ya?ml|txt)$/i.test(rel) || rel === "pnpm-lock.yaml") continue;
-    if (/\.ya?ml$/i.test(rel) && /\bTODO\b/.test(readFileSync9(file, "utf8"))) r.warn(file, "still contains TODO placeholders");
-    const found = (readFileSync9(file, "utf8").match(EMAIL) ?? []).filter((e) => !ALLOWED_EMAIL.test(e));
+    if (/\.ya?ml$/i.test(rel) && /\bTODO\b/.test(readFileSync10(file, "utf8"))) r.warn(file, "still contains TODO placeholders");
+    const found = (readFileSync10(file, "utf8").match(EMAIL) ?? []).filter((e) => !ALLOWED_EMAIL.test(e));
     if (found.length) r.warn(file, `contains email address(es) ${[...new Set(found)].slice(0, 3).join(", ")}: confirm none are prospects`);
   }
 }
@@ -908,11 +1454,24 @@ function checkPinnedApproval(r, contentFile, approval, current, what, approveCmd
   r.err(contentFile, `${what} changed after approval (approved ${pinned}, now ${current}). Re-present it to the approver and record it with \`${approveCmd} --by "<name>"\`, or revert the change`);
   return false;
 }
-function validateCampaign(r, root2, projectId, campaign, icp, signals, icpApproved) {
-  const dir = join10(root2, "campaigns", campaign);
+function checkGitHubMode(r, file, what, approval, approver, prApprovals, content) {
+  if (approval.status !== "approved" || !isGitHubHandle(approver)) return true;
+  if (!approval.approved_via) {
+    r.err(file, `${what} approval was recorded without a pull request, but the approver is ${approver} (GitHub mode): get an APPROVED review on a PR and run \`npx gtm approve ... --pr <number>\``);
+    return false;
+  }
+  if (!approval.approved_by || login(approval.approved_by) !== login(approver)) {
+    r.err(file, `${what} was approved by ${approval.approved_by}, but the project approver is ${approver}`);
+    return false;
+  }
+  prApprovals.push({ file, what, approval, approver, ...content });
+  return true;
+}
+function validateCampaign(r, root2, projectId, campaign, icp, signals, icpApproved, approver, prApprovals) {
+  const dir = join11(root2, "campaigns", campaign);
   console.log(`campaign ${campaign}`);
-  for (const f of REQUIRED_CAMPAIGN) if (!existsSync8(join10(dir, f))) r.err(join10(dir, f), "missing");
-  const cfgFile = join10(dir, "config.yaml");
+  for (const f of REQUIRED_CAMPAIGN) if (!existsSync9(join11(dir, f))) r.err(join11(dir, f), "missing");
+  const cfgFile = join11(dir, "config.yaml");
   const cfg = loadVersioned(r, cfgFile, "campaign-config", CampaignConfig);
   if (cfg) {
     if (cfg.project_id !== projectId) r.err(cfgFile, `project_id "${cfg.project_id}" does not match project.yaml "${projectId}"`);
@@ -929,16 +1488,16 @@ function validateCampaign(r, root2, projectId, campaign, icp, signals, icpApprov
     }
     const providers = /* @__PURE__ */ new Set([...cfg.enrichment.email_waterfall, cfg.enrichment.verification.provider, cfg.sending.sender]);
     for (const p of providers) {
-      if (!p.startsWith("mock-") && !existsSync8(join10(KIT_DIR, "providers", `${p}.md`))) r.warn(cfgFile, `no .gtm/providers/${p}.md documenting "${p}"`);
+      if (!p.startsWith("mock-") && !existsSync9(join11(KIT_DIR, "providers", `${p}.md`))) r.warn(cfgFile, `no .gtm/providers/${p}.md documenting "${p}"`);
     }
-    if (stageIndex(cfg.stage) > stageIndex("tam") && !existsSync8(join10(root2, "tam", `${cfg.tam_id}.md`))) {
+    if (stageIndex(cfg.stage) > stageIndex("tam") && !existsSync9(join11(root2, "tam", `${cfg.tam_id}.md`))) {
       r.err(cfgFile, `stage is "${cfg.stage}" but tam/${cfg.tam_id}.md does not exist`);
     }
     if (stageIndex(cfg.stage) > stageIndex("icp") && !icpApproved) {
       r.err(cfgFile, `stage is "${cfg.stage}" but the ICP gate (context/icp.yaml approval) is not approved, or the ICP changed since approval`);
     }
-    const copyFile = join10(dir, "copy.md");
-    const copyApproved = existsSync8(copyFile) ? checkPinnedApproval(r, copyFile, cfg.gates.copy, copyContentHash(readFileSync9(copyFile, "utf8")), "copy", `npx gtm approve copy ${campaign}`) : false;
+    const copyFile = join11(dir, "copy.md");
+    const copyApproved = existsSync9(copyFile) ? checkPinnedApproval(r, copyFile, cfg.gates.copy, copyContentHash(readFileSync10(copyFile, "utf8")), "copy", `npx gtm approve copy ${campaign}`) && checkGitHubMode(r, cfgFile, `copy (${campaign})`, cfg.gates.copy, approver, prApprovals, { contentPath: `campaigns/${campaign}/copy.md`, hashOf: copyContentHash }) : false;
     if (stageIndex(cfg.stage) > stageIndex("copy") && !copyApproved) {
       r.err(cfgFile, `stage is "${cfg.stage}" but gates.copy is not approved, or copy.md changed since approval`);
     }
@@ -948,64 +1507,266 @@ function validateCampaign(r, root2, projectId, campaign, icp, signals, icpApprov
     if (cfg.gates.launch.status === "approved" && !copyApproved) {
       r.err(cfgFile, "gates.launch is approved but gates.copy is not");
     }
-    if (stageIndex(cfg.stage) > stageIndex("qa") && !existsSync8(join10(dir, "qa.md"))) {
-      r.err(join10(dir, "qa.md"), "missing: QA report is required before launch");
+    if (stageIndex(cfg.stage) > stageIndex("qa") && !existsSync9(join11(dir, "qa.md"))) {
+      r.err(join11(dir, "qa.md"), "missing: QA report is required before launch");
     }
   }
-  const runs = join10(dir, "runs");
-  if (existsSync8(runs)) {
-    for (const f of readdirSync3(runs).filter((f2) => !f2.startsWith("."))) {
-      if (!RUN_LOG_NAME.test(f)) r.err(join10(runs, f), "run logs must be named YYYY-MM-DD-<user>[-n].md");
+  const runs = join11(dir, "runs");
+  if (existsSync9(runs)) {
+    for (const f of readdirSync2(runs).filter((f2) => !f2.startsWith("."))) {
+      if (!RUN_LOG_NAME.test(f)) r.err(join11(runs, f), "run logs must be named YYYY-MM-DD-<user>[-n].md");
     }
   }
 }
-function runValidate(root2, onlyCampaign) {
+async function runValidate(root2, onlyCampaign, opts = {}) {
   const r = new Report(root2);
   console.log(`validating ${root2} against core v${GTM_VERSION}`);
   checkCoreSync(r, root2);
-  for (const { from, to } of pendingRenames(root2)) r.err(join10(root2, from), `renamed to ${to} in core 0.3.0: run \`npx gtm migrate\``);
-  const meta = loadVersioned(r, join10(root2, "project.yaml"), "project", ProjectFile);
+  for (const { from, to } of pendingRenames(root2)) r.err(join11(root2, from), `renamed to ${to} in core 0.3.0: run \`npx gtm migrate\``);
+  const meta = loadVersioned(r, join11(root2, "project.yaml"), "project", ProjectFile);
   const projectId = meta?.project_id ?? "";
   if (meta) {
     for (const key of Object.keys(meta.features)) {
-      if (!FEATURES[key]) r.err(join10(root2, "project.yaml"), `unknown feature "${key}" (known: ${Object.keys(FEATURES).join(", ") || "none"})`);
+      if (!FEATURES[key]) r.err(join11(root2, "project.yaml"), `unknown feature "${key}" (known: ${Object.keys(FEATURES).join(", ") || "none"})`);
     }
   }
-  if (!existsSync8(join10(root2, "PROJECT.md"))) r.warn(join10(root2, "PROJECT.md"), "missing (project-specific rules for agents)");
-  for (const f of REQUIRED_CONTEXT) if (!existsSync8(join10(root2, "context", f))) r.err(join10(root2, "context", f), "missing");
-  const icpFile = join10(root2, "context", "icp.yaml");
-  const sigFile = join10(root2, "context", "signals.yaml");
-  const icp = existsSync8(icpFile) ? loadVersioned(r, icpFile, "icp", IcpFile) : null;
-  const signals = existsSync8(sigFile) ? loadVersioned(r, sigFile, "signals", SignalsFile) : null;
+  if (!existsSync9(join11(root2, "context", "research.md"))) r.warn(join11(root2, "context", "research.md"), "missing: run the research skill (.gtm/skills/research/SKILL.md) before intake questions");
+  if (!existsSync9(join11(root2, "PROJECT.md"))) r.warn(join11(root2, "PROJECT.md"), "missing (project-specific rules for agents)");
+  for (const f of REQUIRED_CONTEXT) if (!existsSync9(join11(root2, "context", f))) r.err(join11(root2, "context", f), "missing");
+  const icpFile = join11(root2, "context", "icp.yaml");
+  const sigFile = join11(root2, "context", "signals.yaml");
+  const icp = existsSync9(icpFile) ? loadVersioned(r, icpFile, "icp", IcpFile) : null;
+  const signals = existsSync9(sigFile) ? loadVersioned(r, sigFile, "signals", SignalsFile) : null;
   if (meta && icp && icp.project_id !== projectId) r.err(icpFile, `project_id "${icp.project_id}" does not match project.yaml "${projectId}"`);
   if (meta && signals && signals.project_id !== projectId) r.err(sigFile, `project_id "${signals.project_id}" does not match project.yaml "${projectId}"`);
-  const icpApproved = icp ? checkPinnedApproval(r, icpFile, icp.approval, icpContentHash(parse3(readFileSync9(icpFile, "utf8"))), "ICP", "npx gtm approve icp") : false;
+  const approver = meta?.owners.approver;
+  const prApprovals = [];
+  const icpApproved = icp ? checkPinnedApproval(r, icpFile, icp.approval, icpContentHash(parse5(readFileSync10(icpFile, "utf8"))), "ICP", "npx gtm approve icp") && checkGitHubMode(r, icpFile, "ICP", icp.approval, approver, prApprovals, { contentPath: "context/icp.yaml", hashOf: (t) => icpContentHash(parse5(t)) }) : false;
   checkNoLeadData(r, root2);
-  const campaigns = onlyCampaign ? [onlyCampaign] : subdirs(join10(root2, "campaigns"));
+  const campaigns = onlyCampaign ? [onlyCampaign] : subdirs(join11(root2, "campaigns"));
   for (const c of campaigns) {
-    if (!existsSync8(join10(root2, "campaigns", c))) {
-      r.err(join10(root2, "campaigns", c), "campaign folder not found");
+    if (!existsSync9(join11(root2, "campaigns", c))) {
+      r.err(join11(root2, "campaigns", c), "campaign folder not found");
       continue;
     }
-    validateCampaign(r, root2, projectId, c, icp, signals, icpApproved);
+    validateCampaign(r, root2, projectId, c, icp, signals, icpApproved, approver, prApprovals);
+  }
+  if (opts.verifyGithub && prApprovals.length) {
+    const api = GitHubApi.fromRepo(root2, opts.fetchImpl);
+    if (typeof api === "string") r.err(root2, `--verify-github: ${api}`);
+    else {
+      for (const p of prApprovals) {
+        const ok = await verifyRecordedApproval(api, p.approval.approved_via, p.approver, p.contentPath, p.approval.content_hash, p.hashOf);
+        if (ok === true) console.log(`  \u2713 ${p.what}: ${p.approver} approved ${p.approval.approved_via}`);
+        else r.err(p.file, `${p.what}: ${ok}`);
+      }
+    }
   }
   r.summary();
   return r.errors === 0;
 }
 
+// src/commands/job.ts
+var PLANNED = ["enrich", "suppression:import", "signals", "qualify", "qa", "push", "activate", "results"];
+function git(root2, args2) {
+  const res = spawnSync3("git", args2, { cwd: root2, encoding: "utf8" });
+  return res.status === 0 ? res.stdout.trim() : null;
+}
+function buildTamInput(root2, campaign) {
+  const read = (rel) => parse6(readFileSync11(join12(root2, rel), "utf8"));
+  const project = ProjectFile.parse(read("project.yaml"));
+  const icp = IcpFile.parse(read("context/icp.yaml"));
+  const cfgText = readFileSync11(join12(root2, "campaigns", campaign, "config.yaml"), "utf8");
+  const cfg = CampaignConfig.parse(parse6(cfgText));
+  if (icp.approval.status !== "approved") return "TAM needs an approved ICP (hard stop, AGENTS.md section 4). Get ICP sign-off first.";
+  if (Stage.options.indexOf(cfg.stage) < Stage.options.indexOf("tam")) return `campaign stage is "${cfg.stage}": move it to "tam" first.`;
+  if (!cfg.tam) return "config.yaml has no `tam:` section. Add `tam: { source: mock-accounts }` for a local proof, or a real account source.";
+  const segments = resolveIcp(icp).segments.filter((s) => cfg.segments.includes(s.id)).map(({ id, description, firmographics }) => ({ id, description, firmographics }));
+  return TamJobInput.parse({
+    ctx: {
+      project_id: project.project_id,
+      campaign_id: campaign,
+      triggered_by: process.env.GTM_USER ?? git(root2, ["config", "user.name"]) ?? "unknown",
+      core_version: GTM_VERSION,
+      git_sha: git(root2, ["rev-parse", "HEAD"]),
+      config_hash: `sha256:${createHash4("sha256").update(cfgText).digest("hex").slice(0, 16)}`
+    },
+    tam_id: cfg.tam_id,
+    source: cfg.tam.source,
+    max_accounts_per_segment: cfg.tam.max_accounts_per_segment,
+    segments,
+    exclusions: icp.exclusions,
+    budget_usd: cfg.budget.max_total
+  });
+}
+function printTam(res, campaign) {
+  const header = ["segment", "found", "excluded", "new", "updated", "reachable", "active"];
+  const rows = res.segments.map((s) => [s.segment_id, s.found, s.excluded, s.inserted, s.updated, s.reachable, s.active].map(String));
+  const widths = header.map((h, i) => Math.max(h.length, ...rows.map((r) => r[i].length)));
+  const line = (r) => r.map((c, i) => i === 0 ? c.padEnd(widths[i]) : c.padStart(widths[i])).join("  ");
+  console.log(`
+${line(header)}
+${widths.map((w) => "-".repeat(w)).join("  ")}`);
+  for (const r of rows) console.log(line(r));
+  console.log(`
+Funnel: TAM ${res.totals.tam} \u2192 reachable ${res.totals.reachable} \u2192 active ${res.totals.active}   cost $${res.cost_usd.toFixed(2)}   run ${res.run_id}`);
+  console.log(`
+Run log row (campaigns/${campaign}/runs/\u2026):
+| tam | ${res.run_id} | succeeded | ${res.segments.length} segment(s) | TAM ${res.totals.tam} \u2192 reachable ${res.totals.reachable} \u2192 active ${res.totals.active} | ${res.cost_usd.toFixed(2)} |`);
+}
+async function runJob(root2, args2) {
+  const [name, campaign] = args2;
+  if (name && PLANNED.includes(name)) {
+    console.error(`gtm job ${name}: not available yet (planned). Per AGENTS.md this is a mandatory stop: do not improvise it with scripts.`);
+    return false;
+  }
+  if (name !== "tam" || !campaign) {
+    console.error(`Usage: gtm job tam <campaign>   (planned: ${PLANNED.join(", ")})`);
+    return false;
+  }
+  if (!existsSync10(join12(root2, "campaigns", campaign, "config.yaml"))) {
+    console.error(`campaigns/${campaign}/config.yaml not found`);
+    return false;
+  }
+  console.log(`\u2022 validating ${campaign}`);
+  if (!await runValidate(root2, campaign)) {
+    console.error("\nFix the validation errors above before running jobs.");
+    return false;
+  }
+  let input;
+  try {
+    input = buildTamInput(root2, campaign);
+  } catch (e) {
+    console.error(e.message);
+    return false;
+  }
+  if (typeof input === "string") {
+    console.error(input);
+    return false;
+  }
+  loadStackEnv();
+  if (!process.env.HATCHET_CLIENT_TOKEN) {
+    console.error(`No Hatchet connection. Local: run \`pnpm stack:up\` and \`pnpm worker\` in gtm-core (writes ${STACK_ENV_FILE}). Deployed: set HATCHET_CLIENT_TOKEN.`);
+    return false;
+  }
+  const { HatchetClient } = await import("@hatchet-dev/typescript-sdk/v1");
+  const hatchet = HatchetClient.init();
+  const tam = hatchet.task({ name: JOB_NAMES.tam, fn: async () => {
+    throw new Error("runs on the gtm worker");
+  } });
+  console.log(`\u2022 running tam for ${input.segments.length} segment(s) via ${input.source} (budget $${input.budget_usd})`);
+  const hint = setTimeout(() => console.log("  \u2026 still waiting. Is the worker running? (`pnpm worker` in gtm-core)"), 2e4);
+  try {
+    const output = await tam.run(input);
+    printTam(TamJobResult.parse(output), campaign);
+    return true;
+  } catch (e) {
+    console.error(`tam failed: ${e.message}`);
+    return false;
+  } finally {
+    clearTimeout(hint);
+  }
+}
+
+// src/commands/new-campaign.ts
+import { existsSync as existsSync11, mkdirSync as mkdirSync3, readFileSync as readFileSync12, writeFileSync as writeFileSync5 } from "fs";
+import { join as join13 } from "path";
+import { parse as parse7 } from "yaml";
+function runNewCampaign(root2, campaign) {
+  if (!campaign || !Slug.safeParse(campaign).success) {
+    console.error("Usage: gtm new-campaign <campaign-slug>");
+    return false;
+  }
+  const projectFile = join13(root2, "project.yaml");
+  if (!existsSync11(projectFile)) {
+    console.error("project.yaml not found: run this from the root of a project repo");
+    return false;
+  }
+  const dest = join13(root2, "campaigns", campaign);
+  if (existsSync11(dest)) {
+    console.error(`campaigns/${campaign} already exists`);
+    return false;
+  }
+  const projectId = parse7(readFileSync12(projectFile, "utf8"))?.project_id ?? "TODO";
+  copyTemplate(join13(KIT_DIR, "templates", "campaign"), dest, { PROJECT_ID: projectId, CAMPAIGN_ID: campaign, OWNER: process.env.GTM_USER ?? "TODO" });
+  mkdirSync3(join13(dest, "runs"), { recursive: true });
+  writeFileSync5(join13(dest, "runs", ".gitkeep"), "");
+  console.log(`Created campaigns/${campaign}. Branch: git switch -c campaign/${campaign}`);
+  return true;
+}
+
+// src/commands/status.ts
+import { existsSync as existsSync12, readdirSync as readdirSync3, readFileSync as readFileSync13 } from "fs";
+import { join as join14 } from "path";
+import { parse as parse8 } from "yaml";
+function readYaml2(file) {
+  try {
+    return parse8(readFileSync13(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function campaignStages(root2) {
+  return subdirs(join14(root2, "campaigns")).map((id) => ({ id, stage: readYaml2(join14(root2, "campaigns", id, "config.yaml"))?.stage ?? "?" }));
+}
+function runStatus(root2) {
+  const project = readYaml2(join14(root2, "project.yaml"));
+  const icp = readYaml2(join14(root2, "context", "icp.yaml"));
+  console.log(`${project?.name ?? "?"} (${project?.project_id ?? "?"}) \xB7 status ${project?.status ?? "?"} \xB7 core v${GTM_VERSION}`);
+  console.log(`ICP gate: ${icp?.approval?.status ?? "?"}${icp?.approval?.approved_by ? ` by ${icp.approval.approved_by} on ${icp.approval.approved_at}` : ""}
+`);
+  const rows = subdirs(join14(root2, "campaigns")).map((id) => {
+    const cfg = readYaml2(join14(root2, "campaigns", id, "config.yaml")) ?? {};
+    const runsDir = join14(root2, "campaigns", id, "runs");
+    const last = existsSync12(runsDir) ? readdirSync3(runsDir).filter((f) => f.endsWith(".md")).sort().at(-1) ?? "-" : "-";
+    return [id, cfg.stage ?? "?", cfg.gates?.copy?.status ?? "?", cfg.gates?.launch?.status ?? "?", cfg.owner ?? "?", last];
+  });
+  if (!rows.length) {
+    console.log("no campaigns yet: npx gtm new-campaign <campaign-slug>");
+    return true;
+  }
+  const header = ["campaign", "stage", "copy gate", "launch gate", "owner", "latest run log"];
+  const widths = header.map((h, i) => Math.max(h.length, ...rows.map((r) => String(r[i]).length)));
+  const line = (r) => r.map((c, i) => String(c).padEnd(widths[i])).join("  ");
+  console.log(line(header));
+  console.log(widths.map((w) => "-".repeat(w)).join("  "));
+  for (const r of rows) console.log(line(r));
+  return true;
+}
+
+// src/commands/upgrade.ts
+import { spawnSync as spawnSync4 } from "child_process";
+import { existsSync as existsSync13, readFileSync as readFileSync14 } from "fs";
+import { join as join15 } from "path";
+
+// src/changelog.ts
+function compareVersions(a, b) {
+  const pa = a.replace(/^[^\d]*/, "").split(/[.-]/).slice(0, 3).map(Number);
+  const pb = b.replace(/^[^\d]*/, "").split(/[.-]/).slice(0, 3).map(Number);
+  for (let i = 0; i < 3; i++) if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) - (pb[i] ?? 0);
+  return 0;
+}
+function changelogBetween(text, from, to) {
+  const parts = text.split(/^(?=## )/m);
+  return parts.filter((p) => {
+    const m = p.match(/^## \[?(\d+\.\d+\.\d+)/);
+    return m && compareVersions(m[1], from) > 0 && compareVersions(m[1], to) <= 0;
+  }).join("").trim();
+}
+
 // src/commands/upgrade.ts
 function detectPackageManager(root2) {
-  if (existsSync9(join11(root2, "pnpm-lock.yaml"))) return "pnpm";
-  if (existsSync9(join11(root2, "yarn.lock"))) return "yarn";
+  if (existsSync13(join15(root2, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync13(join15(root2, "yarn.lock"))) return "yarn";
   return "npm";
 }
 function installExact(root2, pm, spec) {
-  const onPath = (bin) => spawnSync2(bin, ["--version"], { stdio: "ignore" }).status === 0;
+  const onPath = (bin) => spawnSync4(bin, ["--version"], { stdio: "ignore" }).status === 0;
   const [cmd, args2] = pm === "npm" ? ["npm", ["install", "--save-dev", "--save-exact", spec]] : pm === "pnpm" ? onPath("pnpm") ? ["pnpm", ["add", "-D", "--save-exact", spec]] : ["npx", ["-y", "pnpm@10", "add", "-D", "--save-exact", spec]] : onPath("yarn") ? ["yarn", ["add", "-D", "--exact", spec]] : ["npx", ["-y", "yarn@1", "add", "-D", "--exact", spec]];
-  return spawnSync2(cmd, args2, { cwd: root2, stdio: "inherit" }).status ?? 1;
+  return spawnSync4(cmd, args2, { cwd: root2, stdio: "inherit" }).status ?? 1;
 }
 function gtm(root2, args2) {
-  return spawnSync2("npx", ["gtm", ...args2], { cwd: root2, stdio: "inherit" }).status ?? 1;
+  return spawnSync4("npx", ["gtm", ...args2], { cwd: root2, stdio: "inherit" }).status ?? 1;
 }
 var FROZEN_STAGES = ["qa", "launch"];
 function runUpgrade(root2, opts) {
@@ -1020,7 +1781,7 @@ function runUpgrade(root2, opts) {
     console.error("Finish the launch first, or re-run with --force if a GTM engineer approved it.");
     return false;
   }
-  const dirty = spawnSync2("git", ["status", "--porcelain"], { cwd: root2, encoding: "utf8" });
+  const dirty = spawnSync4("git", ["status", "--porcelain"], { cwd: root2, encoding: "utf8" });
   if (dirty.status === 0 && dirty.stdout.trim() && !opts.force) {
     console.error("Refusing to upgrade with uncommitted changes. Commit or stash first (or --force).");
     return false;
@@ -1033,9 +1794,9 @@ function runUpgrade(root2, opts) {
   if (gtm(root2, ["migrate"]) !== 0) return false;
   const valid = gtm(root2, ["validate"]) === 0;
   const after = pinnedVersion(root2) ?? target;
-  const changelog = join11(root2, "node_modules", ...PACKAGE_NAME.split("/"), "CHANGELOG.md");
-  if (existsSync9(changelog)) {
-    const notes = changelogBetween(readFileSync10(changelog, "utf8"), before, after);
+  const changelog = join15(root2, "node_modules", ...PACKAGE_NAME.split("/"), "CHANGELOG.md");
+  if (existsSync13(changelog)) {
+    const notes = changelogBetween(readFileSync14(changelog, "utf8"), before, after);
     console.log(`
 === Changes ${before} \u2192 ${after} ===
 ${notes || "(no changelog entries)"}
@@ -1070,16 +1831,18 @@ var COMMANDS = {
     examples: ["git switch -c campaign/q1-uk-cfo && npx gtm new-campaign q1-uk-cfo"]
   },
   validate: {
-    usage: "gtm validate [campaign]",
+    usage: "gtm validate [campaign] [--verify-github]",
     summary: "check repo against schemas, gates, data rules",
     details: [
       "Checks project.yaml, context/ and campaigns against the schemas; segment/persona/signal references;",
       "gate order (no stage past an unapproved or changed ICP/copy approval); required files; run-log names;",
       "no lead data (blocks data files, warns on email addresses); .gtm/ matches the installed core.",
+      "GitHub mode: ICP/copy approvals must come from the approver's PR review (approved_via).",
+      "--verify-github (CI) re-checks each recorded PR approval on GitHub.",
       "Exit code 1 if there is any error; warnings never fail."
     ],
     writes: "Nothing (read-only).",
-    examples: ["npx gtm validate", "npx gtm validate q1-uk-cfo"]
+    examples: ["npx gtm validate", "npx gtm validate q1-uk-cfo", "npx gtm validate --verify-github"]
   },
   status: {
     usage: "gtm status",
@@ -1088,26 +1851,64 @@ var COMMANDS = {
     writes: "Nothing (read-only).",
     examples: ["npx gtm status"]
   },
+  icp: {
+    usage: "gtm icp",
+    summary: "show the ICP as jobs see it (core + segment overrides)",
+    details: [
+      "Prints the core profile, then every segment's FINAL filters (core with the segment's fields",
+      "replacing the same core fields), which fields the segment overrides, its personas, and the",
+      "shared exclusions. Use it to review an ICP before sign-off and to check what `gtm job tam` searches."
+    ],
+    writes: "Nothing (read-only).",
+    examples: ["npx gtm icp"]
+  },
   approve: {
-    usage: 'gtm approve icp --by "<Name (role)>" [--notes ".."] [--date YYYY-MM-DD]\ngtm approve copy <campaign> --by "<Name (role)>" [--notes ".."] [--date YYYY-MM-DD]',
+    usage: 'gtm approve icp --pr <number> [--notes ".."]\ngtm approve copy <campaign> --pr <number> [--notes ".."]\ngtm approve icp --by "<Name (role)>" [--notes ".."] [--date YYYY-MM-DD]\ngtm approve copy <campaign> --by "<Name (role)>" [..]',
     summary: "record a sign-off and pin a hash of the approved content",
     details: [
-      "Run ONLY after the named human explicitly approved in this session (AGENTS.md section 4).",
-      "Pins a content hash: if context/icp.yaml or the campaign's copy.md changes afterwards,",
-      "`gtm validate` fails until it is re-approved. Refuses if the file would not validate.",
-      "The launch gate is recorded by hand in config.yaml (its content is the lead set)."
+      "GitHub mode (project.yaml owners.approver is an @handle): the approval IS the approver's APPROVED",
+      "review on a pull request. --pr verifies on GitHub that the PR changes the file, the approver approved",
+      "its latest commit, and your local file equals the approved version; then records approved_via.",
+      "Recorded mode (approver is a name): run ONLY after the named human explicitly approved in this session.",
+      "Either way a content hash is pinned: if the ICP or copy changes later, `gtm validate` fails.",
+      "The launch gate is recorded by hand in config.yaml."
     ],
     writes: "context/icp.yaml \u2192 approval (icp), or campaigns/<campaign>/config.yaml \u2192 gates.copy (copy).",
-    examples: ['npx gtm approve icp --by "Maria Chen (VP Marketing)" --notes "Segments A+B, personas CFO+AP"', 'npx gtm approve copy q1-uk-cfo --by "Maria Chen (VP Marketing)"']
+    examples: ["npx gtm approve icp --pr 12", "npx gtm approve copy q1-uk-cfo --pr 15", 'npx gtm approve icp --by "Maria Chen (VP Marketing)"']
+  },
+  track: {
+    usage: "gtm track stage <campaign>\ngtm track gate-open <icp|copy|launch> [campaign] [--pr <number>]\ngtm track gate-done <icp|copy|launch> [campaign]",
+    summary: "mirror stages and gates into the project tracker",
+    details: [
+      "Uses project.yaml \u2192 tracker.kind (github | none). GitHub: one issue per campaign (label stage:<stage>)",
+      "and one per gate, assigned to the approver. Re-running updates the same issue.",
+      "The tracker is a mirror only: stage and gates live in the YAML files. gate-done refuses unless the",
+      "files say the gate is approved."
+    ],
+    writes: "Issues in the tracker (GitHub: issues, labels, comments). No local files.",
+    examples: ["npx gtm track stage q1-uk-cfo", "npx gtm track gate-open icp --pr 12", "npx gtm track gate-done copy q1-uk-cfo"]
+  },
+  github: {
+    usage: "gtm github setup [--apply]",
+    summary: "prepare the GitHub repo: labels and approval ruleset",
+    details: [
+      "Creates the labels gtm track uses, and a ruleset on the default branch: PR required, review from",
+      "CODEOWNERS required (the approver owns icp.yaml, signals.yaml, copy.md), CI job `check` must pass.",
+      "Without --apply it only prints the plan. Needs admin rights; private repos need a paid GitHub plan",
+      "for rulesets (CI verification via `validate --verify-github` works on any plan)."
+    ],
+    writes: "With --apply: labels and a ruleset on GitHub. Without: nothing.",
+    examples: ["npx gtm github setup", "npx gtm github setup --apply"]
   },
   sync: {
     usage: "gtm sync [--check]",
     summary: "copy core kit into .gtm/ + AGENTS.md",
     details: [
-      "Makes .gtm/ (skills, templates, schemas, provider docs) and AGENTS.md match the installed core.",
+      "Makes .gtm/ (skills, templates, schemas, guides, provider docs) and AGENTS.md match the installed core,",
+      "and maintains the gtm block in .github/CODEOWNERS from project.yaml \u2192 owners.approver.",
       "--check only compares and exits 1 if they differ (CI uses this; never edit .gtm/ by hand)."
     ],
-    writes: ".gtm/ (replaced entirely) and AGENTS.md; creates CLAUDE.md if missing. With --check: nothing.",
+    writes: ".gtm/ (replaced entirely), AGENTS.md, the gtm block in .github/CODEOWNERS; creates CLAUDE.md if missing. With --check: nothing.",
     examples: ["npx gtm sync", "npx gtm sync --check"]
   },
   migrate: {
@@ -1128,13 +1929,16 @@ var COMMANDS = {
     examples: ["npx gtm upgrade", "npx gtm upgrade 0.3.0"]
   },
   job: {
-    usage: "gtm job <name> <campaign>",
-    summary: "run a pipeline job (Phase 2)",
+    usage: "gtm job tam <campaign>",
+    summary: "run a pipeline job on the workers",
     details: [
-      "Planned: tam, enrich, suppression:import, signals, qualify, qa, push, activate, results, status.",
-      "Not available yet: it exits 1. Per AGENTS.md this is a stop; do not improvise jobs with ad-hoc scripts."
+      "tam: builds the TAM for the campaign's segments into the database (needs an approved ICP and",
+      "config.yaml \u2192 tam.source; mock-accounts for a local proof) and prints the funnel, cost and run_id.",
+      "Validates first, sends the resolved config to the workers via Hatchet, and waits for the result.",
+      "Local: `pnpm stack:up` + `pnpm worker` in gtm-core (settings in ~/.gtm/stack.env).",
+      "Planned (exit 1, a stop per AGENTS.md): enrich, suppression:import, signals, qualify, qa, push, activate, results."
     ],
-    writes: "Nothing yet.",
+    writes: "Rows in Postgres (runs, accounts, costs). No repo files: copy the printed run-log row into the run log.",
     examples: ["npx gtm job tam q1-uk-cfo"]
   }
 };
@@ -1184,6 +1988,9 @@ var { values, positionals } = parseArgs({
     name: { type: "string" },
     dir: { type: "string" },
     slug: { type: "string" },
+    pr: { type: "string" },
+    apply: { type: "boolean" },
+    "verify-github": { type: "boolean" },
     by: { type: "string" },
     notes: { type: "string" },
     date: { type: "string" },
@@ -1212,7 +2019,7 @@ ${generalHelp(GTM_VERSION)}`);
   console.log(text);
   return true;
 }
-function run() {
+async function run() {
   if (values.version) {
     console.log(GTM_VERSION);
     return true;
@@ -1224,11 +2031,17 @@ function run() {
     case "new-campaign":
       return runNewCampaign(root, args[0]);
     case "validate":
-      return runValidate(root, args[0]);
+      return runValidate(root, args[0], { verifyGithub: values["verify-github"] });
     case "status":
       return runStatus(root);
+    case "icp":
+      return runIcp(root);
     case "approve":
-      return runApprove(root, args, { by: values.by, notes: values.notes, date: values.date });
+      return runApprove(root, args, { by: values.by, notes: values.notes, date: values.date, pr: values.pr });
+    case "track":
+      return runTrack(root, args, { pr: values.pr });
+    case "github":
+      return runGithub(root, args, { apply: values.apply });
     case "sync":
       return runSync(root, { check: values.check });
     case "migrate":
@@ -1236,7 +2049,7 @@ function run() {
     case "upgrade":
       return runUpgrade(root, { version: args[0], force: values.force });
     case "job":
-      return runJob(args[0]);
+      return runJob(root, args);
     case void 0:
       return help(void 0);
     case "help":
@@ -1248,4 +2061,4 @@ ${generalHelp(GTM_VERSION)}`);
       return false;
   }
 }
-process.exit(run() ? 0 : 1);
+process.exit(await run() ? 0 : 1);