# Step 1 validation evidence: GitHub SCM connector

## Intent established

Step 1 is the source-specific implementation of the Step 0 connector contract. It is deliberately scoped to GitHub repositories and paths, supports Markdown/plain-text/source files, and has three invocation paths: full synchronization, cursor-based incremental synchronization, and webhook-triggered synchronization. Its observable output is a KAB-compatible normalized document, not a raw GitHub API response.

## Artifact map

| Requirement | Inspectable artifact | Evidence to inspect |
|---|---|---|
| Contract adapter | `src/connectors/github.py` | Connector input/output types and normalized-document construction |
| Repository and path scope | `src/connectors/github.py` | Repository identity, include/exclude globs, and supported-extension filtering |
| Authenticated retrieval | `src/connectors/github.py` | Managed-secret token injection and authenticated GitHub API requests |
| Full and incremental sync | `src/connectors/github.py` | Full tree traversal and revision/cursor-based changed-file traversal |
| Webhook and revision metadata | `src/connectors/github.py` | Push-event SHA/ref parsing, signature verification, and source revision provenance |
| Regression evidence | `tests/test_github_connector.py` | Focused tests for scope, file types, pagination, cursor updates, signatures, and idempotency |
| Deterministic inputs | `tests/fixtures/github/` | API payload and webhook fixtures used by the focused tests |

## Platform-compliance checks

- GitHub REST requests are authenticated and paginated; credentials are configuration references rather than document content.
- A webhook is accepted only after HMAC-SHA256 verification with the configured secret.
- Repository/path filters are applied before publication, so an event cannot widen a configured scope.
- Revision SHA, source URL, fetched timestamp, and connector identity are retained as provenance.
- The synchronization cursor is advanced only from the completed source revision, allowing retry-safe incremental runs.
- Unsupported binary formats are excluded; Markdown, text, and configured source extensions are normalized into the shared document shape.
- Tenant and source ACL fields are copied into every emitted document; no cross-tenant fallback is permitted.

## Verification evidence

The focused verification was executed against the Step 1 artifact boundary with:

```text
python -m pytest tests/test_github_connector.py -q
python -m compileall src/connectors/github.py
```

The verification boundary is intentionally narrow: it checks the connector and its fixtures without regenerating or changing Steps 0, 2, 3, 4, 5, or 6. The generation result records the same commands and the contract/platform assertions above so the step has a step-specific, inspectable result rather than relying on a cluster-level result.