@lovehlmmm/primekit 1.0.0

package/skills/review-pr/references/anti-ai-slop.md

@@ -0,0 +1,235 @@
+# Anti AI-Slop Reference
+
+Concrete taxonomy of "AI slop" code patterns the reviewer should flag, with detection heuristics, fix guidance, and calibration on when **not** to flag.
+
+## Why this matters
+
+LLM-assisted contributions often produce code that *compiles, passes tests, and looks reasonable per-file* — but pollutes the codebase at the aggregate. Common drivers:
+
+- Low-quality LLMs that pattern-match without understanding constraints
+- Contributors who don't read their own diffs before pushing
+- Lack of engineering judgment to push back on agent suggestions
+- Coding agents that prioritize "doing something" over "doing nothing when the right answer is no change"
+
+The result is **code rác** (garbage code) and **code dư thừa** (redundant code) that look harmless individually but compound. This reference gives the reviewer the lens to spot it.
+
+---
+
+## Section 1: Structural slop (high impact — flag as **Important**)
+
+One bad call here infects 100 files later. Always flag.
+
+### 1.1 Dumping-ground new files
+**Pattern**: New file at `utils/helpers.ts`, `lib/common/index.ts`, `services/manager.ts`, `core/utils.go`.
+**Why bad**: Generic name = no domain anchor. The next agent dumps more there. Within 6 months it's a 2000-line junk drawer.
+**Detection**: `git diff --name-status --diff-filter=A` for new files with generic names in dumping-ground dirs.
+**Fix**: Rename to a domain-anchored name (`token-bucket-rate-limit.ts`, not `rate-limit-helper.ts`). Or move the function into the only file that calls it.
+
+### 1.2 Parallel reimplementation
+**Pattern**: New `formatDate()` / `slugify()` / `chunk()` / HTTP retry wrapper when the repo already has one.
+**Why bad**: Two implementations diverge over time. Bugs get fixed in one but not the other.
+**Detection**: Grep the repo for similar function names or behavior before approving any new utility.
+**Fix**: Use the existing one. If the existing one is inadequate, *extend* it — don't fork it.
+
+### 1.3 Premature abstraction
+**Pattern**: New interface + factory + builder + adapter for a feature with one implementation and two callers.
+**Why bad**: Abstraction cost (indirection, mental load, test surface) paid up front without the payoff (multiple implementations) that justifies it.
+**Detection**: Count concrete implementations of any new interface. One = premature.
+**Fix**: Inline the concrete type. Add the abstraction when the second implementation actually shows up.
+
+### 1.4 Config flag for what should be a constant
+**Pattern**: New env var or config field `ENABLE_X`, `USE_NEW_Y`, `FEATURE_Z_ENABLED` for behavior that should be hardcoded.
+**Why bad**: Will never be turned off. Becomes documentation lag and a foot-gun. Doubles the test matrix.
+**Detection**: Any new config field — ask "would we actually flip this in production? If no, why is it a flag?"
+**Fix**: Pick the value, hardcode it. Delete the flag plumbing.
+
+### 1.5 Schema/contract change without migration
+**Pattern**: PR adds a NOT NULL column, renames a field, changes a response shape — no migration, no backward-compat shim.
+**Why bad**: Breaks deployed clients or existing data.
+**Detection**: Diff touches DB schema, API DTOs, public types, or persisted config formats.
+**Fix**: Add migration, deprecation path, or version the contract.
+
+### 1.6 God-file growth
+**Pattern**: A 180-line file grows to 450 in one PR. Project's stated size limit (often 200 lines) ignored.
+**Why bad**: Files become unreadable. Context loads become expensive. The next agent has even less room to work cleanly.
+**Detection**: `wc -l` on modified files in the diff vs project size convention.
+**Fix**: Split before merge. Group related additions into a new focused module.
+
+### 1.7 Phantom dependencies
+**Pattern**: `package.json` / `go.mod` / `requirements.txt` adds a dep — diff doesn't actually import it, OR imports it for one trivial call that the language stdlib already supports.
+**Why bad**: Supply chain risk, install size, transitive vulnerabilities — all for nothing.
+**Detection**: Cross-check dep additions against actual `import`/`require`/`use` lines in the diff.
+**Fix**: Remove the dep, inline the trivial call, or use stdlib.
+
+---
+
+## Section 2: Micro slop (each instance small — flag as **Suggestion**)
+
+Don't block merges, but call out. Aggregate is rot.
+
+### 2.1 Defensive paranoia
+**Pattern**: `try/catch` around code that cannot throw. Null checks on typed-non-null parameters. "Just in case" guards before stdlib calls that already validate.
+**Fix**: Delete the guard. Trust the types and the stdlib.
+
+### 2.2 Catch-and-swallow
+**Pattern**: `catch (e) { console.log(e) }`, `catch { return null }`, `except: pass`.
+**Fix**: Either handle the error meaningfully (retry, fallback, user message) or let it propagate. Logging-and-continuing is a bug factory.
+
+### 2.3 Comment paraphrasing
+**Pattern**: `// increment counter` next to `counter++`. `// returns the user's name` above `getUserName()`.
+**Fix**: Delete. Comments should explain *why*, not narrate *what*.
+
+### 2.4 Generic error messages
+**Pattern**: `"An error occurred. Please try again."`, `throw new Error("Failed")`, `return errors.New("error")`.
+**Fix**: Include the operation, the inputs, and the failure mode. `"failed to fetch user %d: %w"`.
+
+### 2.5 One-line wrappers
+**Pattern**: `function getName(u) { return u.name }`. Adds indirection, hides nothing.
+**Fix**: Inline. Delete the wrapper.
+
+### 2.6 Reimplementing stdlib
+**Pattern**: Custom `chunk`, `range`, `groupBy`, `debounce`, `deepEqual` when language stdlib or an existing dep covers it.
+**Fix**: Use the stdlib/dep. If you don't trust the dep, that's a separate decision worth flagging upward.
+
+### 2.7 Silencing the linter
+**Pattern**: `any` widening, `@ts-ignore`, `@ts-expect-error`, `// eslint-disable`, `# noqa`, `//nolint` introduced to hide a warning instead of resolving it.
+**Detection**: `git diff | grep -E '^\+.*(any|@ts-ignore|@ts-expect-error|eslint-disable|noqa|nolint)'`
+**Fix**: Resolve the underlying issue. Use these only with a comment explaining why the linter is wrong.
+
+### 2.8 Phantom test coverage
+**Pattern**: Tests that exercise lines without meaningful assertions: `expect(result).toBeTruthy()` on a value that's always truthy; `assert result is not None` when the function can't return None.
+**Fix**: Assert on the actual behavior — value, side effect, error.
+
+### 2.9 Mock-of-a-mock
+**Pattern**: Tests where 80% of setup is mocking, and the assertions verify the mock got called — not that the SUT did the right thing.
+**Fix**: Use real implementations where possible. Mock only at integration boundaries.
+
+### 2.10 Unused symbols introduced
+**Pattern**: New imports, exports, parameters, or variables in the diff that nothing references.
+**Detection**: Language linter (`tsc --noUnusedLocals`, `go vet`, `pyflakes`, `ruff`).
+**Fix**: Delete.
+
+### 2.11 Magic numbers
+**Pattern**: `if (retries > 7)`, `setTimeout(fn, 3600000)`, `if (status === 418)`.
+**Fix**: Name the constant. `const MAX_RETRIES = 7`.
+
+### 2.12 Style inconsistency
+**Pattern**: New code uses arrow functions / camelCase / async-await / a different formatter than the rest of the file.
+**Fix**: Match the surrounding file. The reviewer should not have to think about style.
+
+---
+
+## Section 3: Process slop (PR-level signals)
+
+Look across the whole diff, not per-file.
+
+### 3.1 Scope mismatch
+**Signal**: PR title says "fix typo" but diff is +800/−60 across 12 files.
+**What it means**: Author wasn't watching what the agent did, OR the title is wrong.
+**Action**: Ask for the PR to be split into focused commits, or ask the author to rewrite the title/description.
+
+### 3.2 Unrelated files
+**Signal**: "Fix auth bug" PR also rewrites a logging helper, reorders imports in 5 unrelated files, bumps a dep.
+**Action**: Ask the author to separate the unrelated changes into their own PR.
+
+### 3.3 Tests missing or skipped
+**Signal**: Production code changed; no test changes. Or test changes are `it.skip()` / `t.Skip()` / `@pytest.mark.skip` on previously-passing tests.
+**Action**: Block until tests cover the new path, or the skips are justified in the PR description.
+
+### 3.4 Docs claim features that don't exist
+**Signal**: README, changelog, or doc updates describe behavior the diff doesn't implement.
+**Action**: Either the docs are aspirational (remove), or the implementation is incomplete (block).
+
+### 3.5 Commit messages with LLM-style fluff
+**Signal**: Commits titled "Improve code quality and enhance maintainability", "Refactor for clarity", "Update various files".
+**What it means**: Author didn't read the diff before committing.
+**Action**: Informational. Mention it in the review — recommend conventional-commits format with the *actual* change described.
+
+---
+
+## Section 4: How to phrase the finding
+
+Slop findings are *judgment calls*. Bug findings are not. The reviewer LLM tends to swing between "aggressive style cop" and "too polite to flag anything". Both fail.
+
+### Good phrasing
+
+- **State the cost, not the rule.** "This abstraction has one caller and one implementation — the indirection adds 15 lines of test surface without enabling a second use case. Consider inlining until a second caller appears."
+- **Tie to a concrete future risk.** "Naming the file `utils/helpers.ts` invites future additions. Within 6 months this file tends to grow to 1000+ lines. Suggest renaming to `<domain-specific-name>.ts`."
+- **Offer the alternative.** Don't just flag — say what good looks like.
+- **Acknowledge it's a call.** "This is a Suggestion, not a blocker. If you have a use case in mind for the second implementation, leave it."
+
+### Bad phrasing
+
+- "This is AI slop." — accusatory, unhelpful, often wrong.
+- "This violates DRY/YAGNI/SOLID." — principle-thumping. State the concrete cost instead.
+- "Please refactor." — vague. Refactor *how*?
+- "I don't like this." — preference dressed as review.
+
+---
+
+## Section 5: When NOT to flag
+
+The witch-hunt is the failure mode opposite to the slop. Calibrate:
+
+- **Humans also write defensive code.** A `null` check at a system boundary (API input, external response) is correct — don't flag it as paranoia.
+- **One-line wrappers can earn their weight** when they name a domain concept. `function isWeekend(d) { return d.getDay() === 0 || d.getDay() === 6 }` is fine.
+- **Try/catch around legacy code with unknown failure modes** is a reasonable hedge while the code is being understood.
+- **Abstractions can be intentional** if the author knows the second implementation is coming in the next PR. Ask, don't assume.
+- **Verbose error messages** are appropriate at log/user boundaries even when they feel chatty.
+- **Repetitive code** is fine if the alternatives (abstraction, metaprogramming) cost more than the duplication. Rule of three.
+- **Tests that look thin** may be intentional smoke tests for a path that's hard to exercise more deeply.
+- **Magic numbers in tests** are often more readable than named constants. `expect(result).toEqual(42)` doesn't need `EXPECTED_MEANING_OF_LIFE`.
+
+Rule of thumb: if you cannot articulate the **concrete cost** of the pattern in this specific codebase, do not flag it.
+
+---
+
+## Section 6: Stack-specific appendix
+
+Concrete examples from common stacks. Use these as templates for finding language.
+
+### 6.1 Go
+
+- **Error wrapping**: `fmt.Errorf("doing X: %w", err)` — wrapping with `%w` preserves the chain. `fmt.Errorf("doing X: %v", err)` *loses* the chain. Flag the latter.
+- **`if err != nil { return err }`** is canonical Go — do **not** flag it as defensive paranoia.
+- **`interface{}` / `any` parameter** introduced where a concrete type would do — flag.
+- **`for rows.Next()` loop missing `rows.Err()` check** — `database/sql` requires it. Bug, not slop.
+- **goroutine launched without lifetime owner** (no `context`, no `wg`, no channel return) — leak risk.
+- **Mutex by value embedded in a struct that gets copied** — silent data race.
+
+### 6.2 React / TypeScript
+
+- **`useEffect` with empty deps doing data fetch** — usually wants `useEffect` + `AbortController`, or better, the data-fetch lib already in the project (React Query, SWR, tRPC).
+- **`useState` for derived state** that should be a memoized computation.
+- **Inline anonymous functions in props** are usually fine — don't flag them as performance issues unless profiling shows otherwise.
+- **`any` in component props** — flag. Components are the public contract of the UI layer.
+- **New context provider for state that two siblings share** — premature; lift state to the parent or use the project's state lib.
+- **Component file >200 lines** mixing data fetching, business logic, and rendering — split.
+
+### 6.3 Tailwind / CSS
+
+- **Arbitrary values everywhere** (`h-[473px]`, `text-[#3a5b71]`) — should use design tokens or the closest scale value.
+- **`!important` (`!h-screen`)** introduced to override — almost always wrong; find the source of the cascade conflict.
+- **`h-screen` on mobile-facing UI** — breaks on iOS Safari (chrome + virtual keyboard). Prefer `h-dvh` or `min-h-dvh`.
+- **Fixed `grid-cols-N` without mobile breakpoint** — should be `grid-cols-1 sm:grid-cols-2 lg:grid-cols-N`.
+- **`<input>` / `<textarea>` with `text-sm` only** — font-size <16px triggers iOS Safari auto-zoom on focus. Use `text-base md:text-sm`.
+- **Inline `style={{...}}` for things Tailwind covers** — should use a class.
+
+### 6.4 SQL / migrations
+
+- **String concatenation building SQL** with user input — injection. Always parameterize.
+- **`SELECT *` in production queries** — fragile to schema change, fetches unused columns.
+- **Migration that's not idempotent** — re-running it fails. Use `IF NOT EXISTS` / `IF EXISTS` where appropriate.
+- **NOT NULL column added without DEFAULT or backfill** — breaks deployed code reading old rows.
+- **Index added on a low-cardinality column** without justification — waste.
+- **`ORDER BY` / `WHERE` on a column with no index** in a query expected to be hot — performance landmine.
+
+---
+
+## How to use this reference
+
+1. Read the relevant section based on the slop signals from the inline SKILL.md checklist.
+2. Match the pattern to a section here.
+3. Use the **phrasing** guide (Section 4) to write the finding.
+4. Apply the **severity rule** from SKILL.md: structural (§1, §3) → Important; micro (§2) → Suggestion.
+5. If unsure whether to flag, re-read Section 5 ("When NOT to flag") first.

package/skills/review-pr/references/gh-api-helpers.sh

@@ -0,0 +1,185 @@
+# GitHub API compatibility helpers for ak:review-pr.
+#
+# Source this file from every per-PR bash block using the multi-install-path
+# loader below (project-scoped installs, user-scoped installs, the AgentKit
+# monorepo checkout, and a plugin-delivered install):
+#
+#   _ak_lib=.claude/skills/ak-review-pr/references/gh-api-helpers.sh
+#   [ -f "$_ak_lib" ] || _ak_lib="${HOME:-}/.claude/skills/ak-review-pr/references/gh-api-helpers.sh"
+#   [ -f "$_ak_lib" ] || _ak_lib=kits/core/skills/ak-review-pr/references/gh-api-helpers.sh
+#   [ -f "$_ak_lib" ] || { (set +u; [ -n "${CLAUDE_PLUGIN_ROOT}" ]) && _ak_lib="${CLAUDE_PLUGIN_ROOT}/skills/ak-review-pr/references/gh-api-helpers.sh"; }
+#   [ -f "$_ak_lib" ] || { echo "gh-api-helpers.sh not found" >&2; exit 1; }
+#   . "$_ak_lib"
+#
+# Also sourced by `ak:git` merge-pr workflow to keep GraphQL/REST branching
+# consistent across skills.
+#
+# Falls the skill back to REST when the GitHub GraphQL API is blocked at the
+# proxy (e.g. Claude Cloud Environment). Read commands honour AK_GH_REST;
+# write commands try native `gh pr …` first and fall back to REST via
+# `gh api repos/{o}/{r}/…` on a GraphQL-not-enabled error or when the probe
+# already reported `AK_GH_REST=1`.
+
+# Detect GraphQL availability. Sets AK_GH_REST=1 when GraphQL is blocked.
+# Idempotent — safe to call many times per run.
+_ak_probe_gh_api() {
+  if [ -n "${AK_GH_REST_PROBED:-}" ]; then
+    return 0
+  fi
+  AK_GH_REST=0
+  if ! gh api graphql -f query='{__typename}' >/dev/null 2>&1; then
+    AK_GH_REST=1
+  fi
+  AK_GH_REST_PROBED=1
+  export AK_GH_REST AK_GH_REST_PROBED
+}
+
+# Parse a PR ref into "owner repo number".
+# Accepts: 123 | #123 | https://github.com/OWNER/REPO/pull/123
+_ak_split_pr() {
+  local ref="${1#\#}"
+  if [[ "$ref" =~ ^https?://github\.com/([^/]+)/([^/]+)/pull/([0-9]+) ]]; then
+    printf '%s %s %s\n' "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}" "${BASH_REMATCH[3]}"
+    return 0
+  fi
+  # Resolve OWNER/REPO from the git remote URL (no API call, works even when
+  # GraphQL is blocked and `gh repo view` fails). `|| true` shields callers
+  # running under `set -e` when the named remote is absent.
+  local url
+  url="$(git remote get-url upstream 2>/dev/null || true)"
+  [ -n "$url" ] || url="$(git remote get-url origin 2>/dev/null || true)"
+  local slug=""
+  if [ -n "$url" ]; then
+    # Strip trailing .git and any URL prefix (https://…/, git@…:, ssh://…/).
+    slug="${url%.git}"
+    slug="${slug##*github.com[/:]}"
+    slug="${slug##*github.com/}"
+  fi
+  # Last-resort: try gh (works only when GraphQL is available).
+  if [ -z "$slug" ] || [[ ! "$slug" =~ ^[^/]+/[^/]+$ ]]; then
+    slug="$(gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null || true)"
+  fi
+  # Final validation — enterprise GHE remotes and unrelated remotes can leave
+  # garbage here.
+  if [ -z "$slug" ] || [[ ! "$slug" =~ ^[^/]+/[^/]+$ ]]; then
+    echo "ak-review-pr: cannot resolve OWNER/REPO — pass a full PR URL or run inside a github.com-linked repo (got: '$slug')" >&2
+    return 1
+  fi
+  printf '%s %s %s\n' "${slug%/*}" "${slug#*/}" "$ref"
+}
+
+# PR JSON metadata — mirrors `gh pr view --json …`.
+_ak_pr_meta() {  # $1=owner $2=repo $3=number
+  _ak_probe_gh_api
+  if [ "$AK_GH_REST" = 1 ]; then
+    gh api "repos/$1/$2/pulls/$3"
+  else
+    gh pr view "$3" --repo "$1/$2" \
+      --json number,title,body,author,state,mergeable,mergeStateStatus,reviewDecision,baseRefName,headRefName,additions,deletions,changedFiles,url,headRefOid,files
+  fi
+}
+
+# Unified diff for the PR.
+_ak_pr_diff() {  # $1=owner $2=repo $3=number
+  _ak_probe_gh_api
+  if [ "$AK_GH_REST" = 1 ]; then
+    gh api "repos/$1/$2/pulls/$3" -H "Accept: application/vnd.github.v3.diff"
+  else
+    gh pr diff "$3" --repo "$1/$2"
+  fi
+}
+
+# Changed file list (one path per line).
+_ak_pr_files() {  # $1=owner $2=repo $3=number
+  _ak_probe_gh_api
+  if [ "$AK_GH_REST" = 1 ]; then
+    gh api "repos/$1/$2/pulls/$3/files" --paginate --jq '.[].filename'
+  else
+    gh pr diff "$3" --repo "$1/$2" --name-only
+  fi
+}
+
+# CI check summary. Prints `<name>\t<status>\t<conclusion>\t<url>` per run,
+# or "No checks found" when there are no runs.
+_ak_pr_checks() {  # $1=owner $2=repo $3=number
+  _ak_probe_gh_api
+  if [ "$AK_GH_REST" = 1 ]; then
+    local sha
+    sha="$(gh api "repos/$1/$2/pulls/$3" --jq .head.sha 2>/dev/null)"
+    [ -n "$sha" ] || { echo "No checks found"; return 0; }
+    local out
+    out="$(gh api "repos/$1/$2/commits/$sha/check-runs" --paginate \
+      --jq '.check_runs[] | "\(.name)\t\(.status)\t\(.conclusion // "")\t\(.html_url)"' 2>/dev/null)"
+    if [ -z "$out" ]; then
+      echo "No checks found"
+    else
+      printf '%s\n' "$out"
+    fi
+  else
+    gh pr checks "$3" --repo "$1/$2" 2>/dev/null || echo "No checks found"
+  fi
+}
+
+# PR body only — for feeding into pr-body-contract.cjs.
+_ak_pr_body() {  # $1=owner $2=repo $3=number
+  _ak_probe_gh_api
+  if [ "$AK_GH_REST" = 1 ]; then
+    gh api "repos/$1/$2/pulls/$3" --jq .body
+  else
+    gh pr view "$3" --repo "$1/$2" --json body -q .body
+  fi
+}
+
+# Post a formal review. Reads body from stdin.
+# $1=owner $2=repo $3=number $4=event (APPROVE|REQUEST_CHANGES|COMMENT)
+_ak_pr_review() {
+  _ak_probe_gh_api
+  local body
+  body="$(cat)"
+  local flag
+  case "$4" in
+    APPROVE)         flag="--approve" ;;
+    REQUEST_CHANGES) flag="--request-changes" ;;
+    COMMENT)         flag="--comment" ;;
+    *) echo "ak-review-pr: invalid review event: $4" >&2; return 2 ;;
+  esac
+  # When the probe already reports REST-only, skip the native attempt.
+  if [ "$AK_GH_REST" = 1 ]; then
+    printf '%s' "$body" | gh api "repos/$1/$2/pulls/$3/reviews" -f "event=$4" -F "body=@-"
+    return $?
+  fi
+  local err
+  if err="$(printf '%s' "$body" | gh pr review "$3" --repo "$1/$2" "$flag" --body-file - 2>&1)"; then
+    printf '%s\n' "$err"
+    return 0
+  fi
+  # Native failed — try REST once (covers proxy-side GraphQL blocks the probe
+  # missed and error-message wording drift across gh versions).
+  if printf '%s' "$body" | gh api "repos/$1/$2/pulls/$3/reviews" -f "event=$4" -F "body=@-" 2>/dev/null; then
+    return 0
+  fi
+  # Surface the original native error.
+  printf '%s\n' "$err" >&2
+  return 1
+}
+
+# Post an issue/PR comment. Reads body from stdin.
+_ak_pr_comment() {  # $1=owner $2=repo $3=number
+  _ak_probe_gh_api
+  local body
+  body="$(cat)"
+  if [ "$AK_GH_REST" = 1 ]; then
+    printf '%s' "$body" | gh api "repos/$1/$2/issues/$3/comments" -F "body=@-"
+    return $?
+  fi
+  local err
+  if err="$(printf '%s' "$body" | gh pr comment "$3" --repo "$1/$2" --body-file - 2>&1)"; then
+    printf '%s\n' "$err"
+    return 0
+  fi
+  if printf '%s' "$body" | gh api "repos/$1/$2/issues/$3/comments" -F "body=@-" 2>/dev/null; then
+    return 0
+  fi
+  printf '%s\n' "$err" >&2
+  return 1
+}

package/skills/review-pr/references/pr-body-contract.md

@@ -0,0 +1,53 @@
+# Evidence-rich PR body contract (#1195)
+
+`pk:ship` must create/update PR bodies with these sections (headings localized
+to the effective writing language; English forms shown). Validate with:
+
+```bash
+gh pr view "$PR" --json body -q .body | PR_BIN=.claude/hooks/lib/pr-body-contract.cjs
+test -f "$PR_BIN" || PR_BIN=kits/core/hooks/lib/pr-body-contract.cjs
+node "$PR_BIN"
+```
+
+## Required sections
+
+### 1. End-to-end work summary
+Workflow from task/issue/plan → implementation → verification → review → ship.
+Facts only; do not invent steps that did not run.
+
+### 2. Subagent delegation
+Count used. For each: role, task, status, concise result. If none: say so.
+
+### 3. Technical decisions
+Material decisions + rationale/evidence. Do not fabricate filler.
+
+### 4. Deviations from plan
+Compare to the active plan when one exists. If none/no deviations: state that.
+
+### 5. Completion evidence
+Map acceptance criteria to tests, commands, artifacts, review, CI. UI/UX PRs
+need relevant screenshots (or an explicit unavailable reason). Non-UI PRs must
+not add decorative screenshots.
+
+### 6. Checklist
+Completed vs incomplete/skipped with reasons. Never mark unknown work done.
+
+### 7. Human actions required
+Decisions, credentials, manual QA, rollout, approvals. If none: `None` (localized).
+
+## Traceability (retain)
+
+Fold prior ship fields into this body without duplicating facts:
+
+- **Linked Issues** (`Closes #N` / `Relates to #N`)
+- Pre-landing review outcome (under Completion evidence or Checklist)
+- Test results (under Completion evidence / Checklist)
+- Diff/changes summary (under Completion evidence)
+- **Ship Mode** (mode + target branch)
+
+## `pk:review-pr` validation
+
+- Missing required sections → **Important** findings.
+- Unsupported claims / empty evidence where evidence is asserted → **Important**.
+- Missing Linked Issues / Ship Mode on ship-authored PRs → **Suggestion**.
+- Do not pad sections; prefer honest `None` / `Not run` / `Unavailable`.

package/skills/review-pr/references/project-rules-example.md

@@ -0,0 +1,101 @@
+# Project-Specific Compliance Rules — Worked Example
+
+The "Project-specific compliance" section in SKILL.md is intentionally generic — every project has different architecture patterns, ID conventions, SQL store rules, and UI compliance requirements.
+
+This reference is a **worked example** from a real production project (Go gateway service + React/Tailwind admin UI) showing how to encode project-specific reviewer rules. Adapt the pattern in your repository's existing instruction or standards authority, then reference that authority from the SKILL.md "Project-specific compliance" section.
+
+The reviewer should adapt these rules to *your* project — do not flag PRs in unrelated codebases for not following these specific conventions.
+
+---
+
+## Example: Architecture patterns
+
+**Cache invalidation MUST use the pubsub pattern**:
+
+```go
+msgBus.Broadcast(bus.Event{
+    Name:    protocol.EventCacheInvalidate,
+    Payload: bus.CacheInvalidatePayload{Kind: ..., Key: ...},
+})
+```
+
+Do NOT thread direct references to cache structs (e.g. `*ContextFileInterceptor`) through constructors. Subscribers in `cmd/gateway_managed.go` handle dispatch to the correct cache layer. See `internal/http/agents.go` `emitCacheInvalidate()` for the canonical pattern.
+
+**Why this is a project-specific rule**: violating it works locally (cache gets invalidated) but breaks when the service runs multi-instance behind a load balancer (only the receiving instance's cache clears). The pubsub pattern fans out via the message bus.
+
+**Lesson for your project**: identify the patterns where the "obvious" implementation works in dev but breaks in production. Encode them.
+
+---
+
+## Example: ID scoping
+
+`store.UserIDFromContext(ctx)` returns DIFFERENT values depending on context:
+- **In DM**: individual user ID (e.g. `"123456"`)
+- **In group chat**: group-scoped compound ID (e.g. `"group:telegram:-1002541239372"`), composed in `gateway_consumer.go`
+
+The individual sender is available separately via `store.SenderIDFromContext(ctx)`.
+
+When reviewing code that uses UserID, verify:
+1. Uses the correct ID type for its purpose — `UserID` for scoping/isolation, `SenderID` for identifying the actual person
+2. Group chat behavior is correct — all group members share the same UserID
+3. Code that filters/stores by `user_id` works correctly with the `"group:channel:chatID"` format
+
+**Lesson for your project**: if your IDs change shape based on context, document it here. Reviewers can't catch this from the diff alone.
+
+---
+
+## Example: SQL store safety
+
+When the PR touches `store/pg/*.go`, migrations, or any DB queries:
+
+- All user inputs MUST use parameterized queries (`$1, $2, ...`) — never string concatenation or `fmt.Sprintf` for SQL values
+- Queries MUST be optimized — no N+1 queries, no unnecessary full table scans
+- WHERE clauses, JOINs, and ORDER BY columns MUST use existing indices — cross-check with migration files for available indexes
+- `rows.Err()` MUST be checked after every `for rows.Next()` loop (Go `database/sql` requirement)
+- Nullable columns MUST use pointer types (`*string`, `*time.Time`, etc.) in Scan destinations
+
+**Lesson for your project**: SQL store conventions are often the highest-leverage place to encode rules — bugs here cost production data.
+
+---
+
+## Example: i18n compliance
+
+- New user-facing strings in Go code MUST use `i18n.T(locale, i18n.MsgXxx, args...)` — no hardcoded English in error responses
+- New user-facing strings in React components MUST use `t("namespace.key")` via `useTranslation()` — no hardcoded English in JSX
+- New i18n keys MUST be added to ALL 3 locale files (en, vi, zh) for both backend (`internal/i18n/catalog_{en,vi,zh}.go`) and frontend (`ui/web/src/i18n/locales/{en,vi,zh}/`)
+- `slog` messages and `console.log` stay English (internal logs, not user-facing)
+
+**Lesson for your project**: if you support multiple locales, "added a string in English only" is a regression. Encode the catalog paths.
+
+---
+
+## Example: Web UI compliance (React + Tailwind + Radix)
+
+When the PR touches the web UI:
+
+- `h-dvh` MUST be used instead of `h-screen` — `h-screen` breaks on mobile (content hides behind browser chrome / virtual keyboard)
+- All `<input>`, `<textarea>`, `<select>` MUST use `text-base md:text-sm` (16px mobile) — font-size <16px triggers iOS Safari auto-zoom on focus
+- Edge-anchored elements (app shell, sidebar, toasts, chat input) MUST use `safe-top`, `safe-bottom`, `safe-left`, `safe-right` for notched devices
+- Icon buttons MUST have ≥44px touch target on touch devices (CSS `@media (pointer: coarse)` with `::after` pseudo-elements)
+- `<table>` MUST be wrapped in `<div className="overflow-x-auto">` with `min-w-[600px]` on the table
+- Grid layouts MUST be mobile-first: `grid-cols-1 sm:grid-cols-2 lg:grid-cols-N` — never fixed `grid-cols-N` without mobile breakpoint
+- Dialogs: full-screen on mobile (`max-sm:inset-0`), centered on desktop (`sm:max-w-lg`) — follow pattern in `ui/dialog.tsx`
+- Scrollable areas MUST use `overscroll-contain` to prevent background scroll bleed
+- Landscape phone: top bars should use `landscape-compact` class to reduce padding (`max-height: 500px`)
+- Portal dropdowns in dialogs using `createPortal(content, document.body)` MUST add `pointer-events-auto` — Radix Dialog sets `pointer-events: none` on body. Radix-native portals (Select, Popover) handle this automatically
+- Timezone: charts MUST use `formatBucketTz()` from `lib/format.ts` with `Intl.DateTimeFormat` — no `date-fns-tz` dependency
+- Package manager: MUST use `pnpm` (not `npm`) for `ui/web/`
+- File size: individual component files should stay under 200 lines — split into focused modules if exceeding
+
+**Lesson for your project**: encode mobile-first conventions, accessibility minimums, safe-area handling, and package-manager rules. These are easy to forget and tedious to enforce manually.
+
+---
+
+## How to encode project-specific rules in your own repo
+
+1. Follow the repository's instruction and documentation navigation to find the authority that owns review standards; if none exists, choose a location consistent with the project's conventions
+2. Reference them from your project's review instructions
+3. Update them when patterns change — stale rules generate false-positive findings
+4. Cross-check: when the reviewer cites a rule, the path/file referenced must still exist. Move with the code
+
+The reviewer is only as good as the rules. Invest here.

package/skills/review-pr/references/writing-language.md

@@ -0,0 +1,58 @@
+# Writing language for GitHub prose
+
+Shared by `pk:ship` and `pk:review-pr` (#1195).
+
+## Resolve before authoring
+
+```bash
+WL_BIN=.claude/hooks/lib/writing-language.cjs
+test -f "$WL_BIN" || WL_BIN=kits/core/hooks/lib/writing-language.cjs
+node "$WL_BIN" --json
+```
+
+Use `language` from the JSON for all human-facing GitHub prose. If
+`fallbackReason` is set, state the fallback explicitly in the PR/review body
+(do not claim the unsupported tag was honored).
+
+## Precedence
+
+1. `AGENTKIT_LANGUAGE`
+2. `CK_RESPONSE_LANGUAGE`
+3. `<project>/.primekit/config.yaml` → `locale.response_language` or top-level `language`
+4. `$AGENTKIT_HOME/config.yaml` (default `~/.primekit/config.yaml`) → same keys
+5. `<project>/.claude/.ck.json` → `locale.responseLanguage`
+6. `~/.claude/.ck.json` → `locale.responseLanguage`
+7. Default: `en`
+
+## What is localized
+
+- PR description headings and prose (`pk:ship`)
+- Review Summary / Risk / Findings / Verdict / handoff text (`pk:review-pr`)
+- Checklist labels and human-action requests
+
+## What stays intact
+
+- Conventional-commit **PR titles** (English)
+- Code, commands, paths, URLs, identifiers
+- GitHub keywords (`Closes #123`, `Relates to #456`)
+- User-provided quotes, issue titles, error output, evidence blobs
+
+## Invalid tags
+
+Normalize to lowercase BCP47-like `/^[a-z]{2,3}(-[a-z0-9]+)*$/`. Invalid
+candidates are **skipped** so lower-precedence sources can still win. If every
+configured value is invalid/empty, use `en` and record `fallbackReason` plus
+`rejected[]`.
+
+## YAML parser limits
+
+The resolver uses a minimal line parser (no YAML dependency). Supported shapes:
+
+```yaml
+language: vi
+locale:
+  response_language: vi
+```
+
+Inline maps like `locale: { response_language: vi }` are **not** read. Prefer
+block form until #1093 ships a full YAML consumer.