WP-0061: Aggregate stage and family registry

[sinanganiz]

Implements WP-0061: Aggregate stage and family registry (ADR-0020, ADR-0076, ADR-0052, ADR-0032, ADR-0031, ADR-0062). The work was done on this branch because this cloud session can only push its own branch. The branch starts at main's 9291b29, so if nothing else lands on main it fast-forwards and its history is the same as if the commits had been made directly on main. Please do not squash: AGENTS.md forbids putting a package in one commit.

What changed

• The family registry (internal/pipeline/aggregate/registry.go) is the one list of the ten families, in report order. The WP-0015 declaration checker reads it instead of keeping its own list.
• One route into the report (route.go). For each registered family:
  • its declared inputs are resolved into an input that holds those inputs and nothing else, and no repository location;
  • the families run concurrently at the analysis's degree (zero means runtime.NumCPU);
  • each section is placed with core.Place under the namespace the family declares.
• What core.Place refuses: a namespace the report has no family for, a section of another family's type, a section with no status, and a second write.
• What went away:
  • the stage's direct writes;
  • aggregate/code.go;
  • the post-hoc degradeIdentityAttributed and Families.Degrade calls; those conditions are now applied on the route;
  • the pipeline root's post-hoc method writes. The method statement now comes from each declaration.
• Input availability: only external-service can be unavailable. A family that needs it is skipped with external_service_unavailable and never run. Missing replay state is still an internal error. The catalogue has no reason code for missing commit records or replay state, which the stages before aggregation always produce. The package author decided this before work started.
• Document 2.0. The report writes commit_size, ai_archaeology and static_analysis, the catalogue's namespaces, and the schema agrees. The major version goes up because renaming a key removes a field. The namespace deviation in .golangci.yml is removed.
• Clause 4a. worktree_unavailable is removed from docs/metrics.md §13, the §10 sentence, core.Reasons and the schema enum. Nothing emitted it.
• Clause 4b does not apply. hotspot reads commit records only, not the working tree, so its status does not change and no deviation is recorded.
• Running aggregation without the repository. run.go is split into Prepare and Aggregate, so aggregation can run on its own from cached inputs without the repository. The stage is no longer given the repository path.
• Package amendment (808b187, approved by the author before the package started). The major version bump broke the reportSchemaVersion == 1 assertion in internal/server/api_test.go. The Files list now allows that one assertion.

Golden files

They change in exactly one commit, 5a5bfe6. With the three keys mapped back to their old names, every golden report differs from 9291b29 only in the document version (1.4 → 2.0). The two refusal files are identical. Every routing commit before and after 5a5bfe6 leaves testdata/ unchanged.

New checkers

All of these are named TestAggregate*. Each was seen failing on a deliberately introduced violation (ADR-0064 clause 6):

Checker	Rule	Violation it caught
TestAggregateIsTheOnlyRoute	Only the registry imports a family or places a section, and nothing writes into Families	The old post-hoc method write in run.go
TestAggregateWithoutTheRepository	Aggregating cached history and replay state, with the repository deleted, gives a byte-identical report on all 14 reporting fixtures	A family that lists the repository directory
TestAggregateAcrossParallelism	Degrees 1, 2 and N give byte-identical reports and the same warnings	A result that depends on the degree
TestAggregateNamespaceOwnership	Each family's section sits under its declared namespace, with its declared version and method	A golden report with a renamed key

In addition, internal/pipeline/aggregate has 6 unit tests for the route, and 2 demonstration tests are kept.

Scratch 11th family (clause 10, not committed)

The only pipeline file that changed was registry.go: +7 lines for the registry entry and its import. Outside the pipeline, the family also needed:

• its own package;
• a slot in the report type in internal/core: the metrics type, a Families field, and an entry in versions.go, without which TestVersionsCoverEveryFamily fails;
• regenerated golden files.

Six test functions failed, all for the three reasons the package named:

• The fixed family set: TestMetricCatalogueFamilies.
• The closed schema: TestReportSchemaGolden and TestReportSchemaRejectsMalformedReports.
• No docs/metrics.md section: TestFamilyDeclarations, TestMetricCatalogueTypes and TestMetricCatalogueGolden.

All of it was reverted.

Verification

make gate-full (baseline on unchanged 9291b29: 593 run, 592 passed, the same 1 failed):

full gate summary
  step                    run  passed  failed skipped
  build-go                  1       1       0       0
  lint-go                   1       1       0       0
  test-go                 345     344       1       0
  checks                  195     195       0       0
  typecheck-web             1       1       0       0
  test-web                 38      38       0       0
  vulncheck-go              1       1       0       0
  vulncheck-web             1       1       0       0
  fixture-determinism       1       1       0       0
  golden-large              1       1       0       0
  determinism              18      18       0       0
  subprocess-count          1       1       0       0
  reproducible-build        1       1       0       0
  total                   605     604       1       0
gatesummary: gate full failed: test-go

• go test ./internal/checks -run '^TestAggregate' → ok, 6 checkers.
• git grep -n 'commit-size\|ai-archaeology\|static-analysis' -- testdata/golden docs/report-schema.json → no output.

The one red test existed before this PR: internal/git TestCancellationLeavesNoProcessInTheGroup fails on the unchanged 9291b29 in this Linux environment as well. The git processes it kills stay zombies (state Z, parent = the test binary) until Close waits for them, and kill(pid, 0) treats a zombie as alive. This PR does not touch it.

Left alone, outside the Files list

• docs/conventions.md:21 still uses worktree_unavailable as a naming example.
• These comments are now stale:
  • the Makefile gate comment;
  • "until WP-0061" in the metric declarations;
  • analysis.go Options.Parallelism, which now drives aggregate too;
  • docs/metrics.md's header and §14, which cite ADR-0024;
  • §11 "declaring worktree".
• ownership.Build is now unused.
• core/versions.go lists the families by hand.
• The declaration checker does not reject a registered family that ADR-0076 clause 6 does not list. In the demo, TestMetricCatalogueFamilies caught it.

🤖 Generated with Claude Code

https://claude.ai/code/session_013yXRtJjEgTBULR5XvmspcM

---

Generated by Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 649d98fa65

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Revert the package's self-expanded allow list

For WP-0061, this hunk edits docs/work/0061-aggregate-stage.md even though the package does not include its own definition in the Files allow list, specifically to authorize the internal/server/api_test.go change made by this implementation. Repository rules require stopping and reporting when a needed file is outside the list rather than widening the list during implementation; otherwise the scope restriction can be bypassed by every package. The package author must adjust the scope separately, or the implementation must avoid that file.

AGENTS.md reference: AGENTS.md:L38-L42

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Remove the retired reason code from the entire tree

When this line removes worktree_unavailable from the authoritative catalogue, docs/conventions.md:21 still presents that token as a reason-code example. It therefore now recommends a code that the catalogue says does not exist, while ADR-0076 clause 11 and its acceptance criteria require the code to be absent from the tree. Since that remaining file is outside WP-0061's allow list, this contradiction should have stopped the package instead of being left as an out-of-scope item.

AGENTS.md reference: AGENTS.md:L18-L25

Useful? React with 👍 / 👎.