@arjunkhera/atlas 0.4.7 → 0.4.8

package/.claude-plugin/plugin.json

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

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.8",
   "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