docs: add feature status audit implementation plan
68 batch tasks processing 50 features each. Each batch: fetch unknown features, inspect .NET source, classify, dry-run, execute via PortTracker CLI.
This commit is contained in:
Joseph Doherty
236
docs/plans/2026-02-27-feature-status-audit-plan.md
Normal file
236
docs/plans/2026-02-27-feature-status-audit-plan.md
Normal file
@@ -0,0 +1,236 @@
|
||||
# Feature Status Audit Implementation Plan
|
||||
|
||||
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers-extended-cc:executing-plans to implement this plan task-by-task.
|
||||
|
||||
**Goal:** Classify 3394 features currently marked `unknown` into the correct status (`verified`, `stub`, `n_a`, or `deferred`) by inspecting .NET source code against Go feature specifications.
|
||||
|
||||
**Architecture:** Process features in sequential batches of 50. Each batch: fetch 50 unknown features via PortTracker CLI, inspect the corresponding .NET source files, classify each feature, dry-run the batch updates, then execute. Repeat until zero unknown features remain.
|
||||
|
||||
**Tech Stack:** PortTracker CLI (`dotnet run --project tools/NatsNet.PortTracker`), .NET source at `dotnet/src/ZB.MOM.NatsNet.Server/`
|
||||
|
||||
**Design doc:** `docs/plans/2026-02-27-feature-status-audit-design.md`
|
||||
|
||||
---
|
||||
|
||||
## Important Rules (Read Before Every Task)
|
||||
|
||||
1. **ALWAYS dry-run before executing** — no exceptions. Every `batch-update` command must be run WITHOUT `--execute` first to preview.
|
||||
2. **NEVER use direct SQL** (`sqlite3`) — use the PortTracker CLI exclusively for all database operations.
|
||||
3. **Process exactly 50 per batch** (or fewer if fewer remain in the final batch).
|
||||
4. **Report classification breakdown** after each batch (e.g. "Batch 3: 12 verified, 30 stub, 3 n_a, 5 deferred").
|
||||
|
||||
## Classification Criteria Reference
|
||||
|
||||
| Status | Criteria |
|
||||
|--------|----------|
|
||||
| `verified` | .NET method exists with non-trivial logic that matches the Go implementation's behavior |
|
||||
| `stub` | .NET method exists but is `throw new NotImplementedException()`, empty, or only **partially** implemented (has structure but missing significant logic) |
|
||||
| `n_a` | Go feature doesn't apply to .NET — .NET uses a different approach (e.g. Go logging → .NET uses `Microsoft.Extensions.Logging`) |
|
||||
| `deferred` | .NET method doesn't exist at all, or classification requires the server running end-to-end |
|
||||
|
||||
## Key .NET Source Locations
|
||||
|
||||
When looking for a `dotnet_class`, search in these directories:
|
||||
|
||||
```
|
||||
dotnet/src/ZB.MOM.NatsNet.Server/
|
||||
Accounts/ — Account, AccountResolver, DirJwtStore, AccountTypes
|
||||
Auth/ — AuthHandler, JwtProcessor, CipherSuites, AuthTypes
|
||||
Config/ — ReloadOptions, ServerOptionsConfiguration, NatsJsonConverters
|
||||
Events/ — EventTypes
|
||||
Gateway/ — GatewayTypes
|
||||
Internal/ — Subscription, WaitGroup, ClosedRingBuffer, RateCounter, DataStructures/
|
||||
JetStream/ — MemStore, ConsumerMemStore, FileStore, FileStoreTypes, MessageBlock
|
||||
JetStreamTypes, JetStreamApiTypes, JetStreamErrors, JetStreamVersioning
|
||||
NatsStream, NatsConsumer, RaftTypes, JetStreamClusterTypes
|
||||
LeafNode/ — LeafNodeTypes
|
||||
MessageTrace/ — MsgTraceTypes
|
||||
Monitor/ — MonitorTypes, MonitorSortOptions
|
||||
Mqtt/ — MqttConstants, MqttTypes, MqttHandler
|
||||
Protocol/ — ParserTypes, ProtocolParser, ProxyProtocol
|
||||
Routes/ — RouteTypes
|
||||
WebSocket/ — WebSocketConstants, WebSocketTypes
|
||||
NatsServer.cs, NatsServer.Auth.cs, NatsServer.Signals.cs, NatsServer.Init.cs
|
||||
NatsServer.Accounts.cs, NatsServer.Lifecycle.cs, NatsServer.Listeners.cs
|
||||
ClientConnection.cs, ClientTypes.cs, NatsMessageHeaders.cs
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Task 0: Verify starting state and PortTracker commands
|
||||
|
||||
**Files:** None — verification only.
|
||||
|
||||
**Step 1: Check how many unknown features exist**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature list --module 8 --status unknown --db porting.db
|
||||
```
|
||||
|
||||
Expected: Output shows ~3394 features. Note the total count at the bottom.
|
||||
|
||||
**Step 2: Verify batch-update dry-run works**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids 150-152 --set-status verified --db porting.db
|
||||
```
|
||||
|
||||
Expected: Preview output showing 3 features. Should say "Would affect 3 items:" and "Add --execute to apply these changes." Do NOT execute — this is just confirming the tool works.
|
||||
|
||||
**Step 3: Record the starting count**
|
||||
|
||||
Note the total unknown count. This is your baseline. After all batches complete, the count should be 0.
|
||||
|
||||
---
|
||||
|
||||
### Task N (repeat for N=1 through 68): Process batch of 50 unknown features
|
||||
|
||||
> **This task is a template.** Repeat it until zero unknown features remain. Each execution processes the next 50.
|
||||
|
||||
**Files:** None — classification only, no code changes.
|
||||
|
||||
**Step 1: Fetch the next 50 unknown features**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature list --module 8 --status unknown --db porting.db
|
||||
```
|
||||
|
||||
From the output, take the **first 50 feature IDs**. Note the `dotnet_class` and `dotnet_method` columns for each.
|
||||
|
||||
**Step 2: For each feature, inspect the .NET implementation**
|
||||
|
||||
For each of the 50 features:
|
||||
|
||||
1. **Find the .NET source file** — use `Grep` to search for the class:
|
||||
```
|
||||
Grep pattern: "class {dotnet_class}" path: dotnet/src/ZB.MOM.NatsNet.Server/
|
||||
```
|
||||
|
||||
2. **Find the method** — search within that file for the method name:
|
||||
```
|
||||
Grep pattern: "{dotnet_method}" path: {the file found above}
|
||||
```
|
||||
|
||||
3. **Read the method body** — use `Read` to view the method implementation.
|
||||
|
||||
4. **Classify the feature:**
|
||||
- If the method has real, non-trivial logic matching the Go behavior → `verified`
|
||||
- If the method is `throw new NotImplementedException()`, empty, or only partially there → `stub`
|
||||
- If the Go feature has a .NET-native replacement (e.g., Go's custom logging → `Microsoft.Extensions.Logging`, Go's `sync.Mutex` → C#'s `Lock`) → `n_a`
|
||||
- If the method doesn't exist in the .NET codebase at all → `deferred`
|
||||
|
||||
**Efficiency tip:** Features from the same `dotnet_class` should be inspected together — read the .NET file once and classify all features from that class in the batch.
|
||||
|
||||
**Step 3: Group IDs by classification result**
|
||||
|
||||
After inspecting all 50, organize the IDs into groups:
|
||||
|
||||
```
|
||||
verified_ids: 2068,2069,2070,2071,...
|
||||
stub_ids: 2080,2081,...
|
||||
n_a_ids: 2090,...
|
||||
deferred_ids: 2095,2096,...
|
||||
```
|
||||
|
||||
**Step 4: Dry-run each group (MANDATORY — DO NOT SKIP)**
|
||||
|
||||
Run the dry-run for EACH status group. Review the output carefully.
|
||||
|
||||
```bash
|
||||
# Dry-run verified
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids {verified_ids} --set-status verified --db porting.db
|
||||
|
||||
# Dry-run stub
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids {stub_ids} --set-status stub --db porting.db
|
||||
|
||||
# Dry-run n_a (include reason in notes)
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids {n_a_ids} --set-status n_a --set-notes "{reason}" --db porting.db
|
||||
|
||||
# Dry-run deferred
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids {deferred_ids} --set-status deferred --db porting.db
|
||||
```
|
||||
|
||||
Check that:
|
||||
- The feature names in the preview match what you inspected
|
||||
- The count per group adds up to 50 (or the batch size)
|
||||
- No unexpected features appear
|
||||
|
||||
**Step 5: Execute each group**
|
||||
|
||||
Only after verifying ALL dry-runs look correct:
|
||||
|
||||
```bash
|
||||
# Execute verified
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids {verified_ids} --set-status verified --execute --db porting.db
|
||||
|
||||
# Execute stub
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids {stub_ids} --set-status stub --execute --db porting.db
|
||||
|
||||
# Execute n_a (with notes)
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids {n_a_ids} --set-status n_a --set-notes "{reason}" --execute --db porting.db
|
||||
|
||||
# Execute deferred
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature batch-update --ids {deferred_ids} --set-status deferred --execute --db porting.db
|
||||
```
|
||||
|
||||
**Step 6: Verify remaining count decreased**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature list --status unknown --db porting.db
|
||||
```
|
||||
|
||||
Confirm the total decreased by ~50 from the previous batch.
|
||||
|
||||
**Step 7: Report batch summary**
|
||||
|
||||
Print: `Batch N: X verified, Y stub, Z n_a, W deferred (Total remaining: NNNN)`
|
||||
|
||||
---
|
||||
|
||||
### Task 69: Final verification and report
|
||||
|
||||
**Files:** None — verification only.
|
||||
|
||||
**Step 1: Confirm zero unknown features remain**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature list --status unknown --db porting.db
|
||||
```
|
||||
|
||||
Expected: `Total: 0 features`
|
||||
|
||||
**Step 2: Generate the full status breakdown**
|
||||
|
||||
```bash
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature list --module 8 --status verified --db porting.db
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature list --module 8 --status stub --db porting.db
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature list --module 8 --status n_a --db porting.db
|
||||
dotnet run --project tools/NatsNet.PortTracker -- feature list --module 8 --status deferred --db porting.db
|
||||
```
|
||||
|
||||
Note the count for each status.
|
||||
|
||||
**Step 3: Generate updated porting report**
|
||||
|
||||
```bash
|
||||
./reports/generate-report.sh
|
||||
```
|
||||
|
||||
**Step 4: Commit the updated report**
|
||||
|
||||
```bash
|
||||
git add reports/
|
||||
git commit -m "chore: update porting report after feature status audit"
|
||||
```
|
||||
|
||||
**Step 5: Print final summary**
|
||||
|
||||
```
|
||||
Feature Status Audit Complete
|
||||
=============================
|
||||
Total features audited: 3394
|
||||
verified: NNNN
|
||||
stub: NNNN
|
||||
n_a: NNNN
|
||||
deferred: NNNN
|
||||
```
|
||||
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"planPath": "docs/plans/2026-02-27-feature-status-audit-plan.md",
|
||||
"tasks": [
|
||||
{"id": 0, "subject": "Task 0: Verify starting state and PortTracker commands", "status": "pending"},
|
||||
{"id": 1, "subject": "Task 1-68: Process batches of 50 unknown features (repeating template)", "status": "pending", "blockedBy": [0], "note": "This is a repeating task — execute the template from the plan 68 times until 0 unknown features remain"},
|
||||
{"id": 69, "subject": "Task 69: Final verification and report", "status": "pending", "blockedBy": [1]}
|
||||
],
|
||||
"lastUpdated": "2026-02-27T00:00:00Z"
|
||||
}
|
||||
Reference in New Issue
Block a user