docs(B-0191): add ZETA_EXPECTED_BRANCH rule file + CLAUDE.md pointer (AC3)#2239
Merged
docs(B-0191): add ZETA_EXPECTED_BRANCH rule file + CLAUDE.md pointer (AC3)#2239
Conversation
…(AC3) The core harness hook implementation (tools/orchestrator-checks/verify-branch.ts, .claude/hooks/verify-branch-pretooluse.ts, settings.json wiring) landed in PRs #1585/#1586/#2151. AC3 (CLAUDE.md/AGENTS.md documentation) was the remaining gap — cold-starting agents had no pointer to the ZETA_EXPECTED_BRANCH convention. This slice adds: - .claude/rules/zeta-expected-branch.md: carved sentence + operational content (set-before-checkout discipline, hook wiring table, why it matters) - CLAUDE.md pointer bullet: one-liner with the opt-in semantics and PR refs, discoverable at every session wake - Backlog row: status open → in-progress, pre-start checklist appended per backlog-item-start-gate rule Tests: 4/4 pass (bun test tools/orchestrator-checks/verify-branch.test.ts) Build: 0 warnings 0 errors (dotnet build -c Release) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Documents the ZETA_EXPECTED_BRANCH convention by adding a dedicated .claude/rules/ rule file and a CLAUDE.md pointer, and updates the B-0191 backlog row to reflect the work being actively pursued.
Changes:
- Add
.claude/rules/zeta-expected-branch.mddescribing theZETA_EXPECTED_BRANCHworkflow and hook wiring. - Add a CLAUDE.md bullet pointing to the new rule for cold-start discoverability.
- Update B-0191 backlog row metadata and append a pre-start checklist.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/backlog/P1/B-0191-orchestrator-branch-verify-mechanization-design-aaron-2026-05-04.md | Updates row metadata and adds a pre-start checklist for AC3 documentation work. |
| CLAUDE.md | Adds a pointer bullet to the new ZETA_EXPECTED_BRANCH rule. |
| .claude/rules/zeta-expected-branch.md | Introduces a rule file documenting the expected-branch discipline and hook wiring. |
Four list blocks in the pre-start checklist were missing the required blank line between the bold-text label and the list body, triggering MD032 (blanks-around-lists) in markdownlint. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…g-taxonomy Two Copilot findings from PR #2239: 1. status: in-progress → status: open. The enum only allows open/closed/superseded-by-B-NNNN/deferred; in-progress is not a valid value and causes tooling drift in the generated index. Express in-progress state in the body. 2. Reconcile the CLAUDE.md contradiction: the new zeta-expected-branch bullet claimed "(auto-loaded)" while the loading-taxonomy section still said ".claude/rules/ auto-load is unverified — canary test pending". Both claims were in the same document. Fix: update the taxonomy note to reflect empirical confirmation (rule files load at session start as evidenced by every session context) and update the stale "Zeta currently doesn't use it" paragraph to reflect active use. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- backlog row: revert status to 'open' (in-progress is not a valid status enum per tools/backlog/README.md; valid values are open / closed / superseded-by-B-NNNN / deferred) - CLAUDE.md: drop '(auto-loaded)' qualifier from ZETA_EXPECTED_BRANCH loading-taxonomy section notes .claude/rules/ auto-load isbullet unverified in this harness (canary test pending); claiming auto-load here contradicted that note Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 19470f7af3
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
- keep backlog status wording consistent with supported enum - remove stale rules auto-load unverified sentence after canary confirmation - regenerate docs/BACKLOG.md Co-Authored-By: Codex <noreply@openai.com>
3 tasks
AceHack
added a commit
that referenced
this pull request
May 9, 2026
All primary acceptance criteria are now met: - AC1: tools/orchestrator-checks/verify-branch.ts (PR #1585) - AC2: .claude/settings.json hook wiring (PR #2151) - AC3: .claude/rules/zeta-expected-branch.md + CLAUDE.md pointer (PR #2239) - AC4: unit tests in verify-branch.test.ts - AC5: tools/orchestrator-checks/check-orchestrator-state.ts (this PR) The state-check script (Rule 0: TS not bash) emits structured JSON with currentBranch, expectedBranch, branchMatch, dirtyFiles, worktrees, and driftedWorktrees — the last field flags the CWD-bleed-over hazard when another worktree is on the same branch as ZETA_EXPECTED_BRANCH. Tests: 12 pass / 0 fail across both orchestrator-checks files. Build: 0 warnings / 0 errors. Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/backlog/P1/B-0191AC3 (CLAUDE.md/AGENTS.md documentation) was the only remaining gap. The core implementation already landed:tools/orchestrator-checks/verify-branch.ts(PR feat(orchestrator-checks): verify-branch.ts harness hook (B-0191 implementation) #1585),.claude/hooks/verify-branch-pretooluse.ts(PR feat(claude-hooks): verify-branch-pretooluse.ts wrapper + opt-in README (B-0191 #2 + #3) #1586),settings.jsonwiring (PR feat(B-0191): wire verify-branch PreToolUse hook into settings.json #2151)..claude/rules/zeta-expected-branch.md— carved sentence, set-before-checkout discipline, hook wiring table, full reasoning pointers.ZETA_EXPECTED_BRANCHconvention without priming.status: open → in-progress; appends pre-start checklist perbacklog-item-start-gaterule.Test plan
bun test tools/orchestrator-checks/verify-branch.test.ts→ 4 pass, 0 faildotnet build -c Release→ 0 Warning(s), 0 Error(s).claude/rules/zeta-expected-branch.mdZETA_EXPECTED_BRANCH)What remains after this PR
🤖 Generated with Claude Code