@arjunkhera/atlas 0.4.21 → 0.4.23

package/door/lib/jobs.mjs

@@ -25,6 +25,8 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseYaml } from '../../shape/check.mjs';
 import { api, apiBase, repoOk, openIssues, TOKEN_SHAPE, DEFAULT_BOT, DEFAULT_MAX } from './issues.mjs';
+import { checkGateFiles, checkGateAudit, checkGateErrors } from './gate-audit.mjs';
+import { commitAudit, ghApi } from './gate.mjs';
 
 export const JOBS_LABEL = 'atlas-job';
 export const HANDED_OVER = 'handed-over';
@@ -107,9 +109,16 @@ export async function checkRedMain({ repo, branch, env }) {
 
 // The check of each Atlas job, by its `when`. A job whose check is not built yet reads `none` and
 // says so in the notes; it never reads `found` from nothing.
-const CHECKS = { 'red-main': checkRedMain };
+// The gate jobs (roadmap R14) read GitHub through `gh`, which the Actions
+// runner holds; their token is the run's own GITHUB_TOKEN.
+const CHECKS = {
+  'red-main': checkRedMain,
+  'gate-files': ({ root, env, fetchImpl }) => checkGateFiles({ root, env, fetchImpl }),
+  'gate-audit': ({ repo, branch, gh }) => checkGateAudit({ repo, branch, gh, audit: commitAudit }),
+  'gate-errors': ({ repo, gh }) => checkGateErrors({ repo, gh }),
+};
 
-export async function jobsCheck({ root, repo, branch = null, env = process.env, jobs = atlasJobs() }) {
+export async function jobsCheck({ root, repo, branch = null, env = process.env, jobs = atlasJobs(), gh = ghApi, fetchImpl = fetch }) {
   const named = namedJobs(root);
   const notes = [];
   const ran = [];
@@ -123,7 +132,10 @@ export async function jobsCheck({ root, repo, branch = null, env = process.env,
     if (!check) { notes.push(`${id}: its check is not built yet`); ran.push({ job: id, state: 'none' }); continue; }
     try {
       if (!mainBranch) mainBranch = await defaultBranch({ repo, env });
-      const found = (await check({ repo, branch: mainBranch, env })).map((f) => ({ ...f, job: id }));
+      // A check gives its findings, or { findings, notes }.
+      const got = await check({ repo, branch: mainBranch, env, root, gh, fetchImpl });
+      const found = (Array.isArray(got) ? got : got.findings).map((f) => ({ ...f, job: id }));
+      for (const note of Array.isArray(got) ? [] : got.notes ?? []) notes.push(`${id}: ${String(note).slice(0, 300)}`);
       findings.push(...found);
       ran.push({ job: id, state: found.length ? 'found' : 'none' });
     } catch (error) {
@@ -194,13 +206,22 @@ export function jobIssue(finding) {
 export const handedOverStops = (now = Date.now()) => (issue) => (issue.labels ?? []).some((l) => (typeof l === 'string' ? l : l?.name) === HANDED_OVER)
   && Number.isFinite(Date.parse(issue.closed_at)) && now - Date.parse(issue.closed_at) <= HANDED_OVER_DAYS * DAY;
 
+// A job with `handed_over: ignored` never stops on a closed issue: anyone with
+// the shared login can close an issue, so a gate finding comes back while its
+// commit is in the window (roadmap R14).
+export const closedStopsFor = (jobs, now = Date.now()) => (issue) => {
+  const job = (issue.labels ?? []).map((l) => (typeof l === 'string' ? l : l?.name)).find((name) => String(name).startsWith('job:'));
+  if (job && jobs.get(job.slice(4))?.handed_over === 'ignored') return false;
+  return handedOverStops(now)(issue);
+};
+
 export async function fileJobs({ envelope, repo, dryRun = false, max = DEFAULT_MAX, bot = DEFAULT_BOT, env = process.env, line, now = Date.now(), jobs = atlasJobs() }) {
   const { findings, dropped } = typedFindings(envelope, jobs);
   if (dropped) line(`dropped ${dropped} finding(s) that are not typed, or that name no Atlas job`);
   if (envelope.state === 'broken') line('the check reads broken, so a check found nothing it can trust. The run ends red.');
   const list = findings.map((f) => ({ key: `${f.job}:${f.key}`, issue: jobIssue(f) }));
   const result = list.length
-    ? await openIssues({ findings: list, repo, dryRun, max, bot, env, line, label: JOBS_LABEL, closedStops: handedOverStops(now) })
+    ? await openIssues({ findings: list, repo, dryRun, max, bot, env, line, label: JOBS_LABEL, closedStops: closedStopsFor(jobs, now) })
     : (line('no finding: nothing to file.'), { opened: [], skipped: [], deferred: [], failed: [] });
   return { ...result, broken: envelope.state === 'broken' };
 }

package/door/lib/procedure-steps.mjs

@@ -0,0 +1,122 @@
+// CI runs the procedures (roadmap R40, item 38b2a0fe). Target design 4.6: CI
+// runs each procedure step that a clean machine can run.
+//
+// A procedure marks such a step with a fenced block whose info string holds
+// the tag `atlas-run`:
+//
+//   ```sh atlas-run
+//   npm test
+//   ```
+//
+// A step that needs what a clean machine does not have names it after the
+// tag: `atlas-run needs=secret/NPM_TOKEN` or `atlas-run needs=device/macos`.
+// Such a step is listed as "not run here", never as passed.
+//
+// `atlas upkeep procedures` runs the marked steps of each procedure that
+// atlas.yaml `procedures:` names. With --base, it runs only the procedures a
+// pull request changes: its own folder, or a path its `sources:` names. Each
+// block runs in bash, from the repo root, with `set -euo pipefail`. It reads
+// no repo kind, so a repo with no deploy target uses it unchanged.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fenceOpens, fenceCloses } from './markdown.mjs';
+import { docUnits, covers, changedPaths } from './doc-sources.mjs';
+
+export const TAG = 'atlas-run';
+const SHELLS = new Set(['sh', 'bash', 'shell']);
+const NEEDS = new Set(['secret', 'device', 'network']);
+// The bound on one block. A step that runs longer is a failure. It sits
+// below the 10 minutes of the CI job, so the step fails with a reason.
+export const STEP_TIMEOUT_MS = 8 * 60 * 1000;
+
+// Line 1: the marked steps of one procedure text. Each step is one fenced
+// block. `problems` holds a tag that cannot run as written.
+export function markedSteps(text) {
+  const steps = [];
+  const problems = [];
+  const lines = String(text ?? '').split('\n');
+  for (let i = 0; i < lines.length; i += 1) {
+    const mark = fenceOpens(lines[i]);
+    if (!mark) continue;
+    const info = lines[i].trim().slice(mark.length).trim().split(/\s+/).filter(Boolean);
+    const start = i;
+    const body = [];
+    for (i += 1; i < lines.length && !fenceCloses(lines[i], mark); i += 1) body.push(lines[i]);
+    if (!info.includes(TAG)) continue;
+    const line = start + 1;
+    const lang = info[0] === TAG ? null : info[0];
+    if (!SHELLS.has(lang)) { problems.push({ line, why: `the block is tagged ${TAG} but its language is ${lang ?? 'missing'}; use sh or bash` }); continue; }
+    if (i >= lines.length) { problems.push({ line, why: 'the block never closes' }); continue; }
+    const needs = [];
+    let bad = null;
+    for (const word of info.slice(info.indexOf(TAG) + 1)) {
+      const m = /^needs=(.+)$/.exec(word);
+      if (!m) { bad = `"${word}" after ${TAG} is not needs=<kind>/<name>`; break; }
+      for (const one of m[1].split(',')) {
+        const [kind, name] = one.split('/');
+        if (!NEEDS.has(kind) || !name) { bad = `"${one}" is not one of ${[...NEEDS].map((k) => `${k}/<name>`).join(', ')}`; break; }
+        needs.push({ kind, name });
+      }
+      if (bad) break;
+    }
+    if (bad) { problems.push({ line, why: bad }); continue; }
+    const script = body.join('\n').trim();
+    if (!script) { problems.push({ line, why: 'the block is empty' }); continue; }
+    steps.push({ line, script, needs });
+  }
+  return { steps, problems };
+}
+
+// The procedures to run. With `changed`, only those a pull request changes:
+// a path in the procedure's folder, or a path its `sources:` names.
+export function proceduresToRun(root, changed = null) {
+  const units = docUnits(root).filter((one) => one.kind === 'procedure');
+  if (changed === null) return units;
+  return units.filter((one) => changed.some((path) => path.startsWith(`${one.unit}/`)
+    || (one.named?.sources ?? []).some((source) => covers(root, source, path))));
+}
+
+const needsText = (needs) => needs.map((one) => `${one.kind} ${one.name}`).join(', ');
+
+// Line 2 and line 3: run each marked step of each chosen procedure. A step
+// that needs a secret, a device or the network is "not run here".
+export function runProcedures(root, { base = null, run = runStep } = {}) {
+  const changed = base === null ? null : changedPaths(root, `${base}...HEAD`);
+  const chosen = proceduresToRun(root, changed);
+  const rows = [];
+  for (const unit of chosen) {
+    const { steps, problems } = markedSteps(readFileSync(join(root, unit.where), 'utf8'));
+    for (const one of problems) rows.push({ procedure: unit.unit, where: `${unit.where}:${one.line}`, state: 'bad tag', why: one.why });
+    if (!steps.length && !problems.length) rows.push({ procedure: unit.unit, where: unit.where, state: 'no step', why: `it marks no step with ${TAG}` });
+    for (const step of steps) {
+      const where = `${unit.where}:${step.line}`;
+      if (step.needs.length) { rows.push({ procedure: unit.unit, where, state: 'not run here', why: `needs ${needsText(step.needs)}` }); continue; }
+      const result = run(root, step.script);
+      rows.push({ procedure: unit.unit, where, state: result.ok ? 'passed' : 'failed', why: result.why, tail: result.tail });
+    }
+  }
+  const red = rows.filter((row) => row.state === 'failed' || row.state === 'bad tag');
+  return { procedures: chosen.map((one) => one.unit), all: changed === null, rows, green: red.length === 0 };
+}
+
+export function runStep(root, script) {
+  const out = spawnSync('bash', ['-c', `set -euo pipefail\n${script}`], { cwd: root, encoding: 'utf8', timeout: STEP_TIMEOUT_MS, maxBuffer: 64 * 1024 * 1024 });
+  const tail = `${out.stdout ?? ''}${out.stderr ?? ''}`.trimEnd().split('\n').slice(-20).join('\n');
+  if (out.error?.code === 'ETIMEDOUT') return { ok: false, why: `it ran past ${STEP_TIMEOUT_MS / 60000} minutes`, tail };
+  if (out.error) return { ok: false, why: out.error.message, tail };
+  return out.status === 0 ? { ok: true, why: 'exit 0', tail } : { ok: false, why: `exit ${out.status ?? out.signal}`, tail };
+}
+
+// `atlas upkeep procedures`.
+export function proceduresCommand({ base = null, json = false }, root, line) {
+  const out = runProcedures(root, { base });
+  if (json) { process.stdout.write(`${JSON.stringify(out, null, 2)}\n`); return out.green ? 0 : 1; }
+  line(`procedures: ${out.procedures.length} to run${out.all ? '' : ` (the ones this change touches, from ${base})`}${out.procedures.length ? `: ${out.procedures.join(', ')}` : ''}`);
+  for (const row of out.rows) {
+    line(`  ${row.state.padEnd(12)} ${row.where}  ${row.why}`);
+    if (row.state === 'failed' && row.tail) for (const one of row.tail.split('\n')) line(`      | ${one}`);
+  }
+  line(`procedure steps: ${out.green ? 'GREEN' : 'RED'}`);
+  return out.green ? 0 : 1;
+}

package/door/lib/upkeep.mjs

@@ -23,6 +23,7 @@ import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
 import { join, dirname, posix, resolve } from 'node:path';
 import { listChanged } from './changed-tests.mjs';
 import { docSourceFindings, replay } from './doc-sources.mjs';
+import { proceduresCommand } from './procedure-steps.mjs';
 
 // R39 line 4 gates only after the replay of line 3. The replay of the last 30
 // merges (atlas#225): rule "file" pulled in 81 docs over 24 merges, 58 not
@@ -246,9 +247,10 @@ export function upkeepCheck(root, { event = null } = {}) {
   return { green: findings.length === 0, findings, notes: sources.notes, index, dead, item, text, sources };
 }
 
-export function upkeepCommand({ what, event: eventFile, json = false, last }, root, line) {
+export function upkeepCommand({ what, event: eventFile, json = false, last, base }, root, line) {
   if (what === 'replay') return replayCommand({ last, json }, root, line);
-  if (what !== 'check') throw new Error(`there is no upkeep verb "${what ?? ''}". Use atlas upkeep check, or atlas upkeep replay.`);
+  if (what === 'procedures') return proceduresCommand({ base: base ?? null, json }, root, line);
+  if (what !== 'check') throw new Error(`there is no upkeep verb "${what ?? ''}". Use atlas upkeep check, atlas upkeep replay or atlas upkeep procedures.`);
   let event = null;
   if (eventFile !== undefined) {
     try { event = JSON.parse(readFileSync(resolve(eventFile), 'utf8')); } catch (error) { throw new Error(`cannot read the event file ${eventFile}: ${error.message}`); }

package/door/templates/atlas-jobs.yml

@@ -5,7 +5,9 @@ name: atlas-jobs
 # It runs once a day from the default branch, and never on a pull request, so
 # a pull request cannot change what it runs. It has two jobs:
 #   check  reads the repo and the CI runs of the default branch. It holds only
-#          read permissions and the run's own token, and no repo secret.
+#          read permissions and the run's own token, and no repo secret. The
+#          gate jobs (gate-audit, gate-errors) also read pull requests and
+#          check runs, so the job reads those two as well.
 #   file   holds only issues write. It runs Atlas code on the JSON of the
 #          check job, and files one `atlas-job` issue for each new finding.
 # A job does nothing until atlas.yaml names it under `jobs: { atlas: [...] }`.
@@ -28,6 +30,8 @@ jobs:
     permissions:
       contents: read
       actions: read
+      pull-requests: read
+      checks: read
     outputs:
       findings: ${{ steps.check.outputs.findings }}
     steps:

package/door/workflows/atlas-gate-audit.yml

@@ -0,0 +1,128 @@
+name: atlas-gate-audit
+on:
+  push:
+    branches: [master]
+
+# The push audit of the advisory gate (roadmap R14, design
+# docs/design-docs/audit-job/). This plan gives the repo no rulesets, so
+# GitHub merges and takes pushes with no check. This workflow looks at each
+# commit that a push put on the main branch, along the first parent:
+#   1. A commit that no pull request merged is a push past the gate.
+#   2. A force push.
+#   3. A merge made before the required checks of its pull request were
+#      green. A check counts only from a run of the base file that defines it.
+#   4. A gate run that is not from the base copy of atlas-gate.yml.
+# Each finding opens one `atlas-job` issue, and the run ends red. It does not
+# undo the push.
+#
+# It runs the code of the pushed commit, so a push can edit it and hide. The
+# watcher (atlas-jobs.yml) runs the npm copy of Atlas once a day. It audits
+# the commits of the last two days again, and compares these files with the
+# latest release. A test keeps this file byte identical to
+# packages/atlas/door/workflows/atlas-gate-audit.yml.
+#
+# Two jobs, each with only what it needs:
+#   audit  read rights only. It writes the findings as job output.
+#   file   contents: read for the checkout, and issues: write. That is the
+#          only write right of this workflow.
+permissions: {}
+
+concurrency:
+  group: atlas-gate-audit-${{ github.sha }}
+  cancel-in-progress: false
+
+jobs:
+  audit:
+    name: gate · push audit
+    if: github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      pull-requests: read
+      checks: read
+      actions: read
+    outputs:
+      findings: ${{ steps.audit.outputs.findings }}
+    steps:
+      # actions/checkout v7.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      # actions/setup-node v7.0.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
+        with:
+          node-version: "22.22.0"
+
+      - name: Audit each commit of this push
+        id: audit
+        env:
+          GH_TOKEN: ${{ github.token }}
+          BEFORE: ${{ github.event.before }}
+          AFTER: ${{ github.event.after }}
+          FORCED: ${{ github.event.forced }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -uo pipefail
+          out="$RUNNER_TEMP/findings.json"
+          # keep FILE [FROM]: add the findings of FROM to FILE, through Atlas code.
+          keep() { node --input-type=module -e 'import { keepFindings } from "./packages/atlas/door/lib/gate-audit.mjs"; import { readFileSync, existsSync } from "node:fs"; const [to, from] = process.argv.slice(1); const have = from && existsSync(from) ? JSON.parse(readFileSync(from, "utf8")) : { findings: [] }; keepFindings(to, have.findings ?? [], { broken: have.state === "broken" });' "$@"; }
+          keep "$out"
+          forced=()
+          if [ "$FORCED" = "true" ]; then forced=(--forced); fi
+          if [ -z "${BEFORE//0/}" ] || [ "$FORCED" = "true" ] || ! git cat-file -e "$BEFORE^{commit}" 2>/dev/null; then
+            commits="$AFTER"
+          else
+            commits=$(git rev-list --first-parent --reverse "$BEFORE..$AFTER")
+          fi
+          for sha in $commits; do
+            flag=()
+            if [ "$sha" = "$AFTER" ]; then flag=("${forced[@]}"); fi
+            # GitHub can take a moment to link a fresh merge to its pull
+            # request. So a "no pull request" answer gets one more read, with
+            # a fresh findings file.
+            if ! text=$(node packages/atlas/bin/atlas gate audit --repo "$REPO" --commit "$sha" "${flag[@]}" --findings "$out.$sha"); then
+              if grep -q '^RED PUSH' <<<"$text"; then
+                sleep 30
+                rm -f "$out.$sha"
+                text=$(node packages/atlas/bin/atlas gate audit --repo "$REPO" --commit "$sha" "${flag[@]}" --findings "$out.$sha")
+              fi
+            fi
+            printf '%s\n' "$text" | tee -a "$GITHUB_STEP_SUMMARY"
+            # A run that wrote no file stopped before it could: mark it broken.
+            if [ -s "$out.$sha" ]; then keep "$out" "$out.$sha"; else echo '{"jobs":1,"state":"broken","findings":[]}' > "$out.$sha"; keep "$out" "$out.$sha"; fi
+          done
+          echo "findings=$(base64 -w0 < "$out")" >> "$GITHUB_OUTPUT"
+
+  file:
+    name: gate · push audit issues
+    needs: audit
+    if: always() && needs.audit.outputs.findings != ''
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      issues: write
+    steps:
+      # actions/checkout v7.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          persist-credentials: false
+      # actions/setup-node v7.0.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
+        with:
+          node-version: "22.22.0"
+      - name: File one issue for each new finding
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          FINDINGS: ${{ needs.audit.outputs.findings }}
+        run: |
+          set -euo pipefail
+          printf '%s' "$FINDINGS" | base64 -d > "$RUNNER_TEMP/findings.json"
+          node packages/atlas/bin/atlas jobs file --findings "$RUNNER_TEMP/findings.json" --repo "$GITHUB_REPOSITORY" | tee -a "$GITHUB_STEP_SUMMARY"
+          state=$(node -p 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")).state' "$RUNNER_TEMP/findings.json")
+          if [ "$state" != "none" ]; then
+            echo "::error::the push audit found a break of the gate (state $state). Read the issues it opened."
+            exit 1
+          fi

package/door/workflows/atlas-gate.yml

@@ -0,0 +1,142 @@
+name: atlas-gate
+run-name: "gate #${{ github.event.pull_request.number }} at ${{ github.event.pull_request.head.sha }}"
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened, edited, ready_for_review]
+
+# The gate (roadmap R6, design docs/design-docs/gate-check/). One job, named
+# `gate`, ends as success, or as failure with "owner: class" or "red: reason"
+# in its summary. It judges the pull request by the static rules: the
+# owner-only list, secrets of a known shape, head jobs named like a check, and
+# a test change for product code.
+#
+# It runs on pull_request_target, so GitHub runs this file as the base branch
+# holds it, with the base code. The head is fetched as git objects only and is
+# never checked out, built or run. atlas.yaml comes from the base side only.
+# The title of the run names the pull request and the head; `atlas gate ready`
+# reads it to pin the run (done line 8).
+#
+# The token can only read. No checkout keeps a credential: the one fetch of
+# the head takes the token for that command alone. The job writes two output
+# keys, `result` and `class`, each one word of a fixed set.
+#
+# The signed act (roadmap R72): the gate reads the comments of the pull
+# request, and a valid signature of the owner for this head turns "owner" into
+# success. The key comes from atlas/owner-signers on the base. A new comment
+# with a signed act reruns this run (atlas-gate-signed.yml).
+#
+# Report mode: the gate is not in required_checks yet. It joins the list after
+# the A1 exit test of the overhaul roadmap.
+#
+# The second job, `shape`, is the repo shape check from the base (roadmap R7,
+# design docs/design-docs/shape-check-from-base/). It is the job that
+# `atlas tooling` writes into every repo, word for word, and `atlas status`
+# compares it with the package.
+permissions:
+  contents: read
+  pull-requests: read
+  issues: read
+  checks: read
+  actions: read
+
+concurrency:
+  group: atlas-gate-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  gate:
+    name: gate
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      result: ${{ steps.check.outputs.result }}
+      class: ${{ steps.check.outputs.class }}
+    steps:
+      # actions/checkout v7.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          ref: ${{ github.sha }}
+          fetch-depth: 0
+          persist-credentials: false
+      # actions/setup-node v7.0.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
+        with:
+          node-version: "22.22.0"
+
+      - name: Fetch the head as objects only
+        env:
+          PR: ${{ github.event.pull_request.number }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          header="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$TOKEN" | base64 -w0)"
+          git -c "http.https://github.com/.extraheader=$header" fetch --no-tags --no-recurse-submodules origin "+refs/pull/$PR/head:refs/atlas-gate/head"
+          got="$(git rev-parse --verify refs/atlas-gate/head^{commit})"
+          if [ "$got" != "$HEAD_SHA" ]; then
+            echo "::error::the fetched head is $got, not the head of the event $HEAD_SHA. Push again."
+            exit 1
+          fi
+
+      - name: Read the pull request text from the event
+        run: node -e 'const fs=require("fs");const e=JSON.parse(fs.readFileSync(process.env.GITHUB_EVENT_PATH,"utf8"));fs.writeFileSync(process.env.RUNNER_TEMP+"/body.md",String(e.pull_request.body??""))'
+
+      - name: Gate check
+        id: check
+        env:
+          PR: ${{ github.event.pull_request.number }}
+          BASE_REF: ${{ github.event.pull_request.base.ref }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          node packages/atlas/bin/atlas gate check --root . --repo "$GITHUB_REPOSITORY" --base "$GITHUB_SHA" --head "$HEAD_SHA" --pr "$PR" --base-ref "$BASE_REF" --body "$RUNNER_TEMP/body.md" --summary "$GITHUB_STEP_SUMMARY" --output "$GITHUB_OUTPUT"
+
+  shape:
+    name: gate · shape
+    runs-on: ubuntu-latest
+    # The check reads two trees and opens no network. It finishes in seconds
+    # on a small repo. The bound stops a runner being billed until someone
+    # kills it; a run that hits it is red.
+    timeout-minutes: 10
+    outputs:
+      result: ${{ steps.shape.outputs.result }}
+      class: ${{ steps.shape.outputs.class }}
+    steps:
+      # actions/checkout v7.0.1
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          ref: ${{ github.sha }}
+          fetch-depth: 0
+          persist-credentials: false
+      # actions/setup-node v7.0.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
+        with:
+          node-version: "22.22.0"
+      - name: Fetch the head as objects only
+        env:
+          PR: ${{ github.event.pull_request.number }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          header="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$TOKEN" | base64 -w0)"
+          git -c "http.https://github.com/.extraheader=$header" fetch --no-tags --no-recurse-submodules origin "+refs/pull/$PR/head:refs/atlas-gate/head"
+          got="$(git rev-parse --verify refs/atlas-gate/head^{commit})"
+          if [ "$got" != "$HEAD_SHA" ]; then
+            echo "::error::the fetched head is $got, not the head of the event $HEAD_SHA. Push again."
+            exit 1
+          fi
+      - name: Shape check from the base
+        id: shape
+        env:
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          set -euo pipefail
+          if [ ! -f .github/atlas/check.mjs ]; then
+            echo "OWNER: first-run: the base has no .github/atlas/check.mjs, so the owner reads the first shape"
+            echo "result=owner" >> "$GITHUB_OUTPUT"
+            echo "class=first-run" >> "$GITHUB_OUTPUT"
+            exit 1
+          fi
+          node .github/atlas/check.mjs --gate --repo "$GITHUB_REPOSITORY" --base-commit "$GITHUB_SHA" --head-commit "$HEAD_SHA"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.4.21",
+  "version": "0.4.23",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, as a Claude Code plugin for any repository.",
   "type": "module",
   "license": "UNLICENSED",

package/skills/lead/SKILL.md

@@ -110,7 +110,7 @@ set. A test keeps the two lists equal.
 | `atlas design` | `folder` to learn where designs live; `check` before you show a design; `build` to make its page |
 | `atlas view` | `build --product <id>` makes the project view page of one product, when the owner asks for it or after an Atlas release changes it. Publish it with only the grant the command prints |
 | `atlas jobs` | The `atlas-jobs` workflow calls `check`, then `file`, once a day. A session calls it only to see what the watcher would file: `check`, then `file --dry-run` |
-| `atlas upkeep` | `check` before you ask for a merge. It reads the docs index, dead doc links, the code each doc names, and the tracker item of a pull request. The daily upkeep run calls it on the main branch. `replay` before the doc-sources rule changes how it gates |
+| `atlas upkeep` | `check` before you ask for a merge. It reads the docs index, dead doc links, the code each doc names, and the tracker item of a pull request. The daily upkeep run calls it on the main branch. `replay` before the doc-sources rule changes how it gates. `procedures` runs the procedure steps tagged `atlas-run`; CI runs it with `--base` on each pull request |
 | `atlas gate` | `apply` once per repo, by the owner on his Mac, after the repo's `required_checks` exist. `--dry-run` first. `--off` and `--on` are the break glass. On a plan with no rulesets it reports advisory mode. `ready` before each merge, `check` in the `atlas-gate` workflow, `replay` before a change to the owner-only list. `audit` in the daily upkeep run, and with `--commit` in the push job of a repo that has one |
 | `atlas approve` | Never from a session. Only the owner runs it, on his Mac, with his key's touch. When the gate says "owner" for a pull request, ask him once for the signed act: name each pull request, its class and its cause. Put the owner pull requests of one day in one ask, so one touch signs them. `act`, `verify` and `key-check` work the same way |
 | `atlas judge` | In the fresh-agent test only, as the `atlas:fresh-agent-test` skill says. `seal` after the pick, `brief` to read a sealed ask, `run` for each sealed task, `check` after the grade |

package/skills/repo-skills/SKILL.md

@@ -27,19 +27,24 @@ the form the repo already uses for that kind of thing.
    deploy. A rule says how to judge a change. They have different approval
    rules, so split a skill that holds both.
 4. **Write the header Atlas reads,** for a skill file. It names the type,
-   the commands and files, and the code it covers. It says how CI runs
-   it, if CI can. Today the Atlas check reads only `name` and
-   `description`, and finds the skill when `procedures` in `atlas.yaml`
-   names it. Later upkeep checks read the other keys, so keep each true.
-5. **Keep it to this repo.** A step that holds how to work in general
+   the commands and files, and the code it covers in `sources:`. The
+   Atlas check finds the skill when `procedures` in `atlas.yaml` names
+   it. `atlas upkeep check` reads `sources:`.
+5. **Tag each step a clean machine can run.** Put its commands in a
+   fenced block. Open it with ```` ```sh atlas-run ````. CI runs each
+   such block when a pull request changes the skill or its sources. A
+   step that needs a secret, a device or the network gets
+   `needs=secret/<name>`, `needs=device/<name>` or `needs=network/<name>`
+   after the tag. CI lists it as "not run here".
+6. **Keep it to this repo.** A step that holds how to work in general
    belongs in Atlas. Do not put it here. Propose it to Atlas with the
    `atlas:feedback` skill.
-6. **Follow the repo's own rules.** Read its entry file first. Some repos
+7. **Follow the repo's own rules.** Read its entry file first. Some repos
    ask for one area folder for each change, or a status file updated
    when the state changes. Keep to them.
-7. **Prove the steps once.** Ask the `atlas:verifier` crew to run them in
+8. **Prove the steps once.** Ask the `atlas:verifier` crew to run them in
    a fresh worktree, before you ask for the merge.
-8. **Write the pull request text.** Say what you found, what you kept,
+9. **Write the pull request text.** Say what you found, what you kept,
    and the gap you closed.
 
 ## The header of a skill file
@@ -51,9 +56,8 @@ description: <when to use it, in one or two sentences>
 type: task            # or rule
 names:                # each command and file the steps name
   - <command or path>
-covers:               # the code this skill describes
+sources:              # the code this skill describes
   - <path>
-ci: <how CI runs it, or "cannot run in CI">
 ---
 ```
 

package/work/lib/roundup.mjs

@@ -25,6 +25,29 @@ export const ROUNDUP_READ_VERBS = Object.freeze(['roundup']);
 // stage-2 is the stage 2 item or one of its parts.
 export const STAGE_TAG = /^stage-(\d{1,2})$/;
 export const STUCK_DAYS = 14;
+// Roadmap R14 done line 6: the daily audit runs in the watcher workflow. A
+// repo whose watcher has not run for this long is flagged in part 4.
+export const AUDIT_WORKFLOW = 'atlas-jobs.yml';
+export const AUDIT_STALE_HOURS = 26;
+const HOUR = 3_600_000;
+
+// The newest run of the daily audit in each repo. A repo with no such
+// workflow (GitHub answers 404) has no audit, so it is left out. Any other
+// failure is listed as unread, never as fresh.
+export async function readAudits(repoIds, readGitHub, readAt, staleHours = AUDIT_STALE_HOURS) {
+  const stale = [], unread = [];
+  for (const repo of repoIds) {
+    let runs;
+    try { runs = (await readGitHub(`repos/${repo}/actions/workflows/${AUDIT_WORKFLOW}/runs?per_page=1`))?.workflow_runs; } catch (error) {
+      if (!/\b404\b|Not Found/i.test(String(error?.message ?? error))) unread.push({ repo, reason: oneLine(`the audit runs could not be read: ${error?.message ?? String(error)}`, 200) });
+      continue;
+    }
+    const last = Array.isArray(runs) && runs.length ? runs[0].created_at ?? null : null;
+    const hours = last ? Math.floor((Date.parse(readAt) - Date.parse(last)) / HOUR) : null;
+    if (hours === null || hours >= staleHours) stale.push({ repo, workflow: `.github/workflows/${AUDIT_WORKFLOW}`, last_run_at: last, hours });
+  }
+  return { stale, unread };
+}
 export const TREND_WEEKS = 4;
 const DEFAULT_WINDOW = 7;
 const MAX_WINDOW = 90;
@@ -141,6 +164,7 @@ export function createRoundupVerbs(core) {
       const notMarked = (flight.merged_not_marked ?? []).map((row) => ({ item: row.item, pr: row.pr, title: row.title, days: row.days }));
       const openNoItem = pulls.filter((pull) => pull.state === 'open' && !owner.has(pull.url)).map((pull) => ({ pr: pull.url, title: pull.title, updated_at: pull.updated_at }));
       const longWaits = needRows.filter((row) => row.days_waiting !== null && row.days_waiting >= STUCK_DAYS);
+      const audits = await readAudits(repoIds, readGitHub, readAt);
 
       // 5. Trend, per week; week 1 is the last seven days.
       const weeks = Array.from({ length: TREND_WEEKS }, (_, index) => ({ week: index + 1, from: dayOf(minus(readAt, (index + 1) * 7)), to: dayOf(minus(readAt, index * 7)), merged: 0, delivered: 0, new_items: 0 }));
@@ -150,13 +174,13 @@ export function createRoundupVerbs(core) {
       for (const row of items) bump(row.created_at, 'new_items');
       const oldest = needRows.reduce((max, row) => Math.max(max, row.days_waiting ?? 0), 0);
 
-      const text = render({ product, readAt, windowDays, needRows, ladder, lifecycles, active, merged, deliveries, created, stale, notMarked, openNoItem, longWaits, weeks, oldest, repoErrors });
+      const text = render({ product, readAt, windowDays, needRows, ladder, lifecycles, active, merged, deliveries, created, stale, notMarked, openNoItem, longWaits, audits, weeks, oldest, repoErrors });
       return {
         verb: 'roundup', read_at: readAt, product, window_days: windowDays, since,
         needs_you: needRows,
         where_we_stand: { ladder, lifecycles, active },
         what_moved: { merged, delivered: deliveries, new_items: created },
-        stuck_or_drifting: { stale, merged_not_marked: notMarked, open_prs_with_no_item: openNoItem, long_waits: longWaits, stuck_days: STUCK_DAYS },
+        stuck_or_drifting: { stale, merged_not_marked: notMarked, open_prs_with_no_item: openNoItem, long_waits: longWaits, stuck_days: STUCK_DAYS, audits_not_run: audits.stale, audits_unread: audits.unread, audit_stale_hours: AUDIT_STALE_HOURS },
         trend: { weeks, open_questions: needRows.length, oldest_question_days: oldest },
         repos_read: repoIds, repo_errors: repoErrors,
         citation: { product, read_at: readAt, items: items.length, repos: repoIds },
@@ -167,7 +191,7 @@ export function createRoundupVerbs(core) {
 }
 
 function render(view) {
-  const { product, readAt, windowDays, needRows, ladder, lifecycles, active, merged, deliveries, created, stale, notMarked, openNoItem, longWaits, weeks, oldest, repoErrors } = view;
+  const { product, readAt, windowDays, needRows, ladder, lifecycles, active, merged, deliveries, created, stale, notMarked, openNoItem, longWaits, audits = { stale: [], unread: [] }, weeks, oldest, repoErrors } = view;
   const more = (list) => (list.length > SHOWN ? [`   and ${list.length - SHOWN} more`] : []);
   const out = [`${product} — roundup, ${dayOf(readAt)}`];
 
@@ -195,6 +219,8 @@ function render(view) {
   stuck.push(`   merged, not marked (${notMarked.length})`, ...notMarked.slice(0, SHOWN).map((row) => listLine(row.title, `${row.pr} · ${row.item}`, '     ')));
   stuck.push(`   open pull requests with no item (${openNoItem.length})`, ...openNoItem.slice(0, SHOWN).map((row) => listLine(row.title, row.pr, '     ')));
   stuck.push(`   questions waiting ${STUCK_DAYS} days or more (${longWaits.length})`, ...longWaits.slice(0, SHOWN).map((row) => listLine(row.text, `${row.question} · ${row.days_waiting} days`, '     ')));
+  stuck.push(`   audits with no run in ${AUDIT_STALE_HOURS} hours (${audits.stale.length})`, ...audits.stale.slice(0, SHOWN).map((row) => listLine(row.repo, row.last_run_at ? `last run ${row.last_run_at}, ${row.hours} hours` : 'no run yet', '     ')));
+  for (const row of audits.unread.slice(0, SHOWN)) stuck.push(listLine(row.repo, row.reason, '     '));
   out.push(stuck.join('\n'));
 
   out.push([`5. Trend, per week (week 1 is the last seven days)`,

package/work/mcp.mjs

@@ -206,6 +206,8 @@ export const GITHUB_READS = Object.freeze([
   new RegExp(`^repos/${REPO}/contents/atlas\\.yaml\\?ref=(?:${SHA}|${BRANCH})$`),
   new RegExp(`^repos/${REPO}/releases\\?per_page=\\d{1,3}$`),
   new RegExp(`^repos/${REPO}/compare/${SHA}\\.\\.\\.${TAG}$`),
+  // Roadmap R14 line 6: the newest run of the daily audit, for the roundup.
+  new RegExp(`^repos/${REPO}/actions/workflows/atlas-jobs\\.yml/runs\\?per_page=\\d{1,3}$`),
 ]);
 export function githubReader() {
   return async (path) => {