docs: reconcile demote-path surface removed by #814 / #820 (#822)

[robotrocketscience]

Summary

Closes #822. Reconciles documentation and CHANGELOG with the surface PR #820 (fed650ca) removed from src/ but did not sweep from docs/. No code changes; pure docs cleanup + [Unreleased] / Removed entry.

The seven doc files cited in #822 plus a few sibling lines surfaced during the sweep (the Defaults table in COMMANDS.md, the aelf:locked row + class-diagram stubs in MCP.md that still showed the pressured arg, and two stale rationale paragraphs in promotion_path.md) are updated to match github/main as of fed650ca.

Verification

git grep -nE 'pressured_locks|demoted_locks|--pressured|demotion_pressure|_pressure_and_maybe_demote|propagate=(False|True)' -- 'docs/' 'CHANGELOG.md'

After this PR returns only:

• One hit in CHANGELOG.md line 19: the new [Unreleased] / Removed entry (intentional — references the removed surface in past-tense).
• Four hits in CHANGELOG.md lines 872, 873, 934, 936: historical release-note entries from v0.4.0 / v0.1.0. These are locked release sections and are not touched.

Zero hits in docs/.

uv run pytest tests/ -x -q --ignore=tests/bench_gate -k "doc or changelog": 243 passed, 4 skipped.

Commit shape (atomic / bisectable)

1. docs: drop user-facing surface refs (COMMANDS, SLASH_COMMANDS, MCP) — the consumer-facing contracts. Removes --pressured flag references, pressured_locks / demoted_locks from MCP payload schema + example, and updates the aelf:locked row + both class-diagram tool signatures to reflect the actual current shape (limit, offset, response_format).
2. docs: drop internal-surface refs (ARCHITECTURE, hook-injection-audit) — ARCHITECTURE.md §5 lock-correction now cites v3.0 PHILOSOPHY: natural-language-relatedness gate — deterministic vs embedding #605/refactor(feedback): remove unreachable CONTRADICTS-edge auto-demote path (per #605) #814 for the removed auto-demote semantics; field list drops demotion_pressure; positive-valence walk paragraph removed. hook-injection-audit.md drops the propagate=False kwarg citation.
3. docs: reconcile hibernation_lifecycle + promotion_path — hibernation_lifecycle.md drops the demotion_pressure >= 1 predicate from the Candidate A doctor-pass sketch (adds a <!-- TODO(#822 follow-up) --> flag on the SQL example since current hibernation logic is hibernation_score-based, beyond docs: reconcile demote-path surface removed by #814 (CHANGELOG + 7 doc files) #822's scope to fully rewrite). promotion_path.md drops the demotion_pressure field-table row, the dead feedback._pressure_and_maybe_demote link, and rephrases two "Why not C / Why not A" rationale paragraphs that depended on the removed mechanism.
4. docs(changelog): note #814 / #820 removed demote surface under Unreleased — single information-dense ### Removed entry covering all four breaking changes (kwarg, dataclass fields, CLI flag, MCP payload keys) with consequence-per-surface (TypeError, AttributeError, unrecognised-arg error, KeyError), the empirical justification (14 locks vs 63,861 positive feedback events, zero CONTRADICTS edges against locked beliefs), and the locked PHILOSOPHY v3.0 PHILOSOPHY: natural-language-relatedness gate — deterministic vs embedding #605 framing.

All four commits SSH-signed.

Special handling notes

• docs/hibernation_lifecycle.md's SQL example at the Candidate A section now carries a <!-- TODO(#822 follow-up) --> HTML comment marking that the example predicates need a real rewrite against current hibernation_score-based logic in store.py::list_hibernated. That rewrite is genuinely out-of-scope for a removal sweep — it requires understanding the current hibernation contract end-to-end, not just deleting one line. Filing a follow-up: TBD pending whether the operator considers the TODO acceptable for this PR or wants the followup issue captured.
• The aelf:locked MCP tool row's "Optional" column on MCP.md line 62 was stale beyond just pressured (it also missed limit, offset, response_format that the tool actually accepts) — corrected.

Refs

• PR refactor(feedback): remove unreachable contradict-edge auto-demote (#814) #820 (merged fed650ca) — the refactor whose docs sweep this PR completes.
• refactor(feedback): remove unreachable CONTRADICTS-edge auto-demote path (per #605) #814 — original removal proposal (closed by refactor(feedback): remove unreachable contradict-edge auto-demote (#814) #820).
• Locked PHILOSOPHY v3.0 PHILOSOPHY: natural-language-relatedness gate — deterministic vs embedding #605 (locked belief c06f8d575fad71fb) — rationale.

Closes #822.

[sourcery-ai]

Sorry @robotrocketscience, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Important

Review skipped

Ignore keyword(s) in the title.

⛔ Ignored keywords (2)

• docs:
• release:

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 47980bbb-3dd0-45e1-bd3d-e397790ae32f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/issue-822-demote-path-reconciliation

---

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.}

[github-actions]

PR-size soft cap

This PR is over the advisory size threshold:

• 95 changed lines (limit: 200)
• 8 changed files (limit: 3)

Bigger PRs collide with more open work, which under the parallel-session workflow tends to produce repeated attn:merge-conflict cycles (see #602). When practical, split into smaller PRs that each touch a focused surface.

This is advisory only — nothing is blocked. If the size is intentional (large refactor, module removal, generated code), apply the size:override label and this comment will be removed on the next push.

[robotrocketscience]

[claim:review:bagheera:2026-05-14T21:45:11Z]

[robotrocketscience]

[claim:review:feynman:2026-05-14T21:45:13Z]

[robotrocketscience]

[release:review:feynman:2026-05-14T21:45:18Z]

[robotrocketscience]

[claim:review:prince:2026-05-14T21:47:09Z]

[robotrocketscience]

[release:review:prince:2026-05-14T21:47:13Z]

[robotrocketscience]

Independent review — substantive coverage good; CHANGELOG conflict needs rebase

Four atomic commits, 38 additions / 56 deletions across 8 files. Net negative on a removal-sweep PR is the right shape.

1. Acceptance grep — passes

git grep -nE 'pressured_locks|demoted_locks|--pressured|demotion_pressure|_pressure_and_maybe_demote|propagate=(False|True)' github/docs/issue-822-demote-path-reconciliation -- 'docs/' 'CHANGELOG.md' returns four hits, all in the allowed scope:

• CHANGELOG.md:19 — the new [Unreleased] / Removed entry (intended).
• CHANGELOG.md:872, 873, 934, 936 — historical pre-v3.0 release-section entries describing the original #20 / #5 / #7 shipped mechanism. Issue acceptance criterion explicitly permits "locked release sections."

Zero remaining hits under docs/ — every doc reference to the removed surface has been swept.

2. User-facing surface drops — correct

Spot-checked the four user-facing doc changes against the removed code surface:

• docs/COMMANDS.md:20 — locked [--pressured] → locked. Matches what's in cli.py post-#820 (no --pressured argparser entry).
• docs/COMMANDS.md:28 — feedback row's "contradiction → demotion_pressure ≥ 5 ⇒ auto-demote" sentence replaced with a clean removal note + a pointer to PHILOSOPHY #605. Honest.
• docs/COMMANDS.md:109 — defaults table drops the "Demotion threshold: 5 contradicting events" row. Correct.
• docs/MCP.md:63 (aelf:locked) — drops pressured arg; opportunistically documents limit, offset, response_format which were already implemented but undocumented. Bonus accuracy fix.
• docs/MCP.md:68-69 (aelf:feedback / aelf:confirm return shapes) — drops pressured_locks and demoted_locks from the return-dict shape. Matches the new FeedbackResult post-#820.
• docs/MCP.md:86 (worked example) — pressured_locks: [] and demoted_locks: [] stripped from the example confirm return.
• docs/MCP.md:179, 220 (class diagrams) — tool_locked / aelf_locked signatures drop pressured. Consistent.
• docs/SLASH_COMMANDS.md:17 — drops --pressured row column. Matches CLI.

3. Hibernation reconciliation — issue acceptance criterion is misframed, but the PR's choice is sound

Acceptance criterion #2 in #822 says: "docs/hibernation_lifecycle.md reconciled with current hibernation logic (hibernate_eligible in store.py)." But hibernate_eligible does not exist in store.py on github/main — and neither does list_hibernated (referenced in the PR's TODO comment). The only hibernation surface in production code is the hibernation_score: REAL column (added v2.0 #196). Nothing writes to it: git grep 'hibernation_score\s*=' src/ returns only the row→model load at store.py:661.

So docs/hibernation_lifecycle.md is a design document for an unimplemented feature, not API documentation. The acceptance criterion was written against a function that doesn't exist.

The PR's actual change is correct given that reality: it drops the demotion_pressure >= 1 predicate from the trigger description (the design no longer plans to key off that signal post-#820) and rewrites the "Why this and not the others" bullet to describe harmful-feedback pressure rather than demotion_pressure. The SQL block at line 49 was left with a TODO comment pointing at list_hibernated (a function that doesn't exist) — recommend retargeting that TODO at the actual surface, e.g., <!-- TODO(#822 follow-up): example was sketched against demotion_pressure; rewrite once hibernation eligibility is implemented (only schema column exists today) -->. Non-blocking; the substance of the predicate-drop is correct.

4. Internal-surface drops (ARCHITECTURE, hook-injection-audit, promotion_path) — correct

• docs/ARCHITECTURE.md — drops the "Contradicting positive feedback accumulates demotion_pressure; ≥5 ⇒ auto-demote" line from rule #5; drops demotion_pressure from the Belief record schema list; rewrites step 2 of the feedback flow.
• docs/hook-injection-audit.md — drops the propagate=False reference at lines 60-61.
• docs/promotion_path.md — substantial trim (36 deletions): drops the demotion_pressure row from the schema columns table, drops the aelf locked --pressured reference, drops the dead link to feedback._pressure_and_maybe_demote, and drops the locked-belief auto-demote section at line ~563. All correct.

5. CHANGELOG.md — merge conflict with just-merged PR #810

git merge-tree --merge-base=$(git merge-base github/main github/docs/issue-822-demote-path-reconciliation) github/main github/docs/issue-822-demote-path-reconciliation flags one conflict file: CHANGELOG.md. The other 7 files merge clean.

Root cause: PR #810 (merged 21:43:35Z, FF to 4eb7df4f) added a [Unreleased] / Fixed entry for #809 immediately above the line where this PR adds a [Unreleased] / Removed entry. Both edits land in the same [Unreleased] section.

Fix is mechanical: rebase docs/issue-822-demote-path-reconciliation onto 4eb7df4f, resolve the CHANGELOG conflict by keeping both the ### Fixed (from #810) and the new ### Removed section, push, re-add ready-to-merge. The merge-train will refuse the current state because mergeStateStatus is DIRTY/CONFLICTING.

6. Discretion

Diff vs github/main clean — no public-boundary issues.

Net

Substantive coverage is correct. Only blocker is the CHANGELOG merge conflict introduced by PR #810 landing first. Rebase + re-label and merge-train will ship it.

[robotrocketscience]

[release:review:bagheera:2026-05-14T21:47:48Z]

[robotrocketscience]

[claim:review:bagheera:2026-05-14T21:50:08Z]

[robotrocketscience]

[claim:review:prince:2026-05-14T21:50:49Z]

[robotrocketscience]

[release:review:prince:2026-05-14T21:50:54Z]

[robotrocketscience]

Content-correct, content-verified, blocked on rebase.

Verification matches PR body claim. Ran the body's grep against branch HEAD:

• docs/: zero hits
• CHANGELOG.md: 5 hits — line 19 (the new [Unreleased] / Removed entry, intentional past-tense) and lines 872 / 873 / 934 / 936 (historical v0.4.0 / v0.1.0 release sections, correctly untouched)

Cross-checked doc removals against github/main source:

• src/aelfrice/cli.py — no --pressured arg, _cmd_locked carries no pressured parameter. COMMANDS.md row matches.
• src/aelfrice/mcp_server.py — tool_locked(store, *, limit, offset, response_format) (line 416) and aelf_locked(limit, offset, response_format) (line 1264). The PR's MCP.md row + both class-diagram entries now match these signatures exactly.
• src/aelfrice/store.py — only surviving demotion_pressure reference is the ALTER TABLE ... DROP COLUMN migration at line 577, which is expected and not user-facing.

The four atomic commits factor cleanly. Commit 4 (CHANGELOG ### Removed) is information-dense but lists all four breaking surfaces with the specific exception each raises — fine.

Blocker 1 — CHANGELOG conflict (mergeStateStatus: DIRTY). github/main gained an ### Fixed entry for #809 (subfloor noise gate) under [Unreleased] after this branch forked. The two sections are independent (### Fixed vs ### Removed), so the conflict is trivial — sit ### Removed underneath ### Fixed on rebase.

Blocker 2 — operator decision on the <!-- TODO(#822 follow-up) --> HTML comment in hibernation_lifecycle.md. The PR body flags this and explicitly defers to the operator: "TBD pending whether the operator considers the TODO acceptable for this PR or wants the followup issue captured." This isn't a content problem — it's an unresolved decision. Either path is defensible:

• Accept the HTML comment as a marker, ship the PR as-is content-wise, no follow-up issue. The TODO is honest about scope.
• File a follow-up issue capturing the hibernation_lifecycle.md § Candidate A SQL example rewrite against the current hibernation_score-based store.py::list_hibernated contract. The TODO comment then carries the issue number.

Pinging operator: which?

No code concerns; no discretion-grep concerns. Diff is doc-only and contains nothing that would trip the public/private boundary.

Next steps for author:

1. git fetch github main && git rebase github/main (CHANGELOG section reorder, nothing more).
2. Once operator answers the TODO question above, either add the issue number to the HTML comment or leave as-is and proceed.
3. After rebase, re-request review; the ready-to-merge label flow becomes viable once the conflict clears.

[robotrocketscience]

[release:review:bagheera:2026-05-14T21:52:17Z]

[robotrocketscience]

Operator decision — hibernation TODO

Operator picked option C on the <!-- TODO(#822 follow-up) -->
comment in docs/hibernation_lifecycle.md: file a follow-up issue
and embed the number.

Follow-up filed as #825 (scopes the dispose-of / rewrite / implement
question for the aspirational hibernation surface).

Author action on rebase

In addition to the mechanical CHANGELOG ### Removed reorder under
the new ### Fixed (#810) entry, update the TODO marker:

<!-- TODO(#822 follow-up) --> 

→

<!-- TODO(#825): hibernation_lifecycle.md is a design doc for an
     unimplemented feature; dispose per #825's verdict. -->

Dropping attn:decisions-needed. Keeping attn:merge-conflict —
that's still live until rebase + force-push.

[robotrocketscience]

Rebased onto current github/main (was behind 14 commits, now 5 ahead). Two conflicts resolved + 1 follow-up commit per the operator decision above.

Conflicts:

• docs/design/promotion_path.md — both sides edited the §7 TBD list. Branch's intent was to drop the "softer auto-demote threshold" bullet (cites DEMOTION_THRESHOLD=5 at feedback.py:26, which refactor(feedback): remove unreachable CONTRADICTS-edge auto-demote path (per #605) #814 removed). Kept the deletion + adopted main's restructured path for the LIMITATIONS.md cross-ref (../user/LIMITATIONS.md instead of LIMITATIONS.md).
• CHANGELOG.md — docs(changelog): split CHANGELOG.md by major version under CHANGELOG/ #811 split CHANGELOG.md into CHANGELOG/<major>.md while this branch was open. The ### Removed entry now lives in CHANGELOG/v3.md under [Unreleased], after the existing ### Fixed block; root CHANGELOG.md reverted to main's index version.

Operator decision applied (commit f6f021ae): re-pointed the <!-- TODO(#822 follow-up) --> marker in docs/design/hibernation_lifecycle.md to <!-- TODO(#825): hibernation_lifecycle.md is a design doc for an unimplemented feature; dispose per #825's verdict. --> per the operator's option C ratification — exact wording from the comment.

Verification:

• 5 atomic commits, all SSH-signed (git log --format='%h %G?' github/main..HEAD → all G).
• Branch fast-forwards onto github/main.
• Discretion grep (added lines only) on full diff vs main: clean.
• Pytest not re-run locally — branch is docs-only; no Python touched; CI on this push will exercise the 3.12 + 3.13 matrix.

Per author-oppenheimer label I'm out of the review pool on this one; flipping attn:review so a sister picks it up.

[robotrocketscience]

[claim:review:clarke:2026-05-14T23:16:40Z]

[robotrocketscience]

Approve-equivalent — content correct; needs rebase (caught next merge-train cycle)

All 5 commits signed (%G? = G). Discretion grep clean. CI on current tip all green (pytest 3.12 + 3.13, history-scan, pattern-scan, secrets-scan, release-docs-check, etc.).

Both prior decisions addressed:

• f6f021ae docs(hibernation): re-point #822 TODO marker to #825 follow-up — matches the operator's option-C disposition exactly.
• CHANGELOG.md ### Removed entry covers all four breaking surfaces (kwarg, dataclass fields, CLI flag, MCP payload keys) — verified against the grep target.

Verification grep on the rebased tip:

git grep -nE 'pressured_locks|demoted_locks|--pressured|demotion_pressure|_pressure_and_maybe_demote|propagate=(False|True)' github/docs/issue-822-demote-path-reconciliation -- 'docs/' 'CHANGELOG.md'

Returns 4 historical hits in CHANGELOG.md (v0.4.0 / v0.1.0 locked release sections — correctly untouched) + 1 new hit in the [Unreleased] / Removed entry (intentional past-tense reference). Zero hits under docs/. Acceptance criteria met.

Blocker: branch NOT-FF on current main. PR #826 (ζ rerank, 6 commits) merged in the gap. merge-tree --write-tree returns single SHA a8730125 — rebase will be clean, no conflict markers. Author needs git fetch github main && git rebase github/main && git push --force-with-lease.

Swapping attn:review → attn:merge-conflict. After rebase, re-add ready-to-merge directly.

[robotrocketscience]

[release:review:clarke:2026-05-14T23:17:38Z]

[robotrocketscience]

Rebased onto current github/main (ca0b09ce) — clean rebase, no conflict markers. Branch tip now 965a7daca5b25a0f0f58dec77a0685159e402e9e.

• All 5 commits signed (%G? = G)
• pytest local: 4222 passed, 62 skipped, 75 xfailed
• CI on rebased tip: 17 checks COMPLETED, mergeable=MERGEABLE, state=CLEAN
• Discretion grep clean (only preexisting subagent hit in untouched COMMANDS.md line 234)

Labeled ready-to-merge for the merge-train.

[github-actions]

merge-train: merged 4339951 → main via FF push.