@arjunkhera/atlas 0.3.10 → 0.3.11

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.3.10",
+  "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.10",
+  "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,8 +28,11 @@ 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.
@@ -168,6 +171,9 @@ 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 } };
       // tags as a function replaces the list with what it returns, computed
@@ -552,16 +558,13 @@ 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;
       }
@@ -608,6 +611,73 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
       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) {
       const item = await requireItem(args.item_id);
       const stage = oneOf(args.stage, 'stage', STAGES);
@@ -646,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, 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(', ')}.`), 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."), 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_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 } },