docs: add mandatory branch/PR workflow rules

[shaypal5]

Summary

• Adds a Branch & PR Workflow section to CLAUDE.md as the first section (before all other rules), locking the rule that no work goes directly to main
• Installs .git/hooks/pre-push to mechanically block any push targeting main, regardless of who or what triggers it
• Updates .agent-plan.md to reflect that these workflow rules are now locked

Workflow rules locked

1. git checkout main && git pull before starting any work
2. git checkout -b <descriptive-branch-name> — always branch from latest main
3. Commit work to the branch
4. Update .agent-plan.md to reflect state after the PR merges; commit to same branch
5. Open a PR on GitHub with a detailed description — never push to main directly

Enforcement layers

Layer	Mechanism
Primary	CLAUDE.md — read by Claude at session start
Secondary	Agent memory (feedback entry)
Mechanical	.git/hooks/pre-push — blocks push to main at git level

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds explicit “Branch & PR Workflow” rules to the repo’s agent-facing documentation and updates the agent plan to reflect the new workflow constraints.

Changes:

• Adds a mandatory Branch & PR Workflow section at the top of CLAUDE.md.
• Updates .agent-plan.md current-state text to mention the workflow rules and their enforcement.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
CLAUDE.md	Documents mandatory branching/PR workflow rules, including “never push to main”.
.agent-plan.md	Updates current system state to reference the new workflow rules and claimed enforcement mechanism.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

pr-agent-context report:

This run includes unresolved review comments on PR #1.

For each unresolved review comment, recommend one of: resolve as irrelevant, accept and implement
the recommended solution, open a separate issue and resolve as out-of-scope for this PR, accept and
implement a different solution, or resolve as already treated by the code.

After I reply with my decision per item, implement the accepted actions, resolve the corresponding
PR comments, and push all of these changes in a single commit.

# Copilot Comments

## COPILOT-1
Location: .agent-plan.md
URL: https://github.com/leadforge-dev/leadforge/pull/1#discussion_r3104702550
Status: outdated
Root author: copilot-pull-request-reviewer

Comment:
    The statement that the workflow is “enforced via `.git/hooks/pre-push`” is misleading/inaccurate in a repo context: `.git/hooks` isn’t versioned/cloned for other developers, and this PR doesn’t add any tracked hook script that would be installed automatically. Consider replacing this with a versioned hooks directory (and documented `core.hooksPath` setup), or describing enforcement via GitHub branch protection/CI checks instead of `.git/hooks`.

## COPILOT-2
Location: CLAUDE.md
URL: https://github.com/leadforge-dev/leadforge/pull/1#discussion_r3104702559
Status: outdated
Root author: copilot-pull-request-reviewer

Comment:
    The examples list `git push --force` without specifying `main`, but the sentence is about commands that target `main` directly. As written, it can be read as banning force-pushes to any branch; if the intent is only to block pushes to `main`, consider tightening the wording/examples to explicitly include `main` (or split into two rules: no pushes to `main`, and separate guidance on force-push usage).
    ~~~suggestion
    Never use `git push origin main`, `git push --force origin main`, or any variant that targets `main` directly.
    ~~~

## COPILOT-3
Location: .github/workflows/pr-agent-context.yml:14
URL: https://github.com/leadforge-dev/leadforge/pull/1#discussion_r3104738699
Root author: copilot-pull-request-reviewer

Comment:
    This workflow calls a third-party reusable workflow pinned only to the `v4` tag. For supply-chain security and reproducibility, pin `uses:` to an immutable commit SHA (and optionally keep a comment noting the corresponding release tag).
    ~~~suggestion
        uses: shaypal5/pr-agent-context/.github/workflows/pr-agent-context.yml@<FULL_40_CHAR_COMMIT_SHA_FOR_V4> # v4
    ~~~

## COPILOT-4
Location: .github/workflows/pr-agent-context-refresh.yml:39
URL: https://github.com/leadforge-dev/leadforge/pull/1#discussion_r3104738714
Root author: copilot-pull-request-reviewer

Comment:
    This workflow calls a third-party reusable workflow pinned only to the `v4` tag. For supply-chain security and reproducibility, pin `uses:` to an immutable commit SHA (and optionally keep a comment noting the corresponding release tag).
    ~~~suggestion
        uses: shaypal5/pr-agent-context/.github/workflows/pr-agent-context.yml@<FULL_40_CHAR_COMMIT_SHA_FOR_V4> # v4
    ~~~

Run metadata:

Tool ref: v4
Tool version: 4.0.18
Trigger: commit pushed
Workflow run: 24599246501 attempt 1
Comment timestamp: 2026-04-18T06:52:54.524480+00:00
PR head commit: 270394b4d26bf28533e751aa2aa093c1991ff912