docs: link completion criteria to Gitea issues and add issue tracking guidance

- Created 52 Gitea issues across milestones 1-7, one per completion criterion - Each criterion now links to its corresponding issue ([#N](url) format) - Milestone Tracking sections updated with Issue Updates subsection: when/how to comment, close issues via CLI or web UI - Phases 4-7 criteria converted from plain bullets to checkbox format
2026-02-26 06:50:08 -05:00
parent 6983cb60bb
commit 6021d8445e
7 changed files with 170 additions and 51 deletions
--- a/docs/plans/phases/phase-1-decomposition.md
+++ b/docs/plans/phases/phase-1-decomposition.md
@@ -37,6 +37,23 @@ echo $CGO_ENABLED   # should print 1 (or be unset; we set it explicitly below)

 This phase corresponds to **Milestone 1** in [Gitea](https://gitea.dohertylan.com/dohertj2/natsnet/milestone/1). When starting this phase, verify the milestone is open. Assign relevant issues to this milestone as work progresses.

+### Issue Updates
+
+Each completion criterion has a corresponding Gitea issue. Update issues as you work:
+
+- **Starting a criterion**: Add a comment noting work has begun
+- **Blocked**: Add a comment describing the blocker
+- **Complete**: Close the issue with a comment summarizing the result (e.g., counts, verification output)
+
+Close issues via CLI:
+```bash
+curl -s -X PATCH "https://gitea.dohertylan.com/api/v1/repos/dohertj2/natsnet/issues/{N}" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: token $GITEA_TOKEN" \
+  -d '{"state":"closed"}'
+```
+Or close via the Gitea web UI.
+
 ## Steps

 ### Step 1: Initialize the porting database
@@ -201,16 +218,16 @@ dotnet run --project tools/NatsNet.PortTracker -- report export --format md --ou

 Phase 1 is complete when ALL of the following are true:

- [ ] `porting.db` exists and contains data in all five tables (modules, features,
+- [ ] [#1](https://gitea.dohertylan.com/dohertj2/natsnet/issues/1) `porting.db` exists and contains data in all five tables (modules, features,
      unit_tests, dependencies, library_mappings).
- [ ] All Go source files under `golang/nats-server/server/` are accounted for
+- [ ] [#2](https://gitea.dohertylan.com/dohertj2/natsnet/issues/2) All Go source files under `golang/nats-server/server/` are accounted for
      (no files silently skipped without a logged warning).
- [ ] All public and private functions/methods are extracted as features.
- [ ] All `Test*` and `Benchmark*` functions are extracted as unit_tests.
- [ ] Test-to-feature links are populated where naming conventions allow inference.
- [ ] Module-level dependencies are recorded in the dependencies table.
- [ ] External import paths are recorded in the library_mappings table.
- [ ] `phase check 1` shows all checklist items marked `[x]`:
+- [ ] [#3](https://gitea.dohertylan.com/dohertj2/natsnet/issues/3) All public and private functions/methods are extracted as features.
+- [ ] [#4](https://gitea.dohertylan.com/dohertj2/natsnet/issues/4) All `Test*` and `Benchmark*` functions are extracted as unit_tests.
+- [ ] [#5](https://gitea.dohertylan.com/dohertj2/natsnet/issues/5) Test-to-feature links are populated where naming conventions allow inference.
+- [ ] [#6](https://gitea.dohertylan.com/dohertj2/natsnet/issues/6) Module-level dependencies are recorded in the dependencies table.
+- [ ] [#7](https://gitea.dohertylan.com/dohertj2/natsnet/issues/7) External import paths are recorded in the library_mappings table.
+- [ ] [#8](https://gitea.dohertylan.com/dohertj2/natsnet/issues/8) `phase check 1` shows all checklist items marked `[x]`:

 ```bash
 dotnet run --project tools/NatsNet.PortTracker -- phase check 1 --db porting.db
--- a/docs/plans/phases/phase-2-verification.md
+++ b/docs/plans/phases/phase-2-verification.md
@@ -25,6 +25,23 @@ proceeding to library mapping and porting.

 This phase corresponds to **Milestone 2** in [Gitea](https://gitea.dohertylan.com/dohertj2/natsnet/milestone/2). When starting this phase, verify the milestone is open. Assign relevant issues to this milestone as work progresses.

+### Issue Updates
+
+Each completion criterion has a corresponding Gitea issue. Update issues as you work:
+
+- **Starting a criterion**: Add a comment noting work has begun
+- **Blocked**: Add a comment describing the blocker
+- **Complete**: Close the issue with a comment summarizing the result (e.g., counts, verification output)
+
+Close issues via CLI:
+```bash
+curl -s -X PATCH "https://gitea.dohertylan.com/api/v1/repos/dohertj2/natsnet/issues/{N}" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: token $GITEA_TOKEN" \
+  -d '{"state":"closed"}'
+```
+Or close via the Gitea web UI.
+
 ## Steps

 ### Step 1: Generate the summary report
@@ -256,19 +273,19 @@ dotnet run --project tools/NatsNet.PortTracker -- report export \

 Phase 2 is complete when ALL of the following are true:

- [ ] Source file counts on disk match distinct `go_file` counts in the database
+- [ ] [#9](https://gitea.dohertylan.com/dohertj2/natsnet/issues/9) Source file counts on disk match distinct `go_file` counts in the database
      (within a small margin for intentionally excluded directories).
- [ ] Feature counts from `grep` are within 5% of the database count (AST is the
+- [ ] [#10](https://gitea.dohertylan.com/dohertj2/natsnet/issues/10) Feature counts from `grep` are within 5% of the database count (AST is the
      authoritative source).
- [ ] Test function counts from `grep` match the database count closely.
- [ ] No orphaned features (all linked to valid modules).
- [ ] No orphaned tests (all linked to valid modules).
- [ ] No broken test-to-feature links.
- [ ] No dangling dependency references.
- [ ] Dependency graph is reviewed -- circular deps (if any) are acknowledged.
- [ ] `dependency ready` returns at least one item (the graph has valid roots).
- [ ] Library mappings table contains all external imports.
- [ ] `phase check 1` passes with all items except "All libraries mapped" checked.
+- [ ] [#11](https://gitea.dohertylan.com/dohertj2/natsnet/issues/11) Test function counts from `grep` match the database count closely.
+- [ ] [#12](https://gitea.dohertylan.com/dohertj2/natsnet/issues/12) No orphaned features (all linked to valid modules).
+- [ ] [#13](https://gitea.dohertylan.com/dohertj2/natsnet/issues/13) No orphaned tests (all linked to valid modules).
+- [ ] [#14](https://gitea.dohertylan.com/dohertj2/natsnet/issues/14) No broken test-to-feature links.
+- [ ] [#15](https://gitea.dohertylan.com/dohertj2/natsnet/issues/15) No dangling dependency references.
+- [ ] [#16](https://gitea.dohertylan.com/dohertj2/natsnet/issues/16) Dependency graph is reviewed -- circular deps (if any) are acknowledged.
+- [ ] [#17](https://gitea.dohertylan.com/dohertj2/natsnet/issues/17) `dependency ready` returns at least one item (the graph has valid roots).
+- [ ] [#18](https://gitea.dohertylan.com/dohertj2/natsnet/issues/18) Library mappings table contains all external imports.
+- [ ] [#19](https://gitea.dohertylan.com/dohertj2/natsnet/issues/19) `phase check 1` passes with all items except "All libraries mapped" checked.
 - [ ] Close the Phase 2 milestone in Gitea:
  ```bash
  curl -s -X PATCH "https://gitea.dohertylan.com/api/v1/repos/dohertj2/natsnet/milestones/2" \
--- a/docs/plans/phases/phase-3-library-mapping.md
+++ b/docs/plans/phases/phase-3-library-mapping.md
@@ -24,6 +24,23 @@ returns an empty list and every import has a documented .NET migration path.

 This phase corresponds to **Milestone 3** in [Gitea](https://gitea.dohertylan.com/dohertj2/natsnet/milestone/3). When starting this phase, verify the milestone is open. Assign relevant issues to this milestone as work progresses.

+### Issue Updates
+
+Each completion criterion has a corresponding Gitea issue. Update issues as you work:
+
+- **Starting a criterion**: Add a comment noting work has begun
+- **Blocked**: Add a comment describing the blocker
+- **Complete**: Close the issue with a comment summarizing the result (e.g., counts, verification output)
+
+Close issues via CLI:
+```bash
+curl -s -X PATCH "https://gitea.dohertylan.com/api/v1/repos/dohertj2/natsnet/issues/{N}" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: token $GITEA_TOKEN" \
+  -d '{"state":"closed"}'
+```
+Or close via the Gitea web UI.
+
 ## Steps

 ### Step 1: List all unmapped libraries
@@ -249,13 +266,13 @@ For each mapping, consider:

 Phase 3 is complete when ALL of the following are true:

- [ ] `library suggest` returns "All libraries have been mapped!"
- [ ] Every entry in `library list` shows status `mapped` or `verified`.
- [ ] Each mapping includes a `--package` (the NuGet package or BCL assembly),
+- [ ] [#30](https://gitea.dohertylan.com/dohertj2/natsnet/issues/30) `library suggest` returns "All libraries have been mapped!"
+- [ ] [#21](https://gitea.dohertylan.com/dohertj2/natsnet/issues/21) Every entry in `library list` shows status `mapped` or `verified`.
+- [ ] [#22](https://gitea.dohertylan.com/dohertj2/natsnet/issues/22) Each mapping includes a `--package` (the NuGet package or BCL assembly),
      a `--namespace` (the .NET namespace to use), and `--notes` (migration
      guidance).
- [ ] `phase check 1` shows all items checked including "All libraries mapped".
- [ ] A mapping report has been exported for reference.
+- [ ] [#23](https://gitea.dohertylan.com/dohertj2/natsnet/issues/23) `phase check 1` shows all items checked including "All libraries mapped".
+- [ ] [#24](https://gitea.dohertylan.com/dohertj2/natsnet/issues/24) A mapping report has been exported for reference.
 - [ ] Close the Phase 3 milestone in Gitea:
  ```bash
  curl -s -X PATCH "https://gitea.dohertylan.com/api/v1/repos/dohertj2/natsnet/milestones/3" \
--- a/docs/plans/phases/phase-4-dotnet-design.md
+++ b/docs/plans/phases/phase-4-dotnet-design.md
@@ -20,6 +20,23 @@ Every module, feature, and test in the porting database must have either a .NET

 This phase corresponds to **Milestone 4** in [Gitea](https://gitea.dohertylan.com/dohertj2/natsnet/milestone/4). When starting this phase, verify the milestone is open. Assign relevant issues to this milestone as work progresses.

+### Issue Updates
+
+Each completion criterion has a corresponding Gitea issue. Update issues as you work:
+
+- **Starting a criterion**: Add a comment noting work has begun
+- **Blocked**: Add a comment describing the blocker
+- **Complete**: Close the issue with a comment summarizing the result (e.g., counts, verification output)
+
+Close issues via CLI:
+```bash
+curl -s -X PATCH "https://gitea.dohertylan.com/api/v1/repos/dohertj2/natsnet/issues/{N}" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: token $GITEA_TOKEN" \
+  -d '{"state":"closed"}'
+```
+Or close via the Gitea web UI.
+
 ## Solution Structure

 Define the .NET solution layout following standard conventions:
@@ -184,11 +201,11 @@ dotnet run --project tools/NatsNet.PortTracker -- feature list --status n_a --db

 ## Completion Criteria

- Every module has `dotnet_project` and `dotnet_namespace` set, or status is `n_a` with a reason
- Every feature has `dotnet_project`, `dotnet_class`, and `dotnet_method` set, or status is `n_a` with a reason
- Every test has `dotnet_project`, `dotnet_class`, and `dotnet_method` set, or status is `n_a` with a reason
- Naming follows PascalCase and the namespace hierarchy described above
- No two features map to the same class + method combination (collisions)
+- [ ] [#25](https://gitea.dohertylan.com/dohertj2/natsnet/issues/25) Every module has `dotnet_project` and `dotnet_namespace` set, or status is `n_a` with a reason
+- [ ] [#26](https://gitea.dohertylan.com/dohertj2/natsnet/issues/26) Every feature has `dotnet_project`, `dotnet_class`, and `dotnet_method` set, or status is `n_a` with a reason
+- [ ] [#27](https://gitea.dohertylan.com/dohertj2/natsnet/issues/27) Every test has `dotnet_project`, `dotnet_class`, and `dotnet_method` set, or status is `n_a` with a reason
+- [ ] [#28](https://gitea.dohertylan.com/dohertj2/natsnet/issues/28) Naming follows PascalCase and the namespace hierarchy described above
+- [ ] [#29](https://gitea.dohertylan.com/dohertj2/natsnet/issues/29) No two features map to the same class + method combination (collisions)
 - [ ] Close the Phase 4 milestone in Gitea:
  ```bash
  curl -s -X PATCH "https://gitea.dohertylan.com/api/v1/repos/dohertj2/natsnet/milestones/4" \
--- a/docs/plans/phases/phase-5-mapping-verification.md
+++ b/docs/plans/phases/phase-5-mapping-verification.md
@@ -20,6 +20,23 @@ Confirm zero unmapped items, validate all N/A justifications, enforce naming con

 This phase corresponds to **Milestone 5** in [Gitea](https://gitea.dohertylan.com/dohertj2/natsnet/milestone/5). When starting this phase, verify the milestone is open. Assign relevant issues to this milestone as work progresses.

+### Issue Updates
+
+Each completion criterion has a corresponding Gitea issue. Update issues as you work:
+
+- **Starting a criterion**: Add a comment noting work has begun
+- **Blocked**: Add a comment describing the blocker
+- **Complete**: Close the issue with a comment summarizing the result (e.g., counts, verification output)
+
+Close issues via CLI:
+```bash
+curl -s -X PATCH "https://gitea.dohertylan.com/api/v1/repos/dohertj2/natsnet/issues/{N}" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: token $GITEA_TOKEN" \
+  -d '{"state":"closed"}'
+```
+Or close via the Gitea web UI.
+
 ## Steps

 ### Step 1: Confirm zero unmapped items
@@ -187,14 +204,14 @@ dotnet run --project tools/NatsNet.PortTracker -- feature map <id> \

 ## Completion Criteria

- Zero items in `not_started` status without a .NET mapping
- All N/A items have a documented, valid reason
- All `dotnet_class` and `dotnet_method` values follow PascalCase
- All namespaces follow `ZB.MOM.NatsNet.Server.[Module]` hierarchy
- No two features map to the same class + method combination
- All tests target the correct test project
- `phase check 5` passes with no errors
- Mapping report exported and reviewed
+- [ ] [#31](https://gitea.dohertylan.com/dohertj2/natsnet/issues/31) Zero items in `not_started` status without a .NET mapping
+- [ ] [#32](https://gitea.dohertylan.com/dohertj2/natsnet/issues/32) All N/A items have a documented, valid reason
+- [ ] [#33](https://gitea.dohertylan.com/dohertj2/natsnet/issues/33) All `dotnet_class` and `dotnet_method` values follow PascalCase
+- [ ] [#34](https://gitea.dohertylan.com/dohertj2/natsnet/issues/34) All namespaces follow `ZB.MOM.NatsNet.Server.[Module]` hierarchy
+- [ ] [#35](https://gitea.dohertylan.com/dohertj2/natsnet/issues/35) No two features map to the same class + method combination
+- [ ] [#36](https://gitea.dohertylan.com/dohertj2/natsnet/issues/36) All tests target the correct test project
+- [ ] [#37](https://gitea.dohertylan.com/dohertj2/natsnet/issues/37) `phase check 5` passes with no errors
+- [ ] [#38](https://gitea.dohertylan.com/dohertj2/natsnet/issues/38) Mapping report exported and reviewed
 - [ ] Close the Phase 5 milestone in Gitea:
  ```bash
  curl -s -X PATCH "https://gitea.dohertylan.com/api/v1/repos/dohertj2/natsnet/milestones/5" \
--- a/docs/plans/phases/phase-6-porting.md
+++ b/docs/plans/phases/phase-6-porting.md
@@ -26,6 +26,23 @@ Implement every non-N/A module, feature, and test in the porting database. Work

 This phase corresponds to **Milestone 6** in [Gitea](https://gitea.dohertylan.com/dohertj2/natsnet/milestone/6). When starting this phase, verify the milestone is open. Assign relevant issues to this milestone as work progresses.

+### Issue Updates
+
+Each completion criterion has a corresponding Gitea issue. Update issues as you work:
+
+- **Starting a criterion**: Add a comment noting work has begun
+- **Blocked**: Add a comment describing the blocker
+- **Complete**: Close the issue with a comment summarizing the result (e.g., counts, verification output)
+
+Close issues via CLI:
+```bash
+curl -s -X PATCH "https://gitea.dohertylan.com/api/v1/repos/dohertj2/natsnet/issues/{N}" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: token $GITEA_TOKEN" \
+  -d '{"state":"closed"}'
+```
+Or close via the Gitea web UI.
+
 ## Porting Workflow

 This is the core loop. Repeat until all items are complete.
@@ -248,12 +265,12 @@ dotnet run --project tools/NatsNet.PortTracker -- feature map <id> \

 ## Completion Criteria

- All non-N/A modules have status `complete` or better
- All non-N/A features have status `complete` or better
- All non-N/A tests have status `complete` or better
- The solution compiles without errors: `dotnet build`
- `dependency blocked` returns no items (or only items waiting for Phase 7 verification)
- `report summary` shows the expected completion counts
+- [ ] [#39](https://gitea.dohertylan.com/dohertj2/natsnet/issues/39) All non-N/A modules have status `complete` or better
+- [ ] [#40](https://gitea.dohertylan.com/dohertj2/natsnet/issues/40) All non-N/A features have status `complete` or better
+- [ ] [#41](https://gitea.dohertylan.com/dohertj2/natsnet/issues/41) All non-N/A tests have status `complete` or better
+- [ ] [#42](https://gitea.dohertylan.com/dohertj2/natsnet/issues/42) The solution compiles without errors: `dotnet build`
+- [ ] [#43](https://gitea.dohertylan.com/dohertj2/natsnet/issues/43) `dependency blocked` returns no items (or only items waiting for Phase 7 verification)
+- [ ] [#44](https://gitea.dohertylan.com/dohertj2/natsnet/issues/44) `report summary` shows the expected completion counts
 - [ ] Close the Phase 6 milestone in Gitea:
  ```bash
  curl -s -X PATCH "https://gitea.dohertylan.com/api/v1/repos/dohertj2/natsnet/milestones/6" \
--- a/docs/plans/phases/phase-7-porting-verification.md
+++ b/docs/plans/phases/phase-7-porting-verification.md
@@ -21,6 +21,23 @@ Every ported module passes its targeted tests. Every item in the database reache

 This phase corresponds to **Milestone 7** in [Gitea](https://gitea.dohertylan.com/dohertj2/natsnet/milestone/7). When starting this phase, verify the milestone is open. Assign relevant issues to this milestone as work progresses.

+### Issue Updates
+
+Each completion criterion has a corresponding Gitea issue. Update issues as you work:
+
+- **Starting a criterion**: Add a comment noting work has begun
+- **Blocked**: Add a comment describing the blocker
+- **Complete**: Close the issue with a comment summarizing the result (e.g., counts, verification output)
+
+Close issues via CLI:
+```bash
+curl -s -X PATCH "https://gitea.dohertylan.com/api/v1/repos/dohertj2/natsnet/issues/{N}" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: token $GITEA_TOKEN" \
+  -d '{"state":"closed"}'
+```
+Or close via the Gitea web UI.
+
 ## Verification Workflow

 Work through modules one at a time. Do not move to the next module until the current one is fully verified.
@@ -227,14 +244,14 @@ The issue is at a module boundary. Check:

 ## Completion Criteria

- All non-N/A modules have status `verified`
- All non-N/A features have status `verified`
- All non-N/A tests have status `verified`
- All targeted tests pass: `dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/`
- All integration tests pass: `dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.IntegrationTests/`
- Key behavioral scenarios produce equivalent results on Go and .NET servers
- `phase check 7` passes with no errors
- Final report exported and reviewed
+- [ ] [#45](https://gitea.dohertylan.com/dohertj2/natsnet/issues/45) All non-N/A modules have status `verified`
+- [ ] [#46](https://gitea.dohertylan.com/dohertj2/natsnet/issues/46) All non-N/A features have status `verified`
+- [ ] [#47](https://gitea.dohertylan.com/dohertj2/natsnet/issues/47) All non-N/A tests have status `verified`
+- [ ] [#48](https://gitea.dohertylan.com/dohertj2/natsnet/issues/48) All targeted tests pass: `dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/`
+- [ ] [#49](https://gitea.dohertylan.com/dohertj2/natsnet/issues/49) All integration tests pass: `dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.IntegrationTests/`
+- [ ] [#50](https://gitea.dohertylan.com/dohertj2/natsnet/issues/50) Key behavioral scenarios produce equivalent results on Go and .NET servers
+- [ ] [#51](https://gitea.dohertylan.com/dohertj2/natsnet/issues/51) `phase check 7` passes with no errors
+- [ ] [#52](https://gitea.dohertylan.com/dohertj2/natsnet/issues/52) Final report exported and reviewed
 - [ ] Close the Phase 7 milestone in Gitea:
  ```bash
  curl -s -X PATCH "https://gitea.dohertylan.com/api/v1/repos/dohertj2/natsnet/milestones/7" \