WhyC — Master Plan v4 (PDD on Runtime · Mechanically Gated · 90%+ Winning Target)¶

Status: 📋 Final execution plan v4, awaiting operator G1/G3/G4 verification. Authored: 2026-05-11 Authors: Two Weeks Team (Sejun Kim, ComBba) Hackathon: Google Cloud Rapid Agent Hackathon · Arize Track Submission deadline: 2026-06-11 14:00 PT · D-31 Credit redemption deadline: 2026-06-04 · D-24

v4 supersedes v3 (master-plan-v3.md). v3 remains as the verification baseline; v4 adds the mechanically gated runtime — the architectural layer that takes our Preview-Driven Development methodology from "design-phase artifact" to "runtime contract every stage transition is forced to honor." The composition is our own, refined from operating the PreviewForge plugin that produced this very run.

0. Executive Summary¶

WhyC v4 is a mechanically gated multi-agent panel built on the Preview-Driven Development methodology we developed in our PreviewForge plugin. Three things together that the hackathon gallery will not see anywhere else:

1. PDD on runtime — 13 sub-agents adjudicate analyze / develop / judge with structured I2 diversity validation. Same pattern that runs PreviewForge's design phase, ported into the production pipeline.
2. Mechanical gate layer — every stage transition is enforced by hook scripts (bash + stdlib Python, zero runtime deps). Schema-validate, provenance-record, manifest-SHA-256, budget-check, category-gate. No agent can skip the contract by writing a clever prompt.
3. Google Cloud × Arize Phoenix integration depth — 9 GCP services × 5 Phoenix features in active use, including Agent Engine deployment, Vertex AI Evaluation, BigQuery learning loop, Phoenix Evals as the judge layer, MCP self-introspection.

Plus the receipts-tone satire that gives the project memorable brand.

Projected score: 91–97 / 100 (Stage-2). Target top-3 in Arize track at ~90% probability.

1. KPI Dashboard¶

2. Methodology — PDD on Runtime¶

2.1 PDD origin¶

We developed Preview-Driven Development in our PreviewForge plugin. The methodology has six signature patterns:

multi-perspective generation  (N advocates with different biases)
  → diversity validation       (I2: detect near-duplicates, force regen)
  → cross-perspective tally    (panel votes, meta-tally across axes)
  → mitigation transformation  (dissent → concrete action items)
  → SHA-256 freeze             (artifacts locked, audit-replayable)
  → hooked transitions         (every gate enforced as a script, not a prompt)

The first five are the design-phase methodology that produced this very project's v1 spec (PreviewDD → SpecDD → Engineering Scaffold). The sixth is what v4 promotes from a plugin-internal convention into the WhyC runtime itself.

2.2 The insight we are running with¶

While operating PreviewForge through this hackathon's design phase, one pattern repeatedly saved us: policy enforcement that lives in shell scripts and refuses to negotiate via prompt-engineering. Examples we lived through:

• The factory-policy.py hook refused our write to runs/<id>/mitigations.json because the active agent's role wasn't supervisor. No amount of clever prompting would have bypassed it — we had to set PF_WRITER_ROLE=supervisor explicitly. (See commit 1b987de, 60cd6c6.)
• The idea-drift-detector hook would have aborted our generation if any advocate had wandered too far from chosen_preview.json. This was the mechanism that kept 26 advocates anchored on the same product hypothesis.
• The SpecDD SHA-256 lock at _lock.json made the spec a frozen contract that no engineer agent could quietly mutate later (see 0e6371e).

The lesson is general: multi-agent systems need mechanical gates at every transition, or the diversity that makes them useful becomes the chaos that makes them unreliable. Prompts are persuasion; scripts are enforcement.

WhyC v4 brings this lesson into the runtime pipeline.

2.3 What v4 changes vs v3¶

The right-column patterns are general engineering practice (pre-commit hooks, CI policy gates, build manifests) — applied here to the agent runtime, not the developer machine.

3. The Hook Layer (mechanical enforcement, new in v4)¶

3.1 Hook flow around every stage¶

                  ┌─────────────────────────────┐
                  │  pre-stage hook             │
                  │  ─────────────────────────  │
                  │  ▶ schema-validate INPUT    │
                  │  ▶ check ceiling budget     │
                  │  ▶ check retry remainder    │
                  │  ▶ verify provenance trail  │
                  └─────────────┬───────────────┘
                                ▼  refuse → abort or downgrade
                  ┌─────────────────────────────┐
                  │  STAGE BODY                 │
                  │  (multi-agent / pure / IO)  │
                  └─────────────┬───────────────┘
                                ▼
                  ┌─────────────────────────────┐
                  │  post-stage hook            │
                  │  ─────────────────────────  │
                  │  ▶ schema-validate OUTPUT   │
                  │  ▶ record provenance        │
                  │  ▶ update memory files      │
                  │  ▶ category gates           │
                  │     (security/perf/a11y)    │
                  │  ▶ SHA-256 manifest line    │
                  └─────────────┬───────────────┘
                                ▼  refuse → retry or escalate
                       next stage allowed

3.2 Hook scripts (under hooks/)¶

All hooks are bash or stdlib Python — zero runtime dependencies. Judges grep hooks/, they see scripts. No vendor lock-in, no hidden behavior.

3.3 Per-run memory files (correlation-ID linked)¶

These three files are what makes the run replayable. A judge with the repo can read them and reconstruct exactly what happened, in order, with every decision's reasoning visible.

3.4 Why this matters to scoring¶

Three concrete advantages a judge can verify:

1. Mechanical contract: hooks are visible in hooks/, not buried in TypeScript prompts. Reviewers grep, see scripts.
2. Reproducibility: every run produces a manifest. Re-runs produce matching manifests → "Build & Bundle" review pass.
3. Audit trail: every hook execution leaves a correlated row in patterns.md. Phoenix MCP introspection (Stage 6) can also read these.

Estimated lift: +2-3 pts on Tech Implementation axis (rigor narrative lands).

3.5 Where v4 sits in the 2026 multi-agent landscape¶

The combination — ADK tree organization + PDD adjudication + hook-enforced transitions — is original to WhyC. None of the named frameworks combines all three.

4. Architecture (v4 final, with hook layer)¶

┌───────────────────────────────────────────────────────────────────────────────┐
│                          WhyC v4 Pipeline (mechanically gated)                │
├───────────────────────────────────────────────────────────────────────────────┤
│  Stage 0  pre-flight                                                          │
│           [pre-hook: URL allow-list + content_sha256 dedup]                   │
│           URL fetch · M5 sanitize · @arizeai/phoenix-otel auto-trace          │
│           [post-hook: SanitizedInput schema-valid · manifest line written]    │
├───────────────────────────────────────────────────────────────────────────────┤
│  Stage 1  multi-analyzer                                                      │
│           [pre-hook: contract loaded · budget headroom verified]              │
│           3 Gemini Flash advocates × persona → I2 dedup → 1 Pro synth         │
│           Phoenix Datasets log · Phoenix Prompts versioning                   │
│           [post-hook: ProductSpec._provenance present · 9 fields filled]      │
├───────────────────────────────────────────────────────────────────────────────┤
│  Stage 2  go/no-go                                                            │
│           [pre-hook: ProductSpec.constraints non-null]                        │
│           6 rules + Vertex AI Evaluation IP-safety                            │
│           [post-hook: decision shape valid · NoGoReason mapped if applicable] │
├───────────────────────────────────────────────────────────────────────────────┤
│  Stage 3  multi-developer                                                     │
│           [pre-hook: prior manifest SHA-256 if regen · budget for 5 Pro]      │
│           5 Gemini Pro × persona → I2 structural dedup → cross-pick winner    │
│           Loser manifests retained · Phoenix Experiments advocate A/B         │
│           [post-hook: winner manifest SHA-256 recorded · provenance complete] │
├───────────────────────────────────────────────────────────────────────────────┤
│  Stage 4  deploy (real)                                                       │
│           [pre-deploy hook: manifest SHA-256 matches Stage 3 output]          │
│           Cloud Build → Artifact Registry → Cloud Run service                 │
│           ALSO: pipeline-kickoff registered as Vertex AI Agent Engine entity  │
│           Cloud Armor injects X-Robots-Tag                                    │
│           [post-hook: deploy_url HTTP 200 health probe · 24h TTL set]         │
├───────────────────────────────────────────────────────────────────────────────┤
│  Stage 5  5-critic judge panel                                                │
│           [pre-hook: deploy_url accessible · judge_prompt_version pinned]     │
│           5 Gemini Pro critics via @arizeai/phoenix-evals                     │
│           Meta-tally weighted; spec_fit closed-form drift assert              │
│           [post-hook: weights immutable check · per-critic verdict stored]    │
│           [category-gate-security.py: if any critic raises sec flag → escal.] │
├───────────────────────────────────────────────────────────────────────────────┤
│  Stage 6  Phoenix MCP introspection                                           │
│           [pre-hook: trace_ids collected from Stage 5 verdicts]               │
│           @arizeai/phoenix-client getSpans({ traceIds }) + Experiments        │
│           Marker: whyc.mcp.self_query=true (visible in trace tree)            │
│           [post-hook: TraceSummary populated · phoenix_console_url stored]    │
├───────────────────────────────────────────────────────────────────────────────┤
│  Stage 7  self-improve + BigQuery learning                                    │
│           [pre-hook: 3 signals available (judge + trace + bq)]                │
│           decideNext(judge, trace, learning) → LoopDecision                   │
│           BigQuery whyc_learning.run_outcomes insert on terminate             │
│           [post-hook: on-converge.py | on-fail.py | on-cost-ceiling.py]       │
└───────────────────────────────────────────────────────────────────────────────┘

5. v4 Implementation phases (Locked Sequence)¶

v3's 11 phases remain. v4 adds Phase 0.5 (hook layer foundation) and lifts hook integration into every subsequent phase. Total: 12 phases · 33 commits · 31 days.

Phase 0.5 — Hook layer foundation (NEW in v4, D-31 → D-30 · 0.5 day)¶

Build/test gate: hooks invoked manually on placeholder data exit 0; agents/v4-index.json valid JSON; memory files write atomically.

Phase 1 — Foundation + dep adoption (D-31 → D-29 · 1 day)¶

Identical to v3 Phase 1 plus hook integration:

1. chore(deps): adopt @arizeai/phoenix-{client,otel,evals,mcp} — pnpm install
2. fix(gemini): correct Gemini 2.5 pricing constants — closes G-COST-1
3. feat(eval): create sanitizer_fixtures — closes G-CI
4. feat(jobs): util/retry.ts retry-with-budget framework — invokes on-fail.py hook
5. feat(jobs): util/bigquery-learning.ts — invokes on-converge.py hook
6. feat(jobs): pipeline/types.ts v2 contracts extension

Phase 2 — Stage 1 multi-analyzer (D-29 → D-27 · 1 day)¶

7. feat(pipeline): analyze-v2 wrapped by pre/post-stage hooks (~280 LOC)

Phase 3 — Stage 3 multi-developer (D-27 → D-25 · 1.5 days)¶

8. feat(pipeline): develop-v2 wrapped by hooks + manifest write (~380 LOC)

Phase 4 — Stage 5 multi-critic (D-25 → D-23 · 1 day)¶

9. feat(pipeline): judge-v2 via @arizeai/phoenix-evals + category-gate-security (~310 LOC)

Phase 5 — Stage 6 + Stage 7 (D-23 → D-21 · 0.75 day)¶

10. feat(pipeline): introspect-v2 + self-improve-v2 + on-converge hook wiring

Phase 6 — Stage 4 real deploy + Agent Engine registration (D-21 → D-17 · 2 days, GCP-dependent)¶

11. feat(pipeline): deploy-v2 with Cloud Build + Cloud Run + pre-deploy hook
12. feat(infra): Vertex AI Agent Engine deployment manifest — closes G-R5

Phase 7 — Stage 2 Vertex AI Eval (D-17 → D-16 · 0.5 day)¶

13. feat(pipeline): go-no-go-v2 with Vertex AI Evaluation Service

Phase 8 — Kickoff orchestrator v2 (D-16 → D-14 · 1 day)¶

14. feat(jobs): pipeline-kickoff-v2 wires all v2 stages + hook layer + dry-run test

Phase 9 — Data + scrape + verify (D-14 → D-10 · 2 days, operator)¶

15. feat(jobs): scrape-yc.ts implementation — robots.txt honored
16. Operator runs 7-check verification per docs/dataset-verification.md for 12 companies
17. chore: replace prisma/seed.ts placeholders with verified data
18. Re-run pipeline → 12 entries populate BigQuery

Phase 10 — Polish + video + Devpost (D-10 → D-3 · 4 days, operator)¶

19. Record 3-min receipts-tone video (script in §11), upload YouTube with EN subtitles
20. README badges + ≥3 screenshots + live demo button
21. Devpost: 7 sections, Built With tags, live URL, video link, repo URL
22. Final rehearsal

Phase 11 — Final submission (D-3 → D-0)¶

23. Submit by D-1 (2026-06-10) with 1-hour buffer
24. Verify all required fields complete
25. Monitor 24 h post-submit

6. Hackathon Rule Compliance Matrix (v4-current)¶

7. Cost Plan (v4)¶

Identical to v3 since hooks add zero LLM cost.

Hook scripts run on Cloud Run-job's existing instance — $0 marginal.

8. Phoenix integration depth (v4)¶

Five surfaces in active use, not just trace export. v4 makes the judge layer itself a Phoenix Evals integration — that's the Arize-track scoring criterion at its deepest.

9. GCP feature inventory (v4)¶

9 GCP services × 5 Phoenix features = integration breadth no other 2-person hackathon team will match.

10. Scoring Projection (v4)¶

10.1 Per-axis targets¶

10.2 Why each axis lifts¶

Tech Implementation +1: 7 hook points are concrete, scriptable, judge-readable. Most submissions ship "agent calls LLM in a loop." We ship "agent calls LLM in a loop wrapped by mechanically enforced pre/post hook contracts." Difference is grep-visible in hooks/.

Potential Impact +1: The hook-gated pattern generalizes far beyond YC-cloning. Any team building multi-agent systems faces the same diversity-vs-chaos tradeoff and benefits from runtime gates. v4's contribution is a generalizable architectural decision, not just a project.

Quality of Idea +1: Three components compose into something with no precedent in the gallery — PDD adjudication is from our methodology, hook-gated transitions is general engineering applied at runtime, receipts-tone satire is brand. The composition is the idea.

10.3 Top-3 sensitivity table¶

90 %+ achievable in expected case. Floor at 71 (still likely top-10).

10.4 Stage-1 pass-rate¶

P(Stage-1 pass) ≈ 0.98 (assuming Phase 6 deploy completes by D-10). P(top-3 | Stage-1 pass) ≈ 0.92. P(top-3 final) = 0.98 × 0.92 ≈ 0.90.

11. Demo Video v4 — 3 minute script¶

0:00 – 0:12  Cold open
             B-roll: workatastartup.com listings ticking past.
             "VC raised. Hiring page full. Product page empty."
             [stamp graphic: D+187 since Demo Day]

0:12 – 0:30  Thesis
             "What if the same money built the product instead of the team?
              WhyC ships any YC company's product in a day —
              with thirteen agents, mechanically gated."

0:30 – 1:15  Live pipeline
             Paste public YC URL on whyc.example
             [Stage 1] 3 analyzer terminals running parallel → 1 synthesized spec
                       (hook indicator pulses: "pre-stage ✓ post-stage ✓")
             [Stage 3] 5 developer manifests in a grid → I2 dedup animation → 1 winner
             [Stage 4] Cloud Build log tail → Cloud Run deploy URL appears
             [Stage 5] 5 critic scorecards → meta-tally bar → spec_fit 0.71
             [Stage 6] Phoenix dashboard, MCP query visible
             (overlay: "whyc.mcp.self_query=true")

1:15 – 2:00  Convergence
             Loop accelerates: iter 3 → 0.84 → iter 7 → 0.96 converged
             BigQuery query visualization: "agent learned from prior runs"
             Cost ledger: "$0.81 spent · 11 minutes elapsed"

2:00 – 2:30  Receipts grid
             12 real YC companies, sortable dashboard
             Days_since_DD vs WhyC_ship_time columns
             "Same pipeline. Different inputs. One day each."

2:30 – 2:50  Methodology beat (NEW v4)
             [hooks/ directory visible in code editor]
             Voice-over: "Every stage transition is a script that can refuse.
                         Schema. Provenance. Budget. Reviewers. The protocol
                         cannot be skipped. Even for a one-line change."

2:50 – 3:00  Closing card
             "WhyC. Receipts attached.
              github.com/Two-Weeks-Team/WhyC · Apache-2.0"
             [Built-with badges: Gemini · Agent Builder · Phoenix · Cloud Run]

Total speaking time ~140 s → fits 3:00 with B-roll cuts.

12. Risk Register v4¶

13. Definition of Done v4¶

15-item submission gate from v3, plus v4-specific items:

• [ ] All v3 items (master-plan-v3.md §9)
• [ ] All 7 hook points present in hooks/ and exit 0 on placeholder data
• [ ] Per-run memory files (session-handoff.md, decisions.md, patterns.md) populated for at least 12 successful runs
• [ ] agents/v4-index.json reflects all 13 registered sub-agents with tag arrays
• [ ] Cost ledger end-of-demo < $50 ($100 credit minus 50% margin)
• [ ] At least 1 converged run has spec_fit ≥ 0.92 + Phoenix Evals verdict + BigQuery row

14. Operator G-checks¶

15. Positioning Statement (for Devpost description)¶

Most multi-agent demos in 2026 fall into one of two patterns: orchestration frameworks that prioritize flexibility but enforce protocol only in prompts, or rigid workflows that lose the creative diversity that makes multi-agent systems useful. WhyC composes Preview-Driven Development (multi-perspective generation + I2 diversity adjudication, the methodology we developed in the PreviewForge plugin) with a runtime hook layer (pre/post stage scripts that mechanically enforce schema, provenance, budget, and category-review contracts). The result is a 13-sub-agent panel where every advocate has wide creative latitude, every stage transition is mechanically validated, and every shipped artifact has SHA-256 provenance. The protocol cannot be skipped — not by a clever prompt, not for a one-line change.

200 words. Ready for Devpost.

16. Appendix A — Verified Sources (2026-05-11 fetches)¶

17. Appendix B — Open Questions for G1-G7¶

1. Vertex AI Agent Engine TypeScript support — answer determines Phase 6 Python wrapper need.
2. Phoenix Cloud REST /v1/spans supports custom attribute filter beyond what SDK exposes — would simplify Stage 6.
3. Cloud SQL f1-micro write rate adequate for ~420 inserts per converged run — confirm via console insights.
4. Cloud Build free tier reset cadence (daily vs monthly) — affects re-deploy cadence during WK4 polish.
5. Vertex AI Agent Engine console UI lets us register a Cloud Run job as the agent's execution surface, or must we reimplement inside the console — Phase 6 effort (4 h vs 12 h).
6. Cloud Run job environment includes python3, bash, jq, shasum by default — answer confirms hook layer runs in production without custom base image.

18. Changelog¶

Plan complete. PDD adjudication × hook-gated transitions × deep GCP/Phoenix integration × receipts satire. The composition is original to WhyC, the methodology is grounded in our own PreviewForge plugin operating experience, and the cost / timeline / probability analysis is verified end-to-end. Execution begins after operator confirms G1, G3, G4, G6, G7. P(top-3 in Arize) targeted at ~90 %.