@assuredloop/cli 0.2.2 → 0.2.4

package/README.md

@@ -66,7 +66,9 @@ Search at level 2 needs the library `@huggingface/transformers` 4.3.1 (see
 
   GitHub does not show the marker. The ID is one flat number per file, and
   it is never used again. `al` computes a display number, for example
-  `INV-41 (2.3:4, in Export links)`, which can change when text moves.
+  `INV-41 (2.3:4, in Export links)`, which can change when text moves. So
+  a heading needs no number of its own: write `## The proxy`, not
+  `## 7. The proxy`.
 - **Kinds.** Promise kinds (purpose, scope, rule, limit, definition): a
   change needs a signed requirement that covers it. Design kinds (component,
   interface, data, flow, choice) and `approach` (how one change is built):
@@ -76,7 +78,15 @@ Search at level 2 needs the library `@huggingface/transformers` 4.3.1 (see
 - **A request** is the folder `requests/<name>/`: `origin/` (the owner's words
   and the sign-offs, as snapshots with SHA-256), `request.md` (the dialog, the
   organized requirement R1…, the decisions D1…) and, from path 2, `spec.md`,
-  the change spec, with IDs SP-1, SP-2…
+  the change spec, with IDs SP-1, SP-2… The order of its paragraphs is
+  free. The recommended order is one section per topic. Each section has
+  the promise paragraph first, then the design that keeps it, with its
+  rationale and examples, then its open points. Cross-cutting design and
+  decisions follow. While the request is open, a paragraph of its change
+  spec may be deleted: its ID is retired and never used again, and
+  `al check` gives a hint. In `specs/`, a removal needs `removes:`. Plan,
+  step and migration paragraphs may live in the tracker issue that a task's
+  `ref` names, instead of in the change spec.
 - **Records** in `.assuredloop/records/`, committed to git: one per request
   (its sources, requirement versions, sign-offs, decisions, tasks, the
   bindings of its links and the dispositions of its paragraphs) and one per
@@ -171,7 +181,10 @@ central: {path: ../invoicer}    # in an output repo: the central repo
 ADRs are `specs/adr/NNNN-<slug>.md`, with `Status: proposed`, `accepted` or
 `superseded` on the first line. The heading's marker holds `ADR-<n>` and its
 `decides:`, `source:` and `supersedes:` links. The text of an accepted ADR
-does not change; a new ADR supersedes it.
+does not change; a new ADR supersedes it. You may add links to the marker of
+an accepted ADR when nothing else changes: keep its ID, its kind and each old
+link. `al check` gives a hint for a proposed or accepted ADR with no
+`source:` or no `decides:`; under `--strict`, it is `not ok`.
 
 ## Search
 
@@ -266,7 +279,7 @@ those commits. To move:
 | The tool checks | The skill asks | The owner decides |
 |---|---|---|
 | `al conclude` refuses on its three conditions (see "The close rule") | write the owner's words and the organized requirement, and ask for the sign-off | what is wanted, by signing the organized requirement |
-| IDs: missing, used twice, lost, used again; kinds and links; links that do not resolve; sign-off coverage of promise changes; path and typo claims; dispositions and exact equality; stale bindings; overlapping changes; ADR text changes; result applicability, as hints | choose the path, and state it in a commit message and the PR | whether a changed requirement is signed again |
+| IDs: missing, used twice, lost, used again; kinds and links; links that do not resolve; sign-off coverage of promise changes; path and typo claims; dispositions and exact equality; stale bindings; overlapping changes; ADR text changes; a proposed or accepted ADR with no `source:` or no `decides:`; result applicability; a design paragraph that links to none of its requirement's promise paragraphs in its change spec; a `for:` that names no task, as hints | choose the path, and state it in a commit message and the PR | whether a changed requirement is signed again |
 | `check --strict` exits 1 on a `not ok`, when a project opts in | record each later decision, with its source | decisions whose source is the owner, such as dropping or keeping work |
 
 `al` checks that declarations are well formed and that references resolve.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assuredloop/cli",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "AssuredLoop keeps an AI focused on one change: the al command gathers and checks a change's requirement, spec, decisions, code and tests.",
   "license": "MIT",
   "repository": {

package/skills/assuredloop/SKILL.md

@@ -57,8 +57,13 @@ The export link MUST expire 30 minutes after the email is sent.
 ```
 
 - When you edit a marked paragraph, keep its marker line and the blank lines
-  around it. Keep the ID when you move the paragraph. Never renumber or
-  delete an ID: a lost ID is `not ok`.
+  around it. Keep the ID when you move the paragraph. Never renumber an ID,
+  and never use one again.
+- In an open request's change spec, you may delete a paragraph with its
+  marker. Its ID is retired and never used again. `al check` gives a hint
+  that names the deletion; when it is on purpose, nothing more is needed. In
+  `specs/`, a removal needs `removes:<ID>` in a change spec: a lost ID there
+  is `not ok`.
 - For a new paragraph, write the text with no marker. Then run
   `al spec --add-ids <file> --yes`: it gives each unmarked paragraph the next
   free ID. Then write the kind and the links into each new marker.
@@ -72,6 +77,11 @@ The export link MUST expire 30 minutes after the email is sent.
   `governed-by:<ADR>`; `for:<task>`. A promise, design or approach paragraph
   needs at least one link. In `specs/`, the ID of a change spec paragraph
   names its request: `invoice-exports/SP-12`.
+- An ADR in `specs/adr/` has one marker on its heading: `ADR-<n>`, its kind,
+  and its `decides:`, `source:` and `supersedes:` links. Under `--strict`,
+  `al check` asks each proposed or accepted ADR for `source:` and
+  `decides:`. You may add links to the marker of an accepted ADR. Change
+  nothing else in it: its ID, its kind, its old links and its text stay.
 - `al` writes every hash and every derived field. Do not write them by hand.
 
 ## Path 0: a fix
@@ -131,11 +141,19 @@ The export link MUST expire 30 minutes after the email is sent.
    deliver with the owner's sign-off or after it. A change that touches no
    promise kind needs no sign-off.
 2. Write the design in `requests/<name>/spec.md`, the change spec: the
-   promises this change adds or changes, its design, its plan. Run
+   promises this change adds or changes, its design, its plan. The order
+   of the paragraphs is free. The recommended order is one section per
+   topic. Each section has the promise paragraph first, then the design
+   that keeps it, with its rationale and examples, then its open points.
+   Cross-cutting design and decisions follow. Run
    `al spec --add-ids requests/<name>/spec.md --yes` for the IDs (SP-1,
    SP-2…), then write the kinds and links. A paragraph that relies on a spec
    paragraph says `builds-on:<ID>`. One that replaces it says `changes:<ID>`.
-   One that removes it says `removes:<ID>`. Never copy the old text.
+   One that removes it says `removes:<ID>`. Never copy the old text. A
+   design or approach paragraph that keeps a promise paragraph of this
+   change spec says `builds-on:SP-n`. `al check` gives a hint when it serves
+   a requirement and links to none of that requirement's promise
+   paragraphs here.
 3. Snapshot each later word of the owner that you rely on:
    `al record <name> origin --url <where> --from - --yes`. Record each later
    decision: `al record <name> decision --source <who> --text "<it>" --yes`.
@@ -178,8 +196,9 @@ As path 2, in parts. Each part consolidates the paragraphs it delivers,
 with their dispositions, in its own PR. Tasks are optional: where the
 project uses them, list them in the record as
 `tasks: [{id: T2, ref: "issue #34", delivers: [R3]}]`, and name the task in
-the commit messages of its PRs. Run `al conclude <name> --yes` with the last
-part.
+the commit messages of its PRs. Plan, step and migration paragraphs may live
+in the tracker issue that the task's `ref` names, instead of in the change
+spec. Run `al conclude <name> --yes` with the last part.
 
 ## Path S: a spike
 

package/src/v4/check.js

@@ -4,7 +4,10 @@
 // checks that read records (T10, checks.js). The base is the merge-base of
 // HEAD with main; the head is the working tree. It exits 0; with --strict, 1
 // when it prints a `not ok`. --strict raises every marker lint and an invalid
-// disposition to `not ok`; the hints that need judgment stay hints.
+// disposition to `not ok`; the hints that need judgment stay hints. A lost ID
+// of an open request's change spec is a hint, also under --strict (#230).
+import { parse as parseYaml } from 'yaml';
+import { read, recordPath } from './base.js';
 import { loadConfig, loadSchema } from './config.js';
 import { mergeBase } from './git.js';
 import { diffParagraphs, idLints } from './ids.js';
@@ -34,7 +37,7 @@ export function check({ top, opts }) {
       lints.push(...idLints(head, head));
       continue;
     }
-    lints.push(...idLints(before, head, { everUsed: used.get(scope) ?? [], removes: scope === SPEC ? removes : [] }));
+    lints.push(...idLints(before, head, { everUsed: used.get(scope) ?? [], removes: scope === SPEC ? removes : [] }).map((l) => deleted(top, l)));
     changes.push(...diffParagraphs(before, head).filter((c) => c.changes.length));
   }
 
@@ -43,7 +46,7 @@ export function check({ top, opts }) {
   const shown = lints.filter((l) => !(l.code === 'no-link' && t10.adopted.has(l.id) && !l.file.startsWith('requests/')));
   lints.length = 0;
   lints.push(...shown);
-  const severity = (l) => (opts.strict ? 'not ok' : l.severity);
+  const severity = (l) => (opts.strict && !l.staysHint ? 'not ok' : l.severity);
   const body = notRead(top, config);
   // A root that config sets but that is not read is a not ok, as in al index (#218).
   const rootLine = rootNotOk(top, config);
@@ -53,7 +56,7 @@ export function check({ top, opts }) {
   if (!lints.length) body.push('ok: no marker lint');
   body.push(...t10.findings.map((f) => `${f.severity} ${f.code} ${f.where} ${f.id} ${f.message}`));
   // Under --strict every marker lint is a not ok.
-  const notOk = Boolean(rootLine) || lints.length > 0 || t10.findings.some((f) => f.severity === 'not ok');
+  const notOk = Boolean(rootLine) || lints.some((l) => severity(l) === 'not ok') || t10.findings.some((f) => f.severity === 'not ok');
   // In an output repo: the central IDs that the branch's changed files cite (T12).
   const central = centralLookup(top);
   body.push(...central.body);
@@ -71,6 +74,31 @@ export function check({ top, opts }) {
   };
 }
 
+// A lost ID of an open request's change spec (its file at the base is
+// requests/<name>/spec.md): deleting a paragraph there is ordinary editing,
+// so it is a hint that names the deletion and each disposition or wording
+// decision of the request's record that names the ID (#230, D1-D4).
+const OPEN_SPEC = /^requests\/(?!archive\/)([^/]+)\/spec\.md$/;
+function deleted(top, l) {
+  const name = l.code === 'lost-id' && OPEN_SPEC.exec(l.file)?.[1];
+  if (!name) return l;
+  const source = `${name}/${l.id}`;
+  let rec;
+  try {
+    rec = parseYaml(read(top, recordPath(name)) ?? 'null');
+  } catch {
+    rec = null;
+  }
+  const list = (x) => (Array.isArray(x) ? x : []);
+  const says = { incorporated: (d) => `incorporated as ${d.spec}`, removed: (d) => `removed ${d.spec}`, superseded: (d) => `superseded by ${d.by}` };
+  const facts = [
+    ...list(rec?.dispositions).filter((d) => d?.source === source && says[d.disposition]).map((d) => `its disposition says ${says[d.disposition](d)}`),
+    ...list(rec?.decisions).filter((d) => d?.wording?.source === source).map((d) => `decision ${d.id} names its wording`),
+  ];
+  const message = `${source} is deleted${facts.map((f) => `; ${f}`).join('')}. If that is on purpose, nothing more is needed: the ID is retired and never used again.`;
+  return { ...l, severity: 'hint', staysHint: true, message };
+}
+
 // The Next line names what to do for what printed: a not ok, a hint, both, or
 // neither (#198).
 function nextStep(severities, noId) {

package/src/v4/checks.js

@@ -16,6 +16,7 @@ import {
 } from './state.js';
 import { NEAR, closeness, diffWords, marks, requirementWords, sentencesOf, showHunk } from './words.js';
 import { groupOf, sameBlocks } from './markers.js';
+import { isCentral } from './indexer.js';
 
 const DESIGN = ['component', 'interface', 'data', 'flow', 'choice'];
 const TIER = /^[ \t]*Tier:[ \t]*(0|1d|1|2|3|S)\b[ \t]*(?:—|–|--?)?[ \t]*(.*)$/m;
@@ -256,6 +257,50 @@ export function checks(top, { base, strict = false }) {
     }
   }
 
+  // Design links (design.md 3): a design or approach paragraph of a change
+  // spec that serves a requirement, where promise paragraphs of the same
+  // change spec serve it, and that builds on or changes none of them. In the
+  // central repo, `central:X` is its own X (design.md 12).
+  const self = (ref) => (isCentral(now.config) && ref.startsWith('central:') ? ref.slice('central:'.length) : ref);
+  for (const r of open) {
+    const own = new Set(r.paras.keys());
+    const key = (ref) => qualify(self(ref), r.name, own).key;
+    const promises = new Map();
+    for (const p of r.paras.values()) {
+      if (!promise(p.kind)) continue;
+      for (const k of new Set(p.links.serves.map(key))) {
+        if (!promises.has(k)) promises.set(k, []);
+        promises.get(k).push(p.id);
+      }
+    }
+    if (!promises.size) continue;
+    for (const p of r.paras.values()) {
+      if (groupOf(p.kind, now.kinds) !== 'design') continue;
+      const linked = new Set([...p.links.buildsOn, ...p.links.changes].map(key));
+      for (const k of new Set(p.links.serves.map(key))) {
+        const ids = promises.get(k);
+        if (!ids || ids.some((id) => linked.has(`${r.name}/${id}`))) continue;
+        add('hint', 'design-link', p, `${r.name}/${p.id}`, `serves ${k}, but links to none of its promise paragraphs in this change spec (${ids.join(', ')}): which promise does it keep?`);
+      }
+    }
+  }
+
+  // Task references (design.md 8): where the project uses tasks, a `for:`
+  // that names no task in the record. A bare task is the paragraph's own
+  // request's. The records are read only when an open change spec has a `for:`.
+  const tasksOf = (r) => (Array.isArray(r?.data?.tasks) ? r.data.tasks : []);
+  const fors = open.flatMap((r) => [...r.paras.values()].flatMap((p) => p.links.for.map((ref) => ({ r, p, ref }))));
+  if (fors.length && [...now.requests.values()].some((r) => tasksOf(r).length)) {
+    for (const { r, p, ref } of fors) {
+      const t = self(ref);
+      if (t.includes(':')) continue;
+      const slash = t.indexOf('/');
+      const [name, id] = slash > 0 ? [t.slice(0, slash), t.slice(slash + 1)] : [r.name, t];
+      if (tasksOf(now.requests.get(name)).some((x) => String(x?.id) === id)) continue;
+      add('hint', 'unknown-task', p, `${r.name}/${p.id}`, `for:${ref}: no task ${id} in the record of ${name}`);
+    }
+  }
+
   // Bindings whose target changed since they were bound (design.md 4, 6).
   for (const r of open) {
     for (const b of Array.isArray(r.data?.bindings) ? r.data.bindings : []) {
@@ -308,12 +353,20 @@ export function checks(top, { base, strict = false }) {
     if (pending.length) add('info', 'disposition-pending', r.specFile, r.name, `${pending.length} of ${judged.length} paragraphs with a baseline effect have no disposition for their current version: ${pending.join(', ')}`);
   }
 
-  // ADRs (schema.md 5).
+  // ADRs (schema.md 5). Links may be added to the heading marker of an
+  // accepted ADR: the same kind, each old link kept, the rest unchanged.
+  const linksAdded = (a, h) => a.status === 'accepted' && a.head && h.head && a.rest === h.rest && a.head.kind === h.head.kind
+    && Object.entries(a.head.links).every(([k, refs]) => refs.every((x) => h.head.links[k].includes(x)));
   for (const [id, a] of was?.adrs ?? []) {
     if (!['accepted', 'superseded'].includes(a.status)) continue;
     const h = now.adrs.get(id);
     if (!h) add('not ok', 'adr-changed', a.file, id, `${id} was ${a.status} and its file is gone; an ADR is superseded, never edited or deleted`);
-    else if (h.body !== a.body) add('not ok', 'adr-changed', h.head ?? h.file, id, `the text of ${id} changed after it was accepted; write a new ADR that supersedes it`);
+    else if (h.body !== a.body && !linksAdded(a, h)) add('not ok', 'adr-changed', h.head ?? h.file, id, `the text of ${id} changed after it was accepted; write a new ADR that supersedes it`);
+  }
+  for (const a of now.adrs.values()) {
+    if (!['proposed', 'accepted'].includes(a.status)) continue;
+    const missing = ['source', 'decides'].filter((w) => !a.head?.links[w].length);
+    if (missing.length) add(strict ? 'not ok' : 'hint', 'adr-links', a.head ?? a.file, a.id, `${a.id} has ${missing.map((w) => `no ${w}:`).join(' and ')}; add the links to its marker`);
   }
   for (const a of now.adrs.values()) {
     for (const old of a.head?.links.supersedes ?? []) {

package/src/v4/state.js

@@ -33,6 +33,10 @@ function names(top, rev, dir, folders) {
 // The text after an ADR's Status line: what must not change once it is accepted.
 const adrBody = (text) => text.replace(/\r\n?/g, '\n').replace(/^\s*Status:[^\n]*\n?/, '').replace(/^\n+/, '');
 
+// The same with the line of the heading marker left out: what must not change
+// when links are added to that marker (schema.md 5).
+const adrRest = (text, head) => adrBody(text.replace(/\r\n?/g, '\n').split('\n').map((l, i) => (i === head.line - 1 ? '<!-- -->' : l)).join('\n'));
+
 // The settings of a commit: its own config.yaml and schema.yaml, with the
 // defaults of config.js when a file is absent or not a mapping.
 export function settingsAt(top, rev) {
@@ -143,7 +147,8 @@ export function loadState(top, rev = null) {
     const paragraphs = parseMarkdown(text, file, { kinds }).paragraphs;
     const id = `ADR-${Number(m[1])}`;
     const status = /^\s*Status:\s*([a-z]+)/i.exec(text)?.[1].toLowerCase() ?? null;
-    adrs.set(id, { id, file, status, body: adrBody(text), paragraphs, head: paragraphs.find((p) => p.id === id) ?? null });
+    const head = paragraphs.find((p) => p.id === id) ?? null;
+    adrs.set(id, { id, file, status, body: adrBody(text), rest: head && adrRest(text, head), paragraphs, head });
   }
   return { top, rev, config, kinds, root, get, scopes, lints, spec, requests, adrs };
 }

package/src/v4/views.js

@@ -9,6 +9,7 @@ import { crossRepo, findCites } from './repos.js';
 import { diffParagraphs } from './ids.js';
 import { loadResults } from './results.js';
 import { latestVersion, loadState, named, qualify, requestOf, resolve, signedBy } from './state.js';
+import { isCentral } from './indexer.js';
 
 export const line = (label, text) => `${label.length < 10 ? label.padEnd(10) : `${label} `}${text}`;
 const list = (x) => (Array.isArray(x) ? x : []);
@@ -339,6 +340,25 @@ function checkLines(state, id, local) {
   return out;
 }
 
+// The paragraphs of specs/ and of the open change specs that build on,
+// explain or illustrate the paragraph named `who`. In the central repo,
+// `central:X` is its own X (design.md 12).
+function linkedTo(state, who) {
+  const self = (ref) => (isCentral(state.config) && ref.startsWith('central:') ? ref.slice('central:'.length) : ref);
+  const holders = [
+    ...[...state.spec.values()].map((p) => ({ p, r: null })),
+    ...[...state.requests.values()].filter((r) => r.open).flatMap((r) => [...r.paras.values()].map((p) => ({ p, r }))),
+  ];
+  const out = [];
+  for (const { p, r } of holders) {
+    const own = r ? new Set(r.paras.keys()) : new Set();
+    for (const [key, verb] of [['buildsOn', 'builds on it'], ['explains', 'explains it'], ['illustrates', 'illustrates it']]) {
+      if (p.links[key].some((ref) => qualify(self(ref), r?.name ?? null, own).key === who)) out.push(`${named(r?.name ?? null, p.id)} ${verb}`);
+    }
+  }
+  return out.length ? out.join(' · ') : 'no paragraph builds on, explains or illustrates it';
+}
+
 function idView(state, id) {
   const t = qualify(id, null);
   const r = t.req ? state.requests.get(t.req) : null;
@@ -356,6 +376,7 @@ function idView(state, id) {
     if (word === 'serves' || !refs.length) continue;
     body.push(line('Links', `${word} ${refs.join(', ')}`));
   }
+  body.push(line('Linked', linkedTo(state, who)));
   if (!t.req) {
     const govern = [...state.adrs.values()].filter((a) => (a.head?.links.decides ?? []).includes(p.id) || p.links.governedBy.includes(a.id));
     body.push(line('Governed', govern.length ? `by ${govern.map((a) => `${a.id} (${a.status ?? 'no status'}${a.status === 'superseded' ? ': history' : ''})`).join(' · ')}` : 'by no ADR'));
@@ -398,6 +419,9 @@ function diffView(top, range, review) {
   const now = loadState(top, headSha);
   const was = loadState(top, base);
   const findings = review ? checks(top, { base }).findings : [];
+  // The ADRs with no source link, which the view marks where it names them (schema.md 5).
+  const unsourced = new Set([...now.adrs.values()].filter((a) => !a.head?.links.source.length).map((a) => a.id));
+  const marks = (message) => [...new Set(message.match(/\bADR-\d+\b/g) ?? [])].filter((id) => unsourced.has(id)).map((id) => `; ${id} has no source:`).join('');
   const body = [];
   for (const scope of new Set([...now.scopes.keys(), ...was.scopes.keys()])) {
     const request = requestOf(scope);
@@ -430,10 +454,10 @@ function diffView(top, range, review) {
       }
       if (!request) {
         for (const a of now.adrs.values()) {
-          if ((a.head?.links.decides ?? []).includes(c.id) || p.links.governedBy.includes(a.id)) body.push(`  governed by ${a.id} (${a.status ?? 'no status'})`);
+          if ((a.head?.links.decides ?? []).includes(c.id) || p.links.governedBy.includes(a.id)) body.push(`  governed by ${a.id} (${a.status ?? 'no status'}${unsourced.has(a.id) ? '; no source:' : ''})`);
         }
       }
-      for (const f of findings.filter((x) => x.id === who && x.severity !== 'info')) body.push(`  ${findingLine(f)}`);
+      for (const f of findings.filter((x) => x.id === who && x.severity !== 'info')) body.push(`  ${findingLine(f)}${marks(f.message)}`);
     }
   }
   if (!body.length) body.push('no paragraph changed in the range');