@arjunkhera/atlas 0.4.49 → 0.4.51

package/work/lib/delivery.mjs

@@ -13,6 +13,7 @@
 //   3. Movement is read, never stored. The view computes it at question time
 //      from the marks and from the repos' pull requests (D3 rule 5, R1).
 import { refuse, text, isoDate, url, stringList, sha256, repoKinds, LIVE_KINDS } from './verb-fields.mjs';
+import { originShown, originNote, isRunnerItem } from './view-rules.mjs';
 import { oneLine, ROW_LINE_MAX, priorityOrderOf, byPriority, orderNote, waitsOnLine, blockersOf, blocksOf, blockedPhrase, waitsShown } from './questions.mjs';
 import { parseYaml } from '../../shape/check.mjs';
 import { ACTIONS_APP_ID } from '../../door/lib/gate.mjs';
@@ -584,7 +585,9 @@ export function createDeliveryVerbs(core) {
       const item = await requireItem(args.item_id);
       const fields = item.fields ?? {};
       const replay = alreadyPatched(item, requestId, meta);
-      if (!replay && fields.lifecycle !== 'active') refuse(`item ${item.id} is ${fields.lifecycle}; only an active item is marked done`);
+      // R22 line 5: a runner item stays proposed until its work merges, so
+      // it is marked from proposed. Its proof is the same.
+      if (!replay && fields.lifecycle !== 'active' && !isRunnerItem(fields)) refuse(`item ${item.id} is ${fields.lifecycle}; only an active item, or a proposed item of a runner, is marked done`);
       const reg = await registry();
       const product = await requireProduct(fields.product, reg);
       // A retry of an interrupted write finishes what landed, and it is read
@@ -893,7 +896,7 @@ export function createDeliveryVerbs(core) {
       const orders = new Map([...new Set(items.map((row) => row.fields.product))].map((productId) => [productId, priorityOrderOf(decisions, productId)]));
 
       const readAt = now();
-      const rows = [], delivered = [], notMarked = [];
+      const rows = [], delivered = [], notMarked = [], runnerDone = [];
       for (const item of items) {
         const fields = item.fields ?? {};
         const own = marks.get(item.id) ?? [];
@@ -919,32 +922,39 @@ export function createDeliveryVerbs(core) {
         // pull requests (its design, its lock) are history, not a gap; a
         // reopened item is active again, so its pull requests come back
         // (roadmap R70 line 5).
-        const inScope = fields.lifecycle === 'active';
+        // R22 line 4: a runner item stays proposed, because a routine moves
+        // no stage. Its stage comes from GitHub: an open pull request that
+        // names it reads as build, a merged one as verify.
+        const runner = isRunnerItem(fields);
+        const githubStage = runner ? (mine.some((pull) => pull.state === 'open') ? 'build' : merged.length ? 'verify' : null) : null;
+        const inScope = fields.lifecycle === 'active' || Boolean(runner && githubStage);
+        if (runner && open.length) runnerDone.push({ item: item.id, item_title: oneLine(item.title, 120), product: fields.product, prs: open.map((pull) => pull.url) });
         for (const pull of (inScope ? open : [])) notMarked.push({ item: item.id, item_title: oneLine(item.title, 120), product: fields.product, pr: pull.url, title: pull.title, merged_at: pull.merged_at, days: daysBetween(pull.merged_at, readAt), matched_by: pull.matched_by, note: 'merged, not marked' });
         for (const mark of deliveries) if (!since || String(mark.fields.marked_at ?? '') >= since) delivered.push({ item: item.id, item_title: oneLine(item.title, 120), product: fields.product, mark_id: mark.id, verdict: correctedBy.has(mark.id) ? 'corrected' : (mark.fields.verdict ?? 'delivered'), ...(correctedBy.has(mark.id) ? { corrected_by: correctedBy.get(mark.id) } : {}), delivered_at: mark.fields.marked_at, prs: (mark.fields.prs ?? []).map((pull) => pull.url), deployed_commit: mark.fields.deployed?.commit ?? null, gate_warnings: mark.fields.gate_warnings ?? [] });
         if (legacy && (!since || String(legacy.marked_at) >= since)) delivered.push({ item: item.id, item_title: oneLine(item.title, 120), product: fields.product, mark_id: null, verdict: 'legacy', delivered_at: legacy.marked_at, prs: [], deployed_commit: null, source: legacy.source });
 
         // D3 rule 1: in flight is active work. Delivered and paused items leave
         // the rows; what was delivered since a date has its own list.
-        if (fields.lifecycle !== 'active') continue;
+        if (!inScope) continue;
+        const stage = githubStage ?? fields.stage ?? '';
         const blockers = blockersOf(item, (id) => anyById.get(id));
         const blocks = blocksOf(item, all);
         const blocked = blockedPhrase(blockers, blocks);
         const waits = waitsShown(fields);
         rows.push({
-          item: item.id, product: fields.product, stage: fields.stage ?? '', driver: fields.driver ?? '', days_since_last_change: days,
+          item: item.id, product: fields.product, stage, ...(githubStage ? { stage_from: 'github', runner: true } : {}), driver: fields.driver ?? '', days_since_last_change: days,
           last_change_at: last?.at ?? null, last_change_source: last?.source ?? 'nothing recorded', delivery_state: state,
           lines: [
             // The id is what a reader types back, so the title gives way to it
             // inside the line budget, as the "Needs me" row does (review G6).
             oneLine(`${oneLine(item.title, Math.max(1, ROW_LINE_MAX - item.id.length - 3))} · ${item.id}`),
-            oneLine(`${fields.product} · ${fields.stage ?? 'no stage'} · ${fields.driver ?? 'no driver'}${waitsOnLine(waits) ? ` · ${waitsOnLine(waits)}` : ''} · next: ${fields.next_step || 'not set'}`),
-            oneLine(`${days === null ? 'no movement on record' : `${days} day${days === 1 ? '' : 's'} since last change`} (${last?.source ?? 'nothing recorded'}) · ${mine.length} pull request${mine.length === 1 ? '' : 's'}${open.length ? ` · ${open.length} merged, not marked` : ''}${orderNote(orders, { product: fields.product, item: item.id })}`),
+            oneLine(`${fields.product} · ${stage || 'no stage'}${githubStage ? ' (from GitHub, a runner item)' : ''} · ${fields.driver ?? 'no driver'}${waitsOnLine(waits) ? ` · ${waitsOnLine(waits)}` : ''} · next: ${fields.next_step || 'not set'}`),
+            oneLine(`${days === null ? 'no movement on record' : `${days} day${days === 1 ? '' : 's'} since last change`} (${last?.source ?? 'nothing recorded'}) · ${mine.length} pull request${mine.length === 1 ? '' : 's'}${open.length ? ` · ${open.length} merged, not marked` : ''}${originNote(fields.origin)}${orderNote(orders, { product: fields.product, item: item.id })}`),
             // The blockers get their own line, so a long list never cuts the
             // next step off line two; they come last.
             ...(blocked ? [oneLine(blocked)] : []),
           ],
-          waits_on: waits, blocked_by: blockers, blocks,
+          waits_on: waits, blocked_by: blockers, blocks, origin: originShown(fields.origin),
           folded: { title: item.title, next_step: fields.next_step ?? '', scope: fields.scope?.text ?? '', pieces: fields.split_children ?? [], prs: mine.map((pull) => ({ url: pull.url, state: pull.state, matched_by: pull.matched_by, merged_at: pull.merged_at, updated_at: pull.updated_at })), marks: own.map((mark) => ({ id: mark.id, kind: mark.fields.kind, verdict: mark.fields.verdict, at: mark.fields.marked_at })) },
           citation: { item: item.id, read_at: readAt, repos: [...new Set(mine.map((pull) => pull.repo))] },
         });
@@ -958,6 +968,9 @@ export function createDeliveryVerbs(core) {
       const products = [...new Set(rows.map((row) => row.product))].sort();
       const byProduct = products.map((product) => ({ product, rows: rows.filter((row) => row.product === product) }));
       const block = byProduct.map((group) => [`${group.product} — in flight (${group.rows.length})${orders.get(group.product) ? ` · in your order of ${orders.get(group.product).date}, then by the last change` : ''}`, ...group.rows.flatMap((row, index) => row.lines.map((line, position) => `${position === 0 ? `${index + 1}. ` : '   '}${line}`))].join('\n'));
+      // R22 line 5: the runner's merged work, for the lead to mark in one
+      // batch with item_done, which proves each merge as R17 says.
+      if (runnerDone.length) block.push([`runner deliveries to mark (${runnerDone.length}): call item_done for each`, ...runnerDone.map((row) => listLine(row.item_title, `${row.item} · ${row.prs.join(' ')}`))].join('\n'));
       if (notMarked.length) block.push([`merged, not marked (${notMarked.length})`, ...notMarked.map((row) => listLine(row.title, `${row.pr} · ${row.item} · merged ${row.days} day${row.days === 1 ? '' : 's'} ago`))].join('\n'));
       if (repoErrors.length) block.push([`GitHub did not answer for ${repoErrors.length} repo${repoErrors.length === 1 ? '' : 's'}; movement below is from the graph only`, ...repoErrors.map((row) => oneLine(`   ${row.repo} — ${row.reason}`, ROW_LINE_MAX))].join('\n'));
       if (unregisteredTotal && !only) {
@@ -976,7 +989,7 @@ export function createDeliveryVerbs(core) {
       return {
         verb: 'in_flight', read_at: readAt, product: only, since, rows: rows.length, products: byProduct,
         priority: Object.fromEntries([...orders].filter(([, order]) => order).map(([productId, order]) => [productId, { decision: order.decision, date: order.date }])),
-        merged_not_marked: notMarked, delivered: since ? delivered : delivered.slice(0, 20), unregistered, unregistered_total: unregisteredTotal, repos_read: repoIds, repo_errors: repoErrors,
+        merged_not_marked: notMarked, runner_deliveries: runnerDone, delivered: since ? delivered : delivered.slice(0, 20), unregistered, unregistered_total: unregisteredTotal, repos_read: repoIds, repo_errors: repoErrors,
         text: block.join('\n\n') || 'Nothing is in flight: no active item on a registered product.',
       };
     },

package/work/lib/questions.mjs

@@ -6,7 +6,7 @@
 // checks as slice L1. Every record carries request_id and writer.
 import protectedPaths from '../protected-paths.json' with { type: 'json' };
 import { refuse, text, oneOf, isoDate, url, stringList } from './verb-fields.mjs';
-import { COSTS, COST_MEANING, ROW_LINE_MAX, oneLine, needsYou } from './view-rules.mjs';
+import { COSTS, COST_MEANING, ROW_LINE_MAX, oneLine, needsYou, originShown } from './view-rules.mjs';
 
 // R5 (the costs), R8 (the row width), the blocker rules and the needs-you
 // order live in view-rules.mjs, which the project view page also runs.
@@ -282,7 +282,7 @@ export function createQuestionVerbs(core) {
       const kept = ordered.kept.map(({ question: row, item, lifecycle, cost, cost_rank: costRank }) => {
         const asked = row.fields.asked_by ?? {};
         return {
-          question_id: row.id, product: row.fields.product, item: item.id, item_lifecycle: lifecycle, cost, cost_rank: costRank,
+          question_id: row.id, product: row.fields.product, item: item.id, item_lifecycle: lifecycle, item_origin: originShown(item.fields?.origin), cost, cost_rank: costRank,
           asked_at: row.fields.asked_at ?? row.created_at ?? '', asked_by: asked.agent ?? 'unknown',
           lines: [
             oneLine(row.fields.text),

package/work/lib/roles.mjs

@@ -6,8 +6,8 @@
 // process, and a scheduled run carries the same variables as a project
 // thread. So the role comes from two things only:
 //   1. the key type, which gives the widest role: a user key gives lead, an
-//      agent key gives routine. Today the server starts with a user key
-//      only, so routine comes from the marker until R22 opens the agent key;
+//      agent key gives routine. R22 opened the agent key: the runner's
+//      own propose-only Engram key, which the owner mints;
 //   2. the launcher's marker ATLAS_WORK_ROLE, which can only narrow it.
 // No role is the owner. The lead writes down the owner's words; the owner's
 // own act is a signed act (R72), which the owner door reads (R27).
@@ -56,6 +56,9 @@ export const VERB_ROLES = Object.freeze({
 // The owner-only arguments: a verb that one role may call, with an argument
 // that only a narrower set of roles may pass. when says if a call holds it.
 export const ARGUMENT_ROLES = Object.freeze({
+  // R23: a routine names an input or an outside origin. The owner's words
+  // are the lead's to write down, so a routine never fakes them.
+  'item_propose.origin': { verb: 'item_propose', roles: LEAD, owner_words: true, name: 'a words origin', when: (args) => !(args.origin && typeof args.origin === 'object' && args.origin.kind && args.origin.kind !== 'words') },
   'item_edit.title': { verb: 'item_edit', roles: LEAD, owner_words: true, when: (args) => args.title !== undefined },
   'item_edit.plan': { verb: 'item_edit', roles: LEAD, owner_words: true, when: (args) => args.plan !== undefined },
   'item_comment.voice': { verb: 'item_comment', roles: LEAD, owner_words: true, name: '`voice: owner`', when: (args) => args.voice === 'owner' },

package/work/lib/roundup.mjs

@@ -23,6 +23,7 @@
 // Every row carries a citation: an item id, a question id or a pull request
 // URL. It is computed at read time and never stored.
 import { refuse, isoDate, LIVE_LIFECYCLES } from './verb-fields.mjs';
+import { originShown, shownNote } from './view-rules.mjs';
 import { oneLine, ROW_LINE_MAX } from './questions.mjs';
 import { readPullsByRepo, pullsOfItem, daysBetween, listLine } from './delivery.mjs';
 import { readNumbers, periodOf } from './numbers.mjs';
@@ -33,6 +34,23 @@ export const ROUNDUP_READ_VERBS = Object.freeze(['roundup']);
 // A free tag that places an item on its product's ladder. An item tagged
 // stage-2 is the stage 2 item or one of its parts.
 export const STAGE_TAG = /^stage-(\d{1,2})$/;
+// Roadmap R22 line 6: a tracker record that changed with no Atlas receipt
+// just before. Every Atlas write stamps a receipt; a write made straight to
+// Engram, by any key, does not. A record changed more than this long after
+// its newest receipt is listed. A record with no receipt at all is older
+// than the receipts, and is not listed.
+export const RECEIPT_GAP_MINUTES = 2;
+export function writesWithNoReceipt(rows) {
+  const out = [];
+  for (const row of rows) {
+    const times = Object.values(row.fields?.atlas_receipts ?? {}).map((receipt) => Date.parse(receipt?.at ?? '')).filter(Number.isFinite);
+    const changed = Date.parse(row.updated_at ?? '');
+    if (!times.length || !Number.isFinite(changed)) continue;
+    const last = Math.max(...times);
+    if (changed - last > RECEIPT_GAP_MINUTES * 60 * 1000) out.push({ item: row.id, title: oneLine(row.title ?? '', 120), updated_at: row.updated_at, last_receipt_at: new Date(last).toISOString() });
+  }
+  return out.sort((a, b) => String(b.updated_at).localeCompare(String(a.updated_at)));
+}
 export const STUCK_DAYS = 14;
 // Roadmap R14 done line 6: the daily audit runs in the watcher workflow. A
 // repo whose watcher has not run for this long is flagged in part 4.
@@ -166,7 +184,7 @@ export function createRoundupVerbs(core) {
       const deliveries = (flight.delivered ?? []).filter((row) => String(row.delivered_at) >= since)
         .map((row) => ({ item: row.item, title: row.item_title, verdict: row.verdict, delivered_at: row.delivered_at, prs: row.prs }));
       const created = items.filter((row) => String(row.created_at ?? '') >= since)
-        .map((row) => ({ item: row.id, title: oneLine(row.title, 120), lifecycle: row.fields?.lifecycle ?? 'unknown', created_at: row.created_at }))
+        .map((row) => ({ item: row.id, title: oneLine(row.title, 120), lifecycle: row.fields?.lifecycle ?? 'unknown', created_at: row.created_at, origin: originShown(row.fields?.origin) }))
         .sort((a, b) => String(b.created_at).localeCompare(String(a.created_at)));
 
       // 4. Stuck or drifting.
@@ -184,6 +202,8 @@ export function createRoundupVerbs(core) {
       const markType = await typeNamed('mark');
       const marks = await client.listAllEntities({ type: markType.name, state: 'active' });
       const productMarks = marks.filter((row) => row.fields?.product === product);
+      // R22 line 6: the items and the marks of the product.
+      const noReceipt = writesWithNoReceipt([...items, ...productMarks]);
       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; };
@@ -205,13 +225,13 @@ export function createRoundupVerbs(core) {
         repos: repoIds.map((id) => ({ id, default_branch: reg.repos.get(id)?.fields?.default_branch ?? null })),
       });
 
-      const text = render({ product, readAt, windowDays, needRows, ladder, lifecycles, active, merged, deliveries, created, stale, notMarked, openNoItem, longWaits, audits, weeks, oldest, repoErrors, numbers });
+      const text = render({ product, readAt, windowDays, needRows, ladder, lifecycles, active, merged, deliveries, created, stale, notMarked, openNoItem, longWaits, audits, noReceipt, weeks, oldest, repoErrors, numbers });
       return {
         verb: 'roundup', read_at: readAt, product, window_days: windowDays, since,
         needs_you: needRows,
         where_we_stand: { ladder, lifecycles, active },
         what_moved: { merged, delivered: deliveries, new_items: created },
-        stuck_or_drifting: { stale, merged_not_marked: notMarked, open_prs_with_no_item: openNoItem, long_waits: longWaits, stuck_days: STUCK_DAYS, audits_not_run: audits.stale, audits_unread: audits.unread, audit_stale_hours: AUDIT_STALE_HOURS },
+        stuck_or_drifting: { stale, merged_not_marked: notMarked, open_prs_with_no_item: openNoItem, long_waits: longWaits, written_with_no_receipt: noReceipt, stuck_days: STUCK_DAYS, audits_not_run: audits.stale, audits_unread: audits.unread, audit_stale_hours: AUDIT_STALE_HOURS },
         trend: { weeks, open_questions: needRows.length, oldest_question_days: oldest },
         numbers,
         repos_read: repoIds, repo_errors: repoErrors,
@@ -223,7 +243,7 @@ export function createRoundupVerbs(core) {
 }
 
 function render(view) {
-  const { product, readAt, windowDays, needRows, ladder, lifecycles, active, merged, deliveries, created, stale, notMarked, openNoItem, longWaits, audits = { stale: [], unread: [] }, weeks, oldest, repoErrors, numbers } = view;
+  const { product, readAt, windowDays, needRows, ladder, lifecycles, active, merged, deliveries, created, stale, notMarked, openNoItem, longWaits, audits = { stale: [], unread: [] }, noReceipt = [], weeks, oldest, repoErrors, numbers } = view;
   const more = (list) => (list.length > SHOWN ? [`   and ${list.length - SHOWN} more`] : []);
   const out = [`${product} — roundup, ${dayOf(readAt)}`];
 
@@ -243,7 +263,7 @@ function render(view) {
     ...deliveries.slice(0, SHOWN).map((row) => listLine(`delivered: ${row.title}`, `${row.item} · ${dayOf(row.delivered_at)}`)),
     ...merged.slice(0, SHOWN).map((row) => listLine(`merged: ${row.title}`, `${row.pr} · ${dayOf(row.merged_at)}${row.item ? '' : ' · no item'}`)),
     ...more(merged),
-    ...created.slice(0, SHOWN).map((row) => listLine(`new: ${row.title}`, `${row.item} · ${row.lifecycle}`)),
+    ...created.slice(0, SHOWN).map((row) => listLine(`new: ${row.title}`, `${row.item} · ${row.lifecycle}${shownNote(row.origin)}`)),
     ...more(created)].join('\n'));
 
   const stuck = [`4. Stuck or drifting`];
@@ -253,6 +273,7 @@ function render(view) {
   stuck.push(`   questions waiting ${STUCK_DAYS} days or more (${longWaits.length})`, ...longWaits.slice(0, SHOWN).map((row) => listLine(row.text, `${row.question} · ${row.days_waiting} days`, '     ')));
   stuck.push(`   audits with no run in ${AUDIT_STALE_HOURS} hours (${audits.stale.length})`, ...audits.stale.slice(0, SHOWN).map((row) => listLine(row.repo, row.last_run_at ? `last run ${row.last_run_at}, ${row.hours} hours` : 'no run yet', '     ')));
   for (const row of audits.unread.slice(0, SHOWN)) stuck.push(listLine(row.repo, row.reason, '     '));
+  stuck.push(`   records written with no Atlas receipt (${noReceipt.length})`, ...noReceipt.slice(0, SHOWN).map((row) => listLine(row.title, `${row.item} · changed ${row.updated_at}, last receipt ${row.last_receipt_at}`, '     ')));
   out.push(stuck.join('\n'));
 
   out.push([`5. Trend, per week (week 1 is the last seven days)`,

package/work/lib/verb-fields.mjs

@@ -41,6 +41,63 @@ export function origin(value) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) refuse('origin must be an object with text, source and date, in the owner\'s words');
   return { text: text(value.text, 'origin.text'), source: text(value.source, 'origin.source', { max: 500 }), date: isoDate(value.date, 'origin.date') };
 }
+// Roadmap R23: the three kinds of origin an item may have.
+//   words    the owner's words: { text, source, date }. Old records carry no
+//            kind, and read as words.
+//   input    a typed input that code found, such as a watcher issue:
+//            { kind, url, key, date }, and no prose.
+//   outside  prose that a person or an agent wrote, in an issue body or a
+//            comment, under any login: { kind, url, from, date }, and no
+//            prose. The text stays on GitHub; the tracker keeps the link.
+// Only the lead may write the owner's words (roles.mjs), so a routine names
+// an input or outside origin and never fakes his words.
+export const ORIGIN_KINDS = Object.freeze(['words', 'input', 'outside']);
+export const OUTSIDE_FROM = Object.freeze(['issue', 'comment']);
+const INPUT_KEY = /^[A-Za-z0-9][A-Za-z0-9._:@/#=+-]{0,199}$/;
+export const originKind = (value) => (value && typeof value === 'object' && value.kind ? value.kind : 'words');
+
+export function itemOrigin(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) refuse('origin must be an object: the owner\'s words { text, source, date }, or { kind: "input", url, key, date }, or { kind: "outside", url, from, date }');
+  const kind = oneOf(value.kind, 'origin.kind', ORIGIN_KINDS, 'words');
+  if (kind === 'words') {
+    if (value.kind !== undefined) refuse('origin.kind words is the default: leave kind out, and give text, source and date');
+    return origin(value);
+  }
+  const allowed = kind === 'input' ? ['kind', 'url', 'key', 'date'] : ['kind', 'url', 'from', 'date'];
+  const extra = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (extra.length) refuse(`an origin of kind ${kind} holds no prose and no other field; it takes only ${allowed.join(', ')}, not ${extra.join(', ')}`);
+  const shaped = { kind, url: url(value.url, 'origin.url') };
+  if (kind === 'input') {
+    const key = text(value.key, 'origin.key', { max: 200 });
+    if (!INPUT_KEY.test(key)) refuse('origin.key must be one typed key with no spaces, for example red-main:checks.yml@a1b2c3d');
+    shaped.key = key;
+  } else {
+    shaped.from = oneOf(value.from, 'origin.from', OUTSIDE_FROM);
+  }
+  shaped.date = isoDate(value.date, 'origin.date');
+  return shaped;
+}
+
+// The tag that marks one input URL (R23 line 3). The tracker owns it: no
+// caller adds it or takes it off. The hash is of the URL in one form: no
+// slash at the end, and on github.com, where names have no case, no capitals.
+export const INPUT_TAG_PREFIX = 'input:';
+export function sameUrl(address) {
+  const parsed = new URL(String(address).trim());
+  parsed.pathname = parsed.pathname.replace(/\/+$/, '') || '/';
+  if (parsed.hostname === 'github.com') parsed.pathname = parsed.pathname.toLowerCase();
+  return parsed.toString();
+}
+export const inputTag = (address) => `${INPUT_TAG_PREFIX}${sha256(sameUrl(address)).slice(0, 16)}`;
+
+// R23 line 4: an item from outside text never starts by policy. The policy
+// door (R27) calls this; only a signed ready mark of the owner starts such
+// an item (R72), and item_lock checks that mark.
+export function startsByPolicy(fields) {
+  if (originKind(fields?.origin) === 'outside') return { ok: false, why: 'the item came from outside text; only the owner\'s signed ready mark starts it' };
+  return { ok: true };
+}
+
 export function url(value, name) {
   text(value, name, { max: 2000 });
   let parsed;

package/work/lib/verbs.mjs

@@ -15,7 +15,7 @@
 // additions add entry, the log of an item, in 0.7.0.
 import manifestCurrent from '../manifest-0.7.0.json' with { type: 'json' };
 import { EngramHttpError } from './client.mjs';
-import { VerbError, refuse, canonicalJson, sha256, text, oneOf, origin, url, stringList, LIVE_LIFECYCLES, REPO_KINDS, LIVE_KINDS, repoKinds, kindsFromArgs } from './verb-fields.mjs';
+import { VerbError, refuse, canonicalJson, sha256, text, oneOf, origin, itemOrigin, originKind, inputTag, INPUT_TAG_PREFIX, url, stringList, LIVE_LIFECYCLES, REPO_KINDS, LIVE_KINDS, repoKinds, kindsFromArgs } from './verb-fields.mjs';
 import { createQuestionVerbs, COSTS, QUESTION_WRITE_VERBS, QUESTION_READ_VERBS, oneLine, scrubSecrets } from './questions.mjs';
 import { createDeliveryVerbs, DELIVERY_WRITE_VERBS, DELIVERY_READ_VERBS } from './delivery.mjs';
 import { createCapabilityVerbs, CAPABILITY_READ_VERBS, hubOf } from './capability.mjs';
@@ -24,9 +24,14 @@ import { createActivityVerbs, diffOf, LOG_VERBS, ENTRY_VERBS, ACTIVITY_WRITE_VER
 import { createStepInVerbs, STEP_IN_WRITE_VERBS, STEP_IN_READ_VERBS } from './step-ins.mjs';
 import { ROLES, allow } from './roles.mjs';
 import { createLessonVerbs, LESSON_WRITE_VERBS, LESSON_READ_VERBS } from './lessons.mjs';
+import { parseYaml } from '../../shape/check.mjs';
+import { MARKER as SIGNED_MARKER, SIGNERS_FILE, parseSigners, verifyTexts, findAct } from '../../door/lib/signed-act.mjs';
 
 export { VerbError, canonicalJson, sha256, COSTS, LIVE_LIFECYCLES, REPO_KINDS, LIVE_KINDS, repoKinds };
 export const MANIFEST_VERSION = '0.7.0';
+// R23 line 7: the default weekly cap on the items a routine proposes.
+export const AGENT_PROPOSALS_PER_WEEK = 10;
+const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
 export const PRODUCT_ID = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
 export const REPO_ID = /^[A-Za-z0-9](?:[A-Za-z0-9_.-]{0,99})\/[A-Za-z0-9_.-]{1,100}$/;
 export const STAGES = Object.freeze(['capture', 'spec', 'build', 'verify', 'learn']);
@@ -68,7 +73,7 @@ export function trimReceipts(fields, receipts, logged = new Set(), keep = null)
 }
 // The tags that other verbs own (work item additions, slice 1). item_edit
 // never adds or removes them; item_propose drops them from the caller's list.
-export const OWNED_TAG_PREFIXES = Object.freeze(['product:', 'repo:', 'tier:', 'item:']);
+export const OWNED_TAG_PREFIXES = Object.freeze(['product:', 'repo:', 'tier:', 'item:', INPUT_TAG_PREFIX]);
 export const OWNED_TAGS = Object.freeze(['atlas-work', 'no-model', 'atlas-registry']);
 // Engram reads no-model with the spaces trimmed and in any case, so the check
 // does the same: No-Model is owned too.
@@ -89,7 +94,7 @@ const planDate = (value, name) => {
 const tagList = (value, name) => stringList(value, name, { max: 16 }).map((tag) => {
   text(tag, name, { max: 100 });
   if (tag !== tag.trim()) refuse(`${name} holds a tag with spaces at its start or end: "${tag}"`);
-  if (isOwnedTag(tag)) { const plain = tag.toLowerCase(); refuse(`${tag} is owned by the tracker; ${plain.startsWith('product:') || plain.startsWith('repo:') ? 'change the product or repos with item_lock' : plain.startsWith('tier:') ? 'change the tier with item_lock' : 'no verb removes it'}`); }
+  if (isOwnedTag(tag)) { const plain = tag.toLowerCase(); refuse(`${tag} is owned by the tracker; ${plain.startsWith('product:') || plain.startsWith('repo:') ? 'change the product or repos with item_lock' : plain.startsWith('tier:') ? 'change the tier with item_lock' : plain.startsWith(INPUT_TAG_PREFIX) ? 'item_propose sets it from an input URL' : 'no verb removes it'}`); }
   return tag;
 });
 export const LINK_KINDS = Object.freeze(['pr', 'issue', 'artifact', 'design-doc', 'conversation', 'research', 'slack', 'drive', 'other']);
@@ -268,6 +273,56 @@ export function createVerbs({ client, store, writer, session, agent, role, roleF
   };
   const alreadyPatched = (entity, requestId, meta) => sameRequest(entity.fields?.atlas_receipts?.[requestId], requestId, meta);
 
+  // R23 line 7: the proposals a routine makes stop at a weekly cap, so they
+  // never pass what the owner can read in a week (TD:627-630). atlas.yaml of
+  // the item's first repo sets it with agent_proposals_per_week; a repo with
+  // no such key, or a file GitHub does not give, keeps the default.
+  async function weeklyCapOf(repo) {
+    if (!repo || typeof readGitHub !== 'function') return AGENT_PROPOSALS_PER_WEEK;
+    let file = null;
+    try { file = await readGitHub(`repos/${repo.fields.registry_id}/contents/atlas.yaml?ref=${repo.fields.default_branch ?? 'HEAD'}`); } catch { return AGENT_PROPOSALS_PER_WEEK; }
+    if (!file || typeof file.content !== 'string') return AGENT_PROPOSALS_PER_WEEK;
+    let doc;
+    try { doc = parseYaml(Buffer.from(file.content, 'base64').toString('utf8')); } catch { return AGENT_PROPOSALS_PER_WEEK; }
+    const value = Number(doc?.agent_proposals_per_week);
+    return Number.isInteger(value) && value >= 0 ? value : AGENT_PROPOSALS_PER_WEEK;
+  }
+  // R23 line 4: the owner's signed ready mark for an outside item: a ready
+  // act (R72) that names the issue's repo and the item, posted on the issue
+  // the item came from, and signed with a key of atlas/owner-signers on the
+  // repo's default branch.
+  async function readyMark(item) {
+    const address = String(item.fields?.origin?.url ?? '');
+    const match = /^https:\/\/github\.com\/([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)\/(?:issues|pull)\/([1-9][0-9]{0,8})(?:[#?].*)?$/.exec(address);
+    if (!match) refuse(`item ${item.id} came from outside text, and only the owner's signed ready mark on its GitHub issue starts it; its origin names no GitHub issue (${address || 'no url'})`);
+    if (typeof readGitHub !== 'function') refuse(`item ${item.id} came from outside text; reading the owner's ready mark needs a GitHub reader`);
+    const [, repo, number] = match;
+    const read = async (path) => { try { return await readGitHub(path); } catch (error) { refuse(`GitHub could not read ${path}: ${error?.message ?? 'unknown error'}`); } };
+    const branch = (await read(`repos/${repo}`))?.default_branch;
+    if (typeof branch !== 'string' || !/^[A-Za-z0-9._/-]{1,100}$/.test(branch)) refuse(`GitHub names no default branch of ${repo}`);
+    let file = null;
+    try { file = await readGitHub(`repos/${repo}/contents/${SIGNERS_FILE}?ref=${branch}`); } catch { file = null; }
+    const keys = parseSigners(file && typeof file.content === 'string' ? Buffer.from(file.content, 'base64').toString('utf8') : '').keys;
+    if (!keys.length) refuse(`item ${item.id} came from outside text and needs the owner's signed ready mark, and ${SIGNERS_FILE} of ${repo} holds no owner key`);
+    const texts = [];
+    for (let page = 1; page <= 10; page += 1) {
+      const rows = await read(`repos/${repo}/issues/${number}/comments?per_page=100&page=${page}`);
+      for (const row of Array.isArray(rows) ? rows : []) if (typeof row?.body === 'string' && row.body.includes(SIGNED_MARKER)) texts.push(row.body);
+      if (!Array.isArray(rows) || rows.length < 100) break;
+    }
+    const found = findAct(verifyTexts(texts, keys), { kind: 'ready', repo, item: item.id });
+    if (!found) refuse(`item ${item.id} came from outside text; it starts only with the owner's signed ready mark. Ask him to run: atlas approve act ready --repo ${repo} --item ${item.id}, and to post the block as a comment on ${address}`);
+    return { repo, issue: Number(number), signed_at: found.signed_at ?? null };
+  }
+  const proposedAt = (row) => Object.values(row.fields?.atlas_receipts ?? {}).find((receipt) => receipt?.verb === 'item_propose')?.at ?? row.created_at ?? '';
+  async function underWeeklyCap(all, repo) {
+    const cap = await weeklyCapOf(repo);
+    const since = new Date(Date.parse(now()) - WEEK_MS).toISOString();
+    const name = repo?.fields?.registry_id;
+    const count = all.filter((row) => row.fields?.proposed_by?.role === 'routine' && (!name || (row.fields?.repos ?? []).includes(name)) && String(proposedAt(row)) >= since).length;
+    if (count >= cap) refuse(`a routine may propose at most ${cap} item${cap === 1 ? '' : 's'} a week for ${name ?? 'this repo'}, and ${count} came in the last 7 days. Set agent_proposals_per_week in atlas.yaml to change the cap`);
+  }
+
   const verbs = {
     async setup(args) {
       const publisherHandle = await handle();
@@ -430,16 +485,30 @@ export function createVerbs({ client, store, writer, session, agent, role, roleF
       const reg = await registry();
       const product = await requireProduct(args.product, reg);
       const repos = await requireRepos(args.repos, reg, product.fields.registry_id);
+      const shapedOrigin = itemOrigin(args.origin);
       const fields = {
         lifecycle: 'proposed', stage: 'capture', product: product.fields.registry_id, repos, tier: oneOf(args.tier, 'tier', TIERS, 'standard'),
-        origin: origin(args.origin), driver: oneOf(args.driver, 'driver', DRIVERS, 'owner-led'), next_step: text(args.next_step, 'next_step', { optional: true, max: 1000 }) ?? '',
+        origin: shapedOrigin, driver: oneOf(args.driver, 'driver', DRIVERS, 'owner-led'), next_step: text(args.next_step, 'next_step', { optional: true, max: 1000 }) ?? '',
         summary: text(args.summary, 'summary', { optional: true, max: 4000 }) ?? '', external_refs: [], links: [],
+        // R23 line 7: who proposed it. The writer stamp changes with each
+        // write, so the weekly cap reads this field instead.
+        proposed_by: { role: label.role, agent: label.agent },
       };
       const type = await typeNamed('container');
       const prior = await landed(type, requestId, meta);
       if (prior) return { verb: 'item_propose', item_id: prior.id, version: prior.version, lifecycle: prior.fields.lifecycle, stage: prior.fields.stage, product: prior.fields.product, repos: prior.fields.repos, replayed_from_graph: true };
-      const entity = await create(type, requestId, 'item_propose', { change: { created: { from: null, to: scrubSecrets(oneLine(title, 300)).text } }, digest: meta?.digest, title, body: args.body ? text(args.body, 'body') : undefined, fields, tags: [`product:${product.fields.registry_id}`, ...repos.map((id) => `repo:${id}`), `tier:${fields.tier}`, ...(args.tags ? stringList(args.tags, 'tags', { max: 16 }).filter((tag) => !isOwnedTag(tag)) : [])] });
-      return { verb: 'item_propose', item_id: entity.id, version: entity.version, lifecycle: 'proposed', stage: 'capture', product: fields.product, repos };
+      // R23 lines 3 and 5: an input or outside origin names one URL, and one
+      // URL has one open item. A second proposal writes nothing.
+      const tag = shapedOrigin.url ? inputTag(shapedOrigin.url) : null;
+      let all = null;
+      const items = async () => (all ??= await client.listAllEntities({ type: type.name, state: 'any' }));
+      if (tag) {
+        const open = (await items()).find((row) => Array.isArray(row.tags) && row.tags.includes(tag) && LIVE_LIFECYCLES.includes(row.fields?.lifecycle));
+        if (open) return { verb: 'item_propose', item_id: open.id, duplicate_of: open.id, written: false, lifecycle: open.fields.lifecycle, stage: open.fields.stage, product: open.fields.product, repos: open.fields.repos };
+      }
+      if (label.role === 'routine') await underWeeklyCap(await items(), reg.repos.get(repos[0]));
+      const entity = await create(type, requestId, 'item_propose', { change: { created: { from: null, to: scrubSecrets(oneLine(title, 300)).text } }, digest: meta?.digest, title, body: args.body ? text(args.body, 'body') : undefined, fields, tags: [`product:${product.fields.registry_id}`, ...repos.map((id) => `repo:${id}`), `tier:${fields.tier}`, ...(tag ? [tag] : []), ...(args.tags ? stringList(args.tags, 'tags', { max: 16 }).filter((one) => !isOwnedTag(one)) : [])] });
+      return { verb: 'item_propose', item_id: entity.id, version: entity.version, lifecycle: 'proposed', stage: 'capture', product: fields.product, repos, origin_kind: originKind(fields.origin) };
     },
 
     async item_lock(args, requestId, meta) {
@@ -461,9 +530,16 @@ export function createVerbs({ client, store, writer, session, agent, role, roleF
       if (args.scope.design_doc !== undefined) scope.design_doc = url(args.scope.design_doc, 'scope.design_doc');
       const scopeHash = sha256(scope.text);
       const stage = oneOf(args.stage, 'stage', STAGES, fields.lifecycle === 'active' && fields.stage ? fields.stage : 'build');
+      // R23: the lock is the owner's words. An item from an input or from
+      // outside text keeps that origin, so the views still say where it came
+      // from; the words of the lock go beside it. An outside item starts only
+      // with the owner's signed ready mark on its issue (R23 line 4, R72).
+      const words = origin(args.origin);
+      const typed = originKind(fields.origin) !== 'words';
+      const ready = originKind(fields.origin) === 'outside' ? await readyMark(item) : null;
       const change = {
         lifecycle: 'active', stage, product: product.fields.registry_id, repos, tier: oneOf(args.tier, 'tier', TIERS, fields.tier ?? 'standard'),
-        scope, scope_hash: scopeHash, origin: origin(args.origin), locked_at: now(),
+        scope, scope_hash: scopeHash, origin: typed ? fields.origin : words, ...(typed ? { lock_words: words } : {}), ...(ready ? { ready_mark: ready } : {}), locked_at: now(),
         driver: oneOf(args.driver, 'driver', DRIVERS, fields.driver ?? 'owner-led'), next_step: text(args.next_step, 'next_step', { optional: true, max: 1000 }) ?? fields.next_step ?? '',
         links: Array.isArray(fields.links) ? fields.links : [],
       };

package/work/lib/view-rules.mjs

@@ -11,6 +11,25 @@
 // The lifecycles a view counts as live work (release 0.2.3). A dropped item
 // is closed by the owner's word, and no live list names it.
 export const LIVE_LIFECYCLES = Object.freeze(['proposed', 'active', 'paused']);
+
+// Roadmap R23 line 6: where an item came from, as the views show it. The
+// owner's words, an input that code found, or outside text. An old record
+// carries no kind, and reads as the owner's words.
+export function originShown(value) {
+  if (!value || typeof value !== 'object') return { kind: 'none', label: 'no origin on record' };
+  if (value.kind === 'input') return { kind: 'input', url: value.url ?? '', key: value.key ?? '', date: value.date ?? '', label: `input ${value.key ?? ''} · ${value.url ?? ''}` };
+  if (value.kind === 'outside') return { kind: 'outside', url: value.url ?? '', from: value.from ?? '', date: value.date ?? '', label: `outside text (${value.from ?? 'issue'}) · ${value.url ?? ''}` };
+  return { kind: 'words', source: value.source ?? '', date: value.date ?? '', label: `the owner's words · ${value.source ?? ''}` };
+}
+// The short note a row line carries for an item that did not come from the
+// owner's words.
+export const shownNote = (shown) => (shown?.kind === 'input' ? ' · from an input' : shown?.kind === 'outside' ? ' · from outside text' : '');
+export const originNote = (value) => shownNote(originShown(value));
+// Roadmap R22: an item a routine proposed, which stays proposed because a
+// routine moves no stage. The views read its stage from GitHub.
+// An item from outside text is never one: it starts only with the owner's
+// signed ready mark and a lock (R23 line 4).
+export const isRunnerItem = (fields) => fields?.lifecycle === 'proposed' && fields?.proposed_by?.role === 'routine' && fields?.origin?.kind !== 'outside';
 // A blocker that is delivered or dropped no longer blocks.
 export const CLEARED_LIFECYCLES = Object.freeze(['done', 'dropped']);
 // R5: the cost of waiting is a closed vocabulary, ranked. Index 0 costs most.

package/work/mcp.mjs

@@ -34,6 +34,9 @@ export { childEnvironment };
 const ATLAS_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 const S = (description, extra = {}) => ({ type: 'string', description, ...extra });
 const ORIGIN = { type: 'object', description: "The owner's words, verbatim, with where and when they were said.", required: ['text', 'source', 'date'], properties: { text: S('Verbatim words of the owner.'), source: S('Where the words are on record: a chat turn, a doc URL, an issue.'), date: S('ISO date, in the form YYYY-MM-DD.') } };
+// Roadmap R23: the origin of a new item. The owner's words, or a typed
+// input that code found, or outside text. The last two hold no prose.
+const ITEM_ORIGIN = { type: 'object', description: "Where the item came from. Give one of three shapes. The owner's words: text, source and date, with no kind; only the lead writes these. An input that code found, such as a watcher issue: kind \"input\", url, key and date. Outside text, an issue body or a comment under any login: kind \"outside\", url, from (issue or comment) and date. An input or outside origin holds no prose. One URL has one open item: a second proposal writes nothing and returns duplicate_of. A routine stops at the weekly cap that agent_proposals_per_week in atlas.yaml sets, 10 by default.", properties: { kind: S('One of words (the default), input, outside.'), text: S('Words only: the verbatim words of the owner.'), source: S('Words only: where the words are on record.'), url: S('Input and outside only: the absolute URL of the issue or comment.'), key: S('Input only: one typed key with no spaces, for example red-main:checks.yml@a1b2c3d.'), from: S('Outside only: issue or comment.'), date: S('ISO date, in the form YYYY-MM-DD.') } };
 const REQUEST_ID = S('Stable unique id for this request. A retry with the same id and the same arguments is a no-op that returns the first receipt. The same id with different arguments is refused.');
 const KINDS = { type: 'array', items: { type: 'string', enum: [...REPO_KINDS] }, description: `What the repo is, as a list: one or more of ${REPO_KINDS.join(', ')}. A service or a schema repo keeps the live checks of item_done; a library, a cli and a plugin are proved by the merge.` };
 const RULES = 'Rules: every write needs request_id. Never pass writer, session, actor or role; the server stamps them. Unknown product or repo ids are refused.';
@@ -49,13 +52,13 @@ const TOOL_LIST = [
   { name: 'product_edit', description: `Change a product's name, notes, health endpoint, check paths, design hub link or project link. Refuses an unknown id. The registry id never changes. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'registry_id'], properties: { request_id: REQUEST_ID, registry_id: S('Existing product id.'), name: S('New display name.'), project_id: S('Entity id of an Engram project entity.'), health_url: S('Absolute https URL of the deployed app\'s health endpoint.'), check_paths: { type: 'array', items: { type: 'string' }, description: 'Absolute paths the functional check of item_done may read on that origin.' }, design_hub_url: S('Absolute https URL of the one pinned "Design docs" hub page. Set it once, on any product; registry_list and design_index return it.'), notes: S('Free text.') }, additionalProperties: false } },
   { name: 'repo_add', description: `Register a GitHub repo under a product. The server reads GitHub itself: the id must equal the repo's full name and the owner must have push rights, or the add is refused. The default branch comes from GitHub. The kinds say what the repo is; item_done reads them to choose how a delivery is proved. Give kinds, a list; kind, one value, is the older form. Refuses an unknown product id and an existing repo id; repo ids are immutable. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'registry_id', 'product'], properties: { request_id: REQUEST_ID, registry_id: S('GitHub "owner/repo", exact spelling.'), product: S('Existing product id.'), kinds: KINDS, kind: S(`The older form: one kind. One of ${REPO_KINDS.join(', ')}. Give kinds instead.`), notes: S('Free text.') }, additionalProperties: false } },
   { name: 'repo_edit', description: `Change a repo's kinds or notes, or refresh its default branch from GitHub. registry_id and product never change. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'registry_id'], properties: { request_id: REQUEST_ID, registry_id: S('Existing repo id.'), kinds: KINDS, kind: S(`The older form: one kind. One of ${REPO_KINDS.join(', ')}. Give kinds instead.`), notes: S('Free text.'), refresh_default_branch: { type: 'boolean', description: 'Re-read the default branch and push rights from GitHub.' } }, additionalProperties: false } },
-  { name: 'item_propose', description: `Create a proposed work item (lifecycle proposed, stage capture) for a product, with its repos and the owner's words as origin. When: the owner names a piece of work that is not yet locked. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'title', 'product', 'repos', 'origin'], properties: { request_id: REQUEST_ID, title: S('Short title in the owner\'s words.'), product: S('Product id.'), repos: { type: 'array', items: { type: 'string' }, description: 'Repo ids under that product.' }, origin: ORIGIN, tier: S(`One of ${TIERS.join(', ')}. Default standard.`), driver: S(`One of ${DRIVERS.join(', ')}. Default owner-led.`), next_step: S('One line: what happens next.'), summary: S('Short summary.'), body: S('Longer body, optional.'), tags: { type: 'array', items: { type: 'string' } } }, additionalProperties: false } },
-  { name: 'item_lock', description: `Record the owner's approval of a short design: product and repos by registry id, the scope (the definition of done as text, and the design file), and the owner's words of approval as origin. That approval is the lock (target design, flow 4). The verb keeps a fingerprint of the text for the tools; nobody reads or writes a hash. Lifecycle becomes active; stage defaults to build. Refuses an unknown product or repo id, a missing scope or origin, and an item that is already locked; a change after approval is a decision_record on the same item. When: the owner approves the design. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'item_id', 'product', 'repos', 'scope', 'origin'], properties: { request_id: REQUEST_ID, item_id: S('Entity id of the work item (container).'), product: S('Product id.'), repos: { type: 'array', items: { type: 'string' }, description: 'Repo ids under that product.' }, scope: { type: 'object', required: ['text'], properties: { text: S('The definition of done, in full.'), design_doc: S('URL of the design file the owner approved.'), acceptance_criteria_hash: S('Refused: old records only. A new lock takes no hash; put the definition of done in text.') } }, origin: ORIGIN, tier: S(`One of ${TIERS.join(', ')}.`), stage: S(`One of ${STAGES.join(', ')}. Default build.`), driver: S(`One of ${DRIVERS.join(', ')}.`), next_step: S('One line: what happens next.') }, additionalProperties: false } },
+  { name: 'item_propose', description: `Create a proposed work item (lifecycle proposed, stage capture) for a product, with its repos and its origin: the owner's words, or a typed input or outside URL (roadmap R23). When: the owner names a piece of work that is not yet locked, or a routine files a watcher issue. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'title', 'product', 'repos', 'origin'], properties: { request_id: REQUEST_ID, title: S('Short title in the owner\'s words.'), product: S('Product id.'), repos: { type: 'array', items: { type: 'string' }, description: 'Repo ids under that product.' }, origin: ITEM_ORIGIN, tier: S(`One of ${TIERS.join(', ')}. Default standard.`), driver: S(`One of ${DRIVERS.join(', ')}. Default owner-led.`), next_step: S('One line: what happens next.'), summary: S('Short summary.'), body: S('Longer body, optional.'), tags: { type: 'array', items: { type: 'string' } } }, additionalProperties: false } },
+  { name: 'item_lock', description: `Record the owner's approval of a short design: product and repos by registry id, the scope (the definition of done as text, and the design file), and the owner's words of approval as origin. That approval is the lock (target design, flow 4). The verb keeps a fingerprint of the text for the tools; nobody reads or writes a hash. Lifecycle becomes active; stage defaults to build. Refuses an unknown product or repo id, a missing scope or origin, and an item that is already locked; a change after approval is a decision_record on the same item. An item from an input or from outside text keeps that origin, and the words of the lock go beside it. An item from outside text locks only with the owner's signed ready mark (atlas approve act ready), posted as a comment on its issue and signed with a key of atlas/owner-signers on the repo's default branch (roadmap R23 line 4). When: the owner approves the design. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'item_id', 'product', 'repos', 'scope', 'origin'], properties: { request_id: REQUEST_ID, item_id: S('Entity id of the work item (container).'), product: S('Product id.'), repos: { type: 'array', items: { type: 'string' }, description: 'Repo ids under that product.' }, scope: { type: 'object', required: ['text'], properties: { text: S('The definition of done, in full.'), design_doc: S('URL of the design file the owner approved.'), acceptance_criteria_hash: S('Refused: old records only. A new lock takes no hash; put the definition of done in text.') } }, origin: ORIGIN, tier: S(`One of ${TIERS.join(', ')}.`), stage: S(`One of ${STAGES.join(', ')}. Default build.`), driver: S(`One of ${DRIVERS.join(', ')}.`), next_step: S('One line: what happens next.') }, additionalProperties: false } },
   { name: 'item_split', description: `Split an item into pieces. Each child is a proposed item (stage capture) with a spun_out_of relation to the parent and the reason. Children inherit product, repos, tier, origin and driver unless given. Refuses an unknown parent, a missing reason, or a child repo outside the product. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'item_id', 'reason', 'children'], properties: { request_id: REQUEST_ID, item_id: S('Parent item id.'), reason: S('Why the split, in the owner\'s words.'), children: { type: 'array', items: { type: 'object', required: ['title'], properties: { title: S('Child title.'), repos: { type: 'array', items: { type: 'string' } }, tier: S(`One of ${TIERS.join(', ')}.`), origin: ORIGIN, driver: S(`One of ${DRIVERS.join(', ')}.`), next_step: S('One line.'), summary: S('Short summary.') } } } }, additionalProperties: false } },
   { name: 'item_park', description: `Park an item: lifecycle paused with the reason. Paused items are backlog: the in_flight rows leave them out, and needs_me still shows their open questions. Refuses a missing reason. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'item_id', 'reason'], properties: { request_id: REQUEST_ID, item_id: S('Item id.'), reason: S('Why it is parked.') }, additionalProperties: false } },
   { name: 'item_resume', description: `Resume a parked item to its earlier lifecycle with a reason. It also undoes a drop: a dropped item goes back to the lifecycle it left, and the drop's words stay on it. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'item_id', 'reason'], properties: { request_id: REQUEST_ID, item_id: S('Item id.'), reason: S('Why it resumes.') }, additionalProperties: false } },
   { name: 'item_drop', description: `Drop an item in the owner's words: lifecycle dropped, with the words, the date and the lifecycle it left. A dropped item stays in the graph, and no live view lists it. Refuses a done item (reopen it instead) and an item already dropped. When: the owner retires a piece of work. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'item_id', 'origin'], properties: { request_id: REQUEST_ID, item_id: S('Item id.'), origin: { ...ORIGIN, description: "The owner's words that drop the item, verbatim, with where and when they were said." } }, additionalProperties: false } },
-  { name: 'item_edit', description: `Edit a proposed, active or paused item: its next step, what it waits on, its free tags, its planned dates, or its title. Each edit keeps the old and new values in the item's log, which item_activity reads; the first title stays in first_title. When: the next step, the wait or a tag changes; the lead keeps them true at the end of each session. The tags that other verbs own (product:, repo:, tier:, item:, atlas-work, no-model, atlas-registry) are refused. A new title is the owner's words, and planned dates are the owner's promise. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'item_id'], properties: { request_id: REQUEST_ID, item_id: S('Item id.'), next_step: S('One line: what happens next.'), waits_on: { type: 'object', required: ['on'], description: 'What the item waits on. Shown on its rows.', properties: { on: S(`One of ${WAITS_ON.join(', ')}. To wait on another item, use item_block.`), note: S('What exactly it waits on, in plain words. Required unless on is nothing.') } }, title: S("A new title, in the owner's words."), tags_add: { type: 'array', items: { type: 'string' }, description: 'Free tags to add.' }, tags_remove: { type: 'array', items: { type: 'string' }, description: 'Free tags to remove.' }, plan: { type: 'object', description: 'Planned dates, set by the owner. Each is YYYY-MM-DD, or null to clear it. Dates not named stay as they are.', properties: { start: { type: ['string', 'null'], description: 'Planned start.' }, end: { type: ['string', 'null'], description: 'Planned end. Not before the start.' }, deadline: { type: ['string', 'null'], description: 'Deadline.' } }, additionalProperties: false }, reason: S('One line on why it changed.') }, additionalProperties: false } },
+  { name: 'item_edit', description: `Edit a proposed, active or paused item: its next step, what it waits on, its free tags, its planned dates, or its title. Each edit keeps the old and new values in the item's log, which item_activity reads; the first title stays in first_title. When: the next step, the wait or a tag changes; the lead keeps them true at the end of each session. The tags that other verbs own (product:, repo:, tier:, item:, input:, atlas-work, no-model, atlas-registry) are refused. A new title is the owner's words, and planned dates are the owner's promise. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'item_id'], properties: { request_id: REQUEST_ID, item_id: S('Item id.'), next_step: S('One line: what happens next.'), waits_on: { type: 'object', required: ['on'], description: 'What the item waits on. Shown on its rows.', properties: { on: S(`One of ${WAITS_ON.join(', ')}. To wait on another item, use item_block.`), note: S('What exactly it waits on, in plain words. Required unless on is nothing.') } }, title: S("A new title, in the owner's words."), tags_add: { type: 'array', items: { type: 'string' }, description: 'Free tags to add.' }, tags_remove: { type: 'array', items: { type: 'string' }, description: 'Free tags to remove.' }, plan: { type: 'object', description: 'Planned dates, set by the owner. Each is YYYY-MM-DD, or null to clear it. Dates not named stay as they are.', properties: { start: { type: ['string', 'null'], description: 'Planned start.' }, end: { type: ['string', 'null'], description: 'Planned end. Not before the start.' }, deadline: { type: ['string', 'null'], description: 'Deadline.' } }, additionalProperties: false }, reason: S('One line on why it changed.') }, additionalProperties: false } },
   { name: 'item_stage', description: `Move an active item to a stage (${STAGES.join(', ')}). When: work moves; the lead or the delivering agent calls it. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'item_id', 'stage'], properties: { request_id: REQUEST_ID, item_id: S('Item id.'), stage: S(`One of ${STAGES.join(', ')}.`), note: S('One line on what moved.') }, additionalProperties: false } },
   { name: 'item_block', description: `Record that an item is blocked by another item. The item keeps a list of its blockers, each with a note; the views show "blocked by" on its row and "blocks" on the blocker's row, and a blocker that is delivered or dropped shows as cleared. Refuses the item itself and a link that would close a loop. When: work cannot move until another item lands. ${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 item id that blocks it.'), note: S('One line: what exactly it needs from the blocker.') }, additionalProperties: false } },
   { 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. ${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 } },
@@ -99,6 +102,7 @@ export const TOOLS = TOOL_LIST.map((tool) => ({ ...tool, description: `${tool.de
 // a throw.
 const CONNECTION_HELP = 'Put it in the file ~/.config/atlas/engram-connection, as "https://<host> <key>". "atlas install" prints the commands.';
 const CONNECTION_FILE_LIMIT = 16 * 1024;
+const KEY_TYPES = Object.freeze(['user', 'agent']);
 export function connectionFile(env) { return env.HOME ? join(env.HOME, '.config', 'atlas', 'engram-connection') : null; }
 function readConnectionFile(env) {
   const path = connectionFile(env);
@@ -145,7 +149,10 @@ export function readConnection(env, { allowLoopbackHttp = false, now = Date.now(
   if (url.username || url.password || url.pathname !== '/' || url.search || url.hash) return { state: 'bad', message: `The Engram address must be the host only, with no path. ${CONNECTION_HELP}` };
   let claims;
   try { claims = JSON.parse(Buffer.from(token.split('.')[1], 'base64url')); } catch { return { state: 'bad', message: `The Engram key is not an Engram token. ${CONNECTION_HELP}` }; }
-  if (claims.principal_type !== 'user' || !claims.jti || !claims.exp) return { state: 'bad', message: `The Engram key must be a user token with a token id. ${CONNECTION_HELP}` };
+  // Roadmap R22: a user key gives the lead; an Engram agent key gives a
+  // routine, which only creates records (roles.mjs). Any other principal is
+  // refused.
+  if (!KEY_TYPES.includes(claims.principal_type) || !claims.jti || !claims.exp) return { state: 'bad', message: `The Engram key must be a user or an agent token with a token id. ${CONNECTION_HELP}` };
   if (claims.exp <= now / 1000) {
     const day = new Date(claims.exp * 1000).toISOString().slice(0, 10);
     return { state: 'expired', message: `The Engram key expired on ${day}. Put a new one in ~/.config/atlas/engram-connection.`, expired: day };