Skip to content

docs: self-run setup guide — attested reports from a personal repo, no org needed #56

Description

@gkanitz

Context

Launch-readiness item (pulled forward from the v0.3 sketch; spec:
docs/superpowers/specs/2026-07-04-impact-roadmap-design.md, PR #47,
Multi-source composition section). For public validation, strangers must be
able to try CodeRepute without asking their employer. The pipeline
already supports this — the canonical workflow runs in any repo — but no
documentation walks an individual developer through it.

Goal

docs/setup/self-run.md: a complete guide for running the pinned canonical
workflow in a personal repo over the developer's own private + public
repositories with their own fine-grained PAT — producing a fully attested
report with no org involvement.

In scope

  • The 5-minute local trial first: coderepute -repo ... -subject ... with
    a PAT — full report, explicit unverified status. Frame it as the
    try-before-CI path.
  • The attested self-run: personal repo, workflow yaml pinned to the
    canonical reusable workflow at a tagged version, permissions block
    (id-token: write, attestations: write, read perms), fine-grained PAT
    with least-privilege read-only scopes (state them precisely, following
    docs/setup/github.md conventions).
  • Coverage guidance: own private repos, own public repos, and public OSS
    repos the subject contributed to but does not own (public data — the
    token is only for rate limits).
  • Honesty section (required): what a self-run proves vs an org run —
    the Sigstore certificate still proves the unmodified canonical workflow
    produced the numbers from the platform API; the coverage stamp still
    records token_scope_class; what it does not carry is org endorsement.
    Include the verification-policy note: readers may additionally require
    runner_environment == github-hosted (self-hosted runners could be
    tampered with).
  • Link the guide from README and the docs landing page.

Out of scope

  • Any code changes. GitLab self-run (follow-up when someone asks).
  • The career merge itself (v0.3).

Acceptance criteria

Success

  1. Every workflow snippet cross-checked against action.yml and the
    canonical reusable workflow: input names, permission blocks, and pinned
    version tags all exist and are current.
  2. PAT instructions name the exact fine-grained scopes and nothing broader.
  3. The honesty section exists and draws the self-run vs org-run distinction
    explicitly, including the runner_environment note.
  4. Local-trial section produces a report with "status": "unverified" and
    says so.
  5. README and docs/index.html link the guide.
  6. All example workflow refs are pinned to a tag — no @main anywhere.

Failure — QA red flags (any one observed → reject the PR)

  • Any suggestion that a self-run report is org-endorsed or equivalent to an
    org run.
  • Over-broad PAT scopes, or classic-PAT instructions where fine-grained
    works.
  • Unpinned (@main) workflow references in examples.
  • Org-token setup steps copy-pasted into the personal-repo context.

Parallel-work contract

  • Territory: docs/setup/self-run.md (new), README + docs/index.html
    (additive link edits).
  • Depends on: nothing — start immediately.

Definition of done

Criteria green; docs build/render fine on GitHub; PR references this issue.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationreadyLoop-ready: this org's picker reads this labelready-for-agentTriage complete; ready for an agent to pick up

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions