docs(ci): plan local feedback before coherent batch pushes

[ty-everett]

Program and scope

• Tracker: BotBoard708.
• Problem: repeated hosted iterations pay for easily discoverable local failures, while an indiscriminate full local campaign after every edit also wastes time. Ty requested contributor/agent guidance that uses a focused edit loop and coherent before-push batches.
• Change: root AGENTS/CONTRIBUTING guidance plus an advisory node scripts/ci-local-feedback.mjs --base <intended-PR-base> [--json] entrypoint. It prints focused script/lint/format feedback and existing root/affected/dependent/critical checks without running campaigns, installing packages or qualifying a head.
• Scope includes committed branch changes, separate staged/unstaged/untracked paths and both rename endpoints. Lock importer advice conservatively unions HEAD/index/worktree. Commands validate working-tree bytes; align index/worktree before treating results as next-push evidence.
• Current dependency/mutation selectors and policies remain authoritative. Unknown trust boundaries, cold builds, embedded package builds and platform requirements remain explicit limits. Hardware speed/worker contention must be measured rather than assumed.

Impact

• No public package source, dependency or release manifest changed
• Documentation and an advisory root script changed
• No workflow, gate, test threshold, permission, deployment or publication change

Verification

• Node24.18.0/pnpm10.33.2; frozen offline install with scripts disabled, audited esbuild rebuild.
• pnpm health:check:258/258 root script tests; zero control errors, existing maintenance notices retained.
• pnpm lint, pnpm format:check, pnpm build:property, pnpm typecheck:pass. Package build inputs remain unchanged after latest script/doc fixes; final health/lint/format/type checks repeated.
• Focused planner tests5/5 pass: direct coverage vs dependent regressions; build prerequisites without duplicate tests; docs vs shared-control scope; real Git committed/renamed/staged/unstaged/untracked/ignored paths; staged source/lock edits reversed in working tree still retained. Complete diff/quoting reviewed; git diff --check passes.
• Independent internal reviewer found two scope/guidance gaps; both fixed with regression evidence, final review has no residual actionable findings.
• Actual planner on this four-file change prints focused root script/lint/format commands and invariant health/lint/format/audit/type checks, no unrelated mutation/package campaign.
• Complete exact-head hosted qualification (monitoring after publication; draft)

Security and dependencies

• No audit suppression, exception, skipped gate or security setting change
• pnpm audit:security fails on inherited unchanged root dependencies: brace-expansion GHSA-qhr7-859c-m2p7 / GHSA-6j4f-fj2g-mc7p and engine.io GHSA-2gc4-cqfq-p2gv. Three high advisories remain visible. Manifest/workspace/lock identical to base main69879c3e; no dependency remediation is in scope.
• Audit is included unconditionally in every printed before-push plan. Local results never replace reproducible complete exact-head remote qualification.

Release and completion

• No package release, deployment or active campaign touched
• Local changes and independent review complete
• Exact-head hosted qualification complete; no green/completion or merge claim
• This is a separate draft from merged705 prerequisite gating and709 accounting. It has no adminmerge authorization.

Authored analysis repair

First headfdb6e3ee2 had five new Sonar issues; all were addressed together in521bde322 with independent review and repeated local health/lint/full-format/types plus focused tests. System Git uses a fixed installation rather than writable PATH entries; the harmless shadow-PATH Git regression passes. Raw POSIX quote escapes, explicit stable comparator and Set membership preserve semantics. Printed snippets require POSIX shell/Git Bash; Windows execution is not claimed tested. Revised head521bde3224e6c066776b860edf7f0504caff0324 passes exact Sonar zero-new-findings. Both exact-head CodeQL analyses also passed; inherited audit/downstream qualification stays failed. No complete green claim.

Final exact-head status

Current head521bde3224e6c066776b860edf7f0504caff0324; base69879c3ed27dbff8384b2f12a5ca24c939fa64c6. Sonar zero-new-findings, both CodeQL analyses, Dependency Review, repository health and conformance passed. No open review threads. Existing three-high security audit fails before build; downstream mandatory gates remain failed/skipped. The PR stays draft/unmerged with no complete-green claim or adminmerge authorization.

[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