docs: add PortTracker batch operations design

Design for batch-update and batch-map subcommands across all entity
types (feature, test, module, library) with shared filter infrastructure
and dry-run-by-default safety.

docs/plans/2026-02-27-porttracker-batch-design.md

@@ -0,0 +1,120 @@
+# PortTracker Batch Operations Design
+
+**Date:** 2026-02-27
+**Status:** Approved
+
+## Problem
+
+The PortTracker CLI only supports one-at-a-time operations for status updates, mappings, and N/A marking. With ~3700 features and ~3300 tests, bulk operations require dropping to raw `sqlite3` commands. This is error-prone and bypasses any validation the CLI could provide.
+
+## Design
+
+### Approach
+
+Add `batch-update` and `batch-map` subcommands under each existing entity command (`feature`, `test`, `module`, `library`). All batch commands share a common filter + dry-run infrastructure.
+
+### Shared Batch Infrastructure
+
+A new `BatchFilters` static class in `Commands/BatchFilters.cs` provides:
+
+**Filter Options** (combined with AND logic):
+- `--ids <range>` — ID range like `100-200`, comma-separated `1,5,10`, or mixed `1-5,10,20-25`
+- `--module <id>` — filter by module_id (feature/test only)
+- `--status <status>` — filter by current status value
+
+**Dry-Run Default:**
+- Without `--execute`, commands show a preview: "Would affect N items:" + table of matching rows
+- With `--execute`, changes are applied inside a transaction and "Updated N items." is printed
+- At least one filter is required (no accidental "update everything" with zero filters)
+
+**Shared Methods:**
+- `AddFilterOptions(Command cmd, bool includeModuleFilter)` — adds the common options to a command
+- `BuildWhereClause(...)` — returns SQL WHERE clause + parameters from parsed filter values
+- `PreviewOrExecute(Database db, string table, string selectSql, string updateSql, params[], bool execute)` — handles dry-run preview vs actual execution
+
+### Feature Batch Commands
+
+**`feature batch-update`**
+- Filters: `--ids`, `--module`, `--status`
+- Setters: `--set-status` (required), `--set-notes` (optional)
+- Flag: `--execute`
+
+**`feature batch-map`**
+- Filters: `--ids`, `--module`, `--status`
+- Setters: `--set-project`, `--set-class`, `--set-method` (at least one required)
+- Flag: `--execute`
+
+### Test Batch Commands
+
+**`test batch-update`**
+- Filters: `--ids`, `--module`, `--status`
+- Setters: `--set-status` (required), `--set-notes` (optional)
+- Flag: `--execute`
+
+**`test batch-map`**
+- Filters: `--ids`, `--module`, `--status`
+- Setters: `--set-project`, `--set-class`, `--set-method` (at least one required)
+- Flag: `--execute`
+
+### Module Batch Commands
+
+**`module batch-update`**
+- Filters: `--ids`, `--status`
+- Setters: `--set-status` (required), `--set-notes` (optional)
+- Flag: `--execute`
+
+**`module batch-map`**
+- Filters: `--ids`, `--status`
+- Setters: `--set-project`, `--set-namespace`, `--set-class` (at least one required)
+- Flag: `--execute`
+
+### Library Batch Commands
+
+**`library batch-update`**
+- Filters: `--ids`, `--status`
+- Setters: `--set-status` (required), `--set-notes` (optional, maps to `dotnet_usage_notes`)
+- Flag: `--execute`
+
+**`library batch-map`**
+- Filters: `--ids`, `--status`
+- Setters: `--set-package`, `--set-namespace`, `--set-notes` (at least one required)
+- Flag: `--execute`
+
+## Examples
+
+```bash
+# Preview: which features in module 5 are not_started?
+porttracker feature batch-update --module 5 --status not_started --set-status deferred
+
+# Execute: defer all features in module 5 with a reason
+porttracker feature batch-update --module 5 --status not_started --set-status deferred --set-notes "needs server runtime" --execute
+
+# Execute: mark tests 500-750 as deferred
+porttracker test batch-update --ids 500-750 --set-status deferred --set-notes "server-integration" --execute
+
+# Execute: batch-map all features in module 3 to a .NET project
+porttracker feature batch-map --module 3 --set-project "ZB.MOM.NatsNet.Server" --execute
+
+# Preview: what libraries are unmapped?
+porttracker library batch-update --status not_mapped --set-status mapped
+
+# Execute: batch-map libraries
+porttracker library batch-map --ids 1-20 --set-package "Microsoft.Extensions.Logging" --set-namespace "Microsoft.Extensions.Logging" --execute
+```
+
+## File Changes
+
+| File | Change |
+|------|--------|
+| `Commands/BatchFilters.cs` | New — shared filter options, WHERE builder, preview/execute logic |
+| `Commands/FeatureCommands.cs` | Add `batch-update` and `batch-map` subcommands |
+| `Commands/TestCommands.cs` | Add `batch-update` and `batch-map` subcommands |
+| `Commands/ModuleCommands.cs` | Add `batch-update` and `batch-map` subcommands |
+| `Commands/LibraryCommands.cs` | Add `batch-update` and `batch-map` subcommands |
+| `Data/Database.cs` | Add `ExecuteInTransaction` helper for batch safety |
+
+## Non-Goals
+
+- No batch create or batch delete — not needed for the porting workflow
+- No raw `--where` SQL escape hatch — structured filters cover all use cases
+- No interactive y/n prompts — dry-run + `--execute` flag is sufficient and scriptable

reports/current.md

@@ -1,6 +1,6 @@
 # NATS .NET Porting Status Report
 
-Generated: 2026-02-27 02:53:53 UTC
+Generated: 2026-02-27 09:34:53 UTC
 
 ## Modules (12 total)
 

reports/report_11ec33d.md

@@ -0,0 +1,35 @@
+# NATS .NET Porting Status Report
+
+Generated: 2026-02-27 09:34:53 UTC
+
+## Modules (12 total)
+
+| Status | Count |
+|--------|-------|
+| verified | 12 |
+
+## Features (3673 total)
+
+| Status | Count |
+|--------|-------|
+| deferred | 3394 |
+| verified | 279 |
+
+## Unit Tests (3257 total)
+
+| Status | Count |
+|--------|-------|
+| deferred | 2680 |
+| n_a | 187 |
+| verified | 390 |
+
+## Library Mappings (36 total)
+
+| Status | Count |
+|--------|-------|
+| mapped | 36 |
+
+
+## Overall Progress
+
+**868/6942 items complete (12.5%)**