docs+chore: address third Copilot review on #716 + fix misleading regen comment

Three valid fixes — two from Copilot's third review pass on the
First-Push Safety rewording, plus the script-comment cleanup that
was deferred from the previous round.

## COMMIT_STANDARDS.md "First-Push Safety" example labels

The previous fix updated the rationale to acknowledge that
`git push -u origin <branch-name>` is safe by itself, but the
example block still labeled that form "Risky" — contradicting the
rationale above it. Reworked the example block to show three
distinct cases: DANGEROUS (under-specified pushes that genuinely
resolve to the tracked upstream), DISCOURAGED (the bare-branch-name
form — safe today but relies on push.default config staying
consistent forever), and REQUIRED (the explicit
`HEAD:refs/heads/<name>` form).

## COMMIT_STANDARDS.md and CONTRIBUTING.md hook claim

Both files claimed "a pre-push hook enforces this" / "enforces the
explicit form". Read the actual hook (scripts/pre-push-guard.sh):
it rejects pushes that land any non-`main` local ref on
`refs/heads/main`. It does NOT reject the bare-branch-name push
form (which targets `refs/heads/<name>`, not main).

Reworded both files to describe what the hook actually does — block
the specific originating-incident path — and explain that the
explicit refspec is the contributor-facing rule, not a hook-enforced
constraint.

## scripts/regenerate_client.py inline comment

The comment at line 347 said "Update main __init__.py with
flattened imports (preserve any custom content)" but the code
immediately overwrites the file via `.write_text(init_content)`
with no merge step. The comment misled the reader (and tripped
the Copilot review on this PR's first round). Rewrote the comment
to match actual behavior: overwrite verbatim, no merge, with a
pointer for where to add custom re-exports instead.

Refs #569.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: dougborg

.github/agents/guides/shared/COMMIT_STANDARDS.md

@@ -314,16 +314,27 @@ muscle-memory bare `git push` is all it takes.
 **Always use the fully explicit destination ref for first-time pushes:**
 
 ```bash
-# Risky — depends on push.default, branch tracking, and contributor habits
+# DANGEROUS — under-specified pushes resolve to the tracked upstream (`main`)
+git push                       # no remote, no refspec
+git push -u origin             # no refspec
+git push origin HEAD           # depends on push.default
+
+# DISCOURAGED — safe today, but relies on push.default staying `simple` /
+# `current` and on the branch name being spelled correctly. One stray
+# `git config --global push.default upstream` defeats it.
 git push -u origin chore/foo
 
-# Safe — names both source (HEAD) and destination ref explicitly
+# REQUIRED — names both source (HEAD) and destination ref explicitly.
+# Immune to push.default, branch-tracking config, and bare-push habits.
 git push -u origin HEAD:refs/heads/chore/foo
 ```
 
 This actually happened: commit `30f3fd86` reached main + tagged `mcp-v0.44.1` +
-published to PyPI before the pipeline could be cancelled. A `pre-push` hook now enforces
-the explicit form on every contributor's machine; **do not bypass with `--no-verify`**.
+published to PyPI before the pipeline could be cancelled. A `pre-push` hook at
+`scripts/pre-push-guard.sh` now blocks any push that lands a non-`main` local ref on
+`refs/heads/main`, so the exact incident can't recur — but the hook only catches pushes
+that actually target main, *not* pushes that omit the explicit refspec. **Always use the
+explicit form, and do not bypass the hook with `--no-verify`.**
 
 ## Multi-Package Changes
 

docs/CONTRIBUTING.md

@@ -133,9 +133,12 @@ All formatting is automated via `uv run poe format`.
    destination ref explicitly, so it's immune to git configs (e.g.
    `push.default = upstream`) that can reroute an under-specified push to whatever the
    branch tracks — which, if you created the branch via
-   `git checkout -b <name> origin/main`, is `main`. A pre-push hook enforces the
-   explicit form; never bypass with `--no-verify`. Full rationale + the incident that
-   prompted the rule live in
+   `git checkout -b <name> origin/main`, is `main`. A pre-push hook
+   (`scripts/pre-push-guard.sh`) blocks the specific case where a non-`main` local ref
+   would land on `refs/heads/main`, so the originating incident can't recur — but the
+   hook doesn't reject every under-specified push, so the explicit refspec is the
+   contributor-facing rule. Never bypass with `--no-verify`. Full rationale + the
+   incident that prompted the rule live in
    [COMMIT_STANDARDS "First-Push Safety"](../.github/agents/guides/shared/COMMIT_STANDARDS.md#first-push-safety).
 
 ### Commit Message Format

scripts/regenerate_client.py

@@ -344,7 +344,10 @@ def move_client_to_workspace(workspace_path: Path) -> bool:
                     shutil.copy2(source_item, target_item)
                     print(f"   📄 Updated file: {item_name}")
 
-        # Update main __init__.py with flattened imports (preserve any custom content)
+        # Overwrite main __init__.py with the flattened-import template below.
+        # Note: the file is rewritten verbatim, not merged — any hand-added exports
+        # will be lost on regen. Add custom re-exports to `katana_client.py` or to a
+        # new editable module instead.
         main_init = target_client_path / "__init__.py"
         init_content = '''"""Katana Public API Client - Python client for Katana Manufacturing ERP."""