docs(stock): record dividend retirement workflow

plans/260722-1843-retire-stock-dividend-command/phase-01-remove-command-and-retire-stats.md

@@ -0,0 +1,50 @@
+---
+phase: 1
+title: Remove Command and Retire Stats
+status: completed
+priority: P1
+dependencies: []
+effort: medium
+---
+
+# Phase 1: Remove Command and Retire Stats
+
+## Overview
+
+Delete the generic stock dividend command and add durable stats retirement for
+its retained usage history.
+
+## Requirements
+
+- Preserve `/stock_cash_dividend` and `/stock_share_dividend` behavior.
+- Remove all active `/stock_dividend` command surfaces.
+- Retain stats rows rather than deleting usage history.
+- Filter retired rows from every memory and Mongo stats view.
+- Reconcile late legacy writes on future startup runs.
+- Keep Mongo startup bounded with exact-command bulk operations.
+
+## Architecture
+
+The stats runtime owns a permanent retired-command rule. New increments for the
+retired command are ignored and reads exclude it independently of the stored
+flag. Startup physically restores `deleted: true`: memory uses versioned CAS;
+Mongo uses indexed `UpdateMany` plus `CountDocuments`. The shared system marker
+stores completion status and the current exact-command row count.
+
+## Implementation Checklist
+
+- [x] Remove command registration and combined handler.
+- [x] Remove command-menu metadata and handler/menu tests.
+- [x] Remove README command documentation.
+- [x] Add stats/system startup wiring and migration marker.
+- [x] Add permanent read/write retirement behavior.
+- [x] Add memory and real-Mongo reconciliation tests.
+- [x] Pass review, test, race, build, vet, lint, and diff gates.
+
+## Risks
+
+- A legacy process can write after migration; runtime filtering hides it and
+  every later startup physically tombstones it again.
+- Unbounded per-row Mongo startup work is avoided by exact indexed bulk calls.
+- Marker count is derived from all matching rows, so retries do not undercount.
+

plans/260722-1843-retire-stock-dividend-command/plan.md

@@ -0,0 +1,44 @@
+---
+title: Retire Generic Stock Dividend Command
+description: Remove /stock_dividend while preserving and hiding historical usage statistics.
+status: completed
+priority: P1
+effort: medium
+branch: main
+tags:
+  - stock
+  - stats
+  - migration
+  - telegram
+created: 2026-07-22
+---
+
+# Retire Generic Stock Dividend Command
+
+## Overview
+
+Remove the combined manual dividend command because users can apply cash and
+share dividends through the two specialized commands. Retain historical stats
+as deleted legacy records and prevent rolling-deploy writes from exposing them.
+
+## Phases
+
+| Phase | Name | Status | Progress |
+|---|---|---|---|
+| 1 | [Remove Command and Retire Stats](./phase-01-remove-command-and-retire-stats.md) | Completed | 7/7 (100%) |
+
+## Dependencies
+
+- Uses the existing stats `deleted` field and shared `system` collection.
+- No portfolio schema or dividend-history migration changes.
+
+## Success Criteria
+
+- [x] `/stock_dividend` is absent from registration, menu, help, handler, and README.
+- [x] Cash and share dividend commands remain available and unchanged.
+- [x] Anonymous and per-user historical rows remain stored with `deleted: true`.
+- [x] Retired rows remain hidden even after a late legacy-process write.
+- [x] Memory reconciliation is idempotent and Mongo reconciliation is bulk/indexed.
+- [x] Exact-prefix commands such as `stock_dividend_extra` remain untouched.
+- [x] Full, race, Mongo integration, build, vet, and lint checks pass.
+

plans/260722-1843-retire-stock-dividend-command/reports/pm-260722-1843-retire-stock-dividend-command.md

@@ -0,0 +1,39 @@
+---
+title: Retire Stock Dividend Command Completion Report
+status: completed
+created: 2026-07-22
+---
+
+# Retire Stock Dividend Command Completion Report
+
+## Summary
+
+| Metric | Result |
+|---|---|
+| Phases | 1/1 completed |
+| Tasks | 7/7 completed |
+| Code review | Pass; no remaining findings |
+| Focused/full tests | Pass |
+| Race tests | Pass |
+| Mongo 8 integration | Pass; executed via Testcontainers |
+| Build / vet / lint | Pass / pass / 0 issues |
+| Statement coverage | 77.3% |
+
+## Achievements
+
+- Removed the redundant combined dividend command from every active surface.
+- Preserved specialized cash/share dividend workflows.
+- Retained historical stats while permanently suppressing the retired command.
+- Hardened rolling-deploy behavior against late legacy increments.
+- Used bounded Mongo bulk reconciliation with exact-prefix safety.
+
+## Known Limitations
+
+- A still-running legacy binary can show its own stale stats view until it is
+  replaced; new binaries suppress the command immediately.
+- No repository coverage threshold is configured; measured total is 77.3%.
+
+## Next Step
+
+- Commit and push after user approval.
+