Merge pull request #278 from morluto/agent/cleanup-hotspot-audit

Harden bounded cleanup workflows

Author: morluto

.github/workflows/release.yml

@@ -207,6 +207,11 @@ jobs:
           ' <<<"$metadata"
       - name: Publish npm package
         run: npm publish --provenance --access public
+      - name: Verify npm publication is publicly discoverable
+        shell: bash
+        env:
+          VERSION: ${{ inputs.release_tag || github.ref_name }}
+        run: node scripts/verify-npm-publication.mjs "${VERSION#v}"
       - name: Attach npm package to GitHub release
         env:
           GH_TOKEN: ${{ github.token }}

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "1.1.0"
+  ".": "2.0.0"
 }

CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [2.0.0] (2026-08-09)
+
+### ⚠ BREAKING CHANGES
+
+* **mcp:** `github.search_threads` and `github.read_source_files` now require
+  `repository: {owner, repo}`. Flat `owner` and `repo` request fields are no
+  longer accepted. See [the v2 MCP migration guide](docs/mcp-v2-migration.md).
+
+### Features
+
+* **mcp:** add optional repository scope to authored pull-request portfolios.
+
+### Bug Fixes
+
+* **mcp:** return host-neutral native resource links for durable artifacts.
+
 ## [1.1.0](https://github.com/morluto/gitcontribute/compare/v1.0.0...v1.1.0) (2026-08-08)
 
 

CONTRIBUTING.md

@@ -64,6 +64,10 @@ filesystem locks, job ownership, or cancellation:
 make test-race
 ```
 
+The focused race lane defaults to four in-package test slots. On a constrained
+machine, lower only that setting without reducing the package-level race
+coverage, for example `make test-race RACE_TEST_PARALLELISM=2`.
+
 The SQLite driver is pure Go. Keep CGO-disabled compatibility when changing
 storage or build dependencies.
 

Makefile

@@ -17,6 +17,7 @@ GOTESTSUM ?= $(shell command -v gotestsum 2>/dev/null || printf '%s/bin/gotestsu
 # use more than the historical four-test cap.
 TEST_PARALLELISM ?= 8
 TEST_PACKAGE_PARALLELISM ?= 8
+RACE_TEST_PARALLELISM ?= 4
 INTEGRATION_PARALLELISM ?= 4
 GOTESTSUM_FLAGS ?= --rerun-fails=2 --rerun-fails-max-failures=5
 
@@ -79,12 +80,12 @@ test-uncached:
 test-race:
 	# Keep package-level overlap for cross-package race coverage while bounding
 	# in-process test concurrency for the CPU-heavy SQLite tests.
-	$(GO) test -short -race -p=4 -parallel=2 -timeout 600s ./internal/app ./internal/corpus ./internal/workspace
+	$(GO) test -short -race -p=4 -parallel=$(RACE_TEST_PARALLELISM) -timeout 600s ./internal/app ./internal/corpus ./internal/mcpserver ./internal/workspace
 
 test-race-full:
 	# Keep package-level overlap for cross-package race coverage while bounding
 	# in-process test concurrency for the CPU-heavy SQLite tests.
-	$(GO) test -race -p=4 -parallel=2 -count=1 -timeout 900s ./...
+	$(GO) test -race -p=4 -parallel=$(RACE_TEST_PARALLELISM) -count=1 -timeout 900s ./...
 
 test-verbose:
 	$(GO) test -short -v -p=$(TEST_PACKAGE_PARALLELISM) -parallel=$(TEST_PARALLELISM) -timeout 120s ./...
@@ -143,4 +144,4 @@ test-integration:
 
 check: fmt-check test lint-changed
 
-verify: fmt-check test-uncached lint-full tidy-check generate-check docs-check
+verify: fmt-check vet test-uncached lint-full tidy-check generate-check docs-check

docs/architecture.md

@@ -138,8 +138,9 @@ known zero merge rate remains distinct from an unknown rate.
 
 Pull-request portfolios use the ordinary repository and thread projections.
 `github.sync_pull_request_portfolio` is the only public portfolio producer. Its
-discriminated selection is either authored discovery or an explicit bounded
-set; identity lookup, authored discovery, and scalar status refresh are
+discriminated selection is either authored discovery (optionally scoped to one
+repository) or an explicit bounded set; identity lookup, authored discovery,
+and scalar status refresh are
 internal phases rather than separately advertised operations.
 REST `pr_details` and `pr_reviews` facets are combined with typed GraphQL
 facets for checks, unresolved review threads, detailed merge state, merge queue,
@@ -398,10 +399,11 @@ live GitHub request
   -> local resources/read
 ```
 
-`github.search_threads` persists the returned issue or pull-request
+`github.search_threads` accepts a required nested repository reference and persists the returned issue or pull-request
 observations and an exact `github-thread-search.v1` result artifact. A search
 page never advances repository-wide thread coverage and an empty page is not
-proof that no matching live thread exists. `github.read_source_files` resolves
+proof that no matching live thread exists. `github.read_source_files` accepts
+the same required nested repository reference, resolves
 one named ref to a commit, reads bounded repository-relative files in input
 order, and stores a `source-bundle.v1` artifact. Commit SHA is the authoritative
 revision; GitHub blob SHA remains a separate file identity. Source content is

docs/mcp-composed-workflows.md

@@ -103,8 +103,8 @@ revision authority and are not treated as GitContribute execution results.
 ## Contribution collision checks
 
 ```text
-github.search_threads (bounded current work)
-github.sync_pull_request_portfolio(selection=authored) -> jobs.get
+github.search_threads(repository={owner,repo}, bounded current work)
+github.sync_pull_request_portfolio(selection=authored, repository={owner,repo}) -> jobs.get
 corpus.search_pull_requests | corpus.find_pull_request_overlaps
 workspace.check_merge_conflicts (only after explicit acquisition)
 ```

docs/mcp-scalable-workflows.md

@@ -40,6 +40,9 @@ merge details, checks, files, and other children require explicit facets.
 `github.read_source_files` resolves a ref once and reads up to 20 ordered
 repository-relative files with per-file and total-byte limits. Its immutable
 source-bundle resource records the resolved commit and blob provenance.
+Both live repository acquisitions require `repository: {owner, repo}`. See the
+[v2 migration guide](mcp-v2-migration.md) for request examples; flat owner and
+repo arguments are rejected.
 
 `corpus.search_code` accepts up to 20 queries over one repository or snapshot
 scope. Every query uses the same offline corpus revision. It never falls back
@@ -97,6 +100,8 @@ Exact PR refresh uses `github.sync_pull_request_feedback`. CI uses
 `github.sync_pull_request_ci`; checks and statuses are bound to the observed
 head SHA. Offline authored-PR reads use `corpus.search_pull_requests`, and
 overlap analysis uses `corpus.find_pull_request_overlaps`.
+Use `repository: {owner, repo}` with authored portfolio synchronization or
+offline portfolio reads when the portfolio must be constrained to one project.
 
 ## Jobs, partial results, and recovery
 

docs/mcp-v2-migration.md

@@ -0,0 +1,71 @@
+# MCP v2 migration: repository-bound live acquisition
+
+Version 2 removes the flat `owner` and `repo` fields from the two live
+repository-acquisition tools. Both now require one nested `repository` object.
+There are no compatibility aliases or mixed forms: callers must update every
+request, recovery replay, and saved tool call before connecting to a v2 server.
+
+## `github.search_threads`
+
+Before (v1):
+
+```json
+{
+  "owner": "acme",
+  "repo": "rocket",
+  "query": "cache eviction",
+  "kind": "issue"
+}
+```
+
+After (v2):
+
+```json
+{
+  "repository": {"owner": "acme", "repo": "rocket"},
+  "query": "cache eviction",
+  "kind": "issue"
+}
+```
+
+## `github.read_source_files`
+
+Before (v1):
+
+```json
+{
+  "owner": "acme",
+  "repo": "rocket",
+  "ref": "main",
+  "files": [{"path": "README.md"}]
+}
+```
+
+After (v2):
+
+```json
+{
+  "repository": {"owner": "acme", "repo": "rocket"},
+  "ref": "main",
+  "files": [{"path": "README.md"}]
+}
+```
+
+The tools still return an opaque artifact URI. Follow that URI only through MCP
+`resources/read`; the resource reader remains local and offline.
+
+## Scoped authored portfolios
+
+`github.sync_pull_request_portfolio` accepts the same optional `repository`
+scope only with `selection: "authored"`. The returned job follow-up and a
+truncated `corpus.search_pull_requests` recovery retain that scope. Explicit
+pull-request selections are already exact and reject `repository`.
+
+```json
+{
+  "selection": "authored",
+  "repository": {"owner": "acme", "repo": "rocket"},
+  "state": "open",
+  "limit": 20
+}
+```

docs/onboarding.md

@@ -230,7 +230,8 @@ One tag version controls the Go binaries and npm package. Release automation:
 4. verifies the package has no install lifecycle;
 5. installs the tarball with `--ignore-scripts` and runs a smoke test;
 6. enforces a 100 MB compressed-package ceiling;
-7. publishes the npm package with provenance;
+7. publishes the npm package with provenance and waits for its exact version,
+   `latest` tag, and fresh npx metadata invocation to agree;
 8. publishes matching `server.json` metadata to the MCP Registry with GitHub
    OIDC;
 9. creates a matching GitHub release.