From dfc09560862e2c231b632781d45c0940187b1562 Mon Sep 17 00:00:00 2001 From: Marius Ciepluch <11855163+norandom@users.noreply.github.com> Date: Wed, 7 Oct 2026 17:30:14 +0200 Subject: [PATCH] docs: frame the proof as prioritization evidence for busy devs [skip ci] Revise the developer guide for engineers with full backlogs and no spare schedule: a vague warning dies in the backlog, so the value of the demonstrated proof is the prioritization conversation -- reproducible evidence (input, behavior, the one-line fix difference) a dev takes to a product owner or the business to win capacity, dropped into the ticket system as a location, repair direction, and reproduction. mcp-shift-left-agent brief: the agent's return should be ticket-ready evidence. Co-Authored-By: Claude Opus 4.8 --- .kiro/specs/mcp-shift-left-agent/brief.md | 6 ++++- docs/pre-push-for-developers.md | 30 ++++++++++++++++++----- 2 files changed, 29 insertions(+), 7 deletions(-) diff --git a/.kiro/specs/mcp-shift-left-agent/brief.md b/.kiro/specs/mcp-shift-left-agent/brief.md index 43aa19b..ddbd762 100644 --- a/.kiro/specs/mcp-shift-left-agent/brief.md +++ b/.kiro/specs/mcp-shift-left-agent/brief.md @@ -48,7 +48,11 @@ and lane-selected. Models and spend caps stay in `.env`. 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. + repair direction, optional proof) and how it decides pass/fail in oversight + mode. The return should be ticket-ready evidence a busy developer can paste + into the issue tracker to win capacity in a prioritization discussion with a + product owner, since a reproducible proof is what moves a security fix out of + the backlog. 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 diff --git a/docs/pre-push-for-developers.md b/docs/pre-push-for-developers.md index ab8d20c..c0b4f79 100644 --- a/docs/pre-push-for-developers.md +++ b/docs/pre-push-for-developers.md @@ -14,12 +14,30 @@ 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. +Your backlog is full and your schedule is not yours. Security findings compete +with feature tickets, and a vague "possible vulnerability" loses that fight every +time: no one gets capacity to chase a maybe. Meanwhile you and your coding agents +ship quickly, and an agent writing code does not pause to audit itself. A +pre-push check is the place to catch a 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. + +## From a finding to capacity + +The point of the proof is the prioritization conversation, not just your terminal. + +A theoretical warning dies in the backlog. A demonstrated proof does not: it is a +reproducible check that triggers the problem on the current code and stops once +the code is fixed. That is the thing you take to a product owner or to the +business when you need capacity. It turns "security thinks this might be a +problem" into "here is the exact input, the exact behavior, and the one-line +difference that stops it," which is something a product owner can weigh against a +feature with real information instead of fear. + +So the output is built to drop into your ticket system as evidence: a location, a +concrete repair direction, and, where the app is runnable, the reproduction +itself. That is what gets a fix scheduled rather than deferred. ## What you do