@nikovirtala/adr 0.3.0 → 0.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 Architecture decision records kept as event logs in git, built on [`@nikovirtala/ledger`](https://www.npmjs.com/package/@nikovirtala/ledger). A decision is a Markdown body plus append-only event files. Its status (proposed, accepted, rejected, withdrawn, deprecated, superseded) is computed from the events, the body is frozen by its hash once accepted, and supersession chains always lead to the decision in force. See the [design doc](https://github.com/nikovirtala/ark/blob/main/docs/01-adr-v1.md).
 
-Released at 0.x. Phase 1 ("Core") brought the decision kind, the library and the `adr` CLI with `new`, `accept`, `supersede`, `list`, `show` and `verify`. Phase 2a ("Commands and Scope") adds `init`, `reject`, `withdraw`, `deprecate`, `note`, `link`, `scope` and `for`, `accept --copy-scope`, Conventional Commits messages for `--commit`, and `ARK_ON_BEHALF_OF` for agents. Phase 2b ("Guardrails") adds git hooks (`adr hooks`), a generated `index.md` that every write keeps fresh (`adr index`), display numbers in shallow clones read from that index, `list --since`, a recovery hint when git refuses a `--commit`, and verify checks for scope globs, code anchors, changes under inactive decisions and narrowed scopes.
+Released at 0.x. Phase 1 ("Core") brought the decision kind, the library and the `adr` CLI with `new`, `accept`, `supersede`, `list`, `show` and `verify`. Phase 2a ("Commands and Scope") adds `init`, `reject`, `withdraw`, `deprecate`, `note`, `link`, `scope` and `for`, `accept --copy-scope`, Conventional Commits messages for `--commit`, and `ARK_ON_BEHALF_OF` for agents. Phase 2b ("Guardrails") adds git hooks (`adr hooks`), a generated `index.md` that every write keeps fresh (`adr index`), display numbers in shallow clones read from that index, `list --since`, a recovery hint when git refuses a `--commit`, and verify checks for scope globs, code anchors, changes under inactive decisions and narrowed scopes. 0.5.0 checks references into other repositories' decision logs against a local cache (`verify --fetch-sources`, `adr sources fetch`, `list --source`, `search --source`), re-checks every decision in `verify --staged` when a staged config or template changes, lets proposed decisions name code that doesn't exist yet, and names batches of staged events in default commit subjects.
 
 ## Install
 
@@ -32,6 +32,8 @@ Each decision has a canonical id (`k3f9q8a1`). Accepted decisions also get a num
 ```sh
 # Set up: write adr.toml and starter templates; never overwrites a file.
 adr init --template nygard --template madr --commit
+adr init --skill                                     # also the agent skill and an AGENTS.md pointer
+adr init --skill --skill-dir .kiro/skills/adr
 
 # Propose: render a draft from a template, write the body and the proposed event, and stage them.
 adr new "Use Aurora for orders" --section context="We need SQL." --section scope=services/orders
@@ -67,10 +69,19 @@ adr list --since ORIG_HEAD                 # only decisions with events added si
 adr show ADR-0001 --history
 adr list --ref v1.2.0                      # time travel: the log as of any ref
 
+# Search ids, titles, bodies and notes: every word must match; active decisions unless --all.
+adr search orders aurora
+adr search dynamodb --all
+
 # Verify the log: the whole tree, a range, or the staged changes (for a pre-commit hook).
 adr verify
 adr verify --base origin/main --format github
 adr verify --staged
+adr verify --fetch-sources                   # fetch [[sources]] first (CI, pre-push); a failed fetch exits 2
+
+# Other repositories' decision logs, read from a local cache.
+adr sources fetch [<name>]
+adr list --source platform
 
 # The generated index (with [log] index = "committed"): regenerate it, or check that it is current.
 adr index
@@ -79,20 +90,25 @@ adr index --check
 # Git hooks: install adr in ledger's shared hook shims, or print the config for a hook manager.
 adr hooks install
 adr hooks print --manager lefthook
+
+# The MCP server for agents, over stdio; start it from an MCP client (see "MCP server").
+adr mcp
 ```
 
 - `new` takes `--template <name>` (default `nygard`; built-ins `nygard`, `madr`, `y-statement`, or your own `<root>/templates/<name>.md`), `--section <id>=<markdown>` (repeatable), `--supersedes <decision>` (repeatable), and `--edit`/`--no-edit`. It opens `$VISUAL` or `$EDITOR` with `--edit`, or by default in an interactive terminal; an editor failure never loses your edits and never commits content you didn't confirm.
 - `new --no-edit --commit` (or `--commit` with no editor) refuses a draft with unfilled required sections: exit 1, nothing written. Without `--commit` the draft is staged with a warning on stderr; after an editor, a draft that still has unfilled sections stays staged and isn't committed.
 - `accept` of a decision that supersedes others offers their scope globs: `--copy-scope` copies them in the same write, `--no-copy-scope` doesn't, and without either it asks `[y/N]` in a terminal and otherwise prints the `adr scope … --add …` command that would copy them.
-- `scope` takes `--set <glob>` (repeatable; replaces the set), `--add`/`--remove <glob>` (repeatable) or `--clear`, and stores the set sorted and deduplicated. It notes a glob that matches no tracked file and a narrowing of an accepted decision. verify requires the globs of proposed and accepted decisions to match tracked files (`scope/glob-unmatched`), so with hooks installed `adr scope <proposed> --set 'src/payments/**' --commit` for code not written yet writes and stages the scope, then fails in pre-commit with the recovery hint below, and its note says so. To finish it, commit the code the glob should match first (`git add` it, then `git commit -m "<subject>" -- <its paths>`) and then run the printed command, or `git add` the code and append its paths after `--` in the printed command. `scope --follow-renames [<decision>]` updates the globs of every decision (or one) for the staged renames, so a moved file stays governed, and only stages.
+- `scope` takes `--set <glob>` (repeatable; replaces the set), `--add`/`--remove <glob>` (repeatable) or `--clear`, and stores the set sorted and deduplicated. It notes a glob that matches no tracked file and a narrowing of an accepted decision. verify requires the globs of accepted decisions to match tracked files (`scope/glob-unmatched`). A proposed decision's globs may name code that doesn't exist yet, because the decision is still planned, and the note says verify reports them once it is accepted; `adr accept` notes each glob that still matches nothing, so with hooks installed an `accept --commit` fails in pre-commit until the code is there. `scope --follow-renames [<decision>]` updates the globs of every decision (or one) for the staged renames, so a moved file stays governed, and only stages.
 - `for <path>…` lists the decisions governing each file, from scope globs and code anchors, with a warning for decisions that aren't in force. A code anchor is a comment such as `// adr:<id>` or `# adr:<source>:<id>`: the token counts only after a comment leader on the same line (a heuristic), and anchors in binary files, submodules, the log directory and files matched by `[scope] anchor_exclude` are not found.
-- Writes stage their files and don't commit, unless you pass `--commit` or set `auto_commit`. A commit holds every file of the decisions it touches (body, events, template), so `adr verify --ref <commit>` is clean, and never your unrelated staged work. It refuses with exit 2 when a file it needs has unstaged changes or isn't tracked. Its `ADR: <id>` and `ADR-Event: <type>` trailers name one event each, in a fixed order, whatever your `trailer.*` config.
-- `--commit` messages follow Conventional Commits: the subject comes from `[commit] subject` (default `docs(adr): {action} {title}`, for example `docs(adr): propose to use Aurora for orders`, `docs(adr): decide to use Aurora for orders`, `docs(adr): set the scope of ADR-0003`). The description starts with a lowercase letter and the rest keeps its natural casing (`Use` becomes `use`; `CLI`, `ARK_AGENT`, `GraphQL` and `Node 24` stay). `new`, `accept`, `reject` and `withdraw` name the decision by its title (`propose to`, `decide to`, `decide not to`, `withdraw the proposal to`), while `deprecate`, `supersede`, `note`, `link` and `scope` name it by its number or id. A title that would make the description longer than 72 characters is shortened with `…`, at a word boundary when one is near the limit, the body then starts with `Full title: <title>`, and a note says so; numbers and ids are never shortened. `-m/--message <text>` replaces the subject and body as given; a message that ends in its own trailer block as git reads it, such as `Co-authored-by:` or `Refs:` lines, gets adr's trailers appended to that paragraph. The trailers are always the last paragraph, so `git log --grep "ADR: <id>"` finds a decision's commits.
+- Writes stage their files and don't commit, unless you pass `--commit` or set `auto_commit`. A commit holds every file of the decisions it touches (body, events, template), so `adr verify --ref <commit>` is clean, and never your unrelated staged work. It refuses with exit 2 when a file it needs has unstaged changes or isn't tracked. Its `ADR: <id>` and `ADR-Event: <type>` trailers come in one pair per decision and event type, in a fixed order, whatever your `trailer.*` config.
+- `--commit` messages follow Conventional Commits: the subject comes from `[commit] subject` (default `docs(adr): {action} {title}`, for example `docs(adr): propose to use Aurora for orders`, `docs(adr): decide to use Aurora for orders`, `docs(adr): set the scope of ADR-0003`). The description starts with a lowercase letter and the rest keeps its natural casing (`Use` becomes `use`; `CLI`, `ARK_AGENT`, `GraphQL` and `Node 24` stay). `new`, `accept`, `reject` and `withdraw` name the decision by its title (`propose to`, `decide to`, `decide not to`, `withdraw the proposal to`), while `deprecate`, `supersede`, `note`, `link` and `scope` name it by its number or id. A title that would make the description longer than 72 characters is shortened with `…`, at a word boundary when one is near the limit, the body then starts with `Full title: <title>`, and a note says so, naming the 72-character limit of the description after `docs(adr):`; numbers and ids are never shortened. A commit that sweeps in staged events of other types names them together (`docs(adr): link and scope ADR-0003`, `update ADR-0003` beyond three verbs), and one that sweeps in a staged proposal or status change takes that event's title form (`docs(adr): propose to use SQS for jobs`). `-m/--message <text>` replaces the subject and body as given; a message that ends in its own trailer block as git reads it, such as `Co-authored-by:` or `Refs:` lines, gets adr's trailers appended to that paragraph. The trailers are always the last paragraph, so `git log --grep "ADR: <id>"` finds a decision's commits.
 - When git refuses a `--commit` (a failing hook, signing), the write stays written and staged, and adr exits 2 (`commit-failed`) with a recovery hint: git's error, the staged paths, the trailers, and the exact command that makes the commit, `git -C <top> commit --cleanup=whitespace -F <git dir>/ark/COMMIT_MSG --only -- <paths>`, with the full message saved in that file (edit it if needed, but keep the trailers). Don't run the adr command again: the log already holds the change, so a rerun would be refused, do nothing, or write it a second time. When `index.md` is among the paths, the hint ends with `Then run adr index --no-commit to restore other decisions' entries in docs/adr/index.md.` The notes the write would have reported are printed as warnings before the hint.
 - With `[log] index = "committed"`, every write keeps `<root>/index.md` current: the accepted and proposed decisions, then the superseded, deprecated, rejected and withdrawn ones, each with its number, linked title, status and date, and a last line recording the numbers. A `--commit` renders it from exactly the tree the commit holds and includes it whenever the commit changes it; the work-tree copy keeps other decisions' uncommitted entries. Numbers are projected: on a branch they are the numbers its acceptances will get once it merges, after main's (`[log] main_branch`), also when main was merged into the branch. When a write leaves the staged `index.md` listing another decision's untracked or unstaged files, it notes them, since the next plain commit's hook reports `index/stale` until they are staged. `adr index` regenerates and stages it, `adr index --commit` commits it as `docs(adr): regenerate the decision index`, and `adr index --check` exits 1 when it is stale or missing.
 - `list --since <rev>` lists only the decisions with event files added between `<rev>` and HEAD (or `--ref`), each with the new event types, such as `[new: accepted]`; it prints nothing when the log didn't change.
 - In a shallow clone, numbers need history the clone lacks. With a committed index, adr reads them from `index.md` in the commit being read (`--ref`, else HEAD) and notes `numbers come from docs/adr/index.md (shallow clone)`; without one, decisions display by id until you run `git fetch --unshallow`. Nothing is fetched automatically.
-- `hooks install` registers adr in ledger's shims, one per hook and shared with other ark tools: `pre-commit` runs `adr hooks run pre-commit`, `commit-msg` runs `adr hooks trailers` (adds `ADR:` and `ADR-Event:` trailers when event files are staged, unless the message has them or a merge is in progress), `pre-push` runs `adr verify --base @{upstream} --ref HEAD`, which checks the current branch's commits against its upstream whichever refs the push names (without an upstream, against `origin`'s default branch; with no remote, the whole log), and `post-merge` runs `adr list --since ORIG_HEAD`. It never overwrites a foreign hook (it writes the other hooks, exits 2 and names the line to add to that hook) and writes nothing when `core.hooksPath` is set (exit 2, pointing to `adr hooks print --manager lefthook|husky|pre-commit` for the hook manager in use). `hooks uninstall` removes adr from the shims. The pre-commit steps are rename following (`[hooks] scope_follow_renames`), the index (checked, or regenerated and staged with `[hooks] index = "stage"`), then `verify --staged`. The hook stages only into the commit's own index: for `git commit <paths>`, a rename that changes a decision's scope stops the commit and names the command to run. When the staged `index.md` lists decision files that aren't staged, the `index/stale` finding names them; stage them, or move them out of the work tree and run `adr index`.
+- `hooks install` registers adr in ledger's shims, one per hook and shared with other ark tools: `pre-commit` runs `adr hooks run pre-commit`, `commit-msg` runs `adr hooks trailers` (adds `ADR:` and `ADR-Event:` trailers when event files are staged, unless the message has them or a merge is in progress), `pre-push` runs `adr verify --base @{upstream} --ref HEAD --fetch-sources` (rerun `adr hooks install` after upgrading from 0.4.x to get the flag), which checks the current branch's commits against its upstream whichever refs the push names (without an upstream, against `origin`'s default branch; with no remote, the whole log), and `post-merge` runs `adr list --since ORIG_HEAD`. It never overwrites a foreign hook (it writes the other hooks, exits 2 and names the line to add to that hook) and writes nothing when `core.hooksPath` is set (exit 2, pointing to `adr hooks print --manager lefthook|husky|pre-commit` for the hook manager in use). `hooks uninstall` removes adr from the shims. The pre-commit steps are rename following (`[hooks] scope_follow_renames`), the index (checked, or regenerated and staged with `[hooks] index = "stage"`), then `verify --staged`, which checks every decision when the staged changes touch `adr.toml` or the templates. The hook stages only into the commit's own index: for `git commit <paths>`, a rename that changes a decision's scope stops the commit and names the command to run. When the staged `index.md` lists decision files that aren't staged, the `index/stale` finding names them; stage them, or move them out of the work tree and run `adr index`.
+- `search <query>…` joins its words and lists the decisions whose id, number, title, body or notes contain every one, case- and accent-insensitively (`Café` finds `cafe`), as substrings (`order` finds `orders`). Only proposed and accepted decisions are listed unless `--all`; a note counts the others that match. Each result has the best matching line of the body or a note. It reads the local log, or a cached source's with `--source <name>`.
+- `init --skill` writes the agent skill to `.claude/skills/adr/SKILL.md`, or to `<dir>/SKILL.md` with `--skill-dir <dir>` (a directory inside the repository), and adds one line pointing at it to `AGENTS.md`, creating the file if needed. It never overwrites a SKILL.md (one that differs is kept, with a note), and a second run changes nothing. An `AGENTS.md` with unstaged changes, or not tracked, gets the line but isn't staged; with `--commit` it is refused (exit 2).
 - `show` leads with a state header. A decision that isn't in force says so and names what to read instead, for example `SUPERSEDED by ADR-0002 (accepted 2026-10-18). Do not apply this decision; read ADR-0002 instead.`
 
 Every command takes `--json`, `--root <dir>` (the log directory) and `--help`; reads also take `--ref <ref>`, and writes refuse it.
@@ -103,7 +119,7 @@ Every command takes `--json`, `--root <dir>` (the log directory) and `--help`; r
 - **1**: failing findings from `verify` (or `index --check`, or a hook), or a write the log's rules forbid (an illegal transition, a draft that fails its template lint, an agent's acceptance, an unaccepted successor). Nothing is written, and the findings are in the output.
 - **2**: the tool can't run: bad usage (unknown command, flag or decision, a missing argument, `--ref` on a write), config, environment or internal errors. Nothing is written, except when git refuses a `--commit` (`commit-failed`): the write is then staged and the error says how to finish the commit.
 
-With `--json`, stdout carries exactly one JSON document: `adr-list/v1` (with `since`, `null` without `--since`), `adr-show/v1`, `adr-write/v1` (for every write command), `adr-for/v1`, `adr-init/v1`, `adr-index/v1`, `adr-hooks/v1`, ledger's `ledger-findings/v1` for `verify`, or `ark-error/v1` (`{ "format": "ark-error/v1", "error": { "code", "message" } }`) when the command exits 2; a `commit-failed` error also has the write's `notes`. Every key is always present, with `null` where a value is unknown. A `numbering` object's `reason` is `"index"` when a shallow clone's numbers come from `index.md`. In a shallow clone with a committed index, `adr-write/v1`'s `decision.number` comes from the index in HEAD, which on a branch is the number the acceptance will get once the branch merges. Warnings and notes go to stderr.
+With `--json`, stdout carries exactly one JSON document: `adr-list/v1` (with `since`, `null` without `--since`), `adr-show/v1`, `adr-search/v1`, `adr-write/v1` (for every write command), `adr-for/v1`, `adr-init/v1`, `adr-index/v1`, `adr-hooks/v1`, ledger's `ledger-findings/v1` for `verify`, or `ark-error/v1` (`{ "format": "ark-error/v1", "error": { "code", "message" } }`) when the command exits 2; a `commit-failed` error also has the write's `notes`. Every key is always present, with `null` where a value is unknown. A `numbering` object's `reason` is `"index"` when a shallow clone's numbers come from `index.md`. In a shallow clone with a committed index, `adr-write/v1`'s `decision.number` comes from the index in HEAD, which on a branch is the number the acceptance will get once the branch merges. Warnings and notes go to stderr.
 
 ## Config (`adr.toml`)
 
@@ -119,7 +135,7 @@ index = "none"                  # or "committed": adr index, fresh on every writ
 [policy]
 accept_requires_human = true    # refuse acceptances by an agent
 auto_commit = false             # commit writes without --commit
-mcp_can_decide = false          # validated now, used in phase 3
+mcp_can_decide = false          # agents propose, humans decide; true adds adr_accept, adr_reject, adr_deprecate and adr_supersede to adr mcp
 
 [verify]
 fail_on = "error"               # or "warning"
@@ -137,7 +153,9 @@ scope_follow_renames = "stage"  # stage, warn or off: pre-commit's rename follow
 index = "check"                 # check, or stage to regenerate index.md in pre-commit
 ```
 
-verify also checks code against the log: `scope/glob-invalid` (error) for a stored glob that doesn't parse, `scope/glob-unmatched` (error) for a glob of a proposed or accepted decision that matches no tracked file, `scope/anchor-missing` (error) for an `adr:<id>` anchor naming no decision in the log (qualified anchors are checked in ark's step 4), `decision/governed-by-inactive` (a warning, or an error with `governed_by_inactive = "error"`) for a changed file governed by a superseded or deprecated decision, and `decision/scope-narrowed` (warning) when a new scope stops covering files that still exist. Deprecated decisions' globs no longer have to match files. With `index = "committed"`, `index/missing` and `index/stale` are errors, and `index/unchecked` warns in a shallow clone without a recorded index.
+verify also checks code against the log: `scope/glob-invalid` (error) for a stored glob that doesn't parse, `scope/glob-unmatched` (error) for a glob of an accepted decision that matches no tracked file, `scope/anchor-missing` (error) for an `adr:<id>` anchor naming no decision in the log, `decision/governed-by-inactive` (a warning, or an error with `governed_by_inactive = "error"`) for a changed file governed by a superseded or deprecated decision, and `decision/scope-narrowed` (warning) when a new scope stops covering files that still exist. Deprecated decisions' globs no longer have to match files. With `index = "committed"`, `index/missing` and `index/stale` are errors, and `index/unchecked` warns in a shallow clone without a recorded index.
+
+References into other repositories' decision logs (`platform:k3f9q8a1`, from `[[sources]]` entries with `kind = "adr"`) are checked against a local cache kept in the git directory. Plain `verify`, the hooks' pre-commit step and every read and write use only the cache and never the network: a referenced source that isn't cached gives one `sources/not-fetched` warning. `verify --fetch-sources` fetches each source first and exits 2 when a fetch fails; `adr sources fetch` refreshes the cache by hand, and `verify --json` records the commit each source resolved to. A missing target in a cached source is `decision/reference-missing`, and a source name that isn't configured `decision/unknown-source`. A ref may be a branch, a tag or a full commit; a tag or commit keeps CI reproducible. Fetching uses git's credentials: for a private source in CI, an `insteadOf` URL with a token from the CI secret store, or an SSH deploy key.
 
 `[commit] subject` is one line with `{title}` (what names the decision: its title with an ordinary capitalized first word lowercased (`Use` → `use`, so a single-capital proper noun such as `Aurora` loses that capital; `CLI`, `GraphQL` and `ARK_AGENT` stay), or its number or id), `{raw_title}` (the same with its case kept), `{action}`, `{id}`, `{display}` and `{command}`. It is checked when the config is read: at most one title placeholder, after the type and scope, and room within 72 characters for the title (20 characters) and, uncut, for the longest number-based name (`ADR-0001 to a decision in another log`); an invalid template exits 2. Whatever the template, the description's first letter is lowercased.
 
@@ -149,9 +167,41 @@ An agent using the CLI sets `ARK_AGENT=<agent-id>`, and `ARK_ON_BEHALF_OF=<email
 
 The git identity is git's author identity (`git var GIT_AUTHOR_IDENT` with `user.useConfigOnly`): `GIT_AUTHOR_NAME` and `GIT_AUTHOR_EMAIL` when set, else `user.name` and `user.email`; it is never guessed. Setting `GIT_AUTHOR_*` also changes the author of `--commit` commits, which is why agents should use `ARK_ON_BEHALF_OF` instead. `--commit` also needs a committer identity, and exits 2 before writing without one.
 
+Agents with an MCP client use `adr mcp` instead (below), and `adr init --skill` gives them the skill: when to check the decisions, how to read them, and that they propose and a human accepts.
+
+## MCP server
+
+`adr mcp` serves the decision log to agents over stdio, in the repository it starts in (`--root` works as for every command). Add it to your MCP client's server config:
+
+```json
+{
+  "mcpServers": {
+    "adr": {
+      "command": "npx",
+      "args": ["-y", "@nikovirtala/adr", "mcp"],
+      "env": { "ARK_ON_BEHALF_OF": "you@example.com" }
+    }
+  }
+}
+```
+
+Set `ARK_ON_BEHALF_OF` in that `env`: stdio clients pass only a few environment variables (`HOME`, `PATH` and the like) to the server, so a value exported in your shell doesn't reach it. Writes are recorded as an agent named by the MCP client (`actor.agent`), on behalf of `ARK_ON_BEHALF_OF`, or of the git user, with a note. An invalid `ARK_ON_BEHALF_OF` makes `adr mcp` exit 2 before serving.
+
+| Tools | Listed |
+| --- | --- |
+| `adr_search`, `adr_get`, `adr_list`, `adr_templates`, `adr_for_path` (reads) | always |
+| `adr_propose`, `adr_update_draft`, `adr_note`, `adr_link`, `adr_scope`, `adr_withdraw` (writes) | always |
+| `adr_accept`, `adr_reject`, `adr_deprecate`, `adr_supersede` | with `[policy] mcp_can_decide = true` |
+
+- Every tool returns the JSON document its CLI command prints under `--json` (`adr-search/v1`, `adr-show/v1`, `adr-list/v1`, `adr-for/v1`, `adr-write/v1`, and `adr-templates/v1` for `adr_templates`) as `structuredContent`, with a readable text whose state headers come first and point at `adr://decision/<number>`. Errors are `isError` results with `ark-error/v1`; a write the log or the MCP policy refuses is a document with `ok: false` and the findings.
+- Resources: `adr://index` (the index table) and `adr://decision/{id}`, one decision's state header and body, where `{id}` is the id, the number or `ADR-NNNN`. The prompt `adr_draft_from_discussion` (optional `title`, `template`, `supersedes`) walks an agent from a conversation to a proposal.
+- `adr_propose` takes a `sections` map (section id to markdown); template lint findings come back as data, and `adr_update_draft` replaces sections of a draft in place, writing only if nobody changed the file meanwhile. With `auto_commit`, an incomplete draft is refused instead of committed.
+- Without `mcp_can_decide`, an agent may update, scope and withdraw only proposals made on behalf of the same person, and never rescope an accepted or deprecated decision (`decision/mcp-cannot-decide`). `accept_requires_human` still refuses an agent's `adr_accept`.
+- MCP writes stage their files and commit only with `[policy] auto_commit`; there is no commit input. Each call reads the log again, but the tool list is fixed at startup: restart `adr mcp` after changing `mcp_can_decide`.
+
 ## Library
 
-The CLI is a thin layer over the library, and phase 3's MCP server uses the same functions and returns the same JSON documents.
+The CLI is a thin layer over the library, and the MCP server uses the same functions and returns the same JSON documents.
 
 ```ts
 import { listDecisions, openDecisionLog, readDecisions, showDecision, verifyDecisions } from "@nikovirtala/adr";
@@ -162,7 +212,7 @@ const { decisions } = listDecisions(read, { status: ["accepted"] });
 const findings = await verifyDecisions(log, { type: "full" });
 ```
 
-`initDecisionLog`, `proposeDecision`, `acceptDecision`, `rejectDecision`, `withdrawDecision`, `deprecateDecision`, `supersedeDecision`, `noteDecision`, `linkDecision`, `scopeDecision` and `followScopeRenames` write, `decisionsFor` answers `adr for`, `resolveDecision` turns an id or number into an id, and `stateHeader` gives the header `show` prints. `indexDecisionLog` and `renderDecisionIndex` regenerate or render the index, and `installDecisionHooks`, `uninstallDecisionHooks`, `printDecisionHooks`, `runPreCommitHook` and `addHookTrailers` are the hook commands.
+`initDecisionLog`, `proposeDecision`, `acceptDecision`, `rejectDecision`, `withdrawDecision`, `deprecateDecision`, `supersedeDecision`, `noteDecision`, `linkDecision`, `scopeDecision` and `followScopeRenames` write, `decisionsFor` answers `adr for`, `resolveDecision` turns an id or number into an id, and `stateHeader` gives the header `show` prints. `searchDecisions` answers `adr search`, `listTemplates` lists the usable templates (`adr-templates/v1`), `updateDraft` replaces sections of a proposed draft, `sourcesNote` gives the local-only note, and `SKILL_MD` is the agent skill. `indexDecisionLog` and `renderDecisionIndex` regenerate or render the index, and `installDecisionHooks`, `uninstallDecisionHooks`, `printDecisionHooks`, `runPreCommitHook` and `addHookTrailers` are the hook commands.
 
 `@nikovirtala/adr/kind` exports only the decision kind (`adrKind`, made with ledger's `defineKind`) and its types, without any CLI code, for tools that fold decision logs themselves, such as issues linking to decisions:
 
@@ -172,6 +222,5 @@ import { adrKind } from "@nikovirtala/adr/kind";
 
 ## Not yet included
 
-- **Reference checks are local.** `verify` checks that `supersedes`, `superseded.by` and `linked.to` name decisions in the same log. Qualified references to other logs (`<source>:<id>`, written by `adr link`) and qualified anchors are skipped until ark's step 4.
-- **Phase 3:** an MCP server, a SKILL.md for agents, and search.
-- **ark's step 4, with issues:** cross-log reference checks at the pinned ref and listing across sources; until then `link` stores a qualified target unchecked.
+- **Search limits.** `adr search` matches substrings without stemming (`orders` doesn't find `order`) and without phrases, and folds accents but not `ß` (`strasse` doesn't find `Straße`).
+- **Qualified anchors.** `adr:<source>:<id>` anchors aren't checked against sources.

package/dist/cli.js

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
-import { A as openDecisionLog, C as adrChecks, D as runDecisionIndex, N as resolveDecision, O as changedSince, S as withdrawDecision, _ as proposeDecision, a as initDecisionLog, c as installDecisionHooks, d as uninstallDecisionHooks, f as acceptDecision, g as noteDecision, h as linkDecision, j as readDecisions, k as numberingNote, l as printDecisionHooks, m as followScopeRenames, n as listDecisions, o as addHookTrailers, p as deprecateDecision, r as showDecision, t as decisionsFor, u as runPreCommitHook, v as rejectDecision, x as supersedeDecision, y as scopeDecision } from "./scope-CLqH-q1y.js";
-import { n as DECISION_STATUSES, t as adrKind } from "./kind-DjvA3dyA.js";
+import { F as resolveDecision, M as openDecisionLog, N as readDecisions, O as runDecisionIndex, _ as withdrawDecision, b as readDecisionSources, c as followScopeRenames, d as proposeDecision, f as rejectDecision, h as supersedeDecision, i as showDecision, j as numberingNote, k as changedSince, l as linkDecision, n as decisionsFor, o as acceptDecision, p as scopeDecision, r as listDecisions, s as deprecateDecision, t as searchDecisions, u as noteDecision, x as readSourceDecisions, y as decisionSourceConfigs } from "./search-CTspg2pd.js";
+import { n as DECISION_STATUSES, t as adrKind } from "./kind-C3DiBuUp.js";
+import { a as installDecisionHooks, c as uninstallDecisionHooks, l as adrChecks, o as printDecisionHooks, r as addHookTrailers, s as runPreCommitHook, t as initDecisionLog, u as decisionVerifyInputs } from "./init-CaKKCINh.js";
 import { createRequire } from "node:module";
 import { UsageError, exitCode, findingsReport, formatText, renderStateHeader, resolveAttribution, stagedRenames, templateHistoryRef } from "@nikovirtala/ledger";
-import { resolve } from "node:path";
-import { COMMIT_OPTIONS, commitChoice, confirm, processIO, runCli, verifyCommand } from "@nikovirtala/ledger/cli";
+import { realpath } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { COMMIT_OPTIONS, commitChoice, confirm, processIO, runCli, sourcesCommand, verifyCommand } from "@nikovirtala/ledger/cli";
 import { spawn } from "node:child_process";
 // src/cli/open.ts
 /**
@@ -176,7 +178,8 @@ const VERBS = {
 	deprecate: "deprecated",
 	note: "noted",
 	link: "linked",
-	scope: "scoped"
+	scope: "scoped",
+	update: "updated"
 };
 /**
 * The text of a write command (design §5.6, §6.1). `subject` names what a refused command was
@@ -243,6 +246,9 @@ function writeText(doc, display, o) {
 				recorded
 			].join("\n");
 		}
+		case "update":
+			if (doc.written.length === 0) return `Draft of ${named(v.id, display)} unchanged`;
+			return [`Updated the draft of ${named(v.id, display)}: ${v.title}`, recorded].join("\n");
 	}
 }
 /**
@@ -298,15 +304,39 @@ function forText(doc, display, keyword) {
 	}
 	return lines.join("\n");
 }
+/**
+* `adr search`: one padded row per result with its excerpt (or which field matched) under it, and
+* an inactive result's warning; then the count.
+*/
+function searchText(doc) {
+	const quoted = JSON.stringify(doc.query);
+	if (doc.results.length === 0) return `No ${doc.include_inactive ? "" : "active "}decisions match ${quoted}.`;
+	const rows = columns(doc.results.map((r) => [
+		r.decision.number === null ? r.decision.id : `${r.decision.display} (${r.decision.id})`,
+		r.decision.status,
+		r.decision.title
+	])).split("\n");
+	const lines = [];
+	doc.results.forEach((r, i) => {
+		lines.push(rows[i] ?? "");
+		if (r.header.warning !== null) lines.push(`  ${r.header.warning}`);
+		const where = r.matched.filter((f) => f === "id" || f === "title").join(" and ");
+		lines.push(r.excerpt === null ? `  (${where} match)` : `  ${r.excerpt}`);
+	});
+	const n = doc.total;
+	lines.push(`${n === 1 ? "1 decision matches" : `${n} decisions match`} ${quoted}.`);
+	return lines.join("\n");
+}
 /** `adr init`: what was written and kept, then the next step; or that nothing was needed. */
 function initText(doc) {
 	if (doc.written.length === 0) return `Already initialized: ${doc.root} (kept ${doc.kept.join(", ")})`;
+	const skill = doc.skill !== null && doc.written.includes(doc.skill);
 	return [
-		`Initialized ${doc.root}`,
+		doc.written.every((p) => p === doc.skill || p === "AGENTS.md") ? "Set up the adr agent skill" : `Initialized ${doc.root}`,
 		...doc.written.map((p) => `  ${p}`),
 		...doc.kept.map((p) => `Kept ${p}`),
 		...doc.commit === null ? [] : [`Committed ${short$1(doc.commit)}.`],
-		"Next: adr new \"<title>\""
+		skill ? "Next: adr mcp, from your MCP client's config" : "Next: adr new \"<title>\""
 	].join("\n");
 }
 // src/cli/accept.ts
@@ -594,39 +624,68 @@ const indexCommand = {
 	}
 };
 // src/cli/init.ts
-/** `adr init [--template <name>]… [--commit | --no-commit] [-m <message>]` (design §6.2). */
-const initCommand = {
-	name: "init",
-	summary: "set up a decision log: a config file and starter templates",
-	usage: "init [--template <name>]… [--commit | --no-commit] [-m <message>]",
-	options: {
-		template: {
-			type: "string",
-			multiple: true
+const DEFAULT_SKILL_DIR = ".claude/skills/adr";
+const MAX_DIR = 1024;
+/** `--skill-dir` as a repo-relative directory inside the work tree and outside `.git`. */
+async function skillDir(root, cwd, given) {
+	const dir = given.trim();
+	const bad = () => new UsageError("--skill-dir must be a directory inside the repository");
+	if (dir === "" || dir.length > MAX_DIR || dir.includes("\0")) throw bad();
+	const base = await realpath(cwd).catch(() => cwd);
+	const rel = relative(root, resolve(base, dir));
+	if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) throw bad();
+	const segments = rel.split(sep).filter((s) => s !== "");
+	if (segments[0] === ".git") throw bad();
+	return segments.join("/");
+}
+/**
+* `adr init [--template <name>]… [--skill [--skill-dir <path>]] [--commit | --no-commit]
+* [-m <message>]` (design §6.2, phase 3 §9).
+*/
+function initCommand(version) {
+	return {
+		name: "init",
+		summary: "set up a decision log: a config file and starter templates",
+		usage: "init [--template <name>]… [--skill [--skill-dir <path>]] [--commit | --no-commit] [-m <message>]",
+		options: {
+			template: {
+				type: "string",
+				multiple: true
+			},
+			skill: { type: "boolean" },
+			"skill-dir": { type: "string" },
+			...COMMIT_OPTIONS
 		},
-		...COMMIT_OPTIONS
-	},
-	positionals: {
-		min: 0,
-		max: 0,
-		names: []
-	},
-	ref: "reject",
-	async run({ io, flags, values }) {
-		const templates = Array.isArray(values.template) ? values.template : void 0;
-		const log = await openForCli(io, flags);
-		const doc = await initDecisionLog(log, {
-			...templates === void 0 ? {} : { templates },
-			...commitChoice(values, { autoCommit: log.adr.autoCommit })
-		});
-		return {
-			exit: 0,
-			json: doc,
-			text: initText(doc),
-			notes: doc.notes
-		};
-	}
-};
+		positionals: {
+			min: 0,
+			max: 0,
+			names: []
+		},
+		ref: "reject",
+		async run({ io, flags, values }) {
+			const templates = Array.isArray(values.template) ? values.template : void 0;
+			const given = typeof values["skill-dir"] === "string" ? values["skill-dir"] : null;
+			if (given !== null && values.skill !== true) throw new UsageError("--skill-dir needs --skill");
+			const log = await openForCli(io, flags);
+			const root = log.git.root ?? io.cwd;
+			const dir = values.skill !== true ? null : given === null ? DEFAULT_SKILL_DIR : await skillDir(root, io.cwd, given);
+			const doc = await initDecisionLog(log, {
+				...templates === void 0 ? {} : { templates },
+				...dir === null ? {} : { skill: {
+					dir,
+					version
+				} },
+				...commitChoice(values, { autoCommit: log.adr.autoCommit })
+			});
+			return {
+				exit: 0,
+				json: doc,
+				text: initText(doc),
+				notes: doc.notes
+			};
+		}
+	};
+}
 // src/cli/link.ts
 /** `adr link <decision> <target> [--rel <rel>]` (design §6.7): a typed link, in any state. */
 const linkCommand = {
@@ -685,17 +744,21 @@ function sinceRev(values) {
 	if (v.trim() === "" || v.startsWith("-")) throw new UsageError("--since must be a revision");
 	return v;
 }
-/** `adr list [--status <status>]… [--since <rev>]` (design §5.6, 2b D7). */
+/**
+* `adr list [--status <status>]… [--since <rev>] [--source <name>]` (design §5.6, 2b D7):
+* `--source` lists a `[[sources]]` entry's cached log instead of the local one.
+*/
 const listCommand = {
 	name: "list",
 	summary: "list decisions with their computed status",
-	usage: "list [--status <status>]… [--since <rev>]",
+	usage: "list [--status <status>]… [--since <rev>] [--source <name>]",
 	options: {
 		status: {
 			type: "string",
 			multiple: true
 		},
-		since: { type: "string" }
+		since: { type: "string" },
+		source: { type: "string" }
 	},
 	positionals: {
 		min: 0,
@@ -706,9 +769,11 @@ const listCommand = {
 	async run({ io, flags, values }) {
 		const status = statuses(values);
 		const rev = sinceRev(values);
+		const source = typeof values.source === "string" ? values.source : null;
+		if (source !== null && rev !== null) throw new UsageError("--source can't be combined with --since");
 		const log = await openForCli(io, flags);
 		const since = rev === null ? null : await changedSince(log, rev);
-		const read = await readDecisions(log);
+		const read = source === null ? await readDecisions(log) : await readSourceDecisions(log, source);
 		const doc = listDecisions(read, {
 			status,
 			since
@@ -728,6 +793,42 @@ const listCommand = {
 		};
 	}
 };
+// src/cli/mcp.ts
+/**
+* `adr mcp` (design §7.1): the MCP server over stdio. Loaded with a dynamic import, so no other
+* command loads the MCP SDK.
+*/
+function mcpCommand(version) {
+	return {
+		name: "mcp",
+		summary: "start the MCP server over stdio",
+		usage: "mcp",
+		options: {},
+		positionals: {
+			min: 0,
+			max: 0,
+			names: []
+		},
+		ref: "reject",
+		async run({ io, flags }) {
+			if (flags.json) throw new UsageError("adr mcp speaks JSON-RPC on stdout; it takes no --json");
+			if (io.interactive) io.stderr.write("adr: adr mcp speaks MCP on stdin and stdout; start it from an MCP client\n");
+			const { serveAdrMcp } = await import("./server-D3ySzyj6.js");
+			await serveAdrMcp({
+				cwd: io.cwd,
+				root: flags.root,
+				env: io.env,
+				version,
+				stderr: io.stderr
+			});
+			return {
+				exit: 0,
+				json: null,
+				text: ""
+			};
+		}
+	};
+}
 // src/cli/editor.ts
 /**
 * The user's editor as an `edit` callback (design §5.7), or `null` when neither `VISUAL` nor
@@ -1066,6 +1167,45 @@ const scopeCommand = {
 		};
 	}
 };
+// src/cli/search.ts
+/**
+* `adr search <query>… [--all] [--source <name>]` (design §8.2): words are joined, and every one
+* must match. `--source` searches a `[[sources]]` entry's cached log instead of the local one.
+*/
+const searchCommand = {
+	name: "search",
+	summary: "search decisions' ids, titles, bodies and notes",
+	usage: "search <query>… [--all] [--source <name>]",
+	options: {
+		all: { type: "boolean" },
+		source: { type: "string" }
+	},
+	positionals: {
+		min: 1,
+		max: 20,
+		names: ["query"]
+	},
+	ref: "read",
+	async run({ io, flags, values, positionals }) {
+		const log = await openForCli(io, flags);
+		const read = typeof values.source === "string" ? await readSourceDecisions(log, values.source) : await readDecisions(log);
+		const doc = searchDecisions(read, {
+			query: positionals.join(" "),
+			includeInactive: values.all === true
+		});
+		const notes = [...notesWith(doc.notes, numberingNote(read, { unavailable: false }))];
+		if (doc.inactive_omitted > 0) {
+			const k = doc.inactive_omitted;
+			notes.push(`${k === 1 ? "1 inactive decision also matches" : `${k} inactive decisions also match`}; add --all to see them`);
+		}
+		return {
+			exit: 0,
+			json: doc,
+			text: searchText(doc),
+			notes
+		};
+	}
+};
 // src/cli/show.ts
 /** `adr show <decision> [--history]` (design §5.6). */
 const showCommand = {
@@ -1185,17 +1325,34 @@ const withdrawCommand = {
 * ledger's shared `verify`: the log as the mode reads it (the index for `--staged`, else the
 * `--ref` tree or the work tree), every phase-1 check, and `[verify] fail_on`.
 */
-const verify = verifyCommand({ async open({ io, flags, mode }) {
+const verify = verifyCommand({ async open({ io, flags, mode, fetchSources }) {
 	const log = await openForCli(io, flags, { reader: mode.type === "staged" ? "index" : "worktree" });
+	const sources = await readDecisionSources(log, { fetch: fetchSources ? "network" : "cache" });
 	return {
 		git: log.git,
 		kind: adrKind,
 		layout: log.layout,
-		checks: adrChecks(log, await templateHistoryRef(log.git, mode)),
+		checks: adrChecks(log, await templateHistoryRef(log.git, mode), sources),
 		failOn: log.adr.failOn,
-		notes: log.notes
+		notes: [...log.notes, ...sources.notes],
+		widenOn: decisionVerifyInputs(log),
+		...(log.config?.sources ?? []).length === 0 ? {} : { sources: sources.statuses }
 	};
 } });
+/** ledger's shared `sources fetch`, over the `kind = "adr"` entries of `[[sources]]`. */
+const sources = sourcesCommand({
+	format: "adr-sources/v1",
+	tool: "adr",
+	async open({ io, flags }) {
+		const log = await openForCli(io, flags);
+		return {
+			git: log.git,
+			...decisionSourceConfigs(log),
+			configPath: log.configPath,
+			notes: log.notes
+		};
+	}
+});
 /** The `adr` tool: its commands, for ledger's `runCli`. */
 function adrCli(version) {
 	return {
@@ -1203,7 +1360,7 @@ function adrCli(version) {
 		version,
 		summary: "Architecture decision records kept as event logs in git.",
 		commands: [
-			initCommand,
+			initCommand(version),
 			newCommand,
 			acceptCommand,
 			rejectCommand,
@@ -1218,7 +1375,10 @@ function adrCli(version) {
 			forCommand,
 			listCommand,
 			showCommand,
-			verify
+			searchCommand,
+			verify,
+			sources,
+			mcpCommand(version)
 		]
 	};
 }