PR #539: Opt-in task suggestion tools over the inert ledger

Maintainer Quick Read

Why Maintainers Should Care

This adds optional tools for previewing, recording, and reviewing task suggestions, but only behind an explicit config gate. It keeps the bridge review-led and prevents LCM from becoming a background task writer.

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["taskBridgeToolsEnabled?" ] --> B{"enabled"}
  B -- "no" --> C["tools are not registered"]
  B -- "yes" --> D["preview suggestion"]
  D --> E{"record?"}
  E -- "no" --> F["dry-run output only"]
  E -- "yes" --> G["write suggestion ledger"]
  G --> H["review/dismiss/update ledger state"]
  H -. "never" .-> I["direct task write"]

What Ships In This PR

• config-gated task suggestion tools
• preview behavior that can stay dry-run
• record/review operations that only touch the suggestion ledger
• source/confidence/rationale validation
• tests proving no external task writes

What This PR Intentionally Does Not Do

• no default-on tools
• no automatic task creation/closure
• no reminders, wakes, or Cortex sync
• no direct OpenClaw task mutation

How An Agent Uses It

• A user asks "show me possible tasks from blockers" -> preview suggestions if tools are enabled.
• A reviewer chooses to record a suggestion -> ledger row is created, not an OpenClaw task.
• A reviewer rejects or dismisses -> only suggestion review state changes.

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/tools/lcm-task-suggestion-tools.ts
• src/plugin/index.ts
• src/store/task-bridge-suggestion-store.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.
• Tool registration is disabled by default.
• Preview and record paths are separate.
• Review actions mutate only the suggestion ledger.
• Negative tests cover no task-table/API writes.

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.