Epic: Remediation — integration & consolidation pass to production-readiness

[kcenon]

What

Tracking epic for the remediation plan produced by a deep analysis and an adversarial re-review of the ad-sdlc codebase. The system has a strong, code-verified core — a single SdkExecutionAdapter execution seam, defense-in-depth security (shell-less execFile + CommandSanitizer, path-traversal defense), a 228-code error taxonomy used across ~151 modules, and an honest test pyramid — but it is not production-ready as-is. The gap is concentrated, not diffuse.

Why

A real end-to-end run currently hits several integration-boundary failures, runtime observability is effectively absent, and the documentation describes a prior generation of the architecture (pre-v0.1-cutover). For a system whose premise is doc-to-code traceability, that drift is audit-relevant. This epic sequences the fixes so the project can credibly claim the production-grade, audit-traceable posture its docs imply.

Scope and phasing

• P0 — boundary correctness (parallel, low blast radius): the defects a first real run will hit.
• P1 — foundation + decisions: unify the divergent SSOT contracts, add enforcement gates, and make the keep-or-kill decision (decision only, no execution).
• P2 — execution + security + dedupe: execute the keep-or-kill dispositions, harden SSRF, reconcile docs, collapse duplicated retry/circuit-breaker engines.
• P3 — depth: V&V enforce-or-demote, resilience/cost, secret masking, test-gap closure.

Critical correction from the re-review (read before any deletion)

The four largest "orphaned" subsystems are NOT dead code — they are part of the published library API via src/index.ts (export * of control-plane / data-plane / agents / utilities into dist/index.d.ts):

• monitoring/ (10,872 LOC) — public via utilities/index.ts:319 export * as Monitoring; the reason the optional @opentelemetry/* peerDeps exist.
• controller/ (8,820 LOC) — public via control-plane/index.ts:64-91 + agents/index.ts:725; worker/ statically imports its types.
• ControlPlane / DataPlane facades (1,672 LOC) — public via src/index.ts:19,24; zero production consumers but live named exports.
• SQLite/Redis scratchpad backends — selectable via BackendFactory.create (case 'sqlite'/'redis'), public via scratchpad/index.ts:168-171, backed by optional peerDeps.

Deleting any is a SemVer-breaking change. The default disposition is therefore extract-to-optional-subpath, gated on the keep-or-kill decision child issue. The deletion gate is "public-export OR run-loop reachability", not run-loop reachability alone.

Children

P0 — boundary correctness (parallel, low blast radius):

• fix(pr-reviewer): gh pr create --json is invalid — PR creation fails on every run #867 — gh pr create --json invalid; PR creation fails every run (PR fix(pr-reviewer): gh pr create no longer passes invalid --json #878, merged)
• fix(cli): --stop-after is inverted and executePipeline discards the built request #868 — --stop-after inverted + executePipeline discards the built request (PR fix(cli): correct --stop-after semantics and honor the built request #879, merged)
• fix(regression-tester): executeTests reports passed without running tests (false-green gate) #869 — regression-tester reports passed without running tests (false-green gate) (PR fix(regression-tester): stop reporting passed without running tests #880, merged)
• fix(orchestrator): --local remaps to non-existent agent files (local-reviewer/local-issue-reader) #870 — --local remaps to non-existent local-reviewer.md / local-issue-reader.md (PR fix(orchestrator): resolve --local agent dispatch targets #881, merged)

P1 — foundation + decision:

• infra(schemas): unify 5 divergent tool/model allowlists into one SSOT + enforcement CI gate #871 — unify 5 divergent tool/model allowlists into one SSOT + enforcement CI gate (incl. dispatch-integrity) (PR infra(schemas): unify tool/model allowlist into one SSOT with conformance enforcement #883, merged)
• docs(ci): doc-vs-code symbol gate + reconcile post-cutover doc drift + consolidate ADR trees #872 — doc-vs-code symbol gate + reconcile post-cutover doc drift + consolidate ADR trees
• fix(scratchpad): route Scratchpad through BackendFactory so sqlite/redis backends are reachable #873 — route Scratchpad through BackendFactory (sqlite/redis reachable) (PR fix(scratchpad): honor configured backend via BackendFactory #882, merged)
• decision: keep-or-kill for orphaned-but-public subsystems (public-API + SemVer) + version reconciliation #874 — DECISION: keep-or-kill for orphaned-but-public subsystems (public-API + SemVer) + version reconciliation (gates P2 execution)

P2 — security + dedupe (execution issues filed after #874):

• security(collector): harden InputParser.fetchUrlContent against SSRF (redirects, metadata IP, IP encodings) #875 — harden InputParser.fetchUrlContent against SSRF (PR security(collector): block SSRF via redirect re-validation and IP-form hardening #884, merged)
• refactor(reliability): collapse 3x retry + 3x circuit-breaker to one canonical each #876 — collapse 3x retry + 3x circuit-breaker to one canonical each

P3 — depth:

• P3: production-hardening — V&V enforce-or-demote, resilience/perf gate, secret masking, e2e de-simulation #877 — production-hardening (V&V enforce-or-demote, resilience/perf gate, secret masking, e2e de-simulation)

Note: WS2 keep-or-kill execution issues (extract-to-subpath / keep-wire / delete per subsystem) are intentionally deferred until #874 records the per-subsystem disposition and the SemVer decision.

Context

• The v0.1 cutover is complete: refactor(orchestrator): 전체 34 stage ExecutionAdapter 경유 (cutover) #797 (route all 34 stages through ExecutionAdapter), chore(agents): AgentBridge / Dispatcher / Registry 삭제 #798 (remove AgentBridge / Dispatcher / Registry), docs(architecture): RFC v0.1 Hybrid Pipeline Architecture 게시 #785 (RFC). This epic addresses the residual drift and boundary defects left by that refactor, plus speculative infrastructure built ahead of its consumers.
• All findings were verified against code at file:line; the adversarial re-review overturned 4 of 6 initial deletion assumptions (see decision: keep-or-kill for orphaned-but-public subsystems (public-API + SemVer) + version reconciliation #874).

Acceptance

• All child issues resolved.
• A real end-to-end run completes (PR creation works, no SSRF, regression gate is honest, --stop-after and --local behave correctly).
• Documentation reconciled to post-cutover reality; CI gates added to prevent re-drift.
• A written keep-or-kill verdict + coordinated version/SemVer decision recorded (decision: keep-or-kill for orphaned-but-public subsystems (public-API + SemVer) + version reconciliation #874).