@assuredloop/cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wenqing Gu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,261 @@
-# Temporary Holding Version
+# AssuredLoop
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+AssuredLoop keeps an AI focused on one change. It holds together:
+- the owner's words;
+- the organized requirement the owner signs off;
+- the current consolidated spec, the baseline: Markdown sections in `specs/`,
+  each headed by an ID such as `## [INV-3] Dates`; and the change to it;
+- the decisions;
+- the code and tests that came with it.
+
+A change to a promise keeps these records in a request, the folder
+`requests/<name>/`.
+
+Its command, `al`, gathers and checks these records and says what to do next.
+It gives hints; it blocks nothing but its own `consolidate` and `conclude`.
+
+## Install
+
+It needs Node 24 or newer and git 2.31 or newer, and nothing else. Install
+the npm package `@assuredloop/cli`, which puts `al` on your PATH:
+
+    npm install --global @assuredloop/cli
+
+To pin a version, name it: `npm install --global @assuredloop/cli@0.1.0`.
+`al --version` prints the version and the folder it runs from.
+
+The package carries the skill. Its folder, `<dir>` below, is
+`$(npm root -g)/@assuredloop/cli`, so the skill is at
+`$(npm root -g)/@assuredloop/cli/skills/assuredloop/SKILL.md`. Then add one
+line to the project's AGENTS.md:
+
+```
+AssuredLoop keeps this project's requests and spec: before work that changes a promise, read <dir>/skills/assuredloop/SKILL.md and run `al context`.
+```
+
+In a shared repo whose contributors install `al` in different places, copy
+`skills/assuredloop/SKILL.md` from `<dir>` at the pinned version into the
+project, for example as `.claude/skills/assuredloop/SKILL.md`. Name that path
+in the AGENTS.md line, say in the commit which version it came from, and copy
+it again when you re-pin.
+
+To work on `al` itself, use a clone in place of the npm package:
+
+    git clone https://github.com/guwenqing/assuredloop <dir>
+    npm install --global <dir>
+
+The global `al` links to `<dir>`, so it follows whatever `<dir>` checks out.
+To pin a commit, check out its SHA in a clone of its own (`git -C <dir>
+checkout <sha>`) and run `node <dir>/bin/al.js` in place of `al`; it needs no
+install, having no dependencies. From a clone, `al --version` also prints the
+commit.
+
+To run `al check --strict` in CI, check the project out with its whole history
+(`fetch-depth: 0`), install the pinned version
+(`npm install --global @assuredloop/cli@0.1.0`), and run `al check --strict`. A
+checkout with no main ref says
+`no main to compare with, so no commits were checked`: it compares none of the
+branch's commits with main, though its other checks, such as duplicate IDs in
+the working tree, still run and can fail. A shallow clone that has
+`origin/main` does not print that line, but reads no history before its
+shallow boundary.
+
+## The commands
+
+- `al new <name> --from <file|-> [--tier <1|2|3|S>] [--title <text>]`: start
+  a request from the owner's words (`-` reads standard input); `--title` sets
+  its heading, which is the name otherwise.
+- `al record <name> origin|signoff|decision|part|section`: write one part of
+  a record. To change a section the request already holds, write the decision
+  first, then `al record <name> section <ID> --decision Dn` adds a new version.
+- `al context [<name> | <ID> | --diff <range>]`: where the project, a request
+  or a section stands; `--audit` for the whole trace, `--at <commit>` for any
+  past state.
+- `al spec [--list]`: the design as it stands. `--add-ids <file> --prefix <P>`
+  gives IDs to the headings of a baseline file that have none.
+- `al check [--strict] [--all]`: the hints for this branch, five at most;
+  `--all` shows every one.
+- `al consolidate <name>`: write a request's pending sections into the baseline.
+- `al conclude <name>`: write the Outcome (what became of each requirement) and
+  archive the request.
+
+Every command that changes files, except `new`, shows what it would write, and
+writes only with `--yes`. The skill, `skills/assuredloop/SKILL.md`, says how to
+choose a tier (0 to 3, or S for a spike) and when to use which command. The
+promises are in `specs/`.
+
+A request that follows an earlier one says so on its Status line, as in
+`Status: open · Follows: <name>`. Every word after `Follows:` is read as a
+request name, so write names only.
+
+## Settings
+
+A project may add a file `.assuredloop` at its root, one `key: value` per line,
+each path inside the repo:
+- `root: <folder>`: the baseline's folder, `specs` when there is no such line;
+- `tests: <path>`: a test file or folder beyond the usual names;
+- `results: <path>`: a test result file or folder for `al check` to read;
+- `adrs: <folder>`: a folder of decision records; `docs/adr` is always read too.
+
+`tests:`, `results:` and `adrs:` may each be given on several lines.
+
+## Common situations
+
+Each example gives the steps, and what `al check` says on the PR. The `Tier:`
+line goes in a commit message and in the PR.
+
+### Adopting when the spec lives elsewhere
+
+Say the design is `docs/prd.md`, and the root is to be `docs/prd/`. Use two
+PRs.
+
+PR 1 moves the file, fixes each relative link the move breaks (`(adr/)`
+becomes `(../adr/)`), and sets the root. It comes before the project adopts
+AssuredLoop, so it carries no Tier line:
+
+    mkdir docs/prd && git mv docs/prd.md docs/prd/prd.md
+    printf 'root: docs/prd\n' > .assuredloop
+
+This is the step before the baseline exists. `al check`, if run on it, exits 0
+(`--strict` too) with two notes:
+
+    note: <sha> changes docs/prd/prd.md with no request linked (fine for tier 0; say why); git show <sha>
+    note: no Tier line in origin/main..HEAD; add "Tier: <n> — <claim>" to a commit message, e.g. with git commit --amend
+
+A tier-0 claim here would get
+`not ok: the claim is tier 0, but origin/main..HEAD edits the baseline`: the
+fork had no baseline, so the whole file reads as new.
+
+PR 2, after PR 1 merges, adopts: the AGENTS.md line from Install, and IDs. It
+claims `Tier: 0 — adds section IDs; no promise changes`:
+
+    al spec --add-ids docs/prd/prd.md --prefix PRD --yes
+
+`al check --strict` passes, with one note: the commit changes
+`docs/prd/prd.md` with no request linked (fine for tier 0; say why). In one PR,
+the IDs read as edits too: `edits the baseline: [PRD-1], [PRD-2], [PRD-3]`.
+
+### Adding IDs to a spec file in the root
+
+    al spec --add-ids specs/api.md --prefix API --yes
+
+It numbers the headings that have no ID, with the next free numbers. Claim
+tier 0. `al check --strict` passes, with the same note.
+
+### Moving or splitting sections in the root
+
+Move each section whole, heading and text unchanged, to another file in the
+root. Claim tier 0. `al check --strict` passes, and its Evidence line says
+`moves [R-3] specs/rules.md → specs/dates.md, text unchanged`. A new file holds
+only the moved sections: a title or an intro line in it is new text, and gets
+a `not ok`.
+
+### A move that forces a text change
+
+Moving `[R-2]` from `specs/` into `specs/files/` breaks its link
+`(limits.md)`. The fix, `(../limits.md)`, changes the section's text. So does a
+heading reworded on the way. `al` follows neither. Claimed as tier 0:
+
+    not ok: the claim is tier 0, but origin/main..HEAD edits the baseline: [R-2]; al context --diff origin/main..HEAD
+
+Either keep the change out of the move: move the section where its text still
+works (a file in the same folder keeps its links), and reword in a tier-1 PR of
+its own. Or claim tier 1 for the whole PR, as in the skill's quick path, with
+`Amends: [R-2]` and the owner's sign-off. `al check --strict` then passes.
+
+### Renaming a section's ID
+
+Code, tests and requests cite a section by its ID. Rename `[R-2]` to
+`[SIZE-1]`, claim tier 0, and `al check` says
+`not ok: the claim is tier 0, but origin/main..HEAD edits the baseline: [R-2], [SIZE-1]`.
+`al context R-2` then says `[R-2] not in the baseline`, and still lists the
+code and tests that name it.
+
+Keep the ID: it names the promise, not the file it sits in. If it must change,
+claim tier 1, with the owner's sign-off and `Amends: [R-2], [SIZE-1]` (name
+both, or a note says the new one is not named). In the same PR, change the
+citations in code and tests; `al context R-2` lists them. `[R-2]` is never used
+again.
+
+Do not replace `[R-2]` across the whole repo:
+- Archived requests and the other append-only records ([REC-12]) stay as they
+  are, and keep `[R-2]` as history. Editing one gives
+  `not ok: <sha> requests/archive/<name>/request.md: changes a request archived on main ([REC-12])`.
+- An open request that holds `[R-2]` then reads it as
+  `not found; candidates SIZE-1`, shown as that request's own information. It
+  is re-aligned in that request's own work. A replace there edits its signed
+  `origin/` snapshot, which gives a `not ok`.
+
+### Starting a new repo from an already-agreed spec
+
+Adopt the agreed text as it is, with no request: the owner signs a request's
+organized requirement, never the spec text ([REC-5]). Say in the commit
+message where and when the owner agreed it. Use two steps, as in the first
+example.
+
+PR 1, before adoption, imports the agreed text under `specs/` (with
+`.assuredloop` if the root is elsewhere). It has no AGENTS.md line and no Tier
+line: AssuredLoop is not adopted yet, and its rules start at adoption.
+`al check`, if run on it, exits 0 with the two notes PR 1 above gets. In an
+empty repo, PR 1 can instead be the first commit, straight to main.
+
+PR 2 adopts: the AGENTS.md line from Install, and the IDs. It claims
+`Tier: 0 — adds section IDs and the AGENTS line; no promise changes`:
+
+    al spec --add-ids specs/<file>.md --prefix <P> --yes
+
+`al check --strict` passes, with one note: the commit changes
+`specs/<file>.md` with no request linked (fine for tier 0; say why). Requests,
+with the owner's sign-off, start at the first promise change after that.
+
+`specs/` holds promises, and each change to one needs the owner's sign-off, so
+a build or UI design belongs in `docs/`, or as ADRs in `docs/adr/`, which `al`
+reads, unless a passage is a promise the owner wants guarded.
+
+## What is enforced, and by whom
+
+The way of working (tests first, review, the PR flow) belongs to the bots that
+use AssuredLoop, and is not in this table.
+
+| The tool checks | The skill asks | The owner decides |
+|---|---|---|
+| `consolidate` and `conclude` refuse while the requirement is not signed, or a section is not ready | write the owner's words and the organized requirement, and ask for the sign-off | what is wanted, by signing the organized requirement |
+| section states: was and now against the baseline, by exact text | choose the tier, and state it in a commit message (where `al check` reads it) and the PR | whether a changed requirement is signed again |
+| append-only records, snapshot hashes, duplicate IDs, broken links, as hints | read the hints, and fix each `not ok` or say why it stands | decisions whose source is the owner, such as dropping or keeping work |
+| `check --strict` exits 1 on a `not ok` this branch owns, when a project opts in | record each later decision, with its source | |
+
+Everything else the tool shows is a hint: an observation, not a guarantee.
+Nothing is installed in git hooks.
+
+## Beyond code
+
+The same records work on a repo of documents alone. The documents are the
+deliverable, and `specs/` holds promises about them. "Tests" are named checks
+(a deterministic check, a checklist or a review), listed with `tests:` in
+`.assuredloop`; their results are the files they write, listed with
+`results:`, in TAP or JUnit form. A result counts as evidence for a change
+only when a `revision: <sha>` line names the commit being checked:
+`# revision: <sha>` in TAP, `<!-- revision: <sha> -->` in JUnit XML. A result
+with no such line, or at an older commit, is shown but is not evidence.
+`test/non-code.test.js` walks one through.
+
+## This repository
+
+- `requests/`: the requests, and `requests/archive/` for the concluded ones;
+- `docs/adr/`: the decision records;
+- `specs/`: the current spec.
+
+The previous version is on the `legacy` branch. Its build is tagged
+`assuredloop-base-0.1.0-canonical-build`, and its issues and pull requests stay
+in this repository.
+
+## Releasing
+
+1. Bump `version` in `package.json` in a PR, and merge it.
+2. Publish a GitHub Release tagged `v<version>` on that commit. Mark it a
+   pre-release to publish under npm's `next` tag.
+
+`.github/workflows/publish.yml` does the rest: it runs the tests and
+`al check --strict`, checks that the tag matches `package.json`, and publishes
+@assuredloop/cli to npm. It stores no npm token: npm trusts the workflow by
+name, and adds a provenance statement saying which commit built the package.

package/bin/al.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// al: AssuredLoop's command line. Every output names what it read and ends
+// with a Next line and a Not known line ([VW-9]).
+import { parseArgs } from 'node:util';
+import { readFileSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { Fail, git, mainRef, remember, resolveCommit, topLevel } from '../src/git.js';
+import { newRequest, recordOrigin, context, line } from '../src/commands.js';
+import { spec } from '../src/spec.js';
+import { consolidate } from '../src/consolidate.js';
+import { conclude } from '../src/conclude.js';
+import { check } from '../src/check.js';
+
+const COMMANDS = {
+  new: { run: newRequest, options: { from: { type: 'string' }, title: { type: 'string' }, tier: { type: 'string' } } },
+  record: {
+    run: recordOrigin,
+    options: {
+      from: { type: 'string' }, url: { type: 'string' }, verify: { type: 'string' },
+      fetched: { type: 'string' }, updated: { type: 'string' }, yes: { type: 'boolean' },
+      source: { type: 'string' }, words: { type: 'string' },
+      'builds-on': { type: 'string' }, accept: { type: 'boolean' }, decision: { type: 'string' }, text: { type: 'string' },
+    },
+  },
+  context: { run: context, options: { at: { type: 'string' }, diff: { type: 'string' }, for: { type: 'string' }, all: { type: 'boolean' }, audit: { type: 'boolean' } } },
+  spec: {
+    run: spec,
+    options: { at: { type: 'string' }, list: { type: 'boolean' }, 'add-ids': { type: 'string' }, prefix: { type: 'string' }, yes: { type: 'boolean' } },
+  },
+  consolidate: { run: consolidate, options: { section: { type: 'string' }, revert: { type: 'string' }, yes: { type: 'boolean' } } },
+  conclude: { run: conclude, options: { dropped: { type: 'string' }, yes: { type: 'boolean' } } },
+  check: { run: check, options: { at: { type: 'string' }, strict: { type: 'boolean' }, all: { type: 'boolean' } } },
+};
+const ONE_LINE = ['words', 'source', 'text', 'url', 'updated', 'title'];
+const USAGE = 'al new | record | context | spec | consolidate | conclude | check | --version';
+
+// `al --version`: the package version, and the commit of the install folder
+// when that folder is the top of a git checkout, so a run says what it runs.
+function version() {
+  const dir = realpathSync(fileURLToPath(new URL('..', import.meta.url)));
+  const pkg = JSON.parse(readFileSync(`${dir}/package.json`, 'utf8'));
+  // The caller's GIT_DIR and the like point at the caller's repo, not this folder.
+  const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !k.startsWith('GIT_')));
+  const top = git(dir, ['rev-parse', '--show-toplevel'], { allowFail: true, env });
+  const sha = top && realpathSync(top) === dir ? git(dir, ['rev-parse', 'HEAD'], { allowFail: true, env }) : null;
+  const where = sha ? `${sha.slice(0, 7)} · ${dir}` : `not a git checkout: ${dir}`;
+  print([`al ${pkg.version ?? 'unreleased'} · ${where}`], 'the install folder', { label: 'no project read' }, 'al context',
+    sha ? ['whether the install folder has uncommitted changes'] : ['which commit it was installed from']);
+  return 0;
+}
+
+function main(argv) {
+  const cwd = process.cwd();
+  let top = null;
+  let read = 'working tree';
+  remember();
+  try {
+    if (argv.length === 1 && ['--version', '-v'].includes(argv[0])) return version();
+    top = topLevel(cwd);
+    const [name, ...rest] = argv;
+    const command = COMMANDS[name];
+    if (!command) throw new Fail(name ? `unknown command: ${name}` : 'no command given', USAGE);
+    let parsed;
+    try {
+      parsed = parseArgs({ args: rest, options: command.options, allowPositionals: true, strict: true });
+    } catch (e) {
+      throw new Fail(e.message, USAGE);
+    }
+    // A one-line value is written into a record line; a line break in it would forge another line.
+    const broken = ONE_LINE.find((k) => /[\r\n]/.test(parsed.values[k] ?? ''));
+    if (broken) throw new Fail(`--${broken} holds a line break; it takes one line`, `pass --${broken} on one line`);
+    // [VW-9]: under --at, every output names the commit, error exits included.
+    // [VW-8]: from here on --at is the commit's full id, however it was spelled.
+    if (parsed.values.at !== undefined) {
+      read = `--at ${parsed.values.at} (not found)`; // stays if the rev does not resolve
+      parsed.values.at = resolveCommit(top, parsed.values.at);
+      read = `commit ${parsed.values.at.slice(0, 7)}`;
+    }
+    const out = command.run({ top, cwd, args: parsed.positionals, opts: parsed.values });
+    if (out.tree) read = out.tree.label;
+    print(out.body, read, mainRef(top), out.next, out.notKnown);
+    return out.exit ?? (out.refused ? 1 : 0); // consolidate and conclude refusing, and check --strict ([HNT-3])
+  } catch (e) {
+    if (!(e instanceof Fail)) throw e;
+    let main = { label: 'no main read (not in a git repository)' };
+    if (top) try { main = mainRef(top); } catch { /* keep the fallback */ }
+    if (!top) read = 'nothing';
+    print([`al: ${e.message}`], read, main, e.next ?? USAGE, ['nothing was written']);
+    return 2;
+  }
+}
+
+// Every line of output is one line: text from files, file names and commit
+// subjects are shown with each control character (C0, DEL, C1) but a tab as
+// \xNN, so a line break in a file name or an escape code in a subject reaches
+// no reader as such. A CR that ends a line (a CRLF file) stays: it hides nothing.
+const shown = (l) => String(l).replace(/[\x00-\x08\x0a-\x0c\x0e-\x1f\x7f-\x9f]|\r(?!$)/g, (c) => `\\x${c.charCodeAt(0).toString(16).padStart(2, '0')}`);
+
+function print(body, read, main, next, notKnown) {
+  const unknown = main.unknown ? [...notKnown, main.unknown] : notKnown;
+  const text = [...body, line('Read', `${read} · ${main.label}`), line('Next', next), line('Not known', unknown.join('; ') || 'nothing beyond what is shown')]
+    .map(shown).join('\n');
+  process.stdout.write(text + '\n');
+}
+
+try {
+  process.exitCode = main(process.argv.slice(2));
+} catch (e) {
+  process.stderr.write(`al: internal error: ${e.stack || e}\n`);
+  process.exitCode = 2;
+}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@assuredloop/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "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": {
+    "type": "git",
+    "url": "git+https://github.com/guwenqing/assuredloop.git"
+  },
+  "bugs": {
+    "url": "https://github.com/guwenqing/assuredloop/issues"
+  },
+  "homepage": "https://github.com/guwenqing/assuredloop#readme",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "al": "bin/al.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/assuredloop/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: assuredloop
+description: >-
+  Writing the records of a change with AssuredLoop's `al`: the owner's words,
+  the signed organized requirement, the baseline spec, the change spec and the
+  decisions. Use in a project whose AGENTS.md names AssuredLoop, before work
+  that changes a promise, and whenever you need to know where a request stands.
+---
+## Quick path (tiers 0 and 1)
+1. Run `al context`. Its hints (observations, not verdicts) and Next line say what to do.
+2. No promise in the baseline (`specs/`) changes: tier 0. Write no record. A commit
+   message (`al check` reads it there) and the PR say `Tier: 0 — <what it restores>`.
+3. A small change to a promise: tier 1, several small ones in one request for
+   one sign-off. `al new <name> --tier 1 --from -`, the owner's words on stdin.
+4. In its `request.md`, add `## Organized requirement` in plain words the owner
+   reads, no jargon: a line each, `R1: <MUST/SHOULD/MAY …>. Amends: [ID]` (or
+   `### R1` sub-sections); `Assumed:` for anything you added, `Out:` if needed.
+5. Show it to the owner. The owner signs, not you: only on their OK, run
+   `al record <name> signoff --source <where> --words "<their words>" --yes`.
+6. Edit the baseline section, then `al conclude <name>`. The commit message and
+   the PR say `Tier: 1 — <claim>`. Moves and IDs: al's README, "Common situations".
+7. Before review, run `al check`. Fix or explain each `not ok`; read each `note`.
+`al new` writes at once. Other commands that write show first; add `--yes` to write.
+
+## Larger work: tier 2 needs a design, 3 lands in parts, S is a spike
+- `al new <name> --tier <2|3|S> --from -`, then step 4's `## Organized requirement`, with
+  `### R1` sub-sections, `Out:` and `Assumed:` (one-line `R1:` is tier 1 only). S writes
+  `## Organized question` instead, then `findings.md` opening with its Answer, and no spec
+  change. The owner signs (step 5). Draft freely; deliver with the sign-off or after it.
+- `change.md` holds the design, then `## Spec changes`: a block per section. End each
+  heading with `for R<n>`, so the Outcome links R<n> to it (an `Amends: [ID]` under R<n>
+  also does). `al record <name> section <ID>` copies a section into "was" and "now"; edit
+  "now". `--builds-on <request>` starts from another request's version. For a new section,
+  write `### [PAY-1]@1 add in specs/pay.md` (or `add after [ID]`), then `Now:` and the
+  section, indented. Its ID is one more than the highest ever used for that prefix.
+- Each later decision (D1, D2…): `al record <name> decision --source <who> --text <it>`.
+  Snapshot every link or chat you rely on: `al record <name> origin --url <u> --from -`,
+  with `--updated <time>` when the source shows when it last changed.
+- `al consolidate <name> --section <ID>` writes a part's "now" into the baseline.
+  `al conclude <name>` needs each section consolidated; carried (a later block built on
+  it is in the baseline; if dropped, keep it, never revert); `Dropped <date> (Dn)`, with
+  applied text also reverted by consolidate's `--revert <ID>`; or `Kept <date> (Dn)`, for
+  a consolidated or carried section with `for R<n>` or Dn from the owner.
+
+## Reading where things stand
+- `al context <name>`: a request in twelve lines. `al context <ID>`: one section, with
+  its links. `al spec`: the design now. `--audit` gives the whole trace; `--at <commit>`,
+  any past state. `al context --diff main...HEAD --for review`: what a reviewer reads.

package/src/adrs.js

@@ -0,0 +1,110 @@
+// Decision records ([LNK-4]): `NNNN-<decision>.md` in docs/adr and each
+// `adrs:` folder of .assuredloop, in the kit's format. The tool shows the
+// ADRs governing a section, lists those a request added or superseded, and
+// flags what breaks the format's rules; it never writes one.
+import { git } from './git.js';
+import { openTree } from './tree.js';
+import { configured, pastLines } from './spec.js';
+import { cites, idsOn, paths, requestOf } from './links.js';
+
+// A file name is bounded (255 bytes), so the name is too: unbounded, a long token takes quadratic time.
+const numbers = (s) => [...new Set([...s.matchAll(/\bADR[ \t]+(\d{4})\b|(?<![\w-])(\d{4})-[\w.-]{0,250}\.md\b/g)].map((m) => m[1] ?? m[2]))];
+const numberOf = (p) => p.match(/(?:^|\/)(\d{4})-[^/]*\.md$/)?.[1];
+// `Status:` anywhere in the header, the lines before the first `##` heading,
+// so `Date: … Status: superseded by …` on one line is read. The status ends
+// with its sentence, so a field after it on the line is not part of it.
+const STATUS = /(?<![\w-])Status:[ \t]*(.*?)(?:\.(?=[ \t]|$)|$)/m;
+const statusIn = (text) => { const end = text.search(/^##[ \t]/m); return (end < 0 ? text : text.slice(0, end)).match(STATUS); };
+
+// A `past` tree's `adrs:` lines are read leniently ([VW-8]).
+export const adrFolders = (top, tree, at, past = false) => [...new Set(['docs/adr', ...(past ? pastLines : configured)(top, tree, at, 'adrs')])];
+
+// Every ADR in `tree`: its path, number, text, status word, and its links.
+export function adrsIn(top, tree, at, past = false) {
+  return adrFolders(top, tree, at, past).flatMap((d) => (tree.list(d) ?? []).filter((f) => numberOf(f)).map((f) => {
+    const text = tree.read(`${d}/${f}`)?.toString('utf8') ?? '';
+    const field = (k) => text.match(new RegExp(`^${k}:[ \\t]*(.*)$`, 'm'))?.[1] ?? '';
+    const m = statusIn(text);
+    const status = m?.[1] ?? '';
+    return { path: `${d}/${f}`, n: numberOf(f), text, status: status.match(/^[a-z]+/i)?.[0].toLowerCase() ?? '', hasStatus: Boolean(m),
+      by: /^superseded/i.test(status) ? numbers(status) : [], supersedes: numbers(field('Supersedes')), hasSupersedes: /^Supersedes:/m.test(text),
+      request: field('Request').trim(), governs: idsOn(field('Governs')) };
+  }));
+}
+
+const shown = (a) => `${a.n} ${a.status === 'superseded' ? `superseded by ${a.by.join(', ')}` : a.status || 'no status'}`;
+
+// The ADRs that govern section `id` (a Governs: line) or name it, current first.
+export function governing(top, tree, id, at) {
+  return adrsIn(top, tree, at).filter((a) => a.governs.includes(id) || cites(a.text, id))
+    .sort((x, y) => (y.status === 'accepted') - (x.status === 'accepted') || x.n.localeCompare(y.n))
+    .map((a) => `${shown(a)} (${a.governs.includes(id) ? 'governs' : 'names'} [${id}])`);
+}
+
+// The ADRs request `name` added (its Request: line, or the commit that added
+// the file maps to it, [LNK-2]), and the ADRs those supersede.
+export function adrsOf(top, tree, at, name, requests) {
+  const all = adrsIn(top, tree, at);
+  const addedIn = new Map();
+  let sha = null;
+  // -z keeps each path literal: `>sha`, then its paths, each ended by NUL.
+  for (const l of paths(git(top, ['log', '--diff-filter=A', '--name-only', '-z', '--format=>%H', at ?? 'HEAD', '--', ...adrFolders(top, tree, at)], { allowFail: true }))) {
+    const p = l.replace(/^\n/, '');
+    if (p.startsWith('>')) sha = p.slice(1);
+    else if (!addedIn.has(p)) addedIn.set(p, sha);
+  }
+  // A commit that touched several request folders maps to none of them here.
+  const seen = new Map();
+  const mapped = (sha) => requestOf(top, sha, requests, seen);
+  const added = all.filter((a) => a.request === name || (addedIn.has(a.path) && mapped(addedIn.get(a.path)).how !== 'folder, ambiguous' && mapped(addedIn.get(a.path)).names.includes(name)));
+  return { added, superseded: all.filter((o) => added.some((a) => a.supersedes.includes(o.n) || o.by.includes(a.n))) };
+}
+
+// The ADR hints of branch `b`: not ok for an accepted ADR edited beyond its
+// status (base against the final state), a broken or one-way supersede link,
+// a reused number; a note for a superseded ADR cited as current.
+export function adrHints(top, b) {
+  const out = [];
+  const add = (kind, owners, text, command) => out.push({ kind, rank: kind === 'note' ? 14 : 5, owners, text, command });
+  const all = adrsIn(top, b.tree, b.at);
+  const byN = new Map();
+  for (const a of all) byN.set(a.n, [...(byN.get(a.n) ?? []), a]);
+  // A number's file names over history. A rename that keeps the number
+  // replaces its name; a renumbering leaves the old number used.
+  const names = new Map();
+  const log = paths(git(top, ['log', '--reverse', '-M', '--diff-filter=AR', '--name-status', '-z', '--format=', b.at ?? 'HEAD', '--', ...adrFolders(top, b.tree, b.at)], { allowFail: true }));
+  for (let i = 0; i < log.length; i += log[i][0] === 'R' ? 3 : 2) {
+    const [was, p] = log[i][0] === 'R' ? [log[i + 1], log[i + 2]] : [null, log[i + 1]];
+    if (was && numberOf(was) === numberOf(p)) names.get(numberOf(was))?.delete(was);
+    if (numberOf(p)) names.set(numberOf(p), (names.get(numberOf(p)) ?? new Set()).add(p));
+  }
+  for (const a of all) names.set(a.n, (names.get(a.n) ?? new Set()).add(a.path));
+  for (const [n, ps] of names) if (ps.size > 1) add('not ok', [], `ADR number ${n} is reused: ${[...ps].join(' and ')}; a number is never reused`, 'git mv the newer one to the next free number, then al check');
+  for (const a of all) {
+    // A field the record already has is changed, never added again.
+    const links = [...a.supersedes.map((n) => [n, 'supersedes', (t) => t.by.includes(a.n),
+      (t) => (t.hasStatus ? `set its Status: to "superseded by ADR ${a.n}" in` : `add "Status: superseded by ADR ${a.n}" to`)]),
+    ...a.by.map((n) => [n, 'is superseded by', (t) => t.supersedes.includes(a.n),
+      (t) => (t.hasSupersedes ? `add ADR ${a.n} to the Supersedes: line of` : `add "Supersedes: ADR ${a.n}" to`)])];
+    for (const [n, says, back, fix] of links) {
+      const t = byN.get(n);
+      if (!t) add('not ok', [], `a broken supersede link: ${a.path} ${says} ADR ${n}, which does not exist`, `correct the link in ${a.path}, then al check`);
+      else if (!t.some(back)) add('not ok', [], `a one-way supersede link: ${a.path} ${says} ADR ${n}, but ${t[0].path} does not say so back`, `${fix(t[0])} ${t[0].path}, then al check`);
+    }
+  }
+  if (b.base) {
+    const strip = (t) => { const m = statusIn(t); return m ? t.slice(0, m.index) + t.slice(m.index + m[0].length) : t; };
+    for (const a of adrsIn(top, openTree(top, b.base), b.base, true).filter((x) => x.status === 'accepted')) {
+      const now = b.tree.read(a.path)?.toString('utf8');
+      if (now === undefined || strip(now) !== strip(a.text)) {
+        add('not ok', [], `${a.path} was accepted at ${b.base.slice(0, 7)} and is ${now === undefined ? 'deleted' : 'edited beyond its Status line'} on this branch; a change is a new ADR that supersedes it`, `git diff ${b.base.slice(0, 7)} -- ${a.path}`);
+      }
+    }
+  }
+  const old = (text) => numbers(text).filter((n) => byN.get(n)?.some((a) => a.status === 'superseded'));
+  for (const f of b.files) {
+    for (const s of f.sections) for (const n of old(s.text)) add('note', [], `${s.id ? `[${s.id}]` : `${f.path}:${s.line}`} cites ADR ${n}, which is superseded`, `al context ${s.id ?? f.path}`);
+  }
+  for (const x of b.blocks.values()) if (x.open && x.now) for (const n of old(x.now)) add('note', [x.request], `${x.key} of ${x.request} cites ADR ${n}, which is superseded`, `al context ${x.request}`);
+  return out;
+}