t1473: enforce worktree-first guidance in guardrails

[marcusquinn]

Summary

• update pre-edit-check messaging to require the canonical repo directory to stay on main and move code work into linked worktree paths
• revise shared agent guidance so user-facing workflow language is worktree-first and treats Git refs as internal details inside the linked worktree
• tighten traceability wording from branch-centric to worktree/ref-centric where it affects operator guidance

Verification

• shellcheck .agents/scripts/pre-edit-check.sh
• bash -n .agents/scripts/pre-edit-check.sh
• markdown-formatter check .agents/AGENTS.md

Closes #4443

Summary by CodeRabbit

• Documentation

  • Transitioned Git workflow documentation from branch-centric to linked worktree approach for code changes.
  • Updated all operational guidance and terminology to reflect worktree-first methodology.

• Chores

  • Modified workflow validation and automation scripts to support the new worktree-based development process.

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[github-actions]

🔍 Code Quality Report

�[0;35m[MONITOR]�[0m Code Review Monitoring Report

�[0;34m[INFO]�[0m Latest Quality Status:
SonarCloud: 0 bugs, 0 vulnerabilities, 414 code smells

�[0;34m[INFO]�[0m Recent monitoring activity:
Fri Mar 13 14:34:04 UTC 2026: Code review monitoring started
Fri Mar 13 14:34:05 UTC 2026: SonarCloud - Bugs: 0, Vulnerabilities: 0, Code Smells: 414

📈 Current Quality Metrics

• BUGS: 0
• CODE SMELLS: 414
• VULNERABILITIES: 0

Generated on: Fri Mar 13 14:34:08 UTC 2026

---

Generated by AI DevOps Framework Code Review Monitoring

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: c0572e19-4623-481b-a8a8-8a79b7d726ad

📥 Commits

Reviewing files that changed from the base of the PR and between 14a87d0 and 13c2c7e.

📒 Files selected for processing (3)

• .agents/AGENTS.md
• .agents/prompts/build.txt
• .agents/scripts/pre-edit-check.sh

---

Walkthrough

The pull request transitions the AI agent workflow from branch-centric to worktree-centric development practices. Documentation and scripts are updated to replace branch terminology with linked worktree language, enforce canonical main repository preservation, and reframe operational guidance around worktree paths rather than branching operations.

Changes

Cohort / File(s)	Summary
Workflow Documentation .agents/AGENTS.md, .agents/prompts/build.txt	Replaced branch-centric terminology with worktree-first language throughout; updated Full-loop flow to start from canonical main and use linked worktrees; adjusted Git workflow traceability (TODO → GitHub issue → worktree/ref → PR → merge); reframed pre-edit rules and user-facing guidance to emphasize worktree paths as primary references.
Pre-edit Check Script .agents/scripts/pre-edit-check.sh	Refactored branch-detection logic to worktree-centric checks; updated exit codes and LOOP_DECISION semantics; replaced branch terminology with worktree guidance in all user-facing prompts and warnings; adjusted interactive flows to enforce canonical repo on-main constraint and recommend linked worktree usage for code changes.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• #343: Modifies pre-edit/workflow guidance and safety rules to enforce worktree-first model with restrictions on arbitrary file writes to main branch.
• #4133: Updates git branch/worktree detection logic in pre-edit-check.sh with tests for multi-remote and worktree branch detection.
• #1160: Modifies AGENTS.md to enforce worktree-first PR-required workflows alongside worktree implementation checks.

Suggested labels

needs-review

Poem

🌳 From branches tangled, worktrees bloom,
One main to rule them, room by room,
Paths and refs now lead the way,
Canonical order to stay,
A cleaner workflow, hip-hip-hooray! 🎉

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch bugfix/t1473-worktree-only-guardrails

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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