Four Procedure and Layout Defects in Carried Text That Need a Decision, Not a Reword

[ptr727]

Found by the canonical-content review pass on the PR for #1075/#1120/#1114/#1119/#1129/#1078. The path-qualification defects that pass found are fixed there; these four need a decision about what the text should say, so they are filed instead.

1. repo-worktree forbids in one unit the command it requires in another

The Base Branch says of the base clone:

outside "Listing and Cleanup"'s own terminal step below, nothing else does: never checkout, pull, reset, commit, or any other command that mutates its own working tree, index, or HEAD while a task is in progress.

Creating a Worktree says, of a continuation whose branch is already checked out somewhere:

Return that checkout to its own working branch first when its tree is clean, and stop when it is not, because a dirty tree there may be another task's uncommitted work.

When the "somewhere" is the base clone, which is the case the mandate exists for, the two units give opposite instructions and neither states an exception. The reader either stalls or performs the base-clone checkout the first sentence forbids.

Mechanically the switch is already permitted: gh-write-guard.py exempts checkout <ref>/switch <ref> carrying no force flag, and The Base Branch names that exemption. So only the prose conflicts, and prose is the only layer that binds a non-Claude-Code agent. What it needs is one sentence saying which unit wins.

2. resync-a-repo omits the --branch flag its own cited procedure requires

The skill says:

Then run the audit end to end, RESYNC.md section 2, against the target's main branch, never develop. A finding is a snapshot, so quote the run stamp in anything derived from it and re-run before acting on a finding read earlier in the session.

RESYNC.md section 2 documents python3 spec/audit.py --branch <ref> <Repo> as "the supported way to read something else, and a resync is when it earns its place", because convergence lands on a feature branch and reaches main only after the maintainer merges. The skill names no flag.

Following both sentences literally fails mid-resync: a reader re-running the audit after applying fixes measures main, sees every finding their in-flight branch already fixed, and cannot tell converged work from outstanding work.

3. GOVERNANCE.md "Repository Layout" mis-describes two entries and omits two trees

The hub-only trees now carry their qualifier, but three content problems remain.

.github/workflows/ is described as:

this repo's own lint-only CI and source-only release, the workflow contract it dogfoods.

The directory also holds the fleet's reusable task workflows every downstream repo calls (build-release-task.yml, validate-task.yml, deploy-site-task.yml among others), which this does not account for. In a carrier the same line asserts that repo's CI is lint-only and its release source-only, which is wrong for every csharp, python, docker and hugo repo in the fleet.

docs/ is described as holding "hub-only procedure and measurement docs", but STANDUP.md and RESYNC.md are hub-only procedure docs sitting at the repository root, and neither appears in the layout at all. A reader asking where the STANDUP.md that AGENTS.md "Fleet Bootstrap" routes them to lives is sent to docs/ and finds it is not there.

The section is the fleet's answer to "where a file belongs in the tree" and omits .agents/ and host-setup/, both cited by path from other canonical units. The omission is invisible because the list otherwise reads as complete.

4. Nothing lints .github/actions/**/action.yml

workflow-ci-contract "After Any Workflow Edit" tells the reader to run actionlint locally before pushing. That check covers only .github/workflows/*.yml|yaml: scripts/docker_lint.py's actionlint entry declares exactly those two patterns, and the raven-actions/actionlint step in .github/workflows/validate-task.yml passes no file list, so it uses the same default.

The hub holds nine composite actions under .github/actions/, and the same skill's "Reached, not carried" bullet makes them part of the workflow surface. A reader edits a composite action's action.yml, runs the prescribed check, gets a clean result that read zero of their changed files, and pushes a malformed action that surfaces only when a publish run executes it.

This is a gate gap rather than a wording one, which is why it is filed rather than patched: whether docker_lint.py and the CI step widen their patterns is a tooling decision.

Not This Issue

• #1152 covers WORKFLOW.md section 4's contract claims.
• #1153 covers CODESTYLE.md's language coverage.
• #1154 covers the commit-subject length rule.

[ptr727]

5. The C# "authoritative gate" never compiles, so TreatWarningsAsErrors is not exercised

dotnet-codestyle "Build requirements" says:

CI lint backstop. CI runs the clean-compile checks on every PR as the authoritative gate.

The same unit defines the clean-compile as CSharpier Format -> .NET Build -> dotnet format style --verify-no-changes. .github/workflows/validate-task.yml's C# steps are only two:

        if: hashFiles('**/*.csproj') != '' && hashFiles('.config/dotnet-tools.json') != ''
        run: dotnet csharpier check .
...
        if: hashFiles('**/*.csproj') != ''
        run: dotnet format style --verify-no-changes --severity=info --verbosity=detailed

There is no build step. The only compile anywhere in that workflow is dotnet test in the unit-test job, gated on hashFiles('**/*Tests*.csproj') != '' (line 281).

So a .NET repo with no test project never compiles in the validator, and a PR introducing an analyzer warning passes the gate green. A repo that trusted the "authoritative gate" sentence and skipped the local hook, which the same bullet only "strongly suggests", merges the warning. A repo with no .config/dotnet-tools.json also silently loses the CSharpier half, since that step is gated on the manifest existing.

This is the same shape as item 4 above: the prescribed check does not reach what the prose says it covers. Whether the validator grows a build step, or the prose stops calling it the authoritative gate for warnings, is the decision.

Found by the third canonical-review round on the PR for #1075/#1120/#1114/#1119/#1129/#1078.

[ptr727]

6. repo-worktree has no continuation procedure for the standalone-clone fallback

Creating a Worktree gives one continuation procedure, the registered-worktree git worktree add <path> <task-branch>. The standalone-clone fallback block above it ends at switch -c <task-branch> origin/develop, and nothing says how a continuation under that fallback attaches its existing branch.

An agent resuming a task under the fallback follows the only fallback commands it has, recreates <task-branch> at origin/develop, and loses the branch's existing commits from its local tip. The first push is rejected as non-fast-forward with no explanation the unit covers.

I drafted a fix for this in the PR for #1075/#1120 and then reverted it, because each review round found another defect in the added text and the underlying gaps belong here rather than in a carried-text PR. What a correct fix has to cover, all of it verified against the unit and the guard:

• The worktree path is normally still occupied. Cleanup happens only after merge, so the prior session's worktree is still at ~/repos/worktrees/<Repo>-<task-slug> and git worktree add exits fatal: '<path>' already exists. The unit anticipates only the other refusal, a branch already checked out elsewhere, and its remedy does not clear an occupied path.
• The temporary clone may be gone. The unit warns that "the operating system may reap it as temporary data" and gives no re-clone step, so a continuation after a reap dies on fatal: cannot change to '<temporary-root>/...'.
• git switch <task-branch> without -C is not backstopped. gh-write-guard.py rule 6 exempts checkout <ref>/switch <ref> carrying no force flag when the argument resolves as a ref, which is exactly the normal continuation case in a base clone holding the local task branch. So a forgotten -C mutates the maintainer's primary checkout and no hook fires. Any wording here must not claim rule 6 catches it.
• -C in this unit is not one idea. In the create blocks -C ~/repos/<Repo> points at the base clone deliberately, and git clone --no-checkout carries none, so a rationale framing every -C as protecting the base clone is false against the unit's own blocks.

7. The Base Branch's exemption list does not match the cleanup step it cites

merge --ff-only/pull --ff-only and a checkout <ref>/switch <ref> carrying no force flag stay exempt even there, matching this skill's own cleanup step below, which needs exactly those.

Cleanup also runs git worktree remove <exact-path>, git branch -d/-D <exact-branch>, git fetch --prune, and git status against the base clone, so it needs more than "exactly those". A reader checking cleanup against this sentence finds worktree remove and branch -D in neither the exempt list nor the never-list, and either stops mid-cleanup or runs them blind.

8. Creating a Worktree's command blocks hardcode origin/develop

Every block in that unit bases on origin/develop, and the main-only exception lives only in The Base Branch. A reader who reaches the unit with the commands directly bases a main-only task on develop.

[ptr727]

9. resync-a-repo reads hub-owned content one section before it says to fetch the hub

Raised by CodeRabbit on PR #1157 and confirmed against the file.

"Confirm the procedure before starting" opens the skill with:

Read RESYNC.md section 0. ... Run spec/audit.py <RepoName>, the target's registry/repos.json name field ... and read whether the findings are letters (absent) or drift (present but stale) before doing anything else.

The next section, "Reach the hub and measure before changing anything", is where the reader is told to:

Fetch a hub checkout of your own immediately before reading it ... since a stale clone answers confidently instead of failing.

RESYNC.md, spec/ and registry/ are all hub-hosted rather than carried, so the first section directs a reader to read and run hub-owned content one section before the fetch rule appears. A reader with no hub checkout cannot do the first section at all, and one with a stale checkout does it against whatever that clone last fetched, which is the failure the fetch rule exists to prevent.

The fix is a restructuring of the two sections rather than a wording change, which is why it is filed rather than folded into #1157.

[ptr727]

10. "The Base Branch" both permits and forbids pull --ff-only in the same paragraph

A sharper statement of item 7's conflict, from the canonical pass on PR #1157's third fix round. Item 7 covered the exemption list not matching the cleanup step's commands; this is about the paragraph contradicting itself on one command.

The paragraph bans, with a catch-all:

never checkout, pull, reset, commit, or any other command that mutates its own working tree, index, or HEAD while a task is in progress

then says:

merge --ff-only/pull --ff-only stay exempt even there

and closes:

Prose remains the only enforcement for a non-Claude-Code agent, for a machine without that install, and for the shapes the hook itself exempts.

"stay exempt even there" presupposes these shapes are already exempt from the prose ban, but that ban grants no --ff-only exemption and its catch-all covers merge too. The closing sentence then says prose is what binds for exactly the shapes the hook exempts, which reads as forbidding them.

Concrete failure: an agent asked to refresh a base clone before worktree add cannot tell whether git -C <base clone> pull --ff-only is permitted. The hook allows it, one sentence calls it exempt, and the next says prose is the binding layer for it.

One detail for whoever fixes it: the exemption text is otherwise accurate against gh-write-guard.py rule 6, except that it omits that a bare - positional is exempt without needing to resolve as a ref.