@arjunkhera/atlas 0.2.3 → 0.3.0

package/skills/sdlc-task/lifecycle.yaml

@@ -14,11 +14,13 @@ authority: the Atlas lock procedure, amendment A1.9, section 5, slice L2 stage o
 lifecycle_states: [proposed, active, paused, done, dropped, archived]
 stages: [capture, spec, build, verify, ship, learn]
 
+# A lock is the owner's approval of a short design (target design, flow 4).
+# Long frozen texts with hashes retired in stage 1.
 lock:
-  freezes: [acceptance_criteria, interfaces, approach]
-  preconditions: [open_questions_empty, ac_ratified, approach_chosen, tier_confirmed]
+  holds: [definition_of_done, kind_of_change, impact, undo, tests_it_changes]
+  preconditions: [open_questions_empty, owner_approved_in_own_words, approach_chosen, tier_confirmed]
 
-tripwires: [acceptance_criteria, security, schema_migrations, money_cost]
+tripwires: [definition_of_done, security, schema_migrations, money_cost]
 
 tiers: [hotfix, standard, initiative]
 tier_escalators: [migrations, auth_rls_surface, new_external_dependency, money_cost]

package/skills/sdlc-task/templates/design-doc.md

@@ -14,7 +14,7 @@
 
 # <Feature name> — design
 
-> Status: DRAFT (in design loop) | LOCKED <date> | SHIPPED <date>
+> Status: DRAFT (in design loop) | APPROVED <date> | SHIPPED <date>
 > Work item: <work item id> · Tier: hotfix | standard | initiative
 > Artifact: <claude.ai artifact url once published>
 
@@ -46,7 +46,7 @@ and the one-line goal. Agent interpretation kept separate.>
      what the system does, what they see — written as narrative the owner can
      react to, each tagged to the slice that ships it. Illustrative dialogue
      is fine; mark invented values as illustrative. Draft these BEFORE
-     acceptance criteria — the AC formalize what the stories show. -->
+     the definition of done — its checks formalize what the stories show. -->
 
 - **US-1 — <scene name>** *(slice)*: …
 
@@ -67,7 +67,7 @@ Standard tier: may collapse to "approach + rejected alternative, one line".>
 ## Open questions
 
 <!-- The lock precondition: this checklist must be EMPTY (all items moved to
-     Resolved) before `sdlc-task lock` will stamp the lock block. -->
+     Resolved) before the owner is asked to approve the design. -->
 
 - [ ] OQ-1 —
 
@@ -77,7 +77,7 @@ Standard tier: may collapse to "approach + rejected alternative, one line".>
 
 ## Decision log
 
-- D-1 — <decision> — <rationale> (<date>, <ratifier>)
+- D-1 — <decision> — <rationale> (<date>, <who decided>)
 
 ## Risks & failure modes
 
@@ -89,29 +89,34 @@ Standard tier: may collapse to "approach + rejected alternative, one line".>
 <!-- How each slice proves itself: suites, scenarios, eval questions, prod
      verification. The red spec's table of contents. Trimmable at standard. -->
 
-## Acceptance criteria
+## Definition of done
 
-<!-- These freeze at lock (`lifecycle.yaml` `lock.freezes`). Write them testable — the red spec derives
-     from this list. -->
+<!-- Written as checks, before the build. The verifier proves each line from a
+     fresh run. Name each existing test this work expects to change. -->
 
 1. …
 
-## Lock block
+## Kind of change, impact and undo
 
-<!-- Stamped by `sdlc-task lock`; never hand-edited afterwards. -->
+<!-- A change that cannot be undone goes in bold at the top of this doc. -->
 
-```
-LOCKED: <date> by <ratifier>
-Tier: <tier>
-Frozen: AC (sha256 of the AC section), interfaces: <list>, approach: <chosen>
-Tripwires in force: AC / security / schema / cost (kernel defaults)
-Emitted: <child containers / issues created at lock>
-```
+- Kind: …
+- Impact: …
+- Undo: …
+- Existing tests changed or removed: …
+
+## Approval
+
+<!-- The owner's approval of this short design is the lock (target design,
+     flow 4). Record the owner's words here and with decision_record. A change
+     after approval is a new approval, dated, in the same place. -->
+
+Approved: <date>. The owner's words: "<words>".
 
 ## Deviation log (post-lock)
 
 <!-- Every post-lock divergence from this document. Review checks this list.
-     A deviation touching a tripwire (AC, security, schema, cost) must halt
+     A deviation touching a tripwire (definition of done, security, schema, cost) must halt
      and return to the owner instead of landing here. -->
 
 | # | What changed vs the doc | Why | Tripwire? | Reviewed |

package/work/lib/delivery.mjs

@@ -12,7 +12,7 @@
 //      reopen points at the delivery it corrects with the corrects edge (R9).
 //   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 } from './verb-fields.mjs';
+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';
 
 export const DELIVERY_WRITE_VERBS = Object.freeze(['item_done', 'item_reopen']);
@@ -353,14 +353,20 @@ export function createDeliveryVerbs(core) {
       // or a repo whose kind was never set, keeps the three checks. Nothing
       // weakens by omission, and a mixed-kind item takes the strict path
       // because one of its repos demands it.
+      //
+      // Stage 1 reads a list of kinds. The strict path applies when any kind
+      // of any named repo is live (service or schema). A cli and a plugin
+      // prove delivery like a library until the trial install of stage 2.
       const named = (Array.isArray(fields.repos) ? fields.repos : []).map((id) => reg.repos.get(id)).filter(Boolean);
-      const unset = named.filter((repo) => !repo.fields?.kind).map((repo) => repo.fields.registry_id);
-      const strictKinds = named.filter((repo) => repo.fields?.kind && repo.fields.kind !== 'library').map((repo) => `${repo.fields.registry_id} is a ${repo.fields.kind}`);
+      const kindsOf = (repo) => repoKinds(repo.fields);
+      const said = (repo) => `${repo.fields.registry_id} is a ${kindsOf(repo).join(' and ')}`;
+      const unset = named.filter((repo) => !kindsOf(repo).length).map((repo) => repo.fields.registry_id);
+      const strictKinds = named.filter((repo) => kindsOf(repo).some((kind) => LIVE_KINDS.includes(kind))).map(said);
       const live = !named.length || unset.length > 0 || strictKinds.length > 0;
       const healthUrl = text(product.fields?.health_url, `product ${product.fields.registry_id} health_url`, { optional: true, max: 2000 });
       if (live && !healthUrl) {
         const why = !named.length ? 'the item names no registered repo' : (unset.length ? `repo ${unset.join(', ')} carries no kind` : `${strictKinds.join(', ')}`);
-        refuse(`product ${product.fields.registry_id} has no health_url, and the live checks apply because ${why}; the owner sets it with product edit, or sets the repo kind to library, which is the one kind whose merge is its delivery`);
+        refuse(`product ${product.fields.registry_id} has no health_url, and the live checks apply because ${why}; the owner sets it with product edit, or sets the repo kinds with repo edit; a library, a cli and a plugin are proved by the merge`);
       }
       // Which pull requests deliver this item. The caller names them, always.
       // An earlier draft fell back to the item's own pr links, and the first
@@ -373,7 +379,7 @@ export function createDeliveryVerbs(core) {
       if (!given.length) refuse('prs must name at least one merged pull request');
       let spec = null;
       if (live) { spec = functionalSpec(args.functional); allowedPath(spec, product, healthUrl); }
-      else if (args.functional !== undefined) refuse(`functional is not accepted for this delivery: ${named.map((repo) => `${repo.fields.registry_id} is a ${repo.fields.kind}`).join(', ')}, so there is no deployed page to read. The merge and the gate prove it.`);
+      else if (args.functional !== undefined) refuse(`functional is not accepted for this delivery: ${named.map(said).join(', ')}, so there is no deployed page to read. The merge and the gate prove it.`);
       const note = text(args.note, 'note', { optional: true, max: 2000 }) ?? '';
 
       const repos = new Set(Array.isArray(fields.repos) ? fields.repos : []);
@@ -434,7 +440,7 @@ export function createDeliveryVerbs(core) {
       const checks = live ? [contains, health, functional] : [{
         name: 'every named pull request is merged',
         result: 'pass',
-        detail: `${pulls.length} pull request${pulls.length === 1 ? '' : 's'} merged on GitHub: ${pulls.map((pull) => `${pull.url} at ${pull.merge_commit_sha.slice(0, 7)}`).join(', ')}. No live check ran: ${named.map((repo) => `${repo.fields.registry_id} is a ${repo.fields.kind}`).join(', ')}, so the product has no deployed endpoint to read (amendment A1.7).`,
+        detail: `${pulls.length} pull request${pulls.length === 1 ? '' : 's'} merged on GitHub: ${pulls.map((pull) => `${pull.url} at ${pull.merge_commit_sha.slice(0, 7)}`).join(', ')}. No live check ran: ${named.map(said).join(', ')}, so the product has no deployed endpoint to read (amendment A1.7).`,
         checked_at: now(),
       }];
       const mark = await create(type, requestId, 'item_done', {

package/work/lib/verb-fields.mjs

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

package/work/lib/verbs.mjs

@@ -11,24 +11,22 @@
 // lock block L1, L2 and L3. Every write carries request_id and writer. The
 // server, not the caller, supplies the session. Unknown ids are refused.
 // M2 slice L1 adds the repo kind in 0.5.0, which carries 0.4.0 whole.
-import manifestCurrent from '../manifest-0.5.0.json' with { type: 'json' };
+// Stage 1 of the target design adds kinds, a list, in 0.6.0.
+import manifestCurrent from '../manifest-0.6.0.json' with { type: 'json' };
 import { EngramHttpError } from './client.mjs';
-import { VerbError, refuse, canonicalJson, sha256, text, oneOf, origin, url, stringList, LIVE_LIFECYCLES } from './verb-fields.mjs';
+import { VerbError, refuse, canonicalJson, sha256, text, oneOf, origin, url, stringList, LIVE_LIFECYCLES, REPO_KINDS, LIVE_KINDS, repoKinds, kindsFromArgs } from './verb-fields.mjs';
 import { createQuestionVerbs, COSTS, QUESTION_WRITE_VERBS, QUESTION_READ_VERBS } from './questions.mjs';
 import { createDeliveryVerbs, DELIVERY_WRITE_VERBS, DELIVERY_READ_VERBS } from './delivery.mjs';
 import { createCapabilityVerbs, CAPABILITY_READ_VERBS } from './capability.mjs';
 import { createSweepVerbs, SWEEP_WRITE_VERBS, SWEEP_READ_VERBS } from './sweep.mjs';
 
-export { VerbError, canonicalJson, sha256, COSTS, LIVE_LIFECYCLES };
-export const MANIFEST_VERSION = '0.5.0';
+export { VerbError, canonicalJson, sha256, COSTS, LIVE_LIFECYCLES, REPO_KINDS, LIVE_KINDS, repoKinds };
+export const MANIFEST_VERSION = '0.6.0';
 export const PRODUCT_ID = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
 export const REPO_ID = /^[A-Za-z0-9](?:[A-Za-z0-9_.-]{0,99})\/[A-Za-z0-9_.-]{1,100}$/;
 export const STAGES = Object.freeze(['capture', 'spec', 'build', 'verify', 'learn']);
 export const TIERS = Object.freeze(['hotfix', 'standard', 'initiative']);
 export const DRIVERS = Object.freeze(['owner-led', 'agent']);
-// The repo kind of M2 amendment A1.5. The repo-shape check reads it to decide
-// which of the seven files a repo needs.
-export const REPO_KINDS = Object.freeze(['service', 'library', 'schema']);
 // What an item waits on (release 0.2.3). One line on the item, shown on its
 // rows. "item" names another work item by id.
 export const WAITS_ON = Object.freeze(['owner-decision', 'owner-action', 'item', 'gate', 'nothing']);
@@ -240,7 +238,7 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
     async registry_list() {
       const reg = await registry();
       const products = [...reg.products.values()].map((row) => ({ registry_id: row.fields.registry_id, name: row.fields.name, entity_id: row.id, project_id: row.fields.project_id ?? null, notes: row.fields.notes ?? '',
-        repos: [...reg.repos.values()].filter((repo) => repo.fields.product === row.fields.registry_id).map((repo) => ({ registry_id: repo.fields.registry_id, entity_id: repo.id, kind: repo.fields.kind ?? null, default_branch: repo.fields.default_branch, notes: repo.fields.notes ?? '' })) }));
+        repos: [...reg.repos.values()].filter((repo) => repo.fields.product === row.fields.registry_id).map((repo) => ({ registry_id: repo.fields.registry_id, entity_id: repo.id, kind: repo.fields.kind ?? null, kinds: repoKinds(repo.fields), default_branch: repo.fields.default_branch, notes: repo.fields.notes ?? '' })) }));
       return { verb: 'registry_list', products, read_at: now() };
     },
 
@@ -298,7 +296,9 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
       if (typeof readGitHub !== 'function') refuse('repo add needs a GitHub reader for the push-rights check');
       const registryId = text(args.registry_id, 'registry_id', { max: 200 });
       if (!REPO_ID.test(registryId)) refuse('registry_id must be a GitHub "owner/repo" name');
-      const kind = oneOf(args.kind, 'kind', REPO_KINDS);
+      const given = kindsFromArgs(args);
+      if (!given) refuse('kind is required: give kinds, a list of what the repo is');
+      const { kinds, kind } = given;
       const notes = text(args.notes, 'notes', { optional: true, max: 4000 }) ?? '';
       const reg = await registry();
       const product = await requireProduct(args.product, reg);
@@ -310,10 +310,10 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
       const defaultBranch = text(github.default_branch, 'GitHub default_branch', { max: 200 });
       const type = await typeNamed('repo');
       const prior = await landed(type, requestId, meta);
-      if (prior) { await edge(prior, product, 'part_of', requestId); return { verb: 'repo_add', registry_id: prior.fields.registry_id, product: prior.fields.product, kind: prior.fields.kind ?? null, default_branch: prior.fields.default_branch, entity_id: prior.id, version: prior.version, push_rights: true, replayed_from_graph: true }; }
-      const entity = await create(type, requestId, 'repo_add', { digest: meta?.digest, title: registryId, body: `Atlas repo record for ${registryId}, product ${product.fields.registry_id}. Kind: ${kind}. Default branch: ${defaultBranch}.`, fields: { registry_id: registryId, product: product.fields.registry_id, kind, default_branch: defaultBranch, notes, github_url: github.html_url ?? `https://github.com/${registryId}` }, tags: ['atlas-registry', `product:${product.fields.registry_id}`, `repo:${registryId}`] });
+      if (prior) { await edge(prior, product, 'part_of', requestId); return { verb: 'repo_add', registry_id: prior.fields.registry_id, product: prior.fields.product, kind: prior.fields.kind ?? null, kinds: repoKinds(prior.fields), default_branch: prior.fields.default_branch, entity_id: prior.id, version: prior.version, push_rights: true, replayed_from_graph: true }; }
+      const entity = await create(type, requestId, 'repo_add', { digest: meta?.digest, title: registryId, body: `Atlas repo record for ${registryId}, product ${product.fields.registry_id}. Kinds: ${kinds.join(', ')}. Default branch: ${defaultBranch}.`, fields: { registry_id: registryId, product: product.fields.registry_id, kind, kinds, default_branch: defaultBranch, notes, github_url: github.html_url ?? `https://github.com/${registryId}` }, tags: ['atlas-registry', `product:${product.fields.registry_id}`, `repo:${registryId}`] });
       await edge(entity, product, 'part_of', requestId);
-      return { verb: 'repo_add', registry_id: registryId, product: product.fields.registry_id, kind, default_branch: defaultBranch, entity_id: entity.id, version: entity.version, push_rights: true };
+      return { verb: 'repo_add', registry_id: registryId, product: product.fields.registry_id, kind, kinds, default_branch: defaultBranch, entity_id: entity.id, version: entity.version, push_rights: true };
     },
 
     async repo_edit(args, requestId, meta) {
@@ -325,7 +325,8 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
       await requireProduct(record.fields.product, reg);
       const fields = {};
       if (args.notes !== undefined) fields.notes = text(args.notes, 'notes', { max: 4000 });
-      if (args.kind !== undefined) fields.kind = oneOf(args.kind, 'kind', REPO_KINDS);
+      const given = kindsFromArgs(args);
+      if (given) { fields.kind = given.kind; fields.kinds = given.kinds; }
       if (args.refresh_default_branch === true) {
         if (typeof readGitHub !== 'function') refuse('refreshing the default branch needs a GitHub reader');
         const github = await readGitHub(`repos/${registryId}`);
@@ -333,10 +334,10 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
         fields.default_branch = text(github.default_branch, 'GitHub default_branch', { max: 200 });
       }
       if (alreadyPatched(record, requestId, meta)) return { verb: 'repo_edit', registry_id: registryId, entity_id: record.id, version: record.version, changed: [], replayed_from_graph: true };
-      if (!Object.keys(fields).length) refuse('repo edit needs kind, notes or refresh_default_branch; registry_id and product are immutable');
+      if (!Object.keys(fields).length) refuse('repo edit needs kind, notes or refresh_default_branch (kind may be given as kinds, a list); registry_id and product are immutable');
       // The kind is a field, not a tag: repo edit may change it, and a tag cannot be dropped.
       const entity = await patch(record, 'repo_edit', requestId, fields, { digest: meta?.digest });
-      return { verb: 'repo_edit', registry_id: registryId, entity_id: entity.id, version: entity.version, kind: entity.fields.kind ?? null, changed: Object.keys(fields) };
+      return { verb: 'repo_edit', registry_id: registryId, entity_id: entity.id, version: entity.version, kind: entity.fields.kind ?? null, kinds: repoKinds(entity.fields), changed: Object.keys(fields) };
     },
 
     async item_propose(args, requestId, meta) {

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

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

package/work/mcp.mjs

@@ -25,6 +25,7 @@ const ATLAS_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.
 const S = (description, extra = {}) => ({ type: 'string', description, ...extra });
 const ORIGIN = { type: 'object', description: "The owner's words, verbatim, with where and when they were said.", required: ['text', 'source', 'date'], properties: { text: S('Verbatim words of the owner.'), source: S('Where the words are on record: a chat turn, a doc URL, an issue.'), date: S('ISO date, in the form YYYY-MM-DD.') } };
 const REQUEST_ID = S('Stable unique id for this request. A retry with the same id and the same arguments is a no-op that returns the first receipt. The same id with different arguments is refused.');
+const KINDS = { type: 'array', items: { type: 'string', enum: [...REPO_KINDS] }, description: `What the repo is, as a list: one or more of ${REPO_KINDS.join(', ')}. A service or a schema repo keeps the live checks of item_done; a library, a cli and a plugin are proved by the merge.` };
 const RULES = 'Rules: every write needs request_id. Never pass writer, session, actor or role; the server stamps them. Unknown product or repo ids are refused.';
 
 const CODE_FINDING = { type: 'object', required: ['statement', 'path', 'line'], properties: { name: S('Short label for the finding.'), statement: S('One sentence about what the code does, or what bounds it.'), path: S('Repo-relative path the claim is read from. A never-read path is refused.'), line: { type: 'integer', description: 'The line the claim is read from, 1 or higher.' }, quote: S('The minimal proving line. Never from a never-quote path; a quote from one is refused.') } };
@@ -33,13 +34,13 @@ const CODE_DIGEST = { type: 'object', description: 'One sub-agent digest for one
 
 export const TOOLS = [
   { name: 'registry_list', description: `List the registered products and their repos with registry ids and entity ids. When: before any item verb, to find the ids to pass. Scope: read, no owner flag needed. ${RULES}`, inputSchema: { type: 'object', properties: {}, additionalProperties: false } },
-  { name: 'setup', description: `Publish atlas-work ${MANIFEST_VERSION} to the tenant's Forge and register its types (product, repo with its kind, container, decision, question, receipt, mark and the surviving edges). Idempotent. When: once per tenant, before the first product add, and again after a manifest change. Owner present only. ${RULES}`, inputSchema: { type: 'object', required: ['request_id'], properties: { request_id: REQUEST_ID }, additionalProperties: false } },
+  { name: 'setup', description: `Publish atlas-work ${MANIFEST_VERSION} to the tenant's Forge and register its types (product, repo with its kinds, container, decision, question, receipt, mark and the surviving edges). Idempotent. When: once per tenant, before the first product add, and again after a manifest change. Owner present only. ${RULES}`, inputSchema: { type: 'object', required: ['request_id'], properties: { request_id: REQUEST_ID }, additionalProperties: false } },
   { name: 'product_add', description: `Register a product in the name registry. Refuses when the id exists. When: a product gets its first work item. Owner present only. registry_id is a lowercase slug and is immutable. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'registry_id', 'name'], properties: { request_id: REQUEST_ID, registry_id: S('Lowercase slug, for example "engram". Immutable.'), name: S('Display name.'), project_id: S('Entity id of the existing Engram project entity this product links to.'), health_url: S('Absolute https URL of the deployed app\'s health endpoint. The done verb reads the deployed commit there, and every live check must be on this origin.'), check_paths: { type: 'array', items: { type: 'string' }, description: 'Absolute paths on that origin the functional check of item_done may read, for example ["/v1/housekeeping"]. Unset, the check may read only the health endpoint\'s own path.' }, notes: S('Free text.') }, additionalProperties: false } },
   { name: 'product_edit', description: `Change a product's name, notes, health endpoint, check paths or project link. Refuses an unknown id. The registry id never changes. Owner present only. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'registry_id'], properties: { request_id: REQUEST_ID, registry_id: S('Existing product id.'), name: S('New display name.'), project_id: S('Entity id of an Engram project entity.'), health_url: S('Absolute https URL of the deployed app\'s health endpoint.'), check_paths: { type: 'array', items: { type: 'string' }, description: 'Absolute paths the functional check of item_done may read on that origin.' }, notes: S('Free text.') }, additionalProperties: false } },
-  { name: 'repo_add', description: `Register a GitHub repo under a product. The server reads GitHub itself: the id must equal the repo's full name and the owner must have push rights, or the add is refused. The default branch comes from GitHub. The kind says which of the seven Atlas files the repo needs. Refuses an unknown product id and an existing repo id; repo ids are immutable. Owner present only. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'registry_id', 'product', 'kind'], properties: { request_id: REQUEST_ID, registry_id: S('GitHub "owner/repo", exact spelling.'), product: S('Existing product id.'), kind: S(`What the repo is. One of ${REPO_KINDS.join(', ')}. The repo-shape check reads it.`), notes: S('Free text.') }, additionalProperties: false } },
-  { name: 'repo_edit', description: `Change a repo's kind or notes, or refresh its default branch from GitHub. registry_id and product never change. Owner present only. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'registry_id'], properties: { request_id: REQUEST_ID, registry_id: S('Existing repo id.'), kind: S(`What the repo is. One of ${REPO_KINDS.join(', ')}. The repo-shape check reads it.`), notes: S('Free text.'), refresh_default_branch: { type: 'boolean', description: 'Re-read the default branch and push rights from GitHub.' } }, additionalProperties: false } },
+  { name: 'repo_add', description: `Register a GitHub repo under a product. The server reads GitHub itself: the id must equal the repo's full name and the owner must have push rights, or the add is refused. The default branch comes from GitHub. The kinds say what the repo is; item_done reads them to choose how a delivery is proved. Give kinds, a list; kind, one value, is the older form. Refuses an unknown product id and an existing repo id; repo ids are immutable. Owner present only. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'registry_id', 'product'], properties: { request_id: REQUEST_ID, registry_id: S('GitHub "owner/repo", exact spelling.'), product: S('Existing product id.'), kinds: KINDS, kind: S(`The older form: one kind. One of ${REPO_KINDS.join(', ')}. Give kinds instead.`), notes: S('Free text.') }, additionalProperties: false } },
+  { name: 'repo_edit', description: `Change a repo's kinds or notes, or refresh its default branch from GitHub. registry_id and product never change. Owner present only. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'registry_id'], properties: { request_id: REQUEST_ID, registry_id: S('Existing repo id.'), kinds: KINDS, kind: S(`The older form: one kind. One of ${REPO_KINDS.join(', ')}. Give kinds instead.`), notes: S('Free text.'), refresh_default_branch: { type: 'boolean', description: 'Re-read the default branch and push rights from GitHub.' } }, additionalProperties: false } },
   { name: 'item_propose', description: `Create a proposed work item (lifecycle proposed, stage capture) for a product, with its repos and the owner's words as origin. When: the owner names a piece of work that is not yet locked. Owner present only. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'title', 'product', 'repos', 'origin'], properties: { request_id: REQUEST_ID, title: S('Short title in the owner\'s words.'), product: S('Product id.'), repos: { type: 'array', items: { type: 'string' }, description: 'Repo ids under that product.' }, origin: ORIGIN, tier: S(`One of ${TIERS.join(', ')}. Default standard.`), driver: S(`One of ${DRIVERS.join(', ')}. Default owner-led.`), next_step: S('One line: what happens next.'), summary: S('Short summary.'), body: S('Longer body, optional.'), tags: { type: 'array', items: { type: 'string' } } }, additionalProperties: false } },
-  { name: 'item_lock', description: `Lock a proposed or active item: product and repos by registry id, the scope (text, optional design doc URL and acceptance-criteria hash), and the owner's words as origin. Lifecycle becomes active; stage defaults to build. Refuses an unknown product or repo id, a missing scope or origin, and an item that is already locked. When: the owner says "lock". Owner present only. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'item_id', 'product', 'repos', 'scope', 'origin'], properties: { request_id: REQUEST_ID, item_id: S('Entity id of the work item (container).'), product: S('Product id.'), repos: { type: 'array', items: { type: 'string' }, description: 'Repo ids under that product.' }, scope: { type: 'object', required: ['text'], properties: { text: S('The accepted scope, in full.'), design_doc: S('URL of the design doc at its lock commit.'), acceptance_criteria_hash: S('64-hex sha256 of the frozen acceptance text, when the design doc carries one.') } }, origin: ORIGIN, tier: S(`One of ${TIERS.join(', ')}.`), stage: S(`One of ${STAGES.join(', ')}. Default build.`), driver: S(`One of ${DRIVERS.join(', ')}.`), next_step: S('One line: what happens next.') }, additionalProperties: false } },
+  { name: 'item_lock', description: `Record the owner's approval of a short design: product and repos by registry id, the scope (the definition of done as text, and the design file), and the owner's words of approval as origin. That approval is the lock (target design, flow 4). The verb keeps a fingerprint of the text for the tools; nobody reads or writes a hash. Lifecycle becomes active; stage defaults to build. Refuses an unknown product or repo id, a missing scope or origin, and an item that is already locked; a change after approval is a decision_record on the same item. When: the owner approves the design. Owner present only. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'item_id', 'product', 'repos', 'scope', 'origin'], properties: { request_id: REQUEST_ID, item_id: S('Entity id of the work item (container).'), product: S('Product id.'), repos: { type: 'array', items: { type: 'string' }, description: 'Repo ids under that product.' }, scope: { type: 'object', required: ['text'], properties: { text: S('The definition of done, in full.'), design_doc: S('URL of the design file the owner approved.'), acceptance_criteria_hash: S('Old records only: a 64-hex sha256 a design doc once carried. Omit it.') } }, origin: ORIGIN, tier: S(`One of ${TIERS.join(', ')}.`), stage: S(`One of ${STAGES.join(', ')}. Default build.`), driver: S(`One of ${DRIVERS.join(', ')}.`), next_step: S('One line: what happens next.') }, additionalProperties: false } },
   { name: 'item_split', description: `Split an item into pieces. Each child is a proposed item (stage capture) with a spun_out_of relation to the parent and the reason. Children inherit product, repos, tier, origin and driver unless given. Refuses an unknown parent, a missing reason, or a child repo outside the product. Owner present only. ${RULES}`, inputSchema: { type: 'object', required: ['request_id', 'item_id', 'reason', 'children'], properties: { request_id: REQUEST_ID, item_id: S('Parent item id.'), reason: S('Why the split, in the owner\'s words.'), children: { type: 'array', items: { type: 'object', required: ['title'], properties: { title: S('Child title.'), repos: { type: 'array', items: { type: 'string' } }, tier: S(`One of ${TIERS.join(', ')}.`), origin: ORIGIN, driver: S(`One of ${DRIVERS.join(', ')}.`), next_step: S('One line.'), summary: S('Short summary.') } } } }, additionalProperties: false } },
   { name: 'item_park', description: `Park an item: lifecycle paused with the reason. Paused items are backlog: 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 } },

package/work/protected-paths.json

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

package/door/lib/helpers.mjs

@@ -1,139 +0,0 @@
-// The five helpers, and the entry verb that routes to them.
-//
-// Milestone M2, slice L2 stage one. Authority:
-// Atlas amendment A1.6, section 5, the L2 stage
-// one paragraph; the Atlas architecture record, section 5.1.
-//
-// One helper per class of file. You never pick one. You say what changed, and
-// the entry verb routes it. "We now deploy prod on Fly" reaches Facts, which
-// edits atlas/deploy.yaml, and Procedures, which updates the deploy skill. One
-// request, two helpers, one pull request.
-//
-// What a helper does here: it says which files it owns, it refuses a change to
-// a file it does not own, and it carries the change into one pull request with
-// the fixed label and per-change provenance. It does not draft. An agent in a
-// session drafts, because drafting needs a model and a read of the repository.
-// The tooling helper is the exception: both the files it owns are written from
-// the package, so it needs no model at all.
-import { posix } from 'node:path';
-
-// R13, from the M2 design study's review panel: agent-invoked helper pull
-// requests carried no provenance. Every change now names where it came from,
-// and the set is closed.
-export const PROVENANCE_SOURCES = Object.freeze(['owner words', 'repo read', 'task input']);
-
-// The one label every helper pull request carries. A person filters on it, and
-// slice L4's merge actor reads it.
-export const HELPER_LABEL = 'atlas-helper';
-
-const under = (...prefixes) => (path) => prefixes.some((prefix) => path === prefix || path.startsWith(`${prefix}/`));
-const isOneOf = (...paths) => (path) => paths.includes(path);
-
-export const HELPERS = Object.freeze([
-  {
-    id: 'entry-map',
-    file: 1,
-    title: 'Entry map',
-    owns: isOneOf('CLAUDE.md', 'AGENTS.md'),
-    ownsText: 'CLAUDE.md, AGENTS.md',
-    forWhat: 'Keeps the front door true: what the repo is, how to build it, where things are.',
-    youMightSay: 'the modules moved, refresh the map',
-    words: ['entry map', 'claude.md', 'agents.md', 'front door', 'layout', 'module', 'modules', 'readme', 'structure', 'moved'],
-  },
-  {
-    id: 'rules',
-    file: 2,
-    title: 'Path rules',
-    owns: under('.claude/rules'),
-    ownsText: '.claude/rules/*.md',
-    forWhat: 'Records a constraint that holds under one path only.',
-    youMightSay: 'migrations are append-only under migrations/',
-    words: ['rule', 'rules', 'constraint', 'never', 'append-only', 'forbidden', 'must not', 'policy'],
-  },
-  {
-    id: 'procedures',
-    file: 3,
-    title: 'Procedures',
-    owns: (path) => path.startsWith('.claude/skills/') && path.endsWith('/SKILL.md'),
-    ownsText: '.claude/skills/<name>/SKILL.md',
-    forWhat: 'Keeps the how-to for running, testing, deploying and releasing.',
-    youMightSay: 'we changed how we deploy',
-    words: ['skill', 'procedure', 'how to', 'run locally', 'test', 'tests', 'deploy', 'release', 'ship', 'runbook'],
-  },
-  {
-    id: 'facts',
-    file: 4,
-    title: 'Repo facts',
-    owns: (path) => path === 'atlas.yaml' || under('atlas')(path),
-    ownsText: 'atlas.yaml, atlas/',
-    forWhat: 'Holds where it runs, where the logs are, and every credential by name.',
-    youMightSay: 'add a staging environment on Fly',
-    words: ['fact', 'facts', 'atlas.yaml', 'environment', 'staging', 'prod', 'logs', 'metrics', 'credential', 'credentials', 'dependency', 'dependencies', 'kind', 'deploy target', 'fly', 'region'],
-  },
-  {
-    id: 'tooling',
-    file: 7,
-    title: 'Tooling',
-    owns: (path) => path === '.github/atlas/check.mjs' || path === '.github/workflows/atlas-check.yml',
-    ownsText: '.github/atlas/check.mjs, .github/workflows/atlas-check.yml',
-    forWhat: 'Keeps the automatic checks this repo runs.',
-    youMightSay: 'refresh the Atlas check',
-    words: ['check', 'workflow', 'ci', 'lint', 'linter', 'action', 'tooling', 'refresh the check', 'atlas check'],
-  },
-]);
-
-export const helperById = (id) => HELPERS.find((helper) => helper.id === id) ?? null;
-
-// Which helper owns a path. null means no helper owns it, and no helper may
-// write it.
-export function ownerOf(path) {
-  const clean = posix.normalize(String(path ?? '')).replace(/^\.\//, '');
-  return HELPERS.find((helper) => helper.owns(clean)) ?? null;
-}
-
-// The entry verb's routing. You say what changed; this says which helpers it
-// reaches, in file order. An empty list is an honest answer: it means the
-// sentence names nothing any helper owns, and the caller should say more.
-export function route(say) {
-  const text = String(say ?? '').toLowerCase();
-  if (!text.trim()) return [];
-  return HELPERS.filter((helper) => helper.words.some((word) => text.includes(word)));
-}
-
-// First setup is the same verb. It runs all five, in file order. There is no
-// separate first-run path to maintain.
-export const setupOrder = () => [...HELPERS];
-
-export class HelperError extends Error {}
-
-// Every change a helper carries, checked before anything is written.
-//
-// Two rules, and both are about who may write what. A helper writes only the
-// files it owns, so one request cannot quietly rewrite another class of file.
-// Every change names its source, so a reader of the pull request can tell an
-// owner decision from a guess.
-export function checkChanges(helperId, changes) {
-  const helper = helperById(helperId);
-  if (!helper) throw new HelperError(`there is no helper "${helperId}"; the helpers are ${HELPERS.map((one) => one.id).join(', ')}`);
-  if (!Array.isArray(changes) || !changes.length) throw new HelperError('a helper needs at least one change to carry');
-  for (const change of changes) {
-    const path = String(change?.path ?? '');
-    if (!path) throw new HelperError('a change has no path');
-    if (path.startsWith('/') || path.includes('..')) throw new HelperError(`"${path}" leaves the repo; a helper writes inside one repo only`);
-    if (!helper.owns(path)) {
-      const other = ownerOf(path);
-      throw new HelperError(other
-        ? `the ${helper.id} helper does not own "${path}"; the ${other.id} helper does. Route the change there.`
-        : `no helper owns "${path}"; the five helpers own ${HELPERS.map((one) => one.ownsText).join('; ')}`);
-    }
-    if (typeof change.contents !== 'string') throw new HelperError(`the change to "${path}" carries no contents`);
-    const source = change?.provenance?.source;
-    if (!PROVENANCE_SOURCES.includes(source)) {
-      throw new HelperError(`the change to "${path}" names no source; every change names one of ${PROVENANCE_SOURCES.join(', ')} (review finding R13)`);
-    }
-    if (!String(change?.provenance?.detail ?? '').trim()) {
-      throw new HelperError(`the change to "${path}" names the source "${source}" and says nothing about it; give the words, the file read, or the task`);
-    }
-  }
-  return helper;
-}