# Category Execution Instructions

Use this runbook to execute one category end-to-end using the `executeplan` skill without running the full test suite.

## Inputs
- `CATEGORY` (example: `protocol`)
- `gaps/plans.md` row for that category (contains category gap file, design file, and plan file paths)

## Required Skills
- `executeplan`
- `using-git-worktrees` (required before implementation)
- `finishing-a-development-branch` (required after implementation)

## Execution Flow
1. Resolve the category row from `gaps/plans.md`.
2. Read the category's design and plan files from the resolved row.
3. Announce: `I'm using executeplan to implement this plan.`
4. Create a brand-new git worktree on a new branch and verify clean status.
5. Execute the plan in batches (`executeplan` default batching), with checkpoints between batches.
6. Run only targeted unit tests for the category after each batch; do not run full-suite tests.
7. After implementation, verify the category gap file reflects the completed work.
8. Update the `Status` column in `gaps/plans.md` for the category:
   - `complete` if no `MISSING` or `PARTIAL` rows remain
   - `<N> remaining` where `N = MISSING + PARTIAL`

## Strict Test Scope Policy
- Never run unscoped full test commands such as:
  - `dotnet test tests/NATS.Server.Tests/NATS.Server.Tests.csproj`
- Always use targeted test execution, for example:
  - `dotnet test tests/NATS.Server.Tests/NATS.Server.Tests.csproj --filter "FullyQualifiedName~Protocol"`
  - `dotnet test tests/NATS.Server.Tests/NATS.Server.Tests.csproj --filter "FullyQualifiedName~JetStream"`
  - `dotnet test tests/NATS.Server.Tests/NATS.Server.Tests.csproj --filter "FullyQualifiedName~Auth"`
- If one filter is too broad, split into multiple narrow filters and run them separately.

## Suggested Category Filter Tokens
Use these as starting points for `--filter "FullyQualifiedName~<token>"`:

| Category | Token(s) |
|---|---|
| `core-server` | `Server`, `Client` |
| `protocol` | `Protocol`, `Parser` |
| `subscriptions` | `Subscription` |
| `auth-and-accounts` | `Auth`, `Account` |
| `configuration` | `Configuration`, `Config` |
| `routes` | `Route` |
| `gateways` | `Gateway` |
| `leaf-nodes` | `Leaf` |
| `jetstream` | `JetStream` |
| `raft` | `Raft` |
| `mqtt` | `Mqtt` |
| `websocket` | `WebSocket` |
| `monitoring` | `Monitoring` |
| `events` | `Event` |
| `tls-security` | `Tls`, `Security` |
| `internal-ds` | `Internal` |
| `logging` | `Log`, `Logging` |
| `utilities-and-other` | `IO`, `Server` |
| `misc-uncategorized` | `Misc`, `Server` |

## Gap Verification Rules (Category Gap File)
For the category gap file (`gaps/<category>.md`):
1. Every implemented item must be updated in the Gap Inventory.
2. Each newly completed row must include:
   - `Status = PORTED`
   - concrete `.NET Equivalent` file:line
   - concise notes for parity behavior
3. If behavior is still partial, keep `PARTIAL` and document what is still missing.
4. Do not mark `complete` in `gaps/plans.md` until both `MISSING` and `PARTIAL` counts are zero.

## Status Update Command Snippet
After finishing a category, compute remaining gaps:

```bash
remaining=$(awk -F'|' '
  NF >= 4 {
    s=$4
    gsub(/^ +| +$/, "", s)
    if (s=="MISSING" || s=="PARTIAL") c++
  }
  END { print c+0 }
' "gaps/${CATEGORY}.md")

if [ "$remaining" -eq 0 ]; then
  status_value="complete"
else
  status_value="${remaining} remaining"
fi
```

Then write `status_value` into that category row in `gaps/plans.md`.