quality-gate
Independently verify an Implementation Complete task with a Default-FAIL verification contract, deterministic checks, and an isolated critical reviewer, then decide whether it is Done.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- quality-gate
- description
- Independently verify an Implementation Complete task with a Default-FAIL verification contract, deterministic checks, and an isolated critical reviewer, then decide whether it is Done.
- user-invocable
- false
- disable-model-invocation
- false
03 SKILL.md 正文
Caller: This skill is invoked by
sdd-ship. Do not invoke directly. Results are returned to the caller; no downstream skill is auto-invoked.
Quality Gate
Use after implement-task has set a task to Implementation Complete.
Native Codex evaluator route
For an unmanaged local Codex allocation without an idle sub-agent API, use the
installed review plugin's scripts/launch-codex-review.py with the ordinary
stage: quality, role: sdd-evaluator invocation template. Do not reserve its
placeholder IDs. The launcher allocates a genuinely idle native thread, replaces
only the run/session/ledger continuation fields and its own fresh scratch_root,
then runs the existing evaluator delivery helper before the first model turn.
The original caller template remains pinned and unchanged. Preserve task_id,
implementation_manifest, gate-report and supplemental-delivery declarations,
and every required input. Missing implementation binding is a launch failure.
Managed model routing retains its admitted managed route; this is not a fallback
from a managed failure and does not change the configured Codex evaluator tier.
python3 -I -B "$SDD_REVIEW_SCRIPTS/launch-codex-review.py" \
"$repository_root" "$invocation" --manifest-sha256 "$invocation_sha256" \
--output "$new_output_directory" --timeout 600
Use a new repository-contained output directory. Forward both fixed-input options
when selected. This route requires Linux and native named permission profiles.
It verifies inside read, outside read denial, write denial and network denial;
there is no generic read-only fallback. The child permits only the projected
inputs, its invocation and minimal native runtime files. External tools and
plugins are disabled inside this child; parent workflow guards remain active.
The canonical preflight-evaluator-delivery.py performs scratch hash readback
and delegates the reservation, preserving the implementation identity binding
and feature-wide scratch isolation checks. Do not separately reserve this route.
evaluator.txt is an independently produced candidate, not a quality gate report.
The shared plaintext validator checks identity, exact persisted manifest pin,
verdict, findings and checked evidence. A PASS also requires an observed native
read of an admitted file. The read-only child must list tests it could not rerun;
missing dependencies, writes or network are never silently enabled to get PASS.
Use the usual quality-gate persistence and task-state checks to adopt the result.
Keep delivery.json, native events, permission probes and the reservation receipt
as transport evidence. Timeout, stale inputs, false identity, or missing delivery
binding stops without adopting a result; a consumed reservation stays in history.
Managed allocation boundary
Affected policy roles: evaluator.
Apply this boundary only when the caller explicitly selects managed routing with a policy request or model controls, or this allocation continues that managed workflow. With no managed input, retain the legacy invocation and model hints below. Once managed is selected, do not switch that workflow to legacy because selection, validation or launch fails. No new environment toggle is required, and this boundary does not grant delegation or execution permission.
For a managed allocation, apply in the allocating parent before an unbound forked Skill/Agent, native role, or fresh context receives work, and before any identity reservation. This boundary takes precedence over later native/default launch guidance for these roles. It does not add an availability or authority gate.
Keep an already admitted managed entry with its validated selection/controls and matching role, host, run/session and workload. Keep a concretely known matching batch startup and fixed generated Codex configuration under their original contracts. An already bound worker continues its original procedure: do not select again, allocate again, or run this refusal inside that same worker. A bound parent does not bind a new child, role or session: each new allocation needs its own admitted selection/carrier binding or takes the refusal below.
When this operation has no admitted binding of the selected model and effort to
its actual native carrier, substitute the next affected policy role and actual
host (claude-code, codex-cli, copilot-cli, or gemini-cli) and execute:
python3 -I -B "<installed-root>"/plugins/sdd-implementation/scripts/managed-model-entry.py unsupported-entry \
--role "<policy-role>" --host "<host>"
Exit 2 with model-policy-error/v1 / model-unavailable stops that allocation
before work or reservation. Do not fall through to an old model hint, alias,
unbound native default or another parent session; do not count allocation alone
as selection proof. This refusal does not assert host incapability and never
authorizes same-session reload. Original host-incapable-only implementation
fallback evidence and all review isolation requirements remain unchanged.
Apply before evaluator allocation or reservation. Keep the admitted managed Claude review/delivery route and the fixed generated native Codex configuration entry. The later Codex candidates-file/comment startup guidance is reference-only: selector output and x-sdd reference comments do not prove loaded native model/effort. A zero-turn configuration entry does not prove a substantive evaluator workload; an unbound workload stops here.
Preconditions
If AGENTS.md is absent at the repository root, stop immediately and direct
the user to run /sdd-bootstrap:sdd-adopt; do not proceed without it.
Missing reports/quality-gate/ or docs/review-tickets/ directories may be
created on the fly before continuing.
Required Reading
Read the task, implementation report, requirements, design, acceptance tests,
traceability, contracts, ADRs, Git diff, and all bundled references, including
deterministic-check-policy.md, evaluation-rubric.md, risk-gate-matrix.md,
risk-classification-policy.md, and
plugins/sdd-quality-loop/references/quality-gate-calibration.md.
SQL開発の参照
要求・設計・承認済みタスクがSQL、DBスキーマ、migration、ORMのDB変更を含む場合は、
ホストのスキル索引で sql-develop の配置を確認する。索引に非表示の場合は、
同じホストが現在有効として登録する sdd-implementation のplugin root/manifestから
skills/sql-develop/ を解決する。別versionのcacheや隣接pluginの配置は推測しない。
確認したディレクトリ内の
references/sql-development-policy.mdの「検証と独立レビュー」と該当engineの参照を読む。
公開 sql-develop を再起動せず、このスキルの承認・トラック・状態・実行証跡の規則を維持する。
SQL契約の不足や、承認範囲外のDB変更が見つかった場合は、必要な仕様確認へ戻す。
SQLを扱わない案件はこの追加手順を適用しない。SQL対象なのに参照資料が未導入の場合は、
sdd-implementation の導入を案内し、SQL検証を省略して完了扱いにしない。
初版で実行できるのは合成データの隔離DB検証まで。共有・本番DBへは接続しない。
Process
-
Reject any target not in
Implementation Complete. -
Create the Default-FAIL verification contract for the task from
templates/verification-contract.template.jsonfollowingdeterministic-check-policy.md. Treat the implementation report as a claim, not as evidence. -
Compare the implementation and report with the approved task and source artifacts.
-
Detect and run all available CI-equivalent checks using
verification-policy.md. Save real command output as evidence and update the contract. -
Verify tests using
test-policy.md. -
Run the scripted gates with
scripts/*.shorscripts/*.ps1, in this order:check-riskon the task: confirms a validRisk:tier, a non-emptyRisk Rationale:, and — forhigh/critical—Required Workflow: tdd. The tier selects the required-check set perrisk-gate-matrix.md.check-placeholderson the changed production files only.check-design-systemon the changed files when the project carries adesign-system/directory and the task touches UI-layer files: validates the design-tokens.json contract envelope, scans changed files for raw style values, and confirms design.md's## Design System Compliancesection. Warn-phase: findings are recorded in the report and in the contract'sdesign-systemcheck but do not block until the error promotion (SDD_DESIGN_SYSTEM_ENFORCE=error); whendesign-system/is absent the script skips with a note.check-domain-conformanceon the task'srequirements.md/design.mdwhen the project carries adomain/directory: validates theBounded-Context:field's context name(s) againstdomain/domain-contract.json, structured-field canonical-term usage, anddesign.mdaggregate references againstdomain/aggregates/; for a two-contextBounded-Context:, passes only when the context map declares a relation between them. Warn-phase: findings are recorded in the report but do not block until the error promotion (SDD_DOMAIN_ENFORCE=error); whendomain/is absent the script skips with a note.- During a correction cycle,
check-workflow-state --feature <feature>gives early feedback on the selected specification. This result is explicitly feature-scoped and cannot satisfy the final repository-wide check. At finalization runcheck-workflow-statewithout--feature: validates the canonical persisted-state invariant for every registered specification. Any edit after that final check invalidates it; rerun before Done. Never substitute a saved PASS flag, receipt timestamp or feature-only success. Only when the existing measurement owner shows a total-time benefit for several tasks evaluated together on an unchanged repository, an optional supported Linux profile can usecheck-workflow-state.sh --batch <requests.json>. The external request file contains only{"schema":"workflow-state-batch/v1","requests":["feature/T-001","feature/T-002"]}. It requests the same full scan for each label; labels do not grant task approval. Keep requests, outputs and measurements outside the checked tree. Accept only this invocation's completed result bound to its final snapshot; retained origin run IDs/timestamps identify any same-process reuse. Exit 2 (cold-required) means run the ordinary full checker, with no earlier batch PASS reused. Exit 1 retains ordinary failed-check diagnostics. All remaining gates below and independent reviewers still run. This optional profile does not support Git-history reconciliation, conditional external validators, symlinks/ACLs, oversized trees or arbitrary build/test caching. Seedocs/adr/0045-workflow-session-reuse.mdfor the execution boundary. check-task-stateon tasks.md.check-contracton the task contract: enforces the tier-minimum required set (superset rule) and, whenrequired_workflowistdd, non-emptyred_evidence+green_evidencefor every test-type check.- For an active Project Context with
spec_profile: full, whose approved Resolver invocation publishes a Facet Manifest, additionally runpython3 scripts/evaluate-selected-plan.py --repo-root <project-root> --registry <protected-registry> --facet-manifest <current-resolver-manifest> --contract <task-contract> --output <project-root>/specs/<feature>/verification/<task-id>/selected-plan.json(script path relative to this plugin; on Windows usepython). First complete the existing context approval, Resolver and staleness checks; create the task verification directory before invocation. The output and every parent must be real paths without symlinks or junctions; other output locations are rejected. The feature/task identity comes from the evaluated inputs; supply their current manifest, never a hand-authored selection. Record the command, exit code and versioned plan as gate evidence. Nonzero or missing execution blocks acceptance; only a freshly emittedPASSmay satisfy this additional check. Registry selection never waives the preceding legacy contract. Missing/unrun required observations areBLOCKED; only originally optional, target-unselected checks may be reasoned N/A. An absent Project Context retains the legacy path and does not activate this evaluator from manifest file presence alone. - For C3 PROMOTE_FULL (
spec_profile: liteplus--full), the gate is promoted but the Resolver output remainscapability-summary.yaml. Do not pass that summary to--facet-manifest, fabricate a Facet Manifest, or select this branch merely because a manifest file is missing. Retain all preceding full-gate checks, context approval and Resolver checks, and additionally invokepython3 plugins/sdd-lite/lib/run-lite-gate.py --summary <current-resolver-summary> --enforcement <advisory|required> --full-gate-promotion --repo-root <project-root> --runtime <posix|powershell>(locate the installed sdd-lite plugin; on Windows usepython). This existing adapter validates the Summary and executes its Registry-sourced required Lite checks using the Lite command-discovery contract. The explicit promotion flag satisfiesfull_upgrade_required: trueonly because this caller is already running all full-gate checks; the ordinary Lite caller retains its early upgrade-required failure and must not pass this flag. Its baseline no-ops require the corresponding full-gate observations already executed above. Missing/invalid Summary, unavailable adapter, required-check failure, or nonzero execution blocks acceptance. Record the real command, exit code and JSON result. This branch emits no selected-plan claim and does not change the project's profile; a full-profile context with a missing or invalid Facet Manifest still blocks at the preceding evaluator step. check-component-coverage(epic-191-a3-path-ownership T-004, REQ-004): the Reverse Coverage Gate. Always runs to completion and always emits acheck-component-coverage-verdict/v1evidence record. Derives one of three states from the project'sworkflow.capability_enforcement(never from Facet Manifest file presence, ADR-0016):disabled-legacy(zero evaluation, a real N/A record, exit 0 — this repository's own current state, since noproject-context.yamlexists yet),advisory(full six-Fail-condition evaluation and recording, always exit 0),required(identical evaluation, exit non-zero iff a Fail condition triggers). This is a required invocation with a legitimate applicability result, not an optional waiver or a claim that coverage was substantively evaluated. Preserve its actual command, exit status, configuration/input provenance and producer-bound JSON in evaluator inputs. Do not force capability activation solely because the contract check hasrequired: true. Missing execution, parse errors or enabled-mode missing coverage never qualify as this N/A. This documented invocation is defense-in-depth, not the reachability guarantee —check-component-coverageis registered incheck-contract's own protected tier-minimum required- check-set (INV-017), which is what actually closes the gap were this line to be deleted or the check renamed.check-traceabilityonspecs/<feature>/traceability.json: every REQ → AC → TEST → evidence chain is intact (required forhigh/critical). ForDonetasks, validatespecs/<feature>/verification/<task-id>.evidence.jsonwithcheck-evidence-bundle.(sh|ps1)so the report, contract, and passing evidence artifacts are all bound together. Forhigh/criticalthe bundle must carryspec_revision,build_env, andreview_verdict.verdict == PASS; forcriticalit must additionally carry a verifiable HMACsignatureand a clean tree (git_generated_dirty == trueis a hard fail). Always produce the bundle withgenerate-evidence-bundle.(sh|ps1)— never hand-author sha256 fields or thegit_commitfield. The runner binds the bundle to the current git commit and computes digests automatically.
-
For
refactorandbugfixtasks with abaseline-behavior.md, applydifferential-test-policy.mdand classify every BL diff. -
Run critical review with an isolated evaluator using
evaluation-rubric.md. The evaluator must also applyquality-gate-calibration.md: deterministic command output, bundled scripted gates, line-level inspection, and manual artifacts outrank implementation-report claims; the implementation report never supports PASS by itself. When the change touches the relevant surface, the evaluator also applies the on-demand domain checklists —security-checklist.md(user input, auth, secrets, external systems, AI/LLM),performance-checklist.md(data access, hot paths, rendering),accessibility-checklist.md(user-facing UI), anddesign-system-checklist.md(user-facing UI in projects carrying adesign-system/contract). Load a checklist only when its domain is in scope, to keep review context lean. On Claude Code use thesdd-evaluatorsubagent. The managed non-TTY route below applies the selected model and effort through validated native flags and its generated agent definition. This establishes configuration, not actual backend identity. For legacy routes that only record thex-sdd-effort:comment, retaineffort_applied=nulland pass--effort-control-main frontmatter(no--effort-applied-main) toemit-run-record, exposing the degradation through the resolvedeffort_controlvalue (AC-039, AC-024/AC-051).On Codex use the shipped
sdd-evaluator(orsdd-investigator) TOML agent; do not create new agent role files under~/.codex/agents/. Codex-host startup wiring (REQ-006, T-006): before launchingcodex, resolve--model/--effortfrom the live registry — never from unsanitized task or spec text (security-spec.md B3) — via:plugins/sdd-implementation/scripts/select-agent-model.sh \ --risk <risk> --registry contracts/agent-model-capabilities.v2.json \ --candidates-file <codex-candidates.json> \ --role sdd-evaluator --host codex-cli --json(substitute
--role sdd-investigatorfor the investigator;--host codex-cliresolves each candidate'seffort_control.codex-cli, and--roleseeds the role'sminimum_tier/fallback effort fromrole_defaults). Cross-check the resolvedmodel/effortagainst the# x-sdd-model:/# x-sdd-effort:reference comments T-003's renderer wrote into.codex/agents/sdd-evaluator.toml(orsdd-investigator.toml): when they diverge, report the divergence (DRIFT: <toml-path> toml=<model>/<effort> live=<model>/<effort>) rather than silently preferring either value — the live selector output is always what launchescodex, the stale reference comment is never silently substituted in either direction (AC-038). Reject any resolved--model/--effortvalue that is not a member of the registry's own enumerated vocabulary: a whitespace-containing value, a value with a leading-/--(flag-injection shape), a value containing;(command-separator shape), or an effort string outside the set{low, medium, high, xhigh}. On rejection: non-zero exit, a diagnostic message, and nocodexinvocation attempted (AC-052;run-panelist-gpt.sh/.ps1implement this same rejection for their own--model/--effortarguments —tests/run-panelist-effort.tests.sh/.ps1TEST-052). Launchcodexwith the resolved, validated flags:codex --model <live-model> --effort <live-effort> ...Elsewhere, perform the review in a fresh session or a clearly separated critical-review pass. Before launch, persist a canonical allowed-input manifest containing exactly one
reports/implementation/<feature>/T-NNN.md, the task's required specification and calibration files, and only those changed, test, contract, ADR, or deterministic-evidence files whose exact canonical path and lowercase SHA-256 pair appears in that implementation report's## Outputstable, or in the## Post-Fix Artifactstable of a gate report the manifest names ingate_report_declarationand pins by SHA-256 (WFI-036). The implementation report is frozen, so it can never describe bytes produced by a fix this gate itself raised; a cycle that follows a review-ticket or in-gate fix therefore records the post-fix path/hash rows in its own report, and the next cycle names that report. The second channel is checked exactly as the first: the named report's own hash is verified before a single row is read from it, a path in neither document is still unlisted, and a row carrying the wrong hash still fails. Do not add the rows to an earlier cycle's report -- that report recorded a verdict at a point in time and must not later declare bytes that did not exist then. If a frozen implementation report omitted required evaluation inputs, preserve it and use the approved supplemental-delivery repair: the quality manifest'ssupplemental_delivery_declarationpins a canonical, symlink-free JSON file underspecs/<feature>/verification/<task_id>/. Its exact fields areschema(supplemental-delivery-declaration/v1),feature,task_id,implementation_report(the canonical task-report path and its current SHA-256), andartifacts(unique canonical path/SHA-256 pairs). Include the declaration itself inallowed_input_manifest. Validate its identity, report binding, artifact paths and hashes before reservation; reject duplicate JSON keys, duplicate paths, symlinks, traversal, missing files and raw review/gate reports. This declaration admits inputs only: it neither replaces historical evidence nor asserts approval, a verdict, task completion or tests not actually run. For a frozen report containing only a legacyManifest SHA-256: <hash>citation, declaration v2 adds exactlyimplementation_manifest(path/SHA-256). This pin must equal the invocation's implementation manifest and occur once in its allowed inputs. Verify the file hash and the report's single exact legacy digest; reject anyInput manifest:line rather than override it. Existing task/run/session validation and reservation uniqueness still apply. Version 1 and modern report citations retain their existing behavior. Broadplugins/,tests/,contracts/, ordocs/adr/membership never authorizes an evaluator input. Reverify every hash immediately before launch and bind the manifest path/hash, a fresh run ID and a host-session ID unused by every other context into the evaluator result. These fields may be identical within this invocation; never invent a second native identifier merely to make them unequal. Persist a one-rolereview-context-invocation/v2manifest for the evaluator. Set itstask_idto the current T-NNN and require the sole implementation report path, report heading, andTask IDfield to match that exact task. Bind it to the current SHA-256 and final record hash of the canonicalreports/review-context/identity-ledger.json. The ledger must already carry every earlier reviewer/evaluator reservation as a valid hash chain. For a new reservation, include the existing hash-pinnedtask-input-manifest/v1as an evaluator input and name its path and SHA-256 inimplementation_manifest. Require its task/run/session to agree with the implementation report and reject their reuse in the canonical ledger. Never fabricate an implementation ledger reservation or accept reserved-ID arrays as a substitute. Before reservation, the caller must prepare any dependency fixture needed by read-only checks in a fresh evaluator-only scratch directory, preserving admitted relative paths. Include every test dependency in the manifest; missing dependencies block launch rather than being created by the evaluator. The scratch copy is only a byte-identical projection of admitted files, not an additional source of authority. Record its canonicalscratch_rootin the invocation and independently read back every copied file against its admitted SHA-256. The evaluator remains read-only inside scratch as well. Freeze the manifest and pin its SHA-256 separately in the launch brief. For the explicitly authorized Claude Code non-TTY Sonnet route, use the shared caller (repository-root-relative paths):rtk proxy python3 -B plugins/sdd-review-loop/scripts/launch-impl-review.py <repository-root> <invocation> <reports/quality-gate/launch-SESSION> --manifest-sha256 <caller-pin>. In this legacy route the canonical Claude evaluator and its generator select Sonnet; this does not change the Codex evaluator tier or authorize a host switch to bypass a refusal. This route requires a fresh declared scratch projection. When managed routing is explicitly selected for the authorized Claude Code non-TTY route, prepare the evaluator policy selection and forward its validated controls to the shared caller. Use repository-root-relative request, registry and fresh output paths. The launcher output is absolute under the repository root. The policy role isevaluator; the invocation's transport role stayssdd-evaluator. The run and session IDs must equal the invocation's fresh UUID, and the attempt must match its task attempt. Read the controls SHA fromvalidation.json; do not substitute an unchecked rehash.cd "<repository-root>" || exit $? output="<output-dir>" python3 -B plugins/sdd-implementation/scripts/managed-model-entry.py prepare \ --role evaluator --host claude-code --request "<policy-request>" --registry "<registry>" \ --run-id <run-id> --session-id <session-id> --attempt <attempt> \ --output-dir "$output" --require-actual-id false > /dev/null || exit $? controls_sha=$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1]))["controls"]["sha256"])' "$output/validation.json") || exit $? rtk proxy python3 -B plugins/sdd-review-loop/scripts/launch-impl-review.py \ "<repository-root>" "<invocation>" "<repository-root>/<reports/quality-gate/launch-SESSION>" \ --manifest-sha256 <caller-pin> \ --model-controls "$output/controls.json" --model-controls-sha256 "$controls_sha"Stop on preparation or launch failure; never retry the legacy route. With these controls the canonical Claude evaluator and its generated role both use the trusted selected native model and effort. A standalone legacy launch without controls retains Sonnet. This does not change the Codex evaluator tier or authorize a host switch to bypass a refusal. This route requires a fresh declared scratch projection. Both routes check the external raw pin, common required-input/path admission, and this plugin's
preflight-evaluator-delivery.pyscratch readback before creating launch output. It then pins dependencies, checks live CLI argv, and runs the shared native permission probe before reservation. Missing or failedpreflight-host-review.pyHOST_REVIEW_PREFLIGHT_OKproof, or failed admitted-read, outside-read denial, compound-Bash denial, session collision, or ordered-hash proof stops without reserving. Input preflight alone explicitly leaves permission proof unestablished. Immediately before reservation it rechecks dependency bytes, admission, argv, and the same delivery helper's pin/scratch readback; only that helper delegates the canonical atomic reservation. Do not separately reserve this route. The complete receipt and invocation pin reach the child through the shared prompt, and native delivery is validated independently of its verdict. Exact Read/hash permissions do not permit writable tests: list tests not rerun, and never treat delivery or a receipt as quality PASS. A candidate launcher or fixture success does not establish an installed verified baseline or authorize formal execution. For other already-supported host routes, retain the delivery sequence below: runpython3 -B scripts/preflight-evaluator-delivery.py --manifest <manifest> --manifest-sha256 <caller-pin> --repository-root <repository-root>(paths relative to this plugin); append--scratch-root <scratch>when a fixture is needed. RequireEVALUATOR_DELIVERY_OKbefore calling the reservation validator. Failure leaves the ledger untouched. This delivery check does not replace the existing required-input, path, identity or reservation checks. Do not change these bytes between delivery and launch; the evaluator must independently compare the manifest's raw bytes with the caller's pin before parsing, then verify admitted inputs before use. A scratch fixture does not authorize write-requiring tests; those remain caller-owned evidence. Immediately before launch on those other host routes, run the same delivery command with--reserve. It rechecks the pin and fixture before delegating the atomic reservation toscripts/validate-review-context-set.sh; do not reserve directly and then prepare a fixture. RequireEVALUATOR_DELIVERY_OKandREVIEW_CONTEXT_OK, then pass the complete validator receipt and the persisted invocation manifest path/hash in the launch brief to the shipped evaluator. Tell the evaluator to verify identity from that receipt and manifest alone; the ledger is caller-only. Do not ask it to read/hash the ledger, rerun the validator, inspect the process environment, or open raw session logs. Launch exactly the reserved evaluator run/session. A missing canonical ledger, stale chain tip, deterministic runtime, or any non-zero result retainsImplementation Completeand blocks evaluator launch. This boundary validates only the evaluator being launched; it does not require fabricated future or replayed reviewer contexts. Reject a missing manifest, unlisted path, hash mismatch, chat-only input, or any implementation/review/evaluation session reuse. Never direct an evaluator to reach an artifact the manifest does not authorize -- not throughgit show, not through the live tree, and not by reproducing its contents in the launch prompt. Authorization comes from the persisted, validator-checked manifest, never from the launching agent's prose; a launcher that can widen the evaluator's reachable set by asking has removed the boundary this machinery exists to enforce. When a needed artifact is undeclared, declare it and relaunch rather than instructing around it (WFI-036). No same-session fallback is permitted for the evaluator. Use the caller-prepared evaluator scratch directory and name it in the launch brief and the invocation record's optionalscratch_rootfield: a canonical absolute path used by no implementation context for this feature and by no earlier evaluator run. Tell the evaluator to write nothing, including inside scratch; fixture preparation and writable tests belong to the caller. Whenscratch_rootis present, the deterministic reservation boundary compares it with the current implementation report'sScratch Rootand rejects equal or ancestor/descendant paths before launch. This is not housekeeping (WFI-034). Sharing one scratch root across roles puts the implementing agent's intermediates -- a.bakof the suite under review, per-task append scripts, raw red/green logs -- inside reach of the agent grading that work, through a channel the manifest does not describe and the hash checks never see. Observed insdd-domain-concept-contract: the evaluator found exactly those files and disclosed that it had declined to read them. What held there was the reviewer's judgement, not a mechanism, and a boundary that depends on the reviewed party declining an available capability is not a boundary. Forhigh/criticaltasks, record the evaluator's verdict asreview_verdictin the evidence bundle;check-evidence-bundlerequiresreview_verdict.verdict == PASS. -
Classify findings as
Accepted,Rejected, orDeferred. When a finding is that the implementation report's narrative (counts, statuses, or paths) diverges from the gate-time measured reality -- e.g. a later same-feature task's edit, or a gate-phase artifact move, superseded what the report described -- record the current values directly in this quality-gate report and classify the findingAccepted; do not edit the frozen implementation report to reconcile it. -
Apply only safe fixes allowed by
auto-fix-policy.md. -
Repeat critical review autonomously for a maximum of 3 cycles. Stop earlier when the remaining issue requires human decision, missing evidence cannot be produced, or the fix belongs to
fix-by-review-ticketor an upstream review loop. Do not downgrade a finding merely to end the loop. After escalation, follow Resuming After A Human Decision below. -
For UI changes, use available browser or Playwright tooling to verify the rendered screen, DOM, and console, and when feasible perform the smoke run described in
deterministic-check-policy.md. -
Create review-ticket YAML for unresolved or non-auto-fixable findings.
-
Update traceability and detect drift using
integrity-policy.md. -
Create
reports/quality-gate/<timestamp>.mdfromplugins/sdd-quality-loop/templates/quality-report.template.md— the template exists and is parity-tested (tests/template-validator-parity.tests.{sh,ps1}); do not author the report freeform. Its identity header block (Task ID:/Feature:/Run ID:/VERDICT:/Critical:/Major:/Minor:) is parsed by deterministic consumers (check-evidence-bundle, emit-run-record, generate-evidence-bundle, the retrospective's artifact rules): keep each as a bare line before any prose, and never start a later body line withFeature:orTask ID:— two consumers require exactly one match each. Record the same- Model:/- Effort:two-line requirement the implementation report carries (implementation-report.template.md,validate-implementation-report.shpresent-and-format-only check): name the model and effort the gate's own critical-review pass ran under. (WFI-020)
Resuming After A Human Decision
Escalate-Human ends autonomous retries; it is not a failed quality check that
can be relabeled as success. After a human explicitly authorizes further
correction and review, record in the current handoff and next gate report who
authorized it, the actual instruction and its conversation/artifact reference,
the affected feature/task, the correction scope, and remaining findings.
An existing explicit retry instruction may apply: explain its concrete match
to this correction instead of asking again. A general wish to finish, routine
approval, or Sudo Mode alone does not authorize retries beyond the limit.
Within that recorded scope, perform the authorized correction through the
applicable workflow and obtain a fresh independent review on the corrected
inputs. Re-run all required deterministic checks and satisfy every Done
Decision condition. Preserve every prior report, counter, finding and verdict;
keep the cycle-limit script's actual Escalate-Human output and non-zero exit
in the evidence, describing this continuation as human-authorized rather than
claiming the limit passed. Do not reset history, invent an override flag, or
use a previous PASS for changed inputs. A new out-of-scope correction or an
unresolved genuine human judgment still stops the gate. The recorded decision
authorizes only its stated scope, not an unlimited autonomous retry loop.
Sudo Mode
If a valid SDD_SUDO flag file exists at the project root (see
plugins/sdd-quality-loop/references/sudo-mode-policy.md), routine approval
checkpoints auto-pass: record Approval: Approved (sudo <ISO8601 UTC>) in
tasks.md and continue. A refactor/bugfix BL diff classified accepted also
auto-passes (mark (sudo <ISO8601 UTC>) and update baseline-behavior.md).
Sudo never auto-passes genuine judgment: requires_human_decision: true
findings, architecture/auth/authz/breaking-API/security decisions, and a
fix-required baseline diff still stop the gate and require a human. All
deterministic gates apply; every check runs as normal.
Done Decision
Set the task to Done only when:
check-workflow-statewithout--featurepasses against the final input tree, including specifications outside the selected feature. A correction-cycle feature check is early feedback only; it cannot authorize Done.check-riskpasses: valid tier + rationale, andhigh/criticaldeclaresRequired Workflow: tddcheck-contractpasses: every required contract check (the tier-minimum superset) is true with existing evidence files; fortdd, test checks carryred_evidence+green_evidencecheck-traceabilitypasses forhigh/critical(REQ → AC → TEST → evidence)check-evidence-bundlepasses: the bundle names the report, contract, and contract-passing artifacts, with matching hashes and task id; forhigh/criticalit carriesspec_revision,build_env, andreview_verdict.verdict == PASS; forcriticalit carries a verified HMACsignatureover a clean tree- for
critical, a second distinct named approver recordedSecond Approval: Approved(enforced bycheck-task-state; never sudo-bypassed) - acceptance criteria have tests
- no unresolved Critical or Major finding remains
- required UI verification succeeds
- contracts and ADRs agree with the implementation
- traceability is current
- every in-scope "cannot verify" item has been resolved by evidence or recorded as a blocking review ticket
Otherwise set the task to Blocked or retain Implementation Complete, and
create review tickets. Do not commit, push, or create a PR/MR unless explicitly
requested.
Post-Done: Automatic Retrospective
When the task transitions to Done (all conditions in the Done Decision section
are met), automatically invoke the retrospective flow:
- Confirm
reports/quality-gate/<timestamp>.mdhas been written (step 15 must complete first so the new report is included in retrospective metrics). - Determine the feature path from the task's spec directory (e.g.
specs/<feature>). - Check
tasks.mdfor the feature: if any task withApproval: Approvedis not yetStatus: Done, append[INFO] retrospective deferred: N approved task(s) still pending Doneto the quality-gate report and stop here. Invoke retrospective only when every approved task in the feature isDone. - Invoke
workflow-retrospectivefor that feature path:- Claude Code:
/sdd-quality-loop:workflow-retrospective specs/<feature> - Codex:
Use the workflow-retrospective skill for specs/<feature>
- Claude Code:
- The retrospective runs in read-only mode and does not affect
Donestatus or any other task field. - If the feature path cannot be determined, skip the retrospective and append a
[WARN] retrospective skipped: feature path unknownline to the quality-gate report.
Do not invoke this flow when the gate exits with Blocked or retains
Implementation Complete.
Common Rationalizations
The gate exists because generators grade their own work generously. Reject
these excuses — each one launders a claim into a Done.
- "The report says all tests pass, so they pass" — the report is a claim; rerun
the checks and read the output yourself (
evaluation-rubric.md). - "The checks are green, the review can be light" — green checks do not cover spec compliance, untested acceptance criteria, or completion-faking.
- "This finding is probably fine, downgrade it to Minor" — never weaken a severity without recording why in the report.
- "A check doesn't apply, I'll just delete it from the contract" — mark it
required: falsewith a non-emptywaiver_reason; never remove a check to pass. - "The evidence file is missing but the result is obviously right" — Default-FAIL: no saved evidence means the check stays false.
- "I cannot verify this, but no failure is visible" — cannot-verify is not PASS; keep the check false or create a review ticket.
- "sudo is on, so I can wave this through" — sudo auto-passes routine approval only; judgment findings and architecture/auth/security decisions still stop the gate.
Red Flags
- Flipping a contract check to
passes: truewithout a saved evidence path. - A handler returning data shaped like the test fixture (completion-faking —
Critical). - Skipped/
todo/xittests covering in-scope behavior left unaddressed. - An acceptance criterion with no test traced to it.
- Setting
Donewhile a Critical or Major finding is unresolved. - Running the critical review in the same context as the implementation.
Optional passive timing
Keep measurement output outside the checkout. Existing execution owners accept
--measure-dir <new-empty-directory> and
--measure-parent <open-parent-span-id>: tests/verification.py --run and
sdd-lite/lib/run-lite-gate.py. The immutable sdd-run-measurement/v1 sidecar is
observation only. It records separate command/gate/session spans, real outcomes,
and hashes the owner's receipt/output only after publication. It does not replace
run-records, contracts, independent review, evidence bundles or final checks.
For existing Bash or PowerShell gate calls, open a measurement with
python run_measurement.py open --dir D --measurement-id ID --run-id RUN --scope feature --feature FEATURE,
then start --dir D --phase gate --command-id GATE --span-id SPAN; execute the
original gate and save its exit code before calling
finish --dir D --span-id SPAN --outcome success|failure --exit-code CODE.
Return the saved original gate exit code, not the recorder's. Use an enclosing
session span for aggregation. Record timeout/interruption only when the execution
owner actually observed it; exit 124 alone is not a timeout observation.
summary is obtained with summarize --dir D --as-of none --ref-root ROOT.
Human-active and human-wait phases require explicit observation; unobserved time,
tokens and cost stay null, never zero. Shared boot identity is used where
available; when no shared monotonic clock domain can be established,
cross-process duration remains unknown. Consult current-head
native CI evidence for platform execution rather than inferring it from Linux.
Optional project evidence collection
The project evidence collection procedure
uses the existing runner and contract/report/bundle owners. Low-risk ordinary
collection and prospective Red/Green keep the required checks unchanged.
High/critical --prepare stops before the existing independent review, clean commit
and signing steps; it does not grant approval or set Done. High/critical work
retains its existing review and signing requirements. Collection is optional,
and neither this helper nor an observation file replaces owner-side execution.
04 同仓库更多 Skills
status
Show a read-only Jira-style six-view SDD dashboard in the initiating parent's Sites or Claude Artifacts, with source freshness and failure visibility.
verify-review-reservation
Recheck the bounded identity-ledger reservation invariant after lock, hash-check or publication changes.
aws-cdk
Authors, deploys, and troubleshoots AWS infrastructure using CDK with TypeScript or Python. Covers best practices, stack architecture, and construct patterns. Applies when writing CDK constructs, bootstrapping environments, running cdk deploy/synth/diff, fixing CDK or CloudFormation errors, planning stack structure, importing existing resources, resolving drift, or refactoring stacks without resource replacement.
quality-gate
Independently verify an Implementation Complete task with a Default-FAIL verification contract, deterministic checks, and an isolated critical reviewer, then decide whether it is Done.
ship
Implement approved SDD tasks through the quality gate to Done — the second of the two-command workflow. Run after /sdd-bootstrap:bootstrap and human task approval.
ship
Implement approved SDD tasks through the quality gate to Done — the second of the two-command workflow. Run after /sdd-bootstrap:bootstrap and human task approval.