docs: add audit-verified status updates design

docs/plans/2026-02-27-audit-verified-updates-design.md

@@ -0,0 +1,85 @@
+# Audit-Verified Status Updates Design
+
+## Goal
+
+Require audit verification before applying status changes to features or unit tests. When the requested status disagrees with what the Roslyn audit determines, require an explicit override with a comment. Track all overrides in a new table for later review.
+
+## Architecture
+
+Inline audit verification: when `feature update`, `feature batch-update`, `test update`, or `test batch-update` runs, build the `SourceIndexer` on the fly, classify each item, and compare. If the requested status doesn't match the audit, block the update unless `--override "comment"` is provided.
+
+## Override Table Schema
+
+```sql
+CREATE TABLE status_overrides (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    table_name TEXT NOT NULL CHECK (table_name IN ('features', 'unit_tests')),
+    item_id INTEGER NOT NULL,
+    audit_status TEXT NOT NULL,
+    audit_reason TEXT NOT NULL,
+    requested_status TEXT NOT NULL,
+    comment TEXT NOT NULL,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+```
+
+Each row records: which table/item, what the audit said, what the user requested, and their justification.
+
+## CLI Interface
+
+### Single update
+
+```bash
+# Audit agrees — applied directly
+dotnet run -- feature update 123 --status verified --db porting.db
+
+# Audit disagrees — blocked
+# Error: "Audit classifies feature 123 as 'stub'. Use --override 'reason' to force."
+
+# Override
+dotnet run -- feature update 123 --status verified --override "Manual review confirms complete" --db porting.db
+```
+
+### Batch update
+
+```bash
+# All items agree — applied
+dotnet run -- feature batch-update --module 5 --set-status verified --execute --db porting.db
+
+# Some items disagree — blocked
+# "15 items match audit, 3 require override. Use --override 'reason' to force all."
+
+# Override entire batch (one comment covers all mismatches)
+dotnet run -- feature batch-update --module 5 --set-status verified --override "Batch approved" --execute --db porting.db
+```
+
+Same interface for `test update` and `test batch-update`.
+
+## Verification Flow
+
+1. Build `SourceIndexer` for the appropriate directory (features → `dotnet/src/...`, tests → `dotnet/tests/...`).
+2. For each item: query its `dotnet_class`, `dotnet_method`, `go_file`, `go_method` from DB. Run `FeatureClassifier.Classify()`.
+3. Compare requested status vs audit status. Collect mismatches.
+4. If mismatches and no `--override`: print details and exit with error.
+5. If `--override` provided: apply all updates. Insert one `status_overrides` row per mismatched item.
+6. Items that agree with audit: apply normally, no override row logged.
+
+Items that cannot be audited (no dotnet_class/dotnet_method) are treated as mismatches requiring override.
+
+## Override Review Command
+
+```bash
+dotnet run -- override list --db porting.db
+dotnet run -- override list --type features --db porting.db
+```
+
+Tabular output: id, table, item_id, audit_status, requested_status, comment, date.
+
+## Changes Required
+
+1. **porting-schema.sql**: Add `status_overrides` table.
+2. **FeatureCommands.cs**: Add `--override` option to `update` and `batch-update`. Integrate audit verification before applying.
+3. **TestCommands.cs**: Same changes as FeatureCommands.
+4. **New `OverrideCommands.cs`**: `override list` command.
+5. **Program.cs**: Wire `override` command group.
+6. **Shared helper**: Extract audit verification logic (build indexer, classify, compare) into a reusable method since both feature and test commands need it.