Skip to content

docs(drift): verified corrections and one gap from document-drift - #135

Open
emp3thy wants to merge 2 commits into
mainfrom
docs/drift-2026-10-13
Open

emp3thy wants to merge 2 commits into
mainfrom
docs/drift-2026-10-13

Conversation

@emp3thy

@emp3thy emp3thy commented Oct 13, 2026

Copy link
Copy Markdown
Owner

Summary

Output of the document-drift skill (phase A, first full run with the fixed unit packer) on this repository at 9d5be26: the docs were checked against the code in both directions and every applied edit was accepted by a verifier agent that read the source independently.

  • Corrections commit: 53 verified corrections across 14 docs, plus one drift-unverified notice on a README paragraph that describes the code but names nothing in it.
  • Additions commit: one gap filled (the scope parameter of memory.observe in website/mcp-tools.md).
  • Needs a human decision (45 entries, listed in the commit bodies): 7 undocumented names with no doc to live in (retention parameters, smoke-test flags), guarantee statements the code contradicts (never, must), claims the agent could not settle, 10 edits the verifiers rejected, and 12 edits refused because docs/agentcore-ui/gaps/*.md are titled GAP / DECISION, which the never-edit heading rule protects.

Numbers

claims checked edits proposed kept by script checks verifier accept / reject applied
644 91 64 53 / 10 54

Run id 2026-10-13-b27d, Drift-Base in each commit body. Cost about $9 for 4 review, 5 gap and 18 verifier agents.

Review hints

  • docs/hooks-setup.md and website/mcp-tools.md carry the biggest corrections: contextual_inject fires on every tool call, the evidence gate is a distinct-hit count, and deferred is the default inject mode.
  • The tech-debt-pbis/*/PBI.md docs produced only unsure questions; if they are history rather than documentation, add them to exclude in .document-drift.yaml.
  • .document-drift/ is the skill's workdir, excluded via .git/info/exclude.

🤖 Generated with Claude Code

Drift-Run: 2026-10-13-b27d
Drift-Base: 9d5be26
Drift-Scope: full
Drift-Unchecked: 0 doc units, 0 gap docs, 0 verify batches

- .claude/skills/start-better-memory-ui/SKILL.md:8 correct memory_start_ui is a stub that returns "UI not yet implemented" (better_memory/mcp/handlers/sessions.
- README.md:9 notice unverified block (1st notice)
- README.md:241 correct the memory.start_ui MCP tool is a stub (better_memory/mcp/handlers/sessions.py:160-164, better_memory/services/ui_launcher.py:100-138, b
- README.md:307 correct retention is manual, with no auto-scheduling (better_memory/mcp/handlers/reflections.py:98-111, better_memory/services/retention_schedul
- README.md:343 correct retention is invoked manually and there is no scheduler (better_memory/services/retention_scheduler.py:24-60, better_memory/mcp/handlers
- better_memory/skills/memory-retrieve.md:46 correct memory.retrieve result also carries `insights` and `knowledge` keys (better_memory/mcp/handlers/reflections
- docs/agentcore-ui/agentcore-mapping.md:35 correct retire_reflection location in agentcore.py and protocol.py (better_memory/storage/agentcore.py:1845-1851, be
- docs/agentcore-ui/agentcore-mapping.md:36 correct promote_reflection location in agentcore.py and protocol.py (better_memory/storage/agentcore.py:1838-1843, b
- docs/agentcore-ui/agentcore-mapping.md:37 correct supports_episodes in agentcore.py is at lines 106-107 (better_memory/storage/agentcore.py:156-157, better_me
- docs/agentcore-ui/agentcore-mapping.md:41 correct semantic_observe location in agentcore.py (better_memory/storage/agentcore.py:1428-1478)
- docs/agentcore-ui/agentcore-mapping.md:43 correct semantic_set_scope location in agentcore.py (better_memory/storage/agentcore.py:1657-1689)
- docs/agentcore-ui/agentcore-mapping.md:44 correct semantic_delete location in agentcore.py (better_memory/storage/agentcore.py:1691-1702)
- docs/agentcore-ui/data-sources.md:35 correct no capability gating exists in the UI (better_memory/ui/app.py:94-105, better_memory/ui/app.py:221-233, better_me
- docs/agentcore-ui/data-sources.md:72 correct episodes gating is not yet implemented (better_memory/ui/app.py:221-233, better_memory/ui/templates/base.html:91)
- docs/agentcore-ui/data-sources.md:120 correct episodes gating is not implemented yet (better_memory/ui/app.py:221-233, better_memory/ui/app.py:253-256, better
- docs/agentcore-ui/data-sources.md:127 correct the episodes shell route is at app.py:205-207 (better_memory/ui/app.py:221, better_memory/ui/app.py:227)
- docs/agentcore-ui/data-sources.md:128 correct the timeline route is at app.py:209-226 (better_memory/ui/app.py:229, better_memory/ui/app.py:249)
- docs/agentcore-ui/data-sources.md:129 correct the banner route is at app.py:228-236 (better_memory/ui/app.py:251, better_memory/ui/app.py:262, better_memory/u
- docs/agentcore-ui/data-sources.md:130 correct the drawer route is at app.py:238-246 (better_memory/ui/app.py:264, better_memory/ui/app.py:275, better_memory/u
- docs/agentcore-ui/data-sources.md:131 correct the close route's existence pre-check is at app.py:265-266 (better_memory/ui/app.py:296, better_memory/ui/app.py
- docs/agentcore-ui/data-sources.md:132 correct close route is at app.py:255-288 and EpisodeService is constructed at app.py:93 (better_memory/ui/app.py:284, be
- docs/agentcore-ui/data-sources.md:138 correct semantic() route is at app.py:487 (better_memory/ui/app.py:537, better_memory/ui/templates/semantic.html:12)
- docs/agentcore-ui/data-sources.md:140 correct drawer reads the semantic row via inline SQL in app.py with no service/backend (better_memory/ui/app.py:603, bet
- docs/agentcore-ui/read-spec.md:57 correct the flat agentcore reflection list method is list_reflections(project, status_filter, ...) (better_memory/storage/ag
- docs/agentcore-ui/read-spec.md:84 correct the agentcore reflection accessor is get_reflection (better_memory/storage/agentcore.py:1853, better_memory/storage/
- docs/agentcore-ui/read-spec.md:119 correct the R2 accessor is get_reflection (better_memory/storage/agentcore.py:1853)
- docs/agentcore-ui/read-spec.md:128 correct the project dropdown method is AgentCoreBackend.list_projects() (better_memory/storage/agentcore.py:1956, better_me
- docs/agentcore-ui/read-spec.md:185 correct the public semantic accessor is get_semantic (better_memory/storage/agentcore.py:1704, better_memory/storage/protoc
- docs/agentcore-ui/write-spec.md:44 correct capability flag gating the Confirm action is supports_reflection_confirm (better_memory/storage/protocol.py:94, bet
- docs/agentcore-ui/write-spec.md:59 correct promote_reflection at agentcore.py:1578, declared at protocol.py:241 (better_memory/storage/agentcore.py:1838, bett
- docs/agentcore-ui/write-spec.md:60 correct retire_reflection at agentcore.py:1585, declared at protocol.py:245 (better_memory/storage/agentcore.py:1845, bette
- docs/agentcore-ui/write-spec.md:61 correct Confirm is gated by supports_reflection_confirm=False (better_memory/storage/agentcore.py:172, better_memory/ui/app
- docs/agentcore-ui/write-spec.md:63 correct list_session_exposures is declared at protocol.py:262 (better_memory/storage/protocol.py:380)
- docs/agentcore-ui/write-spec.md:69 correct semantic_observe at agentcore.py:1199, declared at protocol.py:152 (better_memory/storage/agentcore.py:1428, better
- docs/agentcore-ui/write-spec.md:70 correct semantic_update_text at agentcore.py:1383, declared at protocol.py:173 (better_memory/storage/agentcore.py:1630, be
- docs/agentcore-ui/write-spec.md:71 correct semantic_set_scope at agentcore.py:1410, declared at protocol.py:177 (better_memory/storage/agentcore.py:1657, bett
- docs/agentcore-ui/write-spec.md:72 correct semantic_delete at agentcore.py:1444, declared at protocol.py:181 (better_memory/storage/agentcore.py:1691, better_
- docs/agentcore-ui/write-spec.md:99 correct Confirm is gated by supports_reflection_confirm=False (better_memory/storage/agentcore.py:172, better_memory/storag
- docs/hooks-setup.md:11 correct SessionStart injects project + general semantic memories and reflections (default deferred mode renders only an index) (better_
- docs/hooks-setup.md:16 correct PreToolUse contextual_inject is latched to one firing per session and does the same as UserPromptSubmit keyed to tool input (be
- docs/hooks-setup.md:22 correct the gate is a two-leg check (BM25 match on reflection_fts, or keyword-hit fallback) (better_memory/services/relevant.py:3, bett
- docs/hooks-setup.md:32 correct PreToolUse contextual_inject is latched to one real firing per session (better_memory/hooks/contextual_inject.py:11, better_mem
- docs/hooks-setup.md:150 correct contextual_inject PreToolUse group is latched to one real firing per session (better_memory/hooks/contextual_inject.py:11, bet
- docs/hooks-setup.md:174 correct deferred renders general-scope semantic memories in full; legacy is the config default when the env var is unset (better_memor
- website/agentcore-setup.md:10 correct the Stop hook's closure event depends on CreateEvent extractionMode (better_memory/hooks/session_close.py:217, better_me
- website/agentcore-setup.md:63 correct the Stop hook resolves the backend from settings.json (hooks now resolve it, the Stop hook no longer does anything agent
- website/agentcore-setup.md:133 correct the caps context processor exposes six capability flags (better_memory/ui/app.py:97, better_memory/ui/app.py:104, bette
- website/architecture.md:43 correct the Stop hook sends CreateEvent(role=OTHER) in agentcore mode (better_memory/hooks/session_close.py:217, better_memory/stor
- website/configuration.md:78 correct in agentcore mode the Stop hook fires a CreateEvent(role=OTHER) closure event (better_memory/hooks/session_close.py:217, b
- website/mcp-tools.md:60 correct memory.record_use requires outcome (better_memory/mcp/tools.py:253)
- website/mcp-tools.md:126 correct legacy is the default bootstrap mode and deferred renders general-scope semantic memories in full (better_memory/config.py:25
- website/observation-lifecycle.md:39 correct Rule A uses the oldest retirement among the linked reflections (better_memory/services/retention.py:145)
- website/troubleshooting/agentcore.md:59 correct both the server factory and the Stop hook's lazy import raise the boto3 hint (better_memory/storage/factory.py
Drift-Run: 2026-10-13-b27d
Drift-Base: 9d5be26
Drift-Scope: full
Drift-Unchecked: 0 doc units, 0 gap docs, 0 verify batches

- website/mcp-tools.md:20 add param scope (better_memory/mcp/tools.py:66)

Needs a human decision:
- :0 no-home: param retention_days (better_memory/mcp/tools.py:444)
- :0 no-home: param prune (better_memory/mcp/tools.py:452)
- :0 no-home: param prune_age_days (better_memory/mcp/tools.py:460)
- :0 no-home: param dry_run (better_memory/mcp/tools.py:467)
- :0 no-home: flag --mutation (scripts/e2e_mutation_smoke.py:415)
- :0 no-home: flag --check-only (scripts/e2e_mutation_smoke.py:421)
- :0 no-home: flag --no-control (scripts/e2e_mutation_smoke.py:426)
- .claude/skills/start-better-memory-ui/SKILL.md:3 guarantee-mismatch: the MCP tool memory_start_ui is a stub (new drops the guarantee word 'must') (better_memo
- CLAUDE.md:3 unsure: This project has a graphify knowledge graph at graphify-out/ (GRAPH_REPORT.md, wiki/index.md) (graphify-out/GRAPH_REPORT.md was not found
- README.md:307 unsure: synthesis runs from the UI button or automatically by memory.start_episode (better_memory/mcp/handlers/episodes.py:59-77, better_memory/
- better_memory/skills/memory-write.md:5 unsure: component, trigger_type and outcome are mandatory fields; trigger_type is one of decision | implementation | bu
- docs/agentcore-ui/agentcore-mapping.md:35 unsure: EASY rows say the only missing work is to route the UI write/read through the backend (better_memory/ui/app.
- docs/agentcore-ui/agentcore-mapping.md:39 verify-rejected: semantic_list location in agentcore.py and SemanticMemoryService.list_for_project in services/seman
- docs/agentcore-ui/agentcore-mapping.md:40 verify-rejected: _get_semantic_record and fetch_rating_evidence locations: not minimal: drops the 1285 ref (_semanti
- docs/agentcore-ui/agentcore-mapping.md:42 verify-rejected: semantic_update_text location in agentcore.py: not minimal: drops the 1012 ref (_full_metadata_snap
- docs/agentcore-ui/data-sources.md:9 guarantee-mismatch: the UI never imports factory/build_backend/StorageBackend (new drops the guarantee word 'never') (bett
- docs/agentcore-ui/data-sources.md:15 verify-rejected: no UI data flow crosses the StorageBackend Protocol: keeps the false bold claim 'none of them cross the
- docs/agentcore-ui/data-sources.md:38 unsure: goes_through_backend = false for every single item (nothing uses the backend) (better_memory/ui/app.py:326, bette
- docs/agentcore-ui/data-sources.md:167 guarantee-mismatch: app.py never imports storage/factory.py or build_backend and is not backend-aware (new drops the gua
- docs/agentcore-ui/data-sources.md:171 guarantee-mismatch: there is no capability gating; supports_episodes is never referenced in better_memory/ui (new drops
- docs/agentcore-ui/gaps/distinct-project-dropdown-enumeration.md:9 protected: both dropdowns are populated today by raw SELECT DISTINCT against local sqlite (l
- docs/agentcore-ui/gaps/distinct-project-dropdown-enumeration.md:38 protected: call sites and query functions for the two dropdowns (app.py:612/294, queries.py
- docs/agentcore-ui/gaps/distinct-project-dropdown-enumeration.md:41 protected: neither dropdown goes through StorageBackend; both read local content tables (li
- docs/agentcore-ui/gaps/distinct-project-dropdown-enumeration.md:167 unsure: Recommendation: build Option B (ListActors union migration ledger) for both dropdo
- docs/agentcore-ui/gaps/edit-aws-extracted-reflection-text.md:47 protected: ReflectionService is handed a raw connection at app.py:93-96 (line 47 is in a never
- docs/agentcore-ui/gaps/edit-aws-extracted-reflection-text.md:55 protected: _parse_reflection_record is at agentcore.py:732-885 (line 55 is in a never-edit sec
- docs/agentcore-ui/gaps/edit-aws-extracted-reflection-text.md:60 protected: the source_backend body marker is read at agentcore.py:1040-1053, 1526 (line 60 is
- docs/agentcore-ui/gaps/edit-aws-extracted-reflection-text.md:73 protected: _mutate_namespace_and_status lives at agentcore.py:1507-1591 (line 73 is in a never
- docs/agentcore-ui/gaps/edit-aws-extracted-reflection-text.md:77 protected: _credit_body_counter at 1055-1111 and _mutate_namespace_and_status at 1526-1549 (li
- docs/agentcore-ui/gaps/observation-history-absent.md:55 protected: list_observations is at agentcore.py:887 (line 55 is in a never-edit section) (better_memor
- docs/agentcore-ui/gaps/observation-history-absent.md:64 protected: the cross-session-deferred note is at agentcore.py:898-899 (line 64 is in a never-edit sect
- docs/agentcore-ui/gaps/retention-superseded-by-event-expiry.md:99 protected: the retention capability flag is named supports_retention (line 99 is in a never-
- docs/agentcore-ui/gaps/retention-superseded-by-event-expiry.md:152 protected: the retention capability flag is supports_retention (line 152 is in a never-edit
- docs/agentcore-ui/read-spec.md:166 unsure: Scope-filter default gap (must fix): semantic_list today resolves a single namespace and maps None->project only, d
- docs/agentcore-ui/read-spec.md:205 verify-rejected: title resolution uses backend.get_reflection / backend.get_semantic: the /diagnostics route (ui/app.py:711
- docs/agentcore-ui/write-spec.md:3 guarantee-mismatch: create_app never touches build_backend and routes every content write through raw-connection services (n
- docs/agentcore-ui/write-spec.md:91 guarantee-mismatch: a new AgentCoreBackend.list_projects() wrapping ListActors must be added (none exists today — grep conf
- docs/debug/2026-05-13-synthesize-freeze.md:96 verify-rejected: the audit helpers live in mcp/server.py as _append_synth_audit / _audit_synth_call: the doc is
- tech-debt-pbis/chore-mcp-server-god-module-handler-extraction-2026-06-10/PBI.md:15 unsure: mcp/server.py holds 22 inline tool handlers in _call_tool (evidence
- website/agentcore-setup.md:14 unsure: The IAM policy is a narrow, sufficient policy for the actions better-memory performs (better_memory/storage/agentcore.py
- website/agentcore-setup.md:53 verify-rejected: the Stop hook builds a closure client that signs against agentcore.json's region: closure client is gone, but h
- website/agentcore-setup.md:154 verify-rejected: extraction happens ~1-3 minutes after a closure event: the parenthetical describes AWS extraction timing after
- website/agentcore-setup.md:156 guarantee-mismatch: Closure events fire automatically: the Stop hook, when the backend resolves to agentcore, emits a CreateEve
- website/architecture.md:51 verify-rejected: the caps context processor reads six capability flags: count fix is right (app.py:97-105) but 'The first six flags
- website/troubleshooting/agentcore.md:83 verify-rejected: the Stop hook builds a closure client against agentcore.json's region: hooks still build agentcore cl

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Claude BugBot Analysis

The diff only changes documentation (README, docs, website pages, a skill description and a skill markdown file). It has no executable code changes, so I found no bugs.

No bugs were detected in this PR.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant