From 32973342611960ff9913e28b2c772b998058ec78 Mon Sep 17 00:00:00 2001
From: Joseph Doherty <dohejw01@gmail.com>
Date: Fri, 27 Feb 2026 05:46:12 -0500
Subject: [PATCH] docs: add audit-verified status updates design

---
 ...026-02-27-audit-verified-updates-design.md | 85 +++++++++++++++++++
 reports/current.md                            |  2 +-
 reports/report_4972f99.md                     | 38 +++++++++
 3 files changed, 124 insertions(+), 1 deletion(-)
 create mode 100644 docs/plans/2026-02-27-audit-verified-updates-design.md
 create mode 100644 reports/report_4972f99.md

diff --git a/docs/plans/2026-02-27-audit-verified-updates-design.md b/docs/plans/2026-02-27-audit-verified-updates-design.md
new file mode 100644
index 0000000..7905d39
--- /dev/null
+++ b/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.
diff --git a/reports/current.md b/reports/current.md
index e871fcc..e1e403e 100644
--- a/reports/current.md
+++ b/reports/current.md
@@ -1,6 +1,6 @@
 # NATS .NET Porting Status Report
 
-Generated: 2026-02-27 10:36:34 UTC
+Generated: 2026-02-27 10:46:13 UTC
 
 ## Modules (12 total)
 
diff --git a/reports/report_4972f99.md b/reports/report_4972f99.md
new file mode 100644
index 0000000..e1e403e
--- /dev/null
+++ b/reports/report_4972f99.md
@@ -0,0 +1,38 @@
+# NATS .NET Porting Status Report
+
+Generated: 2026-02-27 10:46:13 UTC
+
+## Modules (12 total)
+
+| Status | Count |
+|--------|-------|
+| verified | 12 |
+
+## Features (3673 total)
+
+| Status | Count |
+|--------|-------|
+| deferred | 2500 |
+| n_a | 18 |
+| stub | 168 |
+| verified | 987 |
+
+## Unit Tests (3257 total)
+
+| Status | Count |
+|--------|-------|
+| deferred | 2662 |
+| n_a | 187 |
+| stub | 18 |
+| verified | 390 |
+
+## Library Mappings (36 total)
+
+| Status | Count |
+|--------|-------|
+| mapped | 36 |
+
+
+## Overall Progress
+
+**1594/6942 items complete (23.0%)**