validation

$validation — Full Validation Phase Orchestrator

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

Strict Delegation Contract (default)

Validation delegates to $vibe, $post-mortem, $retro, and $forge (plus lifecycle skills $test, $deps, $review, $perf) as separate skill invocations. Strict delegation is the default.

Anti-pattern to reject: spawning judges directly in place of $vibe, inlining post-mortem analysis, skipping $forge. See [../shared/references/strict-delegation-contract.md](../shared/references/strict-delegation-contract.md) for the full contract and supported compression escapes (--quick, --no-retro, --no-forge, --no-lifecycle, --no-behavioral, --allow-critical-deps).

See [docs/learnings/orchestrator-compression-anti-pattern.md](../../docs/learnings/orchestrator-compression-anti-pattern.md) for the live compression signature.

Validation owns the validate_acceptance port in the [Intent-to-Loop Hexagon](../../docs/architecture/intent-to-loop-hexagon.md). The roll-up must preserve bounded context, context packet, guard adapters, done state, and fresh proof for each accepted scenario. Apply the [Completion-Claim Kernel](../shared/validation-contract.md#completion-claim-kernel) before accepting DONE/closed/green claims.

DAG — Execute This Sequentially

Step 0: Load Prior Validation Context

Before running the validation pipeline, pull relevant learnings from prior reviews:

if command -v ao &>/dev/null; then
    ao lookup --query "<epic or goal context> validation review patterns" --limit 5 2>/dev/null || true
fi

Apply retrieved knowledge (mandatory when results returned):

If learnings are returned, do NOT just load them as passive context. For each returned item:

1. Check: does this learning apply to the current validation scope? (answer yes/no)
2. If yes: include it as a known_risk — what pattern does it warn about? does the code exhibit it?
3. Cite applicable learnings by filename when they influence a validation finding

After applying, record each citation:

ao metrics cite "<learning-path>" --type applied 2>/dev/null || true

Skip silently if ao is unavailable or returns no results.

Run every step in order. Do not stop between steps.

STEP 1  ──  $vibe recent [--quick]
              Use --quick for fast/standard. Full council for full.
              PASS/WARN? → continue
              FAIL?      → write summary, output <promise>FAIL</promise>, stop
                           (validation cannot fix code — caller decides retry)

STEP 1.5 ── Four-Surface Closure (mandatory)
              Read `skills/validation/references/four-surface-closure.md` for the mandatory four-surface closure check.
              Check all four surfaces: Code, Documentation, Examples, Proof.
              All 4 pass? → continue
              if --strict-surfaces:
                Any surface fails? → FAIL, write summary, output <promise>FAIL</promise>, stop
              else (default):
                Code passes, others fail? → WARN, continue
                Code fails? → BLOCK, write summary, output <promise>FAIL</promise>, stop

STEP 1.6 ── Test pyramid coverage audit (advisory, append to summary)
              Check L0-L3 + BF1/BF4 per modified file. WARN only, not FAIL.

STEP 1.6b ── Validation lane budget guard (mandatory)
              If the execution packet or repo profile has `validation_lanes`,
              select the smallest proof set where `read_only=true`,
              `writes_artifacts=false`, `release_only=false`, `cost_class` is
              `cheap` or `standard`, and `auto_select` is `default` or matches
              the changed surface.

              Do not run `expensive`, `explicit`, or `release-only` lanes
              unless the operator explicitly requested them, the plan
              acceptance criteria name the command, or the objective is release
              readiness. Honor each selected lane's `timeout_seconds`; on
              timeout, write `[TIME-BOXED]` and continue with narrower evidence
              unless that lane was the only code-surface proof.

              For unclassified commands, treat `go test -race`, `-shuffle`,
              `-count=N` where `N > 1`, eval runners, retrieval bench,
              headless runtime smoke, and release gates as explicit-only.

STEP 1.7 ── Lifecycle Checks (advisory except critical dependency findings)
              Skip entire step if: --no-lifecycle flag.
              Each sub-step uses --quick mode to limit context consumption.
              On budget expiry: skip remaining sub-steps, write [TIME-BOXED].

              a) if lifecycle tier >= minimal AND test_framework_detected:
                   $test coverage --quick
                   Append coverage delta to phase summary.

              b) if lifecycle tier >= standard AND dependency_manifest_exists:
                   $deps vuln --quick
                   CRITICAL vulns (CVSS >= 9.0): **FAIL** (block shipping). Opt-out: `--allow-critical-deps` for acknowledged risk acceptance.
                   Non-critical: advisory note only.

              c) if lifecycle tier >= standard:
                   $review --diff --quick
                   Append review findings to summary as advisory.

              d) if lifecycle tier == full AND modified_files_touch_hot_path:
                   $perf profile --quick
                   Append perf findings to summary as advisory.
                   Hot path detection: modified files match benchmark files
                   or patterns (handler, middleware, router, parser, engine,
                   worker, pool, codec).

STEP 1.7.5 ── Release-Readiness Gates (MANDATORY when IS_RELEASE_CONTEXT=1)

              Release-context detection: branch name matches release/*,
              v*-prep, v*-evolve-run, or v\d+\.\d+*; OR --release-context
              flag; OR CLI/contracts/hooks/schemas/skills changes AND the
              caller intends to recommend `$release`.

              When IS_RELEASE_CONTEXT=1, this step is MANDATORY — failure
              to run any of the gates below MUST emit a FAIL verdict with
              "release gates not run" reason. Validation MUST NOT recommend
              `$release` until all three (a/b/c) pass.

              a) Full pre-push gate (NOT --fast):
                   bash scripts/pre-push-gate.sh
                   (--fast covers ~5-10 checks; full runs ~33 including
                   doc-release, mkdocs strict, hooks/docs parity, shellcheck,
                   CHANGELOG sync, headless runtime smokes)

              b) CI-local release gate:
                   bash scripts/ci-local-release.sh
                   (If script doesn't exist, log SKIP and continue;
                   if it exists and fails, treat as FAIL)

              c) CLI reference docs regen (when CLI surface changed):
                   Detect: diff contains cli/cmd/**.go with additions of
                   cobra.Command{ or .Flags() or Use:/Short: lines
                   Then: bash scripts/generate-cli-reference.sh &&
                         git diff --quiet cli/docs/COMMANDS.md
                   If diff is non-empty after regen → FAIL
                   ("CLI reference out of sync — commit the regen before
                   declaring release-ready")

              Phase summary records each as a checkbox row:
                [✅] full pre-push gate
                [✅] ci-local-release.sh
                [✅] generate-cli-reference.sh (or [N/A] if no CLI surface change)

              When IS_RELEASE_CONTEXT=0, skip silently.

              Skip suppression: --skip-release-gates (operator risk-accept)

STEP 1.8 ── Stage 4: Behavioral Validation (holdout scenarios + agent-built specs)
            Skip if: no .agents/holdout/ directory AND no .agents/specs/ directory
            Skip if: --no-behavioral flag set
            
            Sub-steps: