@arjunkhera/atlas 0.4.28 → 0.4.30

package/.claude-plugin/plugin.json

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

package/package.json

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

@@ -22,21 +22,35 @@ and makes it hard to miss again.
 
 1. **Name the lesson** in one plain sentence. Say what went wrong and
    what is right.
-2. **Pick one home.**
+2. **Look for a repeat.** Call `lessons` for the product. Read each line.
+   When an earlier lesson says the same thing, this lesson is a repeat.
+   Keep that lesson's id, and read its fix: the fix did not hold, so make
+   the new fix stronger.
+3. **Pick one home.**
    - The lesson holds only for this repo: it becomes a change here.
    - The lesson holds for every repo: it becomes an Atlas item.
-3. **For an Atlas lesson,** propose an item in the Atlas tracker, with
+4. **For an Atlas lesson,** propose an item in the Atlas tracker, with
    the Atlas tools. Put the owner's words in it, word for word. Tag it
    `learning`. Link it to the repo where the miss happened. Tell the owner
    the item and that an Atlas release, on their word, closes it.
-4. **Pick the strongest form that fits,** in this order:
+5. **Pick the strongest form that fits,** in this order:
    1. a check that fails when the miss happens again;
    2. a tool that makes the right way the easy way;
    3. a skill step;
    4. a line in a doc, with a short note.
-5. **Prune.** A new rule retires or merges each rule it replaces. Name
+6. **Prune.** A new rule retires or merges each rule it replaces. Name
    the rules you removed in the pull request.
-6. **Make the change** in its home, through the normal flow.
+7. **Make the change** in its home, through the normal flow.
+8. **Record the lesson.** Call `lesson_record` once, when the fix exists:
+   - `line`: the sentence of step 1;
+   - `home`: `repo` with the repo id, or `atlas`;
+   - `form`: `check`, `tool`, `skill` or `doc`;
+   - `fix`: the pull request, or the Atlas item of step 4;
+   - `source`: `owner`, `revert`, `bug` or `machine`, and in `source_ref`
+     the step-in, the revert or the bug;
+   - `repeats`: the id that step 2 found, if any.
+9. **Link the step-in.** When the owner's message started the lesson, call
+   `step_in_name` on that step-in with the lesson id as `lesson`.
 
 ## Rules
 
@@ -46,3 +60,4 @@ and makes it hard to miss again.
 2. A lesson about one repo's product stays in that repo. It never goes
    into an Atlas release.
 3. One lesson is one fix. Do not batch unrelated lessons.
+4. Every lesson leaves one record, a repo lesson too. Never skip step 8.

package/skills/sdlc-task/SKILL.md

@@ -205,8 +205,8 @@ next action. One short paragraph.
    and quote the exact test. One decision accepts one red check. Then pass
    `accepted_red` to `item_done`; it needs the owner present. Any other red
    check still refuses the mark.
-2. If anything was a struggle, encode the fix where it stops a repeat — a lint,
-   then a tool, then a skill, then a doc — and say which.
+2. If anything was a struggle, run the `atlas:learnings` skill. It picks the
+   home and the form of the fix, and records the lesson.
 3. Rebuild the design's page and the hub, so both read "Shipped". The
    design folder does not change: the tracker holds the delivery. A design
    in the older format is one file, not a folder. Keep its page, and rebuild

package/work/lib/lessons.mjs

@@ -0,0 +1,133 @@
+// Roadmap R55 (item 8d87c567): every lesson leaves one record. A lesson is
+// a mark of kind lesson, so the tracker needs no new type. It holds one line,
+// the home, the form, the fix link, the source and the lesson it repeats.
+// The learnings skill reads the lessons before it records one, and records a
+// match as a repeat. The roundup counts them per week.
+//
+// Three rules hold it together:
+//   1. A mark is never edited. A lesson that repeats another names it; the
+//      first lesson stays as it was.
+//   2. A repeat names a lesson of the same product. A lesson home in a repo
+//      names a registered repo of that product.
+//   3. A failed read throws. It never reads as zero lessons.
+import { refuse, text, oneOf, url } from './verb-fields.mjs';
+import { oneLine, scrubSecrets } from './questions.mjs';
+import { standingOf, isStepIn } from './step-ins.mjs';
+import { isRevert } from './numbers.mjs';
+
+export const LESSON_WRITE_VERBS = Object.freeze(['lesson_record']);
+export const LESSON_READ_VERBS = Object.freeze(['lessons']);
+export const LESSON_KIND = 'lesson';
+// Where the fix lives: this repo, or Atlas for every repo.
+export const LESSON_HOMES = Object.freeze(['repo', 'atlas']);
+// The strongest form that fits, in the order of the learnings skill.
+export const LESSON_FORMS = Object.freeze(['check', 'tool', 'skill', 'doc']);
+// What found the miss: the owner's correction, a revert, a bug after a
+// merge, or a machine (a red main branch, a revert job) with no owner words.
+export const LESSON_SOURCES = Object.freeze(['owner', 'revert', 'bug', 'machine']);
+const RECORD_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const MAX_LISTED = 100;
+
+// A link is a URL, or the id of a tracker record such as the item a lesson
+// became.
+function linkOf(value, name, { optional = false } = {}) {
+  if (value === undefined && optional) return '';
+  const plain = text(value, name, { max: 2000 }).trim();
+  if (RECORD_ID.test(plain)) return plain.toLowerCase();
+  return url(plain, name);
+}
+
+// One rule for a revert and one for a step-in, shared with the numbers of
+// R16: a revert pull request (numbers.mjs), and a step-in that still counts,
+// an owner message whose newest name gives no class (step-ins.mjs).
+export { isRevert };
+export const countedStepIns = (marks) => standingOf(marks).filter(isStepIn).map(({ mark }) => mark);
+
+const rowOf = (mark, repeatedBy) => ({
+  lesson: mark.id, at: mark.fields.marked_at, line: mark.fields.line, home: mark.fields.home, repo: mark.fields.repo || null,
+  form: mark.fields.form, fix: mark.fields.fix, source: mark.fields.source, source_ref: mark.fields.source_ref || null,
+  repeats: mark.fields.repeats || null, item: mark.fields.item || null, repeated_by: repeatedBy.get(mark.id) ?? [],
+});
+
+export function createLessonVerbs(core) {
+  const { client, now, typeNamed, registry, requireProduct, requireItem, create, edge, landed } = core;
+
+  async function lessonMarks(product) {
+    const type = await typeNamed('mark');
+    const rows = await client.listAllEntities({ type: type.name, state: 'active' });
+    return rows.filter((one) => one.fields?.kind === LESSON_KIND && (!product || one.fields?.product === product));
+  }
+
+  return {
+    // R55 line 1: one lesson, one mark. The learnings skill calls it once the
+    // fix exists, so the fix link is never empty.
+    async lesson_record(args, requestId, meta) {
+      const reg = await registry();
+      const product = (await requireProduct(args.product, reg)).fields.registry_id;
+      const scrubbed = scrubSecrets(text(args.line, 'line', { max: 300 }));
+      const line = oneLine(scrubbed.text, 300);
+      const home = oneOf(args.home, 'home', LESSON_HOMES);
+      let repo = '';
+      if (home === 'repo') {
+        repo = text(args.repo, 'repo', { max: 200 });
+        const record = reg.repos.get(repo);
+        if (!record) refuse(`unknown repo id: ${repo}. Known: ${[...reg.repos.keys()].sort().join(', ') || 'none'}`);
+        if (record.fields?.product !== product) refuse(`repo ${repo} belongs to product ${record.fields?.product}, not ${product}`);
+      } else if (args.repo !== undefined) refuse('repo goes with home "repo" only; an Atlas lesson holds for every repo');
+      const form = oneOf(args.form, 'form', LESSON_FORMS);
+      const fix = linkOf(args.fix, 'fix');
+      const source = oneOf(args.source, 'source', LESSON_SOURCES);
+      const sourceRef = linkOf(args.source_ref, 'source_ref', { optional: true });
+      const item = args.item_id === undefined ? null : await requireItem(args.item_id);
+      let repeated = null;
+      if (args.repeats !== undefined) {
+        const id = text(args.repeats, 'repeats', { max: 200 });
+        let entity;
+        try { entity = await client.getEntity(id); }
+        catch (error) { if (error?.status === 404) refuse(`unknown lesson id: ${id}`); throw error; }
+        const type = await typeNamed('mark');
+        if (entity.type_id !== type.id || entity.fields?.kind !== LESSON_KIND) refuse(`entity ${id} is not a lesson mark`);
+        if (entity.fields?.product !== product) refuse(`lesson ${id} belongs to product ${entity.fields?.product}, not ${product}`);
+        repeated = entity;
+      }
+      const type = await typeNamed('mark');
+      const prior = await landed(type, requestId, meta);
+      const mark = prior ?? await create(type, requestId, 'lesson_record', {
+        digest: meta?.digest,
+        title: oneLine(`Lesson${repeated ? ' (repeat)' : ''} · ${line}`, 200),
+        body: `${line}\n\nHome: ${home === 'repo' ? repo : 'Atlas'}. Form: ${form}. Fix: ${fix}. Source: ${source}${sourceRef ? ` (${sourceRef})` : ''}.${repeated ? ` It repeats lesson ${repeated.id}.` : ''}`,
+        fields: {
+          kind: LESSON_KIND, verdict: repeated ? 'repeat' : 'new', item: item?.id ?? '', product, marked_at: now(),
+          line, home, repo, form, fix, source, source_ref: sourceRef, repeats: repeated?.id ?? '',
+        },
+        tags: ['atlas-mark', 'lesson', `product:${product}`, ...(repeated ? ['repeat'] : [])],
+      });
+      if (repeated) await edge(mark, repeated, 'references', requestId);
+      if (item) await edge(mark, item, 'references', requestId);
+      return {
+        verb: 'lesson_record', lesson: mark.id, product, line, home, repo: repo || null, form, fix, source, source_ref: sourceRef || null,
+        repeats: repeated?.id ?? null, item: item?.id ?? null, ...(scrubbed.redactions ? { redactions: scrubbed.redactions } : {}), ...(prior ? { replayed_from_graph: true } : {}),
+      };
+    },
+
+    // R55 line 2: a product's lessons, newest first. Each row lists the
+    // lessons that repeat it, so the learnings skill sees what came back.
+    async lessons(args = {}) {
+      const reg = await registry();
+      const product = (await requireProduct(args.product, reg)).fields.registry_id;
+      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 marks = await lessonMarks(product);
+      const repeatedBy = new Map();
+      for (const mark of marks) if (mark.fields.repeats) repeatedBy.set(mark.fields.repeats, [...(repeatedBy.get(mark.fields.repeats) ?? []), mark.id]);
+      const rows = marks.filter((mark) => !since || String(mark.fields.marked_at) >= new Date(since).toISOString())
+        .sort((a, b) => String(b.fields.marked_at).localeCompare(String(a.fields.marked_at)));
+      return {
+        verb: 'lessons', product, total: rows.length, repeats: rows.filter((mark) => mark.fields.repeats).length,
+        rows: rows.slice(0, limit).map((mark) => rowOf(mark, repeatedBy)),
+      };
+    },
+  };
+}

package/work/lib/numbers.mjs

@@ -16,6 +16,7 @@ import { deliveryFacts, FATAL_CONCLUSIONS } from './delivery.mjs';
 import { standingOf, isOwnerMessage, isStepIn, senderOfMark } from './step-ins.mjs';
 import { ACTIONS_APP_ID } from '../../door/lib/gate.mjs';
 import { groupOf } from '../../door/lib/changed-tests.mjs';
+import { SIGNERS_FILE, parseSigners, verifyTexts, findAct } from '../../door/lib/signed-act.mjs';
 
 export const NUMBERS_MAX_DAYS = 92;
 export const NUMBERS_DEFAULT_DAYS = 28;
@@ -24,20 +25,21 @@ export const PAGE = 100;
 // never cut.
 export const MAX_PULL_PAGES = 10;
 const MAX_FILE_PAGES = 30;
+const MAX_COMMENT_PAGES = 10;
 const CONCURRENCY = 8;
 const DAY = 86_400_000;
 // The second check of a changed test (roadmap R73). A signed act (R72) is
-// the other one; it is not built yet.
+// the other one.
 export const SECOND_CHECK = 'passes-after';
 // A changed or removed file of these groups is an old test that changed. A
 // package.json or a runner config changes for many reasons, so it is not.
 const TEST_GROUPS = Object.freeze(['unit-test', 'check-block', 'scenario-words', 'test-helper', 'kit-manifest']);
 // The GitHub counts and the tracker counts of one row.
-export const GITHUB_COUNTS = Object.freeze(['merges', 'not_on_green', 'reverts', 'unchecked_test_changes']);
+export const GITHUB_COUNTS = Object.freeze(['merges', 'not_on_green', 'reverts', 'unchecked_test_changes', 'signed_acts']);
 export const GRAPH_COUNTS = Object.freeze(['reopens', 'step_ins', 'owner_messages', 'platform_messages']);
-// Line 2: the counts that wait on items not built yet. They are named, never
+// Line 2: the count that waits on an item not built yet. It is named, never
 // shown as zero.
-export const WAITING = Object.freeze({ signed_acts: 'waits on R72, the signed act', audit_unsigned_merges: 'waits on R14, the audit job' });
+export const WAITING = Object.freeze({ audit_unsigned_merges: 'waits on R14 line 3, the unsigned-merge finding of the audit job' });
 
 const DATE = /^\d{4}-\d{2}-\d{2}$/;
 const dayOf = (value) => String(value ?? '').slice(0, 10);
@@ -106,6 +108,29 @@ async function readAllFiles(repo, number, readGitHub) {
   throw new Error(`pull request ${number} changed more than ${MAX_FILE_PAGES * PAGE} files`);
 }
 
+// Line 2: the comment texts of one pull request, every page. More than
+// MAX_COMMENT_PAGES pages is refused, never cut.
+export async function readAllComments(repo, number, readGitHub) {
+  const texts = [];
+  for (let page = 1; page <= MAX_COMMENT_PAGES; page += 1) {
+    const rows = await readGitHub(`repos/${repo}/issues/${number}/comments?per_page=${PAGE}&page=${page}`);
+    if (!Array.isArray(rows)) throw new Error(`the comments of pull request ${number} are not a list`);
+    texts.push(...rows.map((row) => String(row?.body ?? '')));
+    if (rows.length < PAGE) return texts;
+  }
+  throw new Error(`pull request ${number} has more than ${MAX_COMMENT_PAGES * PAGE} comments`);
+}
+
+// Line 2: the owner's signed act for the merged head of one pull request, or
+// null. The key comes from atlas/owner-signers at the first parent of the
+// merge, as the gate reads it from the base. The act must name this repo,
+// this pull request, its base branch and its last head. The gate checked the
+// merge base when it let the head pass; this count does not read it again.
+export function signedActOf({ repo, pull, texts, keys }) {
+  const found = findAct(verifyTexts(texts, keys), { kind: 'merge', repo, pr: Number(pull.number), base: pull.base?.ref, head: pull.head?.sha });
+  return found ? { signed_at: found.signed_at, key: found.key } : null;
+}
+
 // Run each job, at most `limit` at a time. The first failure stops the rest
 // and is thrown, so a count is whole or refused.
 async function pool(jobs, limit = CONCURRENCY) {
@@ -151,8 +176,9 @@ export function notOnGreenReasons({ required = [], runs = [], mergedAt }) {
 }
 
 // A merged pull request that undoes another: GitHub's revert button writes
-// both of these.
-export const isRevert = (pull) => /^revert\b/i.test(String(pull.title ?? '').trim()) || /^Reverts [A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+#\d+/m.test(String(pull.body ?? ''));
+// both of these. The roundup's rows keep the body inside names
+// (delivery.mjs).
+export const isRevert = (pull) => /^revert\b/i.test(String(pull.title ?? '').trim()) || /^Reverts [A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+#\d+/m.test(String(pull.body ?? pull.names ?? ''));
 
 // The old tests that one merge changed or removed. An added test is new, so
 // it is not here.
@@ -179,38 +205,48 @@ export function secondCheckPassed(runs = [], mergedAt) {
 export async function readMerges({ repo, defaultBranch, period, readGitHub }) {
   const pulls = await readAllPulls(repo, readGitHub, period.start);
   const merges = pulls.filter((pull) => pull.merged_at && time(pull.merged_at) >= period.start && time(pull.merged_at) < period.end && (!defaultBranch || pull.base?.ref === defaultBranch));
-  const facts = new Map();
-  const requiredAt = (sha) => {
-    if (!facts.has(sha)) facts.set(sha, (async () => {
+  const cache = new Map();
+  // One file at one commit, read once. A file that is not there is null.
+  const textAt = (path, sha) => {
+    const key = `${path}@${sha}`;
+    if (!cache.has(key)) cache.set(key, (async () => {
       let file;
-      try { file = await readGitHub(`repos/${repo}/contents/atlas.yaml?ref=${sha}`); }
-      catch (error) { if (error?.status === 404 || /HTTP 404|Not Found/i.test(String(error?.message ?? ''))) return []; throw error; }
-      if (!file || typeof file.content !== 'string') return [];
-      return deliveryFacts(Buffer.from(file.content, 'base64').toString('utf8')).required;
+      try { file = await readGitHub(`repos/${repo}/contents/${path}?ref=${sha}`); }
+      catch (error) { if (error?.status === 404 || /HTTP 404|Not Found/i.test(String(error?.message ?? ''))) return null; throw error; }
+      if (!file || typeof file.content !== 'string') return null;
+      return Buffer.from(file.content, 'base64').toString('utf8');
     })());
-    return facts.get(sha);
+    return cache.get(key);
+  };
+  const requiredAt = async (sha) => {
+    const text = await textAt('atlas.yaml', sha);
+    return text === null ? [] : deliveryFacts(text).required;
   };
   return pool(merges.map((pull) => async () => {
     const head = pull.head?.sha, merge = pull.merge_commit_sha;
     if (!/^[0-9a-f]{40}$/i.test(String(head)) || !/^[0-9a-f]{40}$/i.test(String(merge))) throw new Error(`GitHub names no head or merge commit for pull request ${pull.number}`);
-    const requiredBefore = async () => {
+    const before = async () => {
       const parent = (await readGitHub(`repos/${repo}/commits/${merge}`))?.parents?.[0]?.sha;
       if (!/^[0-9a-f]{40}$/i.test(String(parent))) throw new Error(`GitHub names no parent of the merge commit of pull request ${pull.number}`);
-      return requiredAt(parent);
+      const [required, signers] = await Promise.all([requiredAt(parent), textAt(SIGNERS_FILE, parent)]);
+      return { required, signers };
     };
-    const [checks, files, required] = await Promise.all([
+    const [checks, files, { required, signers }] = await Promise.all([
       readGitHub(`repos/${repo}/commits/${head}/check-runs?per_page=${PAGE}`),
       readAllFiles(repo, pull.number, readGitHub),
-      requiredBefore(),
+      before(),
     ]);
     if (!Array.isArray(checks?.check_runs)) throw new Error(`the check runs of pull request ${pull.number} are not a list`);
     const runs = checks.check_runs;
     if (Number(checks?.total_count ?? runs.length) > runs.length) throw new Error(`the head of pull request ${pull.number} has more than ${PAGE} check runs`);
     const tests = changedOldTests(files);
+    // With no owner key at the merge, no act can count: the comments are not read.
+    const keys = parseSigners(signers ?? '').keys;
+    const signed = keys.length ? signedActOf({ repo, pull, texts: await readAllComments(repo, pull.number, readGitHub), keys }) : null;
     return {
       repo, number: pull.number, url: pull.html_url ?? `https://github.com/${repo}/pull/${pull.number}`, title: oneLine(pull.title ?? '', 200), merged_at: pull.merged_at,
       not_on_green: notOnGreenReasons({ required, runs, mergedAt: pull.merged_at }), revert: isRevert(pull),
-      changed_tests: tests, unchecked: tests.length > 0 && !secondCheckPassed(runs, pull.merged_at),
+      changed_tests: tests, signed, unchecked: tests.length > 0 && !signed && !secondCheckPassed(runs, pull.merged_at),
     };
   }));
 }
@@ -283,6 +319,7 @@ export async function readNumbers({ product, repos, items, marks, period, readGi
       if (merge.not_on_green.length) events.push(['not_on_green', merge.merged_at]);
       if (merge.revert) events.push(['reverts', merge.merged_at]);
       if (merge.unchecked) events.push(['unchecked_test_changes', merge.merged_at]);
+      if (merge.signed) events.push(['signed_acts', merge.merged_at]);
     }
     for (const mark of reopens) if (itemRepos.get(mark.fields.item).includes(repo.id)) events.push(['reopens', mark.fields.marked_at]);
     for (const pair of pairs) {
@@ -304,6 +341,7 @@ export async function readNumbers({ product, repos, items, marks, period, readGi
       not_on_green: refused ? null : merges.filter((merge) => merge.not_on_green.length).map((merge) => ({ pr: merge.url, merged_at: merge.merged_at, reasons: merge.not_on_green })),
       reverts: refused ? null : merges.filter((merge) => merge.revert).map((merge) => ({ pr: merge.url, title: merge.title })),
       unchecked_test_changes: refused ? null : merges.filter((merge) => merge.unchecked).map((merge) => ({ pr: merge.url, tests: merge.changed_tests })),
+      signed_acts: refused ? null : merges.filter((merge) => merge.signed).map((merge) => ({ pr: merge.url, signed_at: merge.signed.signed_at, key: merge.signed.key })),
     });
   }
   const delivered = deliveredRows({ marks: marks.filter((mark) => mark.fields?.product === product), items, period });

package/work/lib/roundup.mjs

@@ -12,7 +12,9 @@
 //                       but not marked, open pull requests that name no item,
 //                       and questions that wait longer than STUCK_DAYS
 //   5. Trend            per week, for TREND_WEEKS weeks: merges, deliveries,
-//                       new items; and the open questions with the oldest age
+//                       new items, lessons, repeats, step-ins and reverts
+//                       (roadmap R55); and the open questions with the
+//                       oldest age. A failed read of the marks is an error.
 //   6. The numbers      per repo, per week and per month: merges, merges not
 //                       on green, reverts, reopens, unchecked test changes,
 //                       step-ins and owner messages; and the time from input
@@ -24,6 +26,7 @@ import { refuse, isoDate, LIVE_LIFECYCLES } from './verb-fields.mjs';
 import { oneLine, ROW_LINE_MAX } from './questions.mjs';
 import { readPullsByRepo, pullsOfItem, daysBetween, listLine } from './delivery.mjs';
 import { readNumbers, periodOf } from './numbers.mjs';
+import { LESSON_KIND, countedStepIns, isRevert } from './lessons.mjs';
 
 export const ROUNDUP_READ_VERBS = Object.freeze(['roundup']);
 
@@ -174,17 +177,29 @@ export function createRoundupVerbs(core) {
       const audits = await readAudits(repoIds, readGitHub, readAt);
 
       // 5. Trend, per week; week 1 is the last seven days.
-      const weeks = Array.from({ length: TREND_WEEKS }, (_, index) => ({ week: index + 1, from: dayOf(minus(readAt, (index + 1) * 7)), to: dayOf(minus(readAt, index * 7)), merged: 0, delivered: 0, new_items: 0 }));
-      const bump = (at, key) => { const week = weekOf(at, readAt); if (week) weeks[week - 1][key] += 1; };
+      // Lessons, repeats and step-ins come from the marks; reverts from the
+      // merged pull requests. When GitHub did not answer for a repo, the
+      // reverts read null, never 0 (R55 line 4).
+      // One read of the marks serves part 5 and part 6.
+      const markType = await typeNamed('mark');
+      const marks = await client.listAllEntities({ type: markType.name, state: 'active' });
+      const productMarks = marks.filter((row) => row.fields?.product === product);
+      const revertsKnown = !repoErrors.length;
+      const weeks = Array.from({ length: TREND_WEEKS }, (_, index) => ({ week: index + 1, from: dayOf(minus(readAt, (index + 1) * 7)), to: dayOf(minus(readAt, index * 7)), merged: 0, delivered: 0, new_items: 0, lessons: 0, repeats: 0, step_ins: 0, reverts: revertsKnown ? 0 : null }));
+      const bump = (at, key) => { const week = weekOf(at, readAt); if (week && weeks[week - 1][key] !== null) weeks[week - 1][key] += 1; };
       for (const pull of pulls) if (pull.state === 'merged') bump(pull.merged_at, 'merged');
+      for (const pull of pulls) if (pull.state === 'merged' && isRevert(pull)) bump(pull.merged_at, 'reverts');
       for (const row of flight.delivered ?? []) bump(row.delivered_at, 'delivered');
       for (const row of items) bump(row.created_at, 'new_items');
+      for (const mark of productMarks.filter((row) => row.fields?.kind === LESSON_KIND)) {
+        bump(mark.fields.marked_at, 'lessons');
+        if (mark.fields.repeats) bump(mark.fields.marked_at, 'repeats');
+      }
+      for (const mark of countedStepIns(productMarks)) bump(mark.fields.marked_at, 'step_ins');
       const oldest = needRows.reduce((max, row) => Math.max(max, row.days_waiting ?? 0), 0);
 
       // 6. The numbers. They read every pull request of the period, not only
       // the newest 100, and the marks of the tracker.
-      const markType = await typeNamed('mark');
-      const marks = await client.listAllEntities({ type: markType.name, state: 'active' });
       const numbers = await readNumbers({
         product, items, marks, period, readGitHub,
         repos: repoIds.map((id) => ({ id, default_branch: reg.repos.get(id)?.fields?.default_branch ?? null })),
@@ -241,7 +256,7 @@ function render(view) {
   out.push(stuck.join('\n'));
 
   out.push([`5. Trend, per week (week 1 is the last seven days)`,
-    ...weeks.map((week) => `   week ${week.week} (${week.from} to ${week.to}): ${plural(week.merged, 'merge')} · ${plural(week.delivered, 'delivery')} · ${plural(week.new_items, 'new item')}`),
+    ...weeks.map((week) => `   week ${week.week} (${week.from} to ${week.to}): ${plural(week.merged, 'merge')} · ${plural(week.delivered, 'delivery')} · ${plural(week.new_items, 'new item')} · ${plural(week.lessons, 'lesson')} (${plural(week.repeats, 'repeat')}) · ${plural(week.step_ins, 'step-in')} · ${week.reverts === null ? 'reverts unknown' : plural(week.reverts, 'revert')}`),
     `   waiting on you: ${plural(needRows.length, 'question')}${needRows.length ? `, oldest ${plural(oldest, 'day')}` : ''}`].join('\n'));
 
   out.push(renderNumbers(numbers, more));
@@ -251,7 +266,7 @@ function render(view) {
 }
 
 // Part 6. A refused count reads "refused", never 0.
-const COLUMNS = [['merges', 'merges'], ['not_on_green', 'not on green'], ['reverts', 'reverts'], ['unchecked_test_changes', 'unchecked test changes'], ['reopens', 'reopens'], ['step_ins', 'step-ins'], ['owner_messages', 'owner messages'], ['platform_messages', 'platform messages']];
+const COLUMNS = [['merges', 'merges'], ['not_on_green', 'not on green'], ['reverts', 'reverts'], ['unchecked_test_changes', 'unchecked test changes'], ['signed_acts', 'signed acts'], ['reopens', 'reopens'], ['step_ins', 'step-ins'], ['owner_messages', 'owner messages'], ['platform_messages', 'platform messages']];
 const countsLine = (row) => COLUMNS.map(([key, word]) => `${row[key] === null ? 'refused' : row[key]} ${word}`).join(' · ');
 function renderNumbers(numbers, more) {
   const out = [`6. The numbers, ${numbers.from} to ${numbers.to} (UTC)`];
@@ -269,7 +284,7 @@ function renderNumbers(numbers, more) {
   out.push(`   input to live: ${numbers.delivered.length} delivered ${numbers.delivered.length === 1 ? 'item' : 'items'}${median === null ? '' : `, median ${median} days`}`);
   for (const row of numbers.delivered.slice(0, SHOWN)) out.push(listLine(row.title, `${row.item.slice(0, 8)} · ${row.days ?? '?'} days · live ${dayOf(row.live_at)}`, '     '));
   out.push(...more(numbers.delivered));
-  out.push(`   owner acts: signed acts ${numbers.owner_acts.signed_acts}; unsigned merges ${numbers.owner_acts.audit_unsigned_merges}`);
+  out.push(`   owner acts: unsigned merges ${numbers.owner_acts.audit_unsigned_merges}`);
   if (numbers.not_counted_sessions) out.push(`   ${numbers.not_counted_sessions} sessions ran with the hooks off, so their messages were not counted`);
   return out.join('\n');
 }

package/work/lib/verbs.mjs

@@ -22,6 +22,7 @@ import { createCapabilityVerbs, CAPABILITY_READ_VERBS, hubOf } from './capabilit
 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';
+import { createLessonVerbs, LESSON_WRITE_VERBS, LESSON_READ_VERBS } from './lessons.mjs';
 
 export { VerbError, canonicalJson, sha256, COSTS, LIVE_LIFECYCLES, REPO_KINDS, LIVE_KINDS, repoKinds };
 export const MANIFEST_VERSION = '0.7.0';
@@ -754,9 +755,11 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
   // through record and notCounted, which no tool exposes.
   const stepIns = createStepInVerbs(core);
   Object.assign(verbs, stepIns.verbs);
+  // Roadmap R55: every lesson leaves one record, a mark of kind lesson.
+  Object.assign(verbs, createLessonVerbs(core));
 
-  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, ...ACTIVITY_WRITE_VERBS, ...STEP_IN_WRITE_VERBS]);
-  const READ_VERBS = Object.freeze(['registry_list', ...QUESTION_READ_VERBS, ...DELIVERY_READ_VERBS, ...CAPABILITY_READ_VERBS, ...ROUNDUP_READ_VERBS, ...ACTIVITY_READ_VERBS, ...STEP_IN_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, ...ACTIVITY_WRITE_VERBS, ...STEP_IN_WRITE_VERBS, ...LESSON_WRITE_VERBS]);
+  const READ_VERBS = Object.freeze(['registry_list', ...QUESTION_READ_VERBS, ...DELIVERY_READ_VERBS, ...CAPABILITY_READ_VERBS, ...ROUNDUP_READ_VERBS, ...ACTIVITY_READ_VERBS, ...STEP_IN_READ_VERBS, ...LESSON_READ_VERBS]);
 
   async function run(verb, args = {}) {
     if (!verbs[verb]) refuse(`unknown verb: ${verb}`);

package/work/mcp.mjs

@@ -23,6 +23,7 @@ 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 { LESSON_HOMES, LESSON_FORMS, LESSON_SOURCES } from './lib/lessons.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';
@@ -61,6 +62,8 @@ export const TOOLS = [
   { 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: 'lesson_record', description: `Record one lesson as a mark of kind lesson (roadmap R55): one line, its home, its form, the fix link, the source and the lesson it repeats. A mark is never edited. When: the learnings skill made the fix; call lessons first, and pass repeats when an earlier lesson says the same thing. The line goes through the secret filter. No owner flag. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'product', 'line', 'home', 'form', 'fix', 'source'], properties: { request_id: REQUEST_ID, product: S('Product id.'), line: S('The lesson in one plain sentence: what went wrong and what is right. At most 300 characters.'), home: { type: 'string', enum: [...LESSON_HOMES], description: 'repo: the lesson holds for one repo. atlas: it holds for every repo.' }, repo: S('For home repo: the registered repo id of this product.'), form: { type: 'string', enum: [...LESSON_FORMS], description: 'The form of the fix: a check, a tool, a skill step or a doc line.' }, fix: S('The fix: a pull request URL, or the id of the tracker item the lesson became.'), source: { type: 'string', enum: [...LESSON_SOURCES], description: 'What found the miss: owner (a correction), revert, bug (after a merge), or machine (no owner words).' }, source_ref: S('Where the miss shows: the step-in mark id, the revert pull request, or the bug issue.'), repeats: S('The id of an earlier lesson of this product that this lesson repeats.'), item_id: S('The work item the lesson is about.') }, additionalProperties: false } },
+  { name: 'lessons', description: 'List the lessons of one product, newest first (roadmap R55). Each row gives the line, the home, the form, the fix, the source, the lesson it repeats and the lessons that repeat it. total counts the lessons; repeats counts the repeats. A failed read is an error, never zero lessons. When: the learnings skill calls it before lesson_record, to find a match. Scope: read, no owner flag needed.', inputSchema: { type: 'object', required: ['product'], properties: { product: S('Product id.'), since: S('ISO date or time: only lessons 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: '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 } },
   { name: 'question_answer', description: `Record the owner's answer to one open question. One call writes the decision in the owner's words, keeps the rendered answer as a receipt, and closes the question, so the "Needs me" view loses the row. Refuses an unknown question and one that is already answered. Owner present only. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'question_id', 'text', 'date'], properties: { request_id: REQUEST_ID, question_id: S('Entity id of the open question.'), text: S("The owner's answer, verbatim."), date: S('ISO date the owner said it, in the form YYYY-MM-DD.'), source: S('Where the words are on record: a chat turn, a doc URL, an issue.'), kind: S(`One of ${DECISION_KINDS.join(', ')}. Default answer.`), items: { type: 'array', items: { type: 'string' }, description: 'Item ids the decision touches. Default: the question\'s item.' }, priority_order: { type: 'array', items: { type: 'string' }, description: 'Item ids in the order the owner set.' }, replaces: S('Entity id of the decision this one replaces.'), rendered: S('The view text the owner acted on. Default: the question and the answer.'), view: S('Which view the owner read, for example needs-me.') }, additionalProperties: false } },
@@ -216,6 +219,10 @@ export const GITHUB_READS = Object.freeze([
   new RegExp(`^repos/${REPO}/pulls/\\d{1,9}/files\\?per_page=\\d{1,3}&page=\\d{1,3}$`),
   // Roadmap R14 line 6: the newest run of the daily audit, for the roundup.
   new RegExp(`^repos/${REPO}/actions/workflows/atlas-jobs\\.yml/runs\\?per_page=\\d{1,3}$`),
+  // Roadmap R16 line 2: the comments of a merge, for the owner's signed act,
+  // and the owner key file at the first parent of the merge.
+  new RegExp(`^repos/${REPO}/issues/\\d{1,9}/comments\\?per_page=\\d{1,3}&page=\\d{1,3}$`),
+  new RegExp(`^repos/${REPO}/contents/atlas/owner-signers\\?ref=${SHA}$`),
 ]);
 export function githubReader() {
   return async (path) => {