docs: clarify agent-facing product contract

Author: morluto

AGENTS.md

@@ -1,5 +1,20 @@
 # Repository working agreements
 
+## What we are building
+
+GitContribute is a local-first research and validation workbench for coding
+agents. It gives agents durable repository and GitHub facts, bounded acquisition
+and workspace capabilities, and source-bound validation evidence. Agents do the
+reasoning and contribution work; GitContribute provides the trustworthy local
+context and explicit capabilities they need. It does not hide network access,
+process execution, local writes, or GitHub mutation inside reads.
+
+Treat missing, stale, incomplete, or superseded coverage as unknown rather than
+as negative evidence. Keep imported external claims distinct from validation
+reproduced by GitContribute. For the detailed contracts, read
+`docs/architecture.md`, `CONTRIBUTING.md`, and, for MCP or evidence changes,
+`docs/mcp-composed-workflows.md` and `docs/external-evidence-manifests.md`.
+
 ## Product boundaries
 
 - Follow the contracts in `docs/architecture.md`; do not preserve Gitcrawl
@@ -20,14 +35,15 @@
 - No GitHub mutation is in scope unless explicitly approved.
 - Never execute repository-controlled code during crawling or indexing.
 
-## Go changes
+## Engineering rules
 
 - Keep packages focused and interfaces narrow; avoid config bags and mode
   booleans.
 - Pass `context.Context` through I/O and long-running operations.
-- Make crawl writes idempotent and prevent stale observations from replacing
-  newer projections.
+- Make acquisition, sync, indexing, and projection writes idempotent; prevent
+  stale observations from replacing newer projections.
 - Replace child snapshots atomically only after complete retrieval.
-- Run `gofmt` on changed Go files and `go test ./...` before committing.
+- Run `gofmt` on changed Go files and focused tests while working; run
+  `make verify` before opening a pull request.
 - Add focused regression tests for ordering, resumability, cancellation, and
   side-effect boundaries.