PRD: CodeRepute v1 — verifiable private-repo collaboration reports

[gkanitz]

Problem Statement

Developers who do most of their work in private repositories have no credible way to demonstrate their skills and collaboration habits to the outside world. Their GitHub/GitLab profiles look empty, so recruiters and hiring managers — who routinely use public contribution graphs as a screening signal — undervalue them. Existing options are bad: a CV line is unverifiable, granting an external party access to the employer's codebase is impossible, and manually curated portfolios can't show day-to-day collaboration quality (reviews given, PRs shepherded to merge, responsiveness).

Solution

CodeRepute is an open-source tool that runs inside the employer's own CI (GitHub Actions, GitLab CI), reads only API metadata — never source code — and produces a cryptographically attested report of one developer's collaboration statistics across the org's repositories. The developer shares a self-contained HTML report with recruiters; a static verify page lets anyone confirm, via the platform's public attestation APIs, that the report was produced by the canonical CodeRepute workflow inside the named org and was not fabricated or tampered with. The employer keeps full control: they install the integration with org-owned credentials, no external party ever receives repository access, and the report contains only aggregates about the subject — nothing about colleagues, code, or content.

User Stories

1. As a private-repo developer, I want an attested report of my collaboration statistics, so that recruiters can evaluate me despite my empty public profile.
2. As a private-repo developer, I want the report bound to my platform account ID rather than my git email, so that nobody can fabricate activity under my name or present my activity as theirs.
3. As a private-repo developer, I want the report to cover all repositories in my org that the token can see, so that my work isn't fragmented into misleading per-repo confetti.
4. As a private-repo developer, I want the report rendered as a polished, self-contained HTML file, so that I can attach it to applications or host it anywhere without depending on a third-party service.
5. As a private-repo developer, I want a narrative front page with trends and plain-language framing, so that non-technical recruiters understand my numbers without a glossary.
6. As a private-repo developer, I want a technical annex with the hard numbers (counts, rates, distributions, coverage metadata), so that technical reviewers can dig into the details.
7. As a private-repo developer, I want the same tool to work on GitHub and GitLab without recoding, so that changing employers or platforms doesn't strand my reporting setup.
8. As a private-repo developer, I want to generate reports periodically while employed, so that I have attested evidence even after I leave and can no longer run the tool there.
9. As a private-repo developer, I want the report to clearly state its coverage (repo list, time window, token scope), so that my honesty is visible and recruiters can trust I'm not cherry-picking.
10. As a private-repo developer, I want volume and cadence shown only as context, never as headline numbers, so that my report isn't reduced to gameable vanity metrics.
11. As a recruiter, I want a one-page narrative summary of a candidate's collaboration record, so that I can screen them as quickly as I'd skim a GitHub profile.
12. As a recruiter, I want to verify a report by dropping its JSON into a static web page, so that I can confirm authenticity without installing a CLI or understanding cryptography.
13. As a recruiter, I want the verify page to tell me exactly what is proven (produced by the canonical workflow, in the named org, for the named account) and what is not, so that I don't over- or under-trust the document.
14. As a recruiter, I want each metric accompanied by an honest explanation of what it indicates and its limits, so that I interpret the data correctly.
15. As a hiring manager, I want to see review activity (reviews given, review comments, time-to-first-review), so that I can gauge whether the candidate is a good colleague, not just a good committer.
16. As a hiring manager, I want to see PR outcomes (authored, merged, share needing rework, time-to-merge), so that I can gauge the candidate's delivery quality and autonomy.
17. As a hiring manager, I want the report to show the subject's own trajectory over time, so that I can see growth rather than a single snapshot.
18. As an org admin, I want to enable CodeRepute by installing a marketplace-listed integration with credentials owned by my org, so that approval is a routine integration review rather than a bespoke security exception.
19. As an org admin, I want a one-click GitHub App manifest flow that creates the app inside my own org, so that no private key or token ever leaves my organization.
20. As an org admin (GitLab), I want the integration to run with a group access token with read-only API scope, so that setup follows our existing token policies.
21. As an org admin, I want a guarantee that the tool reads only API metadata and never clones or reads file contents, so that source code confidentiality is structurally protected, not policy-protected.
22. As an org admin, I want reports to contain only aggregates about the requesting subject — no colleague usernames, PR/issue titles, branch names, or code — so that approving one employee's report doesn't leak data about others or about our product.
23. As an org admin, I want no within-team comparisons or rankings in any report, so that the tool can't be repurposed as a surveillance or stack-ranking instrument.
24. As an org admin, I want a concise employer-facing one-pager explaining what the tool accesses, emits, and proves, so that I can route approval through security review without writing the analysis myself.
25. As an org admin, I want the workflow pinned to a published, versioned release of the canonical action/component, so that what runs in my CI is exactly what was audited.
26. As a verifier (anyone), I want the attestation to identify the exact workflow and version that produced the report, so that a modified fork of the tool cannot produce a report that passes verification.
27. As a developer on a platform without attestation support (future Bitbucket/Azure DevOps), I want the report to carry an explicit verification block stating it is unverified, so that degradation is honest rather than silent.
28. As an open-source contributor, I want a provider-neutral core with a clear Provider interface, so that I can add a new platform adapter without touching metrics, schema, or rendering.
29. As an open-source contributor, I want the report schema versioned, so that renderers and verify pages can evolve without breaking previously issued reports.
30. As a job-seeking developer, I want reports from multiple employers to be individually attested and shareable side by side, so that my career story accumulates even before cross-org composition exists.

Implementation Decisions

• Language and shape: Go core CLI (single static binary) orchestrating a pipeline: fetch → normalize → compute → build → render. Thin per-platform CI wrappers (GitHub composite Action, GitLab CI/CD component) invoke the binary and handle attestation.
• Modules:
  • provider — port interface (fetch the subject's activity for a scope and time window, returning a provider-neutral ActivitySet) with github and gitlab adapters. Adapters encapsulate pagination, REST/GraphQL differences, rate limiting, and identity binding via immutable platform account IDs. Both adapters ship in v1 to keep the abstraction honest.
  • metrics — pure, deterministic transformation of an ActivitySet into collaboration metrics (PRs/MRs authored and merged, reviews given, review comments written/received, time-to-merge, time-to-first-review, rework share) plus volume/cadence context (active days, contribution counts, time-bucketed trends). No I/O.
  • report — canonical, versioned, provider-neutral JSON schema and builder. Every report carries: subject identity (platform, username, immutable account ID), coverage stamp (covered repo list, time window, token scope), and a verification block describing how (or whether) the report is attested.
  • render — pure transform from report JSON to a self-contained HTML document: narrative front page (trends, plain-language framing with honest limits per metric) and technical annex (hard numbers, distributions, coverage metadata).
  • verify — static, backend-free verify page (hostable on GitHub Pages) where a consumer drops report JSON and sees verification status fetched from the platform's public attestation APIs; plus the attestation steps in the CI wrappers.
  • cmd/coderepute — thin CLI wiring (provider selection, token/env handling, subject, window, output paths).
• Trust chain: CI provenance attestation (Sigstore/OIDC on GitHub via artifact attestation; GitLab's SLSA-style equivalent). Verification checks workflow identity against the canonical published version, not merely signature validity. Authorship is resolved through authenticated platform accounts, never raw git author emails.
• Graceful degradation: attestation is a per-provider capability. The verification block is mandatory in the schema; the verify page reports "cryptographically verified" or "unverifiable on this platform" explicitly.
• Data boundary: API metadata only — the tool never clones repositories or reads file contents. Output contains subject-only aggregates plus the org name. Prohibited in any output: colleague usernames, PR/issue titles, branch names, code, within-team comparisons. These are schema-level guarantees with safe defaults, not configuration options.
• Scope: one report = one org (all repos visible to the org-owned token), stamped with coverage to make omissions visible. Reports must be generated while the subject has access; "attest as you go" is the usage model.
• Interpretation: subject-own trends plus prose annotations only. No percentile benchmarks (requires central telemetry), no composite score (Goodhart target), no central data collection of any kind.
• Distribution: GitHub Marketplace listing for the Action; GitLab CI/CD Catalog for the component. Credentials are always org-owned (GitHub App created in the customer org via the app-manifest flow; GitLab group access token with read API scope). No hosted multi-tenant service; the project never holds customer credentials.
• License: Apache-2.0.

Testing Decisions

• Tests assert external behavior only — given inputs, observable outputs — never internal call sequences or private state. The pipeline architecture makes this natural: every core module is a transformation with data in, data out.
• metrics: table-driven unit tests over hand-built ActivitySets, including edge cases (empty windows, single-PR subjects, unmerged-only activity, timezone/bucket boundaries).
• provider adapters: tests against recorded HTTP fixtures (httptest serving canned GitHub/GitLab API responses). Include cross-adapter parity tests: equivalent activity on both platforms must normalize to equivalent ActivitySets — this protects the abstraction that dual-adapter v1 exists to keep honest.
• report: build → marshal → validate → unmarshal round-trips; validation must reject reports missing the coverage stamp or verification block; schema-version compatibility checks.
• render: golden-file tests (fixed report JSON in, committed HTML out), including negative assertions that prohibited data classes (colleague usernames, titles seeded into fixtures) never appear in rendered output — rendering is a privacy boundary.
• Prior art: none — this is a greenfield repository. Follow standard Go conventions: table-driven tests, testdata/ directories for fixtures and golden files, httptest for API doubles.

Out of Scope

• Static-analysis "code quality" scores — team-confounded and noisy; explicitly rejected, not deferred.
• Code survivability / ownership metrics — strong signal but complex; planned v2.
• Bitbucket and Azure DevOps adapters — later, initially data-only (no attestation equivalent exists there today).
• Hosted services of any kind — profile pages, multi-tenant app, central verification backend, telemetry.
• Percentile benchmarks and composite scores.
• Career-wide composition across orgs/employers — an attestation-aggregation problem deferred to v3.
• Profile badges / README widgets — possible later complement to the report, not part of v1.
• Within-team comparisons or any output about people other than the subject.
• Local/offline attested runs — attestation only exists in CI; a local dry-run mode may exist for development but produces explicitly unverified output.

Further Notes

• The project's hardest problem is not technical: it is org-admin approval. The employer-facing one-pager (what the tool accesses, what leaves the repo, what is proven) is a first-class v1 deliverable alongside the code.
• The strongest line in the employer pitch is structural: the tool never reads source code — everything comes from API metadata.
• Candor is a feature: plainly stating each metric's limits, and plainly stating when a report is unverifiable, is what differentiates this from vanity dashboards and builds recruiter trust.
• Name/repo: CodeRepute (grkanitz/CodeRepute).

🤖 Generated with Claude Code