Skip to content

docs(agents): harden the three internal worktree recipes to the canonical form - #14003

Merged
os-zhuang merged 1 commit into
mainfrom
claude/issue-13729-worktree-recipe-internal-fold
Sep 1, 2026
Merged

docs(agents): harden the three internal worktree recipes to the canonical form#14003
os-zhuang merged 1 commit into
mainfrom
claude/issue-13729-worktree-recipe-internal-fold

Conversation

@claude

@claude claude Bot commented Aug 31, 2026

Copy link
Copy Markdown
Contributor

Fixes #13729

The three INTERNAL copies that PRESCRIBE a worktree recipe to an agent still taught the unhardened spelling. Each now reads as the form AGENTS.md Prime Directive 11 and CLAUDE.md already teach:

git fetch origin main && git worktree add --no-track ../REPO-TASK -b BRANCH origin/main

Exactly one recipe sentence per file; nothing else in these files is touched.

What changed, per copy

file before after
.claude/skills/checklist-author/SKILL.md L33 git worktree add ../objectstack-TASK -b BRANCH main gains --no-track and the git fetch origin main + origin/main base
.claude/agents/os-dev.md L32-33 git worktree add ../REPO-issue-N -b claude/issue-N-SLUG origin/main gains --no-track and the fetch
.claude/skills/dogfood-verification/SKILL.md L140 git worktree add -b BRANCH /tmp/pr origin/main gains --no-track and the fetch

Placeholder metavariables are spelled in caps above because this body is sanitized; the files themselves keep each copy's own angle-bracket placeholder naming verbatim (../objectstack-TASK stays the checklist-author spelling, claude/issue-N-SLUG stays the os-dev spelling, /tmp/pr stays the dogfood one).

Why

Plain -b writes branch.NAME.remote / branch.NAME.merge into the .git/config that every worktree of the repo SHARES — the class already adjudicated in #13052 / objectstack-ai/objectui#6880 and already hardened in AGENTS.md PD#11 and CLAUDE.md; these copies were never swept with it. The checklist-author copy was additionally the only one still basing a new tree on local main with no fetch — the objectstack-ai/objectui#6208 class.

The published fourth copy (skills/objectstack-pm-dispatch/SKILL.md) is NOT in this diff: it was discharged separately in #13891, which has landed, with its {default_branch} interpolation preserved. Verified on today's origin/main before editing.

Two ratchets bind here, so the edits are reflows rather than rewraps

check:pm-skill-ratchet constrains these files twice, and the obvious spellings break one each:

  • Zero line-count headroom. All three files sit exactly at their ceiling (os-dev.md 466/466, checklist-author 62/62, dogfood-verification 157/157). Wrapping the longer recipe onto a new line failed the gate on all three.
  • 120-byte per-line budget. Keeping the longer recipe on its single existing line failed the other half — 139B / 133B / 134B respectively.

So each recipe is reflowed within the lines its sentence already occupied: the break moves, the line count does not, and every touched line lands under budget (97/81, 105/106, 92/106 bytes). Neither ratchet moves and no ceiling is raised, so no maintainer ruling is needed for either.

Verification

Gate union derived on the final head with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (no hand-built path list) at f977b0b54 — 10 families, all run at that same head:

  • check:pm-skill-ratchet.claude/agents/os-dev.md is 466 lines (ceiling 466; headroom 0), checklist-author/SKILL.md is 62 lines (ceiling 62; headroom 0), dogfood-verification/SKILL.md is 157 lines (ceiling 157; headroom 0); widest-table-row pins all unchanged at 0
  • check:agent-model-declared · check:agent-test-spelling · check:doc-authoring · check:nul-bytes · check:pm-governed-merges · check:pm-skill-id-lint · check:skill-frame-sync
  • pnpm --filter @objectstack/lint run check:doc-formula-expressionsself-test: 58 cases passed, 22 record-scoped formula example(s) across 427 files / 1451 TS blocks judged clean (needed @objectstack/formula and @objectstack/lint built first; its own PREREQUISITE NOT MET refusal is not a finding)
  • node scripts/pm/check-governed-queue-guard.mjsNOT MEASURED locally, by construction: it reads GITHUB_EVENT_PATH and nothing else, so outside a workflow run it exits 1 with could not read GITHUB_EVENT_PATH. That is its refusal path, not a finding. CI measures it.

pnpm lint (repo-wide ESLint) is a declared narrowing, measured on all three axes: (1) the population comes from ESLint's own resolved config, not a guess — all three files report File ignored because no matching configuration was supplied., i.e. markdown is outside the linted population entirely; (2) the count comes from --format json — 3 files reported, 0 errors; (3) invariance for untouched files holds because the diff contains no eslint.config.mjs, no tsconfig and no TypeScript at all, so no untouched file's verdict can move.

No changeset: the diff is .claude/** only and publishes nothing from any package, so skip-changeset applies.

Scope guard

.claude/agents/os-dev.md carries adjacent text owned by other in-flight cards — the verify-lock and skip-changeset paragraphs of #12800 / #13300 / #13432. Those are deliberately untouched here; this diff is the recipe sentence only. Those three cards are not addressed by this PR and remain open.

Draft on purpose: governed .claude/** markdown, human merge.


Generated by Claude Code

…ical form

The three internal copies that PRESCRIBE a worktree recipe to an agent still
taught the unhardened spelling. Each now reads as the form AGENTS.md Prime
Directive 11 and CLAUDE.md teach:
`git fetch origin main && git worktree add --no-track ... origin/main`.

- `.claude/skills/checklist-author/SKILL.md` - gained `--no-track` and the
  fetched `origin/main` base (it was the only copy still basing on local `main`)
- `.claude/agents/os-dev.md` - gained `--no-track` and the fetch
- `.claude/skills/dogfood-verification/SKILL.md` - gained `--no-track` and the
  fetch

Plain `-b` writes `branch.NAME.remote`/`branch.NAME.merge` into the `.git/config`
that every worktree of the repo SHARES; `--no-track` is the adjudicated fix.

Each edit is byte-budget and line-count neutral, because `check:pm-skill-ratchet`
binds twice here: all three files sit at ZERO line-count headroom, and every line
has a 120-byte budget. So the longer recipe is reflowed within the lines the
sentence already occupied rather than wrapped onto a new one - neither ratchet
moves, and neither needs a maintainer ruling. No other text in these files is
touched.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Msg17tAHJ3jVTYFgHydCm2
@os-zhuang
os-zhuang marked this pull request as ready for review September 1, 2026 00:01
@os-zhuang
os-zhuang enabled auto-merge September 1, 2026 00:02
@os-zhuang
os-zhuang added this pull request to the merge queue Sep 1, 2026
Merged via the queue into main with commit 3b2a3f6 Sep 1, 2026
29 checks passed
@os-zhuang
os-zhuang deleted the claude/issue-13729-worktree-recipe-internal-fold branch September 1, 2026 00:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation size/s skip-changeset PR has no user-facing published change; bypasses the changeset gate

Projects

None yet

2 participants