docs: add security posture page

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- Added dedicated security posture documentation (`docs/security-posture.md`) with `/security-review` scope, false-positive handling, and CI integration guidance.
 - Added a "Value in 5 minutes" demo section to `README.md` with one-prompt flow and three copy-ready scenarios.
 - Added visual demo artifact `assets/demo-5min-flow.svg` for quick onboarding value proof.
 

README.md

@@ -68,6 +68,7 @@ Three ready-to-run scenarios:
 ## Included assets
 
 - **Release checklist**: `docs/official-release-checklist.md` for official/public release prep.
+- **Security posture**: `docs/security-posture.md` for `/security-review` scope, false-positive handling, and CI integration.
 - **Agents**
   - `flutter-app-builder` (general Flutter implementation)
   - `flutter-code-reviewer`
@@ -154,6 +155,7 @@ Three ready-to-run scenarios:
 8. For security audit and secrets scanning use:
    - `security-review`
    - `docs/security-audit-checklist.md`
+   - `docs/security-posture.md`
 9. Keep generated output aligned with plugin rules.
 10. For dependency upgrades, also follow:
    - `docs/dependency-upgrade-checklist.md`

docs/official-release-checklist.md

@@ -42,6 +42,7 @@ Use this checklist before tagging a public release.
 ## Security readiness
 
 - Security review flow is documented (`docs/security-audit-checklist.md`).
+- Security posture page is documented (`docs/security-posture.md`).
 - `/security-review` command and security skill exist and are linked from README.
 - Official security references are included and up to date.
 - Optional GitHub Action template exists for PR security reviews (`templates/github_actions_security_review.yml`).

docs/security-posture.md

@@ -0,0 +1,56 @@
+# Security Posture
+
+This page defines what `/security-review` covers, how findings are reported, and how to wire checks into CI.
+
+## Scope of `/security-review`
+
+The command follows `skills/security-audit/SKILL.md` and `docs/security-audit-checklist.md`:
+
+1. Diff-aware review first (focus on pending changes).
+2. Secrets scan and credential leak checks.
+3. Code-level security checks for risky patterns.
+4. Mobile hardening checks (Android/iOS release posture).
+5. Supply-chain/dependency checks.
+6. Findings prioritized by severity and exploitability.
+
+## Findings format
+
+Security findings should be returned in this structure:
+
+- Severity: `critical`, `high`, `medium`, `low`.
+- Risk: what can be exploited and under which conditions.
+- Evidence: affected file/path and short explanation.
+- Remediation: concrete fix steps.
+- Verification: command/check proving the fix.
+
+## False-positive handling
+
+Use these rules to keep output actionable:
+
+- Mark suspected false positives explicitly.
+- Explain why the alert is likely non-exploitable.
+- Keep a short "accepted risk" note only with clear rationale.
+- Do not suppress high/critical issues without remediation plan.
+
+## CI integration
+
+Recommended baseline:
+
+1. Run `/review-flutter-code` on PRs for architecture + quality checks.
+2. Run `/security-review` for security findings before merge/release.
+3. Keep `validate-plugin`, `doc-link-health`, and `api-stability` workflows green.
+4. Enforce release checklist completion in `docs/official-release-checklist.md`.
+
+Optional CI extension:
+
+- Use `templates/github_actions_security_review.yml` as a starter workflow.
+- Add repository secrets only through your CI provider secret store.
+- Block release tags if high/critical findings are unresolved.
+
+## References
+
+- Flutter security: https://docs.flutter.dev/security
+- OWASP MASVS: https://mas.owasp.org/MASVS/
+- Google Play security best practices: https://developer.android.com/privacy-and-security/security-best-practices
+- Apple security resources: https://developer.apple.com/security/
+- Claude Code Security Review: https://github.com/anthropics/claude-code-security-review