Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,10 +51,10 @@ make check
make verify
```

`make verify` runs uncached tests, changed-code linting, module-tidiness checks,
`make verify` runs uncached tests, full-repository linting, module-tidiness checks,
generated-output verification, and documentation validation. It is the complete
local check, while CI adds platform, coverage, security, and focused race jobs.
`make lint-full` is available for auditing existing repository-wide lint debt.
`make lint-full` runs the full lint check on its own.
Use `make test-uncached` when only a fresh test run is needed.

Use focused race tests for changes involving SQLite transactions, goroutines,
Expand Down
29 changes: 23 additions & 6 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -288,15 +288,18 @@ The agent may inspect the stored request and explicitly resubmit an idempotent
operation after reviewing the failure.

Each `JobExecutor` registers an opaque owner ID and periodically updates its
lease. A new executor reconciles only running jobs whose owner is absent or
stale. It must never fail jobs owned by another live process.
lease. Queued work is persisted with its owner atomically at admission. A new
executor reconciles queued and running jobs whose owner is absent or stale; it
must never fail jobs owned by another live process. Reconciled terminal state
also stops the original worker, and losing the owner stops further admission.

```text
queued -> running -> succeeded
-> failed
-> cancelled
```

Queued work can also fail on restart or be cancelled before it starts.
Terminal states do not transition again. Cancellation is first persisted, then
delivered to an in-process worker directly or observed by one executor-wide
poll that checks all active job IDs together. Executors cap both running and
Expand Down Expand Up @@ -552,9 +555,20 @@ authority; duplicated query columns are checked against that manifest while
decoding and discarded rather than exposed as a second source of truth.

Title, labels, body, and hydrated evidence are materialized into one search
document per thread and ranked by one BM25 invocation. The facet index only
document per thread. Relevance puts threads whose titles match every query
term first, including in `match_mode=any`; one BM25 invocation orders matches
within each group. This prevents unrelated hydrated discussion from pushing a
full title match below an incidental body or facet mention through document
length normalization. The title group uses the same FTS tokenizer and literal
query terms as retrieval, without a second string matcher. The facet index only
identifies the matching evidence source and excerpt. A thread page and its exact
count share one read transaction. Counts use a lean FTS match set rather than
count share one read transaction. Search selects ranked, filtered thread IDs
and the page boundary before generating hydrated excerpts. A materialized page
limits excerpt work to the requested page plus its next-page sentinel. Exact
evidence lookup uses the same attribution SQL over one selected thread, without
constructing evidence for other matching threads. Each search index defines its
BM25 weights once for selection, ordering, pagination, and explanations.
Counts use a lean FTS match set rather than
recomputing ranking and excerpts, and the first-page no-overflow case derives
its total directly from the returned rows.

Expand All @@ -571,15 +585,18 @@ partial search document. Transport pages are collapsed into one semantic facet
document, and matches report the source facet plus a bounded excerpt. Untrusted
discussion remains searchable data and cannot grant capabilities. Cursors
encode their query and scope so they cannot be reused for a different search.
Ordering always has a deterministic tie-breaker.
Thread cursors include the title group and encode filter values structurally,
so punctuation within a label cannot alias a different label set. Ordering
always has a deterministic tie-breaker.
Hydrated search text is materialized once per complete facet replacement and
bounded to 262,144 characters per thread. Results expose
`match_truncated=true` when that bound omitted text; complete API coverage must
not be mistaken for complete search-text coverage.

FTS rank is retrieval evidence and must not be relabeled as a separately
hand-written score. Match explanations report the actual lower-is-better BM25
rank and the indexed document or hydrated facet that supplied the excerpt;
rank (within the title group for thread relevance) and the indexed document
or hydrated facet that supplied the excerpt;
they do not guess token matches with a second string matcher. Freshness and
coverage are separate facts. Lens ranking
uses a bounded population and therefore does not support cursor pagination.
Expand Down
79 changes: 79 additions & 0 deletions docs/audits/2026-09-08/coverage.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# External MCP invocation coverage — 2026-09-08

Every advertised tool was invoked. `returned` means a non-error response, not necessarily complete evidence. `queued` requires the terminal job outcomes in the audit report. Error counts include rejected test inputs and environmental failures. Raw logs and temporary runtime artifacts were removed after the follow-up validation at the user's request. Counts below preserve the original audit summary.

| Tool | Baseline calls | Candidate calls | Observed envelope/status |
| --- | ---: | ---: | --- |
| `code.index_repositories` | 1 | 0 | queued |
| `corpus.analyze_fix_patterns` | 1 | 0 | partial |
| `corpus.ensure_coverage` | 1 | 0 | queued |
| `corpus.explain_match` | 1 | 0 | returned |
| `corpus.find_clusters` | 1 | 0 | complete |
| `corpus.find_competing_pull_requests` | 1 | 1 | partial |
| `corpus.find_duplicates` | 1 | 1 | partial |
| `corpus.find_neighbors` | 1 | 0 | complete |
| `corpus.find_precedents` | 1 | 0 | complete |
| `corpus.find_pull_request_overlaps` | 1 | 0 | complete |
| `corpus.get_actor_facets` | 1 | 0 | returned |
| `corpus.get_actors` | 1 | 0 | returned |
| `corpus.get_coverage` | 1 | 0 | partial |
| `corpus.get_repositories` | 1 | 0 | returned |
| `corpus.get_thread_facets` | 1 | 0 | returned |
| `corpus.get_threads` | 2 | 0 | returned, tool_error |
| `corpus.list_concerns` | 1 | 0 | returned |
| `corpus.materialize_repository_dossier` | 1 | 0 | returned |
| `corpus.rank_contribution_candidates` | 1 | 0 | complete |
| `corpus.search_actors` | 1 | 0 | returned |
| `corpus.search_code` | 1 | 0 | partial |
| `corpus.search_contributions` | 1 | 0 | returned |
| `corpus.search_pull_request_feedback` | 1 | 0 | partial |
| `corpus.search_pull_requests` | 1 | 0 | partial |
| `corpus.search_repositories` | 1 | 0 | returned |
| `corpus.search_threads` | 1 | 3 | returned, tool_error |
| `evidence.import_manifest` | 1 | 0 | returned |
| `github.compare_fork` | 2 | 0 | current, tool_error |
| `github.get_authenticated_identity` | 1 | 0 | tool_error |
| `github.index_pull_request_feedback` | 1 | 0 | queued |
| `github.read_source_files` | 2 | 1 | complete, tool_error |
| `github.search_repositories` | 2 | 0 | complete, tool_error |
| `github.search_threads` | 1 | 0 | partial |
| `github.search_users` | 1 | 0 | returned |
| `github.sync_pull_request_ci` | 2 | 0 | queued, tool_error |
| `github.sync_pull_request_feedback` | 1 | 0 | queued |
| `github.sync_pull_request_portfolio` | 1 | 0 | queued |
| `github.sync_repository_context` | 1 | 0 | queued |
| `github.sync_thread_facets` | 1 | 0 | queued |
| `github.sync_threads` | 1 | 0 | queued |
| `github.sync_user_contributions` | 1 | 0 | queued |
| `github.sync_user_organizations` | 1 | 0 | queued |
| `github.sync_user_pinned_items` | 1 | 0 | queued |
| `github.sync_user_repositories` | 1 | 0 | queued |
| `github.sync_user_social_accounts` | 1 | 0 | queued |
| `github.sync_users` | 1 | 0 | queued |
| `github.wait_pull_request_checks` | 1 | 0 | queued |
| `jobs.cancel` | 1 | 0 | returned |
| `jobs.get` | 6 | 1 | protocol_error, returned |
| `research.query_deepwiki` | 1 | 0 | complete |
| `validation.attach_junit_report` | 1 | 0 | returned |
| `validation.attach_receipt` | 1 | 0 | returned |
| `validation.define` | 1 | 0 | returned |
| `validation.run` | 1 | 0 | queued |
| `workflow.create_concern` | 1 | 0 | returned |
| `workflow.export_manifest` | 2 | 0 | returned, tool_error |
| `workflow.get_catalog_contract` | 1 | 1 | returned |
| `workflow.get_source_audit_contract` | 1 | 0 | returned |
| `workflow.link_concern` | 1 | 0 | returned |
| `workflow.link_pull_request` | 1 | 0 | returned |
| `workflow.prepare_contribution` | 1 | 0 | returned |
| `workflow.promote_concern` | 1 | 0 | returned |
| `workflow.promote_opportunity` | 1 | 0 | returned |
| `workflow.record_hypothesis` | 1 | 0 | returned |
| `workflow.set_concern_status` | 1 | 0 | returned |
| `workflow.start_investigation` | 1 | 0 | returned |
| `workflow.update_concern` | 1 | 0 | returned |
| `workflow.verify_published_draft` | 1 | 0 | unknown |
| `workspace.adopt` | 2 | 0 | returned, tool_error |
| `workspace.check_merge_conflicts` | 1 | 0 | returned |
| `workspace.create` | 1 | 0 | queued |
| `workspace.inspect_commit_changes` | 1 | 0 | returned |
| `workspace.plan_semantic_commits` | 1 | 0 | returned |
107 changes: 107 additions & 0 deletions docs/concurrency-ranking-audit.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
# Concurrency and ranking follow-up — 2026-09-08

## Need for jobs and SDK support

At the start of this audit, GitContribute used the latest stable official Go MCP SDK, **v1.7.0**
(released July 28). The newest prerelease checked was **v1.8.0-pre.2** (September 4).
Both the Go module registry and GitHub release metadata were checked, and both
versions' source was inspected. Neither supplies a task runtime or `TaskStore`
that can replace the application executor. Context7 had no matching task API
documentation, so this conclusion rests on the tagged source and official
release documentation, not on a missing search result alone.
[Stable release](https://github.com/modelcontextprotocol/go-sdk/releases/tag/v1.7.0),
[prerelease](https://github.com/modelcontextprotocol/go-sdk/releases/tag/v1.8.0-pre.2).

The current Tasks extension standardizes durable handles, polling, results, and
cooperative cancellation. Servers still own durable creation and execution;
clients must opt into the extension. Protocol support would replace an adapter
surface, not SQLite persistence, admission limits, or process ownership.
Retain the executor for acquisition, indexing, and validation; ordinary bounded
reads stay synchronous. No second task implementation was added. The subsequent
SDK update adopts **v1.8.0-pre.2**, including its cancellation and teardown fixes;
the task-runtime assessment above still applies.
[Tasks extension](https://modelcontextprotocol.io/extensions/tasks/overview).

## Reproduced defects and corrections

| Case | Observed before correction | Corrected behavior |
| --- | --- | --- |
| Abandoned queue | A single-slot executor had one running job and a queued job. After another corpus connection aged and reconciled its owner, the queued job remained queued forever. | Persist owner and queued row together. Reconcile queued and running jobs for missing/stale owners, while preserving live-owner work. |
| Reconciled worker | Reconciliation marked running work failed, but its callback remained active because the cancellation poll only checked cancellation timestamps and missing rows. | Terminal durable state also stops work. Missing-owner heartbeats stop the executor and further admission; terminal results cannot be overwritten. |
| Unrelated ranked evidence | An exact match, weak positive match, and disjoint title produced three findings. Competing-PR matches were automatically contradicting evidence. | Remove exact zero-score findings while preserving weak positive candidates and their order. Similarity produces inconclusive evidence, including competing PR candidates. |
| Hidden candidate cap | Among 201 threads, an older exact match fell outside the first 200 candidates. The resulting empty findings claimed complete status. | Propagate candidate truncation independently from finding count. Increasing the limit recovered the exact match; at the hard maximum, recovery does not suggest a smaller/repeated limit. |

The first three cases failed on the starting production code; the candidate-cap
case failed after zero-score filtering and before bound propagation. Focused
regressions passed after correction. Additional tests cover refusal to replace
a queued job's owner, loss of owner stopping admission, and preservation of live
owners. Existing job, cancellation, and ownership regressions were also run.

The ranking fixture is a small deterministic relevance check, not a broad
retrieval benchmark: exact and partial title overlap are retained in order,
disjoint tokens are excluded, and an older excluded match is recovered by an
explicit larger bound. Generic nearest-neighbor ranking and duplicate-v1 weights
are unchanged. The recent-first candidate cap can still miss older matches;
that limitation is now visible. An exact-sized bound conservatively reports
truncation even if there is no additional result.

## External validation

Separate standalone MCP server processes shared only the task-owned corpus.
A bounded `python3 -c "import time; time.sleep(8)"` validation command made job
states observable without running repository-controlled code. A 12-second
command timeout bounded each process. Six submissions exercised the default
four running slots plus two waiting admissions.

- A second process cancelled one running and one queued job; both reached the
cancelled terminal outcome.
- Closing the submitting server's stdin cancelled and joined the remaining
work; all six jobs were terminal and cancelled.
- A fresh submitting server was killed with four running and two queued jobs.
After the ten-second owner lease expired, a new executor reconciled all six
to failed. Work was not automatically replayed. Abrupt termination does not
prove synchronous termination of child processes; these commands were bounded.
- The preserved Cobra investigation was queried again. Its tiny positive scores
still produced candidates, with unknown source coverage and inconclusive
evidence relations. Rounded `0.00` displays did not establish exact zero.

The probe initially used the wrong job response keys; it was corrected to read
`execution_state` and terminal `outcome` before the successful lifecycle run.
Those harness errors were not product defects. All task-owned runtime artifacts
and raw logs were removed after validation as requested; regression source and
this summary remain.

## Research and remaining limits

SQLite WAL supports concurrent readers but still serializes writes. Existing
reconciliation uses `BEGIN IMMEDIATE`, so no heartbeat can interleave between
liveness inspection and the corresponding updates. These fixes use that same
transaction rather than introducing another lock/lease owner.
[SQLite isolation](https://www.sqlite.org/isolation.html).

The Go race detector checks only executed paths; deterministic lifecycle tests
and a real multi-process workload complement it. Cross-process logical races
are not established or excluded by a clean race-detector run alone.
[Go race detector](https://go.dev/doc/articles/race_detector).

A broad ranking claim requires representative queries and independently judged
relevance, with precision and recall measured over the same collection. This
follow-up does not tune weights or claim a global precision/recall improvement
from a three-document fixture. Larger judged workloads, prolonged writer stalls,
lease-expiry under heavy load, and Windows process termination remain useful
follow-ups.
[IR evaluation](https://nlp.stanford.edu/IR-book/html/htmledition/information-retrieval-system-evaluation-1.html).

## Final validation

`make verify` passed after incorporating the current base's SQLite 1.56.0
update. The focused race command below also passed on that base:

```sh
go test -race -short -p=1 -parallel=4 -count=1 -timeout 120s ./internal/app ./internal/corpus -run 'Test.*Job|Test.*Owner|Test.*Reconcil|TestRelatedWork|TestDuplicateAndCollision'
```

The external workload preceded the dependency update. Final tests cover the
updated dependency, but the external multi-process probe was not repeated after
its task-owned runtime was removed. These audit runs preceded the subsequent
Go MCP SDK update to v1.8.0-pre.2.
Loading
Loading