natsdotnet/gaps/execution.md

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:

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.