feat(doctor): document + flag missing v2.1 auto-capture hooks (#557)

[robotrocketscience]

Closes #557.

What

Two surface fixes for the v2.1 default-on auto-capture pipeline (#529, shipped today in v2.1.0).

A — README messaging (c782497). The What it remembers table at README:66-75 listed only manual inputs (aelf lock, aelf onboard, aelf feedback); a model reading the README inferred aelfrice was for user-locked rules only. Adds a passive-capture row to the table and a Passive capture bullet to What you get for free, both pointing at docs/INSTALL.md for the full hook table and per-hook opt-out flags.

B — aelf doctor nag (b9ee58e). Pre-v2.1 installs that already ran aelf setup have retrieval-only wiring; aelf upgrade-cmd does not re-run setup. Doctor now scans the findings list and reports any of aelf-transcript-logger, aelf-commit-ingest, aelf-session-start-hook that are absent from every scanned settings.json, with a one-line nag pointing to aelf setup. Substring match on the basename so PATH-resolved (pipx) and absolute-path (venv) installs both count as present. Quiet when no settings.json was scanned (existing no-scopes message already covers that) and when every default-on hook is present.

Out of scope

A third proposed fix (LIMITATIONS.md § Out of scope entry rejecting checkpoint-event memory as a primitive) was dropped per maintainer direction — that's a design call for a later release, not part of #557's surface.

Verification

• uv run pytest tests/test_doctor.py — 20 passed (15 prior + 5 new). The new tests cover: pre-v2.1 install (all three hooks missing → nag fires), fresh v2.1 install (all present → quiet), partial install (only the missing two listed), no-settings.json (quiet), and a guardrail asserting doctor's hardcoded basename list matches the aelfrice.setup constants.
• README diff renders cleanly on GitHub (table + bullet); manual scan.

Diagnostic

Posted at #557 (comment) before implementation; confirms three-way root cause (README mismatch, no upgrade nag, decision-event memory out of scope) and the A+B+C disposition options. Maintainer picked A+B.

Summary by Sourcery

Document v2.1’s default-on auto-capture behavior and add an aelf doctor check that warns when the new auto-capture hooks are missing after upgrades from pre-v2.1 installs.

New Features:

• Extend aelf doctor to detect missing default-on auto-capture hooks and emit a guided message to re-run setup when they are absent.

Documentation:

• Update README and changelog to describe v2.1’s default-on passive capture hooks, opt-out flags, and installation behavior.

Tests:

• Add unit tests covering auto-capture hook detection in aelf doctor, including pre-v2.1 installs, fully wired installs, partial installs, no-settings cases, and a guardrail that keeps the doctor’s hook list in sync with setup.

[sourcery-ai]

Reviewer's Guide

Implements a v2.1-aware aelf doctor check that detects missing default-on auto-capture hooks for upgraded installs and surfaces a concise remediation message, while updating README and CHANGELOG to accurately describe passive auto-capture behavior and configuration options.

Sequence diagram for aelf doctor detecting missing auto-capture hooks

sequenceDiagram
    actor User
    participant AelfCLI
    participant DoctorModule
    participant SettingsJson
    participant SetupCommand

    User->>AelfCLI: run aelf doctor
    AelfCLI->>DoctorModule: diagnose()
    DoctorModule->>SettingsJson: scan settings.json for hook commands
    SettingsJson-->>DoctorModule: findings list
    DoctorModule->>DoctorModule: _check_auto_capture_hooks(findings)
    DoctorModule-->>DoctorModule: missing_auto_capture_hooks list
    DoctorModule->>DoctorModule: format_report(report)
    DoctorModule->>DoctorModule: _format_missing_auto_capture_section(report, lines)
    alt some hooks missing
        DoctorModule-->>AelfCLI: report with auto-capture nag
        AelfCLI-->>User: show nag and remediation message
        User->>AelfCLI: run aelf setup
        AelfCLI->>SetupCommand: setup()
        SetupCommand->>SettingsJson: write auto-capture hook commands
        SettingsJson-->>SetupCommand: updated settings
        User->>AelfCLI: run aelf doctor
        AelfCLI->>DoctorModule: diagnose()
        DoctorModule->>SettingsJson: rescan settings.json
        SettingsJson-->>DoctorModule: findings list with hooks
        DoctorModule->>DoctorModule: _check_auto_capture_hooks(findings)
        DoctorModule-->>DoctorModule: empty missing_auto_capture_hooks
        DoctorModule-->>AelfCLI: clean report
        AelfCLI-->>User: show no auto-capture nag
    else no hooks missing
        DoctorModule-->>AelfCLI: clean report
        AelfCLI-->>User: show no auto-capture nag
    end

Loading

Class diagram for updated DoctorReport auto-capture tracking

classDiagram
    class DoctorReport {
        +list~str~ missing_runtime_deps
        +list~str~ missing_auto_capture_hooks
        +property broken list~CommandFinding~
    }

    class CommandFinding {
    }

    DoctorReport --> CommandFinding : uses_in_broken_and_findings

Loading

File-Level Changes

Change	Details	Files
Extend doctor diagnostics to detect and report missing default-on auto-capture hooks for pre-v2.1-style installations.	Add missing_auto_capture_hooks field to DoctorReport to track absent default-on hook basenames across scanned settings scopes. Introduce _AUTO_CAPTURE_HOOK_BASENAMES constant and _check_auto_capture_hooks() helper that substring-matches hook basenames against CommandFinding.command values to support both PATH-resolved and absolute-path installs. Wire _check_auto_capture_hooks() into diagnose() to populate the new field based on existing findings and add _format_missing_auto_capture_section() to render a short nag block recommending re-running aelf setup with optional per-hook opt-out flags, while remaining quiet when no scopes are scanned or all hooks are present.	src/aelfrice/doctor.py
Add test coverage for the new auto-capture hook diagnostics behavior and guardrail against drift with setup hook naming.	Add tests for pre-v2.1 installs where all three auto-capture hooks are missing, verifying both the missing_auto_capture_hooks list and the rendered nag message. Add tests for fully wired v2.1 installs, partial installs, and the no-settings.json case to ensure the doctor output is appropriately quiet or selective. Add a guardrail test that asserts the doctor module’s _AUTO_CAPTURE_HOOK_BASENAMES stays in sync with the corresponding script name constants in aelfrice.setup.	tests/test_doctor.py
Update documentation to describe default-on passive auto-capture behavior and doctor’s new upgrade warning.	Update README’s What it remembers table and What you get for free section to add a passive capture row/bullet that explains default-on transcript, commit, and session-start hooks and how to opt out via aelf setup flags, linking to INSTALL hook docs. Document the new aelf doctor auto-capture hook warning and the README clarification under the Added/Documentation sections of CHANGELOG for the relevant release.	README.md CHANGELOG.md

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#557	Document that aelf supports default-on passive auto-capture (beyond manual preference/feedback commands) so models and users understand it remembers more than user-locked rules.	✅
#557	Ensure pre-v2.1 installs that upgraded without re-running aelf setup are warned when default-on auto-capture hooks are missing, so passive capture is actually wired and functioning.	✅
#557	Add a new checkpoint-style memory primitive so Claude can explicitly record and recall decision/checkpoint events (not just preferences or passively captured data).	❌	The PR explicitly states that a proposed LIMITATIONS entry rejecting checkpoint-event memory as a primitive was dropped as out-of-scope by maintainers, and no code or docs changes implement a new checkpoint memory primitive.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[coderabbitai]

Warning

Rate limit exceeded

@robotrocketscience has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 51 minutes and 43 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 4edfc7b2-ac56-4be2-a89f-64a1a5734a26

📥 Commits

Reviewing files that changed from the base of the PR and between bfc7d23 and 6210caa.

⛔ Files ignored due to path filters (1)

• CHANGELOG.md is excluded by !**/CHANGELOG.md

📒 Files selected for processing (3)

• README.md
• src/aelfrice/doctor.py
• tests/test_doctor.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/issue-557-readme-autocapture

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[robotrocketscience]

[claim:review:rogue1:2026-05-10T05:16:06Z]

[sourcery-ai]

Hey - I've left some high level feedback:

• The _check_auto_capture_hooks implementation relies on a substring search (basename in f.command), which could produce false positives if commands contain those strings as arguments; consider normalizing to the executable name (e.g., splitting on whitespace and comparing Path(part).name) instead.
• The formatted auto-capture nag text hardcodes the three hook names separately from _AUTO_CAPTURE_HOOK_BASENAMES; it might be more robust to derive the human-facing list from the same constant to avoid drift if names change.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The `_check_auto_capture_hooks` implementation relies on a substring search (`basename in f.command`), which could produce false positives if commands contain those strings as arguments; consider normalizing to the executable name (e.g., splitting on whitespace and comparing `Path(part).name`) instead.
- The formatted auto-capture nag text hardcodes the three hook names separately from `_AUTO_CAPTURE_HOOK_BASENAMES`; it might be more robust to derive the human-facing list from the same constant to avoid drift if names change.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[robotrocketscience]

Verdict: changes requested — one CI blocker (title prefix), one mechanical fix (rebase). Substance is good.

Substance — good to ship once mechanics clear

• 4 files, +200/0, all additive. Discretion grep clean. All 3 commits signed (G).
• README change is exactly the row + bullet the issue diagnostic asked for. Pointer to docs/INSTALL.md keeps the README terse.
• aelf doctor nag wires correctly: _AUTO_CAPTURE_HOOK_BASENAMES is duplicated from setup constants with the guardrail test (test_auto_capture_basenames_match_setup) keeping them in sync. Substring match handles both PATH-resolved (pipx) and absolute-path (venv) installs — docstring explains why explicitly. Quiet when no settings scanned (covered by upstream no-scopes message) and when all hooks present (no false positive on fresh v2.1 installs).
• Test coverage: 5 new cases in tests/test_doctor.py cover pre-v2.1 partial install, fresh v2.1 install, partial-install (only the missing two listed), no-settings.json (quiet), and the basename-vs-setup guardrail.
• findings: list[CommandFinding] is mutated downstream; _check_auto_capture_hooks only reads, so no aliasing issue. Good.

Blockers

1. CI failure: pr-title-prefix. Title is feat(doctor)+docs(readme): … — compound prefix. Per ~/.claude/CLAUDE.md's conventional-commits policy, one type prefix per PR. The substantive change here is the doctor nag (new code + tests); README + CHANGELOG are supporting. Suggest renaming to:

   feat(doctor): nag when v2.1 default-on auto-capture hooks are missing (#557)
   

   The README/changelog additions are scope-of-change for the same issue and don't need their own prefix.

2. Branch needs rebase. git merge-base --is-ancestor github/main github/docs/issue-557-readme-autocapture is false. Run git rebase github/main and force-with-lease. After rebase, the title fix re-runs CI; once green, this is mergeable.

Note on the staging-gate cancellations

The CANCELLED rows on secrets-scan, pattern-scan, history-scan, commit-msg-prefix, pr-body-issue-link, release-docs-check are from the previous push being preempted by the new one. Latest run shows them as SUCCESS. Not a blocker.

After fix

When ready to merge: aelf-pr-open should already have prevented the rebase issue, but a manual git rebase github/main && git push --force-with-lease is the fix here. Drop the new commit if it doesn't add anything; the three commits already split the README, the doctor change, and the changelog cleanly — leave them as-is.

[robotrocketscience]

[release:review:rogue1:2026-05-10T05:17:28Z]

[robotrocketscience]

[claim:review:planck:2026-05-10T05:17:35Z]

[robotrocketscience]

Reviewed — code is solid, two mechanical blockers before merge.

Code review: ✅ approved.

• _check_auto_capture_hooks uses substring match on finding.command so both PATH-resolved (pipx) and absolute-path (venv) installs count as present — correct.
• _format_missing_auto_capture_section is appropriately quiet (no scopes scanned → no message; all hooks present → no message). Only nags when there's actually a partial install.
• _AUTO_CAPTURE_HOOK_BASENAMES is duplicated from setup constants with a guardrail test (test_auto_capture_basenames_match_setup) catching drift — acceptable trade-off to keep doctor dep-free of setup's install primitives.
• README additions (passive-capture row + bullet) point at docs/INSTALL.md for the full hook table — good separation, doesn't bloat the README.
• Discretion grep clean. All commits signed.

Blockers:

1. Title fails pr-title-prefix CI check. Current title feat(doctor)+docs(readme): document + flag missing v2.1 auto-capture hooks (#557) uses two conventional prefixes joined by +, which the prefix allowlist doesn't permit. Suggest feat(doctor): document + nag missing v2.1 auto-capture hooks (#557) — the doctor surface is the dominant change and the README addition is part of the same fix. Underlying commits are correctly single-prefixed (docs(readme), feat(doctor), docs(changelog)) — just the PR title needs a retitle.

2. Branch needs rebase on github/main. feat(wonder): wonder_ingest + wonder_gc lifecycle (closes #229, #548) #559 and test(session_id): ≥80% population guard via two-session ingest run (#554) #561 landed during review.

Author, please retitle (gh pr edit 560 --title '...') and rebase. Will re-review.

Released claim. Setting attn:merge-conflict.

— planck

[github-actions]

This PR is now behind main. Rebase locally so your commit signatures stay intact:

git fetch origin && git checkout 'docs/issue-557-readme-autocapture' && git rebase origin/main
# resolve conflicts if any, then
git push --force-with-lease

Auto-rebase was removed because the bot has no signing key; rebasing as the bot strips author signatures and the required_signatures rule on main then blocks the merge. See #341.

[robotrocketscience]

[claim:review:Maxwell:2026-05-10T05:19:07Z]

[robotrocketscience]

[release:review:planck:2026-05-10T05:19:11Z]

[robotrocketscience]

[release:review:Maxwell:2026-05-10T05:19:12Z]

[robotrocketscience]

Took over to unblock. Rebased onto github/main (no conflicts; 3 commits, all signed), title renamed to a single conventional prefix (feat(doctor):), and re-flagged for review.

Verification:

• uv run pytest -q --ignore=tests/e2e → 3125 passed, 53 skipped
• uv run pytest tests/test_doctor.py -x -q → 20 passed
• discretion grep clean

[github-actions]

This PR is now behind main. Rebase locally so your commit signatures stay intact:

git fetch origin && git checkout 'docs/issue-557-readme-autocapture' && git rebase origin/main
# resolve conflicts if any, then
git push --force-with-lease

Auto-rebase was removed because the bot has no signing key; rebasing as the bot strips author signatures and the required_signatures rule on main then blocks the merge. See #341.

[robotrocketscience]

[claim:review:einstein:2026-05-10T05:53:35Z]

[robotrocketscience]

[release:review:einstein:2026-05-10T05:54:16Z]

[robotrocketscience]

[claim:review:einstein:2026-05-10T05:57:03Z]

[robotrocketscience]

[claim:review:Maxwell:2026-05-10T05:57:25Z]

[robotrocketscience]

[release:review:Maxwell:2026-05-10T05:57:30Z]

[github-actions]

This PR is now behind main. Rebase locally so your commit signatures stay intact:

git fetch origin && git checkout 'docs/issue-557-readme-autocapture' && git rebase origin/main
# resolve conflicts if any, then
git push --force-with-lease

Auto-rebase was removed because the bot has no signing key; rebasing as the bot strips author signatures and the required_signatures rule on main then blocks the merge. See #341.

[robotrocketscience]

[claim:review:leibniz:2026-05-10T06:02:32Z]

[robotrocketscience]

[release:review:leibniz:2026-05-10T06:02:37Z]

[robotrocketscience]

Reviewed and merged. Substance was already approved by prior reviewers; mechanical state was rebase-needed (the prior rebase landed before #555/#566 hit main). Re-rebased onto github/main (no conflicts; new test file from #555 doesn't overlap), all 3 commits signed (G), full CI green on the new push (pytest 3.12 + 3.13, CodeQL python + actions, pattern-scan, secrets-scan, history-scan, deptry, vulture, all gate workflows). Discretion grep clean. FF-pushed to main: 6210caa.

[robotrocketscience]

[release:review:einstein:2026-05-10T06:05:08Z]

[robotrocketscience]

[claim:review:faraday:2026-05-10T06:05:09Z]

[robotrocketscience]

[release:review:faraday:2026-05-10T06:06:08Z]