docs(#911): add build and validation workflow to CLAUDE.md

[fullsend-ai-coder]

Summary

• Adds a "Build and validation" section to CLAUDE.md documenting the mandatory workflow for agents modifying shell scripts in this repo.
• Covers script bundling (make script-build), pre-commit requirements (including non-excluded shellcheck codes), co-staging of .src.sh and .sh files, and the make test command.
• Addresses the root cause of 5 failed agent runs on Make fix agent multi-forge (GitHub + GitLab) #860/feat(#860): make fix agent multi-forge (GitHub + GitLab) #872 where agents had no way to discover these repo-specific requirements.

Changes

CLAUDE.md — added three subsections:

• Script bundling: Documents the .src.sh → .sh bundle architecture and the make script-build command.
• Pre-commit: Documents pre-commit run --all-files requirement, lists which shellcheck codes are excluded (SC1091, SC2001, SC2016) and which are blocking (SC2030, SC2031, SC2034, SC2153), and explains the # shellcheck disable=SC2153 pattern for variable name clashes.
• Tests: Documents make test as the test command.

Testing

• Verified the documented shellcheck exclusions match .pre-commit-config.yaml (args: ["-x", "-e", "SC1091,SC2001,SC2016"]).
• Verified make script-build target exists in Makefile and rebuilds all 12 .src.sh files.
• Verified make test is the correct test command.
• Pre-commit could not run in the sandbox (network policy blocked hook environment installation).

---

Closes #911

Post-script verification

• Branch is not main/master (agent/911-document-precommit-workflow)
• Secret scan passed (gitleaks — d491a976c945a03a3a46e96b64405cc7e168a476..HEAD)
• PR body secret scan passed (gitleaks — no-git)

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 1:20 AM UTC · Completed 1:32 AM UTC

Commit: d2b79c9 · View workflow run →

[fullsend-ai-review]

Review

Findings

Medium

• [technical documentation accuracy] CLAUDE.md:20 — The documentation states "The check-bundle pre-commit hook verifies that committed bundles match the output of make script-build and will reject stale bundles." However, check-bundle is not registered in .pre-commit-config.yaml — it is a Makefile target (make check-bundle) invoked only in CI via .github/workflows/script-test.yml. Calling it a "pre-commit hook" is factually incorrect and could mislead agents into believing it runs automatically at commit time when it actually only runs in CI.
  Remediation: Change to "CI runs make check-bundle to verify that committed bundles match the output of make script-build and will reject stale bundles."

• [protected-path] CLAUDE.md — This PR modifies CLAUDE.md, which is a protected governance file. The change is authorized by issue CLAUDE.md should document pre-commit and script-build validation workflow #911 and the PR description explains the rationale. Human approval is always required for protected-path changes, regardless of context.

Low

• [scope-creep] CLAUDE.md:45 — The "Tests" subsection documenting make test is not part of the scope authorized by issue CLAUDE.md should document pre-commit and script-build validation workflow #911, which specifically covers script bundling, pre-commit validation, co-staging, and shellcheck disable patterns. The addition is minor (3 lines) and harmless.
  Remediation: Consider removing the "Tests" subsection if strict scope adherence is desired, though its inclusion is a trivially small addition of useful information.