feat(sentiment-hook): production wire-up of sentiment-feedback into UPS lane (closes #606)

[robotrocketscience]

Closes #606.

What this does

Wires the v2.0 sentiment_feedback module into a live UserPromptSubmit hook lane. Before each turn's retrieval, the lane reads the most-recent prior UPS audit row for the same session_id, projects its beliefs[*].id, and — if detect_sentiment matches the prompt — applies the signal (positive / negative, base / strong, escalated) to those beliefs via apply_sentiment_to_pending. Bumped posteriors are reflected in this turn's retrieval, so a "no, that's wrong" prompt demotes the offending belief before the next block is built.

How the decisions came out

Captured in docs/v3_sentiment_feedback_hook.md. Summary:

• Hook lane: UserPromptSubmit. The corrective prompt arrives after the assistant has acted on the prior retrieval block; applying it at the next UPS keeps the bump in lockstep with the retrieval window it's correcting.
• Window: the most-recent prior UPS audit row for the same session_id. Single-session for v3.0; cross-session propagation is explicit follow-up.
• Audit surface: new tag sentiment_feedback written to the existing hook_audit.jsonl, carrying pattern, matched_text, valence, belief_ids. The per-belief feedback_history rows continue to carry source = sentiment_inferred (unchanged from v2.0).
• Opt-in: single flag [feedback] sentiment_from_prose = true in .aelfrice.toml (or the existing env var). Default off — no behavior change for users who haven't opted in.
• Privacy: no new prose-data surface. UPS already reads every prompt; the lane does additional processing on data already in the hook's hands. Audit row stores the matched pattern + a bounded substring, never the full prompt.

Commits

1. docs(sentiment-hook): v3.0 spec for #606 production wire-up — decision memo.
2. feat(sentiment-hook): wire detect_sentiment into UPS lane — apply_sentiment_feedback + two helpers (_load_aelfrice_toml, _load_prior_ups_belief_ids) + new audit tag + wiring into user_prompt_submit before retrieval.
3. test(sentiment-hook): unit + two-session bench fixture — 16 tests covering the disabled gate, no-signal short-circuit, no-prior-UPS short-circuit, posterior demotion, audit-row schema, missing-belief skip, UPS-integration paths, and the AC4 two-session ranking fixture.
4. docs(changelog): unreleased entry.

#606 acceptance mapping

AC	Where
1. Spec memo + hook lane + decay policy	docs/v3_sentiment_feedback_hook.md
2. Determinism (stdlib regex)	regex only; no LLM / embedding; same-input → same-output asserted by test
3. Privacy (no new PII surface)	audit row stores pattern + bounded substring; full prompt cap reused; _disable_sentiment path verified
4. Two-session bench fixture	test_correction_lowers_subsequent_ranking_across_sessions
5. Audit row per fire	test_apply_demotes_prior_turn_beliefs_and_writes_audit + tag sentiment_feedback

Out of scope (kept per #606)

• Cross-session sentiment propagation.
• Multi-language sentiment.
• Ranked / per-rank decay distribution.
• LLM-judged sentiment (deferred to v3.0 PHILOSOPHY: natural-language-relatedness gate — deterministic vs embedding #605 PHILOSOPHY-determinism decision).

Tests

uv run pytest tests/ -q --ignore=tests/bench_gate — 3278 passed, 30 skipped.

The 16 new tests are in tests/test_hook_sentiment_feedback.py.

Summary by Sourcery

Wire the existing sentiment feedback module into the UserPromptSubmit hook so corrective user prompts can adjust prior belief posteriors before retrieval, with opt-in gating, auditing, and accompanying documentation and tests.

New Features:

• Add a sentiment-feedback lane invoked from the UserPromptSubmit hook that applies detected sentiment in the current prompt to beliefs retrieved in the previous turn.
• Introduce a new sentiment_feedback hook-audit tag that records detected sentiment metadata and affected belief IDs per firing.

Enhancements:

• Add helper utilities to load the full .aelfrice.toml configuration and to read prior UserPromptSubmit belief IDs from hook audit logs in a fail-soft manner.
• Document the v3.0 sentiment-feedback hook design, decisions, and scope in a dedicated spec memo and update the changelog accordingly.

Tests:

• Add comprehensive unit and integration tests covering TOML loading, prior-UPS belief ID extraction, sentiment lane behavior under various gate and error conditions, and a two-session ranking fixture validating that corrections lower subsequent rankings across sessions.

[coderabbitai]

Warning

Rate limit exceeded

@robotrocketscience has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 46 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: 2605b13e-ac7a-498f-a49b-90a72070c134

📥 Commits

Reviewing files that changed from the base of the PR and between 8b8c6d4 and 07d0463.

⛔ Files ignored due to path filters (1)

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

📒 Files selected for processing (3)

• docs/v3_sentiment_feedback_hook.md
• src/aelfrice/hook.py
• tests/test_hook_sentiment_feedback.py

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/issue-606-sentiment-feedback-hook

---

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

[sourcery-ai]

Reviewer's Guide

Wires the existing v2 sentiment_feedback module into the UserPromptSubmit hook so that sentiment expressed in the current prompt is deterministically detected, applied as feedback to the prior UPS turn’s retrieved beliefs before retrieval runs again, and recorded via a new sentiment_feedback audit tag; implementation is fail-soft, opt-in via TOML/env config, and covered by focused unit/integration tests plus a design memo and changelog entry.

Sequence diagram for UserPromptSubmit sentiment-feedback lane integration

sequenceDiagram
    actor User
    participant UserPromptSubmitHook as UserPromptSubmit_hook
    participant SentimentFeedback as sentiment_feedback_module
    participant HookAudit as hook_audit_jsonl
    participant BeliefStore as belief_store
    participant Retriever as retrieval_engine

    User->>UserPromptSubmitHook: submit prompt_N (session_id)
    activate UserPromptSubmitHook

    UserPromptSubmitHook->>SentimentFeedback: apply_sentiment_feedback(prompt_N, session_id)
    activate SentimentFeedback

    SentimentFeedback->>SentimentFeedback: _load_aelfrice_toml()
    SentimentFeedback-->>SentimentFeedback: config_mapping
    SentimentFeedback->>SentimentFeedback: is_enabled(config_mapping)
    alt sentiment_from_prose_disabled
        SentimentFeedback-->>UserPromptSubmitHook: 0 updated_beliefs
    else sentiment_from_prose_enabled
        SentimentFeedback->>SentimentFeedback: detect_sentiment(prompt_N)
        alt no_sentiment_signal
            SentimentFeedback-->>UserPromptSubmitHook: 0 updated_beliefs
        else sentiment_signal_detected
            SentimentFeedback->>HookAudit: read_hook_audit(hook_audit_jsonl + rotated)
            HookAudit-->>SentimentFeedback: most_recent_prior_ups_beliefs_ids
            alt no_prior_ups_or_no_beliefs
                SentimentFeedback-->>UserPromptSubmitHook: 0 updated_beliefs
            else prior_belief_ids_found
                SentimentFeedback->>BeliefStore: _open_store()
                BeliefStore-->>SentimentFeedback: store_handle
                SentimentFeedback->>BeliefStore: apply_sentiment_to_pending(store_handle, signal, prior_belief_ids)
                BeliefStore-->>SentimentFeedback: results_per_belief
                SentimentFeedback->>HookAudit: _write_sentiment_feedback_audit(signal, applied_belief_ids)
                HookAudit-->>SentimentFeedback: append_jsonl_row
                SentimentFeedback-->>BeliefStore: close_store()
                SentimentFeedback-->>UserPromptSubmitHook: n_applied_beliefs
            end
        end
    end
    deactivate SentimentFeedback

    UserPromptSubmitHook->>Retriever: _retrieve(prompt_N, budget)
    activate Retriever
    Retriever-->>UserPromptSubmitHook: hits_reflecting_updated_posteriors
    deactivate Retriever

    UserPromptSubmitHook-->>User: assistant_response_based_on_hits
    deactivate UserPromptSubmitHook

Loading

File-Level Changes

Change	Details	Files
Introduce an opt-in sentiment-feedback lane that runs on each UserPromptSubmit before retrieval, applying regex-detected sentiment from the current prompt to the prior turn’s retrieved beliefs.	Add AUDIT_HOOK_SENTIMENT_FEEDBACK constant and wire apply_sentiment_feedback(prompt, session_id, stderr) into user_prompt_submit before _retrieve executes so corrections affect the next retrieval window. Implement apply_sentiment_feedback to guard on empty inputs, import the sentiment_feedback module, check is_enabled(config), detect_sentiment(prompt), load prior UPS belief IDs from audit, apply sentiment to pending beliefs via the store, write a sentiment_feedback audit row, and fail-soft to 0 on any error. Implement _write_sentiment_feedback_audit to append a sentiment_feedback record to hook_audit.jsonl with prompt prefix, sentiment fields (pattern, matched_text, valence, confidence), applied belief IDs, and count, reusing existing audit config and rotation.	src/aelfrice/hook.py
Add helpers to read global TOML config and to reconstruct the prior UPS retrieval window from audit logs for use by the sentiment-feedback lane.	Implement _load_aelfrice_toml(start, stderr) to walk up from a starting path (or CWD), read .aelfrice.toml, parse via tomllib, and return a dict or {} on missing/unreadable/malformed files, logging errors to stderr. Implement _load_prior_ups_belief_ids(session_id, stderr) to locate the audit JSONL for the current DB (including rotated .1), scan for user_prompt_submit records for the given session, and return the belief IDs from the most recent one, failing soft on IO/shape errors and handling empty/missing audit gracefully.	src/aelfrice/hook.py
Add tests covering configuration/short-circuit behavior, prior-UPS window reconstruction, belief posterior updates, audit-row shape, UPS integration, and a two-session ranking fixture that validates the acceptance criteria.	Add fixtures/helpers to seed an in-memory DB, construct Belief instances, manipulate AELFRICE_DB and sentiment env flags, and generate UPS hook payloads. Test _load_aelfrice_toml for missing, valid, and malformed TOML (including stderr logging on parse errors). Test _load_prior_ups_belief_ids for missing audit, blank session, proper filtering by session and hook, last-record semantics, skipping of malformed/non-dict beliefs, and behavior when the audit file is absent. Test apply_sentiment_feedback for disabled-gate short-circuit (no audit row, no posterior change), no-signal short-circuit, no-prior-UPS short-circuit, successful demotion and audit-row contents, and skipping of belief IDs that no longer exist. Add integration tests where user_prompt_submit is invoked end-to-end with sentiment disabled and enabled to ensure the lane doesn’t fire when disabled and does bump prior-turn beliefs plus write sentiment_feedback audit when enabled. Add a two-session AC4 test where session A corrects a belief and session B’s query ranks the corrected belief below an uncorrected sibling, plus a check that feedback_history entries use the SENTIMENT_INFERRED_SOURCE tag.	tests/test_hook_sentiment_feedback.py
Document the sentiment-feedback hook design and its addition to the system behavior surface.	Add docs/v3_sentiment_feedback_hook.md describing the chosen hook lane (UserPromptSubmit), prior-UPS retrieval window, sentiment_feedback audit surface, opt-in configuration, privacy posture, determinism guarantees, acceptance mapping, and out-of-scope items. Add a CHANGELOG entry under Added summarizing the new sentiment-feedback hook lane behavior, configuration, audit-tagging, default-off posture, failure semantics, and linking to the design memo and issue v3.0: sentiment-feedback hook production wire-up (evaluation #193 passed; integration pending) #606.	docs/v3_sentiment_feedback_hook.md CHANGELOG.md

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#606	Wire the existing aelfrice.sentiment_feedback module into a production hook lane (choosing between UserPromptSubmit and Stop) with a defined retrieval window/decay policy, and document these decisions in a spec memo.	✅
#606	Ensure the sentiment-feedback hook preserves determinism and privacy constraints: deterministic stdlib-only sentiment detection with no LLM/embeddings, and no new PII surface beyond what the existing transcript/audit logging already touches while respecting the existing opt-out/opt-in semantics.	✅
#606	Provide testing and auditing for the sentiment-feedback hook, including a two-session benchmark fixture showing that corrections affect subsequent retrieval rankings, and write an audit-log entry for each sentiment-driven feedback application using a dedicated tag.	✅

Possibly linked issues

• v3.0: sentiment-feedback hook production wire-up (evaluation #193 passed; integration pending) #606: Yes. PR wires sentiment-feedback into UserPromptSubmit, adds sentiment_feedback audit tag, respects config/privacy, and ships the bench.

---

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.

[github-actions]

PR-size soft cap

This PR is over the advisory size threshold:

• 874 changed lines (limit: 200)
• 4 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.

[sourcery-ai]

Hey - I've left some high level feedback:

• The sentiment lane is now on the hot UPS path and re-parses .aelfrice.toml on every prompt; consider caching the parsed config and/or sentiment_feedback.is_enabled result to avoid repeated filesystem and TOML work when the feature is disabled or unchanged.
• _load_prior_ups_belief_ids scans all records in the current and rotated audit files on each sentiment fire; if these JSONL files grow toward the rotation cap this becomes O(N) per corrective prompt, so it may be worth optimizing (e.g., scanning from the end, keeping a lightweight index, or stopping early once you pass a session’s last match).

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The sentiment lane is now on the hot UPS path and re-parses `.aelfrice.toml` on every prompt; consider caching the parsed config and/or `sentiment_feedback.is_enabled` result to avoid repeated filesystem and TOML work when the feature is disabled or unchanged.
- _load_prior_ups_belief_ids scans all records in the current and rotated audit files on each sentiment fire; if these JSONL files grow toward the rotation cap this becomes O(N) per corrective prompt, so it may be worth optimizing (e.g., scanning from the end, keeping a lightweight index, or stopping early once you pass a session’s last match).

---

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]

[claim:review:noether:2026-05-10T23:50:00Z]

[github-actions]

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

git fetch origin && git checkout 'feat/issue-606-sentiment-feedback-hook' && 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]

Substance LGTM — flagging attn:merge-conflict because the branch needs a rebase on top of main (PR #613 just landed).

Things I checked:

• Spec memo (docs/v3_sentiment_feedback_hook.md): each of the five decision points has an explicit rationale. Hook lane (UPS) is the right call given the corrective-prompt-arrives-after-action timing argument. Retrieval window scoped to single-session for v3.0 with cross-session called out as explicit follow-up — clean scope cut. Audit-row design separates event-level (hook_audit.jsonl row) from belief-level (feedback_history row); both already exist for parallel reasons, no duplication.
• Wiring (hook.py:707-708): apply_sentiment_feedback called before retrieval in the UPS lane. Short-circuits when disabled (no behavior change for users who haven't opted in). Audit row writing is fail-soft (catches and logs rather than failing the hook). The is_enabled(config) indirection means programmatic non-hook callers of detect_sentiment / apply_sentiment_to_pending are unaffected.
• Tests: 16 covering TOML loader edge cases (missing / malformed), prior-UPS lookup boundaries (missing audit / empty session / non-dict beliefs), apply-path short-circuits (disabled / no signal / no prior UPS), happy-path demotion + audit row, UPS-integration paths, AC4 two-session ranking fixture, and the source = sentiment_inferred label assertion. Coverage matches the boundary cases the spec memo enumerated.
• Privacy posture: audit row carries pattern + bounded matched_text (≤30 chars per regex shape) + capped prompt_prefix. No full-prompt storage. Consistent with the existing audit row design.
• Discretion grep on the diff vs main: clean.
• Signature check: all five commits SSH-signed (G).
• CI: all green (CodeQL included).

After rebase + green CI, this is FF-mergeable. Re-flag attn:review when ready.

[robotrocketscience]

[release:review:noether:2026-05-10T23:51:40Z]

[robotrocketscience]

[claim:review:Maxwell:2026-05-11T01:46:25Z]

[robotrocketscience]

LGTM. Implements the locked v3.0 sentiment-hook decision exactly:

• UPS lane. apply_sentiment_feedback called from user_prompt_submit before retrieval — corrective prompt mutates posteriors of the prior turn's retrieved beliefs in lockstep with the retrieval window it's correcting.
• Default-off opt-in. Gated on _load_aelfrice_toml + sf.is_enabled(toml_cfg). Bare-default install path stays a no-op.
• Decay policy: most-recent-window only. _load_prior_ups_belief_ids returns ids surfaced by the most-recent prior UPS fire for the same session_id; no cross-session, no fall-through to N-prior.
• Determinism. Stdlib re patterns inside sentiment_feedback.detect_sentiment (existing v2.0 module). No LLM / embedding call introduced.
• Audit tag. New sentiment_feedback row written to existing hook_audit.jsonl. Per-belief feedback_history source stays sentiment_inferred (v2.0-unchanged), no schema migration needed.

State checked:

• FF on github/main. Five signed commits, including a bff7dea docs(sentiment-hook): rephrase host-name to avoid discretion trigger cleanup.
• Local discretion grep on full diff: clean.
• CI green (all checks pass; only surface-failure skips, which is expected when no failure exists).
• Tests: 16 new in tests/test_hook_sentiment_feedback.py, 3278 passing total per PR body. Covers the disabled-gate, no-signal, no-prior-UPS, posterior-demotion, audit-schema, missing-belief, and AC4 two-session-ranking paths.

Notes (none blocking):

1. Fail-soft everywhere is correct for hook scope but worth eyeballing: _load_aelfrice_toml, _load_prior_ups_belief_ids, the outer apply_sentiment_feedback block, and _write_sentiment_feedback_audit all squash exceptions with a stderr line. That's the right contract for a UPS lane (never block the user's turn), but it does mean a silently-broken sentiment lane will leave no trace beyond stderr. If a future audit needs visibility, a per-hook health counter would be the surface — out of scope here.

2. Per the existing memory lock for v3.0: sentiment-feedback hook production wire-up (evaluation #193 passed; integration pending) #606, the operator-designated ratification path runs through a specific session. This review is a content check, not a ratification claim — releasing the review-claim mutex so the designated session can post the ratification comment.

Branch is ready for attn:review → ready-to-merge once content-ratified.

[robotrocketscience]

[release:review:Maxwell:2026-05-11T01:47:23Z]

[github-actions]

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

git fetch origin && git checkout 'feat/issue-606-sentiment-feedback-hook' && 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]

Rebased on github/main (base was 0a3d0cd, main now 8b8c6d4 — moved by #610 / #613 / #615 / #617 / #619 / etc).

• 5 commits replayed cleanly, no conflicts (07d0463, cca18e4, b9bd4de, df7dfb5, b584be9).
• All commits show G on local git log --format='%G?'.
• Discretion grep on github/main...HEAD clean.
• uv run pytest -q → 3319 passed, 52 skipped.
• Force-pushed with explicit --force-with-lease=...:bff7dea (the locked SHA quirk).
• Removed stale attn:merge-conflict label, set attn:review.

Per the locked v3.0 sentiment-hook decision (#606, ratified 2026-05-10): UPS lane, default-off opt-in, most-recent-window decay — this PR matches.

Note: when this gets ready-to-merge, the merge-train signature bug (#618) will likely reject the labeled-merge attempt the same way it rejected #614 at 01:06Z and 01:48Z. Operator decision on signing-key registration is pending (noether's escalation 04:35Z on PR #614). Until #618 fixes ship, this will need the FF-push fallback.

— leibniz

[robotrocketscience]

[claim:review:noether:2026-05-11T04:48:38Z]

[robotrocketscience]

Ratifying. Post-rebase state matches the locked v3.0 sentiment-hook decision (#606): UPS lane, default-off opt-in, most-recent-window decay, stdlib-only determinism, audit tag on existing surface.

Verified on rebased HEAD (07d0463):

• FF-mergeable on github/main (5 commits ahead, 0 behind).
• All 5 commits SSH-signed (G).
• Discretion grep on full diff vs main: clean.
• CI: all green (CodeQL + 3.12/3.13 pytest + secrets/pattern/history scans + label/title/prefix gates).

Per leibniz's note re #618, taking the FF-push path rather than the labeled merge-train.

— noether

[robotrocketscience]

[release:review:noether:2026-05-11T04:50:05Z]