AGENT SKILL

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

  1. Reject any target not in Implementation Complete.

  2. Create the Default-FAIL verification contract for the task from templates/verification-contract.template.json following deterministic-check-policy.md. Treat the implementation report as a claim, not as evidence.

  3. Compare the implementation and report with the approved task and source artifacts.

  4. Detect and run all available CI-equivalent checks using verification-policy.md. Save real command output as evidence and update the contract.

  5. Verify tests using test-policy.md.

  6. Run the scripted gates with scripts/*.sh or scripts/*.ps1, in this order:

    • check-risk on the task: confirms a valid Risk: tier, a non-empty Risk Rationale:, and — for high/critical — Required Workflow: tdd. The tier selects the required-check set per risk-gate-matrix.md.
    • check-placeholders on the changed production files only.
    • check-design-system on the changed files when the project carries a design-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 Compliance section. Warn-phase: findings are recorded in the report and in the contract's design-system check but do not block until the error promotion (SDD_DESIGN_SYSTEM_ENFORCE=error); when design-system/ is absent the script skips with a note.
    • check-domain-conformance on the task's requirements.md/design.md when the project carries a domain/ directory: validates the Bounded-Context: field's context name(s) against domain/domain-contract.json, structured-field canonical-term usage, and design.md aggregate references against domain/aggregates/; for a two-context Bounded-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); when domain/ 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 run check-workflow-state without --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 use check-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. See docs/adr/0045-workflow-session-reuse.md for the execution boundary.
    • check-task-state on tasks.md.
    • check-contract on the task contract: enforces the tier-minimum required set (superset rule) and, when required_workflow is tdd, non-empty red_evidence + green_evidence for every test-type check.
    • For an active Project Context with spec_profile: full, whose approved Resolver invocation publishes a Facet Manifest, additionally run python3 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 use python). 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 emitted PASS may satisfy this additional check. Registry selection never waives the preceding legacy contract. Missing/unrun required observations are BLOCKED; 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: lite plus --full), the gate is promoted but the Resolver output remains capability-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 invoke python3 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 use python). This existing adapter validates the Summary and executes its Registry-sourced required Lite checks using the Lite command-discovery contract. The explicit promotion flag satisfies full_upgrade_required: true only 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 a check-component-coverage-verdict/v1 evidence record. Derives one of three states from the project's workflow.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 no project-context.yaml exists 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 has required: 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-coverage is registered in check-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-traceability on specs/<feature>/traceability.json: every REQ → AC → TEST → evidence chain is intact (required for high/critical). For Done tasks, validate specs/<feature>/verification/<task-id>.evidence.json with check-evidence-bundle.(sh|ps1) so the report, contract, and passing evidence artifacts are all bound together. For high/critical the bundle must carry spec_revision, build_env, and review_verdict.verdict == PASS; for critical it must additionally carry a verifiable HMAC signature and a clean tree (git_generated_dirty == true is a hard fail). Always produce the bundle with generate-evidence-bundle.(sh|ps1) — never hand-author sha256 fields or the git_commit field. The runner binds the bundle to the current git commit and computes digests automatically.
  7. For refactor and bugfix tasks with a baseline-behavior.md, apply differential-test-policy.md and classify every BL diff.

  8. Run critical review with an isolated evaluator using evaluation-rubric.md. The evaluator must also apply quality-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), and design-system-checklist.md (user-facing UI in projects carrying a design-system/ contract). Load a checklist only when its domain is in scope, to keep review context lean. On Claude Code use the sdd-evaluator subagent. 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 the x-sdd-effort: comment, retain effort_applied=null and pass --effort-control-main frontmatter (no --effort-applied-main) to emit-run-record, exposing the degradation through the resolved effort_control value (AC-039, AC-024/AC-051).

    On Codex use the shipped sdd-evaluator (or sdd-investigator) TOML agent; do not create new agent role files under ~/.codex/agents/. Codex-host startup wiring (REQ-006, T-006): before launching codex, resolve --model/--effort from 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-investigator for the investigator; --host codex-cli resolves each candidate's effort_control.codex-cli, and --role seeds the role's minimum_tier/fallback effort from role_defaults). Cross-check the resolved model/effort against the # x-sdd-model:/# x-sdd-effort: reference comments T-003's renderer wrote into .codex/agents/sdd-evaluator.toml (or sdd-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 launches codex, the stale reference comment is never silently substituted in either direction (AC-038). Reject any resolved --model/--effort value 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 no codex invocation attempted (AC-052; run-panelist-gpt.sh/.ps1 implement this same rejection for their own --model/--effort arguments — tests/run-panelist-effort.tests.sh/ .ps1 TEST-052). Launch codex with 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 ## Outputs table, or in the ## Post-Fix Artifacts table of a gate report the manifest names in gate_report_declaration and 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's supplemental_delivery_declaration pins a canonical, symlink-free JSON file under specs/<feature>/verification/<task_id>/. Its exact fields are schema (supplemental-delivery-declaration/v1), feature, task_id, implementation_report (the canonical task-report path and its current SHA-256), and artifacts (unique canonical path/SHA-256 pairs). Include the declaration itself in allowed_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 legacy Manifest SHA-256: <hash> citation, declaration v2 adds exactly implementation_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 any Input 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. Broad plugins/, tests/, contracts/, or docs/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-role review-context-invocation/v2 manifest for the evaluator. Set its task_id to the current T-NNN and require the sole implementation report path, report heading, and Task ID field to match that exact task. Bind it to the current SHA-256 and final record hash of the canonical reports/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-pinned task-input-manifest/v1 as an evaluator input and name its path and SHA-256 in implementation_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 canonical scratch_root in 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 is evaluator; the invocation's transport role stays sdd-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 from validation.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.py scratch readback before creating launch output. It then pins dependencies, checks live CLI argv, and runs the shared native permission probe before reservation. Missing or failed preflight-host-review.py HOST_REVIEW_PREFLIGHT_OK proof, 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: run python3 -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. Require EVALUATOR_DELIVERY_OK before 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 to scripts/validate-review-context-set.sh; do not reserve directly and then prepare a fixture. Require EVALUATOR_DELIVERY_OK and REVIEW_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 retains Implementation Complete and 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 through git 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 optional scratch_root field: 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. When scratch_root is present, the deterministic reservation boundary compares it with the current implementation report's Scratch Root and 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 .bak of 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 in sdd-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. For high/critical tasks, record the evaluator's verdict as review_verdict in the evidence bundle; check-evidence-bundle requires review_verdict.verdict == PASS.

  9. Classify findings as Accepted, Rejected, or Deferred. 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 finding Accepted; do not edit the frozen implementation report to reconcile it.

  10. Apply only safe fixes allowed by auto-fix-policy.md.

  11. 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-ticket or an upstream review loop. Do not downgrade a finding merely to end the loop. After escalation, follow Resuming After A Human Decision below.

  12. 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.

  13. Create review-ticket YAML for unresolved or non-auto-fixable findings.

  14. Update traceability and detect drift using integrity-policy.md.

  15. Create reports/quality-gate/<timestamp>.md from plugins/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 with Feature: or Task 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.sh present-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-state without --feature passes 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-risk passes: valid tier + rationale, and high/critical declares Required Workflow: tdd
  • check-contract passes: every required contract check (the tier-minimum superset) is true with existing evidence files; for tdd, test checks carry red_evidence + green_evidence
  • check-traceability passes for high/critical (REQ → AC → TEST → evidence)
  • check-evidence-bundle passes: the bundle names the report, contract, and contract-passing artifacts, with matching hashes and task id; for high/critical it carries spec_revision, build_env, and review_verdict.verdict == PASS; for critical it carries a verified HMAC signature over a clean tree
  • for critical, a second distinct named approver recorded Second Approval: Approved (enforced by check-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:

  1. Confirm reports/quality-gate/<timestamp>.md has been written (step 15 must complete first so the new report is included in retrospective metrics).
  2. Determine the feature path from the task's spec directory (e.g. specs/<feature>).
  3. Check tasks.md for the feature: if any task with Approval: Approved is not yet Status: Done, append [INFO] retrospective deferred: N approved task(s) still pending Done to the quality-gate report and stop here. Invoke retrospective only when every approved task in the feature is Done.
  4. Invoke workflow-retrospective for that feature path:
    • Claude Code: /sdd-quality-loop:workflow-retrospective specs/<feature>
    • Codex: Use the workflow-retrospective skill for specs/<feature>
  5. The retrospective runs in read-only mode and does not affect Done status or any other task field.
  6. If the feature path cannot be determined, skip the retrospective and append a [WARN] retrospective skipped: feature path unknown line 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: false with a non-empty waiver_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: true without a saved evidence path.
  • A handler returning data shaped like the test fixture (completion-faking — Critical).
  • Skipped/todo/xit tests covering in-scope behavior left unaddressed.
  • An acceptance criterion with no test traced to it.
  • Setting Done while 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