quality: scheduled OSV advisory scan (pending private routing config)

[simple-agent-manager]

Summary

• Extracts the scheduled OSV advisory integration from commit 5863929ace4e0670aecc767e640c068e35d6a959 on PR quality: add deterministic runtime-boundary program #1784 so the broader quality program can merge independently.
• Preserves the schedule-only trigger, fork guard, read-only permissions, dual-secret fail-closed gate, pinned OSV-Scanner 2.5.0 install with SHA256 verification, and authenticated private summary routing.
• Adds focused workflow/request contracts and scanner-to-webhook success/failure slices while keeping the six requested source files byte-for-byte faithful to the source commit.

This PR must stay draft until the SAM_OSV_WEBHOOK_URL and SAM_OSV_WEBHOOK_TOKEN repository secrets exist, the SAM-side private webhook intake exists, and routing has been tested end to end. It was extracted from PR #1784 specifically so that PR's quality program can merge independently.

Staging verification is intentionally not applicable: this scheduled workflow cannot be exercised without the private routing configuration, which is exactly why the work is parked as draft. No staging deployment or mutation was performed.

This PR will need a rebase after PR #1784 merges. Small conflicts are expected in .github/workflows/ci.yml, package.json, and scripts/quality/README.md.

Validation

• pnpm lint
• pnpm typecheck
• pnpm test — the full run reached 6,799 API tests and had three unrelated timeout-only failures; all affected files passed immediately in isolation (3 files, 125 tests)
• pnpm build
• pnpm quality:scripts:test — 22 files, 237 tests
• pnpm quality:osv-policy
• Focused OSV suite — 5 files, 17 tests
• Formatting, source-contract detection, and git diff --check
• Additional validation run (if applicable)
• Candidate-selection load review: N/A, this PR does not change a sweep/cron/alarm candidate query

Staging Verification (REQUIRED for all code changes — merge-blocking)

• Staging deployment green — intentionally skipped by explicit instruction for this parked draft
• Live app verified via Playwright — N/A; no application UI/runtime surface changed
• Existing workflows confirmed working — N/A; no staging mutation was authorized
• New feature/fix verified on staging — N/A until private routing exists
• Infrastructure verification completed — N/A: no cloud-init, VM agent, DNS, TLS, or provisioning infrastructure changes
• Mobile and desktop verification notes added for UI changes — N/A: no UI changes

Staging Verification Evidence

Intentionally not applicable by Raphaël's explicit instruction. The scheduled workflow cannot complete without the two repository secrets and SAM-side private intake, so staging would not provide valid end-to-end evidence. No staging workflow was triggered and no staging state was mutated.

UI Compliance Checklist (Required for UI changes)

• Mobile-first layout verified — N/A: no UI changes
• Accessibility checks completed — N/A: no UI changes
• Shared UI components used or exception documented — N/A: no UI changes
• Playwright visual audit run locally — N/A: no UI changes

End-to-End Verification (Required for multi-component changes)

• Data flow traced from scheduled entry point to private follow-up request
• Capability test exercises the complete local happy path across scanner and HTTP boundaries
• All source-commit assumptions verified with blob hashes and contract tests
• The real private-intake gap is explicitly documented below

Data Flow Trace

1. .github/workflows/osv-scan.yml starts only from the default-branch schedule, rejects forks, derives the dual-secret routing gate, and invokes pnpm quality:osv-policy.
2. scripts/quality/check-osv-policy.ts:validateOsvPolicy rejects scheduled execution when private routing is absent and validates every ignore's reason and future expiry.
3. .github/workflows/osv-scan.yml downloads OSV-Scanner 2.5.0, verifies osv-scanner_SHA256SUMS, and passes the verified binary path to pnpm quality:osv-advisory.
4. scripts/quality/run-osv-advisory.ts:run invokes the scanner, parses its private temporary report, counts validated findings, and deletes the report in finally.
5. scripts/quality/run-osv-advisory.ts:createPrivateFollowUpRequest builds an authenticated, idempotent summary payload; routePrivateFollowUp rejects redirects and non-2xx responses.
6. scripts/quality/run-osv-advisory.integration.test.ts exercises scanner success, scanner failure, private-intake rejection, privacy minimization, and cleanup with realistic process/HTTP boundary mocks.

Untested Gaps

The actual SAM private webhook intake and repository secrets do not yet exist, so real end-to-end routing is intentionally untested. That is the activation prerequisite keeping this PR in draft; it must be completed before readiness or merge.

Post-Mortem (Required for bug fix PRs)

N/A: this is a source extraction of parked advisory infrastructure, not a bug fix.

Specialist Review Evidence (Required for agent-authored PRs)

• All local reviewers completed and findings addressed before PR creation
• If any reviewer did NOT complete: needs-human-review label added and merge deferred to human — N/A: every reviewer completed

Reviewer	Status	Outcome
task-completion-validator	PASS	Research, checklist, diff, criteria, and vertical slice align; Phase 7 draft lifecycle intentionally pending
security-auditor	PASS	No CRITICAL/HIGH draft blocker; readiness hardening notes retained for the parked work
test-engineer	ADDRESSED	Exact workflow/request assertions and scanner/webhook success plus failure slices added
doc-sync-validator	ADDRESSED	Bounded payload and parked-draft wording corrected
env-validator	PASS	Workflow-only secrets and job-local variables are correctly scoped; no Worker/deploy mapping needed
constitution-validator	PASS	No blocker to draft; private-intake setup docs and configurable buffer remain readiness items

Exceptions (If any)

• Scope: staging deployment, live staging verification, readiness, and merge.
• Rationale: explicit task instruction parks this work until private routing exists and is tested end to end.
• Expiration: when both repository secrets and the SAM-side private intake exist and the branch has been rebased after PR quality: add deterministic runtime-boundary program #1784.

Agent Preflight (Required)

• Preflight completed before code changes

Classification

• external-api-change
• cross-component-change
• business-logic-change
• public-surface-change
• docs-sync-change
• security-sensitive-change
• ui-change
• infra-change

External References

N/A: the task required a faithful extraction from repository commit 5863929ace4e0670aecc767e640c068e35d6a959 and PR #1784; no third-party API contract was changed.

Codebase Impact Analysis

• .github/workflows/ gains the schedule-only advisory workflow and the blocking PR ignore-policy step.
• scripts/quality/ gains the policy, advisory runner, contributor documentation, unit contracts, and scanner-to-webhook vertical slice.
• Root package.json exposes the two quality commands; osv-scanner.toml owns expiring ignore policy.
• No apps/, packages/, database, API, UI, VM, or deployment runtime path changes.

Documentation & Specs

Added scripts/quality/README.md for contributor-facing OSV policy, routing, privacy, and draft activation prerequisites. Public product/self-hosting docs remain intentionally unchanged until the private intake exists.

Constitution & Risk Check

Reviewed Principles XI and XII. The webhook destination/token are configured repository secrets; the scanner version, schedule, workflow timeout, and protocol metadata are deliberate repository/protocol constants. The source-parity 16 MiB child-process buffer and missing self-host private-intake setup documentation remain readiness items, explicitly acceptable only while this PR is parked as draft. Primary risks are premature activation without private routing, public disclosure of advisory detail, and supply-chain compromise; schedule/fork/permission/checksum/privacy/fail-closed tests cover the extraction contract.

[codspeed-hq]

Merging this PR will not alter performance

✅ 6 untouched benchmarks

---

_{Comparing sam/create-separate-draft-pr-sdnbxx (12b68a6) with main (8d6296e)}

[sonarqubecloud]

Quality Gate passed

Issues
3 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