@aryaminus/controlkeel-opencode 0.3.31 → 0.3.33

package/.opencode/skills/deep-code-quality-review/references/quality-checklist.md

@@ -0,0 +1,102 @@
+# Deep Code Quality Checklist
+
+Walk this checklist during a deep code quality review. Each item maps to a
+`ck_finding` rule ID. Use `ck_validate` for automated scanning, then manually
+apply these structural checks.
+
+## File Size and Decomposition
+
+- **1000-line threshold**: Has any file crossed 1000 lines due to this change?
+  Rule: `code_quality.file_size`. Severity: high.
+  Check: `wc -l <file>`. If approaching or crossing 1000, recommend decomposition.
+
+- **Module cohesion**: Does each module have a single clear responsibility?
+  If a module handles auth, formatting, and API calls, flag for extraction.
+
+- **Function length**: Are any functions longer than 50 lines?
+  Long functions often hide missing abstractions. Recommend extraction.
+
+## Spaghetti and Branching
+
+- **Ad-hoc conditionals**: Are new `if`/`case`/`cond` branches added to unrelated flows?
+  Rule: `code_quality.spaghetti_condition`. Severity: medium to high.
+  Prefer: dedicated abstraction, helper, state machine, or separate module.
+
+- **Feature flags in shared code**: Are feature-specific checks scattered across general-purpose modules?
+  Rule: `code_quality.wrong_layer`. Severity: medium.
+  Prefer: isolate behind a dedicated abstraction.
+
+- **One-off booleans or nullable modes**: Do new flags complicate existing control flow?
+  Consider whether a typed model or explicit dispatcher would eliminate the branching.
+
+- **Narrow edge-case handling**: Is special-case logic inserted in the middle of an already busy function?
+  Recommend extracting to a helper or restructuring the flow.
+
+## Abstraction Quality
+
+- **Unnecessary abstractions**: Are there wrappers, identity functions, or pass-through helpers that add indirection without clarity?
+  Rule: `code_quality.unnecessary_abstraction`. Severity: medium.
+  Prefer: delete the layer of indirection.
+
+- **Missing abstractions**: Are there repeated conditionals or similar patterns that signal a missing model?
+  Rule: `code_quality.missing_abstraction`. Severity: medium.
+  Prefer: extract a typed model, helper, or dispatcher.
+
+- **Thin wrappers**: Does an abstraction merely call through to another function without adding logic?
+  Recommend: inline the call unless the wrapper provides a clear naming or boundary benefit.
+
+- **Magic handling**: Are generic mechanisms (dynamic dispatch, reflection-like patterns) used where simple data-shape assumptions would be clearer?
+  Rule: `code_quality.magic_handling`. Severity: medium.
+  Prefer: explicit typed models.
+
+## Type Boundaries
+
+- **Unnecessary casts**: Are there type casts that obscure the real contract?
+  Rule: `code_quality.type_boundary`. Severity: low to medium.
+  Prefer: make the boundary explicit.
+
+- **Loose optionality**: Are optional params or nil returns used where the invariant is actually clear?
+  Prefer: explicit types that encode the real state.
+
+- **Ad-hoc object shapes**: Are data structures loosely shaped rather than explicitly typed?
+  Prefer: structs, typed schemas, or shared contracts.
+
+## Layering and Ownership
+
+- **Feature logic in shared paths**: Is feature-specific logic in general-purpose modules?
+  Rule: `code_quality.wrong_layer`. Severity: medium to high.
+  Prefer: move to a dedicated module behind the right boundary.
+
+- **Canonical helper duplication**: Is a new helper created when the codebase already has a canonical utility for the job?
+  Rule: `code_quality.duplicate_logic`. Severity: medium.
+  Prefer: reuse the existing helper.
+
+- **Implementation details leaking through APIs**: Are internal data shapes exposed through public interfaces?
+  Recommend: define explicit API contracts.
+
+## Orchestration
+
+- **Sequential when parallel is simpler**: Is independent work serialized for no reason?
+  Rule: `code_quality.orchestration`. Severity: low to medium.
+  Prefer: parallel execution for independent work.
+
+- **Non-atomic related updates**: Can related updates leave state half-applied?
+  Prefer: more atomic structure (transaction, batch, single operation).
+
+## Code Judo Opportunities
+
+For each change, explicitly ask:
+
+- Can this be reframed so fewer concepts, branches, or helper layers are needed?
+- Is there a reorganization that uses the existing architecture more effectively?
+- Can whole categories of complexity be deleted rather than rearranged?
+- Does the change improve or worsen the local architecture?
+- Is this the simplest implementation that solves the actual task?
+
+**Priority order** for findings:
+1. Structural quality regressions (file size, spaghetti)
+2. Missed opportunities for dramatic simplification
+3. Boundary and abstraction problems
+4. Layering and ownership issues
+5. Type boundary concerns
+6. Legibility and maintainability

package/.opencode/skills/deslop/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: deslop
+description: "Clean AI slop: remove narrative comments, verbosity, hallucinated patterns, padding. Also cleans AI-generated issue/PR text. Trigger: 'unslop', 'clean up AI code', 'remove slop', 'clean up issue description'. Complements aislop detection."
+when_to_use: "Activate ONLY when explicitly asked to clean up AI-generated slop in code or issue/PR text. Do NOT auto-trigger during normal coding."
+argument-hint: "[file, diff, or aislop findings to clean]"
+disable-model-invocation: true
+license: Apache-2.0
+compatibility:
+  - opencode-native
+  - claude-standalone
+  - cursor-native
+  - codex
+metadata:
+  author: controlkeel
+  version: "1.1"
+  category: quality
+  ck_mcp_tools: [ck_validate, ck_git_diff, ck_git_commit, ck_finding]
+  related_skills: [deep-code-quality-review]
+---
+
+# Deslop
+
+Remove AI-generated slop while preserving behavior. Companion to aislop scanner — aislop detects, this skill cleans.
+
+## Do NOT use when
+- Normal coding or refactoring (use `deep-code-quality-review`)
+- Security issues found (use `security-review`)
+- Writing new code (not applicable)
+- Reviewing issue/PR technical correctness (use `investigate` or appropriate review skill)
+
+## Slop patterns (see [catalog](references/slop-patterns.md))
+
+**Code patterns:**
+1. Narrative comments — describing what code obviously does
+2. Unnecessary verbosity — 10 lines where 3 suffice
+3. Hallucinated imports — modules not used or not existing
+4. Mechanical padding — single-call wrappers, unnecessary intermediates
+5. Generic error messages — "An error occurred" instead of context
+6. TODO stubs with no implementation
+7. Redundant type annotations — already inferred
+
+**Issue/PR text patterns:**
+8. Over-confident root cause analysis without evidence
+9. Generic implementation strategies without project-specific context
+10. Long lists of irrelevant error classes
+11. AI-generated issue expansion that broadens scope with hypotheses
+12. Hallucinated code references or function names
+
+## Subtraction rules
+
+- **Delete, don't replace.** If a comment explains what → delete it, don't rewrite it.
+- **Inline, don't redirect.** Single-call helper → inline and delete.
+- **Shrink, don't reorganize.** 10-line function can be 3 → shrink, don't split.
+- **Remove dead code.** Unused imports, unreachable branches.
+- **Preserve intent.** Comments explaining **why** → keep. Helpers with meaningful naming → keep.
+
+## Workflow
+
+**For code cleanup:**
+1. Run `ck_git_diff` to scope changes. Run `ck_validate` for aislop findings.
+2. List slop patterns found. Plan removals — do not start editing until plan is clear.
+3. Apply removals. Run tests after each logical group.
+4. The diff must be **smaller** after cleanup, not just different.
+5. Full suite must pass. Zero new failures.
+6. `ck_validate` on cleaned diff. `ck_git_commit`.
+
+**For issue/PR text cleanup:**
+1. Identify the issue or PR description text to clean.
+2. Run `ck_validate` with `source_type: "issue"` or `source_type: "pull_request"` to assess trust level.
+3. List slop patterns found (over-confident analysis, generic strategies, hallucinated references).
+4. Remove AI-generated expansions and stick to observed facts: command run, expected behavior, actual behavior, exact error/log.
+5. Replace hallucinated code references with accurate ones after verification.
+6. Remove generic implementation advice; keep only specific, actionable guidance.
+7. Validate the cleaned text preserves the core issue report without the AI-generated noise.
+
+## Rules
+
+**For code:**
+- Behavior preservation — every passing test stays passing
+- No scope creep — fix slop only, do not refactor or add features
+- Smaller diff — fewer lines after cleanup, not same or more
+
+**For issue/PR text:**
+- Fact preservation — keep the actual observed behavior and errors
+- No scope narrowing — don't remove important context or edge cases
+- Evidence-based — replace confident analysis with observed facts
+- Specific over generic — keep concrete details, remove vague suggestions
+
+## Output
+
+**For code:**
+- Cleaned code with slop removed
+- Full suite passing
+- Commit with cleanup
+
+**For issue/PR text:**
+- Cleaned description with AI-generated noise removed
+- Preserved core issue report with observed facts
+- Specific, actionable guidance without over-confident analysis

package/.opencode/skills/deslop/references/slop-patterns.md

@@ -0,0 +1,188 @@
+# Slop Pattern Catalog
+
+Common AI-generated code patterns that should be removed during deslop. Each
+pattern includes what to look for and the subtraction rule.
+
+## Issue and PR Text Patterns
+
+### Over-confident root cause analysis without evidence
+```markdown
+# Bad: confident diagnosis without supporting evidence
+The issue is clearly caused by a race condition in the user session manager. We should add a mutex lock around the session state mutations to prevent concurrent access.
+
+# Good: stick to observed facts
+When two requests hit the session endpoint simultaneously, I see session state corruption in the logs. Here's the exact error and reproduction steps.
+```
+
+### Generic implementation strategies
+```markdown
+# Bad: generic advice without project-specific context
+The best approach would be to implement a comprehensive retry mechanism with exponential backoff, circuit breaker pattern, and extensive monitoring.
+
+# Good: specific, actionable guidance tied to the actual problem
+Add retry with exponential backoff (max 3 attempts) to the `ApiClient.post/2` function, which currently fails on network timeouts.
+```
+
+### Long lists of irrelevant error classes
+```markdown
+# Bad: enumerating possible issues without narrowing down
+This could be caused by: network timeouts, SSL certificate errors, DNS resolution failures, malformed JSON responses, rate limiting, authentication failures, or server-side bugs.
+
+# Good: specific error with context
+The specific error is `{:error, :timeout}` after 30 seconds when calling the external payment API. Here's the full stack trace.
+```
+
+### AI-generated issue expansion
+```markdown
+# Bad: expands narrow observation into broad hypotheses
+The login button doesn't work. This suggests potential problems with the authentication flow, session management, CSRF token validation, user database integrity, or frontend event handling. We should audit the entire auth subsystem.
+
+# Good: focused on the actual observation
+Clicking the login button does nothing. No network request is sent to `/auth/login` and no error appears in the console. Here are the browser devtools screenshots.
+```
+
+### Hallucinated code references
+```markdown
+# Bad: confident but wrong code references
+The bug is in `lib/my_app/auth/session_manager.ex` line 45 where the `validate_session/1` function doesn't check for expired tokens.
+
+# Good: accurate code references after actual investigation
+The issue is in `lib/my_app/web/auth_plug.ex` where the `call/2` function doesn't validate session expiration before proceeding.
+```
+
+## Comments
+
+### Narrative comments
+```elixir
+# Bad: describes what the code does
+# Check if the user is authenticated before proceeding
+if user do
+  ...
+end
+
+# Good: delete the comment, the code is self-explanatory
+if user do
+  ...
+end
+```
+
+### Story comments
+```elixir
+# Bad: tells a story
+# First, we need to get the user from the database.
+# Then, we check if they have admin privileges.
+# If they do, we allow access to the dashboard.
+user = Accounts.get_user!(id)
+if Accounts.admin?(user), do: render_dashboard(user)
+
+# Good: just the code
+user = Accounts.get_user!(id)
+if Accounts.admin?(user), do: render_dashboard(user)
+```
+
+### Kept comments
+```elixir
+# Keep: explains WHY, not what
+# Using pessimistic locking here because concurrent updates
+# caused a race condition in production (see #1234)
+Repo.lock(user)
+```
+
+## Verbosity
+
+### Unnecessary intermediate variables
+```elixir
+# Bad
+result = do_something()
+final_result = process(result)
+return_value = format(final_result)
+return_value
+
+# Good
+do_something() |> process() |> format()
+```
+
+### Overly explicit pattern matching
+```elixir
+# Bad
+case value do
+  true -> handle_true()
+  false -> handle_false()
+end
+
+# Good
+if value, do: handle_true(), else: handle_false()
+```
+
+## Dead Code
+
+### Unused imports
+```elixir
+# Bad: imported but never referenced
+alias MyApp.SomeModule  # never used
+
+# Good: delete the import
+```
+
+### TODO stubs with no implementation
+```elixir
+# Bad
+def handle_error(error) do
+  # TODO: implement error handling
+  :ok
+end
+
+# Good: implement it or remove the function if not called
+```
+
+### Unreachable branches
+```elixir
+# Bad: else branch can never execute
+if true do
+  do_thing()
+else
+  handle_impossible_case()  # dead code
+end
+
+# Good: remove the conditional entirely
+do_thing()
+```
+
+## Padding
+
+### Single-call wrappers
+```elixir
+# Bad: helper adds no logic, just redirects
+def get_user_name(user), do: user.name
+
+# Good: just call user.name directly at the call site
+```
+
+### Generic error messages
+```elixir
+# Bad
+{:error, "An error occurred while processing the request"}
+
+# Good
+{:error, "Payment gateway timeout: #{status} after #{timeout}ms"}
+```
+
+## Hallucinated Patterns
+
+### Imports for non-existent modules
+```elixir
+# Bad: module does not exist in the project
+alias Phoenix.HTML.Form  # wrong module name
+
+# Good: use the actual module
+alias Phoenix.Component
+```
+
+### Redundant type specs
+```elixir
+# Bad: typespec repeats what the function body already makes clear
+@spec add(integer(), integer()) :: integer()
+def add(a, b), do: a + b
+
+# Good: keep typespecs for public APIs, remove for trivial private functions
+```

package/.opencode/skills/investigate/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: investigate
+description: "Read-only codebase Q&A: trace code paths, answer how/why/where questions without changes. Trigger: 'how does X work', 'why was Y built this way', 'trace the data flow'."
+when_to_use: "Activate for read-only exploration questions. Do NOT use when code changes are needed."
+argument-hint: "[question about the codebase]"
+disable-model-invocation: true
+license: Apache-2.0
+compatibility:
+  - opencode-native
+  - claude-standalone
+  - cursor-native
+  - codex
+metadata:
+  author: controlkeel
+  version: "1.1"
+  category: exploration
+  ck_mcp_tools: [ck_memory_search]
+  related_skills: [architect-first]
+---
+
+# Investigate
+
+Read-only codebase Q&A. Trace code, not guesses. No file changes.
+
+## Do NOT use when
+- Code changes are needed (use appropriate dev skill)
+- The question is about planning (use `align`)
+- The question is about security (use `security-review`)
+
+## Workflow
+
+1. Search `ck_memory_search` for prior analysis on this area.
+2. Trace actual code paths for the question type:
+   - **How**: entry point → call chain → data flow → side effects
+   - **Why**: `git log --oneline -20 -- <file>`, linked issues, commit messages
+   - **Where**: search for function/module references, trace callers
+   - **What-if**: trace the code path for that scenario, identify edge cases
+3. Check multiple sources: source control, tests, comments. Code shows what, not why.
+4. Answer concisely: direct answer + evidence (file:line, commit SHA) + caveats.
+
+## Rules
+
+- Read-only — no file changes. If fix needed, record and recommend appropriate skill.
+- Every claim backed by code evidence or git history.
+- Answer what was asked — do not explore tangentially.
+- Stop at external boundaries — say so instead of speculating.
+
+## Output
+
+- Concise answer with file:line evidence
+- Optional `ck_memory_record` for durable findings
+- No file changes

package/.opencode/skills/orchestrate-tasks/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: orchestrate-tasks
+description: "Fan large tasks across parallel agents with planner/worker/verifier roles and structured handoffs. Trigger: 'parallelize', 'fan out', 'orchestrate', or when plan-slice produces 3+ independent slices."
+when_to_use: "Activate ONLY when a task is too large for a single agent and has independent parallelizable slices. Do NOT use for single-agent tasks."
+argument-hint: "[goal or slice plan to orchestrate]"
+disable-model-invocation: true
+license: Apache-2.0
+compatibility:
+  - opencode-native
+  - claude-standalone
+  - cursor-native
+  - codex
+metadata:
+  author: controlkeel
+  version: "1.1"
+  category: orchestration
+  ck_mcp_tools: [ck_route, ck_delegate, ck_budget, ck_review_submit, ck_finding, ck_git_diff, ck_memory_record, ck_rollback]
+  related_skills: [plan-slice]
+---
+
+# Orchestrate Tasks
+
+Fan large tasks across parallel agents with planner/worker/verifier roles. Adapted from Cursor's orchestrate plugin for CK governance.
+
+## Do NOT use when
+- Single-agent task (just use `controlkeel-governance`)
+- Task has no parallelizable slices
+- Budget is tight (orchestration is expensive — multiple delegations)
+
+## Principles
+
+1. **Planners own scope, not code** — decompose, publish tasks, read handoffs, decide next. No file edits.
+2. **Workers are isolated** — one task, one agent, one scope. Talk up through handoffs only.
+3. **Verifiers check independently** — read worker output, verify against acceptance criteria.
+4. **State on disk** — `ck_memory_record` and git, no long-running agent state.
+5. **Continuous convergence** — each cycle produces progress. No progress → escalate.
+
+## Workflow
+
+1. Check `ck_budget` — orchestration costs multiple delegations. Stop if insufficient.
+2. Decompose into tasks (or use existing `plan-slice` output). Each task: name, type (worker/verifier/subplanner), scoped goal, acceptance criteria, dependencies, paths.
+3. Record plan via `ck_memory_record` (type: `decision`, tags: `orchestration-plan`).
+4. Submit plan via `ck_review_submit` (review_type: `plan`). **Wait for approval** before spawning.
+5. Execute loop:
+   - Select ready tasks (dependencies satisfied, not started)
+   - Check budget before each delegation
+   - Delegate: `ck_route` → `ck_delegate`
+   - Collect handoffs
+   - Verify completed tasks
+   - `ck_rollback` checkpoint after each success
+   - Decide: new tasks, retry failures, or completion
+6. Synthesize: `ck_git_diff` for total change, `parallel-review` if large.
+
+## Failure recovery
+
+- Worker failure → record `ck_finding`, retry once, escalate if retry fails
+- Budget exhaustion → checkpoint state, stop, record for resumption
+- Verifier failure → worker output not trusted, fix or escalate
+
+## Output
+
+- Approved orchestration plan
+- Delegated tasks with handoffs
+- `ck_finding` for failures
+- `ck_rollback` checkpoints
+- Synthesized result
+
+## Reference
+
+- [Handoff format](references/handoff-format.md)

package/.opencode/skills/orchestrate-tasks/references/handoff-format.md

@@ -0,0 +1,42 @@
+# Handoff Format
+
+Workers and verifiers produce a handoff document when they complete. This is the
+only communication channel between a worker and its planner.
+
+## Structure
+
+```markdown
+# Handoff: <task-name>
+
+## Status
+<completed | failed | blocked>
+
+## What was done
+<1-5 bullets describing the actual changes made>
+
+## Files changed
+- `path/to/file.ex`: <what changed and why>
+- `path/to/test.exs`: <what was tested>
+
+## Acceptance criteria met
+- [x] <criterion 1>
+- [x] <criterion 2>
+- [ ] <criterion not met> — <why>
+
+## Test results
+<mix test output summary>
+
+## Issues encountered
+- <any blockers, unexpected complexity, or things the planner should know>
+
+## Recommendations for planner
+<suggestions for follow-up tasks, verifications, or adjustments>
+```
+
+## Rules
+
+- **Be specific, not narrative.** "Added `validate_email/1` to `Accounts` module" not "improved validation".
+- **Include test evidence.** Every completed worker must include test output.
+- **Flag blocked criteria.** If acceptance criteria are not met, explain why and what the planner should do.
+- **No code dumps.** The handoff summarizes changes; the actual code is in the repo.
+- **Be concise.** A good handoff fits in one screen. If it doesn't, the task was too broad.

package/.opencode/skills/parallel-review/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: parallel-review
+description: "Run security + code quality reviews concurrently, synthesize deduplicated findings. Trigger: 'full review', 'parallel review', 'both reviews', comprehensive pre-merge check."
+when_to_use: "Activate ONLY when explicitly asked for comprehensive security+quality review. Do NOT use when only one review type is needed."
+argument-hint: "[PR, branch, or diff]"
+disable-model-invocation: true
+license: Apache-2.0
+compatibility:
+  - opencode-native
+  - claude-standalone
+  - cursor-native
+  - codex
+metadata:
+  author: controlkeel
+  version: "1.1"
+  category: review
+  ck_mcp_tools: [ck_validate, ck_finding, ck_git_diff, ck_review_submit, ck_route, ck_delegate]
+  related_skills: [security-review, deep-code-quality-review]
+---
+
+# Parallel Review
+
+Run `security-review` and `deep-code-quality-review` concurrently, synthesize into one prioritized report.
+
+## Do NOT use when
+- Only security OR quality review needed (use the specific skill directly)
+- During normal coding
+- For single-file changes where sequential review is fast enough
+
+## Workflow
+
+1. Run `ck_git_diff` to gather the diff. Run `ck_validate` for automated findings.
+2. Launch both reviews (via `ck_delegate` or sequential invocation):
+   - **Security**: `security-review` skill — OWASP, injection, auth, secrets, deps
+   - **Quality**: `deep-code-quality-review` skill — abstraction, file size, spaghetti, layering
+   Both record findings independently via `ck_finding`.
+3. Synthesize:
+   - Deduplicate: same code path flagged by both → one finding, higher severity
+   - Prioritize: critical > high > medium > low; security > quality > reviewability
+   - Weight overlaps: flagged by both = higher confidence
+   - Resolve disagreements with your own judgment
+4. Submit via `ck_review_submit` (review_type: `diff`) with combined findings.
+5. **Wait for approval** before merge/deploy.
+
+## Rules
+
+- Both reviews must complete — do not skip one
+- Blocked finding from either = merge blocked
+- Deduplicate, do not double-count
+
+## Output
+
+- Combined findings (deduplicated, prioritized)
+- `ck_review_submit` diff review
+- Clear verdict: merge / merge with warnings / blocked

package/.opencode/skills/reviewable-pr/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: reviewable-pr
+description: "Prepare PRs for review: clean noisy history, improve descriptions, add reviewer guidance. Trigger: 'make easy to review', 'tidy PR', 'clean up commits', 'annotate diff'."
+when_to_use: "Activate ONLY when explicitly asked to prepare a PR for review. Do NOT auto-trigger during normal coding or review tasks."
+argument-hint: "[PR URL, branch, or current]"
+disable-model-invocation: true
+license: Apache-2.0
+compatibility:
+  - opencode-native
+  - claude-standalone
+  - cursor-native
+  - codex
+metadata:
+  author: controlkeel
+  version: "1.1"
+  category: review
+  ck_mcp_tools: [ck_git_diff, ck_git_status, ck_validate, ck_review_submit, ck_finding]
+  related_skills: [security-review, deep-code-quality-review]
+---
+
+# Reviewable PR
+
+Prepare a PR so a reviewer can quickly understand intent, risk, and key files — without changing code behavior.
+
+## Do NOT use when
+- Doing normal coding or bug fixing
+- Running security or quality reviews (use those skills directly)
+- Making behavior changes (this skill only improves reviewability)
+
+## Workflow
+
+1. Resolve the PR (URL, branch, or current). Run `ck_git_diff` and `ck_git_status`.
+2. Run `ck_validate` on the diff. Resolve blocked findings first — reviewability is secondary to correctness.
+3. Diagnose reviewability issues against [checklist](references/pr-checklist.md):
+   - Noisy/mixed-intent commit history
+   - Missing or stale PR description
+   - Unrelated changes mixed in
+   - Mechanical changes mixed with logic
+   - Missing test coverage for core change
+   - Unclear reviewer entry points
+4. Record issues as `ck_finding` (category `reviewability`, severity `medium`/`low`).
+5. Submit plan via `ck_review_submit` (review_type: `plan`) describing what will change. **Wait for approval** before rewriting history or force-pushing.
+6. Apply approved improvements. After any history rewrite, verify tree hash unchanged:
+   ```
+   ORIGINAL_TREE=$(git rev-parse origin/<branch>^{tree})
+   # ... rewrite ...
+   # Tree must match
+   ```
+7. Update PR description with: TL;DR, core files (3-7), mechanical files, risk callouts, context links.
+
+## Guardrails
+
+- Never hide behavior changes inside cleanup
+- Never force-push without `ck_review_submit` approval
+- If PR too large to review, recommend splitting instead of polishing
+- If `ck_validate` blocked, fix those first
+
+## Output
+
+- `ck_finding` records for reviewability issues
+- `ck_review_submit` plan (approved)
+- Updated PR description with reviewer guidance
+- Verified tree identity after any history changes