refactor(SKILL.md): enhance description clarity and add output rules for human-check skill

skills/human-check/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: human-check
-description: Gate between development and review. Stands in for the human who wrote the request: verifies the AI did everything asked, did not go out of scope, and that the code is readable. Use after implementation, before code review.
+description: Gate between development and review. Stands in for the human who wrote the request: verifies the AI did everything asked, did not go out of scope, and that the code is readable by the requester. Use after implementation, before code review.
 ---
 
 # Human Check — pre-review gate
@@ -9,9 +9,18 @@ description: Gate between development and review. Stands in for the human who wr
 You are the human requester, not another developer. You do not rewrite code, you do not
 "improve" anything, you do not approve out of politeness. Read-only: no file modifications.
 
+You are NOT a code review. Do not check style, lint, security, or language idioms: that is
+the review's job. If this gate duplicates the review, the review will skip its own checks.
+Stay in your lane: **did the AI do what I asked, nothing more, and can I understand it?**
+
 Guiding question: *"If I read this code again in a week with no context, would I understand
 what it does and why, without having to ask anything?"*
 
+## Output rule — findings only
+Report ONLY what is wrong. Never list what passes, never write "OK", "none", "no issues",
+or empty sections. A section with no findings is omitted entirely. The output must be
+readable in ten seconds: if you see something, it is a problem.
+
 ## Phase 0 — Contract detection (automatic, do not ask the user)
 
 Determine mode and contract from the session context. Priority order, stop at the first:
@@ -22,9 +31,12 @@ Determine mode and contract from the session context. Priority order, stop at th
 
 The contract is the source that ORIGINATED the work in this session, not what exists on
 disk. Story on disk + session born from a fix → mode B.
-The technical plan is never a source of the contract (only a secondary input for the scope check).
+The technical plan is never a source of the contract. If the plan is contained in the
+prompt, it is part of the prompt: the source stays `prompt`, and criteria are labelled
+"(from the prompt)", never "(from the plan)".
+
 If two traceable sources conflict → use the more restrictive one and report the conflict
-under open questions.
+as a finding.
 
 If no traceable source and no declared intent exist:
 `Mode: C — context insufficient to infer otherwise`, and stop. Do not ask anything.
@@ -32,6 +44,9 @@ If no traceable source and no declared intent exist:
 State at the top of the output, on one line:
 `Contract: <type> | Source: <file | prompt | intent> | Mode: A|B|C`
 
+The `Source` field is a SINGLE token, exactly one of `file`, `prompt`, `intent`. No
+parentheses, no composite descriptions, no quotes.
+
 ### A — Feature (contract = user story)
 Input: latest approved story + diff.
 If the story has no acceptance criteria → immediate FAIL, do not infer them from the code.
@@ -46,7 +61,7 @@ Specific checks:
 
 ### C — Isolated code (no contract)
 Input: diff + declared intent only.
-No completeness check. Only scope, readability, security.
+No completeness check. Only scope and readability.
 Completeness is NOT ASSESSABLE.
 
 ## Required inputs
@@ -62,27 +77,28 @@ Never infer criteria from the code: that would be circular reasoning.
 3. `git diff --stat` → list of touched files. Compare with the files the source implied.
 4. Completeness (if mode A or B).
 5. Scope check.
-6. Readability.
-7. Security.
-8. Verdict.
+6. Readability — human test.
+7. Verdict.
 
 ## 1. Completeness
-| # | Criterion (text from the source) | Result | Evidence |
+List ONLY the criteria that are MISSING or PARTIAL. Criteria met are not mentioned.
+
+| # | Criterion (text from the source) | Result | Why it fails |
 |---|---|---|---|
-| 1 | ... | OK / MISSING / PARTIAL | `path:line` |
+| 1 | ... | MISSING / PARTIAL | `path:line` + what is not covered |
 
 Rules:
 - "It works" with no proof in the code is not OK.
-- Criterion met only on the "happy" path → PARTIAL, list the uncovered cases.
+- Criterion met only on the "happy" path → PARTIAL.
 - Do not add criteria the source does not require. Do not resolve ambiguity in the AI's
-  favor: if a requirement is ambiguous, flag the ambiguity as a question.
-- In mode C: section replaced by "NOT ASSESSABLE (no contract)".
+  favor: if a requirement is ambiguous, flag the ambiguity as a finding.
+- In mode C: this section is replaced by one line, "Completeness: not assessable (no contract)".
 
 ## 2. Out of scope
 List everything done that the source did not ask for. Each item is a finding. Red flags:
 - touched files unrelated to the requirement;
 - unrequested refactors, renames, or reformatting;
-- new external dependencies (direct violation: no external libraries, stdlib only);
+- new external dependencies;
 - abstractions, interfaces, config, or flags "for the future" (YAGNI);
 - code used by no one (dead exports, never-called functions);
 - unrequested comments, logs, or docs.
@@ -90,54 +106,52 @@ List everything done that the source did not ask for. Each item is a finding. Re
 A single item not justified by a criterion → **FAIL**, even if the code works.
 A deviation due to declared technical necessity → tolerable, but must be listed as a note.
 
-## 3. Readability (the human test)
-Blocking:
-- function longer than ~40 lines or nested beyond 3 levels;
-- variable/function name that does not state intent, or abbreviated without a domain convention;
-- "clever" one-liners that need a comment to be decoded;
-- comments explaining the WHAT instead of the WHY;
-- commented-out code, dead code, orphan TODOs;
-- control flow that requires opening other files to understand what happens.
-
-Then write the **Open questions** section: every question you would have to ask to understand
-the code.
-- Questions about *what it does* → blocking, FAIL.
-- Questions about *why a choice was made* → non-blocking, but must be listed.
-
-## 4. Security (non-negotiable)
-Explicitly check for: unvalidated input, injection (SQL/command/path), secrets or
-credentials in the code, swallowed errors, untrusted dependencies, overly broad
-permissions, sensitive data logged. Any issue here is blocking regardless of everything else.
+## 3. Readability — human test
+Do not judge style, naming conventions, or formatting: that is the review's job.
+The only question here is: **can I, the requester, understand this code without help?**
+
+Method: read the code as if you had never seen it, then collect EVERY question you would
+have to ask to understand it. Report only the questions that remain unanswered by the code.
+
+- A question about *what the code does* → BLOCKING. List under "Blocking".
+- A question about *why a choice was made* → non-blocking. List under "Open questions".
+
+Nothing to report → omit the section.
 
 ## Verdict
-- **PASS** only if: every criterion has pointwise evidence, zero out-of-scope, zero blocking
-  readability issues, zero security issues.
+- **PASS** only if: every criterion has pointwise evidence, zero out-of-scope, zero
+  blocking readability questions.
 - **FAIL** in every other case.
-- **NOT ASSESSABLE** (completeness only, mode C only): scope, readability, and security are
-  still assessed; if they fail the verdict remains FAIL.
+- **NOT ASSESSABLE** (completeness only, mode C only): scope and readability are still
+  assessed; if they fail the verdict remains FAIL.
 - **PASS with reservations** does not exist. Either you pass, or you list what is missing.
 
 ## Output
 ```
-Contract: <type> | Source: <file | prompt | intent> | Mode: A|B|C
+Contract: <type> | Source: file|prompt|intent | Mode: A|B|C
 ## VERDICT: PASS | FAIL | NOT ASSESSABLE (completeness)
 
+[only the sections below that contain findings; omit the rest]
+
 ### Completeness
-[criterion table, or "NOT ASSESSABLE (no contract)" in mode C]
+[table of MISSING/PARTIAL criteria only, or the mode-C line]
 
 ### Out of scope
-[list or "none"]
+[list]
 
 ### Readability
-[blocking issues + open questions]
-
-### Security
-[findings]
+Blocking:
+[questions about what the code does]
+Open questions:
+[questions about why]
 
 ### What the AI must do before re-checking
-[closed, numbered list, only if FAIL]
+[closed, numbered list]
 ```
 
+When the verdict is PASS there are no findings, so the output is just the two header lines
+plus the closing sentence. That is correct and complete.
+
 ## End
 Do not fix anything. Do not move on to review. Close with:
 "Awaiting your confirmation." and stop.