Skip to content

Scratch-repo harness, runbook, and acceptance record #133

Description

@sameera

As a Nexus maintainer, I want one command to provision a throwaway hosted repo seeded with
everything the --pr flow needs and one to tear it down, so that I can run the live acceptance
check on demand without hand-assembling GitHub state each time.

Acceptance Criteria

  • Given an authenticated gh with repo create/delete scope, when the maintainer runs
    the harness provision command, then a scratch repo exists on the same owner carrying a
    trunk commit and the Nexus surfaces the flow reads (.nexus/config/, a docs root, one
    feature folder).
  • Given a provisioned scratch repo, when the maintainer seeds a scenario, then the
    repo has an epic issue with at least two story sub-issues, plus a feature branch carrying a
    multi-commit non-empty diff and an open PR from that branch.
  • Given a scratch repo already provisioned, when provision is run again, then it
    either reuses that repo or exits non-zero naming the existing repo — it never leaves two
    scratch repos behind.
  • Given a finished run, when the maintainer runs teardown, then the scratch repo is
    deleted and git worktree list plus git branch --list in the host checkout show no
    harness-created entries.
  • Given any harness command, when it runs, then it makes no commit, push, or issue
    against the Nexus repo itself — all live state lands on the scratch repo.
  • Given a run the maintainer wants to debug, when teardown is invoked with the
    keep-alive flag, then the scratch repo survives and its URL is printed, while local
    worktrees are still removed.
  • Given a maintainer who has not used the harness before, when they follow only the
    checked-in runbook, then they complete a provision → seed → teardown cycle in one
    sitting under 15 minutes.
  • Given the harness is in place, when the acceptance record is created at
    docs/features/pr-driven-delivery/live-acceptance-record.md, then it carries the
    per-stage and per-merge-strategy result slots that later stories fill in, plus the scratch
    repo URL and the libs/pr-worktree commit SHA the run was made against.

Notes

The runbook is the durable artifact; the scripts are its executable half. Both live under
docs/features/pr-driven-delivery/.

This story creates the acceptance record with empty result slots; the three exercise stories
fill it in. It is the one artifact all of them write to, so it is defined once here rather than
invented by whichever story lands first.

Foundational — the other three stories in this epic all consume this harness.

Metadata

Metadata

Assignees

No one assigned

    Labels

    infrastructureBuild tooling, Nx/Vite/pnpm config, dev environment, CI/CDstoryUser story (created by nxs-gh-create-story)testingVitest unit/component tests and Playwright e2e

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions