[BHAWESHBHASKAR]

Summary

This is the second notes PR of coordination Phase 2, following #283. Three changes:

• Staleness: a note is judged stale once the file it was written against has changed.
• Endorsement: a person who owns a note's path can endorse it, so it ranks first and is shown in full.
• Context pack: the pack gains a notes section, so an agent's first call carries what earlier agents and people recorded about its files.

Why

A note is only useful if the next agent sees it at the moment it starts, and can tell an owner-vouched fact from an agent's guess. Staleness keeps outdated notes from misleading agents. Endorsement by human owners makes vouching a deliberate act by a person, and the maintainer decided agents cannot do it.

Changes

One view for listings and packs: Repo::notes_for (leep-derive/src/notes_view.rs) serves both GET /v1/notes and the context pack, so the two always give the same staleness and endorsement answer.

Staleness

• A note is stale when a tree lookup at the head finds a blob different from the note's at_blob. A changeset note is never stale. A directory note is stale once the directory is gone.
• If the at_changeset is missing or a tree can't be read, the answer is "unknown", never an error. An unknown note is never served as endorsed.
• Bounds:
  • 32 checks per pack and 100 per listing page;
  • 8 checks at once;
  • a deadline of half the section bound.
• Unfinished work is reported as omitted {notes, bound|timeout}.
• GET /v1/notes and GET /v1/notes/{id} take ?ref=; a ref that doesn't exist is 404.
• Write and retract answers carry no stale.

Endorsement: POST /v1/notes/{id}/endorse, or leep note endorse ID in the CLI. There is deliberately no MCP tool, and a test asserts that none offers it.

• Who may endorse:

  • a token with kind: human that may review;
  • named in OWNERS at the default ref's head, so a branch cannot grant ownership; for a directory note, the directory's own OWNERS;
  • not the note's writer.

  Anyone else gets 403.

• Refusals:

  • a closed, expired, stale or unknown note is 409;
  • a changeset note is 400.

• Lifetime: endorsing sets expires to endorsed_at + 365 days. Endorsing again renews it. An endorsement lapses at read time once the note goes stale.

• Operator undo: leep-server notes unendorse --id N | --by P gives each note back the life it had before it was endorsed. OPERATIONS has a runbook for a person's token that was removed, re-kinded, leaked or dropped from OWNERS.

Reports: a human owner's report now hides a human or endorsed note; anyone else's report is still only counted. unreport restores the right life.

Context pack

• A seventh section, notes, takes 10% of the budget (files go from 25 to 20%, history from 20 to 15%).
• Spare budget goes first to ref_health, so notes never displace it.
• Ranking: endorsed, then human, then agent; then fresh, unknown, stale; then nearest anchor; then newest.
• Stale agent notes are dropped from the pack.
• Endorsed notes and fresh human notes carry their body, cut to 1 KiB; every other note carries its title, cut to 80 bytes.
• All note text is under untrusted. MCP fences it and the CLI escapes it.
• The store probe returns endorsed, then human, then agent notes before its 256-row cap, so 300 newer agent notes on a busy path cannot push an older endorsed note out.

Demo: claim 11: an agent's note, endorsed by a human owner, reaches a later agent's leep_task_start pack.

Docs: ADR 0098 §12 and an amendment to ADR 0097; FORMATS, ARCHITECTURE §12, CLI.md, MCP.md and OPERATIONS (metrics and the unendorse runbook); changelog.d/coord-notes-endorse.md.

Testing

• Lint and checks: fmt check, clippy -D warnings, check-version.sh and changelog-assemble.sh --check pass.
• Full suite: cargo test --workspace against Postgres 16: 2,057 passed, 0 failed. The demo passes on SQLite and Postgres.
• New tests:
  • Pack behaviour:
    • four identical pack asks are byte-identical with notes present;
    • notes never displace ref health, at three budgets.
  • Staleness:
    • a changed blob, a deleted directory, another ref, and a file restored to its old content;
    • a missing at_changeset or an unreadable head gives unknown, not an error.
  • Endorsement:
    • refused for a non-owner, an agent-kind owner, the author, a token that can't review, and a human read-only token;
    • refused for a closed, stale or changeset note, and for read-only or no-tokens access;
    • a subdirectory owner is refused on a parent-directory note;
    • endorse racing retract and supersede, 16 rounds;
    • an endorsed note lives a year, then is swept.
  • Bounds:
    • the 32/100/256 bounds, each reporting bound;
    • a passed deadline, on a paused clock.
  • Crowding: contract test on memory, SQLite and Postgres with 300 newer agent notes plus older endorsed and human notes.
  • Injection fixtures: newline, ANSI, OSC, bidi, tag characters, U+2028, backtick fences and "ignore previous instructions" in titles, bodies and anchors, written through a raw store; they never appear outside untrusted.
• No wall-clock asserts: the pack tests run on a paused clock.

Fable reviewed the change: "ship after must-fixes". The must-fix is included: endorsed notes were evicted by crowding before ranking. All should-fixes and nits are included too:

• the unendorse command;
• yearly renewable expiry;
• staleness no longer reported on write answers;
• a partial marker;
• the missing tests.

Compatibility

• API: additive only.
  • NoteEntry gains stale, endorsed and endorsed_at.
  • ContextPack gains notes (#[serde(default)]).
  • New endorse route and ?ref= parameter.
  • New omitted reason bound.
• No migration: the columns came with migration 0010 in coord: notes, agents' shared findings anchored to files (ADR 0098) #283.
• Visible changes:
  • packs now carry a notes section and smaller files and history quotas;
  • leep_notes_endorsed_total also counts renewals.
• Branch history: the branch carries a no-op merge of its earlier, already-squashed history (coord: notes, agents' shared findings anchored to files (ADR 0098) #283).

---

Generated by Claude Code