# Builder evidence contract Shared identity, GitHub, classification, and degradation rules for `war-room-prep`, `cse-profile-builder`, and `cse-bandwidth`. Skills keep their own scoring, attribution windows, and output shape; they do not fork this truth layer. ## Identity and roster 1. Resolve the live CSE roster with `cse_orgchart_identity_snapshot` before attributing any build work. 2. Attribute a CSE only when a commit author email exactly matches a live-roster work email. Display-name guesses and manufactured `firstname.lastname@postman.com` addresses are not attribution. 3. After an exact email match, retain the verified GitHub login for PR attribution on that person. 4. Unmatched personal-email commits are history notes or evidence gaps, not CSE-attributed build evidence. Identity mismatches are excluded from attribution and listed in gaps when material. ## Per-CSE context fan-out - Call `context_assemble` once for every live-roster CSE. Process those calls with concurrency capped at 8, in bounded batches or a queue, until every roster member is covered. ## GitHub transport (`postman-cs`) - Use direct authenticated `gh` against `postman-cs`. There is no GitHub MCP capability. - Preflight: `command -v gh`, `gh auth status`, and one bounded org access probe (for example a single-page repo list). - Enumerate the complete org repository list once with full pagination (`gh api --paginate 'orgs/postman-cs/repos?per_page=100&sort=pushed&direction=desc'` or equivalent). If any page fails, mark GitHub partial and do not claim complete coverage. - Filter to repos pushed inside the lookback window, plus repos named by per-CSE context or operator input, before per-repo fan-out. - Pull default-branch commits and merged/open/draft PRs per selected repo. Attribute per repo via `repos/postman-cs//commits?author=&since=` (and PR list endpoints as needed). Cap concurrent per-repo reads (war room: 8; bandwidth may throttle higher for count sweeps, still abort on a failed page). - Do not clone repositories. - Never trust org-wide `gh search commits --author` (or equivalent org-wide commit search). It can ignore the author qualifier and return org-wide volume. - Bound README/description reads; do not bulk-clone or scrape every file. ## Window and non-GitHub artifacts - Default lookback: 14 days. Accept an operator override from 7 to 30 days unless the calling skill documents a different profile window. - Missing GitHub evidence is unknown, not proof that no work happened. - Concrete non-GitHub artifacts count when directly evidenced: Postman workspaces, collections, templates, demos, dashboards, docs, scripts, deployment assets, and similar deliverables with an owner and recent source. - Communication-only mentions without a code or deliverable proof are `mentioned_only`, not `shipped` or `in_flight`. ## Scope | Scope | Meaning | | --- | --- | | `customer` | Built for a named customer or customer engagement | | `internal` / shared | CSE-maintained internal repos, shared tooling, enablement | Do not infer customer, owner, purpose, or outcome from repo naming alone. Repo name patterns (`Cust-*`, `Internal-*`, demo fleets) are signals to investigate, not field fills. ## State classification | State | Required evidence | | --- | --- | | `shipped` | Merged PR, exact default-branch commit, or versioned/published artifact with a direct delivery receipt inside the window | | `in_flight` | Open/draft PR updated inside the window, or another concrete artifact with a current owner and recent source | | `mentioned_only` | Slack/call/Granola says work is active but no code or deliverable proof was found | A merge proves code landed. It does not prove a customer deployed it, used it, or got value from it. ## Dedupe and grouping - Canonical key: `repo#PR` when a PR exists; otherwise `repo@sha` (or an equivalent stable artifact id for non-GitHub deliverables). - Collapse commits already represented by a PR into that PR workstream. - Group records only when repo, audience/customer, and goal all match; preserve every source link. - An umbrella or composite artifact never absorbs the repositories it coordinates. When one release, composite action, or meta PR spans several repos, expand it into one canonical record per changed repo before any grouping. Grouping coordinated records for presentation is allowed; deduping them into the umbrella is not. ## Workstream questions, purpose taxonomy, and unknowns Keep these fields distinct on every selected workstream: - what was built or changed - why it was built and the customer/team problem it solves - purpose classification: `operational improvement`, `customer-facing capability`, `customer-specific implementation`, or `internal/shared tool` - practical use guidance: who should use it, how, and when/why it is useful - outcome/adoption evidence, or `unknown` - what changes because of it: `pitches`, `execution model`, and/or `day-to-day operating model`, each backed by evidence or `unknown` - next step, demo, decision, or unblock Keep customer scope separate from purpose classification. `customer-facing capability` and `customer-specific implementation` are customer-scoped only when the evidence says so; `operational improvement` and `internal/shared tool` may serve either scope. Do not infer any classification from a repo name. Never label work "adopted" because it merged or a Jira ticket closed. Unknown fields, including use guidance and pitch/execution/operating-model impact, stay visible. Do not fill them from plausible names, generic CSE context, or a generic link. ## Evidence strength - Strong: concrete artifact plus direct customer outcome, usage metric, decision, or practical use/operating impact evidence. - Moderate: concrete artifact plus PR/README rationale, purpose, use guidance, or an explicitly linked ticket. - Weak: concrete artifact with no verified rationale, use guidance, or outcome, or a communication-only mention. ## Degradation - GitHub unavailable: produce a visibly `PARTIAL -- GitHub unavailable` result, retain directly evidenced non-GitHub artifacts and `mentioned_only` items, and make no GitHub-backed completeness claim. - Kepler or Granola unavailable: keep code-state facts, mark why/use/impact/outcome coverage partial, and do not infer adoption. - Jira unavailable: keep builder evidence; explicit ticket correlation stays unknown. - Identity mismatch: exclude from CSE attribution; list in evidence gaps when material. ## Jira correlation (war-room only) War-room Jira use is optional and bounded: at most one lookup per ambiguous workstream, and only for an explicit issue key or account found in artifact evidence. Unlinked artifacts stay unlinked. Never enumerate `all_open`, `stalled`, or any full board query from builder evidence gathering.