Found by standing Blog up against STANDUP.md (context in #456). Audited against hub main @ 1d5b076.
What happened
Blog now has 24 signed commits, the full carried instruction set, the baseline files, a working build, a proven URL gate, and a site serving live on a local host. By any local measure onboarding looks well advanced.
The GitHub repository does not exist.
$ gh repo view ptr727/Blog
GraphQL: Could not resolve to a Repository with the name 'ptr727/Blog'. (repository)
$ git remote -v
(no output)
Steps 0 through 2 completed in full. Step 4 was never reachable. Nothing in the procedure surfaced that, and the maintainer found it by asking rather than by any check reporting it.
Why the procedure allows this
1. No step creates the repository. The steps are 0, 1, 1A, 2, 3, 4, 5. Step 0 governs signing before the first commit, which implies a local git init. Step 4 applies settings, rulesets, and secrets over the GitHub API, which presumes a remote. Nothing between them creates it, says who creates it, or says a remote is required from that point on.
2. Human-gated prerequisites are never enumerated. Several onboarding inputs cannot come from the agent at all:
- creating the repository, which is an outward-facing write needing explicit per-session permission
- installing the GitHub App, since
spec/secrets.json notes the App must be installed rather than only created
- the values of
CODEGEN_APP_CLIENT_ID and CODEGEN_APP_PRIVATE_KEY, in both the Actions and Dependabot stores
- creating the
staging and production Environments and their deploy credentials
STANDUP.md names the maintainer three times: repairing a force-push, fixing a host misconfiguration, and merging a convergence PR. It never names them for any of the above. There is no list to hand a maintainer at the start saying "these are yours, the rest is mine".
3. Nothing fails early. Every local step succeeds with no remote, and each one reports progress. The one tool that would catch it is spec/audit.py, which audits cataloged repos live, so it cannot run for a repo that is neither in the registry nor on GitHub. The check that would detect the problem is unavailable exactly when the problem exists.
This also makes the "definition of done is the audit" obligation in the hub-only Repository Onboarding and Conformance section unreachable rather than merely unmet, and nothing says so.
4. The agent's own tracking hides it. Worth stating plainly, because the fix should not assume a better-behaved agent. The agent knew the repository did not exist, checked it at the start, and carried "create the GitHub repo" as a pending task for the whole session while completing work that depended on it. A pending task and a blocking prerequisite look identical in a task list. The procedure never forces the second to be escalated, so it silently became the first.
Suggested fix
Add a prerequisites step before step 1, listing what the maintainer must do and what the agent may not, so it can be handed over as a checklist at the start rather than discovered at step 4. Repository creation belongs there explicitly, with a note that it is an outward-facing write requiring per-session permission.
Make step 4 assert the remote first. A one-line gh repo view <owner>/<repo> at the top of the step turns a silent stall into an immediate, specific failure.
Say that a repo with no remote is not partially stood up, it is not started. The existing rule against leaving a repo "partially set up and unrecorded" reads as covering this, but every local step passing makes it feel recorded and in progress.
Related ordering trap, worth stating in step 4
The main ruleset requires a check named Check pull request workflow status job, and repo-config/README.md notes it turns green only after the repo's PR workflow has run once. Applying the rulesets before that workflow exists and has run once therefore deadlocks the first pull request: the required check is never reported, and merging is blocked. On an operational repo the develop -> main promotion is still a PR, so this bites there too.
The fact is currently in repo-config/README.md rather than in the step that needs it. Step 4 is where an agent decides when to apply the rulesets, so the ordering constraint belongs there: stand up the workflows, push, let the PR workflow run once, then apply.
Found by standing Blog up against
STANDUP.md(context in #456). Audited against hubmain@1d5b076.What happened
Blog now has 24 signed commits, the full carried instruction set, the baseline files, a working build, a proven URL gate, and a site serving live on a local host. By any local measure onboarding looks well advanced.
The GitHub repository does not exist.
Steps 0 through 2 completed in full. Step 4 was never reachable. Nothing in the procedure surfaced that, and the maintainer found it by asking rather than by any check reporting it.
Why the procedure allows this
1. No step creates the repository. The steps are 0, 1, 1A, 2, 3, 4, 5. Step 0 governs signing before the first commit, which implies a local
git init. Step 4 applies settings, rulesets, and secrets over the GitHub API, which presumes a remote. Nothing between them creates it, says who creates it, or says a remote is required from that point on.2. Human-gated prerequisites are never enumerated. Several onboarding inputs cannot come from the agent at all:
spec/secrets.jsonnotes the App must be installed rather than only createdCODEGEN_APP_CLIENT_IDandCODEGEN_APP_PRIVATE_KEY, in both the Actions and Dependabot storesstagingandproductionEnvironments and their deploy credentialsSTANDUP.mdnames the maintainer three times: repairing a force-push, fixing a host misconfiguration, and merging a convergence PR. It never names them for any of the above. There is no list to hand a maintainer at the start saying "these are yours, the rest is mine".3. Nothing fails early. Every local step succeeds with no remote, and each one reports progress. The one tool that would catch it is
spec/audit.py, which audits cataloged repos live, so it cannot run for a repo that is neither in the registry nor on GitHub. The check that would detect the problem is unavailable exactly when the problem exists.This also makes the "definition of done is the audit" obligation in the hub-only
Repository Onboarding and Conformancesection unreachable rather than merely unmet, and nothing says so.4. The agent's own tracking hides it. Worth stating plainly, because the fix should not assume a better-behaved agent. The agent knew the repository did not exist, checked it at the start, and carried "create the GitHub repo" as a pending task for the whole session while completing work that depended on it. A pending task and a blocking prerequisite look identical in a task list. The procedure never forces the second to be escalated, so it silently became the first.
Suggested fix
Add a prerequisites step before step 1, listing what the maintainer must do and what the agent may not, so it can be handed over as a checklist at the start rather than discovered at step 4. Repository creation belongs there explicitly, with a note that it is an outward-facing write requiring per-session permission.
Make step 4 assert the remote first. A one-line
gh repo view <owner>/<repo>at the top of the step turns a silent stall into an immediate, specific failure.Say that a repo with no remote is not partially stood up, it is not started. The existing rule against leaving a repo "partially set up and unrecorded" reads as covering this, but every local step passing makes it feel recorded and in progress.
Related ordering trap, worth stating in step 4
The
mainruleset requires a check namedCheck pull request workflow status job, andrepo-config/README.mdnotes it turns green only after the repo's PR workflow has run once. Applying the rulesets before that workflow exists and has run once therefore deadlocks the first pull request: the required check is never reported, and merging is blocked. On an operational repo thedevelop -> mainpromotion is still a PR, so this bites there too.The fact is currently in
repo-config/README.mdrather than in the step that needs it. Step 4 is where an agent decides when to apply the rulesets, so the ordering constraint belongs there: stand up the workflows, push, let the PR workflow run once, then apply.