From bc04eeb9d9b1557f55a606def6a7b94051cf3c10 Mon Sep 17 00:00:00 2001 From: Eric Law <39393654+acn-ericlaw@users.noreply.github.com> Date: Sun, 4 Oct 2026 09:40:59 -0700 Subject: [PATCH] =?UTF-8?q?chore(agent-memory):=20upgrade=204.42.0=20?= =?UTF-8?q?=E2=86=92=204.42.1=20=E2=80=94=20declare=20a=20fact=20consulted?= =?UTF-8?q?=20to=20make=20a=20decision;=20check=20for=20declaration=20gaps?= =?UTF-8?q?=20before=20archiving=20one?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mode B upgrade (PATCH, guidance only). Reconcile re-copied DECAY.md, REVIEW.md and .agent/schema.md (stock 4.42.0 before); the protocol semantic step re-copied memory/PROTOCOL.md (byte-identical to the 4.42.0 template). Stamped 4.42.1. Ran in a throwaway worktree of origin/main. Co-Authored-By: Claude Opus 5.5 --- .agent/schema.md | 2 +- .agent/version.md | 4 ++-- DECAY.md | 8 ++++++-- REVIEW.md | 19 ++++++++++++++++++- memory/PROTOCOL.md | 10 ++++++---- memory/sessions/2026-10-04-164021.md | 18 ++++++++++++++++++ 6 files changed, 51 insertions(+), 10 deletions(-) create mode 100644 memory/sessions/2026-10-04-164021.md diff --git a/.agent/schema.md b/.agent/schema.md index 1a1eae2..e629749 100644 --- a/.agent/schema.md +++ b/.agent/schema.md @@ -233,7 +233,7 @@ Bullet list (if any). What the next agent needs to know. ## Memory References -- Referenced: +- Referenced: - Created: - Reactivated: - Closed: diff --git a/.agent/version.md b/.agent/version.md index dcefa31..e89e2da 100644 --- a/.agent/version.md +++ b/.agent/version.md @@ -4,7 +4,7 @@ > Mode B can detect drift and upgrade in place (see the tool's `UPGRADE.md`). > `version` gates the upgrade ladder — don't hand-edit it unless you mean to. -- **version:** 4.42.0 +- **version:** 4.42.1 - **enabled_with:** 4.38.0 -- **last_upgraded:** 2026-09-18 +- **last_upgraded:** 2026-10-04 - **mode:** A diff --git a/DECAY.md b/DECAY.md index d291adc..9fb469e 100644 --- a/DECAY.md +++ b/DECAY.md @@ -81,7 +81,9 @@ Every session log carries a `## Memory References` section: - Reactivated: drizzle-over-prisma ``` -- **Referenced** — ids the session relied on or reinforced. +- **Referenced** — ids the session relied on or reinforced. *Relied on* means consulted to make + a decision: the session would have decided differently without the fact (v4.42.1). Reading a + fact that shaped no decision is not a use. - **Created** — new facts added this session (born `tier: working`). - **Reactivated** — ids pulled back from the archive. - **Closed** — threads completed this session (v4.41.0): list them under `Referenced` with a @@ -91,7 +93,9 @@ Every session log carries a `## Memory References` section: The pre-commit `memory-lint` advisory `[undeclared-reference]` (v4.41.0) warns when a change edits a fact's body without declaring the id in a session log staged with it — the diff is the only place that omission is visible, because the footers and this log then agree with each other -while both are wrong. +while both are wrong. A *consultation* leaves no diff at all, so no check can see an undeclared one +(v4.42.1): the agent declares it when it writes the log, and the review's subject read before +archiving a fact as faded (`REVIEW.md` step 6, *declaration gaps*) is the backstop. So, for any id: - `uses` = number of session logs whose `## Memory References` name it. diff --git a/REVIEW.md b/REVIEW.md index 552fc3b..8b3e6b6 100644 --- a/REVIEW.md +++ b/REVIEW.md @@ -136,6 +136,22 @@ stalled thread as `[thread-stale]`, so the condition cannot hide. Either way, then confirm **no id lives in both `continuity.md` and the archive** (a fact exists in exactly one place). Record the result in the summary. (Superseded facts are exempt — they archive on truth-state, not recency.) + + **Declaration gaps (facts, v4.42.1)** — the fact-level twin of step 5's thread rule. Both checks + above count only *declared* uses, and a fact consulted to make a decision leaves no diff, so for + **each** fact archived as *faded*, read for its **subject** — the code, rule or contract it + records, not its id. Search the `archive_window` session logs for the subject's distinctive terms + (backticked identifiers, words from its bold title), skipping `## Memory Review` and + `## Memory References` blocks, and read the sessions that hit. If one **exercised** the subject — + changed, tested, applied or decided by it — without declaring the id, the fade is a declaration + gap, not disuse: move the fact back as above, name it under *this* review's `## Memory + References` (re-affirmed, citing the session that relied on it) so its count resets, and note + the reversal in the `## Memory Review` block. A mention is not an exercise: prose that names the + subject or the id — a prior review summary, a decay note, a plan never acted on — is not evidence + of use (the `ot-review-step6-prose` livelock). The read is judgment and never counts on its own; + only the declaration it prompts does. (Field report: mercury-composable and mercury, 2026-10-04 + — three in-use facts archived in five weeks; this repo's `git-hook-fragment-dispatch` was a + fourth.) 7. **Verify invariants (cadence).** If `sessions_since_last_invariant_check ≥ verify_invariants_every` (or `last_invariant_check` is unset and that many session files exist), raise **one** Open Thread listing every never-decay fact — @@ -176,7 +192,8 @@ stalled thread as `[thread-stale]`, so the condition cannot hide. **re-arms the over-archival guard, and forces a false reactivation** (it will demand you move the fact you just archived back). `## Memory References` records only the ids you genuinely **relied on / created / reactivated** this session (e.g. a new `(knowledge-harvest)` or - invariant-reverify thread you created). The `## Memory Review` block is *not* parsed as references, + invariant-reverify thread you created) — and a fact kept after a declaration gap (step 6), + which was moved back, not archived. The `## Memory Review` block is *not* parsed as references, so archived ids belong there. *(Learned the hard way: a review summary that listed its archived ids under `## Memory References` threw 13 spurious `over-archived` ERRORs.)* **Inspecting a stalled thread as gate evidence is not a use either** — list a stalled thread diff --git a/memory/PROTOCOL.md b/memory/PROTOCOL.md index fee4d90..9d462d5 100644 --- a/memory/PROTOCOL.md +++ b/memory/PROTOCOL.md @@ -80,10 +80,12 @@ on upgrade; fork it under a new name or upstream a genuine fix instead of editin - Treat `memory/continuity.md` as working memory and check existing decisions before proposing a conflicting change. - Note facts, decisions, preferences, and thread changes for session close. -- Track every fact id referenced, created, reactivated, or closed for the session log's - `## Memory References` — an edit or a closure is a use, inspecting alone is not (the pre-commit - hook's `[undeclared-reference]` advisory catches a fact edited without a declaration); do not - edit `uses`, `last_used`, or `tier` mid-session. +- Track every fact id relied on, created, reactivated, or closed for the session log's + `## Memory References`. A fact is relied on when it shaped a decision — you would have decided + differently without it. An edit or a closure is always a use; a read that shaped nothing is not. + The pre-commit `[undeclared-reference]` advisory catches an undeclared edit, but nothing can + catch an undeclared consultation — declare it when you write the log. Do not edit `uses`, + `last_used`, or `tier` mid-session. - At a natural seam—milestone, phase shift, or unrelated pivot—persist the session log and continuity update before compaction. Context-window utilization is the real pressure signal; wall time and perceived vagueness are only proxies. At high utilization, suggest diff --git a/memory/sessions/2026-10-04-164021.md b/memory/sessions/2026-10-04-164021.md new file mode 100644 index 0000000..150ddf9 --- /dev/null +++ b/memory/sessions/2026-10-04-164021.md @@ -0,0 +1,18 @@ +# Session (2026-10-04T16:40:21.625Z) + +**Agent:** Claude Code + +Lightweight: Mode B upgrade 4.42.0 → 4.42.1 (PATCH — declare a fact consulted to make a decision; check for +declaration gaps before archiving one: the protocol now tracks every fact id *relied on* — it shaped a decision, +you would have decided differently without it; an edit or a closure is always a use, a read that shaped nothing is +not — and `REVIEW.md` step 6 gains *declaration gaps (facts)*: before archiving a fact as faded, read the window's +logs for its subject and keep a fact whose subject was exercised without a declaration; from the mercury-composable +/ mercury field report). Reconcile re-copied DECAY.md, REVIEW.md and .agent/schema.md (each stock 4.42.0 before — +staleness only). Protocol — re-copied (byte-identical to the 4.42.0 template). The governance pair is not adopted — +listed as two optional notes (reference only). Adapters re-synced; stamped 4.42.1; every re-copied file +byte-identical to its MANIFEST source. Ran in a throwaway worktree of origin/main (`--forge github`). memory-lint: +0 errors, 1 warning(s). Upstream release: https://github.com/Accenture/mercury-go/releases/tag/v4.42.1 . + +## Memory References + +(none)