aval-adr 0.6.0

package/README.md

@@ -0,0 +1,217 @@
+# aval
+
+**Git is the history. ADRs are the evidence. `aval resolve` tells you what is
+true now.**
+
+Most ADR tooling helps you write and browse decision records. `aval` answers a
+different question, the one a coding agent actually needs before it writes a
+line of code:
+
+```console
+$ aval resolve storage.object-store --scope homelab
+active   ADR-0021   Ceph RGW
+$ echo $?
+0
+```
+
+and, just as importantly, refuses to guess when it should not:
+
+```console
+$ aval resolve data.realtime-processing
+undecided   no accepted decision for this key
+$ echo $?
+4
+
+$ aval resolve api.gateway
+contradiction   two heads for api.gateway
+  ADR-0062  introduced in 4f2ac1d
+  ADR-0071  introduced in 9bd3e08
+$ echo $?
+5
+```
+
+An agent branches on a number. It never reads three documents and reasons its
+way to a plausible wrong answer.
+
+## The idea
+
+ADRs are not the current architecture. **ADRs are the evidence from which the
+current architecture is computed.**
+
+- A **decision key** names one architectural question, from a controlled
+  vocabulary. `storage.object-store`, not "the storage doc".
+- An **ADR** is an event that changes one or more keys.
+- **Superseded is never written down.** It is derived from supersession edges.
+  A hand-written status is copied state, and copied state drifts.
+- **`HEADS.md` is a projection**, regenerated and byte-compared in CI. Nobody
+  edits it.
+
+## Typed non-answers
+
+The design is mostly about what happens when there is no clean answer, because
+that is where an agent left to its own judgment does damage.
+
+| Exit | Verdict | Means |
+|---|---|---|
+| 0 | `active` | here is the decision |
+| 4 | `undecided` | the key exists, nothing decided it |
+| 5 | `contradiction` | competing heads. Stop, do not pick one. |
+| 6 | `retired` | an ADR deliberately retired this key |
+| 7 | `unknown` | no such key or scope, or a key not decided on that axis |
+
+## In front of an agent
+
+A corpus that resolves is half the point. The other half is that whatever is
+about to write code starts from what was decided:
+
+```console
+$ aval hook install
+  wrote  .claude/hooks/aval-heads.sh  (created)
+  wrote  .claude/settings.json  (merged)
+```
+
+It writes a session-start hook that prints the current heads, and merges one
+entry into `.claude/settings.json` without disturbing what else is there. The
+hook is **silent** when `aval` is not installed, so committing it cannot fail a
+colleague's session, and silent when there is no corpus to report.
+
+Repo-specific caveats go in `.claude/aval-hook.local.md`. The hook appends that
+file; installing again never touches it. `--check` is the drift detector for
+CI: exit 0 wired, exit 1 stale.
+
+The hook pushes; **`aval mcp` lets an agent pull** — the same answers as native
+tools, asked at the moment the question comes up rather than only at the top of
+a session:
+
+```console
+$ claude mcp add aval -- aval mcp
+```
+
+Five read-only tools: `aval_resolve`, `aval_keys`, `aval_heads`, `aval_show`,
+`aval_history`. They resolve through the same graph the CLI does and return the
+same bytes `--json` would, so the two surfaces cannot drift apart.
+
+The distinction that matters: **a verdict is not an error**. `undecided`,
+`retired`, `unknown` and `contradiction` all come back as ordinary results with
+`isError: false`, because each is an answer. Reporting `contradiction` as a tool
+failure would teach an agent to retry or work around the one verdict that means
+*stop and ask a human* — so the flag is reserved for a corpus that would not
+load, or a name it does not carry.
+
+Nothing on that surface writes. Resolving answers a question; deciding is not
+something to do on an agent's behalf.
+
+Codes `1`, `2` and `3` mean the tool failed, was misused, or could not read the
+corpus. They never overlap a verdict, so "I could not look" is never mistaken
+for "I looked and found nothing".
+
+## Scopes
+
+A decision can be global or partitioned. Choosing VXLAN for one cluster must not
+silently change another, so scoped divergence and in-place replacement are
+different edges:
+
+```yaml
+- key: cni.routing-mode
+  scope: cloud
+  choice: VXLAN tunnel + WireGuard
+  first: true
+  overrides: ADR-0006      # the global native-routing head STAYS a head
+```
+
+## Commands
+
+| | |
+|---|---|
+| `aval resolve <key> [--scope S]` | the authoritative lookup |
+| `aval check` | every invariant; what the git hook and CI run |
+| `aval heads [--write\|--check]` | the projection |
+| `aval show ADR-0015` | derived status, including partial supersession |
+| `aval history <key>` | the chain, labelled as history |
+| `aval hook install [--check]` | put the heads in front of an agent at session start |
+| `aval pack [--write\|--check]` | publish this corpus's declarations for others to read |
+| `aval add <source>… [--dry-run]` | vendor another repository's declarations |
+| `aval add --check` | are the vendored packs still what their revisions name |
+
+## Sharing one decision across repositories
+
+A decision made once should be readable everywhere it applies. `aval pack`
+publishes a corpus's declarations; `aval add` vendors them into another
+repository, which then resolves them as if they were its own.
+
+```console
+$ aval add github:acme/decisions
+$ aval resolve stack.sql-layer --scope effect-stack
+active   decisions:ADR-0002   @effect/sql
+  vendored: from the `decisions` pack; change it there, not here
+```
+
+A consumer needs no corpus of its own — a registry with `packs:` and no `dir:`
+is enough. Transport is git and only git, so a private repository and a forge
+behind a client certificate both work with your own credentials and no token
+issued to this tool.
+
+What a consumer cannot do is quietly disagree. A local record deciding a slot a
+pack already decides is two heads for one slot, which is exit 5 — the invariant
+the model already had, and the reason vendoring is worth anything. What it
+*can* do is answer the same key at a scope of its own: one repository may hold
+a SQL layer in the browser and another in the app server without either being
+a disagreement with the fleet's answer at the fleet's scope.
+
+Nothing in a pack is ever executed, so there is no trust prompt to match
+`amont trust`. The review gate is the pull request that adds the file.
+
+## Status
+
+Published, and in use: the resolver, the invariants, the projection, the CLI,
+vendoring and the tool surface all work, against real corpora rather than
+fixtures. [`SEMANTICS.md`](SEMANTICS.md) is normative and is the place to
+start if you intend to write records against this.
+
+Still to come: a 1.0.
+
+## Install
+
+    curl -fsSL https://raw.githubusercontent.com/fredericrous/aval/main/install/install.sh | sh
+
+Pin a version or move the destination with `AVAL_VERSION` and `AVAL_BIN_DIR`.
+Windows: `irm https://raw.githubusercontent.com/fredericrous/aval/main/install/install.ps1 | iex`.
+
+Also `cargo install aval`, and `npx aval-adr` — the npm package carries the
+suffix because plain `aval` was taken in 2016 by an unrelated property
+validator; the binary it installs is still `aval`.
+
+Nothing is gated by installing. To gate a repository, one committed line in its
+[`amont.conf`](https://github.com/fredericrous/amont):
+
+    pre-commit    adr   *+.adr.yaml   block   aval check
+
+Records live under `dir`, and a specification that carries decisions can be
+named where it is rather than moved:
+
+```yaml
+dir: docs/adr
+sources:
+  - docs/spec-change-proposals.md
+```
+
+Literal paths, not patterns: a listed file that goes missing is an error, where
+a pattern that stops matching would drop the record and let a superseded
+decision come back as the current one.
+
+The `+` keeps it inert in any repository without a `.adr.yaml`, and a missing
+binary is reported as a gap rather than blocking a commit.
+
+## Building
+
+    make check      # what CI runs: no-deps, fmt, clippy, tests
+    cargo build --release
+
+No external dependencies, by design and enforced in CI. `aval` runs on the
+pre-commit path, so it pulls in nothing. `make check` uses rustup's shim when
+one is present, because a Homebrew cargo earlier on `PATH` ignores the
+toolchain pin and would lint with a different clippy than CI.
+
+## License
+
+MIT

package/bin/aval.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// The resolver. See ./native.js for how the platform binary is found.
+require("./native.js").become("aval");

package/bin/native.js

@@ -0,0 +1,98 @@
+// Find the native binary npm installed for this platform, and become it.
+//
+// This wrapper exists only because a package manager can link a `bin` that
+// lives inside the package, and the native executable lives in a DIFFERENT
+// package — one of six, selected by npm from `os`/`cpu`/`libc`.
+//
+// It is not on the hook path. `aval init` bakes `current_exe()` — the native
+// binary this spawns, not this file — into `.git/hooks`, so the ~30ms of node
+// start-up below is paid once during `prepare` and never again on a commit.
+// See npm/README.md.
+//
+// Parameterised by binary name rather than copied per binary. Everything below
+// — pnpm's non-hoisting, the libc fallback, spawn-versus-exists, signal exit
+// codes — was learned once and is worth exactly one copy; a second wrapper that
+// duplicated it would be a second place for those lessons to rot.
+
+const { spawnSync } = require("node:child_process");
+const { existsSync } = require("node:fs");
+
+// The same six targets `release.yaml` builds, spelled the way npm spells them.
+// `libc` is why linux-x64 appears twice: a musl host cannot run the glibc build,
+// and npm will install only the package whose `libc` matches.
+const PACKAGES = {
+  "darwin arm64": "@aval-adr/darwin-arm64",
+  "darwin x64": "@aval-adr/darwin-x64",
+  "linux arm64": "@aval-adr/linux-arm64-gnu",
+  "linux x64": ["@aval-adr/linux-x64-gnu", "@aval-adr/linux-x64-musl"],
+  "win32 x64": "@aval-adr/win32-x64",
+};
+
+function candidates() {
+  const found = PACKAGES[`${process.platform} ${process.arch}`];
+  if (!found) return [];
+  return Array.isArray(found) ? found : [found];
+}
+
+// `require.resolve` rather than a hand-built `../aval-<target>/bin/…` path.
+// pnpm does not hoist — the real package sits under `node_modules/.pnpm/` — so a
+// path assembled from `__dirname` is correct under npm and wrong under pnpm and
+// yarn. Node's own resolver knows where the dependency actually is.
+function binaryOf(pkg, name) {
+  const exe = process.platform === "win32" ? `${name}.exe` : name;
+  try {
+    const p = require.resolve(`${pkg}/bin/${exe}`);
+    if (existsSync(p)) return p;
+  } catch {
+    // Not installed: either the wrong libc for this host, or an
+    // `--ignore-scripts`-style install that skipped optional deps.
+  }
+  return null;
+}
+
+// Existence is not runnability, so the loop is over SPAWNS, not paths. With a
+// package manager that ignores the `libc` field — yarn classic does, and
+// `npm install --force` is this file's own suggested remedy — BOTH linux-x64
+// builds get installed, gnu listed first, and on a musl host the gnu binary
+// fails at exec on the missing glibc loader while the right one sits a
+// candidate later. Only a spawn-level failure (`result.error`) falls through:
+// a binary that ran and exited non-zero has ANSWERED, and its exit code is the
+// whole product of a hook runner.
+function become(name) {
+  const failures = [];
+  for (const pkg of candidates()) {
+    const binary = binaryOf(pkg, name);
+    if (!binary) continue;
+    // `spawnSync` with inherited stdio rather than `execFileSync`: this forwards
+    // the child's exit CODE. It also keeps the child's stdin, which `aval run`
+    // reads.
+    const result = spawnSync(binary, process.argv.slice(2), { stdio: "inherit" });
+    if (result.error) {
+      failures.push(`      ${binary}: ${result.error.message}`);
+      continue;
+    }
+    // A signalled child has a null status. Report it the way a shell does, so
+    // "killed by SIGINT" does not read as a clean exit 0.
+    if (result.status === null && result.signal) {
+      process.exit(128 + (require("node:os").constants.signals[result.signal] ?? 0));
+    }
+    process.exit(result.status ?? 1);
+  }
+
+  // Name the platform. "aval binary not found" sends people to reinstall;
+  // "no build for linux/ppc64" tells them the actual answer, which is that they
+  // want `cargo install aval` or the shell installer.
+  const target = `${process.platform}/${process.arch}`;
+  process.stderr.write(
+    `${name}: no runnable native binary for ${target}.\n` +
+      (failures.length ? `  Installed but could not run:\n${failures.join("\n")}\n` : "") +
+      `  npm installs one of: ${Object.values(PACKAGES).flat().join(", ")}\n` +
+      `  If your platform is not among them, build from source:\n` +
+      `      cargo install aval\n` +
+      `  If it is, the optional dependency did not install — try:\n` +
+      `      npm install --force aval\n`,
+  );
+  process.exit(1);
+}
+
+module.exports = { become };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "aval-adr",
+  "version": "0.6.0",
+  "description": "Ask what the current architecture decision is, and get a typed answer",
+  "keywords": [
+    "adr",
+    "architecture",
+    "architecture-decision-record",
+    "decision-record",
+    "governance",
+    "documentation"
+  ],
+  "homepage": "https://github.com/fredericrous/aval#readme",
+  "bugs": "https://github.com/fredericrous/aval/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fredericrous/aval.git"
+  },
+  "license": "MIT",
+  "author": "Frederic Rousseau",
+  "type": "commonjs",
+  "_comment_name": "The package is `aval-adr` and the binary it installs is `aval`. npm's `aval` was taken in 2016 by an unrelated property validator that has not moved since 0.1.3. crates.io and Homebrew both carry the plain name; only npm needs the suffix.",
+  "bin": {
+    "aval": "bin/aval.js"
+  },
+  "files": [
+    "bin/aval.js",
+    "bin/native.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "optionalDependencies": {
+    "@aval-adr/darwin-arm64": "0.6.0",
+    "@aval-adr/darwin-x64": "0.6.0",
+    "@aval-adr/linux-arm64-gnu": "0.6.0",
+    "@aval-adr/linux-x64-gnu": "0.6.0",
+    "@aval-adr/linux-x64-musl": "0.6.0",
+    "@aval-adr/win32-x64": "0.6.0"
+  }
+}