6-layer mechanical quality gate: Schema/Compile/Regression/Review are blocking (fail = reject); Lint and HumanReview are advisory (fail = warn, no block).
When to Use
- Verify whether an executed candidate should be retained (pass/reject/pending three-state decision)
- Manage the human review queue (high-risk candidates automatically enter pending status)
- View/complete items awaiting approval (completed interactively via review.py)
- Automatically invoked at stage 5 of the orchestrator pipeline to verify the executor's change results
- Use as a standalone tool to perform 6-layer quality checks on any change
- Batch-verify multiple candidates in CI/CD integration scenarios
- When an auditable JSON receipt is required (each layer's result is recorded independently)
- When it is necessary to determine whether advisory-only warnings require human attention
When NOT to Use
- Score candidates → use
improvement-discriminator(the gate does not score, it only does pass/reject) - Execute file changes → use
improvement-executor(the gate only verifies, it does not modify files) - Evaluate skill structure → use
improvement-learner(the gate does not perform 6-dimensional structural analysis) - Generate improvement candidates → use
improvement-generator - When a candidate has not yet passed discriminator scoring, the gate should not be invoked out of order
- Do not use the gate for "pre-checks" — the gate requires a complete execution artifact as input, and cannot run without executor output
- Do not use the gate as a substitute for unit tests — the gate checks the completeness of improvement-process artifacts, not business logic correctness
- Do not use the gate as a linter — LintGate only checks new warnings introduced by the change, and does not perform full linting
6-Layer Gate
| Layer | Gate | Pass Condition |
|---|---|---|
| 1 | SchemaGate | Execution result has valid JSON structure |
| 2 | CompileGate | Target file is syntactically valid after change |
| 3 | LintGate | No new lint warnings introduced |
| 4 | RegressionGate | No Pareto dimension regressed beyond 5% |
| 5 | ReviewGate | Multi-reviewer consensus is not DISPUTED+reject |
| 6 | HumanReviewGate | High-risk candidates require manual approval |
Why 6 Layers in This Order
Tradeoff: cheap/deterministic gates run first, expensive/probabilistic gates run last.
The reason for adopting the fixed order Schema → Compile → Lint → Regression → Review → HumanReview is:
- Schema/Compile are millisecond-level purely mechanical checks— if the JSON structure is wrong or there is a syntax error, all subsequent layers are meaningless. Running these two layers first can reject ~30% of bad candidates within 50ms, avoiding wasted LLM tokens.
- Lint is an advisory layer— it only produces warnings and does not block, so it is placed after the blocking layers. If placed before Schema, it would report a large number of meaningless lint errors for malformed files.
- Regression requires benchmark-store data— this is the most expensive automated layer (it requires querying the Pareto front), so it is placed after confirming that the file can at least compile.
- Review is multi-reviewer consensus— it depends on the discriminator's scoring data; the computational cost is moderate, but it involves LLM calls.
- HumanReview is the slowest— it requires a human response and may take hours. Placing it last ensures that only candidates that have passed all automated layers require human intervention.
Question: Why are Lint and HumanReview advisory rather than blocking? Because lint rules often have false positives (for example, a newly added section triggers a "heading level skip" warning), and forcing blocking would cause too many false kills. HumanReview is set to advisory because most low-risk changes should not be blocked in the human queue — only candidates marked high-risk truly require human confirmation.
CLI
gate.py is the core entry point, receiving the ranking and execution artifact, and outputting a receipt.
review.py manages the human review queue and supports the two subcommands list/complete.
All commands support --verbose View detailed logs for each layer.
It is recommended to use --strict mode in CI, treating the advisory layer as blocking as well.
The output receipt.json can be passed directly to the orchestrator or archived for auditing.
review.py's --decision supports three options: approve / reject / defer.
# Run gate validation (requires ranking + execution artifacts)
python3 scripts/gate.py --ranking ranking.json --execution execution.json --output receipt.json
# List pending human reviews
python3 scripts/review.py --list --state-root /path/to/state
# Complete a review
python3 scripts/review.py --complete REVIEW_ID --decision approve --reason "LGTM"
Skip specific layers when you know they are irrelevant (e.g., YAML-only change does not need CompileGate):
# Skip Lint and Regression layers (only run Schema, Compile, Review, HumanReview)
python3 scripts/gate.py \
--ranking ranking.json \
--execution execution.json \
--skip-layers lint,regression \
--output receipt.json
Batch-validate multiple candidates in one invocation. Batch mode runs 6 layers independently for each candidate; a single candidate's failure does not affect the validation of other candidates.
# Batch mode: validate all candidates in a ranking file
python3 scripts/gate.py \
--ranking ranking.json \
--execution-dir ./executions/ \
--batch \
--output receipts/
Output Artifacts
| Request | Deliverable |
|---|---|
| Gate check | JSON receipt: gate_decision (pass/reject/pending), per-layer results array |
| Review list | JSON array of pending reviews with candidate ID, risk level, timestamp |
| Review complete | Updated receipt with human decision, reviewer ID, reason text |
| Batch mode | Directory of individual receipt JSON files, one per candidate |
Example Receipt structure:gate_decision is the top-level field,layers array records each layer's name、status (pass/fail/warn/skip)、message.
When any blocking layer fails,gate_decision is immediately set to reject, and subsequent layers are no longer executed.
When all blocking layers pass but HumanReview is triggered,gate_decision is set to pending.
The warn status of the advisory layer is recorded in the warnings array for downstream reference but does not affect the decision.
Related Skills
- improvement-discriminator: Scores candidates before gate — gate relies on the discriminator's cognitive_label for ReviewGate determination
- improvement-executor: Applies changes before gate validates — gate validates the execution artifact produced by the executor
- improvement-orchestrator: Calls gate as stage 5 — in the full pipeline, gate is the second-to-last step
- benchmark-store: Pareto front data for RegressionGate — provides baseline data to determine whether any dimension has regressed
- improvement-generator: Produces candidates — the generator's output passes through the discriminator and executor before reaching the gate
- improvement-learner: 6-dim structural scoring — the learner's metrics such as knowledge_density can serve as supplementary dimensions for RegressionGate
- improvement-evaluator: Task-based evaluation — the evaluator's pass_rate can serve as an additional signal for RegressionGate
Data flow in the Pipeline: generator → discriminator → evaluator → executor → gate → (optional) human review