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
- 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.
- PAT instructions name the exact fine-grained scopes and nothing broader.
- The honesty section exists and draws the self-run vs org-run distinction
explicitly, including the runner_environment note.
- Local-trial section produces a report with
"status": "unverified" and
says so.
- README and
docs/index.html link the guide.
- 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.
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 canonicalworkflow 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
coderepute -repo ... -subject ...witha PAT — full report, explicit
unverifiedstatus. Frame it as thetry-before-CI path.
canonical reusable workflow at a tagged version,
permissionsblock(
id-token: write,attestations: write, read perms), fine-grained PATwith least-privilege read-only scopes (state them precisely, following
docs/setup/github.mdconventions).repos the subject contributed to but does not own (public data — the
token is only for rate limits).
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 betampered with).
Out of scope
Acceptance criteria
Success
action.ymland thecanonical reusable workflow: input names, permission blocks, and pinned
version tags all exist and are current.
explicitly, including the
runner_environmentnote."status": "unverified"andsays so.
docs/index.htmllink the guide.@mainanywhere.Failure — QA red flags (any one observed → reject the PR)
org run.
works.
@main) workflow references in examples.Parallel-work contract
docs/setup/self-run.md(new), README +docs/index.html(additive link edits).
Definition of done
Criteria green; docs build/render fine on GitHub; PR references this issue.