ck:quality — Independent Quality Gate & Auditor
ck:quality never fixes code and never writes tests. It evaluates a target against the shared Engineering Quality Contract and returns an evidence-based, structured report. Remediation is always ck:cook's or ck:fix's job — this skill has no --fix.
Modes
Exactly one of:
--gate <phase-file> — pipeline mode. Scope is the files the current phase created or modified. target is the phase file's stem (e.g. phase-02-receipt-gate). Always writes a report to plans/{slug}/quality/{target}-quality-report.json. Hard-blocks the phase on any open BLOCKER/HIGH finding, or a MEDIUM finding introduced by the current change.--audit <path> — standalone mode on any file, directory, or whole repo. Report-only: prints the result, writes nothing to disk unless --save <path> is also given. Never blocks anything outside itself.--diff <ref> — audit only files changed versus <ref> (e.g. main).--changed — audit only the current working-tree diff (staged + unstaged).--verify <report-path> — re-evaluate exactly the findings in an existing report after ck:cook/ck:fix claims they're resolved. Produces a new report of the same shape; does not re-scan unrelated code.
--save <path> is only meaningful with --audit/--diff/--changed.
Step 1 — Resolve Scope and Conventions
- Resolve the target file set:
--gate: the phase file's "Files" section, cross-checked against git diff since the phase's last session-notes timestamp.--audit / --diff / --changed: the given path, diff range, or working tree respectively.--verify: the reviewed_files list from the report being verified, refreshed against current git diff in case scope grew.
- Detect the stack(s) present in scope (
package.json+.ts → TypeScript/Node, pyproject.toml/*.py → Python, *.csproj → .NET, etc. — see references/adapters.md).
- Read 2-3 sibling files outside the changed set to learn actual naming, constants/error, module-structure, and DI conventions already in use. Existing convention always outranks a generic rule.
Step 2 — Load Contract
Always load the Core tier of references/core-contract.md. Load Context-module sections only for categories relevant to what's in scope (e.g. skip TXN/transactions entirely if nothing touches persistence). Load only the references/adapters.md section(s) matching detected stacks — never load an adapter for a stack not present.
For --gate, also read the phase file's own Design Constraints / Quality Acceptance Criteria, if present, and treat them as additional applicable rules for this phase.
Step 3 — Evaluate
If a named quality-reviewer agent is available, spawn it with the resolved target files, detected conventions, loaded contract sections, and (gate mode) the phase constraints. Otherwise perform this evaluation inline using the same inputs and report schema. The inline path is required for Codex, Antigravity, and standalone installations that copy only the skill directory; it must not weaken severity or evidence requirements.
A candidate issue becomes a finding only when:
- It's evidence-based — cites the exact snippet/line, not "consider improving X".
applicable: true and a confidence level are stated. A rule that doesn't clearly apply here is skipped, not force-reported at low confidence.introduced_by_current_change is determined from git blame/diff evidence, not assumed.
Consolidate duplicate root causes across files into one finding referencing all locations, rather than one finding per line.
Step 4 — Severity and Verdict
| Severity | Gate behavior |
|---|
BLOCKER | Always blocks |
HIGH | Always blocks |
MEDIUM | Blocks only if introduced_by_current_change: true |
LOW | Never blocks |
NOTED | Pre-existing debt or out-of-scope suggestion; never blocks |
--audit/--diff/--changed compute the same verdict for information only — they never block anything outside the call itself.
Verdict is APPROVED (zero open blocking findings) or CHANGES_REQUIRED (at least one).
Step 5 — Report
Produce a report matching references/report-schema.json. --gate and --verify always write it to plans/{slug}/quality/{target}-quality-report.json ({target} is the phase file stem, e.g. phase-02-receipt-gate); --audit/--diff/--changed print it and only write with --save <path>.
If the verdict is APPROVED and the mode is --gate or --verify, issue the receipt immediately after writing the report:
python {ck-quality-skill-root}/scripts/receipt.py issue plans/{slug}/quality/{target}-quality-report.json
Resolve {ck-quality-skill-root} from the SKILL.md currently loaded (for example skills/ck-quality, .claude/skills/ck-quality, .codex/skills/ck-quality, or .agents/skills/ck-quality). Never assume one client-specific install path.
This writes plans/{slug}/quality/{target}-receipt.json, which hooks/quality_receipt_gate.py checks before allowing the phase's completion transition. --audit/--diff/--changed never issue a receipt, even with --save — they have no phase target for a hook to gate.
Print exactly:
[ck:quality] {mode} → {APPROVED | CHANGES_REQUIRED}
Target: {scope}
Findings: {N} blocking, {N} advisory, {N} noted
Report: {path, or "not saved (use --save to persist)"}
Receipt: {path, or "not issued (mode does not gate a phase, or verdict is CHANGES_REQUIRED)"}
If CHANGES_REQUIRED, list every blocking finding's id, rule, location, and required_action — this is exactly what ck:cook/ck:fix consumes to remediate.
Constraints
- Multi-repo layout:
plans/{slug} and the reviewed code do not need to share one git repo. receipt.py computes the filesystem common ancestor of the report and every reviewed_files entry at issue time (e.g. a shared workspace folder like pte-org/ above sibling repos pte-doc/ and pte-api/, even if that folder itself isn't a git repo) and records it in the receipt, so verify never has to re-derive it. reviewed_files entries just need a path resolvable from the current working directory (relative with ../ segments across repos, or absolute).
- Never edit a file. Never write, run, or suggest test code — that's
ck:test's job.
- Issuing a receipt is a mechanical fingerprint step performed by
scripts/receipt.py, invoked only after this skill itself reaches APPROVED in --gate/--verify mode — never invoke it for a CHANGES_REQUIRED report, and never invoke it from --audit/--diff/--changed. A receipt proves report/file freshness, not the correctness of the semantic review.
--audit/--diff/--changed without --save never write to disk.- If asked to "just fix it" or "apply the finding", refuse and point to
ck:cook/ck:fix — evaluating and fixing stay separate even when both happen in the same session.
Full rule catalogue: references/core-contract.md. Stack-specific rules: references/adapters.md. Exact report/finding shape: references/report-schema.json. Exact receipt shape: references/receipt-schema.json.