Ledger corrections: fix a record's wording while it keeps its id

.docket/ledger.jsonl

@@ -127,3 +127,4 @@
 {"schema":2,"kind":"decision","id":"d127","text":"Question-shaped decision headlines get rewritten in place, not superseded.","state":"adopted","ts":"2026-09-23T08:04:09+00:00","author":"claude-code","session":"","branch":"main","scope":[".docket/ledger.jsonl","scripts/declarative_ledger.py"],"rationale":"Superseding would retire all 81, and 36 records declare support or prerequisites through them, so each would lose its grounds.","supports":[],"depends_on":[],"answers":[],"supersedes":[],"evidence":[],"revisit":"","cost_if_wrong":"Any revision token held before the rewrite goes stale and falls back to a full briefing; the old headlines survive only in the backup and git history.","pinned":false,"choice":"A one-off script rewrites the text field of the 81 question-shaped decisions in place, after writing a backup beside the ledger. Ids, relations, choice, and provenance stay unchanged.","alternatives":["Supersede each decision with a declarative restatement."],"decided_by":""}
 {"schema":2,"kind":"decision","id":"d128","text":"Ledger records accept field-level corrections that keep the record's id.","state":"adopted","ts":"2026-09-23T08:17:31+00:00","author":"claude-code","session":"","branch":"main","scope":["docket/**","docs/ledger.md"],"rationale":"Supersession changes the id, so records that support, depend on, or cite the old id point at a retired record. d88 restating d38 left d39 on stale support. Three one-off scripts already rewrote history in place with no trail.","supports":[],"depends_on":[],"answers":[],"supersedes":["d89"],"evidence":[],"revisit":"","cost_if_wrong":"A new line kind changes the ledger format, the projection every reader uses, and the revision hash.","pinned":false,"choice":"A correction is its own ledger line, addressed as <id>.<n>, that changes wording and metadata of an earlier record: text, rationale, scope, cost, evidence, revisit. Relations, state, kind, and provenance stay fixed; changing those still goes through supersession.","alternatives":["Supersede a mis-recorded record with a restatement.","Add a restatement flag to supersession that moves inbound links to the new record."],"decided_by":""}
 {"schema":2,"kind":"decision","id":"d129","text":"Corrections are ledger lines that project() folds into the corrected record.","state":"adopted","ts":"2026-09-23T08:20:41+00:00","author":"claude-code","session":"","branch":"main","scope":["docket/ledger.py","docket/rebase.py","docket/context_delta.py","docket/cli/admin.py"],"rationale":"project() already runs after any history slice, so show --at and --since see only earlier corrections without their own change. A side file doubles merge, rebase, and hashing; folding in read() hides the original lines from rebase and check.","supports":[["d128"]],"depends_on":[],"answers":[],"supersedes":[],"evidence":[],"revisit":"","cost_if_wrong":"Every raw-line reader must accept a fourth line kind, and older docket releases refuse a ledger holding one.","pinned":false,"choice":"A correction line (kind correction, id <target>.<n>) names one earlier record and a fields object of replacement values. project() applies corrections in file order, drops the lines, and adds corrections and original to the record. choice stays fixed; alternatives, decided_by, and pinned join the correctable fields.","alternatives":["A side file, .docket/corrections.jsonl, like the feature store.","Fold corrections inside read(), so raw consumers never see a correction line."],"decided_by":""}
+{"schema":2,"kind":"decision","id":"d130","text":"A correction appended with its id already set skips the write-time refusals.","state":"adopted","ts":"2026-09-23T09:15:42+00:00","author":"claude-code","session":"","branch":"feat/ledger-corrections","scope":["docket/ledger.py","docket/corrections.py","docket/rebase.py"],"rationale":"A correction valid on its own branch can be refused against the other branch's corrected state, which leaves a rebase half-applied.","supports":[["d129"]],"depends_on":[],"answers":[],"supersedes":[],"evidence":[],"revisit":"","cost_if_wrong":"A hand-written numbered correction line bypasses the refusals; validation still bounds its fields.","pinned":false,"choice":"append runs the no-op drop and the echo and question-text refusals only for a correction the CLI submits unnumbered. A pre-numbered correction, as rebase appends, passes on validation alone, the same as a pre-numbered record.","alternatives":["Run the refusals on every appended correction, including rebased ones."],"decided_by":""}

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `docket correct` fixes a record's wording or metadata while it keeps its id. Corrections are ledger lines, `docket show` lists them, and briefings tag corrected records. A ledger that holds a correction needs this release or later to read.
+
 ### Changed
 
 - `docket claim` and `docket decision` refuse a text that ends in `?`. A

docket/cli/__init__.py

@@ -8,6 +8,7 @@
 from docket.cli.completion import cmd_completion
 from docket.cli.construct import cmd_construct
 from docket.cli.context_cmd import CONTEXT_ENVELOPES, cmd_context
+from docket.cli.correct import add_correct_parser
 from docket.cli.feature_parser import add_feature_parser
 from docket.cli.graph import cmd_graph
 from docket.cli.query import cmd_list, cmd_show, cmd_where
@@ -53,7 +54,7 @@ def main(argv: list[str] | None = None) -> int:
     sub = p.add_subparsers(
         dest="cmd",
         metavar=(
-            "{claim,decision,question,list,show,graph,context,where,check,"
+            "{claim,decision,question,correct,list,show,graph,context,where,check,"
             "rebase,migrate,init,feature,completion,update}"
         ),
     )
@@ -78,6 +79,8 @@ def main(argv: list[str] | None = None) -> int:
     _add_shared_args(qu)
     qu.set_defaults(func=cmd_question)
 
+    add_correct_parser(sub)
+
     ls = sub.add_parser("list", help="list records")
     ls.add_argument("--kind", choices=KINDS)
     ls.add_argument(

docket/cli/admin.py

@@ -142,7 +142,8 @@ def cmd_check(args: argparse.Namespace) -> int:
     prefix = _Prefix([])
     seen: dict[str, int] = {}
     highest = 0
-    count = 0
+    records = 0
+    correction_lines = 0
     for number, line in enumerate(lines, 1):
         if not line.strip():
             continue
@@ -151,7 +152,18 @@ def cmd_check(args: argparse.Namespace) -> int:
         except json.JSONDecodeError as exc:
             faults.append(f"line {number}: invalid JSON: {exc.msg}")
             continue
-        count += 1
+        if isinstance(record, dict) and record.get("kind") == "correction":
+            correction_lines += 1
+            # Kept out of seen: a feature that names a correction id names
+            # nothing a brief can attach, and the feature check reports it.
+            try:
+                checked = validate_record(record, prefix=prefix)
+            except LedgerError as exc:
+                faults.append(f"line {number}: {str(exc).removeprefix('docket: ')}")
+            else:
+                prefix.add(checked)
+            continue
+        records += 1
         ident = str(record.get("id", "")) if isinstance(record, dict) else ""
         match = ID_RE.fullmatch(ident)
         if not match:
@@ -180,7 +192,10 @@ def cmd_check(args: argparse.Namespace) -> int:
 
     failed = bool(faults)
     if not faults:
-        print(f"docket: {path} reads cleanly, {count} record{'s' if count != 1 else ''}")
+        summary = f"{records} record{'s' if records != 1 else ''}"
+        if correction_lines:
+            summary += f" and {correction_lines} correction{'s' if correction_lines != 1 else ''}"
+        print(f"docket: {path} reads cleanly, {summary}")
     else:
         print(f"docket: {path} has {len(faults)} fault{'s' if len(faults) != 1 else ''}")
         for fault in faults:

docket/cli/completion.py

@@ -52,6 +52,7 @@
     "claim",
     "decision",
     "question",
+    "correct",
     "list",
     "show",
     "graph",

docket/cli/context_cmd.py

@@ -148,6 +148,7 @@ def cmd_context(args: argparse.Namespace) -> int:
             projected,
             since=args.since,
             baseline=project(prefix),
+            raw=raw,
             max_chars=args.max_chars,
             ledger=str(env.ledger_path()),
             settings=settings,
@@ -168,7 +169,8 @@ def cmd_context(args: argparse.Namespace) -> int:
     if forced or default_on:
         files = tuple(dict.fromkeys(files + auto_scope_files(settings["auto_scope"]["limit"])))
     try:
-        entries = project(read(env.ledger_path()), validated=True)
+        raw = read(env.ledger_path())
+        entries = project(raw, validated=True)
         text = render_context(
             entries,
             query=args.query or "",
@@ -179,6 +181,7 @@ def cmd_context(args: argparse.Namespace) -> int:
             settings=settings,
             settings_id=settings_id,
             feature=_feature_block(env.project_root(), entries),
+            latest_id=raw[-1]["id"] if raw else "",
         )
     except (LedgerError, OSError) as exc:
         print(str(exc), file=sys.stderr)

docket/cli/correct.py

@@ -0,0 +1,104 @@
+import argparse
+import sys
+
+from docket import corrections, env
+from docket.ledger import ID_RE, LedgerError, append, parse_evidence
+
+# Flags that change what a record commits to. Accepted by the parser only so
+# the refusal can name supersession instead of argparse's generic error.
+FIXED_FLAGS = {
+    "choice": "--choice",
+    "state": "--state",
+    "supports": "--supports",
+    "depends_on": "--depends-on",
+    "answers": "--answers",
+    "supersedes": "--supersedes",
+}
+CLEARABLE = ("scope", "evidence", "alternatives")
+CLEAR_FLAGS = {"scope": "--scope", "evidence": "--evidence", "alternatives": "--alternative"}
+
+
+def _fields(args: argparse.Namespace) -> dict:
+    fields: dict = {}
+    if args.text is not None:
+        fields["text"] = args.text
+    if args.rationale is not None:
+        fields["rationale"] = args.rationale
+    if args.scope:
+        fields["scope"] = args.scope
+    if args.evidence:
+        fields["evidence"] = [parse_evidence(item) for item in args.evidence]
+    if args.revisit is not None:
+        fields["revisit"] = args.revisit
+    if args.cost is not None:
+        fields["cost_if_wrong"] = args.cost
+    if args.pin:
+        fields["pinned"] = True
+    if args.unpin:
+        fields["pinned"] = False
+    if args.alternative:
+        fields["alternatives"] = args.alternative
+    if args.decided_by is not None:
+        fields["decided_by"] = args.decided_by
+    for name in args.clear:
+        if name in fields:
+            raise LedgerError(f"docket: --clear {name} and {CLEAR_FLAGS[name]} conflict")
+        fields[name] = []
+    return fields
+
+
+def cmd_correct(args: argparse.Namespace) -> int:
+    if not ID_RE.fullmatch(args.id):
+        print("docket: correct names a claim, decision, or question id", file=sys.stderr)
+        return 1
+    fixed = [flag for dest, flag in FIXED_FLAGS.items() if getattr(args, dest) is not None]
+    if fixed:
+        print(
+            f"docket: a correction cannot change {', '.join(fixed)}; record a "
+            f"restatement with --supersedes {args.id} instead",
+            file=sys.stderr,
+        )
+        return 1
+    try:
+        fields = _fields(args)
+        if not fields:
+            raise LedgerError("docket: name at least one field to correct")
+        entry = append(
+            env.ledger_path(),
+            corrections.make(
+                args.id,
+                fields,
+                reason=args.reason,
+                author=env.resolved_author(),
+                session=env.session_id(),
+                branch=env.branch(env.project_root()),
+            ),
+        )
+    except (LedgerError, OSError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    print(f"{entry['id']}  corrects {entry['corrects']}: {', '.join(sorted(fields))}")
+    return 0
+
+
+def add_correct_parser(sub) -> None:
+    co = sub.add_parser("correct", help="fix a record's wording or metadata, keeping its id")
+    co.add_argument("id", help="the claim, decision, or question to correct")
+    co.add_argument("--text")
+    co.add_argument("--rationale")
+    co.add_argument("--scope", action="append", default=[])
+    co.add_argument("--evidence", action="append", default=[])
+    co.add_argument("--revisit")
+    co.add_argument("--cost")
+    pin = co.add_mutually_exclusive_group()
+    pin.add_argument("--pin", action="store_true")
+    pin.add_argument("--unpin", action="store_true")
+    co.add_argument("--alternative", action="append", default=[])
+    co.add_argument("--decided-by")
+    co.add_argument(
+        "--clear", action="append", default=[], choices=CLEARABLE, help="set a list field to empty"
+    )
+    co.add_argument("--reason", default="", help="why the record was wrong")
+    for dest, flag in FIXED_FLAGS.items():
+        co.add_argument(flag, dest=dest, help=argparse.SUPPRESS)
+    co.set_defaults(func=cmd_correct)

docket/cli/query.py

@@ -12,7 +12,7 @@
 import sys
 import textwrap
 
-from docket import env
+from docket import corrections, env
 from docket.cli.term import _DIM, _STATE_COLOR, _c, _match, _use_color
 from docket.context_model import positions
 from docket.env import LEDGER, justification_sets, read, retired_by
@@ -110,6 +110,8 @@ def cmd_show(args: argparse.Namespace) -> int:
         at = positions(raw)
         cutoff = at[args.at]
         raw = [item for item in raw if at[item["id"]] <= cutoff]
+    if corrections.split_id(args.id):
+        return _show_correction(raw, args.id, args.json)
     entries = project(raw, validated=True)
     by_id = {e.get("id"): e for e in entries}
     e = by_id.get(args.id)
@@ -163,13 +165,39 @@ def field(label: str, value: str) -> None:
         field("Decided by", e["decided_by"])
     if e.get("cost_if_wrong"):
         field("Cost if wrong", e["cost_if_wrong"])
+    if e.get("corrections"):
+        field("Corrections", ", ".join(e["corrections"]))
     field("Recorded state", e.get("recorded_state", e.get("state", "")))
+    print(f"  Recorded: {e.get('ts', '')}")
     print(
         f"  Author: {e.get('author', '')}  Session: {e.get('session', '')}  Branch: {e.get('branch', '')}"
     )
     return 0
 
 
+def _show_correction(raw: list, ident: str, as_json: bool) -> int:
+    at = next((index for index, item in enumerate(raw) if item["id"] == ident), None)
+    if at is None:
+        print(f"docket: no entry {ident}", file=sys.stderr)
+        return 1
+    line = raw[at]
+    target = next(i for i in corrections.fold(raw[:at]) if i["id"] == line["corrects"])
+    before = {field: target.get(field) for field in line["fields"]}
+    if as_json:
+        print(json.dumps({**line, "before": before}, indent=2))
+        return 0
+    print(f"{ident}  correction  corrects {line['corrects']}")
+    for field, value in line["fields"].items():
+        print(f"  {field}: {json.dumps(before[field])} -> {json.dumps(value)}")
+    if line["reason"]:
+        print(f"  Reason: {line['reason']}")
+    print(
+        f"  Author: {line['author']}  Session: {line['session']}  Branch: {line['branch']}  "
+        f"Ts: {line['ts']}"
+    )
+    return 0
+
+
 def cmd_where(args: argparse.Namespace) -> int:
     path = env.ledger_path()
     kind = "project" if LEDGER.name in str(path) and ".claude" not in str(path) else "global"

docket/context.py

@@ -82,6 +82,7 @@ def build_context(
     settings: Mapping[str, Any] | None = None,
     settings_id: str = "default",
     feature: str = "",
+    latest_id: str = "",
 ) -> str:
     """Render whole records under tiered budget rules.
 
@@ -153,11 +154,13 @@ def build_context(
             adjacency[ident].add(target)
             adjacency[target].add(ident)
     revision = _revision(history)
-    latest = max(by_id, key=lambda ident: at[ident], default="")
+    latest = latest_id or max(by_id, key=lambda ident: at[ident], default="")
     if latest:
         # The digest covers the history up to and including that record, which
         # here is the whole history. A rebase renumbers the tail, so an agent
         # that passes the pair back to --since learns its baseline is stale.
+        # A correction can be the last line, and projection drops correction
+        # lines, so the caller passes the raw last id.
         latest = f"{latest}@{revision}"
     feature_prefix = _feature_prefix(feature, max(1, soft_limit // 4))
     prefix = (

docket/context_delta.py

@@ -21,6 +21,7 @@ def build_delta(
     *,
     since: str,
     baseline: Iterable[Mapping[str, Any]],
+    raw: Iterable[Mapping[str, Any]] | None = None,
     max_chars: int | None = None,
     ledger: str = "",
     settings: Mapping[str, Any] | None = None,
@@ -38,39 +39,54 @@ def build_delta(
     """
 
     history = list(entries)
+    baseline = list(baseline)
     by_id = {_id(item): item for item in history}
-    at = positions(history)
+    lines = list(raw) if raw is not None else history
+    at = positions(lines)
     since, _, expected = since.partition("@")
-    if since not in by_id:
+    if since not in at:
         return None
     cutoff = at[since]
-    prefix = [item for item in history if at[_id(item)] <= cutoff]
-    if expected and _revision(prefix) != expected:
+    # The token was minted when since was the last line, so the baseline, the
+    # projection of lines up to since, is exactly the history it hashed.
+    if expected and _revision(baseline) != expected:
         # A rebase renumbers the tail, so this ID now covers different history.
         return None
     was_available = {_id(item) for item in baseline if _available(item)}
     cfg = settings if settings is not None else _SETTINGS_DEFAULTS
     limit = max_chars if max_chars is not None else cfg["budget"]["target"]
+    corrected_ids = {
+        str(line["corrects"])
+        for line in lines
+        if line.get("kind") == "correction"
+        and at[_id(line)] > cutoff
+        and at.get(str(line["corrects"]), cutoff + 1) <= cutoff
+    }
     added = [item for item in history if at[_id(item)] > cutoff]
+    corrected = [item for item in history if _id(item) in corrected_ids]
     changed = [
         item
         for item in history
-        if at[_id(item)] <= cutoff and _id(item) in was_available and not _available(item)
+        if at[_id(item)] <= cutoff
+        and _id(item) in was_available
+        and not _available(item)
+        and _id(item) not in corrected_ids
     ]
-    latest = max(by_id, key=lambda ident: at[ident], default="")
+    latest = _id(lines[-1]) if lines else ""
     revision = _revision(history)
     head = (
         "\n".join(
             [
                 f"# docket: {_clip_metadata(ledger or 'ledger', 180)} | revision: {revision}"
                 f" | latest: {latest}@{revision} | since: {since}",
-                f"# changed: {len(added)} added, {len(changed)} no longer available.",
+                f"# changed: {len(added)} added, {len(corrected)} corrected, "
+                f"{len(changed)} no longer available.",
             ]
         )
         + "\n\n"
     )
     blocks: list[str] = []
-    for item in added + changed:
+    for item in added + corrected + changed:
         block = _render_record(item, "changed", "", by_id)
         if len(head) + len("\n\n".join(blocks + [block])) > limit:
             block = _index_line(item, cfg["index"]["detail_min"])

docket/context_render.py

@@ -142,6 +142,8 @@ def _render_record(
         tags.append("pinned")
     if _is_retired(entry):
         tags.append("historical")
+    if _list(entry.get("corrections")):
+        tags.append("corrected")
     lines = [f"### {ident} | {kind} | {state} [{', '.join(tags)}]", f"role: {role}"]
     lines.append(f"text: {_text(entry.get('text'))}")
     if recorded_state != state: