docs(#179): add shell-safety heuristics to review correctness

[fullsend-ai-coder]

Add echo-flag-injection and unquoted-heredoc-expansion heuristics to the correctness sub-agent and the code-review skill. Both rules are scoped to harness scripts (post-code.sh, post-fix.sh, post-review.sh) where user- or agent-controlled content flows through shell commands.

Echo flag injection: echo "${VAR}" interprets leading dashes as flags, silently corrupting output. Recommends printf. Unquoted heredoc: <<TOKEN allows shell expansion of $ and backticks in structured data, silently corrupting JSON/YAML. Recommends jq -n or quoted heredocs.

False-positive scoping: neither rule fires on hardcoded strings, quoted heredocs, or non-harness scripts.

---

Closes #179

Post-script verification

• Branch is not main/master (agent/179-shell-safety-heuristics)
• Secret scan passed (gitleaks — f96750babbed5ada406a9ae04e8068449701d9c7..HEAD)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[github-actions]

E2E tests did not run

E2E tests run automatically for org/repo members and collaborators on pull requests.

For other contributors, a maintainer must add the ok-to-test label after the latest push.

See E2E testing guide for details.

[fullsend-ai-review]

Review

Findings

Medium

• [incomplete-doc] docs/guides/user/building-custom-agents.md:334 — The shell safety guidance in the "Building custom agents" guide does not mention the two specific patterns now documented in the code-review skill: echo flag injection (echo "${VAR}" where VAR may start with -e/-n) and unquoted heredoc expansion (<<TOKEN without quotes). The guide's current advice — "Never interpolate agent output into shell commands without quoting. Use jq -r to extract values into variables, then use "${VAR}" (double-quoted) everywhere" — is correct at the principle level but does not address the subtlety that echo interprets leading dashes as flags even when the variable is properly quoted. The review agent will now catch these violations automatically via the heuristics added by this PR, so the user-facing risk is mitigated. Updating the guide with these specific patterns would make the guidance self-contained for users who read docs without relying on automated review.

Previous run

Review

Findings

Low

• [documentation-structure] internal/scaffold/fullsend-repo/skills/code-review/SKILL.md:92 — The new shell safety bullet points use a nested parent-child structure (a parent bullet with sub-bullets for each heuristic). All other bullets in the Correctness section are top-level and self-contained. The Security section similarly uses top-level bullets with bold inline headers for extended items rather than parent-child nesting.
  Remediation: Consider flattening the structure — make "Echo flag injection" and "Unquoted heredoc expansion" top-level bullets, each starting with a bold name followed by the explanation, matching the pattern used elsewhere in both sections.

[guyoron1]

/fs-review