@arjunkhera/atlas 0.0.0 → 0.2.1

package/work/lib/capability.mjs

@@ -0,0 +1,487 @@
+// Atlas M1 slice L4: "where are we with X" and "Built, pending, possible".
+// Design: the Atlas M1 study, page four (the six-part
+// answer and its sources), page five (what the owner asked Q3 to become), D3
+// (the views), D6 findings R12 and R14, and the frozen L4 paragraph of the
+// lock block.
+//
+// Three rules hold this slice together:
+//   1. The answer is computed at question time and never stored (D3). Nothing
+//      here writes a record.
+//   2. Every row carries a citation: a path and a line for a code claim, an
+//      entity id for a graph claim, a pull request for a delivery, a date for
+//      a decision. A claim with no citation does not enter the answer.
+//   3. The code half comes from sub-agents through acceptCodeRead, which
+//      refuses a never-read path, refuses a quote from a never-quoted path and
+//      scrubs by pattern. The rendered answer is scrubbed once more before it
+//      leaves the door (R12).
+import { refuse, text, isoDate, stringList } from './verb-fields.mjs';
+import { oneLine, scrubSecrets, ROW_LINE_MAX } from './questions.mjs';
+import { listLine, legacySealOf, marksByItem, movementOf, pullsOfItem, readPullsByRepo, correctionsOf, daysBetween } from './delivery.mjs';
+import { acceptCodeRead, codeReadBrief } from './code-read.mjs';
+
+export const CAPABILITY_READ_VERBS = Object.freeze(['code_read_brief', 'where_are_we', 'built_pending_possible']);
+
+const MAX_DIGESTS = 8;
+const MAX_TERMS = 12;
+const MAX_MATCHED = 60;
+const MAX_ITEMS = 500;
+const MAX_REPOS = 16;
+const MAX_DECISIONS = 300;
+const SHOWN = 12;
+const OMITTED_KEPT = 25;
+
+const shortCommit = (commit) => String(commit ?? '').slice(0, 7);
+const day = (value) => (value ? String(value).slice(0, 10) : 'no date on record');
+const plural = (count, word) => `${count} ${word}${count === 1 ? '' : 's'}`;
+// A delivery can carry several pull requests. The line names the first and
+// counts the rest, so a list of URLs never eats the title (review H13).
+const prsOf = (row) => (row.prs?.length ? `${row.prs[0]}${row.prs.length > 1 ? ` +${row.prs.length - 1}` : ''}` : (row.source || 'no pull request on the mark'));
+export const codeCitation = (row) => `${row.repo}@${shortCommit(row.commit)} ${row.path}:${row.line}`;
+
+// Parts three, four and five read items. An item belongs to the answer when the
+// lead names it, or when a term the lead gave appears in its title, summary or
+// tags. The lead judges the match, as the owner's cut decided
+// (study page 4.4): there is no link field from a capability to an item.
+export function matchOf(item, terms) {
+  const fields = item.fields ?? {};
+  const hay = `${item.title ?? ''}\n${fields.summary ?? ''}\n${(item.tags ?? []).join(' ')}`.toLowerCase();
+  const hit = terms.find((term) => hay.includes(term.toLowerCase()));
+  return hit ? `term "${hit}"` : null;
+}
+
+export function createCapabilityVerbs(core) {
+  const { client, now, typeNamed, registry, requireProduct, requireItem, readGitHub } = core;
+
+  const productRepos = (reg, productId) => [...reg.repos.values()].filter((repo) => repo.fields?.product === productId).map((repo) => repo.fields.registry_id).sort();
+
+  // How a row names its product (D3 rule 2). An item that names no registered
+  // product is never given one here: it is carried as "unregistered", and the
+  // slice L5 sweep is what gives it a product. An item that names a product the
+  // registry does not hold keeps that name too, so a row never says the record
+  // is silent when it is not (review H8).
+  const productOf = (item, reg) => {
+    const named = item.fields?.product;
+    if (typeof named === 'string' && reg.products.has(named)) return { product: named, named: null };
+    return { product: 'unregistered', named: typeof named === 'string' && named.trim() ? named : null };
+  };
+  const unregisteredNote = (named) => (named
+    ? `the item names product "${named}", which is not in the registry; the slice L5 sweep gives it a registered one`
+    : 'the item names no product; the slice L5 sweep gives it one');
+
+  async function allItems() {
+    const container = await typeNamed('container');
+    const rows = await client.listAllEntities({ type: container.name, state: 'active' });
+    if (rows.length > MAX_ITEMS) refuse(`${rows.length} items are in the graph; a view reads at most ${MAX_ITEMS}`);
+    return rows;
+  }
+
+  async function marksFor(itemIds) {
+    const type = await typeNamed('mark');
+    return marksByItem(await client.listAllEntities({ type: type.name, state: 'active' }), itemIds);
+  }
+
+  async function decisionsFor(productId) {
+    const type = await typeNamed('decision');
+    const rows = await client.listAllEntities({ type: type.name, state: 'active' });
+    if (rows.length > MAX_DECISIONS) refuse(`${rows.length} decisions are recorded; a view reads at most ${MAX_DECISIONS}`);
+    return rows.filter((row) => row.fields?.product === productId)
+      .sort((a, b) => String(b.fields?.date ?? '').localeCompare(String(a.fields?.date ?? '')) || String(b.created_at ?? '').localeCompare(String(a.created_at ?? '')));
+  }
+
+  // A delivery on an item, as parts four reads it: the standing marks, the
+  // marks a reopen corrected (named, never hidden), and the legacy seal of the
+  // first slice (R14).
+  function deliveriesOf(item, marks) {
+    const own = marks.get(item.id) ?? [];
+    const correctedBy = correctionsOf(own);
+    const rows = own.filter((mark) => mark.fields?.kind === 'delivery').map((mark) => ({
+      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 ?? null, prs: (mark.fields?.prs ?? []).map((pull) => pull.url),
+      deployed_commit: mark.fields?.deployed?.commit ?? null, gate_warnings: mark.fields?.gate_warnings ?? [],
+    }));
+    // R14: a legacy seal reads as a delivery mark. Only a delivery mark
+    // replaces it. A reopen, or any later mark kind, must not erase it
+    // (review H9).
+    const legacy = rows.length ? null : legacySealOf(item);
+    if (legacy) rows.push({ mark_id: null, verdict: 'legacy', delivered_at: legacy.marked_at, prs: [], deployed_commit: null, source: legacy.source });
+    return { rows: rows.sort((a, b) => String(b.delivered_at ?? '').localeCompare(String(a.delivered_at ?? ''))), marks: own };
+  }
+
+  const verbs = {
+    // The brief the sub-agents are given, one per repo of the product. Read
+    // only: it writes nothing and reads no repo. It exists so the deny rules
+    // and the citation contract come from one place, and so the evidence of an
+    // answer shows what its readers were told (D6 R3, R12).
+    async code_read_brief(args = {}) {
+      const reg = await registry();
+      const product = await requireProduct(args.product, reg);
+      const productId = product.fields.registry_id;
+      const capability = text(args.capability, 'capability', { max: 200 });
+      const known = productRepos(reg, productId);
+      if (!known.length) refuse(`product ${productId} has no registered repo; register one with repo_add before a code read`);
+      const wanted = args.repos === undefined ? known : stringList(args.repos, 'repos', { max: MAX_REPOS });
+      for (const repo of wanted) if (!known.includes(repo)) refuse(`unknown repo id: ${repo}. Registered for ${productId}: ${known.join(', ')}`);
+      // The answer takes at most MAX_DIGESTS digests. A brief above that number
+      // would spend a sub-agent read that no answer could use, so the cost is
+      // refused before it is paid (review H7).
+      if (wanted.length > MAX_DIGESTS) refuse(`${wanted.length} repos are registered for ${productId}, and an answer reads at most ${MAX_DIGESTS} digests. Name the repos to read with "repos".`);
+      const roots = args.roots === undefined ? {} : args.roots;
+      if (roots === null || typeof roots !== 'object' || Array.isArray(roots)) refuse('roots must be an object: repo id to the local checkout path');
+      const focus = args.focus === undefined ? [] : stringList(args.focus, 'focus', { max: 16 });
+      const commits = args.commits === undefined ? {} : args.commits;
+      if (commits === null || typeof commits !== 'object' || Array.isArray(commits)) refuse('commits must be an object: repo id to the commit the read runs against');
+      const briefs = wanted.map((repo) => {
+        const record = reg.repos.get(repo);
+        return codeReadBrief({
+          capability, repo, root: roots[repo] ? text(roots[repo], `roots.${repo}`, { max: 1000 }) : null,
+          commit: commits[repo] ? text(commits[repo], `commits.${repo}`, { max: 40 }) : null,
+          defaultBranch: record?.fields?.default_branch ?? null, focus,
+        });
+      });
+      return {
+        verb: 'code_read_brief', read_at: now(), product: productId, capability, repos: wanted, briefs,
+        note: 'Give one brief to one sub-agent. Sub-agents never receive the verb server or the Engram MCP. Pass each returned digest back in where_are_we.code.',
+      };
+    },
+
+    // D3: "where are we with X". The six parts of study page 4.2, each from the
+    // source that page names. Computed at question time, never stored.
+    async where_are_we(args = {}) {
+      const reg = await registry();
+      const product = await requireProduct(args.product, reg);
+      const productId = product.fields.registry_id;
+      const capability = text(args.capability, 'capability', { max: 200 });
+      const since = args.since === undefined ? null : isoDate(args.since, 'since');
+      const repos = productRepos(reg, productId);
+
+      // Parts one and two. An answer with no code read is the failure the study
+      // names on page four: the earlier answers came from docs and the graph,
+      // and they said nothing about what the code does today.
+      if (!Array.isArray(args.code) || !args.code.length) refuse('code must hold at least one sub-agent digest: parts one and two of the answer come from the code, read at question time. Call code_read_brief first.');
+      if (args.code.length > MAX_DIGESTS) refuse(`code holds more than ${MAX_DIGESTS} digests`);
+      let redactions = 0;
+      const digests = args.code.map((entry, index) => {
+        const accepted = acceptCodeRead(entry, { repos, name: `code[${index}]` });
+        redactions += accepted.redactions;
+        return accepted.digest;
+      });
+      const seen = new Set();
+      for (const digest of digests) {
+        if (seen.has(digest.repo)) refuse(`code holds two digests for ${digest.repo}; one read per repo`);
+        seen.add(digest.repo);
+      }
+      const supports = digests.flatMap((digest) => digest.supports.map((row) => ({ ...row, commit: digest.commit })));
+      const limits = digests.flatMap((digest) => digest.limits.map((row) => ({ ...row, commit: digest.commit })));
+
+      // Parts three, four and five. The lead names the items, or gives terms to
+      // match. One of the two is required: an answer needs a basis.
+      const named = args.items === undefined ? [] : stringList(args.items, 'items', { max: MAX_MATCHED });
+      const terms = args.match === undefined ? [] : stringList(args.match, 'match', { max: MAX_TERMS }).map((term) => text(term, 'match', { max: 100 }));
+      if (!named.length && !terms.length) refuse('name the items with items, or give match terms, or both: the lead judges which items answer this question (study page 4.4)');
+      const rows = await allItems();
+      const byId = new Map(rows.map((row) => [row.id, row]));
+      const picked = new Map(), omitted = [];
+      const belongs = (item) => {
+        const owner = item.fields?.product;
+        return !(typeof owner === 'string' && reg.products.has(owner) && owner !== productId);
+      };
+      for (const id of named) {
+        const item = byId.get(id) ?? await requireItem(id);
+        if (!belongs(item)) refuse(`item ${id} belongs to product ${item.fields.product}, not ${productId}`);
+        picked.set(item.id, { item, matched_by: 'named by the lead' });
+      }
+      for (const row of rows) {
+        if (picked.has(row.id)) continue;
+        const how = matchOf(row, terms);
+        if (!how) continue;
+        if (!belongs(row)) { omitted.push({ item: row.id, title: row.title, product_named: row.fields.product, reason: null }); continue; }
+        picked.set(row.id, { item: row, matched_by: how });
+      }
+      if (picked.size > MAX_MATCHED) refuse(`${picked.size} items match; the answer reads at most ${MAX_MATCHED}. Narrow the terms or name the items.`);
+      const items = [...picked.values()];
+      const marks = await marksFor(new Set(picked.keys()));
+
+      // Movement for part three, from git through the repo ids and the item
+      // links, exactly as the "In flight" view reads it (D3 rule 5, R1).
+      // Movement reads the product's repos and the repos the code read covered.
+      // A product with more than MAX_REPOS repos would otherwise have no answer
+      // at all, so the caller may narrow the movement read to the repos that
+      // matter (review J2). The digests' own repos are always read.
+      const wantedRepos = args.movement_repos === undefined ? null : stringList(args.movement_repos, 'movement_repos', { max: MAX_REPOS });
+      if (wantedRepos) for (const repo of wantedRepos) if (!reg.repos.has(repo)) refuse(`unknown repo id: ${repo}. Known: ${[...reg.repos.keys()].sort().join(', ') || 'none'}`);
+      const repoIds = [...new Set([...(wantedRepos ?? repos), ...digests.map((digest) => digest.repo)])].filter((repo) => reg.repos.has(repo)).sort();
+      if (repoIds.length > MAX_REPOS) refuse(`${repoIds.length} repos would be read for movement; an answer reads at most ${MAX_REPOS}. Name the repos to read with "movement_repos".`);
+      const { pullsByRepo, repoErrors } = await readPullsByRepo(repoIds, readGitHub);
+      // Which registered repos the code half did not read. Parts one and two
+      // are then a partial picture, and the answer says so (review H4).
+      const unread = repos.filter((repo) => !digests.some((digest) => digest.repo === repo));
+
+      const readAt = now();
+      const clean = (value, max = 200) => { const out = scrubSecrets(oneLine(value, max)); redactions += out.redactions; return out.text; };
+      // A gate warning comes from the mark, so it is graph text like any other
+      // and passes the same scrub (review H2).
+      const cleanWarnings = (warnings) => (Array.isArray(warnings) ? warnings : []).map((warning) => (warning && typeof warning === 'object'
+        ? Object.fromEntries(Object.entries(warning).map(([key, value]) => [key, typeof value === 'string' ? clean(value, 500) : value]))
+        : clean(String(warning ?? ''), 500)));
+      const inProgress = [], delivered = [], proposed = [];
+      for (const { item, matched_by: matchedBy } of items) {
+        const fields = item.fields ?? {};
+        const lifecycle = fields.lifecycle ?? 'unknown';
+        const where = productOf(item, reg);
+        const pulls = pullsOfItem(item, pullsByRepo, repoIds);
+        const { rows: deliveries, marks: own } = deliveriesOf(item, marks);
+        const { last, days } = movementOf({ item, marks: own, pulls, legacy: deliveries.some((row) => row.verdict === 'legacy') ? { marked_at: deliveries.find((row) => row.verdict === 'legacy').delivered_at } : null, readAt });
+        const base = {
+          item: item.id, title: clean(item.title, 160), product: where.product, ...(where.named ? { product_named: clean(where.named, 64) } : {}), matched_by: matchedBy,
+          citation: { item: item.id, read_at: readAt, ...(where.product === 'unregistered' ? { note: unregisteredNote(where.named && clean(where.named, 64)) } : {}) },
+        };
+        // Part four is every delivery this answer knows of, whatever its date.
+        // A date narrows the "changed since" line below, not the answer: the
+        // owner asking "where are we with X" is asking about the whole of X
+        // (study page 4.2).
+        for (const delivery of deliveries) delivered.push({ ...base, ...delivery, prs: delivery.prs.map((url) => clean(url, 500)), gate_warnings: cleanWarnings(delivery.gate_warnings), citation: { ...base.citation, mark: delivery.mark_id, prs: delivery.prs.map((url) => clean(url, 500)) } });
+        // A done item with no mark and no legacy seal is still delivered work.
+        // The row says what is missing rather than dropping the item, and the
+        // done verb is what catches it up (R2).
+        // The graph's list rows carry created_at but not always updated_at, so
+        // the date falls back rather than reading as no date at all.
+        const doneAt = fields.delivered_at ?? item.updated_at ?? item.created_at ?? null;
+        if (lifecycle === 'done' && !deliveries.length) delivered.push({ ...base, mark_id: null, verdict: 'done, no delivery mark', delivered_at: doneAt, prs: pulls.filter((pull) => pull.state === 'merged').map((pull) => clean(pull.url, 500)), deployed_commit: null, source: 'no mark yet', note: 'the item record says done; the done verb writes the mark' });
+        if (lifecycle === 'active') {
+          inProgress.push({
+            ...base, stage: clean(fields.stage ?? '', 64), driver: clean(fields.driver ?? '', 64), next_step: clean(fields.next_step ?? '', 200),
+            days_since_last_change: days, last_change_at: last?.at ?? null, last_change_source: clean(last?.source ?? 'nothing recorded', 120),
+            delivery_state: fields.delivery_state ? clean(fields.delivery_state, 64) : null, prs: pulls.map((pull) => ({ url: clean(pull.url, 500), state: clean(pull.state, 32), matched_by: pull.matched_by })),
+            citation: { ...base.citation, repos: [...new Set(pulls.map((pull) => pull.repo))] },
+          });
+        } else if (lifecycle === 'proposed') {
+          const born = fields.created_at ?? item.created_at ?? null;
+          proposed.push({ ...base, age_days: born ? daysBetween(born, readAt) : null, proposed_at: born, driver: clean(fields.driver ?? '', 64) });
+        } else if (lifecycle !== 'done' && !deliveries.length) {
+          omitted.push({ item: item.id, title: clean(item.title, 120), reason: `the item is ${clean(lifecycle, 32)}; paused and archived items are backlog (D3 rule 1)` });
+        }
+      }
+      inProgress.sort((a, b) => (a.days_since_last_change ?? Number.MAX_SAFE_INTEGER) - (b.days_since_last_change ?? Number.MAX_SAFE_INTEGER) || a.item.localeCompare(b.item));
+      delivered.sort((a, b) => String(b.delivered_at ?? '').localeCompare(String(a.delivered_at ?? '')));
+      proposed.sort((a, b) => (b.age_days ?? 0) - (a.age_days ?? 0));
+
+      // Part six: the current priority decision, or "none recorded". A decision
+      // that touches one of these items is named too, whatever its kind.
+      const decisions = await decisionsFor(productId);
+      const touched = new Set(picked.keys());
+      const priority = decisions.filter((row) => row.fields?.kind === 'priority');
+      const related = decisions.filter((row) => Array.isArray(row.fields?.items) && row.fields.items.some((id) => touched.has(id)));
+      const decisionRow = (row, why) => ({ decision: row.id, kind: row.fields?.kind ?? 'decision', date: row.fields?.date ?? '', text: clean(row.fields?.text ?? row.title, 400), why, priority_order: row.fields?.priority_order ?? [], citation: { decision: row.id, date: row.fields?.date ?? '', source: row.fields?.source ?? '' } });
+      const priorityRows = [
+        ...(priority[0] ? [decisionRow(priority[0], 'the latest priority decision for this product')] : []),
+        ...related.filter((row) => row.id !== priority[0]?.id).slice(0, SHOWN).map((row) => decisionRow(row, 'related, not a priority decision: it names one of these items')),
+      ];
+
+      const unknowns = [
+        ...digests.flatMap((digest) => digest.unknowns.map((line) => `${digest.repo}: ${line}`)),
+        ...repoErrors.map((row) => `movement for ${row.repo} is from the graph only: ${row.reason}`),
+        // The warning depends on the priority decisions alone. A related
+        // decision of another kind must not silence it (review H3).
+        ...(priority.length ? [] : ['no priority decision is recorded for this product']),
+        // Which registered repos the code half did not read (review H4).
+        ...unread.map((repo) => `the code half did not read ${repo}; parts one and two do not cover it`),
+      ];
+      const unregistered = [...new Set([...inProgress, ...delivered, ...proposed].filter((row) => row.product === 'unregistered').map((row) => row.item))];
+      if (unregistered.length) unknowns.push(`${unregistered.length} of these items name no registered product; the slice L5 sweep gives them one`);
+
+      // The omitted list is scrubbed here, because the match loop runs before
+      // the scrub exists, and it is bounded, because a wide term can omit many
+      // items and a long list is not a view (reviews H2 and H16).
+      // Every string of every row passes the scrub, whatever field it came from
+      // and however deep it sits. Field-by-field scrubbing kept missing one
+      // (reviews H2, J1, K1), so the rows are walked instead: one rule, no list
+      // to keep up to date. The rendered text is scrubbed again at the end.
+      // The walk scrubs, but it does not flatten: a path may hold a space, and
+      // a flattened path no longer resolves (review L2). Rendering is where
+      // whitespace is collapsed, not storage.
+      const cleanDeep = (value) => {
+        if (typeof value === 'string') {
+          const out = scrubSecrets(value.length > 4000 ? `${value.slice(0, 3999)}…` : value);
+          redactions += out.redactions;
+          return out.text;
+        }
+        if (Array.isArray(value)) return value.map(cleanDeep);
+        if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, cleanDeep(entry)]));
+        return value;
+      };
+      // The rendered block keeps its line breaks: it is scrubbed whole, on its
+      // own, and it must not pass through the one-line flattener. The count is
+      // read after the walk, so the walk's own finds are counted too (L1).
+      const scrubbed = ({ text, ...rest }) => { const rows = cleanDeep(rest); return { ...rows, redactions: redactions + rendered.redactions, text }; };
+      const omittedTotal = omitted.length;
+      const omittedRows = omitted.slice(0, OMITTED_KEPT).map((row) => ({
+        item: row.item, title: clean(row.title, 120),
+        reason: row.reason ?? `the item belongs to product ${clean(row.product_named ?? '', 64)}`,
+      }));
+
+      const changed = since ? {
+        since,
+        delivered: delivered.filter((row) => String(row.delivered_at ?? '') >= since).length,
+        locked: items.filter(({ item }) => String(item.fields?.locked_at ?? '') >= since).map(({ item }) => item.id),
+        merged_prs: [...new Set(items.flatMap(({ item }) => pullsOfItem(item, pullsByRepo, repoIds).filter((pull) => pull.state === 'merged' && String(pull.merged_at ?? '') >= since).map((pull) => pull.url)))],
+      } : null;
+
+      // Why a row is in the answer: the lead named the item, or a term matched
+      // it. The owner reads the reason on the row, and never has to open a
+      // source to learn why it is there.
+      const why = (row) => (row.matched_by === 'named by the lead' ? 'named' : row.matched_by);
+      const part = (number, title, count, lines) => [`${number}. ${title} (${count})`, ...(lines.length ? lines : ['   nothing recorded'])].join('\n');
+      const more = (list) => (list.length > SHOWN ? [`   and ${list.length - SHOWN} more, in the rows`] : []);
+      const block = [
+        `Where are we with ${capability}? — ${productId} · read ${readAt.slice(0, 19)}Z · code at ${digests.map((digest) => `${digest.repo}@${shortCommit(digest.commit)}`).join(', ')}`,
+        part(1, 'Live support, from the code', supports.length, [...supports.slice(0, SHOWN).map((row) => listLine(`${row.name} — ${row.statement}`, codeCitation(row))), ...more(supports)]),
+        part(2, 'Known limits, from the code', limits.length, [...limits.slice(0, SHOWN).map((row) => listLine(`${row.kind}: ${row.name} — ${row.statement}`, codeCitation(row))), ...more(limits)]),
+        part(3, 'In progress', inProgress.length, [...inProgress.slice(0, SHOWN).map((row) => listLine(`${row.title} · ${row.stage || 'no stage'} · next: ${row.next_step || 'not set'}`, `${row.item} · ${row.days_since_last_change === null ? 'no movement on record' : `${row.days_since_last_change} day${row.days_since_last_change === 1 ? '' : 's'} since ${row.last_change_source}`} · ${why(row)}`)), ...more(inProgress)]),
+        part(4, 'Delivered', delivered.length, [...delivered.slice(0, SHOWN).map((row) => listLine(row.title, `${row.verdict} ${day(row.delivered_at)} · ${prsOf(row)} · ${row.item}${row.mark_id ? ` · mark ${row.mark_id.slice(0, 8)}` : ''}`)), ...more(delivered)]),
+        part(5, 'Proposed, with age', proposed.length, [...proposed.slice(0, SHOWN).map((row) => listLine(row.title, `${row.age_days === null ? 'age unknown' : `${row.age_days} days old`} · ${row.item} · ${why(row)}`)), ...more(proposed)]),
+        part(6, 'The current priority decision', priorityRows.length, priorityRows.length ? priorityRows.map((row) => listLine(`${row.kind}: ${row.text}`, `${row.date} · ${row.why} · ${row.decision}`)) : ['   none recorded']),
+        ...(changed ? [`Changed since ${since}: ${changed.delivered} delivered, ${changed.locked.length} locked, ${plural(changed.merged_prs.length, 'pull request')} merged`] : []),
+        ...(unknowns.length ? [['Unknowns', ...unknowns.slice(0, SHOWN).map((line) => oneLine(`   ${line}`, ROW_LINE_MAX)), ...(unknowns.length > SHOWN ? [`   and ${unknowns.length - SHOWN} more, in the rows`] : [])].join('\n')] : []),
+        ...(omittedTotal ? [[`Omitted (${omittedTotal})`, ...omittedRows.slice(0, SHOWN).map((row) => listLine(row.title, row.reason)), ...(omittedTotal > SHOWN ? [`   and ${omittedTotal - SHOWN} more, ${Math.max(0, omittedRows.length - SHOWN)} of them in this answer`] : [])].join('\n')] : []),
+      ].join('\n\n');
+      const rendered = scrubSecrets(block);
+      return scrubbed({
+        verb: 'where_are_we', read_at: readAt, product: productId, capability, since,
+        code: digests.map((digest) => ({ repo: digest.repo, commit: digest.commit, files_read: digest.files_read.length, supports: digest.supports.length, limits: digest.limits.length, read_by: digest.read_by })),
+        parts: [
+          { part: 1, title: 'Live support, from the code', source: 'code, read at question time by sub-agents', rows: supports },
+          { part: 2, title: 'Known limits, from the code', source: 'code, read at question time by sub-agents', rows: limits },
+          { part: 3, title: 'In progress', source: 'item records, plus git for movement', rows: inProgress },
+          { part: 4, title: 'Delivered', source: 'item records and delivery marks', rows: delivered },
+          { part: 5, title: 'Proposed, with age', source: 'item records', rows: proposed },
+          { part: 6, title: 'The current priority decision', source: 'decision records', rows: priorityRows },
+        ],
+        items_matched: items.length, omitted: omittedRows, omitted_total: omittedTotal, unknowns, changed_since: changed, repos_unread: unread,
+        repos_read: repoIds, repo_errors: repoErrors, redactions: redactions + rendered.redactions,
+        citations: supports.length + limits.length + inProgress.length + delivered.length + proposed.length + priorityRows.length,
+        text: rendered.text,
+      });
+    },
+
+    // D3: "Built, pending, possible", the view the owner asked Q3 to become on
+    // 2026-09-16: "what all are we building, what all is built, what is yet to
+    // be done and pending and what can be done". Item records, delivery marks
+    // and decisions only. No code read, no GitHub read.
+    async built_pending_possible(args = {}) {
+      const reg = await registry();
+      let only = null;
+      if (args.product !== undefined) only = (await requireProduct(args.product, reg)).fields.registry_id;
+      const since = args.since === undefined ? null : isoDate(args.since, 'since');
+      const rows = await allItems();
+      const registered = (row) => typeof row.fields?.product === 'string' && reg.products.has(row.fields.product);
+      // A read narrowed to one product keeps that product's items only. A wide
+      // read keeps every item, because eighty-eight of the tenant's ninety name
+      // no registered product, and a board that drops them answers nothing
+      // before the slice L5 sweep (review H5). No row is given a product it
+      // does not carry: an item with none reads "unregistered", as the six-part
+      // answer already renders it.
+      const items = only ? rows.filter((row) => row.fields?.product === only) : rows;
+      const unregisteredTotal = rows.filter((row) => !registered(row)).length;
+      const unregisteredShown = items.filter((row) => !registered(row)).length;
+      const marks = await marksFor(new Set(items.map((row) => row.id)));
+      const readAt = now();
+      let redactions = 0;
+      const clean = (value, max = 200) => { const out = scrubSecrets(oneLine(value, max)); redactions += out.redactions; return out.text; };
+      // A gate warning comes from the mark, so it is graph text like any other
+      // and passes the same scrub (review H2).
+      const cleanWarnings = (warnings) => (Array.isArray(warnings) ? warnings : []).map((warning) => (warning && typeof warning === 'object'
+        ? Object.fromEntries(Object.entries(warning).map(([key, value]) => [key, typeof value === 'string' ? clean(value, 500) : value]))
+        : clean(String(warning ?? ''), 500)));
+
+      // Every string of every row passes the scrub, whatever field it came from
+      // and however deep it sits. Field-by-field scrubbing kept missing one
+      // (reviews H2, J1, K1), so the rows are walked instead: one rule, no list
+      // to keep up to date. The rendered text is scrubbed again at the end.
+      // The walk scrubs, but it does not flatten: a path may hold a space, and
+      // a flattened path no longer resolves (review L2). Rendering is where
+      // whitespace is collapsed, not storage.
+      const cleanDeep = (value) => {
+        if (typeof value === 'string') {
+          const out = scrubSecrets(value.length > 4000 ? `${value.slice(0, 3999)}…` : value);
+          redactions += out.redactions;
+          return out.text;
+        }
+        if (Array.isArray(value)) return value.map(cleanDeep);
+        if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, cleanDeep(entry)]));
+        return value;
+      };
+      // The rendered block keeps its line breaks: it is scrubbed whole, on its
+      // own, and it must not pass through the one-line flattener. The count is
+      // read after the walk, so the walk's own finds are counted too (L1).
+      const scrubbed = ({ text, ...rest }) => { const rows = cleanDeep(rest); return { ...rows, redactions: redactions + rendered.redactions, text }; };
+      const built = [], building = [], pending = [], possible = [];
+      for (const item of items) {
+        const fields = item.fields ?? {};
+        const { rows: deliveries, marks: own } = deliveriesOf(item, marks);
+        const { last, days } = movementOf({ item, marks: own, legacy: deliveries.some((row) => row.verdict === 'legacy') ? { marked_at: deliveries.find((row) => row.verdict === 'legacy').delivered_at } : null, readAt });
+        const where = productOf(item, reg);
+        const base = {
+          item: item.id, title: clean(item.title, 160), product: where.product, ...(where.named ? { product_named: clean(where.named, 64) } : {}),
+          citation: { item: item.id, read_at: readAt, ...(where.product === 'unregistered' ? { note: unregisteredNote(where.named && clean(where.named, 64)) } : {}) },
+        };
+        for (const delivery of deliveries) {
+          if (since && String(delivery.delivered_at ?? '') < since) continue;
+          built.push({ ...base, ...delivery, prs: delivery.prs.map((url) => clean(url, 500)), gate_warnings: cleanWarnings(delivery.gate_warnings), citation: { ...base.citation, mark: delivery.mark_id, prs: delivery.prs.map((url) => clean(url, 500)) } });
+        }
+        const doneAt = fields.delivered_at ?? item.updated_at ?? item.created_at ?? null;
+        if (fields.lifecycle === 'done' && !deliveries.length && !(since && String(doneAt ?? '') < since)) built.push({ ...base, mark_id: null, verdict: 'done, no delivery mark', delivered_at: doneAt, prs: [], source: 'no mark yet', note: 'the item record says done; the done verb writes the mark' });
+        if (fields.lifecycle === 'active') building.push({ ...base, stage: clean(fields.stage ?? '', 64), driver: clean(fields.driver ?? '', 64), next_step: clean(fields.next_step ?? '', 200), days_since_last_change: days, last_change_source: clean(last?.source ?? 'nothing recorded', 120), delivery_state: fields.delivery_state ? clean(fields.delivery_state, 64) : null });
+        else if (fields.lifecycle === 'paused') pending.push({ ...base, reason: clean(fields.pause_reason ?? 'no reason on record', 300), days_since_last_change: days, parked_at: fields.parked_at ?? null });
+        else if (fields.lifecycle === 'proposed') {
+          const born = fields.created_at ?? item.created_at ?? null;
+          possible.push({ ...base, age_days: born ? daysBetween(born, readAt) : null, proposed_at: born, driver: clean(fields.driver ?? '', 64) });
+        }
+      }
+      built.sort((a, b) => String(b.delivered_at ?? '').localeCompare(String(a.delivered_at ?? '')));
+      building.sort((a, b) => (a.days_since_last_change ?? Number.MAX_SAFE_INTEGER) - (b.days_since_last_change ?? Number.MAX_SAFE_INTEGER) || a.item.localeCompare(b.item));
+      pending.sort((a, b) => (a.days_since_last_change ?? Number.MAX_SAFE_INTEGER) - (b.days_since_last_change ?? Number.MAX_SAFE_INTEGER) || a.item.localeCompare(b.item));
+      possible.sort((a, b) => (b.age_days ?? 0) - (a.age_days ?? 0));
+
+      // The decisions that set the order. The owner's words are what ordered
+      // this work, so the view ends with them, newest first.
+      const products = only ? [only] : [...new Set(items.filter(registered).map((row) => row.fields.product))];
+      const order = [];
+      for (const productId of products) {
+        for (const row of await decisionsFor(productId)) {
+          if (since && String(row.fields?.date ?? '') < since) continue;
+          if (row.fields?.kind === 'priority' || (Array.isArray(row.fields?.priority_order) && row.fields.priority_order.length)) {
+            order.push({ decision: row.id, product: productId, kind: row.fields?.kind ?? 'decision', date: row.fields?.date ?? '', text: clean(row.fields?.text ?? row.title, 400), priority_order: row.fields?.priority_order ?? [], citation: { decision: row.id, date: row.fields?.date ?? '', source: row.fields?.source ?? '' } });
+          }
+        }
+      }
+      order.sort((a, b) => String(b.date).localeCompare(String(a.date)));
+
+      // D3 rule 2: a row names its product. The board does not group, so every
+      // line carries the id (review H6).
+      const where_ = (row) => (row.product_named ? `${row.product_named} (not registered)` : row.product);
+      const section = (title, list, line) => [`${title} (${list.length})`, ...(list.length ? [...list.slice(0, SHOWN).map(line), ...(list.length > SHOWN ? [`   and ${list.length - SHOWN} more, in the rows`] : [])] : ['   nothing recorded'])].join('\n');
+      const block = [
+        `Built, pending, possible — ${only ?? `every product${unregisteredShown ? `, and ${plural(unregisteredShown, 'item')} that name${unregisteredShown === 1 ? 's' : ''} none` : ''}`} · read ${readAt.slice(0, 19)}Z${since ? ` · since ${since}` : ''}`,
+        section(since ? `Built since ${since}` : 'Built', built, (row) => listLine(row.title, `${where_(row)} · ${row.verdict} ${day(row.delivered_at)} · ${prsOf(row)} · ${row.item}${row.mark_id ? ` · mark ${row.mark_id.slice(0, 8)}` : ''}`)),
+        section('Building', building, (row) => listLine(`${row.title} · ${row.stage || 'no stage'} · next: ${row.next_step || 'not set'}`, `${where_(row)} · ${row.item} · ${row.days_since_last_change === null ? 'no movement on record' : `${plural(row.days_since_last_change, 'day')} since ${row.last_change_source}`}`)),
+        section('Pending, parked until someone returns to it', pending, (row) => listLine(`${row.title} — ${row.reason}`, `${where_(row)} · ${row.item}`)),
+        section('Possible, proposed and waiting for a yes', possible, (row) => listLine(row.title, `${where_(row)} · ${row.age_days === null ? 'age unknown' : `${plural(row.age_days, 'day')} old`} · ${row.item}`)),
+        section('The decisions that set the order', order, (row) => listLine(`${row.kind}: ${row.text}`, `${row.product} · ${row.date} · ${row.decision}`)),
+        ...(unregisteredTotal ? [[
+          `Not in the registry (${unregisteredTotal}${only ? '' : `, ${unregisteredShown} of them in the rows above, named "unregistered"`})`,
+          '   The slice L5 sweep gives them a product.',
+          ...(only ? ['   A read narrowed to one product cannot show them: an item with no product belongs to none.'] : []),
+        ].join('\n')] : []),
+      ].join('\n\n');
+      const rendered = scrubSecrets(block);
+      return scrubbed({
+        verb: 'built_pending_possible', read_at: readAt, product: only, since,
+        built, building, pending, possible, order, unregistered_total: unregisteredTotal, unregistered_in_rows: unregisteredShown,
+        rows: built.length + building.length + pending.length + possible.length,
+        redactions: redactions + rendered.redactions, text: rendered.text,
+      });
+    },
+  };
+  return verbs;
+}

package/work/lib/child-env.mjs

@@ -0,0 +1,11 @@
+// The variables a program started by Atlas receives: a short list, never the
+// Engram connection, never an ATLAS_WORK_* setting (F11 study, fix one).
+const CHILD_VARIABLES = ['PATH', 'HOME', 'USER', 'LOGNAME', 'LANG', 'LC_ALL', 'TMPDIR', 'XDG_CONFIG_HOME', 'SSL_CERT_FILE', 'SSH_AUTH_SOCK'];
+
+export function childEnvironment(env = process.env) {
+  const out = {};
+  for (const [name, value] of Object.entries(env)) {
+    if (CHILD_VARIABLES.includes(name) || name.startsWith('GH_') || name === 'GITHUB_TOKEN') out[name] = value;
+  }
+  return out;
+}