PR #540: Maintenance wiring for extraction and event processing

Maintainer Quick Read

Why Maintainers Should Care

This connects extraction/event processing to maintenance so LCM can update observed-work and event observations outside user-facing reads. The key product point is trust: asking a question does not secretly mutate memory.

Stack Map

flowchart LR
  P516["#516 Temporal spine"] --> P517["#517 Observed work read model"]
  P517 --> P518["#518 Suggestion ledger"]
  P518 --> P537["#537 Deterministic extraction"]
  P537 --> P538["#538 Event observations"]
  P518 --> P539["#539 Opt-in suggestion tools"]
  P538 --> P540["#540 Maintenance wiring"]
  P540 --> P530["#530 Tracker/open state"]
  P538 --> P531["#531 Event episodes"]
  P530 --> P532["#532 Topic/vocabulary"]
  P526["#526 Draft reference"] -. "not the merge path" .-> P516

How It Works

flowchart TD
  A["Summary-producing maintenance"] --> B["Observed-work extraction sweep"]
  B --> C["Event-observation sweep"]
  C --> D["Persist cursor/retry state"]
  D --> E["Later reads see updated evidence"]
  F["lcm_recent / lcm_work_density / lcm_event_search"] -. "read-only" .-> E

What Ships In This PR

• maintenance hooks for observed-work extraction
• maintenance hooks for event observation extraction
• bounded sweeps with retry state
• ordering after summary-producing work
• tests that read tools do not perform maintenance writes

What This PR Intentionally Does Not Do

• does not run extraction from every read
• does not add background reminders/wakes
• does not grant task/Cortex write authority

How An Agent Uses It

• After new summaries are produced, maintenance processes only the new evidence window.
• If a batch fails, retry state preserves the failure instead of losing coverage.
• A read tool call observes whatever maintenance already produced; it does not kick off a write.

Engineering Boundaries

• LCM is an evidence layer. It does not become Cortex, GBrain, OpenClaw Tasks, or a fuzzy semantic authority.
• Recaps and observed states are entry points for investigation, not proof of exact commands, SHAs, paths, timestamps, root cause, or task completion.
• Exact claims still require source drilldown through lcm_describe, lcm_expand, lcm_expand_query, raw messages, GitHub, logs, tickets, or the relevant authority.
• Source identifiers stay hidden by default unless a tool has an explicit includeSources or debug affordance.
• Reads stay read-only. Writes happen through explicit storage, maintenance, extraction, or review-ledger paths for the slice that owns them.

Primary Review Files

• src/engine.ts
• src/maintenance.ts
• src/observed-work-extractor.ts
• src/event-observation-extractor.ts
• test/observed-work-store.test.ts

Size And Review Surface

These are intentionally large LCM changes, so the body separates the GitHub-visible diff from the intended logical review slice. Later PRs target main, which makes the GitHub Files tab include parent-stack code; reviewers should use the logical parent listed above when judging the slice.

Logical slice breakdown:

Review Concerns Already Folded Into The Code

• Fallback message timestamp scans keep mixed-format julianday() correctness and now use matching expression indexes for indexed range/order plans.
• Maintenance runs after summary-producing work.
• Retry state is preserved on failure.
• Read-vs-write path separation is covered by tests.
• No task/Cortex side effects are introduced.

Validation Evidence

• npm test -- --run test/observed-work-store.test.ts test/rollup-store-builder.test.ts test/task-bridge-suggestion-store.test.ts
• npm test
• npm run build
• git diff --check
• GitHub test check: success

Suggested Maintainer Review Path

1. Start with the Why Maintainers Should Care and How It Works sections.
2. Use Primary Review Files for the logical slice; the GitHub Files tab can look much larger because the public PRs target main while the series is logically stacked.
3. Check the non-goals before asking whether LCM should create tasks, close tasks, write Cortex memory, or make authoritative project claims.
4. Review and merge in the order shown in the stack diagram. feat: implement LCM architecture follow-up (draft) #526 stays draft/reference unless maintainers explicitly choose a single large integration branch.