@mcptoolshop/housekeeping 1.4.0 → 1.5.0

package/housekeeping.config.example.json

@@ -1,5 +1,6 @@
 {
   "org": "your-org",
   "metaRepos": [".github"],
-  "homeOrgs": ["your-org"]
+  "homeOrgs": ["your-org"],
+  "watch": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcptoolshop/housekeeping",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Operational-health warehouse for a GitHub organization: CI, issues, PRs, releases, Actions cost and repo hygiene, collected into SQLite and audited against written rules.",
   "keywords": [
     "github",

package/src/cli.mjs

@@ -9,7 +9,7 @@ import { openDb, loadSnapshot, latestSnapshotFile, DB_PATH } from './load.mjs';
 import { analyze, healthScores, RUN_IS_LIVE_MAINLINE_SIGNAL, HEAD_CHECKS_RED } from './analyze.mjs';
 import { collect, DRILL_BUDGET } from './collect.mjs';
 import { preflight } from './gh.mjs';
-import { resolveOrg } from './config.mjs';
+import { resolveOrg, loadConfig } from './config.mjs';
 import { writeReport } from './report.mjs';
 import { EXIT, HkError, userError, exitCodeFor, formatError, readOnlyQuery, sweepGaps } from './errors.mjs';
 import { info, isDebug, levelFromFlags, parseLevel, setLevel } from './log.mjs';
@@ -141,6 +141,35 @@ const REPORTS = {
            disk_usage_kb kb, days_since_push push_age, open_issues iss, open_prs prs,
            release_count rels, ci_rollup, workflow_count wfs
     FROM repo WHERE snapshot_id=? ORDER BY name`).all(sid), { max: 200 }),
+  // Branches by repo: what a cleanup would delete (merged), what it must not
+  // (merged_moved: commits after the merge), and what has no PR at all.
+  branches: (sid, repo) => {
+    if (!db.prepare('SELECT 1 FROM repo_branches WHERE snapshot_id=? LIMIT 1').get(sid)) {
+      return console.log('no branch data in this snapshot (collector 1.6.0 or later) - run `hk refresh`');
+    }
+    if (repo) {
+      return table(db.prepare(`SELECT name, state, age_days age, pr_number pr, SUBSTR(head_oid,1,7) head
+        FROM branch WHERE snapshot_id=? AND repo=? ORDER BY state, age_days DESC`).all(sid, repo), { max: 500 });
+    }
+    table(db.prepare(`SELECT s.repo, CASE s.delete_on_merge WHEN 1 THEN 'on' WHEN 0 THEN 'off' END auto_delete,
+        s.branch_count branches,
+        SUM(b.state='merged') merged, SUM(b.state='merged_moved') moved,
+        SUM(b.state='closed') closed, SUM(b.state='no_pr' AND b.age_days>=${STALE_BRANCH_DAYS}) no_pr_stale,
+        SUM(b.state IN ('open_pr','open_base')) open
+      FROM repo_branches s LEFT JOIN branch b ON b.snapshot_id=s.snapshot_id AND b.repo=s.repo
+      WHERE s.snapshot_id=? GROUP BY s.repo HAVING s.branch_count > 1
+      ORDER BY merged + moved + closed + no_pr_stale DESC, s.repo`).all(sid), { max: 200 });
+  },
+  watch: (sid, ...names) => {
+    const repos = names.length ? names : loadConfig().watch;
+    if (!repos.length) {
+      throw userError('USAGE', 'no repositories to watch',
+        'name them (hk watch <repo> ...) or set "watch" in housekeeping.config.json');
+    }
+    const s = db.prepare('SELECT taken_at, collector_version FROM snapshot WHERE id=?').get(sid);
+    console.log(`watch: ${repos.join(', ')}\nsnapshot ${sid}, taken ${s.taken_at} (collector ${s.collector_version})`);
+    for (const name of repos) watchRepo(sid, name);
+  },
   repo: (sid, name) => {
     if (!name) throw userError('USAGE', '`hk repo` needs a repository name', 'hk repo <name>');
     table(db.prepare('SELECT * FROM repo WHERE snapshot_id=? AND name=?').all(sid, name));
@@ -155,6 +184,56 @@ const REPORTS = {
 
 function latestOr(sid) { return sid; }
 
+// A branch with no PR and no commit for this long is listed as stale. The
+// number is the Publisher's sweep brief of 2026-10-11, not an org rule.
+const STALE_BRANCH_DAYS = 7;
+
+// One watched repo: open PRs by idle time, open alerts, and the branches a
+// cleanup would touch. Every section says when it was not measured, because
+// an empty list from an unscanned repo reads exactly like a clean one.
+function watchRepo(sid, name) {
+  const r = db.prepare('SELECT is_archived FROM repo WHERE snapshot_id=? AND name=?').get(sid, name);
+  console.log(`\n== ${name}`);
+  if (!r) return console.log('not in this snapshot (misspelt, or not in the org)');
+  if (r.is_archived) console.log('archived');
+
+  const prs = db.prepare(`SELECT number, stale_days idle, age_days age, is_draft draft, mergeable,
+      base_ref base, head_ref head, SUBSTR(title,1,60) title
+    FROM pull_request WHERE snapshot_id=? AND repo=? ORDER BY stale_days DESC, number`).all(sid, name);
+  console.log(`\n-- open PRs (${prs.length}), longest idle first --`);
+  table(prs);
+
+  const sec = db.prepare('SELECT vuln_alerts FROM repo_security WHERE snapshot_id=? AND repo=?').get(sid, name);
+  console.log('\n-- open Dependabot alerts --');
+  if (!sec) console.log('not measured (the security pass did not read this repo)');
+  else if (sec.vuln_alerts === 0) console.log('NOT SCANNED: vulnerability alerts are off, so no alert can appear');
+  else {
+    if (sec.vuln_alerts === null) console.log('(whether alerts are on could not be read)');
+    table(db.prepare(`SELECT number, severity, package, manifest, fixed_version fix, age_days age, ghsa
+      FROM security_alert WHERE snapshot_id=? AND repo=?
+      ORDER BY CASE severity WHEN 'critical' THEN 0 WHEN 'high' THEN 1 WHEN 'medium' THEN 2 ELSE 3 END, number`)
+      .all(sid, name));
+  }
+
+  const set = db.prepare('SELECT delete_on_merge, branch_count FROM repo_branches WHERE snapshot_id=? AND repo=?').get(sid, name);
+  console.log('\n-- branches --');
+  if (!set) return console.log('not measured (no branch data for this repo in this snapshot)');
+  const auto = set.delete_on_merge === 1 ? 'on' : set.delete_on_merge === 0 ? 'off' : 'unknown';
+  const rows = db.prepare(`SELECT name, state, age_days age, pr_number pr, SUBSTR(head_oid,1,7) head
+    FROM branch WHERE snapshot_id=? AND repo=? ORDER BY name`).all(sid, name);
+  const of = st => rows.filter(b => b.state === st);
+  const stale = of('no_pr').filter(b => b.age_days >= STALE_BRANCH_DAYS);
+  console.log(`${set.branch_count} branches; auto-delete head branches: ${auto}; ` +
+    `open ${of('open_pr').length + of('open_base').length}, merged ${of('merged').length}, ` +
+    `moved after merge ${of('merged_moved').length}, closed ${of('closed').length}, ` +
+    `no PR ${of('no_pr').length} (${stale.length} idle ${STALE_BRANCH_DAYS}+ days)`);
+  const list = (label, bs) => { if (bs.length) { console.log(`\n${label}:`); table(bs); } };
+  list('merged, tip = merged head (deletable; restorable from the PR page)', of('merged'));
+  list('MOVED after merge (commits exist only here; do not delete unconfirmed)', of('merged_moved'));
+  list('closed without merging', of('closed'));
+  list(`no PR, idle ${STALE_BRANCH_DAYS}+ days`, stale);
+}
+
 // ---- commands ---------------------------------------------------------------
 // One table drives both the dispatch and `hk help`, so the help text cannot
 // describe a command that does not exist or omit one that does.
@@ -178,7 +257,9 @@ async function refresh(args) {
   // silently.
   const pre = await preflight({
     rest: 300 + Math.min(DRILL_BUDGET, 900),
-    graphql: 300,
+    // ~195 for the repo pages and workflow files, ~1 per repo for the
+    // branch pass (collector 1.6.0, measured 2026-10-11), with headroom.
+    graphql: 450,
   });
   if (!pre.ok && !force) {
     if (pre.limit === 'secondary') {
@@ -265,6 +346,8 @@ const COMMANDS = {
   versions:         ['',                'package.json against git tag against npm', viaReport('versions')],
   prs:              ['',                'every open pull request by age', viaReport('prs')],
   issues:           ['',                'every open issue by staleness', viaReport('issues')],
+  branches:         ['[repo]',          'branches by state: merged, moved after merge, closed, no PR', viaReport('branches')],
+  watch:            ['[repo ...]',      'open PRs, alerts and branches for the watch list in the config', viaReport('watch')],
   snapshots:        ['',                'the snapshots loaded into the database', () => {
     db = openDb();
     table(db.prepare('SELECT id, taken_at, org, repo_count, duration_ms FROM snapshot ORDER BY id').all());

package/src/collect.mjs

@@ -14,7 +14,7 @@ import { priceRun, ratesFromUsage, withFallback, runnerClass } from './cost.mjs'
 import { pagesDeployJobs, jobEnvironment } from './workflow-risks.mjs';
 import { DATA_DIR } from './paths.mjs';
 
-export const COLLECTOR_VERSION = '1.5.0';
+export const COLLECTOR_VERSION = '1.6.0';
 
 const REPO_FIELDS = `
   id name description url homepageUrl
@@ -622,7 +622,7 @@ function readAtlasCache() {
  */
 async function atlasFleetVersion(fetchImpl = fetch) {
   try {
-    const res = await fetchImpl(`https://registry.npmjs.org/${ATLAS_PACKAGE.replace('/', '%2f')}`, {
+    const res = await fetchImpl(`https://registry.npmjs.org/${encodeURIComponent(ATLAS_PACKAGE)}`, {
       headers: { accept: 'application/vnd.npm.install-v1+json' }, signal: AbortSignal.timeout(30_000),
     });
     if (!res.ok) return { version: null, source: 'npm dist-tags latest', error: `http_${res.status}` };
@@ -694,7 +694,7 @@ async function collectNpm(repos, concurrency = 12) {
     .filter(x => x.pkg && x.pkg.name && !x.pkg.private);
 
   const results = await pMap(named, async x => {
-    const res = await fetch(`https://registry.npmjs.org/${x.pkg.name.replace('/', '%2f')}`, {
+    const res = await fetch(`https://registry.npmjs.org/${encodeURIComponent(x.pkg.name)}`, {
       headers: { accept: 'application/vnd.npm.install-v1+json' },
     });
     if (res.status === 404) return { repo: x.repo, pkg_name: x.pkg.name, status: 'unpublished' };
@@ -817,6 +817,74 @@ async function collectSecurity(org, repos, concurrency = 10) {
   return { ok: alertsOk, alerts, auto_security_fixes: fixes, vulnerability_alerts: scanned };
 }
 
+// Every branch, the pull requests it was the head of, and whether the repo
+// deletes a head branch when its pull request merges.
+//
+// A merged PR's branch is restorable from the PR page only while its tip is
+// the commit the PR merged; a branch pushed to after its merge carries work
+// that exists nowhere else. So the head commit is kept beside each PR's
+// headRefOid, and the loader tells the two apart.
+//
+// Cost: one GraphQL query per non-archived, non-empty repo, plus one per
+// further 100 branches. Measured 2026-10-11 by rateLimit(dryRun): 1 point per
+// repo at first:100 with five associated PRs per branch (8 repos: 8 points).
+const BRANCH_QUERY = `
+query($owner:String!, $name:String!, $cursor:String) {
+  repository(owner:$owner, name:$name) {
+    deleteBranchOnMerge
+    refs(refPrefix:"refs/heads/", first:100, after:$cursor) {
+      totalCount
+      pageInfo { hasNextPage endCursor }
+      nodes {
+        name
+        target { ... on Commit { oid committedDate } }
+        associatedPullRequests(first:5, orderBy:{field:UPDATED_AT, direction:DESC}) {
+          nodes { number state headRefOid }
+        }
+      }
+    }
+  }
+}`;
+
+export async function collectBranches(org, repos, { query = graphql, concurrency = 6 } = {}) {
+  const out = {};
+  const errors = [];
+  const targets = repos.filter(r => !r.isArchived && !r.isEmpty);
+  await pMap(targets, async r => {
+    const branches = [];
+    let cursor = null, total = 0, deleteOnMerge = null;
+    try {
+      for (;;) {
+        const body = await query(BRANCH_QUERY, { owner: org, name: r.name, cursor });
+        const repo = body.data?.repository;
+        if (!repo) throw new Error('repository not visible');
+        deleteOnMerge = repo.deleteBranchOnMerge ?? null;
+        total = repo.refs?.totalCount ?? 0;
+        for (const b of repo.refs?.nodes ?? []) {
+          branches.push({
+            name: b.name,
+            oid: b.target?.oid ?? null,
+            committed_at: b.target?.committedDate ?? null,
+            prs: (b.associatedPullRequests?.nodes ?? []).map(p => ({
+              number: p.number, state: p.state, head_oid: p.headRefOid ?? null,
+            })),
+          });
+        }
+        cursor = repo.refs?.pageInfo?.hasNextPage ? repo.refs.pageInfo.endCursor : null;
+        if (!cursor) break;
+      }
+      out[r.name] = { delete_branch_on_merge: deleteOnMerge, total, branches };
+    } catch (e) {
+      // A repo that could not be read gets no record at all, never an empty
+      // one: no branches would read as "nothing to clean up".
+      errors.push({ repo: r.name, stage: 'branches', message: String(e.message ?? e).slice(0, 200) });
+    }
+  }, concurrency);
+  const n = Object.values(out).reduce((s, x) => s + x.branches.length, 0);
+  log(`branches: ${n} in ${Object.keys(out).length} repos, ${errors.length} unreadable`);
+  return { ok: errors.length === 0, repos: out, errors };
+}
+
 // ---------------------------------------------------------------------------
 // Committed lockfiles, audited by the warehouse itself. See lockfile.mjs for
 // why GitHub's own count cannot be trusted per manifest.
@@ -1097,6 +1165,7 @@ async function sweep(org, ctx) {
   ctx.stage = 'deploy_settings'; const deploySettings = await collectDeploySettings(org, repos, workflowFiles);
   ctx.stage = 'npm';            const npm = await collectNpm(repos);
   ctx.stage = 'security';       const security = await collectSecurity(org, repos);
+  ctx.stage = 'branches';       const branches = await collectBranches(org, repos);
   ctx.stage = 'lockfiles';      const lockfiles = await collectLockfiles(org, repos);
   ctx.stage = 'atlas_maps';     const atlasMaps = await collectAtlasMaps(org, repos);
   ctx.stage = 'billing';        const billing = await collectBilling(org);
@@ -1121,13 +1190,14 @@ async function sweep(org, ctx) {
     deploy_settings: { ok: deploySettings.ok, calls: deploySettings.calls, repos: deploySettings.repos },
     npm,
     security,
+    branches: { ok: branches.ok, repos: branches.repos },
     lockfiles,
     // fetched/cached counts are left out: they describe this machine's cache,
     // not the org, and would make two identical observations look different.
     atlas_maps: { ok: atlasMaps.ok, fleet_version: atlasMaps.fleet_version, repos: atlasMaps.repos },
     billing,
     run_costs: runCosts,
-    errors: errors.concat(deploySettings.errors ?? [], runCosts.errors ?? [],
+    errors: errors.concat(deploySettings.errors ?? [], runCosts.errors ?? [], branches.errors,
       failedSteps.runs.filter(x => x.error).map(x => ({ repo: x.repo, stage: 'failed_steps', message: x.error }))),
   };
 

package/src/config.mjs

@@ -8,12 +8,17 @@
 //
 //   housekeeping.config.json
 //   { "org": "your-org", "metaRepos": [".github", "design-assets"],
-//     "homeOrgs": ["your-org", "your-other-org"] }
+//     "homeOrgs": ["your-org", "your-other-org"],
+//     "watch": ["repo-a", "repo-b"] }
 //
 // `homeOrgs` names the organizations whose projects count as the org's own.
 // A fork of a project outside them is exempt from the map rule. Unset, it is
 // the swept org alone.
 //
+// `watch` names the repos `hk watch` reports on when it is given none: a short
+// list someone reviews every week. It narrows a view, never the sweep, and
+// changes no finding.
+//
 // No network and no database here, so every branch is unit-testable.
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
@@ -22,7 +27,7 @@ import { WORK_DIR } from './paths.mjs';
 
 export const CONFIG_PATH = process.env.HK_CONFIG ?? join(WORK_DIR, 'housekeeping.config.json');
 
-const KEYS = ['org', 'metaRepos', 'homeOrgs'];
+const KEYS = ['org', 'metaRepos', 'homeOrgs', 'watch'];
 const invalid = message => userError('CONFIG_INVALID', message,
   'fix housekeeping.config.json; housekeeping.config.example.json shows the shape');
 const DEFAULT_META = ['.github'];
@@ -56,7 +61,11 @@ export function parseConfig(text) {
   if (home !== null && (!Array.isArray(home) || !home.length || home.some(o => typeof o !== 'string' || !o.trim()))) {
     throw invalid('housekeeping config: "homeOrgs" must be a non-empty array of organization names');
   }
-  return { org, metaRepos: [...meta], homeOrgs: home ? [...home] : null };
+  const watch = raw.watch ?? [];
+  if (!Array.isArray(watch) || watch.some(w => typeof w !== 'string' || !w.trim())) {
+    throw invalid('housekeeping config: "watch" must be an array of repo names');
+  }
+  return { org, metaRepos: [...meta], homeOrgs: home ? [...home] : null, watch: [...watch] };
 }
 
 /** Read the config file. A missing file is the defaults; an unreadable or malformed one throws. */
@@ -64,7 +73,7 @@ export function loadConfig(path = CONFIG_PATH) {
   let text;
   try { text = readFileSync(path, 'utf8'); }
   catch (e) {
-    if (e.code === 'ENOENT') return { org: null, metaRepos: [...DEFAULT_META], homeOrgs: null };
+    if (e.code === 'ENOENT') return { org: null, metaRepos: [...DEFAULT_META], homeOrgs: null, watch: [] };
     throw e;
   }
   return parseConfig(text);

package/src/load.mjs

@@ -103,8 +103,10 @@ export function openDb(path = DB_PATH, { fresh = false } = {}) {
  *
  * `atlasEnv` maps a job key to the `environment` the repository's Atlas map
  * records for it (Atlas 1.24.0 and later), when the map has this file.
+ * `isPrivate` is the repository's visibility, which decides whether a job
+ * gated to public repositories can run at all.
  */
-export function inspectWorkflow(text, path, defaultBranch = null, atlasEnv = null) {
+export function inspectWorkflow(text, path, defaultBranch = null, atlasEnv = null, isPrivate = false) {
   const out = {
     path, name: path.split('/').pop(), state: 'unknown',
     has_paths_filter: 0, has_workflow_dispatch: 0, has_concurrency: 0,
@@ -197,7 +199,7 @@ export function inspectWorkflow(text, path, defaultBranch = null, atlasEnv = nul
   out.schedule_gaps = gaps ? gaps.join('\n') : null;
 
   // The deploy doors, joined in analyze.mjs to the settings they depend on.
-  out.pages_deploy_jobs = pagesDeployJobs(jobEntries).join('\n');
+  out.pages_deploy_jobs = pagesDeployJobs(jobEntries, { isPrivate }).join('\n');
   // The environment a job deploys to is a fact Atlas also records, so where
   // the map names one it is preferred: one definition for both tools. This
   // file's own reading is kept beside it, so a disagreement stays visible.
@@ -467,6 +469,38 @@ export function failedStepRows(record, text) {
   return rows;
 }
 
+/**
+ * Classify one repo's branches (schema.sql, table `branch`). Pure.
+ *
+ * Order matters, and each step was a real case on 2026-10-11:
+ * - an open PR beats a merged one: a branch reused for a second PR is live;
+ * - being an open PR's BASE beats being merged: a stacked PR targets it, and
+ *   deleting it would retarget or close that PR;
+ * - "merged" needs the tip to equal the merged head. Four branches had commits
+ *   pushed after their PR merged, which the PR page's restore cannot bring back.
+ */
+export function branchRows(record, { defaultBranch = null, openBases = [] } = {}) {
+  const bases = new Set(openBases);
+  const rows = [];
+  for (const b of record?.branches ?? []) {
+    if (b.name === defaultBranch) continue;
+    const prs = b.prs ?? [];
+    const open = prs.find(p => p.state === 'OPEN');
+    const merged = prs.filter(p => p.state === 'MERGED');
+    const exact = merged.find(p => p.head_oid && p.head_oid === b.oid);
+    let state, pr = null;
+    if (open)                  { state = 'open_pr'; pr = open.number; }
+    else if (bases.has(b.name)) state = 'open_base';
+    else if (exact)            { state = 'merged'; pr = exact.number; }
+    else if (merged.length)    { state = 'merged_moved'; pr = merged[0].number; }
+    else if (prs.length)       { state = 'closed'; pr = prs[0].number; }
+    else                        state = 'no_pr';
+    rows.push({ name: b.name, state, head_oid: b.oid ?? null,
+      committed_at: b.committed_at ?? null, age_days: daysSince(b.committed_at), pr_number: pr });
+  }
+  return rows;
+}
+
 export function isWorkspaceRoot(pkg, rootEntryNames = [], pnpmWorkspaceText) {
   if (pkg?.workspaces) return true;
   const names = new Set(rootEntryNames.map(n => String(n).toLowerCase()));
@@ -542,6 +576,8 @@ function loadSnapshotInner(db, snap) {
     lock: insertInto('lockfile'),
     lockAdv: insertInto('lockfile_advisory'),
     bprot: insertInto('branch_protection'),
+    branch: insertInto('branch'),
+    repoBranches: insertInto('repo_branches'),
     ctx: insertInto('check_context'),
     bill: insertInto('billing_usage'),
     runCost: insertInto('run_cost'),
@@ -692,7 +728,7 @@ function loadSnapshotInner(db, snap) {
     const atlasEnvByFile = new Map(mapDoors.filter(d => Array.isArray(d.jobs)).map(d => [d.file,
       new Map(d.jobs.filter(j => j && typeof j.name === 'string' && j.environment).map(j => [j.name, j.environment]))]));
     for (const f of wfFiles) {
-      const w = inspectWorkflow(f.text, f.path, r.defaultBranchRef?.name ?? null, atlasEnvByFile.get(f.path) ?? null);
+      const w = inspectWorkflow(f.text, f.path, r.defaultBranchRef?.name ?? null, atlasEnvByFile.get(f.path) ?? null, !!r.isPrivate);
       stmts.wf.run(sid, r.name, w.path, w.name, w.state,
         w.has_paths_filter, w.has_workflow_dispatch, w.has_concurrency,
         w.runners, w.uses_macos, w.uses_windows,
@@ -791,6 +827,22 @@ function loadSnapshotInner(db, snap) {
     }
   }
 
+  // ---- branches ------------------------------------------------------------
+  // Absent `branches` (an older snapshot) or a repo missing from it (archived,
+  // empty, unreadable) leaves no rows: not measured, never "nothing to clean".
+  if (snap.branches) {
+    for (const r of snap.repos) {
+      const rec = snap.branches.repos?.[r.name];
+      if (!rec) continue;
+      stmts.repoBranches.run(sid, r.name,
+        rec.delete_branch_on_merge === null ? null : bool(rec.delete_branch_on_merge), rec.total ?? null);
+      const openBases = (r.prList?.nodes ?? []).map(p => p.baseRefName).filter(Boolean);
+      for (const b of branchRows(rec, { defaultBranch: r.defaultBranchRef?.name ?? null, openBases })) {
+        stmts.branch.run(sid, r.name, b.name, b.state, b.head_oid, b.committed_at, b.age_days, b.pr_number);
+      }
+    }
+  }
+
   // ---- committed lockfiles, audited directly ------------------------------
   // Absent `lockfiles` means the pass did not run (older snapshot): no rows,
   // and the analyzer stays silent rather than reporting zero exposure.

package/src/schema.sql

@@ -371,6 +371,31 @@ CREATE TABLE IF NOT EXISTS cost_reconciliation (
   ratio REAL, trustworthy INTEGER, reason TEXT
 );
 
+-- One row per non-default branch (collect.mjs collectBranches). `state` is
+-- decided at load time (load.mjs branchRows), first match wins:
+--   open_pr       the head of an open pull request
+--   open_base     the base of an open pull request (a stacked PR targets it)
+--   merged        its PR merged and the tip IS the merged head: restorable
+--                 from the PR page, so deleting it loses nothing
+--   merged_moved  its PR merged, but the tip moved after: those commits exist
+--                 only on this branch
+--   closed        only closed, unmerged pull requests
+--   no_pr         never the head of a pull request
+-- Data, not findings: no org rule names stale branches. No rows for a repo
+-- means not measured (archived, empty, unreadable, or an older snapshot).
+CREATE TABLE IF NOT EXISTS branch (
+  snapshot_id INTEGER, repo TEXT, name TEXT, state TEXT,
+  head_oid TEXT, committed_at TEXT, age_days INTEGER,
+  pr_number INTEGER                 -- the PR the state was decided by, if any
+);
+
+-- Per-repo branch settings, one row per repo the branch pass read.
+CREATE TABLE IF NOT EXISTS repo_branches (
+  snapshot_id INTEGER, repo TEXT,
+  delete_on_merge INTEGER,          -- "Automatically delete head branches": 1 on, 0 off
+  branch_count INTEGER              -- every branch, the default included
+);
+
 CREATE TABLE IF NOT EXISTS finding (
   snapshot_id INTEGER, repo TEXT, code TEXT, severity TEXT,
   category TEXT, message TEXT, evidence TEXT
@@ -387,6 +412,7 @@ CREATE INDEX IF NOT EXISTS idx_wf_snap      ON workflow(snapshot_id, repo);
 CREATE INDEX IF NOT EXISTS idx_wfrun_snap   ON workflow_run(snapshot_id, repo);
 CREATE INDEX IF NOT EXISTS idx_finding_snap ON finding(snapshot_id, severity, code);
 CREATE INDEX IF NOT EXISTS idx_bprot_snap   ON branch_protection(snapshot_id, repo);
+CREATE INDEX IF NOT EXISTS idx_branch_snap  ON branch(snapshot_id, repo);
 CREATE INDEX IF NOT EXISTS idx_ctx_snap     ON check_context(snapshot_id, repo);
 CREATE INDEX IF NOT EXISTS idx_bill_snap    ON billing_usage(snapshot_id, repo);
 CREATE INDEX IF NOT EXISTS idx_rcost_snap   ON run_cost(snapshot_id, repo);

package/src/workflow-risks.mjs

@@ -184,14 +184,47 @@ export function auditSteps(doc, jobs) {
 
 const jobSteps = job => (job && typeof job === 'object' && Array.isArray(job.steps) ? job.steps : []);
 
-/** Job ids with a step that uses actions/deploy-pages, at any version. */
-export function pagesDeployJobs(jobEntries) {
+/**
+ * Job ids with a step that uses actions/deploy-pages, at any version.
+ *
+ * In a private repository a job that skips itself there is left out: Pages on
+ * a private repo is a plan feature, and a deploy gated on
+ * `!github.event.repository.private` is how a workflow says "only when public".
+ * That job never reaches deploy-pages, so Pages being off refuses nothing.
+ */
+export function pagesDeployJobs(jobEntries, { isPrivate = false } = {}) {
+  const byId = new Map(jobEntries);
   return jobEntries
     .filter(([, job]) => jobSteps(job).some(st =>
       typeof st?.uses === 'string' && /^actions\/deploy-pages(?:@|$)/i.test(st.uses.trim())))
+    .filter(([id]) => !(isPrivate && skipsWhenPrivate(byId, id)))
     .map(([id]) => id);
 }
 
+// A term that is false exactly when the repository is private.
+const PUBLIC_ONLY = /^(?:!\s*github\.event\.repository\.private|github\.event\.repository\.private\s*==\s*false|github\.event\.repository\.private\s*!=\s*true|github\.event\.repository\.visibility\s*==\s*'public')$/;
+
+/**
+ * True when the job cannot run in a private repository: its own `if:` is a
+ * conjunction with a public-only term, or it has no `if:` of its own (so
+ * GitHub's implicit success() applies) and a job it needs cannot run. Any
+ * `||`, or anything else this cannot read, is false: unknown never excuses.
+ */
+export function skipsWhenPrivate(byId, id, seen = new Set()) {
+  if (seen.has(id)) return false;
+  seen.add(id);
+  const job = byId.get(id);
+  if (!job || typeof job !== 'object') return false;
+  if (job.if !== undefined) {
+    if (typeof job.if !== 'string') return false;
+    const expr = job.if.trim().replace(/^\$\{\{\s*([\s\S]*?)\s*\}\}$/, '$1');
+    if (expr.includes('||')) return false;
+    return expr.split('&&').some(t => PUBLIC_ONLY.test(t.trim().replace(/^\((.*)\)$/, '$1').trim()));
+  }
+  const needs = typeof job.needs === 'string' ? [job.needs] : (Array.isArray(job.needs) ? job.needs : []);
+  return needs.some(n => skipsWhenPrivate(byId, n, seen));
+}
+
 /**
  * The environment a job names, or null when it names none or names it with an
  * expression. `environment:` is either a string or `{ name, url }`. A name built