@assuredloop/cli 0.2.3 → 0.2.4

package/README.md

@@ -181,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
 
@@ -276,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; 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 |
+| 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.3",
+  "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

@@ -77,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

package/src/v4/checks.js

@@ -353,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

@@ -419,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);
@@ -451,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');