@arjunkhera/atlas 0.3.9 → 0.3.11

package/.claude-plugin/plugin.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, as a Claude Code plugin for any repository.",
   "type": "module",
   "license": "UNLICENSED",

package/skills/sdlc-task/SKILL.md

@@ -33,6 +33,7 @@ checks and the transition log; each verb's own description says what it needs.
 | Drop it, in the owner's words (`item_resume` undoes a drop) | `item_drop` |
 | Keep its next step, its wait or its title true | `item_edit` |
 | Split it, or link it to other work | `item_split`, `item_link` |
+| Mark that it waits on another item, or clear that | `item_block`, `item_unblock` |
 | Ask the owner something, or record the answer | `question_ask`, `question_answer` |
 | Record a decision in the owner's words | `decision_record` |
 | Mark it delivered, or reopen it | `item_done`, `item_reopen` |

package/work/lib/capability.mjs

@@ -15,7 +15,7 @@
 //      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, priorityOrderOf, byPriority, orderNote, waitsOnLine } from './questions.mjs';
+import { oneLine, scrubSecrets, ROW_LINE_MAX, priorityOrderOf, byPriority, orderNote, waitsOnLine, blockersOf, blocksOf, blockedPhrase, waitsShown } from './questions.mjs';
 import { listLine, legacySealOf, marksByItem, movementOf, pullsOfItem, readPullsByRepo, correctionsOf, daysBetween } from './delivery.mjs';
 import { acceptCodeRead, codeReadBrief } from './code-read.mjs';
 
@@ -391,6 +391,9 @@ export function createCapabilityVerbs(core) {
       const unregisteredTotal = rows.filter(unsorted).length;
       const unregisteredShown = items.filter(unsorted).length;
       const marks = await marksFor(new Set(items.map((row) => row.id)));
+      // Blocked-by links read from every item loaded, so a blocker of another
+      // product still names its state (work item additions, slice 2).
+      const itemById = new Map(rows.map((row) => [row.id, row]));
       const readAt = now();
       let redactions = 0;
       const clean = (value, max = 200) => { const out = scrubSecrets(oneLine(value, max)); redactions += out.redactions; return out.text; };
@@ -437,7 +440,10 @@ export function createCapabilityVerbs(core) {
         }
         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' });
-        const waits = fields.waits_on && typeof fields.waits_on === 'object' ? { waits_on: fields.waits_on } : {};
+        const shown = waitsShown(fields);
+        const blockers = blockersOf(item, (id) => itemById.get(id));
+        const blocks = blocksOf(item, rows);
+        const waits = { ...(shown && typeof shown === 'object' ? { waits_on: shown } : {}), ...(blockers.length ? { blocked_by: blockers } : {}), ...(blocks.length ? { blocks } : {}) };
         if (fields.lifecycle === 'active') building.push({ ...base, ...waits, 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, ...waits, 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') {
@@ -467,7 +473,7 @@ export function createCapabilityVerbs(core) {
       building.sort(byPriority(orders, byDays));
       pending.sort(byPriority(orders, byDays));
       possible.sort(byPriority(orders, (a, b) => (b.age_days ?? 0) - (a.age_days ?? 0)));
-      const waitsOf = (row) => (row.waits_on ? ` · ${waitsOnLine(row.waits_on)}` : '');
+      const waitsOf = (row) => `${row.waits_on ? ` · ${waitsOnLine(row.waits_on)}` : ''}${blockedPhrase(row.blocked_by ?? [], row.blocks ?? []) ? ` · ${blockedPhrase(row.blocked_by ?? [], row.blocks ?? [])}` : ''}`;
 
       // D3 rule 2: a row names its product. The board does not group, so every
       // line carries the id (review H6).

package/work/lib/delivery.mjs

@@ -13,7 +13,7 @@
 //   3. Movement is read, never stored. The view computes it at question time
 //      from the marks and from the repos' pull requests (D3 rule 5, R1).
 import { refuse, text, isoDate, url, stringList, sha256, repoKinds, LIVE_KINDS } from './verb-fields.mjs';
-import { oneLine, ROW_LINE_MAX, priorityOrderOf, byPriority, orderNote, waitsOnLine } from './questions.mjs';
+import { oneLine, ROW_LINE_MAX, priorityOrderOf, byPriority, orderNote, waitsOnLine, blockersOf, blocksOf, blockedPhrase, waitsShown } from './questions.mjs';
 
 export const DELIVERY_WRITE_VERBS = Object.freeze(['item_done', 'item_reopen']);
 export const DELIVERY_READ_VERBS = Object.freeze(['in_flight']);
@@ -544,6 +544,9 @@ export function createDeliveryVerbs(core) {
       if (items.length > MAX_ITEMS) refuse(`${items.length} items are registered; the view reads at most ${MAX_ITEMS}. Narrow it with a product id.`);
       const byId = new Map(items.map((row) => [row.id, row]));
       const marks = await marksOf(new Set(byId.keys()));
+      // Blocked-by links are read from every item the view loaded, in any
+      // lifecycle, so "blocks" and "cleared" need no extra call.
+      const anyById = new Map(all.map((row) => [row.id, row]));
 
       // Movement from git: every registered repo of the products in view, its
       // recent pull requests, once per repo and shared by every item.
@@ -587,6 +590,10 @@ export function createDeliveryVerbs(core) {
         // D3 rule 1: in flight is active work. Delivered and paused items leave
         // the rows; what was delivered since a date has its own list.
         if (fields.lifecycle !== 'active') continue;
+        const blockers = blockersOf(item, (id) => anyById.get(id));
+        const blocks = blocksOf(item, all);
+        const blocked = blockedPhrase(blockers, blocks);
+        const waits = waitsShown(fields);
         rows.push({
           item: item.id, product: fields.product, stage: fields.stage ?? '', driver: fields.driver ?? '', days_since_last_change: days,
           last_change_at: last?.at ?? null, last_change_source: last?.source ?? 'nothing recorded', delivery_state: state,
@@ -594,10 +601,13 @@ export function createDeliveryVerbs(core) {
             // The id is what a reader types back, so the title gives way to it
             // inside the line budget, as the "Needs me" row does (review G6).
             oneLine(`${oneLine(item.title, Math.max(1, ROW_LINE_MAX - item.id.length - 3))} · ${item.id}`),
-            oneLine(`${fields.product} · ${fields.stage ?? 'no stage'} · ${fields.driver ?? 'no driver'}${waitsOnLine(fields.waits_on) ? ` · ${waitsOnLine(fields.waits_on)}` : ''} · next: ${fields.next_step || 'not set'}`),
+            oneLine(`${fields.product} · ${fields.stage ?? 'no stage'} · ${fields.driver ?? 'no driver'}${waitsOnLine(waits) ? ` · ${waitsOnLine(waits)}` : ''} · next: ${fields.next_step || 'not set'}`),
             oneLine(`${days === null ? 'no movement on record' : `${days} day${days === 1 ? '' : 's'} since last change`} (${last?.source ?? 'nothing recorded'}) · ${mine.length} pull request${mine.length === 1 ? '' : 's'}${open.length ? ` · ${open.length} merged, not marked` : ''}${orderNote(orders, { product: fields.product, item: item.id })}`),
+            // The blockers get their own line, so a long list never cuts the
+            // next step off line two; they come last.
+            ...(blocked ? [oneLine(blocked)] : []),
           ],
-          waits_on: fields.waits_on ?? null,
+          waits_on: waits, blocked_by: blockers, blocks,
           folded: { title: item.title, next_step: fields.next_step ?? '', scope: fields.scope?.text ?? '', pieces: fields.split_children ?? [], prs: mine.map((pull) => ({ url: pull.url, state: pull.state, matched_by: pull.matched_by, merged_at: pull.merged_at, updated_at: pull.updated_at })), marks: own.map((mark) => ({ id: mark.id, kind: mark.fields.kind, verdict: mark.fields.verdict, at: mark.fields.marked_at })) },
           citation: { item: item.id, read_at: readAt, repos: [...new Set(mine.map((pull) => pull.repo))] },
         });

package/work/lib/questions.mjs

@@ -98,6 +98,42 @@ export function waitsOnLine(waits) {
   return `waits on ${what}${waits.item ? ` ${waits.item}` : ''}${waits.note ? `: ${waits.note}` : ''}`;
 }
 
+// Work item additions, slice 2: the items that block an item, the items it
+// blocks, and one phrase for a row. lookup gives an item record by id, or
+// undefined when the view did not load it. A blocker that is delivered or
+// dropped no longer blocks; the row shows it as cleared.
+export const CLEARED_LIFECYCLES = Object.freeze(['done', 'dropped']);
+export function blockersOf(item, lookup) {
+  const list = Array.isArray(item?.fields?.blocked_by) ? item.fields.blocked_by : [];
+  return list.filter((entry) => entry && typeof entry.item === 'string').map((entry) => {
+    const other = lookup(entry.item);
+    // A blocker the view cannot find is archived or gone, so it blocks no more.
+    if (!other) return { item: entry.item, title: null, state: 'gone', cleared: true, ...(entry.note ? { note: entry.note } : {}) };
+    const lifecycle = other.fields?.lifecycle ?? 'unknown';
+    const cleared = CLEARED_LIFECYCLES.includes(lifecycle);
+    return { item: entry.item, title: oneLine(other.title, 60), state: cleared ? 'cleared' : (lifecycle === 'active' ? (other.fields?.stage ?? 'active') : lifecycle), cleared, ...(entry.note ? { note: entry.note } : {}) };
+  });
+}
+// Only a live item is still held up, so a delivered or dropped one leaves the
+// "blocks" list.
+export function blocksOf(item, all) {
+  return all.filter((other) => other.id !== item.id && LIVE_LIFECYCLES.includes(other.fields?.lifecycle) && Array.isArray(other.fields?.blocked_by) && other.fields.blocked_by.some((entry) => entry?.item === item.id))
+    .map((other) => ({ item: other.id, title: oneLine(other.title, 60) }));
+}
+export function blockedPhrase(blockers, blocks) {
+  const parts = [];
+  if (blockers.length) parts.push(`blocked by: ${blockers.map((row) => `${row.title ?? row.item} (${row.state})`).join(', ')}`);
+  if (blocks.length) parts.push(`blocks: ${blocks.map((row) => row.title ?? row.item).join(', ')}`);
+  return parts.join(' · ');
+}
+// An old waits_on pointer to an item is hidden when a blocked_by link names
+// the same item, so a row does not say it twice.
+export function waitsShown(fields) {
+  const waits = fields?.waits_on;
+  if (waits?.on === 'item' && Array.isArray(fields?.blocked_by) && fields.blocked_by.some((entry) => entry?.item === waits.item)) return null;
+  return waits ?? null;
+}
+
 // 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, lifecycle = 'active') {

package/work/lib/verbs.mjs

@@ -28,9 +28,38 @@ export const STAGES = Object.freeze(['capture', 'spec', 'build', 'verify', 'lear
 export const TIERS = Object.freeze(['hotfix', 'standard', 'initiative']);
 export const DRIVERS = Object.freeze(['owner-led', 'agent']);
 // 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']);
+// rows. Work item additions, slice 2: "item" retires for new writes, and
+// item_block keeps the links. A record that already holds it still reads.
+export const WAITS_ON = Object.freeze(['owner-decision', 'owner-action', 'gate', 'nothing']);
+// How far the loop check of item_block walks before it stops.
+const MAX_BLOCK_WALK = 200;
 const MAX_EDITS = 20;
+// The tags that other verbs own (work item additions, slice 1). item_edit
+// never adds or removes them; item_propose drops them from the caller's list.
+export const OWNED_TAG_PREFIXES = Object.freeze(['product:', 'repo:', 'tier:']);
+export const OWNED_TAGS = Object.freeze(['atlas-work', 'no-model', 'atlas-registry']);
+// Engram reads no-model with the spaces trimmed and in any case, so the check
+// does the same: No-Model is owned too.
+export const isOwnedTag = (tag) => {
+  const plain = String(tag).trim().toLowerCase();
+  return OWNED_TAGS.includes(plain) || OWNED_TAG_PREFIXES.some((prefix) => plain.startsWith(prefix));
+};
+// The planned dates the owner may set on an item (work item additions, slice 1).
+export const PLAN_DATES = Object.freeze(['start', 'end', 'deadline']);
+// A planned date is a calendar day. Date.parse takes 2026-02-30 and moves it
+// to 2 March, so the day must read back the same.
+const planDate = (value, name) => {
+  if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value)) refuse(`${name} must be a date in the form YYYY-MM-DD, or null to clear it`);
+  const parsed = new Date(`${value}T00:00:00Z`);
+  if (Number.isNaN(parsed.getTime()) || parsed.toISOString().slice(0, 10) !== value) refuse(`${name} is not a real date: ${value}`);
+  return value;
+};
+const tagList = (value, name) => stringList(value, name, { max: 16 }).map((tag) => {
+  text(tag, name, { max: 100 });
+  if (tag !== tag.trim()) refuse(`${name} holds a tag with spaces at its start or end: "${tag}"`);
+  if (isOwnedTag(tag)) { const plain = tag.toLowerCase(); refuse(`${tag} is owned by the tracker; ${plain.startsWith('product:') || plain.startsWith('repo:') ? 'change the product or repos with item_lock' : plain.startsWith('tier:') ? 'change the tier with item_lock' : 'no verb removes it'}`); }
+  return tag;
+});
 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;
@@ -142,9 +171,15 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
     for (let attempt = 0; attempt < 2; attempt += 1) {
       if (attempt > 0 && guard) guard(current);
       const next = typeof fields === 'function' ? fields(current) : fields;
+      // A fields function returns null when the newest record already holds
+      // the change; then nothing is written.
+      if (next === null) return current;
       const receipts = { ...(current.fields?.atlas_receipts ?? {}), [requestId]: { verb, at: now(), ...(digest ? { digest } : {}) } };
       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])];
+      // tags as a function replaces the list with what it returns, computed
+      // from the newest record; a list is added to the tags already there.
+      if (typeof tags === 'function') body.tags = [...new Set(tags(current))];
+      else 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); }
       catch (error) {
@@ -360,7 +395,7 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
       const type = await typeNamed('container');
       const prior = await landed(type, requestId, meta);
       if (prior) return { verb: 'item_propose', item_id: prior.id, version: prior.version, lifecycle: prior.fields.lifecycle, stage: prior.fields.stage, product: prior.fields.product, repos: prior.fields.repos, replayed_from_graph: true };
-      const entity = await create(type, requestId, 'item_propose', { digest: meta?.digest, title, body: args.body ? text(args.body, 'body') : undefined, fields, tags: [`product:${product.fields.registry_id}`, ...repos.map((id) => `repo:${id}`), `tier:${fields.tier}`, ...(args.tags ? stringList(args.tags, 'tags', { max: 16 }).filter((tag) => !/^(?:product|repo|tier):|^atlas-registry$/.test(tag)) : [])] });
+      const entity = await create(type, requestId, 'item_propose', { digest: meta?.digest, title, body: args.body ? text(args.body, 'body') : undefined, fields, tags: [`product:${product.fields.registry_id}`, ...repos.map((id) => `repo:${id}`), `tier:${fields.tier}`, ...(args.tags ? stringList(args.tags, 'tags', { max: 16 }).filter((tag) => !isOwnedTag(tag)) : [])] });
       return { verb: 'item_propose', item_id: entity.id, version: entity.version, lifecycle: 'proposed', stage: 'capture', product: fields.product, repos };
     },
 
@@ -398,7 +433,25 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
       requireOwner('item split');
       const parent = await requireItem(args.item_id);
       const reason = text(args.reason, 'reason', { max: 2000 });
-      if (alreadyPatched(parent, requestId, meta)) return { verb: 'item_split', item_id: parent.id, version: parent.version, reason, children: (parent.fields.split_children ?? []).map((id) => ({ item_id: id })), replayed_from_graph: true };
+      // split_order is a piece's place in the parent's split_children. That
+      // list changes only through a function of the newest parent, so its
+      // order holds under a race and a retry. Each piece gets its number after
+      // the parent write lands (work item additions, slice 1).
+      const stampOrder = async (list, rows) => {
+        const out = [];
+        for (const row of rows) {
+          const order = list.indexOf(row.id);
+          const child = order >= 0 && row.fields?.split_order !== order ? await patch(row, 'item_split', requestId, { split_order: order }, { digest: meta?.digest }) : row;
+          out.push({ item_id: child.id, title: child.title, repos: child.fields?.repos ?? [], split_order: child.fields?.split_order ?? null });
+        }
+        return out;
+      };
+      if (alreadyPatched(parent, requestId, meta)) {
+        // Only this request's pieces, in the order of the call.
+        const mine = (await findCreated(await typeNamed('container'), requestId)).filter((row) => row.fields?.split_from === parent.id).sort((a, b) => a.fields.split_index - b.fields.split_index);
+        const children = await stampOrder(Array.isArray(parent.fields.split_children) ? parent.fields.split_children : [], mine);
+        return { verb: 'item_split', item_id: parent.id, version: parent.version, reason, children, replayed_from_graph: true };
+      }
       if (!['proposed', 'active'].includes(parent.fields?.lifecycle)) refuse(`item ${parent.id} is ${parent.fields?.lifecycle}; only a proposed or active item can be split`);
       if (!Array.isArray(args.children) || !args.children.length) refuse('children must list at least one piece: { title, origin?, repos?, tier?, next_step?, driver? }');
       if (args.children.length > MAX_CHILDREN) refuse(`children holds more than ${MAX_CHILDREN} pieces`);
@@ -421,14 +474,19 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
         if (!spec.origin) refuse('each child needs an origin in the owner\'s words when the parent has none');
       }
       const already = await findCreated(type, requestId);
-      const children = [];
+      // split_index is the place in this call, so a retry finds its own
+      // pieces.
+      const created = [];
       for (const [index, spec] of specs.entries()) {
-        const existing = already.find((row) => row.fields?.split_index === index);
+        const existing = already.find((row) => row.fields?.split_index === index && row.fields?.split_from === parent.id);
         const child = existing ?? await create(type, requestId, 'item_split', { digest: meta?.digest, title: spec.title, fields: { lifecycle: 'proposed', stage: 'capture', product: product.fields.registry_id, repos: spec.repos, tier: spec.tier, origin: spec.origin, driver: spec.driver, next_step: spec.next_step, summary: spec.summary, external_refs: [], links: [], split_index: index, split_from: parent.id, split_reason: reason }, tags: [`product:${product.fields.registry_id}`, ...spec.repos.map((id) => `repo:${id}`), `tier:${spec.tier}`] });
         await edge(child, parent, 'spun_out_of', requestId, { reason });
-        children.push({ item_id: child.id, title: spec.title, repos: spec.repos });
+        created.push(child);
       }
-      const entity = await patch(parent, 'item_split', requestId, { split_children: [...new Set([...(parent.fields.split_children ?? []), ...children.map((child) => child.item_id)])] }, { digest: meta?.digest });
+      // A function of the newest parent, so a split that lands at the same
+      // moment keeps its pieces.
+      const entity = await patch(parent, 'item_split', requestId, (current) => ({ split_children: [...new Set([...(current.fields?.split_children ?? []), ...created.map((child) => child.id)])] }), { digest: meta?.digest });
+      const children = await stampOrder(entity.fields?.split_children ?? [], created);
       return { verb: 'item_split', item_id: entity.id, version: entity.version, reason, children };
     },
 
@@ -479,10 +537,12 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
     // 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.
+    // Work item additions, slice 1: tags_add and tags_remove change the free
+    // tags, and plan holds the owner's planned start, end and deadline.
     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 };
+      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, tags: item.tags ?? [], plan: fields.plan ?? null, changed: [], 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 = {};
@@ -498,29 +558,124 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
       }
       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(', ')}`);
+        if (!given || typeof given !== 'object' || Array.isArray(given)) refuse(`waits_on must be { on, note? }, with on one of ${WAITS_ON.join(', ')}`);
+        if (given.on === 'item') refuse('waits_on.on "item" is retired; link the items with item_block, which lists every blocker and shows "blocks" on the other row');
         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`);
+        if (given.item !== undefined) refuse('waits_on.item is retired; link the items with item_block');
+        if (wait.on !== 'nothing' && !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 tagsAdd = args.tags_add === undefined ? [] : tagList(args.tags_add, 'tags_add');
+      const tagsRemove = args.tags_remove === undefined ? [] : tagList(args.tags_remove, 'tags_remove');
+      const both = tagsAdd.filter((tag) => tagsRemove.includes(tag));
+      if (both.length) refuse(`a tag cannot be added and removed in one edit: ${both.join(', ')}`);
+      const tagsOf = (current) => [...new Set([...(current.tags ?? []).filter((tag) => !tagsRemove.includes(tag)), ...tagsAdd])];
+      const sameList = (a, b) => a.length === b.length && a.every((value, index) => value === b[index]);
+      let tagEdit = tagsAdd.length || tagsRemove.length;
+      let planGiven = null;
+      if (args.plan !== undefined) {
+        requireOwner('item edit of planned dates');
+        if (!args.plan || typeof args.plan !== 'object' || Array.isArray(args.plan)) refuse(`plan must be { ${PLAN_DATES.join(', ')} }, each a date YYYY-MM-DD or null to clear it`);
+        const unknown = Object.keys(args.plan).filter((key) => !PLAN_DATES.includes(key));
+        if (unknown.length) refuse(`plan holds only ${PLAN_DATES.join(', ')}; not ${unknown.join(', ')}`);
+        if (!Object.keys(args.plan).length) refuse(`plan must name at least one of ${PLAN_DATES.join(', ')}`);
+        planGiven = Object.fromEntries(Object.entries(args.plan).map(([key, value]) => [key, value === null ? null : planDate(value, `plan.${key}`)]));
+      }
+      // The dates merge with the ones on the newest record; a null clears one.
+      const planOf = (current) => {
+        const merged = { ...(current.fields?.plan ?? {}), ...planGiven };
+        for (const key of Object.keys(merged)) if (merged[key] === null) delete merged[key];
+        if (merged.start && merged.end && merged.end < merged.start) refuse(`the planned end ${merged.end} is before the planned start ${merged.start}`);
+        return Object.keys(merged).length ? merged : null;
+      };
+      const samePlan = (a, b) => JSON.stringify(Object.entries(a ?? {}).sort()) === JSON.stringify(Object.entries(b ?? {}).sort());
+      if (args.title === undefined && !Object.keys(change).length && !tagEdit && !planGiven) refuse('item edit needs title, next_step or waits_on, or one of tags_add, tags_remove and plan');
+      // A tag or plan edit that changes nothing is left out. When nothing is
+      // left, the item is not written and the history gets no empty entry.
+      if (planGiven && samePlan(planOf(item), fields.plan)) planGiven = null;
+      if (tagEdit && sameList(tagsOf(item), item.tags ?? [])) tagEdit = false;
+      if (args.title === undefined && !Object.keys(change).length && !tagEdit && !planGiven) 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, tags: item.tags ?? [], plan: fields.plan ?? null, changed: [], unchanged: true };
       const reason = text(args.reason, 'reason', { optional: true, max: 1000 });
-      const entry = { at: now(), by: label.agent, previous, ...(reason ? { reason } : {}) };
+      const at = now();
       // 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.
+      // owner gave is kept on its own, so a title never falls out of it. The
+      // old tags and dates come from the record the write lands on.
+      const entryOf = (current) => ({ at, by: label.agent, previous: { ...previous, ...(tagEdit ? { tags: current.tags ?? [] } : {}), ...(planGiven ? { plan: current.fields?.plan ?? null } : {}) }, ...(reason ? { reason } : {}) });
       const entity = await patch(item, 'item_edit', requestId, (current) => ({
-        ...change, edits: [...(Array.isArray(current.fields?.edits) ? current.fields.edits : []), entry].slice(-MAX_EDITS),
+        ...change, ...(planGiven ? { plan: planOf(current) } : {}), edits: [...(Array.isArray(current.fields?.edits) ? current.fields.edits : []), entryOf(current)].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)] };
+      }), { digest: meta?.digest, guard: live, ...(title ? { title } : {}), ...(tagEdit ? { tags: tagsOf } : {}) });
+      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, tags: entity.tags ?? [], plan: entity.fields?.plan ?? null, changed: [...(args.title !== undefined ? ['title'] : []), ...Object.keys(change), ...(tagEdit ? ['tags'] : []), ...(planGiven ? ['plan'] : [])] };
+    },
+
+    // Work item additions, slice 2: an item names the items that block it.
+    // The list on the item is the one home of the fact; a view works out
+    // "blocks" from the items it loaded. The lead keeps the links true, so no
+    // owner flag is needed. A link that would close a loop is refused.
+    async item_block(args, requestId, meta) {
+      const item = await requireItem(args.item_id);
+      text(args.blocked_by, 'blocked_by', { max: 200 });
+      const note = text(args.note, 'note', { optional: true, max: 300 });
+      const listOf = (record) => (Array.isArray(record.fields?.blocked_by) ? record.fields.blocked_by : []);
+      // The replay comes before the blocker is read: a blocker archived since
+      // the write landed must not refuse a write that already happened.
+      if (alreadyPatched(item, requestId, meta)) return { verb: 'item_block', item_id: item.id, version: item.version, blocked_by: listOf(item).map((entry) => entry.item), replayed_from_graph: true };
+      const blocker = await requireItem(args.blocked_by);
+      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 blocked`); };
+      live(item);
+      if (blocker.id === item.id) refuse('an item cannot block itself');
+      if (listOf(item).some((entry) => entry.item === blocker.id)) return { verb: 'item_block', item_id: item.id, version: item.version, blocked_by: listOf(item).map((entry) => entry.item), unchanged: true };
+      // Walk what the blocker waits on, with an old waits_on pointer to an
+      // item counted as a link. Reaching the item means the new link closes a
+      // loop. Two sessions can pass this check at the same moment;
+      // one owner runs these products, so the design accepts that.
+      const seen = new Set([blocker.id]);
+      const path = new Map([[blocker.id, [blocker.id]]]);
+      const queue = [blocker];
+      while (queue.length) {
+        const current = queue.shift();
+        const links = [...listOf(current), ...(current.fields?.waits_on?.on === 'item' && typeof current.fields.waits_on.item === 'string' ? [{ item: current.fields.waits_on.item }] : [])];
+        for (const entry of links) {
+          if (entry.item === item.id) refuse(`this link would close a loop: ${[item.id, ...path.get(current.id), item.id].join(' → ')}`);
+          if (seen.has(entry.item)) continue;
+          if (seen.size >= MAX_BLOCK_WALK) refuse(`the loop check stopped after ${MAX_BLOCK_WALK} items; the blocked-by chain is too long to check`);
+          seen.add(entry.item);
+          let next;
+          try { next = await client.getEntity(entry.item); } catch (error) { if (error instanceof EngramHttpError && error.status === 404) continue; throw error; }
+          path.set(next.id, [...path.get(current.id), next.id]);
+          queue.push(next);
+        }
+      }
+      const at = now();
+      const link = { item: blocker.id, at, by: label.agent, ...(note ? { note } : {}) };
+      // null tells patch() not to write: another session added the same link.
+      const entity = await patch(item, 'item_block', requestId, (current) => (listOf(current).some((entry) => entry.item === blocker.id) ? null : { blocked_by: [...listOf(current), link] }), { digest: meta?.digest, guard: live });
+      return { verb: 'item_block', item_id: entity.id, version: entity.version, blocked_by: listOf(entity).map((entry) => entry.item), ...(entity.fields?.atlas_receipts?.[requestId] ? {} : { unchanged: true }) };
+    },
+
+    async item_unblock(args, requestId, meta) {
+      const item = await requireItem(args.item_id);
+      text(args.blocked_by, 'blocked_by', { max: 200 });
+      const reason = text(args.reason, 'reason', { optional: true, max: 1000 });
+      const listOf = (record) => (Array.isArray(record.fields?.blocked_by) ? record.fields.blocked_by : []);
+      if (alreadyPatched(item, requestId, meta)) return { verb: 'item_unblock', item_id: item.id, version: item.version, blocked_by: listOf(item).map((entry) => entry.item), removed: args.blocked_by, replayed_from_graph: true };
+      // Live and still blocked, on the first read and on the newest record.
+      const guard = (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 unblocked`);
+        if (!listOf(current).some((entry) => entry.item === args.blocked_by)) refuse(`item ${current.id} is not blocked by ${args.blocked_by}`);
+      };
+      guard(item);
+      const at = now();
+      // The removed link goes into the edits, so the history keeps it. It is
+      // taken from the record the write lands on.
+      const entity = await patch(item, 'item_unblock', requestId, (current) => ({
+        blocked_by: listOf(current).filter((row) => row.item !== args.blocked_by),
+        edits: [...(Array.isArray(current.fields?.edits) ? current.fields.edits : []), { at, by: label.agent, previous: { blocked_by: listOf(current).find((row) => row.item === args.blocked_by) }, ...(reason ? { reason } : {}) }].slice(-MAX_EDITS),
+      }), { digest: meta?.digest, guard });
+      return { verb: 'item_unblock', item_id: entity.id, version: entity.version, blocked_by: listOf(entity).map((row) => row.item), removed: args.blocked_by };
     },
 
     async item_stage(args, requestId, meta) {
@@ -561,7 +716,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_drop', 'item_edit', '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_block', 'item_unblock', '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/mcp.mjs

@@ -51,8 +51,10 @@ export const TOOLS = [
   { 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_edit', description: `Edit a proposed, active or paused item: its next step, what it waits on, its free tags, its planned dates, or its title. Each edit 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, the wait or a tag changes; the lead keeps them true at the end of each session. No owner flag for next_step, waits_on and tags; the tags that other verbs own (product:, repo:, tier:, atlas-work, no-model, atlas-registry) are refused. A new title is the owner's words, and planned dates are the owner's promise, so both need 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(', ')}. To wait on another item, use item_block.`), note: S('What exactly it waits on, in plain words. Required unless on is nothing.') } }, title: S("A new title, in the owner's words. Owner present only."), tags_add: { type: 'array', items: { type: 'string' }, description: 'Free tags to add.' }, tags_remove: { type: 'array', items: { type: 'string' }, description: 'Free tags to remove.' }, plan: { type: 'object', description: 'Planned dates, set by the owner. Owner present only. Each is YYYY-MM-DD, or null to clear it. Dates not named stay as they are.', properties: { start: { type: ['string', 'null'], description: 'Planned start.' }, end: { type: ['string', 'null'], description: 'Planned end. Not before the start.' }, deadline: { type: ['string', 'null'], description: 'Deadline.' } }, additionalProperties: false }, reason: S('One line on why it changed.') }, additionalProperties: false } },
   { name: 'item_stage', description: `Move an active item to a stage (${STAGES.join(', ')}). When: work moves; the lead or the delivering agent calls it. 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_block', description: `Record that an item is blocked by another item. The item keeps a list of its blockers, each with a note; the views show "blocked by" on its row and "blocks" on the blocker's row, and a blocker that is delivered or dropped shows as cleared. Refuses the item itself and a link that would close a loop. When: work cannot move until another item lands. No owner flag needed. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'item_id', 'blocked_by'], properties: { request_id: REQUEST_ID, item_id: S('The blocked item id.'), blocked_by: S('The item id that blocks it.'), note: S('One line: what exactly it needs from the blocker.') }, additionalProperties: false } },
+  { name: 'item_unblock', description: `Remove one blocked-by link from an item. The removed link stays in the item's edits. When: the blocker no longer holds the item back. No owner flag needed. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'item_id', 'blocked_by'], properties: { request_id: REQUEST_ID, item_id: S('The blocked item id.'), blocked_by: S('The blocker item id to remove.'), reason: S('One line on why.') }, additionalProperties: false } },
   { name: 'item_link', description: `Attach a typed link (kind, url, role, note) to an item: a PR, an issue, an artifact, a design doc, a conversation. When: any in-session agent has a link the item should carry, for example a PR it opened. No owner flag needed. A duplicate kind and url is a no-op. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'item_id', 'kind', 'url'], properties: { request_id: REQUEST_ID, item_id: S('Item id.'), kind: S(`One of ${LINK_KINDS.join(', ')}.`), url: S('Absolute http or https URL.'), role: S('What the link is to the item, for example "delivers", "design", "evidence".'), note: S('One line.') }, additionalProperties: false } },
   { name: 'item_adopt', description: `Give an existing work item its product and repos. This is the slice L5 sweep: most items in the tenant were made before the registry existed and name no product, so no view can place them. Refuses an item that already names another registered product; an item is named once. The audit stamps adopted_at and adopted_from move only when the product actually changes. When: the owner says which product a piece of work belongs to. Owner present only. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'item_id', 'product', 'repos'], properties: { request_id: REQUEST_ID, item_id: S('Item id.'), product: S('Product id the item belongs to.'), repos: { type: 'array', items: { type: 'string' }, description: 'Repo ids under that product. Required. Pass an empty list for an item that has no repo, such as a container root; a repo of another product is dropped and named in dropped_repos.' }, stage: S(`One of ${STAGES.join(', ')}. Active items only.`), tier: S(`One of ${TIERS.join(', ')}.`), driver: S(`One of ${DRIVERS.join(', ')}.`), next_step: S('One line: what happens next.') }, additionalProperties: false } },
   { name: 'question_ask', description: `Ask the owner one question that blocks work on an item, and say what waiting costs. When: an agent is blocked and cannot decide by itself. Any in-session agent may call it; no owner flag. The question shows in the "Needs me" view until it is answered. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'text', 'item_id', 'product', 'cost'], properties: { request_id: REQUEST_ID, text: S('The question, in plain words, answerable without opening a source.'), item_id: S('Entity id of the work item the question blocks.'), product: S('Product id of that item.'), cost: S(`What waiting costs. One of: ${COSTS.map((cost) => `${cost} (${COST_MEANING[cost]})`).join('; ')}.`), context: { type: 'object', description: 'What the owner needs to answer without opening a source.', properties: { current_behavior: S('What happens today.'), change: S('What would change.'), affected: { type: 'array', items: { type: 'string' }, description: 'Parts that change.' }, options: { type: 'array', items: { type: 'string' }, description: 'The options, one per entry.' }, consequences: S('What follows from each option.'), sources: { type: 'array', items: { type: 'string' }, description: 'Absolute http or https URLs that back the context.' } } } }, additionalProperties: false } },