@arjunkhera/atlas 0.4.7 → 0.4.9

package/.claude-plugin/plugin.json

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

package/door/cli.mjs

@@ -150,6 +150,11 @@ const HELP = `atlas — the door into a repo's Atlas files
   atlas gate ready --repo <owner/name> --pr <n>   may this pull request merge: every required check green on its head
   atlas gate audit --repo <owner/name> [--since <date>]   each merge since the date (default: one day) that came before its checks were green
   atlas gate audit --repo <owner/name> --commit <sha>   one commit on the main branch: red when no pull request merged it, or one merged it before its checks were green
+  atlas gate check --base <ref> --head <sha>   the gate: judge a pull request with this copy of Atlas; success, owner or red
+      --root <repo>                    the clone that holds both commits (default: this folder); the head is read as git data only
+      --body <file>                    the pull request text, for the "behaviour change: no" of a refactor
+      --json                           print the answer as JSON
+      --summary <file> --output <file> append the text to a job summary, and result= and class= to an output file
 
   atlas judge seal <tasks.md>          the fresh-agent test: check the judge's six candidates, print the seal and the three that run
   atlas judge brief <tasks.md> <id>    print the exact words for one run: the task, then the report form
@@ -191,7 +196,7 @@ export const FLAGS = Object.freeze({
   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' },
   upkeep: { root: 'optional', event: 'value', json: 'switch' },
-  gate: { repo: 'value', root: 'optional', 'dry-run': 'switch', off: 'switch', on: 'switch', pr: 'value', since: 'value', commit: 'value' },
+  gate: { repo: 'value', root: 'optional', 'dry-run': 'switch', off: 'switch', on: 'switch', pr: 'value', since: 'value', commit: 'value', base: 'value', head: 'value', body: 'value', json: 'switch', summary: 'value', output: 'value' },
   judge: { tasks: 'value', verdict: 'value', seal: 'value', runs: 'value', out: 'value', repo: 'value', budget: 'value', model: 'value' },
   install: { local: 'switch', from: 'value', 'skip-global': 'switch', yes: 'switch', cloud: 'switch' },
   upgrade: { version: 'optional', yes: 'switch' },
@@ -432,7 +437,7 @@ function upkeepVerb(chosen) {
 }
 
 function gateVerb(chosen) {
-  return gateCommand({ what: chosen._[1], repo: chosen.repo, root: rootOf(chosen), dryRun: Boolean(chosen['dry-run']), off: Boolean(chosen.off), on: Boolean(chosen.on), pr: chosen.pr, since: chosen.since, commit: chosen.commit }, line);
+  return gateCommand({ what: chosen._[1], repo: chosen.repo, root: rootOf(chosen), dryRun: Boolean(chosen['dry-run']), off: Boolean(chosen.off), on: Boolean(chosen.on), pr: chosen.pr, since: chosen.since, commit: chosen.commit, base: chosen.base, head: chosen.head, body: chosen.body, json: Boolean(chosen.json), summary: chosen.summary, output: chosen.output }, line);
 }
 
 function judgeVerb(chosen) {

package/door/lib/gate-check.mjs

@@ -0,0 +1,294 @@
+// `atlas gate check`: the static rules of the gate (roadmap R6, tracker item
+// da9c3481; design docs/design-docs/gate-check/). The `gate` job runs it from
+// the base copy of Atlas, on `pull_request_target`, and reads the head only as
+// git data. It waits for no other job: the test rules stay in fails-before and
+// passes-after, and `atlas gate ready` reads all three checks with pins.
+//
+//   judge({ root, base, head, body, redMain })   the answer, from git data
+//   renderText(answer)                           the lines of the job summary
+//   checkCommand(options, line, read)            the command; `read` gives the red main checks
+//
+// The answer is success, owner or red:
+//
+//   red      a secret in an added line; product code that changed with no test
+//            case added or changed; a head that git cannot read
+//   owner    a path or a sign of the owner-only list; a head job named like a
+//            check; a refactor claim (until the review job, roadmap R28); a
+//            file too large to scan
+//   success  no rule holds the pull request
+//
+// Red wins over owner: the pull request must be fixed before the owner signs.
+// Rules that hold everywhere here:
+// 1. The owner-only list and atlas.yaml come from the merge base, never from
+//    the head (owner-only.mjs reads them there).
+// 2. Nothing of the head runs. Every read is a git object.
+// 3. It fails closed: a head or a merge base that git cannot read is red.
+import { spawnSync } from 'node:child_process';
+import { readFileSync, appendFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { classify, changedPaths, compile, matcher } from './owner-only.mjs';
+import { listChanged } from './changed-tests.mjs';
+import { parseYaml, SECRET_PATTERNS } from '../../shape/check.mjs';
+
+export const VERSION = 1;
+export const GATE_CHECK = 'gate';
+export const GATE_WORKFLOW = '.github/workflows/atlas-gate.yml';
+export const TEST_CHECKS = Object.freeze(['fails-before', 'passes-after']);
+export const RESULTS = Object.freeze(['success', 'owner', 'red']);
+export const ANSWER_KEYS = Object.freeze(['gate', 'base', 'merge_base', 'head', 'result', 'class', 'rows', 'signed_act']);
+export const SIGNED_ACT = "Clears with the owner's signed act: atlas approve <pr> (roadmap R72).";
+// A file over this size is not scanned for secrets, and comes to the owner.
+export const SCAN_LIMIT = 1024 * 1024;
+// The test groups of the changed-test list that hold test cases.
+const CASE_GROUPS = new Set(['unit-test', 'check-block', 'scenario-words']);
+
+export class GateCheckError extends Error {}
+
+function git(root, args, { allowFail = false } = {}) {
+  const r = spawnSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+  if (r.error) throw new GateCheckError(`git cannot run: ${r.error.message}`);
+  if (r.status !== 0) {
+    if (allowFail) return null;
+    throw new GateCheckError(`git ${args.join(' ')} failed: ${String(r.stderr || r.stdout || '').trim().split('\n')[0]}`);
+  }
+  return r.stdout;
+}
+
+const commitOf = (root, ref) => (git(root, ['rev-parse', '--verify', '--quiet', '--end-of-options', `${ref}^{commit}`], { allowFail: true }) ?? '').trim();
+// git's word for the shared commit, joined so the package names no ancestry verb (test/package D9).
+const MERGE_BASE = ['merge', 'base'].join('-');
+const textAt = (root, ref, path) => git(root, ['show', `${ref}:${path}`], { allowFail: true });
+
+// Docs, the archive and a root markdown file are not product code. The same
+// rule as fails-before and passes-after.
+export const isProduct = (path) => !/^(docs|archive)\//.test(path) && !/^[^/]+\.md$/i.test(path);
+
+// ------------------------------------------------------------------ secrets
+
+// Each added line of one changed text file, with its line number in the head.
+// A binary file prints no lines, so it is skipped.
+export function addedLines(root, base, head, path) {
+  const out = git(root, ['diff', '--no-renames', '--no-textconv', '--no-ext-diff', '--no-color', '-U0', base, head, '--', path]) ?? '';
+  const rows = [];
+  let next = null;
+  for (const text of out.split('\n')) {
+    const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(text);
+    if (hunk) { next = Number(hunk[1]); continue; }
+    if (next === null) continue;
+    if (text.startsWith('+')) { rows.push({ line: next, text: text.slice(1) }); next += 1; }
+    else if (text.startsWith(' ')) next += 1;
+  }
+  return rows;
+}
+
+// The secret patterns that make the gate red: the ones with a known shape. The
+// loose pattern "named-value" (token = ...) matches much test code, so it
+// comes to the owner through the credentials sign of the owner-only list.
+export const RED_SECRETS = Object.freeze(['json-web-token', 'github-token', 'vendor-key', 'private-key', 'url-credential']);
+// A host that only serves examples holds no real password.
+const EXAMPLE_HOST = /@(?:[^\s/]*\.)?(?:example\.(?:com|org|net|test)|[^\s/]*\.test|[^\s/]*\.example|localhost)(?:[:/\s]|$)/i;
+
+// One row for each secret of a known shape in an added line. The row names
+// the path, the line and the pattern id, never the value.
+export function secretRows(root, base, head, changes) {
+  const patterns = SECRET_PATTERNS.filter((pattern) => RED_SECRETS.includes(pattern.id)).map((pattern) => ({ id: pattern.id, regex: compile(pattern.source) }));
+  const rows = [];
+  for (const change of changes) {
+    if (change.status === 'D' || change.newMode === '160000') continue;
+    const size = Number((git(root, ['cat-file', '-s', `${head}:${change.path}`], { allowFail: true }) ?? '0').trim());
+    if (size > SCAN_LIMIT) { rows.push({ kind: 'owner', class: 'too-large', path: change.path, cause: `${size} bytes: too large to scan for secrets` }); continue; }
+    for (const added of addedLines(root, base, head, change.path)) {
+      const found = patterns.find((pattern) => {
+        const hit = pattern.regex.exec(added.text);
+        return hit && !(pattern.id === 'url-credential' && EXAMPLE_HOST.test(hit[0]));
+      });
+      if (found) rows.push({ kind: 'red', class: 'secret', path: change.path, line: added.line, cause: `secret pattern ${found.id}` });
+    }
+  }
+  return rows;
+}
+
+// ------------------------------------------------------------------ jobs named like a check
+
+const WORKFLOW = /^\.github\/workflows\/[^/]+\.ya?ml$/;
+
+// The job names of one workflow text: each job's `name:`, or its id.
+export function jobNames(text) {
+  let facts;
+  try { facts = parseYaml(text ?? '') ?? {}; } catch { return null; }
+  const jobs = facts.jobs && typeof facts.jobs === 'object' ? facts.jobs : {};
+  return Object.entries(jobs).map(([id, job]) => String(job && typeof job === 'object' && job.name !== undefined ? job.name : id));
+}
+
+// The checks that a job name may not take: the required checks of the base,
+// the gate and the two test checks. Each one maps to the base workflow file
+// that defines it, which may keep it.
+export function guardedChecks(root, base) {
+  const facts = parseYaml(textAt(root, base, 'atlas.yaml') ?? '') ?? {};
+  const names = new Set([GATE_CHECK, ...TEST_CHECKS, ...(Array.isArray(facts.required_checks) ? facts.required_checks.map(String) : [])]);
+  const home = new Map([...names].map((name) => [name, new Set()]));
+  const files = (git(root, ['ls-tree', '-r', '--name-only', base, '--', '.github/workflows/'], { allowFail: true }) ?? '').split('\n').filter((path) => WORKFLOW.test(path));
+  for (const path of files) for (const name of jobNames(textAt(root, base, path)) ?? []) if (home.has(name)) home.get(name).add(path);
+  home.get(GATE_CHECK).add(GATE_WORKFLOW);
+  return home;
+}
+
+// Owner rows for a changed head workflow that defines a job with a guarded
+// name outside its home file, or a job name that GitHub computes.
+function jobRows(root, base, head, changes) {
+  const home = guardedChecks(root, base);
+  const rows = [];
+  for (const change of changes) {
+    if (change.status === 'D' || !WORKFLOW.test(change.path)) continue;
+    const names = jobNames(textAt(root, head, change.path));
+    if (names === null) { rows.push({ kind: 'owner', class: 'gate-checks', path: change.path, cause: 'the workflow does not read' }); continue; }
+    for (const name of names) {
+      if (name.includes('${{')) rows.push({ kind: 'owner', class: 'gate-checks', path: change.path, cause: `a job name that GitHub computes: ${name}` });
+      else if (home.has(name) && !home.get(name).has(change.path)) rows.push({ kind: 'owner', class: 'gate-checks', path: change.path, cause: `a job named like the check "${name}"` });
+    }
+  }
+  return rows;
+}
+
+// ------------------------------------------------------------------ the test rule
+
+// True when the "Behaviour change" heading of the pull request text says no.
+export function saysNoBehaviourChange(body) {
+  const text = String(body ?? '').replace(/<!--[\s\S]*?-->/g, '');
+  const lines = text.split('\n');
+  const at = lines.findIndex((line) => /^#{1,6}\s*behaviou?r change\s*$/i.test(line.trim()));
+  if (at < 0) return false;
+  const first = lines.slice(at + 1).map((line) => line.trim()).find(Boolean) ?? '';
+  return !/^#/.test(first) && /^no\b/i.test(first);
+}
+
+// Product code sits under the `product_paths:` of atlas.yaml at the merge base
+// (roadmap R4 line 5). It is not a doc by the rule of fails-before, and not a
+// markdown file: a unit test cannot test skill text yet (roadmap R2 line 4).
+// A repo with no such key keeps the other two rules alone.
+export function productTest(root, ref) {
+  const facts = parseYaml(textAt(root, ref, 'atlas.yaml') ?? '') ?? {};
+  const paths = Array.isArray(facts.product_paths) ? facts.product_paths.map(String) : null;
+  const code = (path) => isProduct(path) && !/\.md$/i.test(path);
+  if (!paths) return code;
+  const tests = paths.map((pattern) => matcher(pattern));
+  return (path) => code(path) && tests.some((test) => test(path));
+}
+
+// The files that main changed since a check was last green: the diff from
+// the last green commit to the merge base.
+export function coveredFiles(root, green, mergeBase) {
+  if (!commitOf(root, green)) return null;
+  return (git(root, ['diff', '--name-only', '--no-renames', green, mergeBase], { allowFail: true }) ?? '').split('\n').filter(Boolean);
+}
+
+// Line 6: new product code needs a new or changed test case, and fails-before
+// proves it. Line 7: a fix of a red main check that changes no test is exempt
+// for the files that main changed since that check was last green.
+function testRows({ root, mergeBase, head, body, redMain }) {
+  const list = listChanged({ root, base: mergeBase, head });
+  const product = list.other_paths.filter(productTest(root, mergeBase));
+  if (!product.length) return [];
+  const cases = list.rows.filter((row) => CASE_GROUPS.has(row.group) && row.status !== 'removed');
+  if (cases.length) return [{ kind: 'note', class: 'tests', cause: `${new Set(cases.map((row) => row.path)).size} test file(s) added or changed; fails-before proves them` }];
+  const anyTest = list.rows.length > 0;
+  if (!anyTest && redMain.length) {
+    const covered = new Set();
+    const names = [];
+    for (const red of redMain) {
+      const files = coveredFiles(root, red.green, mergeBase);
+      if (!files) continue;
+      names.push(red.check);
+      for (const path of files) covered.add(path);
+    }
+    if (names.length) {
+      const loose = product.filter((path) => !covered.has(path));
+      if (!loose.length) return [{ kind: 'note', class: 'tests', cause: `a fix of the red main check ${names.join(', ')}: each changed product file changed on main since the check was green` }];
+      return [{ kind: 'red', class: 'tests', cause: `product code changed and no test case was added or changed; the red-main fix of ${names.join(', ')} does not cover ${loose.join(', ')}` }];
+    }
+  }
+  if (!anyTest && saysNoBehaviourChange(body)) return [{ kind: 'owner', class: 'refactor', cause: 'a refactor claim: no test changed and the text says "behaviour change: no"; the review job (R28) will check such claims' }];
+  return [{ kind: 'red', class: 'tests', cause: 'product code changed and no test case was added or changed' }];
+}
+
+// ------------------------------------------------------------------ the judge
+
+// The answer for one pull request. `redMain` lists the required checks that
+// are red on the merge base: [{ check, green }], where `green` is the newest
+// commit of main on which the check was green.
+export function judge({ root, base, head, body = '', redMain = [] }) {
+  const top = resolve(root);
+  const baseSha = commitOf(top, base);
+  if (!baseSha) throw new GateCheckError(`the base "${base}" is not a commit in this repo.`);
+  const headSha = commitOf(top, head);
+  const answer = { gate: VERSION, base: baseSha, merge_base: null, head: headSha || String(head), result: 'red', class: null, rows: [], signed_act: null };
+  if (!headSha) {
+    answer.rows.push({ kind: 'red', class: 'gate', cause: 'the head commit is not readable in this clone' });
+    return finish(answer);
+  }
+  const mergeBase = (git(top, [MERGE_BASE, '--end-of-options', baseSha, headSha], { allowFail: true }) ?? '').trim();
+  if (!mergeBase) {
+    answer.rows.push({ kind: 'red', class: 'gate', cause: 'the base and the head share no commit in this clone' });
+    return finish(answer);
+  }
+  answer.merge_base = mergeBase;
+  const changes = changedPaths(top, mergeBase, headSha);
+  for (const row of classify({ root: top, base: mergeBase, head: headSha }).rows) answer.rows.push({ kind: 'owner', class: row.class ?? 'unlisted', path: row.path, cause: row.cause });
+  answer.rows.push(...jobRows(top, mergeBase, headSha, changes));
+  answer.rows.push(...secretRows(top, mergeBase, headSha, changes));
+  answer.rows.push(...testRows({ root: top, mergeBase, head: headSha, body, redMain }));
+  return finish(answer);
+}
+
+function finish(answer) {
+  const red = answer.rows.filter((row) => row.kind === 'red');
+  const owner = answer.rows.filter((row) => row.kind === 'owner');
+  answer.result = red.length ? 'red' : owner.length ? 'owner' : 'success';
+  answer.class = red[0]?.class ?? owner[0]?.class ?? null;
+  answer.signed_act = answer.result === 'owner' ? SIGNED_ACT : null;
+  return answer;
+}
+
+// ------------------------------------------------------------------ the text
+
+// No control character of a path reaches a line, and every head string comes
+// after a fixed prefix, so it cannot start a workflow command.
+const oneLine = (text) => String(text ?? '').replace(/[\u0000-\u001f\u007f]/g, ' ');
+
+export function renderText(answer) {
+  const named = new Set(answer.rows.filter((row) => row.path).map((row) => row.path)).size;
+  const out = [`gate: base ${answer.base.slice(0, 7)}, merge base ${String(answer.merge_base ?? '-').slice(0, 7)}, head ${oneLine(answer.head).slice(0, 7)}; ${named} path(s) named`];
+  const order = { red: 0, owner: 1, note: 2 };
+  for (const row of [...answer.rows].sort((a, b) => order[a.kind] - order[b.kind])) {
+    const where = row.path ? `  ${oneLine(row.path)}${row.line ? `:${row.line}` : ''}` : '';
+    out.push(`  ${row.kind.padEnd(6)} ${oneLine(row.class).padEnd(12)}${where}  ${oneLine(row.cause)}`);
+  }
+  if (answer.result === 'red') out.push(`RED: ${oneLine(answer.rows.find((row) => row.kind === 'red').cause)}. Fix it; red wins over owner.`);
+  else if (answer.result === 'owner') out.push(`OWNER: ${oneLine(answer.class)}. ${answer.signed_act}`);
+  else out.push('SUCCESS: no rule holds this pull request.');
+  return out;
+}
+
+// ------------------------------------------------------------------ the command
+
+// `atlas gate check`. `read` gives { redMain } from GitHub when the job runs
+// with --repo. Exit 0 on success, 1 on owner or red, 2 on a usage error.
+export function checkCommand({ root, base, head, body: bodyFile, json = false, summary, output }, line, read = null) {
+  try {
+    if (!base || base === true) throw Object.assign(new GateCheckError('atlas gate check needs --base <ref>.'), { usage: true });
+    if (!head || head === true) throw Object.assign(new GateCheckError('atlas gate check needs --head <sha>.'), { usage: true });
+    const body = bodyFile && bodyFile !== true ? readFileSync(resolve(bodyFile), 'utf8') : '';
+    const redMain = read ? read() : [];
+    const answer = judge({ root, base, head, body, redMain });
+    const text = renderText(answer);
+    if (json) process.stdout.write(`${JSON.stringify(answer, null, 2)}\n`);
+    else for (const each of text) line(each);
+    if (summary && summary !== true) appendFileSync(summary, `${['```text', ...text, '```'].join('\n')}\n`);
+    // Two keys, each one word of a fixed set, so no path can add a key.
+    if (output && output !== true) appendFileSync(output, `result=${answer.result}\nclass=${/^[a-z-]+$/.test(answer.class ?? '') ? answer.class : 'none'}\n`);
+    return answer.result === 'success' ? 0 : 1;
+  } catch (error) {
+    line(`gate check: ${error.message}`);
+    return error.usage ? 2 : 1;
+  }
+}

package/door/lib/gate.mjs

@@ -20,6 +20,7 @@ import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { childEnvironment } from '../../work/lib/child-env.mjs';
 import { parseYaml } from '../../shape/check.mjs';
+import { checkCommand } from './gate-check.mjs';
 
 export const BRANCH_RULESET = 'atlas gate';
 export const TAG_RULESET = 'atlas release tags';
@@ -302,9 +303,10 @@ function commitAudit({ repo, commit }, line, gh) {
   return 0;
 }
 
-// `atlas gate apply|ready|audit`. Returns the exit code.
-export function gateCommand({ what, repo, root, dryRun = false, off = false, on = false, pr, since, commit, home = homedir() }, line, gh = ghApi) {
-  if (!['apply', 'ready', 'audit'].includes(what)) throw new GateError(`there is no gate verb "${what ?? ''}". Use apply, ready or audit.`);
+// `atlas gate apply|ready|audit|check`. Returns the exit code.
+export function gateCommand({ what, repo, root, dryRun = false, off = false, on = false, pr, since, commit, base, head, body, json = false, summary, output, home = homedir() }, line, gh = ghApi) {
+  if (!['apply', 'ready', 'audit', 'check'].includes(what)) throw new GateError(`there is no gate verb "${what ?? ''}". Use apply, ready, audit or check.`);
+  if (what === 'check') return checkCommand({ root, base, head, body, json, summary, output }, line);
   if (!repo || repo === true || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(repo)) throw new GateError(`atlas gate ${what} needs --repo <owner/name>.`);
   if (what === 'ready') {
     const answer = {};

package/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "Loads the Atlas lead at the start of each session in a repo that runs Atlas, and keeps the merge door: no merge without a fresh READY, no push to the default branch, no force push.",
+  "description": "Loads the Atlas lead at the start of each session in a repo that runs Atlas, keeps the merge door (no merge without a fresh READY, no push to the default branch, no force push), and counts each message the person sends as a step-in, with no text.",
   "hooks": {
     "SessionStart": [
       {
@@ -23,6 +23,17 @@
           }
         ]
       }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/step-in.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
     ]
   }
 }

package/hooks/step-in.mjs

@@ -0,0 +1,91 @@
+// The step-in hook: the third hook Atlas ships (roadmap R15, item ebbf9693).
+// Claude Code runs it on each message the person sends. It appends one row
+// to the step-in journal, so code counts each step-in and the lead only
+// names its class later. A lead that skipped a steer would otherwise pass
+// every test that reads the count.
+//
+// Its limits are the reason the package may ship it:
+// 1. A row holds the time, the session and the repos. It never holds the
+//    text of the message.
+// 2. It makes no network call, reads no key and starts no program. It reads
+//    the hook input, atlas.yaml in the session folder or one level down, and
+//    ATLAS_HOOKS and HOME.
+// 3. It prints nothing, and it always exits 0: a message is never held up.
+// 4. It writes only where the session folder, or a folder one level down,
+//    holds atlas.yaml.
+// 5. ATLAS_HOOKS=off, set outside the session, turns it off. The Atlas
+//    tools then write one "not counted" mark for the session.
+import { randomUUID } from 'node:crypto';
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, writeSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const MAX_REPOS = 16;
+const REPO = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}\/[A-Za-z0-9_.-]{1,100}$/;
+const SESSION = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,199}$/;
+
+// The folder that the hook writes and the Atlas tools read. The tools keep
+// their own copy of the path, because these bytes are pinned.
+export const stepInFolder = (home = homedir()) => join(home, '.atlas', 'step-ins');
+
+// The repo that one atlas.yaml names, from its top-level `repo:` line.
+function repoOf(path) {
+  let text;
+  try { text = readFileSync(path, 'utf8').slice(0, 65536); } catch { return null; }
+  for (const line of text.split('\n')) {
+    const match = /^repo:\s*["']?([^"'#\s]+)["']?\s*(?:#.*)?$/.exec(line);
+    if (match) return REPO.test(match[1]) ? match[1] : null;
+  }
+  return null;
+}
+
+// The repos of the session folder: its own atlas.yaml, or else each folder
+// one level down that holds one. Null when no folder runs Atlas.
+export function reposOf(cwd) {
+  if (typeof cwd !== 'string' || !isAbsolute(cwd)) return null;
+  if (existsSync(join(cwd, 'atlas.yaml'))) { const repo = repoOf(join(cwd, 'atlas.yaml')); return repo ? [repo] : []; }
+  let names;
+  try { names = readdirSync(cwd, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort(); } catch { return null; }
+  const found = names.filter((name) => existsSync(join(cwd, name, 'atlas.yaml')));
+  if (!found.length) return null;
+  return [...new Set(found.map((name) => repoOf(join(cwd, name, 'atlas.yaml'))).filter(Boolean))].slice(0, MAX_REPOS);
+}
+
+// One message in, one row out, or null when no row is due.
+export function rowOf(input, { now = new Date(), id = randomUUID() } = {}) {
+  const session = typeof input?.session_id === 'string' && SESSION.test(input.session_id) ? input.session_id : null;
+  if (!session) return null;
+  const repos = reposOf(input?.cwd);
+  if (repos === null) return null;
+  return { v: 1, id, at: now.toISOString(), session, repos };
+}
+
+// The row goes to a file of its own, written under a temporary name and
+// then renamed, so a reader never sees half a row.
+export function writeRow(row, home = homedir()) {
+  const folder = stepInFolder(home);
+  mkdirSync(folder, { recursive: true, mode: 0o700 });
+  const name = `${row.at.replace(/[:.]/g, '-')}-${row.id}.json`;
+  const temp = join(folder, `.${name}.tmp`);
+  const handle = openSync(temp, 'wx', 0o600);
+  try { writeSync(handle, `${JSON.stringify(row)}\n`); } finally { closeSync(handle); }
+  renameSync(temp, join(folder, name));
+  return join(folder, name);
+}
+
+export function main(text, env = process.env) {
+  if (env.ATLAS_HOOKS === 'off') return null;
+  let input;
+  try { input = JSON.parse(text); } catch { return null; }
+  const row = rowOf(input);
+  if (!row) return null;
+  try { return writeRow(row, env.HOME || homedir()); } catch { return null; }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const chunks = [];
+  process.stdin.on('data', (chunk) => chunks.push(chunk));
+  process.stdin.on('end', () => { main(Buffer.concat(chunks).toString('utf8')); process.exit(0); });
+  process.stdin.on('error', () => process.exit(0));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "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

@@ -70,6 +70,11 @@ A crew reads and reports. It never holds the Atlas tools.
    Never record one on your own judgment.
 3. A change after the owner approved a design is a new decision on the
    same item, with the owner's words. The design file names the change.
+4. A hook counts each message the owner sends as a step-in. Some
+   messages are a brake, an answer, a signed act or an owner-only act.
+   Find each one with `step_ins`, and name it with `step_in_name`. When
+   a lesson came from a step-in, link it there. Never name a steer as
+   something else.
 
 ## 4. The learnings rule
 

package/work/lib/step-ins.mjs

@@ -0,0 +1,217 @@
+// Roadmap R15 (item ebbf9693): the step-in record. The step-in hook,
+// packages/atlas/hooks/step-in.mjs, appends one row for each message the
+// person sends: the time, the session and the repos, never the text. This
+// module turns the rows into step-in marks, and lets the lead name the
+// class of one. Code counts; the lead only names.
+//
+// Three rules hold it together:
+//   1. The server writes the rows itself, at its start and before each write
+//      verb. No verb takes a row, and no verb skips or deletes one.
+//   2. A mark is never edited. The lead's class is a new mark that corrects
+//      the step-in, and the newest one stands.
+//   3. A message with no class is a step-in. A class of the owner-only list,
+//      a brake, a signed act or an answer says the message was something
+//      else. An answer names a question that was open when the message came.
+import { readdir, readFile, rename, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { refuse, text, url } from './verb-fields.mjs';
+import { oneLine } from './questions.mjs';
+import { OWNER_ONLY_CLASSES } from '../../shape/check.mjs';
+
+export const STEP_IN_WRITE_VERBS = Object.freeze(['step_in_name']);
+export const STEP_IN_READ_VERBS = Object.freeze(['step_ins']);
+// The class names. The first eight are the classes of the owner-only list
+// (R2). A brake stops work, a signed act approves an owner-only change, and
+// an answer replies to an open question.
+export const STEP_IN_CLASSES = Object.freeze([...OWNER_ONLY_CLASSES, 'brake', 'signed-act', 'answer']);
+export const STEP_IN_KIND = 'step-in';
+export const NAME_KIND = 'step-in-name';
+const ROW_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const SESSION = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,199}$/;
+const REPO = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}\/[A-Za-z0-9_.-]{1,100}$/;
+const MAX_ROWS = 200;
+const MAX_LISTED = 100;
+// A claim older than this belongs to a server that stopped mid-write. The
+// mark's request id makes a second write of the same row a no-op.
+const STALE_CLAIM_MS = 10 * 60 * 1000;
+
+// The folder the hook writes. The hook keeps its own copy of the path,
+// because its bytes are pinned.
+export const stepInFolder = (home) => join(home, '.atlas', 'step-ins');
+
+// A row read from the folder, checked field by field. Anything else is not a
+// row: the server leaves the file, and names it in the log.
+export function parseRow(raw) {
+  let row;
+  try { row = JSON.parse(raw); } catch { return null; }
+  if (!row || typeof row !== 'object' || row.v !== 1) return null;
+  if (!ROW_ID.test(String(row.id ?? '')) || !SESSION.test(String(row.session ?? ''))) return null;
+  if (typeof row.at !== 'string' || Number.isNaN(Date.parse(row.at))) return null;
+  if (!Array.isArray(row.repos) || row.repos.length > 16 || !row.repos.every((repo) => typeof repo === 'string' && REPO.test(repo))) return null;
+  return { id: row.id, at: new Date(row.at).toISOString(), session: row.session, repos: [...row.repos] };
+}
+
+// Turn each row in the folder into a mark. Each row is claimed by a rename
+// first, so two servers on one machine never both write it. A row whose
+// write fails goes back, for the next flush.
+export async function flushStepIns({ folder, record, log = () => {}, now = () => Date.now() }) {
+  let names;
+  try { names = await readdir(folder); } catch (error) { if (error.code === 'ENOENT') return { written: 0, left: 0 }; throw error; }
+  for (const name of names.filter((one) => one.endsWith('.claim'))) {
+    try { if (now() - (await stat(join(folder, name))).mtimeMs > STALE_CLAIM_MS) await rename(join(folder, name), join(folder, name.replace(/\.[0-9]+\.claim$/, ''))); } catch { /* another server took it */ }
+  }
+  const rows = (await readdir(folder)).filter((one) => one.endsWith('.json') && !one.startsWith('.')).sort().slice(0, MAX_ROWS);
+  let written = 0, left = 0;
+  for (const name of rows) {
+    const path = join(folder, name), claimed = `${path}.${process.pid}.claim`;
+    try { await rename(path, claimed); } catch { continue; }
+    const row = parseRow(await readFile(claimed, 'utf8').catch(() => ''));
+    if (!row) { await rename(claimed, `${path}.bad`).catch(() => {}); log(`step-in row ${name} is not a row; it was kept as ${name}.bad`); left += 1; continue; }
+    try { await record(row); await rm(claimed, { force: true }); written += 1; }
+    catch (error) { await rename(claimed, path).catch(() => {}); log(`step-in row ${name} was not written: ${error.message}`); left += 1; }
+  }
+  return { written, left };
+}
+
+export function createStepInVerbs(core) {
+  const { client, now, typeNamed, kindOf, registry, requireItem, create, edge, landed } = core;
+
+  // The product of a row, when its repos name one product of the registry.
+  async function productOf(repos) {
+    const reg = await registry();
+    const products = [...new Set(repos.map((id) => reg.repos.get(id)?.fields?.product).filter(Boolean))];
+    return products.length === 1 ? products[0] : '';
+  }
+
+  async function markOf(id) {
+    const type = await typeNamed('mark');
+    let entity;
+    try { entity = await client.getEntity(id); }
+    catch (error) { if (error?.status === 404) refuse(`unknown mark id: ${id}`); throw error; }
+    if (entity.type_id !== type.id) refuse(`entity ${id} is not a mark`);
+    return entity;
+  }
+
+  // One row in, one step-in mark out. The request id comes from the row, so
+  // a row written twice lands once.
+  async function record(row) {
+    const type = await typeNamed('mark');
+    const requestId = `step-in-${row.id}`;
+    const prior = await landed(type, requestId, { verb: 'step_in_record' });
+    if (prior) return prior;
+    const product = await productOf(row.repos);
+    return create(type, requestId, 'step_in_record', {
+      title: oneLine(`Step-in · ${row.repos.join(', ') || 'no repo'} · ${row.at}`, 200),
+      body: 'One message from the person. The hook keeps the time, the session and the repos; it never keeps the text.',
+      fields: { kind: STEP_IN_KIND, verdict: 'counted', item: '', product, marked_at: row.at, session: row.session, repos: row.repos, row: row.id, source: 'hook' },
+      tags: ['atlas-mark', 'step-in', ...(product ? [`product:${product}`] : [])],
+      readBack: false,
+    });
+  }
+
+  // R15 line 7: with the hooks off, nothing counts this session's messages.
+  // The server says so once, with one mark for the session.
+  async function notCounted(session) {
+    const type = await typeNamed('mark');
+    const requestId = `step-in-off-${session.replace(/[^A-Za-z0-9._:-]/g, '-')}`;
+    const prior = await landed(type, requestId, { verb: 'step_in_record' });
+    if (prior) return prior;
+    return create(type, requestId, 'step_in_record', {
+      title: oneLine(`Step-ins not counted · ${session}`, 200),
+      body: 'ATLAS_HOOKS=off stopped the step-in hook, so this session\'s messages were not counted.',
+      fields: { kind: STEP_IN_KIND, verdict: 'not counted', item: '', product: '', marked_at: now(), session, repos: [], source: 'ATLAS_HOOKS=off' },
+      tags: ['atlas-mark', 'step-in', 'not-counted'],
+      readBack: false,
+    });
+  }
+
+  // Every step-in mark with the newest name that corrects it.
+  async function standing() {
+    const type = await typeNamed('mark');
+    const rows = await client.listAllEntities({ type: type.name, state: 'active' });
+    const names = new Map();
+    for (const row of rows.filter((one) => one.fields?.kind === NAME_KIND)) {
+      const of = row.fields.corrects;
+      const held = names.get(of);
+      if (!held || String(row.fields.marked_at ?? '') > String(held.fields.marked_at ?? '')) names.set(of, row);
+    }
+    return rows.filter((one) => one.fields?.kind === STEP_IN_KIND).map((mark) => ({ mark, name: names.get(mark.id) ?? null }));
+  }
+
+  const verbs = {
+    // R15 lines 3, 4 and 5: the lead names what one message was, and links
+    // the lesson it led to. It writes a new mark; the step-in stays.
+    async step_in_name(args, requestId, meta) {
+      const stepIn = await markOf(text(args.step_in, 'step_in', { max: 200 }));
+      if (stepIn.fields?.kind !== STEP_IN_KIND || stepIn.fields?.verdict !== 'counted') refuse(`mark ${stepIn.id} is not a counted step-in mark`);
+      const cls = args.class === undefined ? null : text(args.class, 'class', { max: 40 });
+      if (cls !== null && !STEP_IN_CLASSES.includes(cls)) refuse(`class must be one of ${STEP_IN_CLASSES.join(', ')}; a message with no class is a step-in`);
+      const lesson = args.lesson === undefined ? null : lessonOf(args.lesson);
+      if (cls === null && lesson === null) refuse('name a class, a lesson, or both');
+      let item = args.item_id === undefined ? null : await requireItem(args.item_id);
+      let question = null;
+      if (cls === 'answer') {
+        if (args.question_id === undefined) refuse('the class "answer" needs question_id: the question that was open when the message came');
+        question = await questionOf(text(args.question_id, 'question_id', { max: 200 }));
+        const came = stepIn.fields.marked_at;
+        const asked = question.fields?.asked_at ?? question.created_at ?? '';
+        const closed = question.fields?.status === 'open' ? null : (question.fields?.answered_at ?? null);
+        if (!asked || asked > came) refuse(`question ${question.id} was asked at ${asked || 'an unknown time'}, after the message came at ${came}; an answer replies to a question that was already open`);
+        if (question.fields?.status !== 'open' && (!closed || closed < came)) refuse(`question ${question.id} was ${question.fields?.status ?? 'not open'} before the message came at ${came}; an answer replies to an open question`);
+        if (!item && typeof question.fields?.item === 'string' && question.fields.item) item = await requireItem(question.fields.item);
+      } else if (args.question_id !== undefined) refuse('question_id goes with the class "answer" only');
+      const type = await typeNamed('mark');
+      const prior = await landed(type, requestId, meta);
+      const mark = prior ?? await create(type, requestId, 'step_in_name', {
+        digest: meta?.digest,
+        title: oneLine(`Step-in named · ${cls ?? 'lesson only'} · ${stepIn.fields.marked_at}`, 200),
+        body: `${cls ? `The lead named step-in ${stepIn.id} "${cls}".` : `The lead linked a lesson to step-in ${stepIn.id}.`}${lesson ? ` Lesson: ${lesson}.` : ''}`,
+        fields: {
+          kind: NAME_KIND, verdict: cls ?? 'step-in', item: item?.id ?? '', product: stepIn.fields.product ?? '', marked_at: now(), corrects: stepIn.id,
+          ...(cls ? { class: cls } : {}), ...(question ? { question: question.id } : {}), ...(lesson ? { lesson } : {}),
+        },
+        tags: ['atlas-mark', 'step-in', ...(stepIn.fields.product ? [`product:${stepIn.fields.product}`] : [])],
+      });
+      await edge(mark, stepIn, 'corrects', requestId);
+      if (item) await edge(mark, item, 'references', requestId);
+      return { verb: 'step_in_name', mark_id: mark.id, step_in: stepIn.id, class: cls, item: item?.id ?? null, question: question?.id ?? null, lesson, ...(prior ? { replayed_from_graph: true } : {}) };
+    },
+
+    // The step-ins of a session or since a time, newest first, with the
+    // name that stands on each. The lead reads it to find the id to name.
+    async step_ins(args = {}) {
+      const session = args.session === undefined ? null : text(args.session, 'session', { max: 200 });
+      const since = args.since === undefined ? null : text(args.since, 'since', { max: 40 });
+      if (since !== null && Number.isNaN(Date.parse(since))) refuse('since must be an ISO date or time');
+      const limit = args.limit === undefined ? 20 : Number(args.limit);
+      if (!Number.isInteger(limit) || limit < 1 || limit > MAX_LISTED) refuse(`limit must be a whole number from 1 to ${MAX_LISTED}`);
+      const rows = (await standing())
+        .filter(({ mark }) => (!session || mark.fields.session === session) && (!since || String(mark.fields.marked_at) >= new Date(since).toISOString()))
+        .sort((a, b) => String(b.mark.fields.marked_at).localeCompare(String(a.mark.fields.marked_at)));
+      const shown = rows.slice(0, limit).map(({ mark, name }) => ({
+        step_in: mark.id, at: mark.fields.marked_at, session: mark.fields.session, repos: mark.fields.repos ?? [], verdict: mark.fields.verdict,
+        class: name?.fields?.class ?? null, lesson: name?.fields?.lesson ?? null, item: name?.fields?.item || null, named_by: name?.id ?? null,
+      }));
+      const counted = rows.filter(({ mark, name }) => mark.fields.verdict === 'counted' && !name?.fields?.class).length;
+      return { verb: 'step_ins', total: rows.length, step_ins: counted, not_counted_sessions: rows.filter(({ mark }) => mark.fields.verdict === 'not counted').length, rows: shown };
+    },
+  };
+
+  async function questionOf(id) {
+    let entity;
+    try { entity = await client.getEntity(id); }
+    catch (error) { if (error?.status === 404) refuse(`unknown question id: ${id}`); throw error; }
+    if ((await kindOf(entity)) !== 'question') refuse(`entity ${id} is not a question`);
+    return entity;
+  }
+
+  return { verbs, record, notCounted };
+}
+
+// A lesson is a link: a pull request, a learnings entry, a page. Or the id
+// of a tracker record, such as the item the lesson became.
+function lessonOf(value) {
+  const plain = text(value, 'lesson', { max: 500 }).trim();
+  if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(plain)) return plain.toLowerCase();
+  return url(plain, 'lesson');
+}

package/work/lib/verbs.mjs

@@ -22,6 +22,7 @@ import { createCapabilityVerbs, CAPABILITY_READ_VERBS, hubOf } from './capabilit
 import { createSweepVerbs, SWEEP_WRITE_VERBS, SWEEP_READ_VERBS } from './sweep.mjs';
 import { createRoundupVerbs, ROUNDUP_READ_VERBS } from './roundup.mjs';
 import { createActivityVerbs, diffOf, LOG_VERBS, ENTRY_VERBS, ACTIVITY_WRITE_VERBS, ACTIVITY_READ_VERBS } from './activity.mjs';
+import { createStepInVerbs, STEP_IN_WRITE_VERBS, STEP_IN_READ_VERBS } from './step-ins.mjs';
 
 export { VerbError, canonicalJson, sha256, COSTS, LIVE_LIFECYCLES, REPO_KINDS, LIVE_KINDS, repoKinds };
 export const MANIFEST_VERSION = '0.7.0';
@@ -755,9 +756,13 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
   Object.assign(verbs, createRoundupVerbs({ ...core, readGitHub, inFlight: (args) => verbs.in_flight(args), needsMe: (args) => verbs.needs_me(args) }));
   const activity = createActivityVerbs(core);
   Object.assign(verbs, activity.verbs);
+  // Roadmap R15: the step-in record. The server writes the hook's rows
+  // through record and notCounted, which no tool exposes.
+  const stepIns = createStepInVerbs(core);
+  Object.assign(verbs, stepIns.verbs);
 
-  const WRITE_VERBS = Object.freeze(['setup', 'product_add', 'product_edit', 'repo_add', 'repo_edit', 'item_propose', 'item_lock', 'item_split', 'item_park', 'item_resume', 'item_drop', 'item_edit', 'item_block', 'item_unblock', 'item_stage', 'item_link', ...QUESTION_WRITE_VERBS, ...DELIVERY_WRITE_VERBS, ...SWEEP_WRITE_VERBS, ...ACTIVITY_WRITE_VERBS]);
-  const READ_VERBS = Object.freeze(['registry_list', ...QUESTION_READ_VERBS, ...DELIVERY_READ_VERBS, ...CAPABILITY_READ_VERBS, ...SWEEP_READ_VERBS, ...ROUNDUP_READ_VERBS, ...ACTIVITY_READ_VERBS]);
+  const WRITE_VERBS = Object.freeze(['setup', 'product_add', 'product_edit', 'repo_add', 'repo_edit', 'item_propose', 'item_lock', 'item_split', 'item_park', 'item_resume', 'item_drop', 'item_edit', 'item_block', 'item_unblock', 'item_stage', 'item_link', ...QUESTION_WRITE_VERBS, ...DELIVERY_WRITE_VERBS, ...SWEEP_WRITE_VERBS, ...ACTIVITY_WRITE_VERBS, ...STEP_IN_WRITE_VERBS]);
+  const READ_VERBS = Object.freeze(['registry_list', ...QUESTION_READ_VERBS, ...DELIVERY_READ_VERBS, ...CAPABILITY_READ_VERBS, ...SWEEP_READ_VERBS, ...ROUNDUP_READ_VERBS, ...ACTIVITY_READ_VERBS, ...STEP_IN_READ_VERBS]);
 
   async function run(verb, args = {}) {
     if (!verbs[verb]) refuse(`unknown verb: ${verb}`);
@@ -795,5 +800,7 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
     });
   }
 
-  return Object.freeze({ run, verbs: Object.freeze([...WRITE_VERBS, ...READ_VERBS]), writer: label });
+  // Roadmap R15: the server writes the step-in rows itself, never a caller.
+  const stepInRecord = Object.freeze({ record: (row) => stepIns.record(row), notCounted: (session) => stepIns.notCounted(session) });
+  return Object.freeze({ run, verbs: Object.freeze([...WRITE_VERBS, ...READ_VERBS]), readVerbs: READ_VERBS, writer: label, stepIns: stepInRecord });
 }

package/work/mcp.mjs

@@ -22,6 +22,7 @@ import { createEngramClient } from './lib/client.mjs';
 import { createActionStore } from './lib/action-store.mjs';
 import { createVerbs, STAGES, TIERS, DRIVERS, LINK_KINDS, REPO_KINDS, WAITS_ON, MANIFEST_VERSION, COSTS } from './lib/verbs.mjs';
 import { COST_MEANING, DECISION_KINDS } from './lib/questions.mjs';
+import { STEP_IN_CLASSES, stepInFolder, flushStepIns } from './lib/step-ins.mjs';
 import { FATAL_CONCLUSIONS } from './lib/delivery.mjs';
 import { createMcpServer } from './lib/mcp-stdio.mjs';
 import { childEnvironment, CLOUD_NODE_VARIABLES } from './lib/child-env.mjs';
@@ -58,6 +59,8 @@ export const TOOLS = [
   { name: 'item_unblock', description: `Remove one blocked-by link from an item. The removed link stays in the item's log. When: the blocker no longer holds the item back. No owner flag needed. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'item_id', 'blocked_by'], properties: { request_id: REQUEST_ID, item_id: S('The blocked item id.'), blocked_by: S('The blocker item id to remove.'), reason: S('One line on why.') }, additionalProperties: false } },
   { name: 'item_comment', description: `Add a comment to an item's log: a running note from the lead, or the owner's own words. A comment is never edited; to correct one, add a new comment that names it in corrects. The text goes through the secret filter. When: something about the item is worth keeping that no other verb records. No owner flag for the agent's voice; the owner's voice is his words, word for word, so it needs the owner present. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'item_id', 'text'], properties: { request_id: REQUEST_ID, item_id: S('Item id.'), text: S('The comment, at most 4000 characters.'), voice: S('agent (the default) or owner. owner means the text is the owner\'s own words. Owner present only.'), corrects: S('The entry id of an earlier comment on this item that this one corrects.') }, additionalProperties: false } },
   { name: 'item_activity', description: 'Answer "what happened on this item?". One list, newest first: the comments, each change an item verb made with its old and new values, the questions, the decisions, the delivery marks, the pieces and the links. A write that kept no values, such as one from before manifest 0.7.0, shows its verb and time with "no values recorded". The edits kept on the item before 0.7.0 show too. Scope: read, no owner flag needed.', inputSchema: { type: 'object', required: ['item_id'], properties: { item_id: S('Item id.'), limit: { type: 'integer', minimum: 1, maximum: 200, description: 'How many rows, newest first. Default 50.' } }, additionalProperties: false } },
+  { name: 'step_in_name', description: `Name what one message of the person was, or link the lesson it led to (roadmap R15). The step-in hook counts each message the person sends, and the server writes each one as a step-in mark; this verb never adds, skips or deletes one. It writes a new mark that corrects the step-in, and the newest name stands. A message with no class is a step-in. The classes: ${STEP_IN_CLASSES.join(', ')}. The first eight are the classes of the owner-only list. "answer" needs question_id, a question that was open when the message came. When: the lead knows what the message was, or a lesson came out of it. No owner flag. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'step_in'], properties: { request_id: REQUEST_ID, step_in: S('The step-in mark id, from step_ins.'), class: { type: 'string', enum: [...STEP_IN_CLASSES], description: 'What the message was. Leave it out to keep it a step-in and only link a lesson.' }, question_id: S('For class answer: the question the message answered.'), item_id: S('The item the message was about. An answer takes the item of its question.'), lesson: S('The lesson the step-in led to: a URL, or the id of a tracker record.') }, additionalProperties: false } },
+  { name: 'step_ins', description: 'List the step-in marks, newest first, with the name that stands on each: the time, the session, the repos, and the class and lesson the lead named. step_ins counts the messages with no class; not_counted_sessions counts the sessions whose hooks were off. When: before step_in_name, to find the id. Scope: read, no owner flag needed.', inputSchema: { type: 'object', properties: { session: S('Only this session.'), since: S('ISO date or time: only step-ins from then on.'), limit: { type: 'integer', minimum: 1, maximum: 100, description: 'How many rows. Default 20.' } }, additionalProperties: false } },
   { name: 'item_link', description: `Attach a typed link (kind, url, role, note) to an item: a PR, an issue, an artifact, a design doc, a conversation. When: any in-session agent has a link the item should carry, for example a PR it opened. No owner flag needed. A duplicate kind and url is a no-op. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'item_id', 'kind', 'url'], properties: { request_id: REQUEST_ID, item_id: S('Item id.'), kind: S(`One of ${LINK_KINDS.join(', ')}.`), url: S('Absolute http or https URL.'), role: S('What the link is to the item, for example "delivers", "design", "evidence".'), note: S('One line.') }, additionalProperties: false } },
   { name: 'item_adopt', description: `Give an existing work item its product and repos. This is the slice L5 sweep: most items in the tenant were made before the registry existed and name no product, so no view can place them. Refuses an item that already names another registered product; an item is named once. The audit stamps adopted_at and adopted_from move only when the product actually changes. When: the owner says which product a piece of work belongs to. Owner present only. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'item_id', 'product', 'repos'], properties: { request_id: REQUEST_ID, item_id: S('Item id.'), product: S('Product id the item belongs to.'), repos: { type: 'array', items: { type: 'string' }, description: 'Repo ids under that product. Required. Pass an empty list for an item that has no repo, such as a container root; a repo of another product is dropped and named in dropped_repos.' }, stage: S(`One of ${STAGES.join(', ')}. Active items only.`), tier: S(`One of ${TIERS.join(', ')}.`), driver: S(`One of ${DRIVERS.join(', ')}.`), next_step: S('One line: what happens next.') }, additionalProperties: false } },
   { name: 'question_ask', description: `Ask the owner one question that blocks work on an item, and say what waiting costs. When: an agent is blocked and cannot decide by itself. Any in-session agent may call it; no owner flag. The question shows in the "Needs me" view until it is answered. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'text', 'item_id', 'product', 'cost'], properties: { request_id: REQUEST_ID, text: S('The question, in plain words, answerable without opening a source.'), item_id: S('Entity id of the work item the question blocks.'), product: S('Product id of that item.'), cost: S(`What waiting costs. One of: ${COSTS.map((cost) => `${cost} (${COST_MEANING[cost]})`).join('; ')}.`), context: { type: 'object', description: 'What the owner needs to answer without opening a source.', properties: { current_behavior: S('What happens today.'), change: S('What would change.'), affected: { type: 'array', items: { type: 'string' }, description: 'Parts that change.' }, options: { type: 'array', items: { type: 'string' }, description: 'The options, one per entry.' }, consequences: S('What follows from each option.'), sources: { type: 'array', items: { type: 'string' }, description: 'Absolute http or https URLs that back the context.' } } } }, additionalProperties: false } },
@@ -302,15 +305,36 @@ export function buildServer({ env = process.env, input, output, readGitHub, read
   const instructions = connection.state === 'ok'
     ? `Atlas work verbs for the owner's session. Session ${session}; owner present: ${ownerPresent ? 'yes' : 'no: the owner-only tools refuse'}. Call registry_list first to learn the product and repo ids, needs_me to see the open questions, and in_flight to see the active work. Every write needs a request_id. The server stamps writer.session and the bound client; never pass writer, session, actor or role. Unknown product or repo ids are refused. Sub-agents must not receive this server.`
     : `Atlas work verbs. They cannot reach Engram yet: ${connection.message}`;
-  const server = createMcpServer({ name: 'atlas-work', version: MANIFEST_VERSION, instructions, tools: TOOLS, input, output, log, call: (name, args, boundTo) => {
+  // Roadmap R15: the step-in rows of the hook become marks at the server's
+  // start and before each write verb. A failed flush leaves the rows for the
+  // next one and never stops the verb. With ATLAS_HOOKS=off nothing counts
+  // this session's messages, so the server writes one "not counted" mark.
+  const stepInHome = typeof env.HOME === 'string' && isAbsolute(env.HOME) ? env.HOME : null;
+  const claudeSession = /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,199}$/.test(env.CLAUDE_CODE_SESSION_ID ?? '') ? env.CLAUDE_CODE_SESSION_ID : session;
+  const say = (line) => { try { log?.(line); } catch { /* the log is advice */ } };
+  let flushing = null;
+  const flush = () => {
+    if (!verbs || !stepInHome) return Promise.resolve(null);
+    const { record } = verbs.stepIns;
+    flushing ??= flushStepIns({ folder: stepInFolder(stepInHome), record, log: say })
+      .catch((error) => { say(`step-ins: ${error.message}`); return null; })
+      .finally(() => { flushing = null; });
+    return flushing;
+  };
+  const started = verbs ? Promise.all([
+    flush(),
+    env.ATLAS_HOOKS === 'off' ? verbs.stepIns.notCounted(claudeSession).catch((error) => say(`step-ins: the "not counted" mark was not written: ${error.message}`)) : null,
+  ]) : Promise.resolve();
+  const server = createMcpServer({ name: 'atlas-work', version: MANIFEST_VERSION, instructions, tools: TOOLS, input, output, log, call: async (name, args, boundTo) => {
     // The upgrade needs no Engram connection: an old key must not block a new release.
     if (name === 'atlas_upgrade') return runUpgrade({ args, env, ownerPresent });
     if (!verbs) throw new Error(connection.message);
     // The writer names the one client this server is bound to (D6 R3): stamped by the server, never by the caller.
     if (boundTo && boundTo.session !== bound) { bound = boundTo.session; verbs = verbsFor(bound); }
+    if (!verbs.readVerbs.includes(name)) await flush();
     return verbs.run(name, args);
   } });
-  return { server, session, connection, health, verbs: () => verbs };
+  return { server, session, connection, health, verbs: () => verbs, stepIns: { flush, started } };
 }
 
 // Real paths on both sides: macOS reaches /var through /private/var, and a