@arjunkhera/atlas 0.4.52 → 0.4.53

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.4.52",
+  "version": "0.4.53",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, for any repository.",
   "author": {
     "name": "Arjun Khera"

package/door/cli.mjs

@@ -155,6 +155,8 @@ const HELP = `atlas — the door into a repo's Atlas files
       --json                           print the whole answer as JSON
   atlas runner claim --repo <owner/name> --issue <n> --holder <run id>   claim one atlas-job issue; the oldest live claim holds it
   atlas runner line --from <file>      print the last line of a run, from a JSON file of ids and counts
+      --notice                         print the comment that hands the run facts to the notice workflow
+  atlas runner notice --repo <owner/name> --issue <n> --comment <id>   in the notice workflow only: post the run line of one run comment as the bot
                                        Until the A2 exit test, the runner works on the scratch repo only
 
   atlas upkeep check --root <repo>     the upkeep check: the docs index, dead doc links, the code each doc names, stale pages, and in a pull request its tracker item, its changed designs and STE on its changed lines
@@ -236,7 +238,7 @@ export const FLAGS = Object.freeze({
   view: { product: 'value', name: 'value', out: 'value' },
   tests: { root: 'optional', halves: 'value', evidence: 'value', 'guards-from': 'value', tests: 'value', 'dry-run': 'switch', run: 'value', own: 'value', base: 'value', head: 'value', list: 'value', side: 'value', old: 'value', new: 'value', covers: 'switch', findings: 'value', repo: 'value', max: 'value', bot: 'value', since: 'value', out: 'value', text: 'switch', json: 'switch', scenario: 'value', language: 'value' },
   jobs: { root: 'optional', repo: 'value', branch: 'value', out: 'value', findings: 'value', max: 'value', 'dry-run': 'switch' },
-  runner: { repo: 'value', issue: 'value', holder: 'value', from: 'value', json: 'switch' },
+  runner: { repo: 'value', issue: 'value', holder: 'value', from: 'value', comment: 'value', notice: 'switch', json: 'switch' },
   upkeep: { root: 'optional', event: 'value', json: 'switch', last: 'value', base: 'value' },
   gate: { repo: 'value', root: 'optional', 'dry-run': 'switch', off: 'switch', on: 'switch', pr: 'value', since: 'value', commit: 'value', from: 'value', base: 'value', 'base-ref': 'value', head: 'value', body: 'value', json: 'switch', summary: 'value', output: 'value', days: 'value', branch: 'value', errors: 'switch', forced: 'switch', findings: 'value' },
   approve: { repo: 'value', root: 'optional', key: 'value', provider: 'value', yes: 'switch', out: 'value', file: 'value', signers: 'value', commit: 'value', item: 'value', card: 'value', words: 'value', pr: 'value', head: 'value', decision: 'value', check: 'value' },
@@ -497,7 +499,7 @@ function jobsVerb(chosen) {
 }
 
 function runnerVerb(chosen) {
-  return runnerCommand({ what: chosen._[1], repo: chosen.repo, issue: chosen.issue, holder: chosen.holder, from: chosen.from, json: Boolean(chosen.json), args: [...chosen._, ...Object.values(chosen).filter((v) => typeof v === 'string')] }, line);
+  return runnerCommand({ what: chosen._[1], repo: chosen.repo, issue: chosen.issue, holder: chosen.holder, from: chosen.from, comment: chosen.comment, notice: Boolean(chosen.notice), json: Boolean(chosen.json), args: [...chosen._, ...Object.values(chosen).filter((v) => typeof v === 'string')] }, line);
 }
 
 function upkeepVerb(chosen) {

package/door/lib/runner.mjs

@@ -3,7 +3,8 @@
 //
 //   atlas runner start --repo <owner/name> [--json]
 //   atlas runner claim --repo <owner/name> --issue <n> --holder <run id>
-//   atlas runner line --from <file>
+//   atlas runner line --from <file> [--notice]
+//   atlas runner notice --repo <owner/name> --issue <n> --comment <id>
 //
 // The runner is one scheduled Claude session for each repo. It follows the
 // atlas:runner skill, and that skill calls these commands. The commands read
@@ -15,6 +16,12 @@
 //   claim  posts one claim on an issue, then reads the claims back. The
 //          oldest live claim holds the issue, so two runs build it once.
 //   line   prints the last line of a run, built by code from ids and counts.
+//          With --notice it prints the comment that hands the run facts to
+//          the notice workflow.
+//   notice runs in the notice workflow, as github-actions[bot]. It reads one
+//          run comment of the owner's login, builds the run line again from
+//          its facts, and posts the line, so GitHub tells the owner's phone
+//          (R25 line 10). It never copies the comment's text.
 //
 // Rules that hold everywhere here:
 // 1. Until the owner records the A2 exit test as passed, the runner works on
@@ -28,7 +35,7 @@
 // 4. No call here merges, pushes or changes a branch.
 import { readFileSync } from 'node:fs';
 import { jobMarker, typedFindings, JOBS_LABEL, atlasJobs } from './jobs.mjs';
-import { repoOk, TOKEN_SHAPE, DEFAULT_BOT } from './issues.mjs';
+import { repoOk, TOKEN_SHAPE, DEFAULT_BOT, api, apiBase } from './issues.mjs';
 import { ghApi } from './gate.mjs';
 import { PACKAGE_NAME } from './gate-audit.mjs';
 
@@ -253,14 +260,56 @@ export function runLine({ repo, at, you = [], landed = [], opened = [], open_job
   return parts.join(' · ');
 }
 
+// ------------------------------------------------------------ the notice
+
+// R25 line 10. The runner session acts as the owner's login, and GitHub does
+// not tell a person about his own comment. So the session posts its run facts
+// in one comment on the notice issue, and the notice workflow posts the run
+// line as the bot. The workflow trusts no text: it reads the facts as JSON,
+// and runLine refuses any field that is not an id, a count or a known form.
+export const RUN_MARKER = '<!-- atlas-runner:run -->';
+export const NOTICE_LABEL = 'atlas-notice';
+export const noticeBody = (facts) => [RUN_MARKER, '```json', JSON.stringify(facts), '```'].join('\n');
+
+export function factsOf(body) {
+  const text = String(body ?? '');
+  if (!text.startsWith(`${RUN_MARKER}\n`)) return null;
+  const blocks = [...text.matchAll(/```json\n([\s\S]*?)\n```/g)];
+  if (blocks.length !== 1) return null;
+  try { return JSON.parse(blocks[0][1]); } catch { return null; }
+}
+
+export async function runnerNotice({ repo, issue, comment, env = process.env, call = null, allowed = RUNNER_REPOS }) {
+  if (!repoAllowed(repo, allowed)) throw usage(`${repo} is not a runner repo`);
+  const gh = call ?? ((method, path, body) => api(apiBase(env), env.GITHUB_TOKEN, method, path, body));
+  if (!call && !env.GITHUB_TOKEN) throw usage('the notice needs GITHUB_TOKEN, the token of the workflow run');
+  const got = await gh('GET', `/repos/${repo}/issues/comments/${comment}`);
+  if (!got.ok) return { posted: false, why: `GitHub answered ${got.status} for comment ${comment}` };
+  const note = got.data;
+  if (!String(note?.issue_url ?? '').endsWith(`/repos/${repo}/issues/${issue}`)) return { posted: false, why: `comment ${comment} is not on issue #${issue}` };
+  if (note?.author_association !== 'OWNER') return { posted: false, why: `comment ${comment} is not by the owner's login, so no runner wrote it` };
+  const thread = await gh('GET', `/repos/${repo}/issues/${issue}`);
+  const labels = (thread.data?.labels ?? []).map((one) => (typeof one === 'string' ? one : one?.name));
+  if (!thread.ok || !labels.includes(NOTICE_LABEL)) return { posted: false, why: `issue #${issue} is not the notice issue (label ${NOTICE_LABEL})` };
+  const facts = factsOf(note.body);
+  if (!facts) return { posted: false, why: `comment ${comment} holds no run facts` };
+  if (String(facts.repo ?? '').toLowerCase() !== repo.toLowerCase()) return { posted: false, why: `the run facts name ${facts.repo}, not ${repo}` };
+  const runLineText = runLine(facts);
+  const posted = await gh('POST', `/repos/${repo}/issues/${issue}/comments`, { body: runLineText });
+  if (!posted.ok) return { posted: false, why: `GitHub answered ${posted.status} to the notice` };
+  return { posted: true, line: runLineText };
+}
+
 // ------------------------------------------------------------ the command
 
-export async function runnerCommand({ what, repo, issue, holder, from, json = false, args = [] }, line, env = process.env) {
+export async function runnerCommand({ what, repo, issue, holder, from, comment, notice = false, json = false, args = [] }, line, env = process.env) {
   try {
     if ([...args, repo, holder, from].some((a) => typeof a === 'string' && TOKEN_SHAPE.test(a))) throw usage('a token must never be an argument');
     if (what === 'line') {
       if (!from) throw usage('give the run as --from <file>, a JSON object of ids and counts');
-      line(runLine(JSON.parse(readFileSync(from, 'utf8'))));
+      const facts = JSON.parse(readFileSync(from, 'utf8'));
+      const text = runLine(facts);
+      line(notice ? noticeBody(facts) : text);
       return 0;
     }
     if (!repoOk(repo)) throw usage('give the repo as --repo <owner/name>');
@@ -278,7 +327,14 @@ export async function runnerCommand({ what, repo, issue, holder, from, json = fa
       line(result.held ? `HELD: issue #${issue} is this run's` : `TAKEN: issue #${issue} is held by ${result.holder}; leave it`);
       return result.held ? 0 : 1;
     }
-    throw usage('use atlas runner start, atlas runner claim or atlas runner line');
+    if (what === 'notice') {
+      if (!/^[1-9][0-9]{0,8}$/.test(String(issue ?? ''))) throw usage('give the notice issue as --issue <number>');
+      if (!/^[1-9][0-9]{0,11}$/.test(String(comment ?? ''))) throw usage('give the run comment as --comment <id>');
+      const result = await runnerNotice({ repo, issue: Number(issue), comment: Number(comment), env });
+      line(result.posted ? `POSTED: ${result.line}` : `NOT POSTED: ${result.why}`);
+      return result.posted ? 0 : 1;
+    }
+    throw usage('use atlas runner start, claim, line or notice');
   } catch (error) {
     line(`atlas runner: ${error.message}`);
     return error.usage ? 2 : 1;

package/door/lib/tooling.mjs

@@ -63,6 +63,11 @@ function packagedPinned(packageRoot, source) {
 export const packagedJobsWorkflow = (packageRoot) => packagedPinned(packageRoot, PACKAGE_JOBS_SOURCE);
 export const packagedUpkeepWorkflow = (packageRoot) => packagedPinned(packageRoot, PACKAGE_UPKEEP_SOURCE);
 export const packagedProceduresWorkflow = (packageRoot) => packagedPinned(packageRoot, PACKAGE_PROCEDURES_SOURCE);
+// The notice workflow of the runner (R25 line 10). It is not in PINNED: until
+// the owner records the A2 exit test, only the scratch repo gets it, by hand.
+export const RUNNER_NOTICE_PATH = '.github/workflows/atlas-runner-notice.yml';
+export const PACKAGE_RUNNER_NOTICE_SOURCE = 'door/templates/atlas-runner-notice.yml';
+export const packagedRunnerNotice = (packageRoot) => packagedPinned(packageRoot, PACKAGE_RUNNER_NOTICE_SOURCE);
 const pinOf = (text) => /@arjunkhera\/atlas@(\d+)\.(\d+)\.(\d+)\b/.exec(text)?.slice(1).map(Number) ?? null;
 const older = (a, b) => { for (let i = 0; i < 3; i += 1) if (a[i] !== b[i]) return a[i] < b[i]; return false; };
 // written, refreshed, unchanged or kept: what the writer does with one pinned workflow.

package/door/templates/atlas-runner-notice.yml

@@ -0,0 +1,41 @@
+name: atlas-runner-notice
+# The notice of the Atlas runner (roadmap R25 line 10). Atlas wrote this file
+# from the Atlas package; do not edit it by hand.
+#
+# A runner session acts as the owner's login, and GitHub does not tell a
+# person about his own comment. So the session posts its run facts in one
+# comment on the notice issue (label atlas-notice), and this job posts the run
+# line as github-actions[bot]. GitHub then tells the owner's phone.
+#
+# It holds no secret, only issues write. It never copies the comment's text:
+# Atlas code reads the facts as JSON and builds the line from ids and counts.
+# Until the owner records the A2 exit test, only the scratch repo has it.
+on:
+  issue_comment:
+    types: [created]
+
+permissions: {}
+
+jobs:
+  notice:
+    if: >-
+      github.event.comment.author_association == 'OWNER' &&
+      startsWith(github.event.comment.body, '<!-- atlas-runner:run -->') &&
+      contains(github.event.issue.labels.*.name, 'atlas-notice')
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      issues: write
+    steps:
+      # actions/setup-node v7.0.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
+        with:
+          node-version: "22.22.0"
+      - name: Post the run line as the bot
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          ISSUE: ${{ github.event.issue.number }}
+          COMMENT: ${{ github.event.comment.id }}
+        run: |
+          set -euo pipefail
+          npx --yes --ignore-scripts @arjunkhera/atlas@__ATLAS_VERSION__ runner notice --repo "$GITHUB_REPOSITORY" --issue "$ISSUE" --comment "$COMMENT" | tee -a "$GITHUB_STEP_SUMMARY"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.4.52",
+  "version": "0.4.53",
   "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/runner/SKILL.md

@@ -72,9 +72,12 @@ its environment come from `trigger.yaml` beside this file.
    `the merge door is off in the runner`, `start stopped`. A landed pull
    request carries its `number`, its `release`, and the id of its proof
    comment as `proof`. The command refuses any other text.
-8. Run `atlas runner line --from <file>`. Its output is the last message of
-   the run, word for word. The notice workflow posts it on the repo's notice
-   issue.
+8. Run `atlas runner line --from <file> --notice`. Post its output, word for
+   word, as one comment on the repo's notice issue (label `atlas-notice`).
+   The notice workflow reads the facts and posts the run line as the bot,
+   so GitHub tells the owner.
+9. Run `atlas runner line --from <file>`. Its output is the last message of
+   the run, word for word.
 
 ## Until the exit test