PR #518: Task-bridge ledger: inert suggestion storage only

Maintainer Quick Read

Why Maintainers Should Care

This creates a ledger for possible task actions suggested from LCM evidence, but keeps the bridge inert. It is the audit trail and review state, not an automation engine.

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["Observed-work item"] --> B["Suggestion record"]
  B --> C["pending / accepted / rejected / dismissed / expired"]
  B --> D["rationale, confidence, source links"]
  C --> E["Reviewer/user decides outside LCM"]
  E -. "no task write here" .-> F["OpenClaw Tasks remains authority"]

What Ships In This PR

• task-bridge suggestion table/store
• source-linked suggestion records with confidence and rationale
• review states: pending, accepted, rejected, dismissed, expired
• upsert behavior that preserves reviewed rows, creator metadata, and review metadata
• tests for source requirements and ledger safety

What This PR Intentionally Does Not Do

• no direct OpenClaw task writes
• no automatic task creation or closure
• no runtime suggestion generation or review tool; feat: add opt-in LCM task suggestion tools (6/10) #539 adds opt-in tools later
• no reminders, wakes, Cortex sync, or default-on bridge behavior

How An Agent Uses It

• "Should we make a task from this observed blocker?" -> store a suggestion for human review, not a task mutation.
• "Was this suggestion reviewed?" -> read ledger status and metadata.
• "Can LCM auto-close a task?" -> no; task state remains outside LCM.

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/store/task-bridge-suggestion-store.ts
• src/db/migration.ts
• test/task-bridge-suggestion-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.
• Reviewed rows are protected from accidental reset on upsert.
• Creator/review metadata is preserved.
• Suggestions require source-backed provenance.
• No external task table/API writes are introduced.

Validation Evidence

• npm test -- --run test/task-bridge-suggestion-store.test.ts test/observed-work-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.