@nikovirtala/adr 0.2.0 → 0.4.0

package/dist/types/log.d.ts

@@ -32,9 +32,18 @@ export interface DecisionsRead {
     readonly findings: readonly Finding[];
     /** How the log was located (`ToolLog.notes`); `[]` for a MemoryTree read. */
     readonly notes: readonly string[];
+    /** The `[[sources]]` names in the config; their logs aren't read yet (ark's step 4). */
+    readonly sources: readonly string[];
 }
-/** `numberLog` on the repository, then `readDecisionsFrom(log.tree, …)`. */
+/**
+ * `numberLog` on the repository, then `readDecisionsFrom(log.tree, …)`. In a shallow clone of a
+ * log with `[log] index = "committed"`, the numbers come from `<root>/index.md` in the commit
+ * being read (`--ref`, else HEAD, resolved when the numbers are needed), never from the work tree's
+ * copy, which may number acceptances that exist only there (design 2b D1, §4.6).
+ */
 export declare function readDecisions(log: DecisionLog): Promise<DecisionsRead>;
+/** The display numbers `readDecisions` uses, with its shallow-clone fallback to `index.md`. */
+export declare function numberDecisions(log: DecisionLog): Promise<Numbering>;
 /** The git-free core of `readDecisions`; tests pass a MemoryTree and a hand-made `Numbering`. */
 export declare function readDecisionsFrom(tree: TreeReader, o: {
     readonly layout: LogLayout;
@@ -43,7 +52,22 @@ export declare function readDecisionsFrom(tree: TreeReader, o: {
     readonly ref?: string | null;
     readonly commit?: string | null;
     readonly notes?: readonly string[];
+    readonly sources?: readonly string[];
 }): Promise<DecisionsRead>;
+/**
+ * The note listing reads add while only the local log is read: the logs of `[[sources]]` aren't
+ * listed or searched until ark's step 4. `null` without sources.
+ */
+export declare function sourcesNote(read: DecisionsRead): string | null;
+/** `read.notes`, then the sources note when there is one. */
+export declare function listingNotes(read: DecisionsRead): readonly string[];
+/**
+ * The note a read command adds about where numbers come from: the shallow-clone index, or why
+ * they are unavailable (`unavailable: false` leaves that one out); `null` for none.
+ */
+export declare function numberingNote(read: DecisionsRead, o: {
+    readonly unavailable: boolean;
+}): string | null;
 /** Why numbers are unavailable, in words: `shallow clone` or `no main branch`. */
 export declare function unavailableReason(n: Numbering): string;
 /**
@@ -51,3 +75,22 @@ export declare function unavailableReason(n: Numbering): string;
  * Throws `UsageError` (exit 2) naming the reason when it names nothing.
  */
 export declare function resolveDecision(read: DecisionsRead, input: string): string;
+/** The `since` key of `adr list --since <rev>` (design 2b D7). */
+export interface ChangedSince {
+    /** The revision as given, such as `ORIG_HEAD`. */
+    readonly rev: string;
+    readonly commit: string;
+    /** Event files added since `rev`, sorted by path. */
+    readonly events: readonly {
+        readonly subject: string;
+        readonly type: string;
+        readonly path: string;
+    }[];
+}
+/**
+ * The event files in `--ref`'s tree (else HEAD's) that `rev`'s tree lacks (design 2b D7). Diffing
+ * trees answers "what did this pull bring" for fast-forwards and merges (`ORIG_HEAD` is the tip
+ * before them), and lists nothing for a rebase of your own work, whose events are in both trees.
+ * Throws `RefNotFoundError` when either revision doesn't resolve.
+ */
+export declare function changedSince(log: DecisionLog, rev: string): Promise<ChangedSince>;

package/dist/types/mcp/policy.d.ts

@@ -0,0 +1,33 @@
+import type { Actor, Finding } from "@nikovirtala/ledger";
+import type { AdrConfig } from "../config.js";
+import { type DecisionView } from "../kind.js";
+import type { DecisionsRead } from "../log.js";
+/** The tools that decide; listed only with `[policy] mcp_can_decide = true`. */
+export declare const DECISION_TOOLS: readonly ["adr_accept", "adr_reject", "adr_deprecate", "adr_supersede"];
+/** Whether `adr mcp` offers the decision tools (design §7.5, Table A). */
+export declare function decisionToolsAvailable(adr: AdrConfig): boolean;
+/**
+ * Who a proposal is for (design D5): its `proposed` event's actor, `on_behalf_of` for an agent
+ * and `email` for a human, lower-cased; `null` when the event or the address is missing.
+ */
+export declare function proposalOwner(read: DecisionsRead, id: string): string | null;
+/** The writes `mcpWriteRefusal` judges: the ones whose ownership matters. */
+export type PolicyTool = "adr_scope" | "adr_update_draft" | "adr_withdraw";
+/**
+ * The MCP policy (design §7.5, Table B): `null` when the write may go ahead, else the
+ * `decision/mcp-cannot-decide` finding. Without `mcp_can_decide` an agent may scope, edit and
+ * withdraw only the proposals made for the person it acts for, and rescope no accepted or
+ * deprecated decision.
+ * Writes the state machine forbids anyway get `null`, so the library refuses them with the real
+ * reason.
+ */
+export declare function mcpWriteRefusal(o: {
+    readonly tool: PolicyTool;
+    readonly view: DecisionView;
+    readonly owner: string | null;
+    readonly actor: Actor;
+    readonly mcpCanDecide: boolean;
+    readonly display: (id: string) => string;
+    /** The finding's file when the decision has no body: its events directory. */
+    readonly eventsDir: string;
+}): Finding | null;

package/dist/types/mcp/prompt.d.ts

@@ -0,0 +1,7 @@
+import type { McpPrompt } from "@nikovirtala/ledger/mcp";
+import { type AdrMcpEnv } from "./tools.js";
+/**
+ * `adr_draft_from_discussion` (design §7.8): the steps from a discussion to a proposal, with the
+ * template's sections spelled out, ending with a human's `adr accept`.
+ */
+export declare function draftPrompt(e: AdrMcpEnv): McpPrompt;

package/dist/types/mcp/resources.d.ts

@@ -0,0 +1,16 @@
+import type { McpResource, McpResourceTemplate } from "@nikovirtala/ledger/mcp";
+import { type DecisionsRead } from "../log.js";
+import { type AdrMcpEnv } from "./tools.js";
+/**
+ * Where an MCP client reads a decision: `adr://decision/ADR-0012` when numbered, else
+ * `adr://decision/<id>`. The `refer` of every header the MCP texts show.
+ */
+export declare function decisionUri(read: DecisionsRead): (id: string) => string;
+/** `adr://index`: the index table, numbered like every other read (design §7.7). */
+export declare function indexResource(e: AdrMcpEnv): McpResource;
+/**
+ * `adr://decision/{id}`: the decision's state header, then its body. `{id}` is the id, the number
+ * (`12`, `0012`) or `ADR-0012`; an unknown one is not found, a malformed or qualified one is the
+ * caller's error.
+ */
+export declare function decisionResource(e: AdrMcpEnv): McpResourceTemplate;

package/dist/types/mcp/server.d.ts

@@ -0,0 +1,16 @@
+import { type McpServeOptions } from "@nikovirtala/ledger/mcp";
+export declare const INSTRUCTIONS = "Architecture decisions in this repository are managed by adr. Decision files don't show their status: read decisions with adr_get or adr://decision/{id}, check adr_for_path and adr_search before changing architecture, and propose changes with adr_propose; a human accepts them.";
+/**
+ * `adr mcp` (design §7.2): checks `ARK_ON_BEHALF_OF` and opens the log first, so a bad
+ * environment exits 2 before serving, then serves adr's tools over stdio until the client goes.
+ */
+export declare function serveAdrMcp(o: {
+    readonly cwd: string;
+    readonly root: string | null;
+    readonly env: NodeJS.ProcessEnv;
+    readonly version: string;
+    readonly stderr: {
+        write(s: string): void;
+    };
+    readonly transport?: McpServeOptions["transport"];
+}): Promise<void>;

package/dist/types/mcp/text.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The readable text of each MCP tool result (design §7.4, last column). The documents are the
+ * CLI's; these texts are MCP's own, and their state headers point at `adr://decision/…`.
+ */
+import { type StateHeader } from "@nikovirtala/ledger";
+import type { McpToolResult } from "@nikovirtala/ledger/mcp";
+import type { DecisionView } from "../kind.js";
+import type { DecisionsRead } from "../log.js";
+import type { DecisionsForJson } from "../scope.js";
+import type { DecisionSearchJson } from "../search.js";
+import type { TemplatesJson } from "../templates/list.js";
+import { type DecisionListJson, type DecisionShowJson } from "../views.js";
+import type { WriteResultJson } from "../write.js";
+type Text = Omit<McpToolResult, "document">;
+/** The decision's state header with MCP's `adr://` references. */
+export declare function mcpHeader(view: DecisionView, read: DecisionsRead): StateHeader;
+/** `adr_search`: each result's header, title and excerpt, then the counts. */
+export declare function searchText(doc: DecisionSearchJson, read: DecisionsRead): Text;
+/** `adr_get`: the header, the decision's fields as `adr show` lists them, then the body. */
+export declare function getText(doc: DecisionShowJson, read: DecisionsRead): Text;
+/** `adr_list`: one line per decision. */
+export declare function listText(doc: DecisionListJson, read: DecisionsRead): Text;
+/** `adr_templates`: each template, then its sections. */
+export declare function templatesText(doc: TemplatesJson): Text;
+/** `adr_for_path`: per path, each decision's header and how it matched. */
+export declare function forText(doc: DecisionsForJson, read: DecisionsRead): Text;
+/** What a write's text needs besides the document. */
+export interface WriteTextOptions {
+    /** The log read after the write, for the headers and how decisions display. */
+    readonly read: DecisionsRead;
+    /** For `adr_propose`: whether a human must accept. */
+    readonly acceptRequiresHuman?: boolean;
+    /** For `adr_scope`: the globs before the write. */
+    readonly scopeBefore?: readonly string[];
+    /** For `adr_update_draft`: the section ids sent. */
+    readonly sections?: readonly string[];
+    /** The tool, for the refusal's last line. */
+    readonly tool: string;
+}
+/** A write's text: `Refused:` and the findings, or what was written; then the notes. */
+export declare function writeText(doc: WriteResultJson, o: WriteTextOptions): Text;
+export {};

package/dist/types/mcp/tools.d.ts

@@ -0,0 +1,27 @@
+import { type JsonValue } from "@nikovirtala/ledger";
+import { type McpTool } from "@nikovirtala/ledger/mcp";
+import { type DecisionLog } from "../log.js";
+/** Where `adr mcp` runs: every call opens the log afresh from here (design D2). */
+export interface AdrMcpEnv {
+    readonly cwd: string;
+    readonly root: string | null;
+    readonly env: NodeJS.ProcessEnv;
+}
+type Schema = Readonly<Record<string, JsonValue>>;
+export declare const ID: Schema;
+export declare const READ: {
+    readonly readOnlyHint: true;
+    readonly openWorldHint: false;
+};
+export declare const WRITE: {
+    readonly readOnlyHint: false;
+    readonly destructiveHint: false;
+    readonly openWorldHint: false;
+};
+/** The log for one call, opened again so outside edits and `[policy]` changes are seen. */
+export declare const openLog: (e: AdrMcpEnv, ref?: string | null) => Promise<DecisionLog>;
+/** The eleven tools `adr mcp` always lists (design §7.4). */
+export declare function alwaysOnTools(e: AdrMcpEnv): McpTool[];
+/** The four tools `adr mcp` lists only with `[policy] mcp_can_decide = true` (design §7.4). */
+export declare function decisionTools(e: AdrMcpEnv): McpTool[];
+export {};

package/dist/types/scope.d.ts

@@ -1,6 +1,6 @@
 import { type Finding, type ScopeVia } from "@nikovirtala/ledger";
 import type { DecisionStatus } from "./kind.js";
-import type { DecisionLog, DecisionsRead } from "./log.js";
+import { type DecisionLog, type DecisionsRead } from "./log.js";
 import { type NumberingJson } from "./views.js";
 /** One decision that governs a path in `adr-for/v1` (design §6.9). */
 export interface DecisionForJson {
@@ -39,6 +39,8 @@ export interface DecisionsForJson {
     readonly findings: readonly Finding[];
     readonly notes: readonly string[];
 }
+/** The order `adr for` and `adr search` list statuses in: in force first. */
+export declare const STATUS_ORDER: readonly DecisionStatus[];
 /**
  * Which decisions govern each path (design §6.9): globs of decisions that were ever in force, and
  * comment anchors of any decision, read from the work tree or, with a `--ref` log, that commit.

package/dist/types/search.d.ts

@@ -0,0 +1,61 @@
+import { type Finding, type StateHeader } from "@nikovirtala/ledger";
+import type { DecisionView } from "./kind.js";
+import { type DecisionsRead } from "./log.js";
+import { type NumberingJson } from "./views.js";
+export type SearchField = "id" | "title" | "body" | "notes";
+/** One decision `adr search` found. */
+export interface DecisionSearchResultJson {
+    readonly decision: DecisionView;
+    /** `stateHeader(view, read)`: the CLI's wording. */
+    readonly header: StateHeader;
+    readonly score: number;
+    /** The fields with a hit, in the order id, title, body, notes (the display number is `id`). */
+    readonly matched: readonly SearchField[];
+    /** The best matching line of the body or a note, cut to about 160 characters; `null` if none. */
+    readonly excerpt: string | null;
+}
+/** `adr search <query>… --json` and `adr_search` (design §6.4). */
+export interface DecisionSearchJson {
+    readonly format: "adr-search/v1";
+    readonly root: string;
+    readonly ref: string | null;
+    readonly commit: string | null;
+    readonly numbering: NumberingJson;
+    /** As given, trimmed. */
+    readonly query: string;
+    /** Folded, deduplicated, in query order. */
+    readonly terms: readonly string[];
+    readonly include_inactive: boolean;
+    /** Matching decisions before `limit`. */
+    readonly total: number;
+    /** Decisions that match but aren't active; `0` with `include_inactive`. */
+    readonly inactive_omitted: number;
+    readonly results: readonly DecisionSearchResultJson[];
+    /** The read's findings of the listed decisions and of the log as a whole. */
+    readonly findings: readonly Finding[];
+    /** `read.notes`, then the sources note. */
+    readonly notes: readonly string[];
+}
+/** A folded string and, for every folded UTF-16 offset (and its end), the original offset. */
+interface Folded {
+    readonly text: string;
+    readonly at: readonly number[];
+}
+/**
+ * Case- and accent-insensitive form: per code point NFKD, combining marks dropped, lower-cased.
+ * `Café` → `cafe` and `fi` → `fi`; `ß` and `ø` have no decomposition and stay as they are.
+ */
+export declare function fold(s: string): Folded;
+/**
+ * Full-text search of the log (design §8.1): a decision matches when every term of the folded
+ * query is a substring of its folded id, display number, title, body or note texts. Ranked by
+ * score (10 for a term equal to the id or number, 5 in the title, up to 3 for body hits and 2
+ * for note hits), then status as `adr for` orders them, then list order. Only proposed and
+ * accepted decisions unless `includeInactive`. Throws `UsageError` for an invalid query.
+ */
+export declare function searchDecisions(read: DecisionsRead, o: {
+    readonly query: string;
+    readonly includeInactive?: boolean;
+    readonly limit?: number;
+}): DecisionSearchJson;
+export {};

package/dist/types/skill.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The agent skill `adr init --skill` writes (01, "Agent skill (SKILL.md)"): the judgment of when
+ * to use adr's MCP tools. `skill.test.ts` keeps it equal to the block in docs/01-adr-v1.md.
+ */
+export declare const SKILL_MD = "---\nname: adr\ndescription: Use before changing architecture, data stores, integration patterns, dependencies or cross-cutting conventions, and whenever asked to record, propose or look up an architectural decision.\n---\n\n# Architectural decisions (adr)\n\nDecisions in this repo are managed by adr. Decision files do not\nshow their own status, so never judge from the raw files whether a\ndecision applies.\n\n## Before changing architecture\n\n1. Call adr_for_path for the files you will touch, and adr_search\n   for the area you are about to change. adr_search returns active\n   decisions only; adr_for_path also lists inactive ones, each with\n   a warning.\n2. If your change conflicts with an accepted decision, stop and tell\n   the user which ADR it conflicts with. Do not work around it silently.\n3. If the user still wants the change, propose a superseding ADR.\n\n## Reading decisions\n\n- Use adr_get or adr://decision/{id}, never docs/adr/decisions/*.md.\n- If a response says SUPERSEDED or DEPRECATED, follow it to the\n  effective decision before acting.\n- If it says REJECTED or WITHDRAWN, the decision was never in force;\n  do not apply it.\n\n## Proposing decisions\n\n1. Call adr_templates and fill every required section.\n2. Use only facts from the conversation and the code. Mark unknowns\n   as open questions instead of inventing them.\n3. List at least two options considered when the template has that section.\n4. Set supersedes when the proposal replaces an existing decision.\n5. Do not accept your own proposal. Tell the user the ADR id and\n   that they can review it and run: adr accept <id>\n6. If the user decides against your proposal, withdraw it with\n   adr_withdraw and give their reason. Don't withdraw other\n   people's proposals; tell the user instead.\n\n## Changing scope\n\n- When you move or rename code covered by a decision, let the\n  pre-commit hook update its globs (adr hooks install). For your\n  own proposals, you can use adr_scope. Rescoping an accepted\n  decision needs mcp_can_decide; otherwise tell the user and\n  suggest adr scope <id> \u2026.\n- Before any scope change, read the decision's Scope section. If it\n  would no longer read true after the change, do not rescope: tell\n  the user the decision itself is changing and propose a\n  superseding ADR.\n\n## Never\n\n- Edit an accepted decision body, any file under docs/adr/events/,\n  or index.md by hand.\n- Use adr_note to change the meaning of a decision. Notes clarify;\n  changed decisions need a superseding ADR.\n\n## Without the MCP server\n\nUse the CLI with --json: adr search, adr for, adr show, adr new,\nadr note. Set ARK_AGENT=<your name> and ARK_ON_BEHALF_OF=<the user's\nemail> so your writes are attributed.\n";

package/dist/types/templates/list.d.ts

@@ -0,0 +1,31 @@
+import { type Finding } from "@nikovirtala/ledger";
+import type { DecisionsRead } from "../log.js";
+/** `adr_templates` (and phase 4's `adr template list --json`): the templates a proposal can use. */
+export interface TemplatesJson {
+    readonly format: "adr-templates/v1";
+    readonly root: string;
+    /** `[log] default_template`. */
+    readonly default: string;
+    readonly templates: readonly {
+        readonly name: string;
+        readonly version: number;
+        readonly source: "repo" | "builtin";
+        /** `<root>/templates/<name>.md` for a repo template; `null` for a built-in one. */
+        readonly path: string | null;
+        readonly sections: readonly {
+            readonly id: string;
+            readonly heading: string;
+            readonly required: boolean;
+            readonly guidance: string | null;
+        }[];
+    }[];
+    /** Why a repo template is left out: it doesn't parse or fails the template lint. */
+    readonly findings: readonly Finding[];
+    readonly notes: readonly string[];
+}
+/**
+ * The templates of `<root>/templates` that parse and pass the template lint, and the built-in
+ * ones no repo template or file of the same name shadows (`adr new` copies those on first use),
+ * sorted by name.
+ */
+export declare function listTemplates(read: DecisionsRead): Promise<TemplatesJson>;

package/dist/types/verify.d.ts

@@ -1,9 +1,11 @@
 import { type Check, type Finding, type VerifyMode } from "@nikovirtala/ledger";
-import type { DecisionLog } from "./log.js";
+import { type DecisionLog } from "./log.js";
 /**
- * Every phase-1 check for the log: ledger's mechanical and fold checks with adr's actor policy,
- * and template lint against the templates in the head tree and, for older versions, the history
- * of `historyRef`.
+ * Every check for the log: ledger's mechanical and fold checks with adr's actor policy, template
+ * lint against the templates in the head tree and, for older versions, the history of
+ * `historyRef`, the scope-glob and anchor checks, and the decision checks over code
+ * (`decision/governed-by-inactive`, `decision/scope-narrowed`). With `[log] index = "committed"`,
+ * also the freshness of `<root>/index.md`.
  */
 export declare function adrChecks(log: DecisionLog, historyRef: string | null): readonly Check[];
 /** Verifies the decision log in `mode` (staged, range or full) with `adrChecks`. */

package/dist/types/views.d.ts

@@ -1,10 +1,10 @@
 import { type EventEnvelope, type Finding, type StateHeader } from "@nikovirtala/ledger";
 import type { DecisionStatus, DecisionView } from "./kind.js";
-import type { DecisionsRead } from "./log.js";
+import { type ChangedSince, type DecisionsRead } from "./log.js";
 /** The `numbering` key of the read documents. */
 export interface NumberingJson {
     readonly available: boolean;
-    readonly reason: "shallow" | "no-main-ref" | null;
+    readonly reason: "shallow" | "no-main-ref" | "index" | null;
     readonly ref: string | null;
 }
 /** `adr list --json` (design §5.5). */
@@ -15,6 +15,8 @@ export interface DecisionListJson {
     readonly commit: string | null;
     readonly numbering: NumberingJson;
     readonly decisions: readonly DecisionView[];
+    /** With `--since <rev>`: the event files added since `rev`; `null` without it. */
+    readonly since: ChangedSince | null;
     /** Newer envelope or schema versions; upgrade adr. */
     readonly unreadable: readonly string[];
     /** First event not `proposed`, or a body with no events; run adr verify. */
@@ -39,12 +41,16 @@ export interface DecisionShowJson {
 }
 /** The `numbering` key of `adr-list/v1`, `adr-show/v1` and `adr-for/v1`. */
 export declare const numberingJson: (read: DecisionsRead) => NumberingJson;
+/** Numbered decisions by number, then unnumbered ones by `proposed_at`, then id. */
+export declare function compareViews(a: DecisionView, b: DecisionView): number;
 /**
- * The `adr-list/v1` document: decisions in list order, filtered by `status` and truncated to
+ * The `adr-list/v1` document: decisions in list order, filtered by `status` and by `since` (only
+ * the decisions with event files added since its revision, from `changedSince`), and truncated to
  * `limit` after ordering. `findings` are those of the listed decisions and of the log as a whole.
  */
 export declare function listDecisions(read: DecisionsRead, o?: {
     readonly status?: readonly DecisionStatus[];
+    readonly since?: ChangedSince | null;
     readonly limit?: number;
 }): DecisionListJson;
 /**

package/dist/types/write.d.ts

@@ -1,15 +1,17 @@
-import { type Actor, type EventEnvelope, type Finding, type SetOp, type Template, type TemplateSource, type Trailer } from "@nikovirtala/ledger";
+import { type Actor, type EventEnvelope, type Finding, type SetOp, type Template, type TemplateSource, type Trailer, type TreeReader } from "@nikovirtala/ledger";
 import { type DecisionView } from "./kind.js";
 import { type DecisionLog, type DecisionsRead } from "./log.js";
 /** `adr <write command> --json` (design §5.5, §6.1). */
 export interface WriteResultJson {
     readonly format: "adr-write/v1";
-    readonly command: "new" | "accept" | "supersede" | "reject" | "withdraw" | "deprecate" | "note" | "link" | "scope";
+    readonly command: "new" | "accept" | "supersede" | "reject" | "withdraw" | "deprecate" | "note" | "link" | "scope" | "update";
     readonly ok: boolean;
     /**
      * The decision after the write; before it when `ok` is false (`null` for a refused `new`).
      * After a commit it is read again from the log, so an acceptance committed on the main ref
-     * carries its number; otherwise `number` is `null` until the acceptance lands on main.
+     * carries its number; otherwise `number` is `null` until the acceptance lands on main. In a
+     * shallow clone with a committed index, the number comes from HEAD's `index.md`, which on a
+     * branch is the number the decision will get once the branch merges.
      */
     readonly decision: DecisionView | null;
     /** Each decision superseded by this write, after it (read again after a commit, like `decision`). */
@@ -33,6 +35,11 @@ export interface WriteOptions {
     readonly message?: string | null;
     /** Notes to report before the write's own, such as the attribution notes. */
     readonly notes?: readonly string[];
+    /**
+     * With `[log] index = "committed"`: `"refresh"` (the default) keeps `<root>/index.md` fresh;
+     * `"skip"` leaves it alone (the pre-commit hook's rename following, design 2b D8).
+     */
+    readonly index?: "refresh" | "skip";
 }
 export interface ProposeInput {
     readonly title: string;
@@ -61,6 +68,14 @@ export interface WritePlan {
     readonly subject: string;
     /** New files, repo-relative path → bytes, in write order: body, materialized template, events. */
     readonly files: Readonly<Record<string, Uint8Array>>;
+    /**
+     * Existing files to replace, path → the new bytes and the bytes the plan read; written only if
+     * the file still holds `expected` (a draft update).
+     */
+    readonly replace?: Readonly<Record<string, {
+        readonly bytes: Uint8Array;
+        readonly expected: Uint8Array;
+    }>>;
     readonly events: readonly EventEnvelope[];
     /** Paths to stage: every new file, plus the existing body for accept. */
     readonly stage: readonly string[];
@@ -119,6 +134,21 @@ export type PlanResult = {
 export declare function planPropose(read: DecisionsRead, input: ProposeInput, c: PlanContext, o?: {
     readonly refuseIncomplete?: boolean;
 }): Promise<PlanResult>;
+/** Input of a draft update: the decision and the sections to replace (section id → markdown). */
+export interface UpdateDraftInput {
+    readonly id: string;
+    readonly sections: Readonly<Record<string, string>>;
+}
+/**
+ * Plans a draft update (design §6.6): the given sections of a proposed decision's body replaced in
+ * place, every other line kept, written only if the body still holds the bytes read. Refused
+ * (`ok: false`) when the decision isn't proposed or its body or template version is missing or
+ * unreadable, and with `refuseIncomplete` when the new draft fails its template lint. An unknown
+ * section, a missing heading or a heading in the content is a `UsageError`.
+ */
+export declare function planUpdateDraft(read: DecisionsRead, input: UpdateDraftInput, c: PlanContext, o?: {
+    readonly refuseIncomplete?: boolean;
+}): Promise<PlanResult>;
 /** Plans `adr accept`: `accepted` with the body hash, and `superseded` on each declared target. */
 export declare function planAccept(read: DecisionsRead, input: {
     readonly id: string;
@@ -229,10 +259,26 @@ export interface AfterStage {
     /** `false` skips the commit: the files stay written and staged, and `commit` is `null`. */
     readonly commit: boolean;
 }
+/** What `applyPlan` did. */
+export interface AppliedPlan {
+    /** Repo-relative paths written: the plan's files, then `<root>/index.md` when it was written. */
+    readonly written: string[];
+    readonly commit: string | null;
+    readonly findings: readonly Finding[];
+    /** Notes about the index ("not updated", "may be stale"); `[]` when none. */
+    readonly notes: readonly string[];
+}
+/**
+ * What the recovery hint says about rerunning a write command after `git commit` failed (design
+ * 2b D5): the batch is already in the log, so a rerun is refused, writes nothing or duplicates it.
+ */
+export declare const WRITE_RERUN = "Don't run the command again: the log already holds the change, so a rerun would be refused, do nothing, or write it a second time.";
 /**
  * Applies a plan (§5.4): refuses a commit whose scope has unstaged or needed untracked paths,
  * writes the files (removing them again if a write fails), stages them, runs `afterStage`, and
- * commits `plan.stage` plus the involved subjects' already-staged files with exact trailers.
+ * commits `plan.stage` plus the involved subjects' already-staged files with exact trailers. A
+ * failed `git commit` throws `CommitFailedError` with the manual command (design 2b D5) and the
+ * notes made so far.
  */
 export declare function applyPlan(log: DecisionLog, plan: WritePlan, o: {
     readonly commit: boolean;
@@ -241,11 +287,13 @@ export declare function applyPlan(log: DecisionLog, plan: WritePlan, o: {
     /** `message` is the user's own: append the trailers to its own trailer block, if it ends in one. */
     readonly mergeTrailers?: boolean;
     readonly afterStage?: () => Promise<AfterStage>;
-}): Promise<{
-    written: string[];
-    commit: string | null;
-    findings: readonly Finding[];
-}>;
+    /**
+     * Renders the log's index for `tree`, which builds on `history` (HEAD, the new commit, or
+     * null on an unborn HEAD); `null` when the numbers can't be projected. Given only when the log
+     * keeps a committed index (design 2b D2, §4.5).
+     */
+    readonly index?: (tree: TreeReader, history: string | null) => Promise<string | null>;
+}): Promise<AppliedPlan>;
 /**
  * The clock, the randomness and `applyPlan` the write functions use. Only tests pass their own
  * (for example an `apply` that fails once); the default is the real ones.
@@ -318,6 +366,14 @@ export declare function linkDecision(log: DecisionLog, input: LinkInput, o?: Wri
  * and commits with `commit`. An unchanged set writes nothing.
  */
 export declare function scopeDecision(log: DecisionLog, input: ScopeInput, o?: WriteOptions, deps?: WriteDeps): Promise<WriteResultJson>;
+/**
+ * Replaces sections of a proposed decision's draft (design §6.6), stages the body, and commits
+ * with `commit` (default `[policy] auto_commit`). A body with unstaged changes is a `UsageError`,
+ * so nobody's unsaved edit is folded into this write; a body changed between plan and write is
+ * `FileChangedError`. A commit is never made of a draft that fails its template lint: it is
+ * refused (`ok: false`, nothing written), as for `proposeDecision` without an editor.
+ */
+export declare function updateDraft(log: DecisionLog, input: UpdateDraftInput, o?: WriteOptions, deps?: WriteDeps): Promise<WriteResultJson>;
 /**
  * `adr scope [<decision>] --follow-renames` (design §6.8): rewrites the scope globs of the given
  * decision, or of every decision, after the renames staged against `HEAD`, and stages one

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nikovirtala/adr",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Architecture decision records kept as event logs in git: frozen bodies, computed status and supersession chains. CLI and library.",
   "keywords": [
     "adr",
@@ -45,7 +45,10 @@
     "provenance": true
   },
   "dependencies": {
-    "@nikovirtala/ledger": "^0.4.0"
+    "@nikovirtala/ledger": "^0.6.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "1.32.2"
   },
   "scripts": {
     "build": "tsdown",