docs(reflect): convert design to KEP format

[samzong]

What's changed?

• Reframe the reflect extension design as a KEP-style proposal.
• Document personal/project scope defaults, TUI-first MVP behavior, and the instruction patch apply loop.
• Add risks, graduation criteria, production readiness notes, and alternatives.

Why

• Clarify the MVP contract for Reflect while keeping it as an extension-owned workflow over Recall's stable CLI protocol.

Verification

• git diff --cached --check
• git diff HEAD~1..HEAD --check
• awk 'length($0)>100 {print FILENAME ":" FNR ":" length($0) ":" $0}' docs/extensions/reflect.md\n- Pre-ship committed-diff review: no MUST-FIX findings.\n- Rust tests not run; documentation-only change.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ebd38f196e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Keep the documented default scope implementable

In the current extension, apply_default_scope in extensions/recall-reflect/src/main.rs always calls current_git_root() when neither --project nor --repo is present, and current_git_root() bails outside a worktree; the regression test reflect_cli_requires_explicit_scope_outside_git_worktree asserts this behavior. With this new rule, recall reflect outside a repo is documented as personal reflection, but today it exits with an error, so users/agents following the KEP get a non-working command unless the CLI changes or the default remains explicit-scope.

Useful? React with 👍 / 👎.

[zhexulong]

I read through this KEP version, and I think the personal + project split is the right direction.

The first recall-reflect implementation is definitely more repo/project-timeline oriented: it infers the current Git repository as scope, consumes metadata,messages, then builds a project timeline plus a very small pattern prompt layer. This KEP makes the product boundary clearer:

• personal reflection answers “how do I use coding agents across projects?”
• project reflection answers “how did work in this repo continue across sessions/agents?”

I suggest we avoid jumping directly to TUI/apply in the next implementation PR, because that would make the PR large and harder to review. I’d split the work into smaller steps:

1. Align the design doc first: keep the personal/project direction, but distinguish current MVP from next milestone so TUI/apply do not read as already-implemented behavior.
2. First implementation PR: add scope kind and --personal. Inside a Git repo, default to project reflection; outside a Git repo, default to personal reflection. Text/JSON output should both expose the selected scope kind.
3. Second implementation PR: add useful deterministic personal-report sections, such as source breakdown, active projects, task-shape signals, and cross-agent usage patterns.
4. Third implementation PR: enrich project observations, e.g. verification reminders, handoff/continuation, and repeated correction signals.
5. Later milestone: build the TUI workbench and instruction patch preview/apply loop.

That lets us make the personal view real quickly while keeping the extension boundary clean: Reflect continues to consume Recall through recall export --include metadata,messages, does not read SQLite directly, and does not push workflow-engine behavior into core.

[zhexulong]

Note on merge method: PR #107 was accidentally merged with a regular merge commit instead of the repo-preferred squash merge. The code and checks are fine, but the merge method was not the intended one.\n\nI prepared an equivalent squash replacement commit with the same final tree and tried the safe correction path with --force-with-lease, but branch protection correctly blocks force-pushing main, so I left main unchanged.\n\nGoing forward, I’ll use squash merge for Recall PRs by default to keep the main history consistent.