fix: trim security heuristics to policy directives

[ralphbean]

Summary

• Trim security sub-agent heuristics from feat(#898): add security heuristics to review sub-agent #2038 to policy directives only, removing domain-knowledge explanations Claude already knows (fail-open definitions, least-privilege explanations)
• Merge the redundant "Permission manifest changes" and "Workflow permission and role auditing" sections into a single "Permission and role changes" section
• Deduplicate the permission file-type list between the Own block and the dedicated section

These commits were pushed to #2038's branch but the merge queue picked up the prior head before they landed.

Toward #898

Test plan

• make lint passes
• CI passes (markdown-only change, no Go code affected)

[github-actions]

Site preview

Preview: https://ab67c02e-site.fullsend-ai.workers.dev

Commit: 51c0f75a7fcd9648e9f1a0749c046153b6bd6e7b

[fullsend-ai-review]

🤖 Review · Started 8:22 PM UTC
Commit: d0ac11b · View workflow run →

[fullsend-ai-retro]

🤖 Retro · Started 8:25 PM UTC
Commit: d0ac11b · View workflow run →

[fullsend-ai-retro]

Retro: PR #2046 — fix: trim security heuristics to policy directives

What happened: PR #2038 (by fullsend-ai-coder[bot]) added security heuristics to the review sub-agent to address issue #898. The code agent produced verbose heuristics that re-explained security concepts (fail-open definitions, least-privilege explanations) that Claude already knows. A human (ralphbean) had to open PR #2046 to trim the output down to just policy directives — what to flag and at what severity — and to merge redundant sections. PR #2046 was opened and closed within 3 minutes without merging (the changes were likely applied via another path).

The review agent started a run on PR #2046 but was wasted since the PR was closed ~90 seconds later. This is already tracked by issues #1870 and #1439.

One new proposal is included below, addressing the code agent's tendency to over-explain domain knowledge when writing agent prompts, which caused human rework.

Skipped proposals (already tracked):

• Wasted review agent run on quickly-closed PR → Skip review/fix dispatch when PR action is 'closed' #1870, Skip review dispatch when PR is already closed or merged #1439, Debounce review dispatch on rapid synchronize events #1014
• Agent run cancellation/dedup → Handle concurrent agent runs: deduplication, locking, and conflict resolution #77, feat: dispatch-layer dedup and per-issue concurrency guard to prevent duplicate agent runs #766

Proposals filed

• Code agent over-explains domain knowledge in agent prompt files, causing rework (in fullsend-ai/fullsend)

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 8:25 PM UTC · Completed 8:30 PM UTC
Commit: d0ac11b · View workflow run →

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 8:22 PM UTC · Completed 8:32 PM UTC
Commit: d0ac11b · View workflow run →

[github-actions]

E2E tests are running

Authorization passed for this commit. See the E2E Tests workflow for results.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[ben-alkov]

/fs-review

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 4:29 PM UTC · Completed 4:39 PM UTC
Commit: 6bfb10b · View workflow run →

[ben-alkov]

Good stuff

• Dedupe and eliminate redundancy
• Remove the parenthetical file-type list from the "Own:" paragraph; it's misplaced in this section
• Provide policy thresholds and severity assignments without re-teaching the concept

[fullsend-ai-review]

Review

Findings

Medium

• [stale-reference] internal/scaffold/fullsend-repo/skills/pr-review/SKILL.md:198 — The diff removes the workflow-permission category from security.md by deleting the "Workflow permission and role auditing" section and merging it into "Permission and role changes" (which lists permission-expansion, permission-reduction, role-escalation, secret-exposure). However, SKILL.md line 198 still includes workflow-permission in the security dimension's category routing table. This creates a cross-file inconsistency: the orchestrator will route prior workflow-permission findings to the security sub-agent for re-review anchoring, but the sub-agent will never produce new findings with that category.
  Remediation: Remove workflow-permission from the security categories list in SKILL.md, or re-add it to the merged section in security.md.

Low

• [fail-open] internal/scaffold/fullsend-repo/skills/pr-review/sub-agents/security.md:14 — The "Own" scope line removed the parenthetical examples (GitHub App manifests, workflow permissions blocks, IAM policies, OAuth scopes) that previously disambiguated "permission manifest changes." The merged "Permission and role changes" section still enumerates all these file types, so the operative detection instructions are intact — but the scope declaration is now vaguer than its subsections.

Info

• [permission-reduction] internal/scaffold/fullsend-repo/skills/pr-review/sub-agents/security.md:95 — The workflow-permission finding category was dropped when merging the two permission sections. Workflow permissions: block changes will now be categorized under permission-expansion or permission-reduction. This is a taxonomy simplification, not a security gap.

• [design-direction] internal/scaffold/fullsend-repo/skills/pr-review/sub-agents/security.md — The condensation brings security.md closer to the length of other sub-agents (~120 lines vs correctness at 75, intent-coherence at 76). The tradeoff is whether the condensed policy directives maintain the same finding quality as the verbose checklists. The proof point will be empirical — whether the condensed version catches the same findings on future security-relevant PRs.

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 5:39 PM UTC · Completed 5:47 PM UTC
Commit: 51c0f75 · View workflow run →

[fullsend-ai-retro]

Retro: PR #2046 — fix: trim security heuristics to policy directives

Context: PR #2038 (code agent) added verbose security heuristics to the review sub-agent for issue #898. A human opened PR #2046 to trim those heuristics to concise policy directives, removing domain-knowledge explanations Claude already knows, and merging redundant sections. The PR was needed because the merge queue on #2038 picked up the prior HEAD before the human's cleanup commits landed.

Workflow observations:

1. Retro raced review on PR open. When PR fix: trim security heuristics to policy directives #2046 was created, both the review agent (20:22 UTC) and retro agent (20:25 UTC) dispatched nearly simultaneously. The retro completed at 20:30 — two minutes before the review finished at 20:32. This means the retro analyzed the PR without access to the review's findings. The retro filed issue Code agent over-explains domain knowledge in agent prompt files, causing rework #2047 based solely on the PR description and parent PR context, missing the review's later stale-reference finding.

2. Valid medium finding merged unresolved. The second review (triggered by /fs-review on 2026-06-11) found a genuine cross-file inconsistency: SKILL.md:198 still references a workflow-permission category that was removed from security.md. Verified as accurate. The PR was approved and merged without addressing this. Already tracked by Auto-file tracking issues for unresolved medium+ severity review findings #1956 and Review agent medium findings should trigger fix agent or block merge #870.

3. Code agent verbosity causing rework. Already tracked by Code agent over-explains domain knowledge in agent prompt files, causing rework #2047 (filed by the first retro run on this same PR).

4. Duplicate retro runs. This is the second retro on PR fix: trim security heuristics to policy directives #2046 — the first ran on PR open (2026-06-08), this one on merge (2026-06-11). Partially overlaps with existing skip-guard issues (Skip retro dispatch on PRs with no agent involvement #939, Refine retro dispatch guard in issue #939 to account for agent involvement on non-agent branches #942, Skip retro dispatch for unmerged PRs with no agent interaction #1411, Extend retro skip guard to human-authored PRs with no-finding reviews #1675) but none specifically address the retro-before-review race.

One new proposal below addresses the retro→review sequencing gap. Other findings are already tracked by existing issues.

Proposals filed

• Retro dispatch should depend on review completion, not fire concurrently on PR open (in fullsend-ai/fullsend)