@arjunkhera/atlas 0.3.8 → 0.3.10

package/work/lib/verbs.mjs

@@ -31,6 +31,32 @@ export const DRIVERS = Object.freeze(['owner-led', 'agent']);
 // 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;
+// 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;
@@ -144,7 +170,10 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
       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 ?? {}), ...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 +389,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 +427,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 +468,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 +531,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 = {};
@@ -511,16 +565,47 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
         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'] : [])] };
     },
 
     async item_stage(args, requestId, meta) {

package/work/mcp.mjs

@@ -51,7 +51,7 @@ 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(', ')}.`), 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_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 } },