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

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

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

# 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

# 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

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.