@neikyun/ciel 6.11.0 → 6.11.2

package/assets/skills/workflow/pr-review-responder/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: pr-review-responder
+description: Handles PR review comments — lists unresolved threads via GraphQL, classifies accept/reject/clarify, applies fixes, marks resolved, re-requests review. Invoke on CHANGES_REQUESTED, "respond to PR review", "address review feedback". Inline.
+allowed-tools: Bash, Read, Edit
+context: inline
+---
+
+# pr-review-responder — Respond to PR feedback systematically
+
+A PR in CHANGES_REQUESTED state is a dead PR until its comments are addressed. This skill closes the feedback loop: list, classify, respond, mark resolved, re-request.
+
+---
+
+## Inputs
+
+```
+PR_NUMBER: [from current branch or explicit]
+REVIEWER: [optional — filter by specific reviewer login]
+MODE: [interactive | batch — default interactive; in batch, only respond to accept/reject, flag clarify for user]
+```
+
+### Auto-inference sources
+
+- **PR_NUMBER** → `gh pr view --json number --jq .number`
+- **REVIEWER** → latest reviewer from `gh pr view --json reviews --jq '.reviews[-1].author.login'`
+
+---
+
+## Preflight
+
+```bash
+gh auth status 2>&1 | grep -q "Logged in" || exit 1
+PR_NUMBER=${PR_NUMBER:-$(gh pr view --json number --jq .number)}
+[ -z "$PR_NUMBER" ] && { echo "No PR for current branch"; exit 1; }
+
+# Must be on the PR's head branch to push fixes
+HEAD=$(gh pr view "$PR_NUMBER" --json headRefName --jq .headRefName)
+CURRENT=$(git rev-parse --abbrev-ref HEAD)
+[ "$HEAD" = "$CURRENT" ] || { echo "Checkout the PR branch first: gh pr checkout $PR_NUMBER"; exit 1; }
+```
+
+---
+
+## Process
+
+### 1. Fetch unresolved review threads
+
+GitHub's REST API doesn't expose thread-resolution state directly — use GraphQL:
+
+```bash
+OWNER=$(gh repo view --json owner --jq .owner.login)
+REPO=$(gh repo view --json name --jq .name)
+
+gh api graphql -f query="
+  query {
+    repository(owner: \"$OWNER\", name: \"$REPO\") {
+      pullRequest(number: $PR_NUMBER) {
+        reviewThreads(first: 100) {
+          nodes {
+            id
+            isResolved
+            path
+            line
+            comments(first: 10) {
+              nodes { author { login } body createdAt }
+            }
+          }
+        }
+      }
+    }
+  }
+" --jq '.data.repository.pullRequest.reviewThreads.nodes[] | select(.isResolved == false)'
+```
+
+Extract: thread ID, file path, line, comment bodies, reviewer login.
+
+### 2. Classify each unresolved thread
+
+For each thread, classify:
+
+- **ACCEPT** — reviewer has a valid point, code change needed. Examples: bug, missed edge case, naming, obvious improvement.
+- **REJECT** — reviewer misread / disagreement on non-blocking preference. Document the rebuttal.
+- **CLARIFY** — ambiguous; ask reviewer a follow-up question. Examples: "Did you mean X or Y?", "This was intentional because Z — does that address your concern?"
+
+Classification heuristic:
+- Comment contains "bug", "broken", "wrong", "missing" → likely ACCEPT
+- Comment contains "nit", "preference", "style" → likely REJECT (if inconsistent with codebase convention) or ACCEPT (if aligns)
+- Comment is a question (contains "?") → likely CLARIFY
+
+In `MODE=batch`, auto-handle ACCEPT + REJECT; defer CLARIFY to user.
+
+### 3. Apply code changes for ACCEPT threads
+
+For each ACCEPT:
+
+```bash
+# Read the file at the reviewer-pointed line
+# Apply the suggested change (from comment body, or derived from review context)
+# Example: reviewer suggests "use `?.` instead of `&&` chain"
+```
+
+Use Edit tool for precise changes. Group changes by file. Commit each logical group separately:
+
+```bash
+git add <file>
+git commit -m "fix: address review feedback on <file>:<line>
+
+Addresses comment from @<reviewer>:
+> <first line of reviewer comment>
+
+Refs #<PR_NUMBER>"
+```
+
+### 4. Reply + resolve threads
+
+For each thread (ACCEPT or REJECT):
+
+```bash
+# Post reply comment
+gh api graphql -f query="
+  mutation {
+    addPullRequestReviewThreadReply(input: {
+      pullRequestReviewThreadId: \"<THREAD_ID>\"
+      body: \"<reply>\"
+    }) { comment { id } }
+  }
+"
+
+# Resolve thread
+gh api graphql -f query="
+  mutation {
+    resolveReviewThread(input: { threadId: \"<THREAD_ID>\" }) {
+      thread { isResolved }
+    }
+  }
+"
+```
+
+Reply templates:
+- ACCEPT applied: `"Good catch — fixed in <SHA>. Thanks!"`
+- REJECT: `"Intentional — <rebuttal>. Happy to reconsider if you disagree."`
+- CLARIFY (user-authored follow-up): `"<user question>"`
+
+### 5. Push + re-request review
+
+```bash
+git push origin "$CURRENT"
+
+# Collect reviewer logins (those who left the resolved threads)
+REVIEWERS=$(gh pr view "$PR_NUMBER" --json reviews --jq '[.reviews[].author.login] | unique | join(",")')
+
+# Re-request review from original reviewer(s)
+for R in $(echo "$REVIEWERS" | tr ',' ' '); do
+  gh api \
+    --method POST \
+    "repos/$OWNER/$REPO/pulls/$PR_NUMBER/requested_reviewers" \
+    -f "reviewers[]=$R"
+done
+```
+
+### 6. Emit output
+
+```
+[REVIEW RESPONDED]
+PR: #<P>
+Unresolved threads: <N>
+Accepted: <N> (fixes pushed in <count> commits)
+Rejected: <N> (rebuttals posted)
+Clarify (deferred to user): <N>
+Reviewers re-requested: <@user1, @user2>
+```
+
+---
+
+## Guardrails
+
+- **Never force-resolve a thread without replying** — always post a reply before marking resolved; silent resolution is hostile.
+- **Never accept a change that breaks tests** — run the test suite locally after each ACCEPT commit. If red, revert and reclassify to CLARIFY.
+- **Never reject without rationale** — a REJECT reply must explain *why*, reference codebase convention or past decision.
+- **CLARIFY blocks the merge** — a thread in CLARIFY state is NOT resolved. `pr-merger` must see 0 unresolved threads.
+- **Batch mode is dangerous for CLARIFY** — in batch, always defer CLARIFY to user rather than auto-replying with a guess.
+- **Don't touch unrelated code** — a review comment on `auth.ts:42` only authorizes edits to that file/area. Scope creep invalidates the review.
+- **Re-request review only after push succeeds** — don't re-request on a broken push.
+
+---
+
+## When triggered
+
+- `gh pr view` shows `reviewDecision: CHANGES_REQUESTED`
+- User says: "respond to PR review", "address comments on PR #N", "handle review feedback"
+- After `pr-opener` if reviewers are auto-added and they post comments within the same session
+
+---
+
+## Anti-pattern
+
+```
+❌ Reviewer comment → silent push → reviewer confused about what changed
+✅ Reviewer comment → reply acknowledging → push → resolve thread → re-request
+```
+
+```
+❌ Batch-auto-reply "Done" to all threads without applying changes
+✅ Apply change, reference SHA in reply, mark resolved
+```
+
+---
+
+## References
+
+- GraphQL review threads — docs.github.com/en/graphql/reference/objects#pullrequestreviewthread
+- Resolve thread mutation — docs.github.com/en/graphql/reference/mutations#resolvereviewthread
+- Request reviewers API — docs.github.com/en/rest/pulls/review-requests
+- Ciel pipeline: pr-opener → (reviewer comments) → pr-review-responder → pr-merger

package/assets/skills/workflow/prouver-verifier/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: prouver-verifier
+description: How to verify implementation with evidence — AVANT/APRÈS methodology, constraint synthesis, CI gate, PR body gate, issue comment gate, and closure gate. Proves code works with concrete evidence, not assumptions.
+allowed-tools: Bash, WebFetch, Read
+---
+
+# Implementation Verification — Evidence-Based Proof
+
+## What this covers
+
+How to prove that code works with concrete evidence. Code written ≠ done. Verified with AVANT/APRÈS evidence = done.
+
+## Core principle
+
+**"No error in logs" ≠ proof.** Trigger the scenario, see a POSITIVE signal.
+
+## AVANT/APRÈS methodology (bug fixes)
+
+- **AVANT**: failing test (RED) OR log showing broken behavior — code diff ≠ proof
+- **APRÈS**: staging log / curl output / HTTP status AFTER deploying AND triggering the scenario
+
+### Same-source rule
+
+- Bug found in logs → verify fix in logs
+- Bug in screenshot → verify by screenshot
+- Curl result ≠ substitute for original observation source
+
+### Constraint synthesis (write BEFORE checking logs)
+
+Force yourself to write expected signals BEFORE looking:
+
+1. Functional: `"POST /api/X returns 201 with body.data.id"`
+2. Behavioral: `"Log contains '[MESSAGE]' after triggering"`
+3. Negative: `"Old error '[ERROR]' no longer appears"`
+
+Then check logs. Match or miss = clear signal.
+
+### Attacker perspective (security fixes)
+
+"If I were an attacker, what test proves my fix blocks me?" Write THAT test. Can't write it → fix isn't proven.
+
+## Verification gates
+
+### CI gate
+
+```bash
+gh run list --branch $BRANCH --limit 1
+```
+
+Status must be `completed/success`. If failed → identify root cause, fix before PR.
+
+"CI is running" ≠ done.
+
+### PR body gate
+
+- `Closes #XXX` present for every linked issue?
+- No WIP marker? (`WIP`, `[WIP]`, `wip`)
+- Draft vs ready correct?
+
+### Issue comment gate
+
+Add a comment on EVERY linked issue with:
+- Staging PID (process/deploy ID)
+- AVANT/APRÈS evidence
+
+Do NOT wait for post-merge. Batch PRs → each issue gets its own comment.
+
+### Closure gate
+
+```bash
+gh issue view <N> --comments
+```
+
+Does a comment with staging PID + AVANT/APRÈS exist? No → add NOW before merge.
+
+Post-merge closure includes:
+1. What was fixed (1 line)
+2. Concrete observed evidence (logs / curl / DOM — NOT code diffs)
+3. PR/SHA reference
+
+Closure without evidence = not closed.
+
+## Quick verification (trivial tasks)
+
+1. Compile OK locally
+2. Push to branch
+3. Verify no regression (existing tests still green)
+
+No CI gate mandatory, no staging mandatory.
+
+## Output format
+
+```
+## VERIFICATION
+
+### AVANT (before fix)
+<log excerpt / curl output / screenshot>
+
+### APRÈS (after fix, on staging)
+<log excerpt / curl output / screenshot>
+
+### Constraints (written before check)
+1. Functional: <expected signal>
+2. Behavioral: <expected signal>
+3. Negative: <expected absence>
+
+### CI gate
+- Run: <URL>
+- Status: <success | in_progress | failed>
+
+### PR body gate
+- [✓/✗] Closes #XXX present
+- [✓/✗] No WIP marker
+
+### Issue comments
+- #<N>: comment added with PID + AVANT/APRÈS
+
+### VERDICT
+<DONE | PENDING: remaining items>
+```
+
+## How to verify
+
+- [ ] AVANT state captured (before fix)?
+- [ ] APRÈS state captured (after fix, on staging)?
+- [ ] Constraints written BEFORE checking logs?
+- [ ] CI gate passed?
+- [ ] PR body gate passed (AVANT/APRÈS evidence)?
+- [ ] Issue comment gate passed (evidence posted)?
+- [ ] VERDICT issued (DONE / NOT-YET)?
+
+## Staging evidence capture — three modes
+
+**Never sleep-and-poll.** Use Monitor for streaming events, Bash background for one-shot waits.
+
+### Mode 1: Snapshot (last N lines)
+
+When: you've already deployed and just need to read what happened.
+
+```bash
+journalctl -u <service> -n 50 --no-pager
+```
+
+Use **Bash** (not Monitor, not background).
+
+### Mode 2: Stream (watch for specific event)
+
+When: you've just triggered a scenario and want to see the log line confirming it.
+
+```
+Monitor(
+  description: "staging logs after trigger",
+  persistent: false,
+  timeout_ms: 60000,
+  command: "journalctl -u <service> -f --since now | grep --line-buffered 'KEYWORD'"
+)
+```
+
+Critical: `grep --line-buffered` — without it, pipe buffering delays events minutes.
+
+### Mode 3: One-shot wait (deploy done?)
+
+When: long-running command that blocks until complete (deploy script, test run).
+
+```
+Bash(command="deploy-staging.sh", run_in_background=true)
+```
+
+→ Returns PID immediately. You get notified when it completes.
+
+### Anti-patterns
+
+- **`sleep N && tail`** — harness blocks it. Use Monitor or background instead.
+- **Monitor for deploys** — Monitor doesn't wait synchronously. Use `run_in_background` for deploys.
+- **No `grep --line-buffered`** — pipe buffering delays events by minutes
+- **Indefinite Monitor** — always set `timeout_ms` (60s typical)
+- **Too many Monitors** — auto-killed by harness. One event at a time.
+
+## Common mistakes
+
+- **"No error in logs"**: not proof — trigger the scenario and look for positive signal
+- **Code diff as proof**: showing what changed ≠ showing it works
+- **Missing AVANT**: without before-state, can't prove improvement
+- **Skipping issue comments**: auto-close won't add evidence — do it manually

package/assets/skills/workflow/prouver-verifier/reference.md

@@ -0,0 +1,152 @@
+# prouver-verifier — Reference
+
+## Log observation tools — three modes, use the right one
+
+| Need | Tool | Example |
+|------|------|---------|
+| Snapshot (last N lines) | `Bash` | `journalctl -u neiyomi-staging -n 50 --no-pager` |
+| Stream (watch for events) | `Monitor` | `journalctl -u neiyomi-staging -f \| grep --line-buffered "keyword"` |
+| One-shot wait (deploy done?) | `Bash` with `run_in_background: true` | `deploy-staging.sh` |
+
+**NEVER** use `sleep N && tail` or `sleep N && journalctl` — the harness blocks it. Use Monitor for streaming events, Bash `run_in_background` for one-shot waits.
+
+### Monitor example
+
+```
+Monitor(
+  description: "staging logs after deploy",
+  persistent: false,
+  timeout_ms: 60000,
+  command: "journalctl -u neiyomi-staging -f --since now | grep --line-buffered 'keyword'"
+)
+```
+
+Always use `grep --line-buffered` in pipes — without it, pipe buffering delays events by minutes.
+
+### Monitor budget
+
+Every Monitor stdout line becomes a conversation message. Always filter. Use `persistent: false` with tight `timeout_ms` for verification (60s typical). Reserve `persistent: true` for session-long watches (debugging live traffic).
+
+### Bash run_in_background
+
+For deploys or long-running one-shot commands:
+
+```
+Bash(command="deploy-staging.sh", run_in_background=true)
+```
+
+Returns immediately with a PID. Use BashOutput tool later to retrieve output. You'll be notified when the command completes — don't poll.
+
+## CI commands — gh CLI
+
+```bash
+# Check CI for current branch
+gh run list --branch $(git branch --show-current) --limit 1
+
+# View failing job details
+gh run view --job=<ID> --log-failed
+
+# Wait for CI to complete (polling — prefer notification pattern)
+gh run watch <run-id>
+
+# List PR status
+gh pr list --state open --draft
+gh pr view <N>
+gh pr ready <N>  # Convert draft to ready
+
+# Issue comments
+gh issue view <N> --comments
+gh issue comment <N> --body "..."
+```
+
+## Staging evidence — what counts
+
+**Good evidence** (trust-worthy):
+- Log line with timestamp showing the expected behavior (`2026-04-17T14:23:15 [INFO] User 42 updated profile successfully`)
+- Curl output with HTTP status + response body matching constraints
+- Screenshot with URL bar showing staging domain + relevant UI state
+- DOM snapshot (accessibility tree) showing expected elements
+
+**Weak evidence** (insufficient on its own):
+- "No errors in logs"
+- "Tests pass"
+- "I tested it locally"
+- "The CI is green"
+- Diff of the code (proves intent, not behavior)
+
+## Constraint synthesis — examples
+
+Good constraints (specific, falsifiable):
+
+```
+1. Functional: `POST /api/users/42/profile` with name="Alice" returns HTTP 200 with body `{"id":42,"name":"Alice","updatedAt":<ISO 8601>}`
+2. Behavioral: Log contains `[UserService] Profile updated for user 42` within 5s of trigger
+3. Negative: Log does NOT contain `[UserService] Validation failed` after trigger
+```
+
+Bad constraints (vague):
+
+```
+1. Endpoint works
+2. User is saved
+3. No errors
+```
+
+## PR body template
+
+```
+## Summary
+<1-3 bullets describing what changed and why>
+
+## Test plan
+- [ ] Unit tests for <component>
+- [ ] Integration test for <boundary>
+- [ ] Manual verification on staging: <URL>
+
+## Evidence
+- AVANT: <log excerpt or URL>
+- APRÈS: <log excerpt or URL>
+
+Closes #<issue>
+```
+
+Rules:
+- Title ≤ 70 chars, no WIP marker
+- `Closes #XXX` required for every linked issue
+- Evidence section non-optional for bug fixes
+
+## Issue comment template
+
+```
+Deployed to staging.
+
+**PID**: <deploy-id>
+**AVANT** (broken):
+<log/curl/screenshot>
+
+**APRÈS** (fixed):
+<log/curl/screenshot>
+
+Triggered by: <PR #N> / <commit SHA>
+```
+
+## Post-merge closure comment
+
+```
+Fixed: <1 line description>
+
+**Evidence** (from staging):
+<concrete log/curl/DOM — NOT code diffs>
+
+PR: #<N>
+Commit: <SHA>
+```
+
+## Common failure modes
+
+- Declaring "done" while CI is in_progress → wait for completion
+- Declaring "done" with AVANT captured but no APRÈS on staging
+- Evidence from same source as bug, but wrong time (read logs from before the deploy)
+- PR opened with `[WIP]` title → PR never reviewed, rots as draft
+- Batch PR closing 3 issues with one comment copy-pasted → not sufficient, each issue needs its own evidence
+- Closure gate skipped because "CI will auto-close via PR merge" → closure via auto-close never adds evidence comment

package/assets/skills/workflow/quoi-framer/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: quoi-framer
+description: How to frame a task before starting — forces explicit goal, NOT-X constraint, intention partagee, and measurable definition of done. For Ciel v5 pipeline step 2 (QUOI). Use after DOCS phase, before ASK phase.
+---
+
+# Task Framing — Define Before You Start (Ciel v5)
+
+## What this covers
+
+How to define a task clearly before doing any work. This is the first step of the Ciel v5 pipeline (etape 2: QUOI). Applied after DOCS phase (etape 1) and before ASK (etape 3). Prevents scope drift, wasted research, and "I thought you meant..." conversations.
+
+## Core principle
+
+**State the goal, the constraint, the intention, and the done criteria BEFORE researching or coding.** If you can't state these in 5 lines, you don't understand the task yet.
+
+## The 5 output gates (ALL required)
+
+### 1. Expected result
+
+One sentence. Concrete and testable.
+
+- BAD: "Improve the API"
+- GOOD: "GET /api/users returns a paginated list with page+limit query params"
+
+### 2. NOT-X constraint
+
+At least 1 concrete thing the solution MUST NOT do:
+- "NOT-X: no N+1 queries"
+- "NOT-X: no new dependencies added"
+- "NOT-X: no breaking changes to existing callers"
+- "NOT-X: no schema migration"
+
+"no bad code" is not NOT-X. "No global state mutation" is.
+
+### 3. Intentions partagees (v5)
+
+State what you are looking for, not what you expect to find. This guides exploration without biasing it:
+- BAD: "Find where pdfmake is used for PDF export" (cherche une solution specifique)
+- GOOD: "Understand how exports are handled in this project" (intention ouverte)
+
+The intention is passed to @ciel-explorer to guide scent-following without creating confirmation bias.
+
+### 4. Definition of done
+
+Measurable before research starts:
+- "Done when: endpoint returns 200 with `{items, total, page}` shape, test passes on staging, no perf regression vs baseline"
+
+"done when it works" is not acceptable. Specify the observable signal.
+
+### 5. DOCS gate (v5)
+
+Before framing, verify that documentation has been read:
+- README.md (project overview and conventions)
+- ADRs if they exist (architecture decisions)
+- Tickets/specs (requirements context)
+- .ciel/map.json (existing project map)
+- ciel-overlay.md (project overlay)
+
+## Output format
+
+```
+## QUOI
+
+Expected result: <one sentence>
+NOT-X: <concrete constraint>
+Intentions: <what I'm looking for (open question)>
+Done when: <measurable criteria>
+Docs read: <yes — README, ADRs, map, tickets>
+```
+
+## Common rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "This is simple, I don't need to frame it" | Simple tasks benefit from 2-line frames. The frame costs 10 seconds. Scope drift costs hours. |
+| "I already know what to build" | Write it down anyway. Writing forces precision. "I know" is how ambiguity hides. |
+| "NOT-X is obvious" | If it's obvious, writing it takes 2 seconds. If you can't write it, it wasn't obvious. |
+
+## How to verify
+
+- [ ] QUOI statement: 1 sentence, describes WHAT not HOW?
+- [ ] NOT-X constraint: >= 1 explicit exclusion?
+- [ ] Intentions partagees: open question, not solution-biased?
+- [ ] Definition of done: >= 1 measurable criterion?
+- [ ] DOCS gate: documentation has been read?
+
+## When to re-frame
+
+- Start of any task (before research, after DOCS)
+- When scope drift is detected (3+ files touched without re-checking goal)
+- When the user changes direction mid-task