keelwright — engine for vibe / loop coding

a loop with nested loops · safety cannot be switched off · a human who does not read code stays in control
Layer 0 · the human
▣ YOU (need not read code)  →  GOAL + ACCEPTANCE CRITERIA   ◄──   PLAIN-LANGUAGE REPORT / BUILD
★ DNA: understands LOGIC, not syntax. Every gate below is translated to plain words — "this checks the password is right", never "string arg to fn()".
▼
Layer 1 · control
🎛 AUTONOMY DIAL
Autopilot → Checkpoint → Copilot
★ freedom = blast radius (auth / money / prod → Copilot: approve each)
🗂 TRIAGE
Trivial · Low · Standard · High · Critical
★ machinery = risk. Trivial → Express, no per-iter scans
▸ PHASE 1–2
Requirements → Planning
★ no acceptance criteria? ⛔ STOP, ask. Never invents scope
⬚ LOOP DESIGN
5 whiteboard questions before any code
★ trigger · check · action · stop · escalate — skip = demo
▼
Layer 2 · the build loop (Phase 3 — one task = one turn, repeats)
⟳ PHASE 3 · BUILDING — discipline INSIDE writing, not cleanup afterward
①
@implementer writes (1 file/fn) ◄ REUSE LADDER — reuse before adding a lib/abstraction · catches: over-engineering
②
BACKPRESSURE GATES: tests │ typecheck │ lint │ build
③
STRUCTURAL-INTEGRITY GATE ★ jscpd·lizard·madge/import-linter·eslint-boundaries·knip/vulture · catches: spaghetti, lava flow, tangled deps
④
🛡 SECURITY GATES R1–R12 ★★ machine-enforced, cannot disable even on Autopilot · catches: OWASP·secrets·slopsquat·IDOR
⑤
🔍 R3 BUSINESS-LOGIC REVIEW ► spawn @reviewer (fresh context) ★ NOT self-review · catches: happy-path bias, auth holes
⑦
✅ VERIFICATION GATE ★★ read+compile+diff · test red→green · not tautological · ad-hoc · catches: "works on my machine", "I fixed it" with no diff
⑧
⟲ MATCH LOOP (nested sub-loop) ★ Generator ⇄ Analyst: render → browser → numeric a11y (contrast≥4.5:1 · no overflow · sizes) — repeat until convergence
⑨
git commit (atomic) ► ⑩ PROGRESS.md + STATUS + tool-budget count
⑪
cadence: /3 → STABILITY scan · /10 → AUTORESEARCH · /N → refactor checkpoint
↩ LOOP BACK — next task, while tasks remain
▼  perimeter supervision  ▼

🚦 CIRCUIT-BREAKER

  • catches: doom loop + token/$ burn
  • 4 caps: 50 iters / 5 no-progress / 2h / 3× repeat
  • + RATE LIMITING (event-driven loops)
  • + PER-ITER BUDGETS ≤10 shell / 5 file / 3 external
  • → graceful STOP with report

📉 STABILITY (5 modes)

  • catches: goal drift, oscillation, thrash
  • dead-retry · oscillation · drift · amplification · feedback-starvation
  • ESCALATION: 3→REFINE 5→PIVOT 2→ask 3→blocker
  • + CONTEXT COMPACTION (iter > 20)
  • a "keep" resets the counters

🔄 SELF-LEARNING ★

★★ REWARD-HACKING GUARD — never weaken/delete a test to go green; fix the code, not the metric.  ·  PERSONAS (delegate_task): @architect @implementer @tester @reviewer @architecture-critic @visual-qa  ·  STRUCTURED FEEDBACK into each iteration: relevant code + intent + "repeat vs new" flag — not a raw stack-trace dump.
Layer 4 · outer operational cycle (production lifecycle)
🔭OBSERVEread prod logs/reports
🩺ANALYZEroot-cause + plan
🔧FIXrun the build loop
✅VALIDATEpost-deploy metric compare
🎓LEARNupdate lessons
⭐ verify-in-production + AUTO-ROLLBACK (git revert, not force-push) — a bad deploy that passes tests is caught by the metric, not by a human  ·  ⚡ PARALLEL: independent subtasks fan out as separate empty-context loops
🔒 BATTLE-TESTED QA ★★★
A/B (control vs skill), fact-checked on disk, not self-report — published WITH an honest adversarial report.
💸 ZERO INSTALL · ZERO COST
Plain markdown that orchestrates free, permissively-licensed tools. Full transparency, nothing to buy.
🗣 PLAIN-LANGUAGE THROUGHOUT
Built for people who read product logic, not code syntax. Every gate speaks human.
documented 2026

🗺 VIBE/LOOP-CODING RISK MAP → WHAT KEELWRIGHT COVERS

Every known vibe/loop-coding pain → the mechanism that closes it. ✅ = machine-enforced / on-disk · ⚠ = partial (honest: no cheap machine detector)
Context rot / decay✅
fresh-context + PROGRESS.md
Ralph (Wiggum) loop✅
state in files, not chat
Spaghetti / big ball of mud✅
structural-integrity gate ③
Lava flow (dead code)✅
knip / vulture
Dependency hell✅
reuse ladder + dep vetting
Slopsquatting✅
R8 verify + GuardDog
"Works on my machine"✅
verification gate ⑦
Reward hacking / spec gaming✅
reward-hacking guard
Doom loop / death loop✅
circuit-breaker + budgets
Goal drift✅
Stability L3 + goal re-read
Happy-path bias✅
R3 business-logic review
Tech debt (80% problem)✅
R4 prod checklist
Secret leakage✅
R2 Gitleaks
SQL injection / OWASP✅
R1 Semgrep + review
Reasoning-action (said≠did)✅
R7 + verification
Malicious 3rd-party skill✅
R11 SkillSpector audit
Token / budget burn✅
per-iteration budgets
Regression passes tests✅
post-deploy + rollback
Human as bottleneck✅
autonomy dial + parallel
Design-for-failure⚠
R5 fault checklist (warn)
Sycophancy⚠
R7 catches false claims, not trait
Multi-agent cascade / mem-poison⚠
R10 verify-before-memory (warn)
Model version drift⚠
R9 pin (warn)
Style / consistency drift⚠
critic + Pink Flag (no machine detector)
Confabulation / fabricated facts⚠
factual-grounding: verify-before-assert
Loop design absence✅
5 whiteboard questions
Context rot in long loops✅
compaction (trim/summarize/delegate)
Event storm / rate limiting✅
rate limit + debounce + backpressure
Honesty as a feature: three ⚠ (style consistency, sycophancy-as-trait, confabulation) cannot be closed by a cheap machine detector — keelwright catches their measurable consequences and enforces verification discipline, not the disposition itself. Everything marked ✅ is machine-enforced or verified on disk, not "eyeball it."
keelwright by ratingtesting · CC BY 4.0 · source of truth: assets/architecture.md