@arjunkhera/atlas 0.2.2 → 0.3.0

package/skills/sdlc-task/SKILL.md

@@ -30,27 +30,27 @@ checks and the transition log; each verb's own description says what it needs.
 | Record new work, with the owner's words | `item_propose`, then `item_stage` as it moves |
 | Freeze the design | `item_lock` |
 | Park it, or pick it up again | `item_park`, `item_resume` |
+| 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` |
 | 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` |
 | Say where things stand | `where_are_we`, `in_flight`, `needs_me` |
 
-The repo's own facts come from `atlas.yaml` and `atlas/`. Its `kind` (`service`,
-`library`, `schema`) decides which procedures it has and what "delivered" means.
-Read it. Never assume a deployed service.
+The repo's own facts come from `atlas.yaml` and `atlas/`. Its kinds (`service`,
+`library`, `schema`, `cli`, `plugin`) decide which procedures it has and what
+"delivered" means. Read them. Never assume a deployed service.
 
-A change to the process itself is not a task. It is an amendment to the
-frozen text, and the rule for one is short:
+How to talk with the owner lives in the `atlas:lead` skill: one question at a
+time, a page first with a worked example, plain words, push back. This skill
+does not repeat those rules; follow the lead.
 
-1. Say so at once. Never build against a sentence you know is wrong.
-2. Write the amendment as its own dated file: what changes, why, the new
-   frozen text in full, one new hash over the whole frozen section, and the old
-   hash named as retired.
-3. Never edit frozen text in place. A reviewer's finding is a normal reason to
-   amend.
-
-(Source: the Atlas lock procedure, amendment A1.6, section 12.)
+**A change after the owner approved a design** is not a new lock. Say so at
+once, and never build against a sentence you know is wrong. Show the owner the
+change in one screen. When the owner approves it, record the owner's words with
+`decision_record` on the same item, and write the change into the design file
+with the date. (Target design, flow 4: long frozen texts with hashes retire.)
 
 ## start
 
@@ -68,73 +68,62 @@ frozen text, and the rule for one is short:
    [`templates/design-doc.md`](templates/design-doc.md) to
    `docs/design-docs/<slug>.md`, fill Context and goal, and list it in
    `docs/index.md` in the commit that first lands it. Hotfix tier skips the
-   doc: the acceptance criteria live on the work item, and a resume anchor
+   doc: the definition of done lives on the work item, and a resume anchor
    covers pauses.
 5. Enter the design loop.
 
 ## The design loop (between start and lock)
 
-- **One voice.** The owner talks to one colleague. Crews run behind the
-  curtain as subagents and come back as digests — never as a committee
-  surfacing question lists.
-- **Guided elicitation** (the owner's words: *"one on one
-  conversation that flows… the purpose of agent is to do research and guide my
-  thoughts into useful features"*). Research first, then **one pointed question
-  at a time**, with a recommendation (the owner: *"Questions if posed
-  should be one by one. Just think, if you say 5 things in one go, how do I
-  respond."*). Keep the question queue in the design doc; surface only the
-  next one. Record each question with `question_ask` and each answer with
-  `question_answer`.
-- **Succinct chat; artifacts carry the content** (the owner's words:
-  *"the content is very verbose… I won't read that much"* · *"artefacts should
-  be the default method of communication… use as many diagrams and examples as
-  possible"*). Chat is a few short sentences: the outcome, the artifact link,
-  the one question.
-- **Lead with a worked example.** Real input, real process, real output, and a
-  sequence diagram where order matters. The owner cannot read dense prose.
-- **Read the reason, not only the rule.** Before you build to a done line, read
-  the owner's words behind it and ask whether the thing should exist at all. A
-  done line is a measure, not the goal.
+Talk to the owner by the `atlas:lead` skill. What this loop adds:
+
 - **Research before opinions.** Fan out `atlas:code-explorer` for how the system
-  works today. Raw exploration never enters this session — digests only.
+  works today. Raw exploration never enters this session; digests only.
+- **Read the reason, not only the rule.** Before you build to a definition of
+  done, read the owner's words behind it and ask whether the thing should exist
+  at all.
 - **When the task is a cluster of filed bugs, first ask whether the model
   they presume was ever decided.** A bug report says the code surprised
   someone; it does not say what the code should do.
+- **User stories before the definition of done.** Never write checks for a
+  flow no story walks through.
 - **The doc accretes in real time.** Every resolved question, decision and
-  approach lands in the design doc as it happens. The doc is the pause and
-  resume state. Record each decision with `decision_record`.
-- **HTML is the owner's reading surface.** Any design, review or status the
-  owner reads is a styled artifact, rendered by the `atlas:artifact-renderer`
-  crew. Its treatment contract lives in that crew; do not restate it.
-- **No bare acronyms in front of the owner.** Spell a thing out on first
-  mention. Ids are for the machine; names are for the human.
-- **User stories before acceptance criteria** (the owner's words:
-  *"I need to see how a user would use the product, or like how the flow
-  works"*). Never draft criteria for a flow no story walks through.
-- **Adversarial review before lock.** Standard tier: at least one persona.
-  Initiative: the panel — `atlas:reviewer-pm`, `atlas:reviewer-architect`,
-  `atlas:reviewer-security` — each briefed with the doc path, in parallel. Brief each
-  one to ask whether the design is the right thing, not only whether it is
-  consistent. An unresolved finding goes into the doc's open questions, and
-  that blocks the lock.
+  approach lands in the design doc as it happens. Record each question with
+  `question_ask`, each answer with `question_answer`, each decision with
+  `decision_record`.
+- **Adversarial review before the owner approves.** Standard tier: at least one
+  persona. Initiative: the panel, `atlas:reviewer-pm`, `atlas:reviewer-architect`
+  and `atlas:reviewer-security`, each briefed with the doc path, in parallel.
+  Brief each one to ask whether the design is the right thing. An unresolved
+  finding goes into the doc's open questions.
 
 ## lock
 
-Gate on `lifecycle.yaml` `lock.preconditions`, all four: the open questions
-are empty, the owner ratified the criteria, the approach is chosen, the tier
-is confirmed. Then:
-
-1. Stamp the design doc's lock block: date, ratifier, tier, the sha256 of the
-   acceptance criteria text, frozen interfaces, the work list. Commit.
-2. Call `item_lock` with the frozen scope and its hash.
-3. Build against the frozen text. **Tripwires** (`lifecycle.yaml`
-   `tripwires`): a discovery after lock that touches the criteria, security,
-   a schema or cost stops the build and goes back to the owner. If the frozen
-   text is wrong, say so at once and write an amendment. Never build against a
-   sentence you know is wrong.
-4. Test with the repo's own `test` procedure, which `atlas.yaml` names. Open a
-   pull request. Keep a separate acceptance reviewer, and close its findings
-   before acceptance.
+A lock is the owner's approval of a short design (target design, flow 4).
+
+1. **The design is short and sized to the work.** A feature gets a full
+   document; a small fix gets a one-screen card. It holds what
+   `lifecycle.yaml` `lock.holds` lists: the definition of done, written as checks; the kind of change, its impact and its undo; and
+   each existing test it expects to change. A change that cannot be undone
+   shows in bold at the top.
+2. **The owner approves it in the owner's own words.** Gate on
+   `lifecycle.yaml` `lock.preconditions`. Record the words with
+   `decision_record`, and mark the design doc "Approved <date>", with the words.
+3. Call `item_lock` with the definition of done as `scope.text` and the design
+   file as `scope.design_doc`. The verb keeps a fingerprint of that text for
+   the tools. No person reads or writes a hash, and no frozen text is copied
+   into the doc.
+4. Build against the approved design. **Tripwires** (`lifecycle.yaml`
+   `tripwires`): a discovery that touches the definition of done, security, a
+   schema or cost stops the build and goes back to the owner, as a change after
+   approval (above).
+5. Test with the repo's own `test` procedure, which `atlas.yaml` names. Open a
+   pull request. Its text holds the definition of done, the kind of change, the
+   undo, and the list of existing tests it changes or removes, and it links the
+   tracker item.
+6. **Proof before the merge.** Run the `atlas:verifier` agent on the pull
+   request. It proves each line of the definition of done from a fresh run and
+   posts its own proof comment. Never edit that comment. Ask the owner for the
+   merge only after the proof is there, and show the proof first.
 
 ## pause
 
@@ -142,6 +131,9 @@ is confirmed. Then:
    resume anchor from [`templates/resume-anchor.md`](templates/resume-anchor.md)
    (hotfix). The bar: a fresh session needs nothing else.
 2. Call `item_park` with the reason. A parked item keeps its stage.
+3. Before the session ends, keep each item you touched true: call
+   `item_edit` with its next step and what it waits on. If the owner retires
+   a piece of work, call `item_drop` with his words.
 
 ## resume
 
@@ -160,8 +152,9 @@ next action. One short paragraph.
 ## done
 
 1. Prove delivery the way the repo's `kind` requires, then call `item_done`. A
-   `library` or `schema` repo proves it by merged pull requests and a green
-   gate. A `service` repo also needs its live checks.
+   `library` repo proves it by merged pull requests and a green gate. A
+   `service` or `schema` repo also needs its live checks, because a schema
+   migration reaches the running node after the merge.
 2. If anything was a struggle, encode the fix where it stops a repeat — a lint,
    then a tool, then a skill, then a doc — and say which.
 3. Design doc status: `SHIPPED <date>`.

package/skills/sdlc-task/lifecycle.yaml

@@ -2,7 +2,9 @@
 #
 # Atlas is the package that sets how a repo is worked on, and this is its
 # lifecycle. It travels with the package, beside the skill that reads it, not
-# with any one repo. A verb reads these lists; it never hard-codes them.
+# with any one repo. The skill reads these lists. The work verbs still keep
+# their own copies (STAGES and LIVE_LIFECYCLES in work/lib), and the stage
+# lists differ on ship; the register records that gap.
 #
 # The values came from the old ops pack, unchanged. That pack and every script
 # that read it are deleted.
@@ -12,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

@@ -1,4 +1,4 @@
-<!-- Living design document — template (lifecycle spec §7, LC-5).
+<!-- Living design document — template (sdlc-task skill, "The design loop").
      Copy to docs/design-docs/<slug>.md at `sdlc-task start` (standard/initiative
      tiers). Sections may be trimmed at standard tier; never at initiative.
      The artifact projection republishes on change (D14: git is truth).
@@ -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 (LC-6). 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/skills/sdlc-task/templates/resume-anchor.md

@@ -1,16 +1,18 @@
-<!-- Resume anchor — template (lifecycle spec §8).
+<!-- Resume anchor — template (sdlc-task skill, "pause").
      For work BELOW the design-doc threshold: hotfix tier, bug investigations,
-     any interrupted queue work. Posted as a comment on the issue (queue lane)
-     or the container thread (conversation lane) at every pause AND at stage
-     transitions of long-running work.
-     The bar (and the eval): a fresh session given only this anchor proceeds
-     without asking the owner anything the anchor should have contained. -->
+     any interrupted work. Write it at every pause AND at stage transitions of
+     long-running work. Keep it where the work item can point at it: a file in
+     the repo or a comment on the issue, attached with `item_link`. Put its
+     next action in the item's next step with `item_edit`.
+     The bar: a fresh session given only this anchor proceeds without asking
+     the owner anything the anchor should have contained. No eval checks this
+     bar yet; the reviewer judges it. -->
 
 ## ⏸ Resume anchor — <date>
 
 **Goal:** <one line, owner-verbatim where possible>
 
-**State:** lifecycle `<active|paused>` · stage `<capture|spec|build|verify|ship|learn>`
+**State:** lifecycle `<active|paused>` · stage `<capture|spec|build|verify|learn>`
 
 **Findings so far:** <POINTER to where they live — issue comment link, doc
 path, graph entity id. Never duplicate content inline.>

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 } from './questions.mjs';
+import { oneLine, scrubSecrets, ROW_LINE_MAX, priorityOrderOf, byPriority, orderNote, waitsOnLine } from './questions.mjs';
 import { listLine, legacySealOf, marksByItem, movementOf, pullsOfItem, readPullsByRepo, correctionsOf, daysBetween } from './delivery.mjs';
 import { acceptCodeRead, codeReadBrief } from './code-read.mjs';
 
@@ -259,7 +259,7 @@ export function createCapabilityVerbs(core) {
           const born = fields.created_at ?? item.created_at ?? null;
           proposed.push({ ...base, age_days: born ? daysBetween(born, readAt) : null, proposed_at: born, driver: clean(fields.driver ?? '', 64) });
         } else if (lifecycle !== 'done' && !deliveries.length) {
-          omitted.push({ item: item.id, title: clean(item.title, 120), reason: `the item is ${clean(lifecycle, 32)}; paused and archived items are backlog (D3 rule 1)` });
+          omitted.push({ item: item.id, title: clean(item.title, 120), reason: lifecycle === 'dropped' ? 'the owner dropped this item' : `the item is ${clean(lifecycle, 32)}; paused and archived items are backlog (D3 rule 1)` });
         }
       }
       inProgress.sort((a, b) => (a.days_since_last_change ?? Number.MAX_SAFE_INTEGER) - (b.days_since_last_change ?? Number.MAX_SAFE_INTEGER) || a.item.localeCompare(b.item));
@@ -382,8 +382,10 @@ export function createCapabilityVerbs(core) {
       // does not carry: an item with none reads "unregistered", as the six-part
       // answer already renders it.
       const items = only ? rows.filter((row) => row.fields?.product === only) : rows;
-      const unregisteredTotal = rows.filter((row) => !registered(row)).length;
-      const unregisteredShown = items.filter((row) => !registered(row)).length;
+      // A dropped item is counted once, under "Dropped by you", never as unsorted.
+      const unsorted = (row) => !registered(row) && row.fields?.lifecycle !== 'dropped';
+      const unregisteredTotal = rows.filter(unsorted).length;
+      const unregisteredShown = items.filter(unsorted).length;
       const marks = await marksFor(new Set(items.map((row) => row.id)));
       const readAt = now();
       let redactions = 0;
@@ -415,7 +417,7 @@ export function createCapabilityVerbs(core) {
       // own, and it must not pass through the one-line flattener. The count is
       // read after the walk, so the walk's own finds are counted too (L1).
       const scrubbed = ({ text, ...rest }) => { const rows = cleanDeep(rest); return { ...rows, redactions: redactions + rendered.redactions, text }; };
-      const built = [], building = [], pending = [], possible = [];
+      const built = [], building = [], pending = [], possible = [], dropped = [];
       for (const item of items) {
         const fields = item.fields ?? {};
         const { rows: deliveries, marks: own } = deliveriesOf(item, marks);
@@ -431,24 +433,24 @@ 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' });
-        if (fields.lifecycle === 'active') building.push({ ...base, 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, reason: clean(fields.pause_reason ?? 'no reason on record', 300), days_since_last_change: days, parked_at: fields.parked_at ?? null });
+        const waits = fields.waits_on && typeof fields.waits_on === 'object' ? { waits_on: fields.waits_on } : {};
+        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') {
           const born = fields.created_at ?? item.created_at ?? null;
-          possible.push({ ...base, age_days: born ? daysBetween(born, readAt) : null, proposed_at: born, driver: clean(fields.driver ?? '', 64) });
-        }
+          possible.push({ ...base, ...waits, age_days: born ? daysBetween(born, readAt) : null, proposed_at: born, driver: clean(fields.driver ?? '', 64) });
+        } else if (fields.lifecycle === 'dropped') dropped.push({ ...base, dropped_at: fields.dropped_at ?? null });
       }
-      built.sort((a, b) => String(b.delivered_at ?? '').localeCompare(String(a.delivered_at ?? '')));
-      building.sort((a, b) => (a.days_since_last_change ?? Number.MAX_SAFE_INTEGER) - (b.days_since_last_change ?? Number.MAX_SAFE_INTEGER) || a.item.localeCompare(b.item));
-      pending.sort((a, b) => (a.days_since_last_change ?? Number.MAX_SAFE_INTEGER) - (b.days_since_last_change ?? Number.MAX_SAFE_INTEGER) || a.item.localeCompare(b.item));
-      possible.sort((a, b) => (b.age_days ?? 0) - (a.age_days ?? 0));
-
       // The decisions that set the order. The owner's words are what ordered
-      // this work, so the view ends with them, newest first.
+      // this work, so the view ends with them, newest first. Release 0.2.3:
+      // his newest priority decision also orders the rows above.
       const products = only ? [only] : [...new Set(items.filter(registered).map((row) => row.fields.product))];
       const order = [];
+      const orders = new Map();
       for (const productId of products) {
-        for (const row of await decisionsFor(productId)) {
+        const decisions = await decisionsFor(productId);
+        orders.set(productId, priorityOrderOf(decisions, productId));
+        for (const row of decisions) {
           if (since && String(row.fields?.date ?? '') < since) continue;
           if (row.fields?.kind === 'priority' || (Array.isArray(row.fields?.priority_order) && row.fields.priority_order.length)) {
             order.push({ decision: row.id, product: productId, kind: row.fields?.kind ?? 'decision', date: row.fields?.date ?? '', text: clean(row.fields?.text ?? row.title, 400), priority_order: row.fields?.priority_order ?? [], citation: { decision: row.id, date: row.fields?.date ?? '', source: row.fields?.source ?? '' } });
@@ -456,6 +458,12 @@ export function createCapabilityVerbs(core) {
         }
       }
       order.sort((a, b) => String(b.date).localeCompare(String(a.date)));
+      const byDays = (a, b) => (a.days_since_last_change ?? Number.MAX_SAFE_INTEGER) - (b.days_since_last_change ?? Number.MAX_SAFE_INTEGER) || a.item.localeCompare(b.item);
+      built.sort((a, b) => String(b.delivered_at ?? '').localeCompare(String(a.delivered_at ?? '')));
+      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)}` : '');
 
       // D3 rule 2: a row names its product. The board does not group, so every
       // line carries the id (review H6).
@@ -464,20 +472,23 @@ export function createCapabilityVerbs(core) {
       const block = [
         `Built, pending, possible — ${only ?? `every product${unregisteredShown ? `, and ${plural(unregisteredShown, 'item')} that name${unregisteredShown === 1 ? 's' : ''} none` : ''}`} · read ${readAt.slice(0, 19)}Z${since ? ` · since ${since}` : ''}`,
         section(since ? `Built since ${since}` : 'Built', built, (row) => listLine(row.title, `${where_(row)} · ${row.verdict} ${day(row.delivered_at)} · ${prsOf(row)} · ${row.item}${row.mark_id ? ` · mark ${row.mark_id.slice(0, 8)}` : ''}`)),
-        section('Building', building, (row) => listLine(`${row.title} · ${row.stage || 'no stage'} · next: ${row.next_step || 'not set'}`, `${where_(row)} · ${row.item} · ${row.days_since_last_change === null ? 'no movement on record' : `${plural(row.days_since_last_change, 'day')} since ${row.last_change_source}`}`)),
-        section('Pending, parked until someone returns to it', pending, (row) => listLine(`${row.title} — ${row.reason}`, `${where_(row)} · ${row.item}`)),
-        section('Possible, proposed and waiting for a yes', possible, (row) => listLine(row.title, `${where_(row)} · ${row.age_days === null ? 'age unknown' : `${plural(row.age_days, 'day')} old`} · ${row.item}`)),
+        section('Building', building, (row) => listLine(`${row.title} · ${row.stage || 'no stage'}${waitsOf(row)} · next: ${row.next_step || 'not set'}`, `${where_(row)} · ${row.item} · ${row.days_since_last_change === null ? 'no movement on record' : `${plural(row.days_since_last_change, 'day')} since ${row.last_change_source}`}${orderNote(orders, row)}`)),
+        section('Pending, parked until someone returns to it', pending, (row) => listLine(`${row.title}${waitsOf(row)} — ${row.reason}`, `${where_(row)} · ${row.item}${orderNote(orders, row)}`)),
+        section('Possible, proposed and waiting for a yes', possible, (row) => listLine(`${row.title}${waitsOf(row)}`, `${where_(row)} · ${row.age_days === null ? 'age unknown' : `${plural(row.age_days, 'day')} old`} · ${row.item}${orderNote(orders, row)}`)),
         section('The decisions that set the order', order, (row) => listLine(`${row.kind}: ${row.text}`, `${row.product} · ${row.date} · ${row.decision}`)),
-        ...(unregisteredTotal ? [[
-          `Not in the registry (${unregisteredTotal}${only ? '' : `, ${unregisteredShown} of them in the rows above, named "unregistered"`})`,
+        ...(dropped.length ? [`Dropped by you (${dropped.length}): they stay in the graph, and no live list names them.`] : []),
+        // Release 0.2.3: a read narrowed to
+        // one product says nothing about items that name no product. The
+        // count stays in the result, as unregistered_total.
+        ...(unregisteredTotal && !only ? [[
+          `Not in the registry (${unregisteredTotal}, ${unregisteredShown} of them in the rows above, named "unregistered")`,
           '   The slice L5 sweep gives them a product.',
-          ...(only ? ['   A read narrowed to one product cannot show them: an item with no product belongs to none.'] : []),
         ].join('\n')] : []),
       ].join('\n\n');
       const rendered = scrubSecrets(block);
       return scrubbed({
         verb: 'built_pending_possible', read_at: readAt, product: only, since,
-        built, building, pending, possible, order, unregistered_total: unregisteredTotal, unregistered_in_rows: unregisteredShown,
+        built, building, pending, possible, order, dropped_total: dropped.length, unregistered_total: unregisteredTotal, unregistered_in_rows: unregisteredShown,
         rows: built.length + building.length + pending.length + possible.length,
         redactions: redactions + rendered.redactions, text: rendered.text,
       });

package/work/lib/delivery.mjs

@@ -12,8 +12,8 @@
 //      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 { oneLine, ROW_LINE_MAX } from './questions.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']);
 export const DELIVERY_READ_VERBS = Object.freeze(['in_flight']);
@@ -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', {
@@ -545,6 +551,11 @@ export function createDeliveryVerbs(core) {
       if (repoIds.length > MAX_REPOS) refuse(`${repoIds.length} repos are registered for this view; it reads at most ${MAX_REPOS}. Narrow it with a product id.`);
       const { pullsByRepo, repoErrors } = await readPullsByRepo(repoIds, readGitHub);
 
+      // Release 0.2.3: the owner's priority decision orders the rows.
+      const decisionType = await typeNamed('decision');
+      const decisions = await client.listAllEntities({ type: decisionType.name, state: 'active' });
+      const orders = new Map([...new Set(items.map((row) => row.fields.product))].map((productId) => [productId, priorityOrderOf(decisions, productId)]));
+
       const readAt = now();
       const rows = [], delivered = [], notMarked = [];
       for (const item of items) {
@@ -583,21 +594,23 @@ 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'} · 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` : ''}`),
+            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(`${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 })}`),
           ],
+          waits_on: fields.waits_on ?? null,
           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))] },
         });
       }
       // The owner's rule: order by days since last change, latest on top, and
-      // show the days on the row.
-      rows.sort((a, b) => (a.days_since_last_change ?? Number.MAX_SAFE_INTEGER) - (b.days_since_last_change ?? Number.MAX_SAFE_INTEGER) || a.item.localeCompare(b.item));
+      // show the days on the row. Release 0.2.3: the items his priority
+      // decision names come first, in his order.
+      rows.sort(byPriority(orders, (a, b) => (a.days_since_last_change ?? Number.MAX_SAFE_INTEGER) - (b.days_since_last_change ?? Number.MAX_SAFE_INTEGER) || a.item.localeCompare(b.item)));
       delivered.sort((a, b) => String(b.delivered_at ?? '').localeCompare(String(a.delivered_at ?? '')));
       notMarked.sort((a, b) => (a.days ?? 0) - (b.days ?? 0));
       const products = [...new Set(rows.map((row) => row.product))].sort();
       const byProduct = products.map((product) => ({ product, rows: rows.filter((row) => row.product === product) }));
-      const block = byProduct.map((group) => [`${group.product} — in flight (${group.rows.length})`, ...group.rows.flatMap((row, index) => row.lines.map((line, position) => `${position === 0 ? `${index + 1}. ` : '   '}${line}`))].join('\n'));
+      const block = byProduct.map((group) => [`${group.product} — in flight (${group.rows.length})${orders.get(group.product) ? ` · in your order of ${orders.get(group.product).date}, then by the last change` : ''}`, ...group.rows.flatMap((row, index) => row.lines.map((line, position) => `${position === 0 ? `${index + 1}. ` : '   '}${line}`))].join('\n'));
       if (notMarked.length) block.push([`merged, not marked (${notMarked.length})`, ...notMarked.map((row) => listLine(row.title, `${row.pr} · ${row.item} · merged ${row.days} day${row.days === 1 ? '' : 's'} ago`))].join('\n'));
       if (repoErrors.length) block.push([`GitHub did not answer for ${repoErrors.length} repo${repoErrors.length === 1 ? '' : 's'}; movement below is from the graph only`, ...repoErrors.map((row) => oneLine(`   ${row.repo} — ${row.reason}`, ROW_LINE_MAX))].join('\n'));
       if (unregisteredTotal && !only) {
@@ -615,6 +628,7 @@ export function createDeliveryVerbs(core) {
       if (since && delivered.length) block.push([`delivered since ${since} (${delivered.length})`, ...delivered.map((row) => listLine(row.item_title, `${row.verdict}${(row.gate_warnings ?? []).length ? `, gate warning on ${row.gate_warnings.map((warning) => warning.check).join(' ')}` : ''} · ${String(row.delivered_at ?? '').slice(0, 10)} · ${row.prs.join(' ') || 'no pull request on the mark'}`))].join('\n'));
       return {
         verb: 'in_flight', read_at: readAt, product: only, since, rows: rows.length, products: byProduct,
+        priority: Object.fromEntries([...orders].filter(([, order]) => order).map(([productId, order]) => [productId, { decision: order.decision, date: order.date }])),
         merged_not_marked: notMarked, delivered: since ? delivered : delivered.slice(0, 20), unregistered, unregistered_total: unregisteredTotal, repos_read: repoIds, repo_errors: repoErrors,
         text: block.join('\n\n') || 'Nothing is in flight: no active item on a registered product.',
       };