docs: developer-facing pre-push security guide + mcp-shift-left-agent brief [skip ci]

docs/pre-push-for-developers.md: COBESY-structured guide for engineers who are
strong at dev but not security. Leads with the conclusion (zero-setup, no
annotations, diff-scoped, proof-backed), frames the agent-era case (a pre-push
check is how you oversee coding agents), states control (advisory vs blocking,
budget, lane, models), and is honest about limits with an explicit disproof
condition (coverage, large-repo latency, generalization being measured by G0).

.kiro/specs/mcp-shift-left-agent/: follow-up brief for an MCP agent + skills that
give devs and coding agents early shift-left feedback and a required pre-push
security step for agent oversight; builds on the existing ousast mcp server;
sequenced after the safety net is qualified.

Co-Authored-By: Claude Opus 4.8 <[email protected]>

.kiro/specs/mcp-shift-left-agent/brief.md

@@ -0,0 +1,63 @@
+# Brief: MCP shift-left agent + skills
+
+Status: brief / not yet specced. Proposed 2026-10-07. Delivery surface for the
+qualified safety net; builds on the existing `ousast mcp` server and the product
+skills. Related: `proof-arm-opencode` (the proof model), `pre-push-safety-net`
+(the gate), `unseen-repo-evaluation` (the qualification).
+
+## Motivation
+
+The pre-push hook is the gate. Developers and their coding agents want the same
+security feedback **earlier**, while the code is still being written, not only at
+push. And in an agent-driven workflow, a mandatory security check is how a human
+oversees agents: the agent's output has to clear it before it ships.
+
+Proposal: expose the safety net through an MCP agent and a small set of skills so
+an editor or a coding agent can ask for a security read of the changed code on
+demand, shift-left, and so a coding agent can be required to pass it before it
+proposes a push.
+
+## Shape
+
+- **Transport:** extend the existing narrow MCP server (`ousast mcp`, stdio) that
+  OpenCode and other agents already speak. No new network surface; same
+  no-secret, bounded contract.
+- **What the agent offers:**
+  1. Scan the current diff with the static arm (fast, no model, no cluster) and
+     return findings scoped to the change, with location and a concrete repair
+     direction, not a confidence label.
+  2. Triage a finding: explain it in plain terms and whether it is reachable.
+  3. Prove on demand: hand the top candidate to the proof arm when a runnable
+     harness exists, and return the demonstrated proof-of-concept.
+- **Skills:** the existing `openultrasast-scan` and `openultrasast-triage`
+  product skills, plus shift-left additions (scan-the-diff, explain-a-finding,
+  suggest-a-fix-direction) that a coding agent invokes mid-task.
+- **Oversight mode:** a coding agent can be configured to call the scan as a
+  required step before it finalizes a change, so security review is automatic
+  rather than remembered.
+
+## Control (same model as the hook)
+
+Advisory by default; blocking is opt-in. Budget and a push/call deadline bound
+the work. The inline path runs the fast static arm only; heavy proof is explicit
+and lane-selected. Models and spend caps stay in `.env`.
+
+## Open questions for the spec
+
+1. Inline latency budget: in-editor feedback must return in seconds, so the
+   static arm must be fast on a single diff. What is the time contract, and does
+   the large-repo latency problem block it?
+2. Return contract: exactly what a coding agent gets back (findings, locations,
+   repair direction, optional proof) and how it decides pass/fail in oversight mode.
+3. Does oversight mode need a signed/attestable result so a reviewer can trust
+   that the agent actually ran the check?
+4. Reuse: the `ousast mcp` tool set already exists; which tools are enough and
+   what is genuinely new.
+
+## Scope and sequencing
+
+This is a delivery and adoption surface, correctly **after** the safety net is
+qualified on unseen repositories (G0 through G5). It is not a detection change;
+it is how developers and agents consume the detection early. The proof model
+improvement lives in `proof-arm-opencode`; this brief is the dev- and
+agent-facing feedback channel.

.kiro/specs/mcp-shift-left-agent/spec.json

@@ -0,0 +1,10 @@
+{
+  "feature_name": "mcp-shift-left-agent",
+  "created_at": "2026-10-07T15:10:00Z",
+  "updated_at": "2026-10-07T15:10:00Z",
+  "language": "en",
+  "phase": "brief",
+  "approvals": {"requirements": {"generated": false, "approved": false}, "design": {"generated": false, "approved": false}, "tasks": {"generated": false, "approved": false}},
+  "ready_for_implementation": false,
+  "summary": "MCP agent + skills so developers and coding agents get the safety net's feedback early (shift-left, in-editor) and so a coding agent can be required to pass a security check before it ships. Delivery surface after G0-G5 qualification; builds on the existing ousast mcp server."
+}

docs/pre-push-for-developers.md

@@ -0,0 +1,70 @@
+# Pre-push security for developers
+
+You push code. This checks it for security regressions first. You do not annotate
+anything, you do not need a security background, and you do not change how you work.
+
+## The short version
+
+Install a git pre-push hook once. On every push it reads the code you changed,
+compares it against the known risks of the frameworks you already use, and warns
+you before the push leaves your machine. Where it can build and run your app, it
+goes further and proves an issue with a demonstration: a check that triggers the
+problem on your change and stops triggering once the problem is fixed. By default
+it only advises; it never blocks until you turn blocking on.
+
+## Why this matters now
+
+You and your coding agents ship quickly. Security is not most engineers' day job,
+and an agent writing code does not pause to audit itself. A pre-push check is the
+place to catch a security regression that you, or an agent acting for you,
+introduced, before it reaches the remote. In an agent-driven workflow it is the
+oversight step: the gate that reviews what the agent wrote, every push, without
+you having to become the security reviewer.
+
+## What you do
+
+1. Install the hook in a repo: `ousast pre-push install`.
+2. Push normally. Findings print at push time.
+3. Optionally set model keys and a spend cap in `.env`; nothing else is required.
+
+No code annotations. No markup. No per-project security config.
+
+## How it decides, without annotations
+
+- **The tool brings the security knowledge.** It ships framework facts: the
+  sources, sinks, sanitizers, and guards for common frameworks. Your code does
+  not declare any of this.
+- **It looks only at your change.** It builds a graph of the changed code and
+  checks it against those framework facts, scoped to the diff, not the whole repo.
+- **It can prove, not just warn.** When the app is runnable, the proof arm builds
+  and runs it and demonstrates the issue by execution, so a finding is a
+  reproducible fact, not a confidence score.
+
+## What you control
+
+- **Advisory or blocking.** Advisory by default; `OUSAST_PUSH_MODE=blocking`
+  turns it into a gate. Adopt in advisory mode, build trust, then block.
+- **Budget and deadline.** One budget covers the whole push; if it runs out you
+  get an honest "incomplete coverage" notice, never a made-up verdict.
+- **Where proof runs.** Local sandbox, a container, or a shared cluster.
+- **Models and spend.** Keys and caps live in `.env`.
+
+## Honest limits
+
+- **Coverage follows support.** It helps where the tool has framework facts and a
+  language grammar; outside that it is weak, and third-party or vendor code is not
+  analyzed.
+- **Large repositories can be slow.** On big codebases the deep analysis can
+  exceed a comfortable push deadline today; that is an open engineering problem.
+- **Generalization is being measured, not asserted.** Whether it reliably catches
+  real regressions and stays quiet on ordinary changes in repositories it has
+  never seen is under active measurement. We consider the tool wrong if it misses
+  real regressions or alarms on ordinary changes on unseen repositories, and that
+  is exactly the catch-rate and false-alarm number the unseen-repo evaluation is
+  producing now. Treat the advisory output accordingly until that number exists.
+
+## Where this is going
+
+An MCP agent and skills so your editor or your coding agent gets the same check
+earlier, inline, before the push, so feedback arrives while you are still writing
+rather than at the gate. See the follow-up spec `mcp-shift-left-agent`.