fall-out-bug · fall-out-bug · Apr 29, 2026
@@ -2,7 +2,7 @@
 
 Get SDP installed in a repo and run the first useful checks.
 
-Audience: CTOs, architects, and developers evaluating SDP as a structured AI PDLC/SDLC harness layer.
+Audience: CTOs, architects, and developers evaluating SDP as a structured AI PDLC/SDLC governance layer.
 
 ## What You Are Installing
 
@@ -19,6 +19,8 @@ It does not ask for model API keys during install. Model/provider setup belongs
 
 The `sdp_lab` repo is the research workspace where SDP is built. You do not need to clone it unless you are contributing to the platform. ChangePassport (`sdp-pr-gate`) and Enterprise Delivery Governance are separate product surfaces — they are product directions, not part of this install.
 
+If your team already has Claude Code, OpenCode, Cursor, Codex, Superpowers, custom prompts, or internal agents, do not start by replacing that workflow. Start with the existing-harness quality gate path: [reference/existing-harness-quality-gate.md](reference/existing-harness-quality-gate.md).
+
 ## Prerequisites
 
 | Requirement | Minimum | Why |
@@ -108,6 +110,7 @@ sdp bootstrap --dry-run --mode brownfield .
 | Path | Use when | Start with |
 |---|---|---|
 | **Toolkit evaluation** | You want to inspect an existing repo and recover useful context. | `scout`, `metrics`, `index`, `spec`, `bootstrap --dry-run` |
+| **Existing harness gate** | You already have an AI coding process and want to know whether it is safe, consistent, and reviewable. | [reference/existing-harness-quality-gate.md](reference/existing-harness-quality-gate.md) |
 | **Local delivery** | You want a lightweight idea-to-change loop in one repo. | `sdp build --dry-run`, then harness-specific commands |
 | **Operator mode** | You need queue-backed delivery, explicit ownership, PR gates, and QA/UAT. | [reference/canonical-happy-path.md](reference/canonical-happy-path.md) |
 | **MCP integration** | You want an AI harness to call SDP tools directly. | [reference/installation.md](reference/installation.md) |
@@ -168,6 +171,7 @@ sdp doctor adapters
 Be honest in pilots:
 
 - SDP is not a replacement for code review.
+- SDP does not require replacing an existing AI coding harness before producing useful evidence.
 - SDP does not guarantee compliance.
 - Policy enforcement is advisory by default unless configured otherwise.
 - Native Windows is not supported in v1.

@@ -0,0 +1,121 @@
+# Existing Harness Quality Gate
+
+Status: product adoption reference
+Updated: 2026-04-29
+Related workstream: `00-152-03`
+
+Use this path when a team already has an AI coding workflow and wants to know whether quality is degrading.
+
+This is the right starting point for teams that already use Claude Code, OpenCode, Cursor, Codex, Superpowers, custom prompts, or an internal agent harness. Do not ask these teams to replace their harness before SDP proves value.
+
+## Positioning
+
+SDP can be introduced as a governance and evidence layer around an existing harness.
+
+The first promise is not "use our whole workflow". The first promise is:
+
+> Keep your current AI coding workflow, then use SDP to make its scope, evidence, findings, and readiness decisions reviewable.
+
+This is narrower than Operator Mode and more concrete than a generic repository audit. It is the low-friction path toward `sdp-pr-gate` / ChangePassport.
+
+## When To Use This Path
+
+Use it when:
+
+- the repo already has `AGENTS.md`, prompts, skills, or harness-specific setup
+- developers have already been trained on a local process
+- the organization worries about AI-assisted code quality, review burden, or process drift
+- a full harness migration would create adoption risk
+- the buyer wants a controlled pilot before changing team workflow
+
+Do not use it as the first path when:
+
+- the repo has no agent process and the team wants SDP to bootstrap one
+- the team is ready for Beads-backed Operator Mode from the start
+- the main need is only repo comprehension, where `scout`, `metrics`, `index`, and `spec` are enough
+
+## Adoption Sequence
+
+1. Inventory the existing harness.
+
+   Identify where prompts, skills, commands, repo rules, and generated adapter files live. Treat these as installed process, not clutter to overwrite.
+
+2. Run read-only repo inspection.
+
+   Start with `scout`, `metrics`, `index`, and `spec`. The output should establish repo shape and risk signals before any generated files are written.
+
+3. Define the gate boundary.
+
+   Decide what the gate evaluates: a PR, a feature branch, a module, a service inside a monorepo, or a whole repo. For monorepos, prefer scoped service/module assessment over root-level generic assessment.
+
+4. Require evidence-backed findings.
+
+   Findings must cite inspected files, commands, checks, or source artifacts. Use `not_assessed` when the evidence is missing instead of filling gaps with model judgment.
+
+5. Decide before migration.
+
+   Only after the gate produces useful decisions should the team consider adopting more SDP workflow: bootstrap, Operator Mode, Beads, workstreams, or full delivery orchestration.
+
+## Output Contract
+
+A useful gate output should separate facts from judgment.
+
+Minimum fields:
+
+| Field | Requirement |
+|---|---|
+| Scope | What repo, branch, PR, service, or module was assessed |
+| Inputs | PR diff, issue, workstream, evidence bundle, commands, or repo paths |
+| Evidence | Files read, commands run, tests observed, CI data, review comments |
+| Findings | Each finding has severity, source, evidence, and confidence |
+| Verdict | `pass`, `warn`, `fail`, or `not_assessed` |
+| Rubric | How the verdict was computed |
+| Overrides | Human override reason and owner, when used |
+
+Avoid single opaque health scores. If a score is shown, it must be derived from an explicit rubric and every component must be explainable.
+
+## Skill And Tool Routing
+
+Use task language, not internal skill names, in user-facing docs.
+
+| User intent | SDP route |
+|---|---|
+| "What is in this repo?" | `sdp scout`, then `sdp index` |
+| "Where are the process risks?" | `sdp metrics` |
+| "What implicit contracts does the code contain?" | `sdp spec` |
+| "Can my existing harness be trusted?" | existing-harness quality gate path |
+| "Is this PR ready?" | `sdp-pr-gate` / ChangePassport direction |
+| "Run a governed delivery loop" | Operator Mode |
+
+Do not make evaluators choose `reality`, `review`, or other internal skills by guessing. Skills are implementation details unless the user is already contributing to SDP.
+
+## Monorepo And JVM/Bazel Caveat
+
+For JVM/Kotlin/Bazel monorepos, generic language detection is not enough. Assessment docs and tools should require an explicit scoped target when automatic detection is weak.
+
+Good input:
+
+```text
+Assess service //payments/api in this monorepo.
+Language: Kotlin.
+Build: Bazel.
+Do not infer Maven or Gradle conventions unless files prove them.
+```
+
+Bad output:
+
+- applying Java-only idioms to Kotlin without saying so
+- falling from `Mixed` to `Unknown` and still publishing strong architecture findings
+- claiming files were missing without showing search/read evidence
+- rating repository health without showing the formula
+
+## Relationship To Product Surfaces
+
+This path uses the stable Toolkit for read-only inspection and points toward the future `sdp-pr-gate` product surface.
+
+It does not mean ChangePassport is GA today. It means the docs should make the migration path legible:
+
+1. read-only inspection
+2. evidence-backed quality gate over the existing harness
+3. PR readiness packet / ChangePassport when schema and pilot gates are ready
+4. Operator Mode only when the team wants SDP to own the delivery workflow
@@ -25,6 +25,8 @@ More precise version:
 
 SDP is not trying to be a better IDE or a black-box AI software engineer. Codex, Claude Code, Cursor, Copilot, OpenCode, and other harnesses can own execution UX. SDP owns the delivery contract around that execution.
 
+For teams that already have an agent workflow, the first SDP pitch should be a quality gate, not a harness replacement. Keep the existing harness, then use SDP to make scope, evidence, findings, and readiness decisions reviewable. See [existing-harness-quality-gate.md](existing-harness-quality-gate.md).
+
 ## Product Layers (F150 memo v3)
 
 | # | Layer | Kind | Status | First commercial role |
@@ -256,6 +258,22 @@ Current SDP building blocks:
 
 Current limitation: the stable "ChangePassport" packet is a product direction, not yet the default public CLI.
 
+### 5. Gate An Existing Harness
+
+Use this when the business problem is controlled adoption of AI coding across a team that already has prompts, skills, `AGENTS.md`, or a harness-specific workflow.
+
+Default sequence:
+
+1. inventory the installed harness surface
+2. run read-only Toolkit inspection
+3. define a scoped gate boundary: PR, service, module, or repo
+4. emit evidence-backed findings with `pass`, `warn`, `fail`, or `not_assessed`
+5. decide whether any SDP workflow migration is justified
+
+This path is the lowest-friction bridge from Toolkit evaluation to `sdp-pr-gate` / ChangePassport. It should not require Operator Mode or Beads on day one.
+
+Canonical doc: [existing-harness-quality-gate.md](existing-harness-quality-gate.md)
+
 ## Formula Install Surface
 
 The default Homebrew formula installs the `sdp` binary. It does NOT install:
@@ -273,6 +291,7 @@ Exclusion mechanism: GoReleaser allowlist (`.goreleaser.yml`). Build tags (`sdp_
 Do not claim that SDP:
 
 - replaces code review
+- requires teams to replace their existing AI harness before seeing value
 - guarantees compliance
 - is a complete autonomous software engineer
 - has market-grade IDE UX

@@ -29,6 +29,8 @@ Do not use this doc as your main onboarding path if your real goal is:
 
 For that path, go straight to [../QUICKSTART.md](../QUICKSTART.md). Today that quickstart covers `Claude Code`, `OpenCode`, `Codex`, and `Cursor`.
 
+If your team already has an AI coding harness and wants governance without a migration, start with [existing-harness-quality-gate.md](existing-harness-quality-gate.md). That path treats SDP as an evidence and readiness gate around existing prompts, skills, agents, and PR workflow.
+
 ## Main Components
 
 | Area | What it owns |
@@ -81,6 +83,7 @@ Use one source per question.
 | What repo owns this file? | [docs/MULTI-REPO-WORKFLOW.md](../MULTI-REPO-WORKFLOW.md) |
 | What belongs in `sdp_lab` vs `sdp`? | [docs/architecture/REPO-BOUNDARY.md](../architecture/REPO-BOUNDARY.md) |
 | How do I adopt SDP in another repo? | [../QUICKSTART.md](../QUICKSTART.md) |
+| How do I use SDP without replacing my current harness? | [existing-harness-quality-gate.md](existing-harness-quality-gate.md) |
 | What is the canonical happy path from intake to delivery? | [canonical-happy-path.md](canonical-happy-path.md) |
 | What is the canonical operator loop? | [canonical-happy-path.md](canonical-happy-path.md), [docs/SDP_OPERATOR_WORKFLOW.md](../SDP_OPERATOR_WORKFLOW.md) |
 | What agents and skills are on the happy path? | [agent-catalog.md](agent-catalog.md), [skills.md](skills.md) |
@@ -141,8 +144,9 @@ If you are new to this repo, read in this order:
 If you are new to SDP but not to this repo, use this shorter decision:
 
 1. "I want to use SDP in my own repo" -> [../QUICKSTART.md](../QUICKSTART.md)
-2. "I want to work on SDP platform internals" -> keep reading this file
-3. "I am a dev agent entering cold" -> [../../AGENTS.md](../../AGENTS.md), then this file
+2. "I already have a harness and want quality gates" -> [existing-harness-quality-gate.md](existing-harness-quality-gate.md)
+3. "I want to work on SDP platform internals" -> keep reading this file
+4. "I am a dev agent entering cold" -> [../../AGENTS.md](../../AGENTS.md), then this file
 
 If you are touching protocol artifacts in `sdp/`, read these before changing anything:
 

@@ -114,6 +114,7 @@ Post-F150 v3 lane (post-IIP-council, 2026-04-27) — see [docs/roadmap/2026-04-2
 - `F158` — Go Import-Path Contamination Decision (highest unaddressed structural risk; blocks F156 / F157 active status)
 - `F159` — Competitive Positioning Artifact (vs Copilot Workspace, CodeRabbit, GitLab Duo, Tabnine, Factory)
 - `F160` — Procurement / Compliance Install Profile (SOC2 stance, SLA template, no-egress mode)
+- `F161` — `sdp pi-review`: Pi-backed review contracts, scoped working-tree context, model synthesis, verdict/telemetry integration
 
 Deferred (no work until ICP signal): Enterprise Delivery Governance product family; Russian sovereign model adapters (sub-track of EDG); `sdp-pr-gate` implementation track (gated on committed pilot per Wedge B gate).
 

@@ -0,0 +1,101 @@
+# 2026-04-29 Discovery Interview: DevOps Architecture Lead
+
+Status: source evidence for F152-03
+Source: [Fireflies transcript `01KQCW4BZS014BHVR7NB9J44X3`](https://app.fireflies.ai/view/01KQCW4BZS014BHVR7NB9J44X3)
+Workstream: `00-152-03`
+Bead: `sdplab-qnyr.3`
+
+## Context
+
+The participant tested SDP against a key internal monorepo and reported feedback from the perspective of a DevOps architecture lead responsible for organization-wide developer infrastructure.
+
+The test environment is commercially useful because it matches the hard version of the target problem:
+
+- team-level and cross-team AI development process is being piloted
+- existing harness/process work already exists
+- repo shape is not a simple open-source demo project
+- buyer concern is controlled adoption, not raw agent speed
+
+## Repo And Tooling Setup
+
+- Monorepo with Kotlin and Java services.
+- Bazel build, not Maven or Gradle.
+- Internal model gateway through LiteLLM.
+- Tested with internal Qwen-family models and Minimax 2.5-class model access.
+- Evaluation started from "can SDP assess code quality?", then discovered SDP is broader than assessment.
+
+## What Failed
+
+### Project Detection
+
+SDP did not handle the target repo shape cleanly. JVM/Bazel/Kotlin was treated too much like generic Java or fell through `Mixed` / `Unknown` style heuristics. This caused weak downstream findings because language and build assumptions were wrong.
+
+### Evidence Depth
+
+Some runs produced surface metrics without enough file reads. A quality report that mainly counts files/classes/lines is not credible for a CTO unless it shows what it inspected and where the claims came from.
+
+### Score Trust
+
+Opaque health scores were not trusted. The participant explicitly objected to a score where the formula is unclear and reads like unsupported LLM judgment rather than a defensible assessment.
+
+### Finding Consistency
+
+Some findings appeared internally inconsistent, for example treating test volume as both healthy coverage and a performance risk without a clear rubric separating the two claims.
+
+### Skill Routing
+
+The evaluator selected `reality` because it looked closest to the need. That is a product UX issue: users should not need to understand the internal skill catalog to choose between repository mapping, quality assessment, feature review, and full delivery adoption.
+
+## Strongest Product Signal
+
+The strongest signal is not "support Bazel better", though that is real. The stronger signal is:
+
+> Buyers already have agent workflows. They want SDP to validate and control those workflows before they consider replacing them.
+
+The participant's core question was whether SDP can be applied to an existing harness as a quality gate. Requiring a full SDP harness migration first would create too much adoption risk.
+
+## Buyer Language
+
+Use this language in product docs:
+
+- "Apply SDP as a quality gate over your existing harness."
+- "Assess whether AI-assisted delivery is degrading quality."
+- "Show evidence, scope, and decision records before asking teams to change their workflow."
+- "Start with a read-only assessment path; migrate only where the evidence justifies it."
+
+Avoid this as the first message:
+
+- "Replace your current harness with SDP."
+- "Run the whole Operator Mode loop before you see value."
+- "Trust a health score without traceable evidence."
+
+## Pricing And Pilot Implications
+
+This interview supports the `sdp-pr-gate` / ChangePassport wedge more than an Operator Mode-first sale.
+
+Likely willingness-to-pay anchor:
+
+- reduced review and governance burden for AI-assisted PRs
+- reduced risk of quality degradation across teams
+- lower cost of standardizing agent practices across repos
+
+Open commercial questions for the remaining F152 interviews:
+
+- How many AI-assisted PRs per week create enough pain to pay?
+- Who owns the budget: CTO, platform engineering, DevOps, or engineering managers?
+- Is the first paid object a PR gate, a repo assessment, or a team process audit?
+- What level of false-block rate is tolerable before developers bypass the gate?
+
+## Product Follow-Ups
+
+These are not F152 implementation scope, but they should feed the roadmap:
+
+- Define a first-class "existing harness quality gate" path in docs.
+- Make evidence-backed assessment output explicit: `pass`, `warn`, `fail`, `not_assessed`.
+- Replace opaque health score language with a rubric and evidence links.
+- Add JVM/Kotlin/Bazel detection to assessment/scout paths.
+- Add a skill/task decision tree so users do not route themselves into `reality` by guessing.
+
+## F152 Signal
+
+This counts as one target-ICP discovery input, but it does not complete F152-03. It validates a major objection: customers may not accept a harness replacement pitch, but they are interested in an SDP gate that sits on top of what they already use.