fix(sdlc): prevent bare primary alpha role inference

[ryanklee]

Summary

• remove the legacy primary-worktree hapax-council -> alpha identity fallback from agent-role.sh
• keep role-named lane worktree recovery for hapax-council--, cx-, antigrav, and vbe- paths
• add FM-1 coverage proving an alpha/* branch with a session id resolves through roleless and does not inherit a stale alpha claim

Verification

• uv run pytest tests/hooks/test_cc_task_gate.py tests/hooks/test_agent_role.py tests/scripts/test_hapax_claude_headless.py -q
• uv run ruff check tests/hooks/test_cc_task_gate.py tests/hooks/test_agent_role.py tests/scripts/test_hapax_claude_headless.py
• uv run ruff format --check tests/hooks/test_cc_task_gate.py tests/hooks/test_agent_role.py tests/scripts/test_hapax_claude_headless.py
• bash -n hooks/scripts/agent-role.sh hooks/scripts/cc-task-gate.sh scripts/hapax-claude scripts/hapax-codex scripts/hapax-antigrav scripts/hapax-vibe scripts/hapax-gemini scripts/hapax-claude-headless
• git diff --check

Summary by CodeRabbit

Bug Fixes

• Removed automatic role inference from the primary repository checkout directory. Roles must now be explicitly exported rather than inferred from directory names, ensuring clearer and more predictable identity/role resolution.
• Updated session handling to correctly treat callers without explicit roles as role-less, preventing unintended role claims.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 9ac2ba6d-cfc4-458c-bbfb-dcf6bfc6fb99

📥 Commits

Reviewing files that changed from the base of the PR and between 414db01 and cdd2545.

📒 Files selected for processing (2)

• hooks/scripts/agent-role.sh
• tests/hooks/test_cc_task_gate.py

---

📝 Walkthrough

Walkthrough

This PR removes an implicit role inference fallback from the agent role resolution function, which no longer treats the primary hapax-council checkout directory as an alpha lane identity. Tests are updated to validate this change and add regression cases for session identity semantics.

Changes

Primary Checkout Path Role Semantics

Layer / File(s)	Summary
Remove alpha inference and update test parameters hooks/scripts/agent-role.sh, tests/hooks/test_cc_task_gate.py	hapax_agent_role_from_path removes the fallback that inferred alpha from the primary hapax-council directory name, replaced with clarifying comments. The test_role_from_path parameter list removes the ("hapax-council", "alpha") mapping.
Regression tests for path and session identity behavior tests/hooks/test_cc_task_gate.py	Adds test_primary_worktree_path_does_not_infer_alpha asserting the primary path does not infer a role, and test_branch_prefix_with_session_is_roleless_not_alpha_claim verifying that role-less sessions on alpha/ branches are treated as roleless even when an alpha claim exists. TestSpawnerSessionIdentity docstring is updated to document six spawners exporting identity metadata.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• hapax-systems/hapax-council#3758: Aligns with this PR's change to hapax_agent_role_from_path and implements role-less/session-keyed gating semantics that the regression tests now validate.

Poem

🐰 The council's path grows wise and clear,
No alpha claim from primary tier,
Each role must speak for what it is,
No fallback fuzz in identity's fizz!
With tests that guard what's roleless, bright,
The gate knows session-truth is right. ✨

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description provides a clear summary and verification steps but lacks the required AuthorityCase and CLAUDE.md hygiene sections from the template.	Add the AuthorityCase section with Case and Slice identifiers, and include the CLAUDE.md hygiene checklist with appropriate selections.
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: removing the legacy fallback that inferred an alpha role from the primary hapax-council directory.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/cx-blue-reform-kill-phantom-role-20260601

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: cdd2545583

ℹ️ 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".

[chatgpt-codex-connector]

Align primary-session identity with existing consumers

When a bare session starts in the primary checkout with only a session id, this branch now makes hapax_agent_identity return empty, so cc-claim/cc-task-gate degrade to roleless. Existing consumers were not updated: for example hooks/scripts/session-context.sh still falls back from an empty helper result to */hapax-council) ROLE="alpha", and scripts/cc-close only asks hapax_agent_identity, so the same session can be prompted/onboarded as alpha while claims and gate decisions are keyed as roleless and close can miss clearing the roleless lease. Please update those remaining identity fallbacks to use the same effective-role behavior, or keep the primary checkout mapping consistent until they are migrated.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Skip relay inference for the primary checkout

In a primary hapax-council checkout with no explicit role but a session id, this only makes hapax_agent_identity fail; hapax_effective_role then checks hapax_relay_inferred_role before falling back to roleless. If exactly one relay file exists, e.g. ~/.cache/hapax/relay/alpha.yaml, cc-claim and cc-task-gate still resolve the bare primary session as that lane and can inherit its claim, so the intended “primary checkout is not a lane identity” behavior is bypassed in the normal relay-enabled environment.

Useful? React with 👍 / 👎.