@arjunkhera/atlas 0.2.2 → 0.3.0

package/work/lib/questions.mjs

@@ -5,7 +5,7 @@
 // The verbs run behind the same door, the same journal and the same registry
 // 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 { refuse, text, oneOf, isoDate, url, stringList, LIVE_LIFECYCLES } from './verb-fields.mjs';
 
 // R5: the cost of waiting is a closed vocabulary, ranked. Index 0 costs most.
 export const COSTS = Object.freeze(['blocked-merge', 'paused-item', 'spend', 'date']);
@@ -62,13 +62,50 @@ function questionContext(value) {
   return context;
 }
 
+// Release 0.2.3: the owner's order. One rule for every view, the same one
+// part six of "where are we with X" uses: the current priority decision is the
+// newest decision of kind priority for the product. When it carries a
+// priority_order, the rows it names come first, in its order; every other row
+// follows, in the view's own order. When it carries none, no order applies:
+// an older list never stands in for the newest decision.
+export function currentPriorityOf(decisions, productId) {
+  return decisions
+    .filter((row) => row.fields?.product === productId && row.fields?.kind === 'priority')
+    .sort((a, b) => String(b.fields?.date ?? '').localeCompare(String(a.fields?.date ?? '')) || String(b.created_at ?? '').localeCompare(String(a.created_at ?? '')))[0] ?? null;
+}
+export function priorityOrderOf(decisions, productId) {
+  const latest = currentPriorityOf(decisions, productId);
+  if (!latest || !Array.isArray(latest.fields?.priority_order) || !latest.fields.priority_order.length) return null;
+  return { decision: latest.id, date: latest.fields?.date ?? '', rank: new Map(latest.fields.priority_order.map((id, index) => [id, index])) };
+}
+// orders maps a product id to priorityOrderOf's result, or to null.
+export const byPriority = (orders, fallback) => (a, b) => {
+  const ra = orders.get(a.product)?.rank.get(a.item);
+  const rb = orders.get(b.product)?.rank.get(b.item);
+  if (ra !== undefined && rb !== undefined) return ra - rb;
+  if (ra !== undefined) return -1;
+  if (rb !== undefined) return 1;
+  return fallback(a, b);
+};
+export const orderNote = (orders, row) => {
+  const rank = orders.get(row.product)?.rank.get(row.item);
+  return rank === undefined ? '' : ` · your order: ${rank + 1}`;
+};
+// Release 0.2.3: what an item waits on, as one short phrase for a row.
+export function waitsOnLine(waits) {
+  if (!waits || typeof waits !== 'object' || !waits.on) return '';
+  const what = { 'owner-decision': 'your decision', 'owner-action': 'your action', item: 'another item', gate: 'the gate', nothing: 'nothing' }[waits.on] ?? String(waits.on);
+  return `waits on ${what}${waits.item ? ` ${waits.item}` : ''}${waits.note ? `: ${waits.note}` : ''}`;
+}
+
 // Row line two: the id is the citation a reader types back, so the title gives
 // way to it, not the other way round (review G6).
-export function itemLine(item, product) {
+export function itemLine(item, product, lifecycle = 'active') {
   // Each part is flattened on its own, so no field in the graph can add a
   // fourth line to a three-line row (review G8). The separator is added after
-  // the flattening, because flattening also trims the ends.
-  const tail = oneLine(`${product} · ${item.fields?.stage ?? 'unknown stage'} · ${item.id}`);
+  // the flattening, because flattening also trims the ends. An item that is
+  // not active says so in place of its stage (release 0.2.3).
+  const tail = oneLine(`${product} · ${lifecycle === 'active' ? (item.fields?.stage ?? 'unknown stage') : `item ${lifecycle}`} · ${item.id}`);
   const budget = ROW_LINE_MAX - tail.length - 3;
   if (budget < 1) return oneLine(`${oneLine(item.title)} · ${tail}`);
   return `${oneLine(item.title, budget)} · ${tail}`;
@@ -134,6 +171,7 @@ export function createQuestionVerbs(core) {
       const prior = await landed(type, requestId, meta);
       // A retry after an interrupted write finds the record and re-makes the edge it lost (review G1).
       if (prior) { await edge(prior, item, 'references', requestId); return { verb: 'question_ask', question_id: prior.id, version: prior.version, status: prior.fields.status, item: prior.fields.item, product: prior.fields.product, cost: prior.fields.cost, replayed_from_graph: true }; }
+      if (item.fields?.lifecycle === 'dropped') refuse(`item ${item.id} is dropped; the owner closed it, so a question on it can never need him`);
       const entity = await create(type, requestId, 'question_ask', {
         digest: meta?.digest, title: oneLine(questionText, 200), body: questionText,
         fields: {
@@ -250,20 +288,23 @@ export function createQuestionVerbs(core) {
       for (const row of open) {
         const item = items.get(row.fields.item) ?? null;
         const lifecycle = item?.fields?.lifecycle ?? 'unknown';
-        // D3 rule 1: active items only. A question on any other item is named, not dropped in silence.
-        if (lifecycle !== 'active') { omitted.push({ question_id: row.id, item: row.fields.item, item_lifecycle: lifecycle, reason: item ? `the item is ${lifecycle}; paused and proposed items are backlog` : (unreadable.get(row.fields.item) ?? 'the item cannot be read') }); continue; }
+        // Release 0.2.3: a question on a
+        // proposed or paused item still needs him, so it is a row. D3 rule 1
+        // kept active items only, and it hid real questions. A question on a
+        // done or dropped item is named, not dropped in silence.
+        if (!LIVE_LIFECYCLES.includes(lifecycle)) { omitted.push({ question_id: row.id, item: row.fields.item, item_lifecycle: lifecycle, reason: item ? `the item is ${lifecycle}; only a proposed, active or paused item can still need you` : (unreadable.get(row.fields.item) ?? 'the item cannot be read') }); continue; }
         const cost = row.fields.cost;
         const rank = COSTS.indexOf(cost);
         const asked = row.fields.asked_by ?? {};
         kept.push({
-          question_id: row.id, product: row.fields.product, item: item.id, cost, cost_rank: rank === -1 ? COSTS.length : rank,
+          question_id: row.id, product: row.fields.product, item: item.id, item_lifecycle: lifecycle, cost, cost_rank: rank === -1 ? COSTS.length : rank,
           asked_at: row.fields.asked_at ?? row.created_at ?? '', asked_by: asked.agent ?? 'unknown',
           lines: [
             oneLine(row.fields.text),
-            itemLine(item, row.fields.product),
+            itemLine(item, row.fields.product, lifecycle),
             oneLine(`${cost}: ${COST_MEANING[cost] ?? 'cost outside the vocabulary'} · asked by ${asked.agent ?? 'unknown'} on ${(row.fields.asked_at ?? '').slice(0, 10)}`),
           ],
-          folded: { question: row.fields.text, context: row.fields.context ?? {}, asked_by: asked, item_title: item.title, item_stage: item.fields.stage ?? '', item_next_step: item.fields.next_step ?? '' },
+          folded: { question: row.fields.text, context: row.fields.context ?? {}, asked_by: asked, item_title: item.title, item_stage: item.fields.stage ?? '', item_next_step: item.fields.next_step ?? '', item_waits_on: item.fields.waits_on ?? null },
           citation: { question: row.id, item: item.id, read_at: readAt },
         });
       }
@@ -271,7 +312,10 @@ export function createQuestionVerbs(core) {
       const products = [...new Set(kept.map((row) => row.product))].sort();
       const byProduct = products.map((product) => ({ product, rows: kept.filter((row) => row.product === product) }));
       const render = byProduct.map((group) => [`${group.product} — needs you (${group.rows.length})`, ...group.rows.flatMap((row, index) => row.lines.map((line, position) => `${position === 0 ? `${index + 1}. ` : '   '}${line}`))].join('\n')).join('\n\n');
-      return { verb: 'needs_me', read_at: readAt, product: only, row_budget: ROW_LINES, rows: kept.length, products: byProduct, omitted, text: render || 'Nothing needs you: no open question on an active item.' };
+      // A question left open on a done or dropped item is not a row, but the
+      // text says it exists, so nothing waits in silence.
+      const aside = omitted.length ? `${omitted.length} open question${omitted.length === 1 ? '' : 's'} sit${omitted.length === 1 ? 's' : ''} on done, dropped or unreadable items; they are listed under omitted.` : '';
+      return { verb: 'needs_me', read_at: readAt, product: only, row_budget: ROW_LINES, rows: kept.length, products: byProduct, omitted, text: [render || 'Nothing needs you: no open question on a proposed, active or paused item.', aside].filter(Boolean).join('\n\n') };
     },
   };
   return verbs;

package/work/lib/verb-fields.mjs

@@ -5,6 +5,9 @@
 import { createHash } from 'node:crypto';
 
 export const MAX_TEXT = 20_000;
+// 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']);
 
 export class VerbError extends Error {
   constructor(message, code = 'refused') { super(message); this.name = 'VerbError'; this.code = code; }
@@ -45,6 +48,37 @@ export function url(value, name) {
   if (!['http:', 'https:'].includes(parsed.protocol)) refuse(`${name} must be an http or https URL`);
   return value;
 }
+// What a repo is (stage 1 of the target design). A record holds a list,
+// because a monorepo or a plugin that is also a library is more than one
+// thing. Manifest 0.5.0 held one scalar kind, and an old record still has
+// only that, so every reader goes through repoKinds.
+export const REPO_KINDS = Object.freeze(['service', 'library', 'schema', 'cli', 'plugin']);
+// The kinds whose merge is not their delivery. A service runs after the
+// merge, and a schema repo applies its migration after the merge, so both
+// keep the live checks of item_done.
+export const LIVE_KINDS = Object.freeze(['service', 'schema']);
+
+export function repoKinds(fields) {
+  if (Array.isArray(fields?.kinds) && fields.kinds.length) return [...fields.kinds];
+  return typeof fields?.kind === 'string' && fields.kind ? [fields.kind] : [];
+}
+
+// The kinds a repo_add or repo_edit call gives, from `kinds` or the older
+// `kind`. Returns null when the call names neither. The scalar written beside
+// the list is the first live kind, else the first kind, so a reader of 0.5.0
+// still takes the strict path when the list needs it.
+export function kindsFromArgs(args) {
+  if (args.kinds !== undefined && args.kind !== undefined) refuse('give kinds or kind, not both');
+  if (args.kinds !== undefined) {
+    const list = stringList(args.kinds, 'kinds', { max: REPO_KINDS.length });
+    if (!list.length) refuse('kinds must name at least one kind');
+    for (const one of list) oneOf(one, 'each of kinds', REPO_KINDS);
+    return { kinds: list, kind: list.find((one) => LIVE_KINDS.includes(one)) ?? list[0] };
+  }
+  if (args.kind !== undefined) { const kind = oneOf(args.kind, 'kind', REPO_KINDS); return { kinds: [kind], kind }; }
+  return null;
+}
+
 export function stringList(value, name, { max = 64 } = {}) {
   if (!Array.isArray(value)) refuse(`${name} must be an array of strings`);
   if (value.length > max) refuse(`${name} holds more than ${max} entries`);

package/work/lib/verbs.mjs

@@ -11,24 +11,26 @@
 // lock block L1, L2 and L3. Every write carries request_id and writer. The
 // server, not the caller, supplies the session. Unknown ids are refused.
 // M2 slice L1 adds the repo kind in 0.5.0, which carries 0.4.0 whole.
-import manifestCurrent from '../manifest-0.5.0.json' with { type: 'json' };
+// Stage 1 of the target design adds kinds, a list, in 0.6.0.
+import manifestCurrent from '../manifest-0.6.0.json' with { type: 'json' };
 import { EngramHttpError } from './client.mjs';
-import { VerbError, refuse, canonicalJson, sha256, text, oneOf, origin, url, stringList } from './verb-fields.mjs';
+import { VerbError, refuse, canonicalJson, sha256, text, oneOf, origin, url, stringList, LIVE_LIFECYCLES, REPO_KINDS, LIVE_KINDS, repoKinds, kindsFromArgs } from './verb-fields.mjs';
 import { createQuestionVerbs, COSTS, QUESTION_WRITE_VERBS, QUESTION_READ_VERBS } from './questions.mjs';
 import { createDeliveryVerbs, DELIVERY_WRITE_VERBS, DELIVERY_READ_VERBS } from './delivery.mjs';
 import { createCapabilityVerbs, CAPABILITY_READ_VERBS } from './capability.mjs';
 import { createSweepVerbs, SWEEP_WRITE_VERBS, SWEEP_READ_VERBS } from './sweep.mjs';
 
-export { VerbError, canonicalJson, sha256, COSTS };
-export const MANIFEST_VERSION = '0.5.0';
+export { VerbError, canonicalJson, sha256, COSTS, LIVE_LIFECYCLES, REPO_KINDS, LIVE_KINDS, repoKinds };
+export const MANIFEST_VERSION = '0.6.0';
 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']);
 export const TIERS = Object.freeze(['hotfix', 'standard', 'initiative']);
 export const DRIVERS = Object.freeze(['owner-led', 'agent']);
-// The repo kind of M2 amendment A1.5. The repo-shape check reads it to decide
-// which of the seven files a repo needs.
-export const REPO_KINDS = Object.freeze(['service', 'library', 'schema']);
+// What an item waits on (release 0.2.3). One line on the item, shown on its
+// rows. "item" names another work item by id.
+export const WAITS_ON = Object.freeze(['owner-decision', 'owner-action', 'item', 'gate', 'nothing']);
+const MAX_EDITS = 20;
 export const LINK_KINDS = Object.freeze(['pr', 'issue', 'artifact', 'design-doc', 'conversation', 'research', 'slack', 'drive', 'other']);
 export const AUTHORITY_FIELDS = Object.freeze(['writer', 'session', 'actor', 'owner_present', 'agent', 'token_id']);
 const MAX_CHILDREN = 32;
@@ -131,11 +133,17 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
   }
   const requireOwner = (verb) => { if (!ownerPresent) refuse(`${verb} needs the owner-present flag on the server host (ATLAS_WORK_OWNER_PRESENT=1)`); };
 
-  async function patch(entity, verb, requestId, fields, { tags, title, digest } = {}) {
+  // fields may be a function of the record as read, so a retry after a 409
+  // recomputes it from the newer record. guard, when given, is checked again on
+  // that newer record: a write that another writer made wrong is refused, not
+  // forced through (release 0.2.3).
+  async function patch(entity, verb, requestId, fields, { tags, title, digest, guard } = {}) {
     let current = entity;
     for (let attempt = 0; attempt < 2; attempt += 1) {
+      if (attempt > 0 && guard) guard(current);
+      const next = typeof fields === 'function' ? fields(current) : fields;
       const receipts = { ...(current.fields?.atlas_receipts ?? {}), [requestId]: { verb, at: now(), ...(digest ? { digest } : {}) } };
-      const body = { version: current.version, fields: { ...(current.fields ?? {}), ...fields, writer: label, request_id: requestId, atlas_receipts: receipts } };
+      const body = { version: current.version, fields: { ...(current.fields ?? {}), ...next, writer: label, request_id: requestId, atlas_receipts: receipts } };
       if (tags) body.tags = [...new Set([...(current.tags ?? []), ...tags])];
       if (title) body.title = title;
       try { await client.updateEntity(current.id, body); return client.getEntity(current.id); }
@@ -230,7 +238,7 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
     async registry_list() {
       const reg = await registry();
       const products = [...reg.products.values()].map((row) => ({ registry_id: row.fields.registry_id, name: row.fields.name, entity_id: row.id, project_id: row.fields.project_id ?? null, notes: row.fields.notes ?? '',
-        repos: [...reg.repos.values()].filter((repo) => repo.fields.product === row.fields.registry_id).map((repo) => ({ registry_id: repo.fields.registry_id, entity_id: repo.id, kind: repo.fields.kind ?? null, default_branch: repo.fields.default_branch, notes: repo.fields.notes ?? '' })) }));
+        repos: [...reg.repos.values()].filter((repo) => repo.fields.product === row.fields.registry_id).map((repo) => ({ registry_id: repo.fields.registry_id, entity_id: repo.id, kind: repo.fields.kind ?? null, kinds: repoKinds(repo.fields), default_branch: repo.fields.default_branch, notes: repo.fields.notes ?? '' })) }));
       return { verb: 'registry_list', products, read_at: now() };
     },
 
@@ -288,7 +296,9 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
       if (typeof readGitHub !== 'function') refuse('repo add needs a GitHub reader for the push-rights check');
       const registryId = text(args.registry_id, 'registry_id', { max: 200 });
       if (!REPO_ID.test(registryId)) refuse('registry_id must be a GitHub "owner/repo" name');
-      const kind = oneOf(args.kind, 'kind', REPO_KINDS);
+      const given = kindsFromArgs(args);
+      if (!given) refuse('kind is required: give kinds, a list of what the repo is');
+      const { kinds, kind } = given;
       const notes = text(args.notes, 'notes', { optional: true, max: 4000 }) ?? '';
       const reg = await registry();
       const product = await requireProduct(args.product, reg);
@@ -300,10 +310,10 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
       const defaultBranch = text(github.default_branch, 'GitHub default_branch', { max: 200 });
       const type = await typeNamed('repo');
       const prior = await landed(type, requestId, meta);
-      if (prior) { await edge(prior, product, 'part_of', requestId); return { verb: 'repo_add', registry_id: prior.fields.registry_id, product: prior.fields.product, kind: prior.fields.kind ?? null, default_branch: prior.fields.default_branch, entity_id: prior.id, version: prior.version, push_rights: true, replayed_from_graph: true }; }
-      const entity = await create(type, requestId, 'repo_add', { digest: meta?.digest, title: registryId, body: `Atlas repo record for ${registryId}, product ${product.fields.registry_id}. Kind: ${kind}. Default branch: ${defaultBranch}.`, fields: { registry_id: registryId, product: product.fields.registry_id, kind, default_branch: defaultBranch, notes, github_url: github.html_url ?? `https://github.com/${registryId}` }, tags: ['atlas-registry', `product:${product.fields.registry_id}`, `repo:${registryId}`] });
+      if (prior) { await edge(prior, product, 'part_of', requestId); return { verb: 'repo_add', registry_id: prior.fields.registry_id, product: prior.fields.product, kind: prior.fields.kind ?? null, kinds: repoKinds(prior.fields), default_branch: prior.fields.default_branch, entity_id: prior.id, version: prior.version, push_rights: true, replayed_from_graph: true }; }
+      const entity = await create(type, requestId, 'repo_add', { digest: meta?.digest, title: registryId, body: `Atlas repo record for ${registryId}, product ${product.fields.registry_id}. Kinds: ${kinds.join(', ')}. Default branch: ${defaultBranch}.`, fields: { registry_id: registryId, product: product.fields.registry_id, kind, kinds, default_branch: defaultBranch, notes, github_url: github.html_url ?? `https://github.com/${registryId}` }, tags: ['atlas-registry', `product:${product.fields.registry_id}`, `repo:${registryId}`] });
       await edge(entity, product, 'part_of', requestId);
-      return { verb: 'repo_add', registry_id: registryId, product: product.fields.registry_id, kind, default_branch: defaultBranch, entity_id: entity.id, version: entity.version, push_rights: true };
+      return { verb: 'repo_add', registry_id: registryId, product: product.fields.registry_id, kind, kinds, default_branch: defaultBranch, entity_id: entity.id, version: entity.version, push_rights: true };
     },
 
     async repo_edit(args, requestId, meta) {
@@ -315,7 +325,8 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
       await requireProduct(record.fields.product, reg);
       const fields = {};
       if (args.notes !== undefined) fields.notes = text(args.notes, 'notes', { max: 4000 });
-      if (args.kind !== undefined) fields.kind = oneOf(args.kind, 'kind', REPO_KINDS);
+      const given = kindsFromArgs(args);
+      if (given) { fields.kind = given.kind; fields.kinds = given.kinds; }
       if (args.refresh_default_branch === true) {
         if (typeof readGitHub !== 'function') refuse('refreshing the default branch needs a GitHub reader');
         const github = await readGitHub(`repos/${registryId}`);
@@ -323,10 +334,10 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
         fields.default_branch = text(github.default_branch, 'GitHub default_branch', { max: 200 });
       }
       if (alreadyPatched(record, requestId, meta)) return { verb: 'repo_edit', registry_id: registryId, entity_id: record.id, version: record.version, changed: [], replayed_from_graph: true };
-      if (!Object.keys(fields).length) refuse('repo edit needs kind, notes or refresh_default_branch; registry_id and product are immutable');
+      if (!Object.keys(fields).length) refuse('repo edit needs kind, notes or refresh_default_branch (kind may be given as kinds, a list); registry_id and product are immutable');
       // The kind is a field, not a tag: repo edit may change it, and a tag cannot be dropped.
       const entity = await patch(record, 'repo_edit', requestId, fields, { digest: meta?.digest });
-      return { verb: 'repo_edit', registry_id: registryId, entity_id: entity.id, version: entity.version, kind: entity.fields.kind ?? null, changed: Object.keys(fields) };
+      return { verb: 'repo_edit', registry_id: registryId, entity_id: entity.id, version: entity.version, kind: entity.fields.kind ?? null, kinds: repoKinds(entity.fields), changed: Object.keys(fields) };
     },
 
     async item_propose(args, requestId, meta) {
@@ -430,12 +441,82 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
       const item = await requireItem(args.item_id);
       const reason = text(args.reason, 'reason', { max: 2000 });
       if (alreadyPatched(item, requestId, meta)) return { verb: 'item_resume', item_id: item.id, version: item.version, lifecycle: item.fields.lifecycle, reason, replayed_from_graph: true };
-      if (item.fields?.lifecycle !== 'paused') refuse(`item ${item.id} is ${item.fields?.lifecycle}; only a paused item can be resumed`);
+      // Release 0.2.3: resume also undoes a drop, back to the lifecycle the
+      // item left. The drop's words stay on the item.
+      if (item.fields?.lifecycle === 'dropped') {
+        const back = LIVE_LIFECYCLES.includes(item.fields.dropped_from) ? item.fields.dropped_from : 'proposed';
+        const undone = await patch(item, 'item_resume', requestId, { lifecycle: back, resume_reason: reason, resumed_at: now(), undropped_at: now() }, { digest: meta?.digest });
+        return { verb: 'item_resume', item_id: undone.id, version: undone.version, lifecycle: back, reason, undid_drop: true };
+      }
+      if (item.fields?.lifecycle !== 'paused') refuse(`item ${item.id} is ${item.fields?.lifecycle}; only a paused or dropped item can be resumed`);
       const lifecycle = item.fields.parked_from === 'proposed' ? 'proposed' : 'active';
       const entity = await patch(item, 'item_resume', requestId, { lifecycle, pause_reason: '', resume_reason: reason, resumed_at: now(), parked_from: null }, { digest: meta?.digest });
       return { verb: 'item_resume', item_id: entity.id, version: entity.version, lifecycle, reason };
     },
 
+    // Release 0.2.3: the owner drops a piece of work in his own words. A
+    // dropped item stays in the graph; no live view lists it. A delivered item
+    // is not dropped: item_reopen is its path.
+    async item_drop(args, requestId, meta) {
+      requireOwner('item drop');
+      const item = await requireItem(args.item_id);
+      const words = origin(args.origin);
+      if (alreadyPatched(item, requestId, meta)) return { verb: 'item_drop', item_id: item.id, version: item.version, lifecycle: item.fields.lifecycle, dropped_from: item.fields.dropped_from ?? null, replayed_from_graph: true };
+      const live = (current) => { if (!LIVE_LIFECYCLES.includes(current.fields?.lifecycle)) refuse(`item ${current.id} is ${current.fields?.lifecycle}; only a proposed, active or paused item can be dropped`); };
+      live(item);
+      const at = now();
+      const entity = await patch(item, 'item_drop', requestId, (current) => ({ lifecycle: 'dropped', drop_reason: words, dropped_at: at, dropped_from: current.fields.lifecycle }), { digest: meta?.digest, guard: live });
+      return { verb: 'item_drop', item_id: entity.id, version: entity.version, lifecycle: 'dropped', dropped_from: entity.fields?.dropped_from ?? item.fields.lifecycle, reason: words };
+    },
+
+    // Release 0.2.3: edit an item's next step, what it waits on, and its title.
+    // The next step and the wait are the lead's to keep true, so any
+    // in-session caller may change them. The title is the owner's words, so a
+    // new title needs the owner present. Each edit keeps the old values.
+    async item_edit(args, requestId, meta) {
+      const item = await requireItem(args.item_id);
+      const fields = item.fields ?? {};
+      if (alreadyPatched(item, requestId, meta)) return { verb: 'item_edit', item_id: item.id, version: item.version, title: item.title, next_step: fields.next_step ?? '', waits_on: fields.waits_on ?? null, replayed_from_graph: true };
+      const live = (current) => { if (!LIVE_LIFECYCLES.includes(current.fields?.lifecycle)) refuse(`item ${current.id} is ${current.fields?.lifecycle}; only a proposed, active or paused item can be edited`); };
+      live(item);
+      const change = {}, previous = {};
+      let title;
+      if (args.title !== undefined) {
+        requireOwner('item edit of a title');
+        title = text(args.title, 'title', { max: 300 });
+        if (title !== item.title) previous.title = item.title ?? '';
+      }
+      if (args.next_step !== undefined) {
+        change.next_step = text(args.next_step, 'next_step', { max: 1000 });
+        previous.next_step = fields.next_step ?? '';
+      }
+      if (args.waits_on !== undefined) {
+        const given = args.waits_on;
+        if (!given || typeof given !== 'object' || Array.isArray(given)) refuse(`waits_on must be { on, note?, item? }, with on one of ${WAITS_ON.join(', ')}`);
+        const wait = { on: oneOf(given.on, 'waits_on.on', WAITS_ON) };
+        const note = text(given.note, 'waits_on.note', { optional: true, max: 300 });
+        if (note) wait.note = note;
+        if (wait.on === 'item') {
+          const other = await requireItem(given.item);
+          if (other.id === item.id) refuse('an item cannot wait on itself');
+          wait.item = other.id;
+        } else if (given.item !== undefined) refuse('waits_on.item is only for on: item');
+        if (wait.on !== 'nothing' && wait.on !== 'item' && !wait.note) refuse(`waits_on.note is required for on: ${wait.on}; say what exactly it waits on`);
+        change.waits_on = wait;
+        previous.waits_on = fields.waits_on ?? null;
+      }
+      if (args.title === undefined && !Object.keys(change).length) refuse('item edit needs title, next_step or waits_on');
+      const reason = text(args.reason, 'reason', { optional: true, max: 1000 });
+      const entry = { at: now(), by: label.agent, previous, ...(reason ? { reason } : {}) };
+      // The history keeps the last MAX_EDITS entries. The first title the
+      // owner gave is kept on its own, so a title never falls out of it.
+      const entity = await patch(item, 'item_edit', requestId, (current) => ({
+        ...change, edits: [...(Array.isArray(current.fields?.edits) ? current.fields.edits : []), entry].slice(-MAX_EDITS),
+        ...(previous.title !== undefined && current.fields?.first_title === undefined ? { first_title: previous.title } : {}),
+      }), { digest: meta?.digest, guard: live, ...(title ? { title } : {}) });
+      return { verb: 'item_edit', item_id: entity.id, version: entity.version, title: entity.title, next_step: entity.fields?.next_step ?? '', waits_on: entity.fields?.waits_on ?? null, changed: [...(args.title !== undefined ? ['title'] : []), ...Object.keys(change)] };
+    },
+
     async item_stage(args, requestId, meta) {
       const item = await requireItem(args.item_id);
       const stage = oneOf(args.stage, 'stage', STAGES);
@@ -474,7 +555,7 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
   Object.assign(verbs, createCapabilityVerbs({ ...core, readGitHub }));
   Object.assign(verbs, createSweepVerbs({ ...core, requireRepos, inFlight: (args) => verbs.in_flight(args), stages: STAGES, tiers: TIERS, drivers: DRIVERS }));
 
-  const WRITE_VERBS = Object.freeze(['setup', 'product_add', 'product_edit', 'repo_add', 'repo_edit', 'item_propose', 'item_lock', 'item_split', 'item_park', 'item_resume', 'item_stage', 'item_link', ...QUESTION_WRITE_VERBS, ...DELIVERY_WRITE_VERBS, ...SWEEP_WRITE_VERBS]);
+  const WRITE_VERBS = Object.freeze(['setup', 'product_add', 'product_edit', 'repo_add', 'repo_edit', 'item_propose', 'item_lock', 'item_split', 'item_park', 'item_resume', 'item_drop', 'item_edit', 'item_stage', 'item_link', ...QUESTION_WRITE_VERBS, ...DELIVERY_WRITE_VERBS, ...SWEEP_WRITE_VERBS]);
   const READ_VERBS = Object.freeze(['registry_list', ...QUESTION_READ_VERBS, ...DELIVERY_READ_VERBS, ...CAPABILITY_READ_VERBS, ...SWEEP_READ_VERBS]);
 
   async function run(verb, args = {}) {

package/work/{manifest-0.5.0.json → manifest-0.6.0.json}

@@ -1,8 +1,8 @@
 {
   "name": "atlas-work",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "kind": "extension",
-  "description": "Atlas work records: products and repos as the registry, work items, questions, decisions, receipts, delivery and reopen marks, and their relations. Version 0.4.0 adds mark, the delivery fields on the item and the health endpoint on the product (M1 slice L3, 2026-09-17). Version 0.3.0 added question and receipt. Version 0.2.0 dropped atlas_key and write_class.",
+  "description": "Atlas work records: products and repos as the registry, work items, questions, decisions, receipts, delivery and reopen marks, and their relations. Version 0.6.0 adds kinds, a list, on the repo. Version 0.5.0 added the repo kind. Version 0.4.0 adds mark, the delivery fields on the item and the health endpoint on the product (M1 slice L3, 2026-09-17). Version 0.3.0 added question and receipt. Version 0.2.0 dropped atlas_key and write_class.",
   "capability": {
     "semantics_version": ">=1.0.0 <2.0.0"
   },
@@ -93,6 +93,9 @@
                 "kind": {
                   "type": "string"
                 },
+                "kinds": {
+                  "type": "array"
+                },
                 "notes": {
                   "type": "string",
                   "default": ""
@@ -591,7 +594,7 @@
     ],
     "0.3.0": [
       "Adds question and receipt. A question holds its text, item, product, asker, date, cost of waiting and the context to answer; a receipt holds the rendered answer the owner acted on and the decision it belongs to.",
-      "Re-declares decision with the fields of design page D1: the owner\u2019s words, date, source, the question it answers, the items it touches, the priority order, and what it replaces. $required is unchanged, so an older decision record still validates.",
+      "Re-declares decision with the fields of design page D1: the owner’s words, date, source, the question it answers, the items it touches, the priority order, and what it replaces. $required is unchanged, so an older decision record still validates.",
       "No new edge type. Questions, decisions and receipts point at their records by field and carry one references edge each."
     ],
     "0.4.0": [
@@ -604,6 +607,9 @@
       "kind is not a required field, so every repo record written under 0.2.0, 0.3.0 and 0.4.0 still validates. repo edit fills it.",
       "Nothing else changes. 0.4.0 and its mark record are carried over whole.",
       "Why 0.5.0 and not 0.4.0: M1 slice L3 published 0.4.0 for the mark record on 2026-09-17, in a session that ran beside this one. A published version never changes, so this slice took the next number. Owner decision, 2026-09-17."
+    ],
+    "0.6.0": [
+      "Added: kinds on the repo record, a list of what the repo is (service, library, schema, cli, plugin). A monorepo or a plugin that is also a library holds more than one. The scalar kind stays, so a record written under 0.5.0 still validates and an older reader still reads it. Stage 1 of the target design."
     ]
   }
 }

package/work/mcp.mjs

@@ -14,7 +14,7 @@ import { existsSync, realpathSync, readFileSync, writeFileSync, mkdirSync } from
 import { fileURLToPath } from 'node:url';
 import { createEngramClient } from './lib/client.mjs';
 import { createActionStore } from './lib/action-store.mjs';
-import { createVerbs, STAGES, TIERS, DRIVERS, LINK_KINDS, REPO_KINDS, MANIFEST_VERSION, COSTS } from './lib/verbs.mjs';
+import { createVerbs, STAGES, TIERS, DRIVERS, LINK_KINDS, REPO_KINDS, WAITS_ON, MANIFEST_VERSION, COSTS } from './lib/verbs.mjs';
 import { COST_MEANING, DECISION_KINDS } from './lib/questions.mjs';
 import { FATAL_CONCLUSIONS } from './lib/delivery.mjs';
 import { createMcpServer } from './lib/mcp-stdio.mjs';
@@ -25,6 +25,7 @@ const ATLAS_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.
 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.') } };
 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.';
 
 const CODE_FINDING = { type: 'object', required: ['statement', 'path', 'line'], properties: { name: S('Short label for the finding.'), statement: S('One sentence about what the code does, or what bounds it.'), path: S('Repo-relative path the claim is read from. A never-read path is refused.'), line: { type: 'integer', description: 'The line the claim is read from, 1 or higher.' }, quote: S('The minimal proving line. Never from a never-quote path; a quote from one is refused.') } };
@@ -33,16 +34,18 @@ const CODE_DIGEST = { type: 'object', description: 'One sub-agent digest for one
 
 export const TOOLS = [
   { name: 'registry_list', description: `List the registered products and their repos with registry ids and entity ids. When: before any item verb, to find the ids to pass. Scope: read, no owner flag needed. ${RULES}`, inputSchema: { type: 'object', properties: {}, additionalProperties: false } },
-  { name: 'setup', description: `Publish atlas-work ${MANIFEST_VERSION} to the tenant's Forge and register its types (product, repo with its kind, container, decision, question, receipt, mark and the surviving edges). Idempotent. When: once per tenant, before the first product add, and again after a manifest change. Owner present only. ${RULES}`, inputSchema: { type: 'object', required: ['request_id'], properties: { request_id: REQUEST_ID }, additionalProperties: false } },
+  { name: 'setup', description: `Publish atlas-work ${MANIFEST_VERSION} to the tenant's Forge and register its types (product, repo with its kinds, container, decision, question, receipt, mark and the surviving edges). Idempotent. When: once per tenant, before the first product add, and again after a manifest change. Owner present only. ${RULES}`, inputSchema: { type: 'object', required: ['request_id'], properties: { request_id: REQUEST_ID }, additionalProperties: false } },
   { name: 'product_add', description: `Register a product in the name registry. Refuses when the id exists. When: a product gets its first work item. Owner present only. registry_id is a lowercase slug and is immutable. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'registry_id', 'name'], properties: { request_id: REQUEST_ID, registry_id: S('Lowercase slug, for example "engram". Immutable.'), name: S('Display name.'), project_id: S('Entity id of the existing Engram project entity this product links to.'), health_url: S('Absolute https URL of the deployed app\'s health endpoint. The done verb reads the deployed commit there, and every live check must be on this origin.'), check_paths: { type: 'array', items: { type: 'string' }, description: 'Absolute paths on that origin the functional check of item_done may read, for example ["/v1/housekeeping"]. Unset, the check may read only the health endpoint\'s own path.' }, notes: S('Free text.') }, additionalProperties: false } },
   { name: 'product_edit', description: `Change a product's name, notes, health endpoint, check paths or project link. Refuses an unknown id. The registry id never changes. Owner present only. ${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.' }, 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 kind says which of the seven Atlas files the repo needs. Refuses an unknown product id and an existing repo id; repo ids are immutable. Owner present only. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'registry_id', 'product', 'kind'], properties: { request_id: REQUEST_ID, registry_id: S('GitHub "owner/repo", exact spelling.'), product: S('Existing product id.'), kind: S(`What the repo is. One of ${REPO_KINDS.join(', ')}. The repo-shape check reads it.`), notes: S('Free text.') }, additionalProperties: false } },
-  { name: 'repo_edit', description: `Change a repo's kind or notes, or refresh its default branch from GitHub. registry_id and product never change. Owner present only. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'registry_id'], properties: { request_id: REQUEST_ID, registry_id: S('Existing repo id.'), kind: S(`What the repo is. One of ${REPO_KINDS.join(', ')}. The repo-shape check reads it.`), notes: S('Free text.'), refresh_default_branch: { type: 'boolean', description: 'Re-read the default branch and push rights from GitHub.' } }, 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. Owner present only. ${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. Owner present only. ${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. Owner present only. ${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: `Lock a proposed or active item: product and repos by registry id, the scope (text, optional design doc URL and acceptance-criteria hash), and the owner's words as origin. 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. When: the owner says "lock". Owner present only. ${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 accepted scope, in full.'), design_doc: S('URL of the design doc at its lock commit.'), acceptance_criteria_hash: S('64-hex sha256 of the frozen acceptance text, when the design doc carries one.') } }, 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_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. Owner present only. ${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('Old records only: a 64-hex sha256 a design doc once carried. Omit it.') } }, 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. Owner present only. ${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 and appear only on request. Refuses a missing reason. Owner present only. ${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. Owner present only. ${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_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. Owner present only. ${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. Owner present only. ${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. Owner present only. ${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, or its title. Each edit appends the old values to the item's edits, and the last 20 are kept; the first title stays in first_title. When: the next step or the wait changes; the lead keeps them true at the end of each session. No owner flag for next_step and waits_on; a new title is the owner's words, so it needs the owner present. ${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(', ')}.`), note: S('What exactly it waits on, in plain words. Required unless on is item or nothing.'), item: S('The item id it waits on, for on: item.') } }, title: S("A new title, in the owner's words. Owner present only."), 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. No owner flag needed. ${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_link', description: `Attach a typed link (kind, url, role, note) to an item: a PR, an issue, an artifact, a design doc, a conversation. When: any in-session agent has a link the item should carry, for example a PR it opened. No owner flag needed. A duplicate kind and url is a no-op. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'item_id', 'kind', 'url'], properties: { request_id: REQUEST_ID, item_id: S('Item id.'), kind: S(`One of ${LINK_KINDS.join(', ')}.`), url: S('Absolute http or https URL.'), role: S('What the link is to the item, for example "delivers", "design", "evidence".'), note: S('One line.') }, additionalProperties: false } },
   { name: 'item_adopt', description: `Give an existing work item its product and repos. This is the slice L5 sweep: most items in the tenant were made before the registry existed and name no product, so no view can place them. Refuses an item that already names another registered product; an item is named once. The audit stamps adopted_at and adopted_from move only when the product actually changes. When: the owner says which product a piece of work belongs to. Owner present only. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'item_id', 'product', 'repos'], properties: { request_id: REQUEST_ID, item_id: S('Item id.'), product: S('Product id the item belongs to.'), repos: { type: 'array', items: { type: 'string' }, description: 'Repo ids under that product. Required. Pass an empty list for an item that has no repo, such as a container root; a repo of another product is dropped and named in dropped_repos.' }, stage: S(`One of ${STAGES.join(', ')}. Active items only.`), tier: S(`One of ${TIERS.join(', ')}.`), driver: S(`One of ${DRIVERS.join(', ')}.`), next_step: S('One line: what happens next.') }, additionalProperties: false } },
@@ -50,11 +53,11 @@ export const TOOLS = [
   { name: 'question_answer', description: `Record the owner's answer to one open question. One call writes the decision in the owner's words, keeps the rendered answer as a receipt, and closes the question, so the "Needs me" view loses the row. Refuses an unknown question and one that is already answered. Owner present only. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'question_id', 'text', 'date'], properties: { request_id: REQUEST_ID, question_id: S('Entity id of the open question.'), text: S("The owner's answer, verbatim."), date: S('ISO date the owner said it, in the form YYYY-MM-DD.'), source: S('Where the words are on record: a chat turn, a doc URL, an issue.'), kind: S(`One of ${DECISION_KINDS.join(', ')}. Default answer.`), items: { type: 'array', items: { type: 'string' }, description: 'Item ids the decision touches. Default: the question\'s item.' }, priority_order: { type: 'array', items: { type: 'string' }, description: 'Item ids in the order the owner set.' }, replaces: S('Entity id of the decision this one replaces.'), rendered: S('The view text the owner acted on. Default: the question and the answer.'), view: S('Which view the owner read, for example needs-me.') }, additionalProperties: false } },
   { name: 'decision_record', description: `Record what the owner decided outside a question, in their own words. Refuses missing text and a missing date. Pass rendered to keep the view the owner acted on as a receipt in the same call. Owner present only. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'text', 'date'], properties: { request_id: REQUEST_ID, text: S("The owner's words, verbatim."), date: S('ISO date the owner said it.'), source: S('Where the words are on record.'), kind: S(`One of ${DECISION_KINDS.join(', ')}. Default decision.`), product: S('Product id the decision is about.'), items: { type: 'array', items: { type: 'string' }, description: 'Item ids the decision touches.' }, priority_order: { type: 'array', items: { type: 'string' }, description: 'Item ids in the order the owner set.' }, replaces: S('Entity id of the decision this one replaces.'), rendered: S('The view text the owner acted on.'), view: S('Which view the owner read.') }, additionalProperties: false } },
   { name: 'receipt_keep', description: `Keep the rendered answer the owner acted on and attach it to a decision. Refuses when there is no decision to attach to. Secret patterns are redacted before the write. Owner present only. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'decision_id', 'rendered'], properties: { request_id: REQUEST_ID, decision_id: S('Entity id of the decision this receipt belongs to.'), rendered: S('The answer as the owner read it.'), view: S('Which view it came from, for example needs-me.') }, additionalProperties: false } },
-  { name: 'item_done', description: `Mark an item delivered. What proves it follows the repo kind (amendment A1.7). A service repo gets the three read-only live checks: the deployed commit carries the pull requests, the health endpoint answers, and a functional check scoped to the change passes. Every check is a GET. The merge state of each pull request and the gate runs come from GitHub; the caller supplies none of them, and a red gate (${FATAL_CONCLUSIONS.join(', ')}) refuses the mark. A library or schema repo has no deploy target, so its delivery is proven by the merge and the gate alone: pass no functional, and the product needs no health_url. An item with no registered repo, or a repo whose kind was never set, keeps the three checks. The delivering agent calls this; the lead calls it to catch up a delivery made outside a session. No owner flag. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'item_id', 'prs'], properties: { request_id: REQUEST_ID, item_id: S('Item id. The item must be active, and its product must carry a health_url.'), prs: { type: 'array', items: { type: 'string' }, description: 'The merged GitHub pull request URLs this delivery shipped. Required: the item\'s own pr links are not read, because a link can be a design or a lock, not a delivery.' }, functional: { type: 'object', required: ['url', 'contains'], description: 'The read-only functional check. Required for a service repo, and refused for a library or schema repo. The verb GETs this URL once. No method, body or headers are accepted.', properties: { url: S('Absolute URL on the product health endpoint\'s origin, under one of the product\'s check_paths, and not the health endpoint itself.'), contains: { type: 'array', items: { type: 'string' }, description: 'Required. Strings the answer must carry, chosen so they exist only because of this change. Only whether each was found is recorded; the answer itself never enters the graph.' }, status: { type: 'number', description: 'Expected HTTP status, 2xx only. Default 200.' } } }, note: S('One line on what was delivered.') }, additionalProperties: false } },
+  { name: 'item_done', description: `Mark an item delivered. What proves it follows the repo kind (amendment A1.7). A service or schema repo gets the three read-only live checks: the deployed commit carries the pull requests, the health endpoint answers, and a functional check scoped to the change passes. Every check is a GET. The merge state of each pull request and the gate runs come from GitHub; the caller supplies none of them, and a red gate (${FATAL_CONCLUSIONS.join(', ')}) refuses the mark. A library repo has no deploy target, so its delivery is proven by the merge and the gate alone: pass no functional, and the product needs no health_url. A schema repo keeps the three checks, because its migration runs after the merge. An item with no registered repo, or a repo whose kind was never set, keeps the three checks. The delivering agent calls this; the lead calls it to catch up a delivery made outside a session. No owner flag. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'item_id', 'prs'], properties: { request_id: REQUEST_ID, item_id: S('Item id. The item must be active. Unless every repo it names is a library, its product must carry a health_url.'), prs: { type: 'array', items: { type: 'string' }, description: 'The merged GitHub pull request URLs this delivery shipped. Required: the item\'s own pr links are not read, because a link can be a design or a lock, not a delivery.' }, functional: { type: 'object', required: ['url', 'contains'], description: 'The read-only functional check. Required for a service or schema repo, and refused for a library repo. The verb GETs this URL once. No method, body or headers are accepted.', properties: { url: S('Absolute URL on the product health endpoint\'s origin, under one of the product\'s check_paths, and not the health endpoint itself.'), contains: { type: 'array', items: { type: 'string' }, description: 'Required. Strings the answer must carry, chosen so they exist only because of this change. Only whether each was found is recorded; the answer itself never enters the graph.' }, status: { type: 'number', description: 'Expected HTTP status, 2xx only. Default 200.' } } }, note: S('One line on what was delivered.') }, additionalProperties: false } },
   { name: 'item_reopen', description: `Reopen a delivered item: the lifecycle goes back to active and a reopen mark is appended, citing the failed check by URL. The delivery mark is never erased; the reopen points at it with the corrects relation. The owner, or the lead in this session, calls it. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'item_id', 'reason', 'failed_check'], properties: { request_id: REQUEST_ID, item_id: S('Item id carrying at least one delivery mark.'), reason: S('Why it is reopened, in plain words.'), failed_check: S('Absolute URL of the check that failed: a CI run, a monitor, an issue.'), corrects: S('Mark id of the delivery this reopen corrects. Default: the item\'s latest delivery mark.') }, additionalProperties: false } },
-  { name: 'in_flight', description: 'Answer "what are we working on, and what changed since a date?". Active items per product, ordered by days since the last change with the latest on top, and the days shown on each row. Movement is read from the marks and from each registered repo\'s recent pull requests: the item\'s own pr links, plus any pull request whose title, body or branch names the item id. Merged pull requests with no delivery mark are listed as "merged, not marked". A legacy seal reads as a delivery mark with verdict "legacy". Computed at read time and never stored. Scope: read, no owner flag needed.', inputSchema: { type: 'object', properties: { product: S('Limit the view to one product id.'), since: S('ISO date. Adds what was delivered since then.') }, additionalProperties: false } },
+  { name: 'in_flight', description: 'Answer "what are we working on, and what changed since a date?". Active items per product, ordered by the owner\'s current priority decision first, when it carries an order, then by days since the last change with the latest on top, and the days shown on each row. Each row says what the item waits on. Movement is read from the marks and from each registered repo\'s recent pull requests: the item\'s own pr links, plus any pull request whose title, body or branch names the item id. Merged pull requests with no delivery mark are listed as "merged, not marked". A legacy seal reads as a delivery mark with verdict "legacy". Computed at read time and never stored. Scope: read, no owner flag needed.', inputSchema: { type: 'object', properties: { product: S('Limit the view to one product id.'), since: S('ISO date. Adds what was delivered since then.') }, additionalProperties: false } },
   { name: 'sweep_check', description: 'Check the sweep against the "In flight" view: the newest decision record of kind sweep names the items the owner called in flight, and this reads the view and names every difference — what is listed and not in flight, and what is in flight and not listed. A product with no sweep on record is named too. It answers two things apart: `matches` says each product\'s view holds exactly what its sweep lists, and `complete` says that and that no item in the tenant sits outside every product. An item nobody adopted is missing from both sides, so `matches` alone can read "equal" over an unfinished sweep. Computed at read time and never stored. Scope: read, no owner flag needed.', inputSchema: { type: 'object', properties: { product: S('Limit the check to one product id.') }, additionalProperties: false } },
-  { name: 'needs_me', description: 'Answer "what needs me?": every open question on an active item, per product, ordered by what waiting costs. Each row is three lines, the question, the item and the cost, with the context folded under it. Computed at read time and never stored. Scope: read, no owner flag needed. Pass the row text back as rendered when the owner answers.', inputSchema: { type: 'object', properties: { product: S('Limit the view to one product id.') }, additionalProperties: false } },
+  { name: 'needs_me', description: 'Answer "what needs me?": every open question on a proposed, active or paused item, per product, ordered by what waiting costs. A row on an item that is not active names its lifecycle. Each row is three lines, the question, the item and the cost, with the context folded under it. Computed at read time and never stored. Scope: read, no owner flag needed. Pass the row text back as rendered when the owner answers.', inputSchema: { type: 'object', properties: { product: S('Limit the view to one product id.') }, additionalProperties: false } },
   { name: 'code_read_brief', description: 'The brief for the sub-agents that read the code for "where are we with X", one per registered repo of the product. It carries the never-read and never-quote rules, the citation contract and the JSON shape of the digest. Give one brief to one sub-agent; sub-agents never receive this server or the Engram MCP. Pass each digest back in where_are_we.code. When: before answering "where are we with X". Scope: read, no owner flag needed; it opens no repo and writes nothing.', inputSchema: { type: 'object', required: ['product', 'capability'], properties: { product: S('Product registry id.'), capability: S('The capability to read for, the X of the question.'), repos: { type: 'array', description: 'Limit the briefs to these registered repo ids. Default: every repo of the product.', items: { type: 'string' } }, roots: { type: 'object', description: 'Repo id to the local checkout path the sub-agent reads.', additionalProperties: { type: 'string' } }, commits: { type: 'object', description: 'Repo id to the commit the read runs against.', additionalProperties: { type: 'string' } }, focus: { type: 'array', description: 'Extra things the read should look for.', items: { type: 'string' } } }, additionalProperties: false } },
   { name: 'where_are_we', description: 'Answer "where are we with X" in six parts: live support and known limits from the code read at question time, then in progress, delivered and proposed from the items, then the current priority decision. Every row carries a citation: a path and a line, an entity id, a pull request, or a decision date. The code half comes from the sub-agent digests, which are refused when they cite a never-read path or quote a never-quote path, and every string is scrubbed by pattern. Computed at read time and never stored. Scope: read, no owner flag needed.', inputSchema: { type: 'object', required: ['product', 'capability', 'code'], properties: { product: S('Product registry id.'), capability: S('The capability the question is about, the X.'), code: { type: 'array', description: 'One digest per repo, from the sub-agents briefed by code_read_brief. At least one is required: an answer with no code read says nothing about what the code does today.', items: CODE_DIGEST }, items: { type: 'array', description: 'Item ids the lead judges to answer this question.', items: { type: 'string' } }, match: { type: 'array', description: 'Terms to match against item titles, summaries and tags. Give items, match, or both.', items: { type: 'string' } }, movement_repos: { type: 'array', description: "Narrow the movement read to these registered repo ids. Default: every repo of the product. The digests' own repos are always read.", items: { type: 'string' } }, since: S('ISO date. Adds what changed since then.') }, additionalProperties: false } },
   { name: 'built_pending_possible', description: 'Answer "what are we building, what is built, what is pending and what can be done": delivered items by date, active items, paused items with their reason, proposed items with their age, and the decisions that set the order. Item records, delivery marks and decisions only; no code read and no GitHub read. Computed at read time and never stored. Scope: read, no owner flag needed.', inputSchema: { type: 'object', properties: { product: S('Limit the view to one product id.'), since: S('ISO date. Limits built and the decisions to what came after it.') }, additionalProperties: false } },

package/work/protected-paths.json

@@ -8,7 +8,8 @@
     ".stack/",
     ".atlas/",
     ".mcp.json",
-    ".sdlc/"
+    ".sdlc/",
+    ".dev.vars*"
   ],
   "never_quote": [
     "fixtures",
@@ -30,7 +31,8 @@
     "agents/reviewer-architect.md",
     "agents/reviewer-pm.md",
     "agents/reviewer-security.md",
-    "agents/artifact-renderer.md"
+    "agents/artifact-renderer.md",
+    "agents/verifier.md"
   ],
   "sub_agents_that_write_files": [
     "agents/artifact-renderer.md"