BOHICA-LABS / BOHICA-LABS/vsdd-factory

documentation(phase-1d): document rationale for '3 clean passes minimum' convergence rule

Open
#222 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Rust
Stars
2
Forks
1
Avg merge
6h 43m
Merged PRs (30d)
29

Description

## Summary

The orchestrator's Phase 1d convergence policy says (per `AGENTS.md` and the run-phase skill):

> Phase 1d adversarial convergence — always 3 clean passes minimum.

The rationale for "3" is not documented anywhere. It's treated as an absolute requirement. There's no:

- Empirical evidence shown for why 3 is the right number (vs 2, vs 5).
- Size-scaling parameters (does 3 work for a 20-file spec? a 500-file spec?).
- Discussion of what "clean" means precisely (the gate-audit also runs alongside; do its findings count?).
- Documented experience with cycles that struggled to reach 3 (if any).

This matters because, empirically, achieving even 1 clean pass on a moderately-sized spec corpus (200+ files) is difficult, and 3 consecutive may be unreachable in finite time — see Issue #8 (relaxed convergence alternative).

## Proposed change

Add a documentation section under `docs/policy/phase-1d-convergence.md` (or similar) that includes:

1. **The rule**: "3 consecutive clean passes (0c/0h) required before human gate."

2. **The rationale**: What evidence supports 3 (vs other numbers)? E.g., was this derived from prior pilot cycles? Empirical studies of finding-decay curves? A team-internal heuristic? Cite the source.

3. **The size-scaling**: Does the rule apply equally to a brief-stage product spec (10 files) and a full L3 PRD (200+ files)? If not, document the size brackets.

4. **The "clean" definition**: Specifically:
- Critical = 0, High = 0 — is that strict?
- Do gate-audit findings count (they run alongside adversary)?
- Do `[process-gap]` findings count (they're tooling defects, not spec defects)?
- Do `[advisory]` lint outputs count?

5. **The escape hatch**: If 3 isn't reachable, what's the documented path? (Currently: nothing — see Issue #8.)

6. **Worked examples**: At least one cycle that hit 3 cleanly, and one that struggled, with retro.

## Applies to

- New file: `docs/policy/phase-1d-convergence.md` (or fold into existing docs)
- `agents/orchestrator/AGENTS.md` — link to the policy doc instead of just stating the rule
- `skills/phase-1d-adversarial-spec-review/SKILL.md` — same

## Acceptance criteria

- [ ] Policy doc exists with the 6 sections above
- [ ] Rationale is grounded in either empirical data, cited heuristic, or explicit "we picked this; revise if you have evidence"
- [ ] Size-scaling guidance is clear
- [ ] "Clean" criteria are precise

## Found during

ftc-blue Phase 1d adversarial cycle (2026-06-23, vsdd-factory@1.0.0-rc.21). Cycle ran 5 passes this session, never converged; orchestrator had no documented basis for "is 3 actually achievable here?"

## Notes

Pairs with Issue #8 (relaxed convergence). Even if the rule stays as-is, documenting why helps practitioners reason about exceptions.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.