@neikyun/ciel 6.11.0 → 6.11.2

package/assets/skills/workflow/meta-critiquer/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: meta-critiquer
+description: How to reflect on completed work — 10-item post-task reflection checklist for Ciel v5. Covers depth match, failure mode detection, user corrections, stale branches, uncovered issues, context health, dead code, map update, parking lot, and boy-scout rule. Closes the feedback loop between execution and improvement.
+---
+
+# Post-Task Reflection — 10-Item Checklist (Ciel v5)
+
+## What this covers
+
+How to reflect on completed work and capture learnings. In Ciel v5, this is the last pipeline step (etape 16: META). Always run after every task, even trivial ones.
+
+## Core principle
+
+**Always reflect, even after trivial tasks.** 30 seconds is cheap; missed reflections compound. In v5, the reflection covers not just the code but the project map, parking lot, and boy-scout rule.
+
+## The 10 checks (v5)
+
+### 1. Depth match?
+
+Was the task processed at the right depth?
+- Over-processed trivial = waste
+- Under-processed critical = risk
+- Wrong depth -> flag for future classifier refinement
+
+### 2. New failure mode?
+
+Did something go wrong that current gates didn't catch?
+- Yes -> add a new gate immediately
+- Capture the pattern for future reference (in .ciel/learnings.md)
+
+### 3. User correction?
+
+Did the user correct you during the task?
+- Yes -> persist to .ciel/learnings.md
+- Don't just note it -- save it so it doesn't happen again
+
+### 4. Stale branches?
+
+```bash
+git branch -r | wc -l
+```
+Excessive remote branches (> 30) -> consider cleanup of merged branches.
+
+### 5. Uncovered issues?
+
+Any recently closed issues with 0 comments? -> missing evidence comment -> add it now.
+
+### 6. Context health?
+
+After Critical task or 3+ agent dispatches: consider context compression or new session. Stacking Critical tasks in one context window degrades output quality.
+
+### 7. Dead code sweep
+
+Run language-specific linter:
+- **Python**: `ruff check --select F401,F811,F841 . && vulture . --min-confidence 80`
+- **TypeScript**: `npx knip` or manual grep for unused exports
+- **Kotlin**: Detekt `UnusedPrivateMember` + `UnusedImport`
+- **Go**: `go vet ./...`
+- **Rust**: `cargo clippy -- -W unused`
+
+### 8. Map update (v5)
+
+Has the project map (.ciel/map.json) been updated with new modules, key files, or patterns discovered during this task?
+- If exploration happened -> update map
+- If new ADR was written -> reference it in map
+
+### 9. Parking lot (v5)
+
+Were any tangential discoveries made during the task?
+- Yes -> note in .ciel/parking.md
+- Don't act on them now -- just note them
+
+### 10. Boy-scout rule (v5)
+
+Did you leave the code better than you found it?
+- Minor improvements count: better naming, removed dead code, added missing test, improved error message
+- If you only modified what was required and nothing else -> acceptable but note it
+
+## Output format
+
+```
+## REFLECTION
+
+1. Depth match: <match | over/under-processed>
+2. New failure mode: <none | detected>
+3. User correction: <none | captured in .ciel/learnings.md>
+4. Stale branches: <N branches | cleanup recommended>
+5. Uncovered issues: <none | #N needs closure>
+6. Context health: <N% | compact recommended>
+7. Dead code: <0 findings | N fixed>
+8. Map update: <up-to-date | needs update>
+9. Parking: <none | N notes added>
+10. Boy-scout: <improved | status quo>
+
+### ACTION ITEMS
+- <list or "none">
+```
+
+## How to verify
+
+- [ ] All 10 checks completed?
+- [ ] >= 1 action item generated?
+- [ ] User corrections captured (if any)?
+- [ ] Stale branches flagged (if any)?
+- [ ] Map checked for updates?
+- [ ] Parking lot entries noted?
+
+## Key rules
+
+- **Always non-blocking**: reflection never blocks the commit/push
+- **Persist, don't just report**: items 2 and 3 must trigger learnings capture
+- **Map update (item 8) is mandatory after exploration**: without it, the next session starts with a stale map

package/assets/skills/workflow/modern-patterns-checker/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: modern-patterns-checker
+description: Scans proposed or existing code for obsolete patterns that LLMs tend to reproduce from stale training data — React class components instead of hooks, sync-when-async-is-standard, callback hell, Python 2 idioms, old Go error handling, jQuery in React codebases, CommonJS in ESM projects. Flags each anti-pattern with the 2026 canonical replacement and a link to the migration note. Referenced by ThoughtWorks Technology Radar April 2026.
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# modern-patterns-checker — Don't ship 2019-era code in 2026
+
+LLMs over-weight patterns that dominated their training set years ago. Without a guardrail, React class components, callback-based async, and sync-APIs-in-async-codebases keep leaking into new PRs. ThoughtWorks 2026 calls this "cognitive debt from AI autocompletion."
+
+---
+
+## Inputs (infer before asking — see orchestrator's Autonomy protocol)
+
+```
+CODE_UNDER_REVIEW: [file paths OR diff hunk]
+TARGET_STACK: [language + framework + version — resolved from package manifests]
+```
+
+### Auto-inference sources (exhaust BEFORE asking the user)
+
+- **CODE_UNDER_REVIEW** → `git diff main...HEAD` for the branch under review; fall back to `git diff HEAD~1` for the latest commit; or the user-named file(s).
+- **TARGET_STACK** → read `package.json` / `pyproject.toml` / `go.mod` / `Cargo.toml`; derive framework from dependencies (`react`, `vue`, `svelte`, `fastapi`, `django`, etc.). Read `tsconfig.json` / `pyproject.toml` for strictness settings. Cross-check with `ciel-overlay.md`.
+
+Never ask the user for either. Both are deterministically inferable.
+
+---
+
+## Anti-pattern catalogue (2026)
+
+### TypeScript / JavaScript
+
+| Anti-pattern | Canonical 2026 replacement |
+|---|---|
+| `class Foo extends React.Component` | Functional component + hooks |
+| `componentDidMount / componentDidUpdate` | `useEffect` (or Server Component for data fetching) |
+| `.then().catch()` chains > 2 links | `async/await` with `try/catch` |
+| `require()` in a project with `"type":"module"` | `import` (ESM) |
+| `var` | `const` / `let` |
+| `null`-checks everywhere | Discriminated unions + `?.` / `??` |
+| `any` as escape hatch | `unknown` + narrowing, or proper type |
+| `lodash.get` / `lodash.set` | Optional chaining `?.` + `??` |
+| `fetch().then(r => r.json()).then(...)` | `await fetch()` + `await r.json()` |
+| `moment.js` | `Temporal` API (Node 22+) or `date-fns` |
+| Redux for local UI state | `useState` / `useReducer` / Zustand |
+| PropTypes | TypeScript types |
+
+### Python
+
+| Anti-pattern | Canonical 2026 replacement |
+|---|---|
+| `print` as debug | `logging` with structured fields |
+| `%`-format or `.format()` | f-strings |
+| `dict.has_key(k)` | `k in dict` |
+| Nested `if` guards | Early-return pattern |
+| Bare `except:` | `except SpecificError:` |
+| `os.path.join` | `pathlib.Path` |
+| Sync `requests` in async codebase | `httpx.AsyncClient` / `aiohttp` |
+| `dataclass` without `slots=True` | `@dataclass(slots=True)` (3.10+) |
+| `typing.List`, `typing.Dict` | Built-in `list`, `dict` (3.9+ PEP 585) |
+| `from typing import Optional` | `X \| None` (3.10+ PEP 604) |
+
+### Go
+
+| Anti-pattern | Canonical 2026 replacement |
+|---|---|
+| `if err != nil { return err }` without wrapping | `fmt.Errorf("context: %w", err)` |
+| Bare `err == sql.ErrNoRows` | `errors.Is(err, sql.ErrNoRows)` |
+| Passing request context implicitly | Explicit `ctx context.Context` first arg |
+| `interface{}` | `any` (Go 1.18+), or typed interface |
+| `sync.Mutex` wrapping a slice | `sync.Map` or channel |
+
+### SQL
+
+| Anti-pattern | Canonical 2026 replacement |
+|---|---|
+| String concatenation for queries | Parameterized queries / prepared statements |
+| `SELECT *` in production queries | Explicit column list |
+| `N+1` loop queries | JOIN or batched `IN (...)` |
+| Missing indexes on FK | Index on every foreign key |
+
+### React (post-19)
+
+| Anti-pattern | Canonical 2026 replacement |
+|---|---|
+| `useEffect` for data fetching | Server Components, `use()`, or TanStack Query |
+| `useState` for derived values | `useMemo` or compute inline |
+| Prop-drilling > 3 levels | Context, composition, or state library |
+| Manual form state | `react-hook-form` or native `<form>` actions |
+
+---
+
+## Detection method
+
+1. **Regex pass** (fast) — grep for obvious markers: `extends Component`, `componentDidMount`, `require(`, `var `, `any`, `.then(.*).then(`, etc.
+2. **AST pass** (accurate, optional) — if `tsc` / `ruff` / `go vet` configured in the repo, run with strict rules.
+3. **Context pass** — read `tsconfig.json`, `pyproject.toml`, `go.mod` to confirm the stack is modern enough to allow the replacement. Don't suggest `Temporal` if Node is pinned to 18.
+
+---
+
+## Report format
+
+```
+## MODERN-PATTERNS VERDICT
+
+### Findings
+[BLOCK]  components/Profile.tsx:24 — class component
+         Replacement: functional + hooks
+         Migration: react.dev/reference/react/Component#alternatives
+
+[WARN]   lib/api.ts:55-70 — .then() chain (3 links)
+         Replacement: async/await
+         Rationale: readability + stack traces
+
+[INFO]   tests/user.test.ts:8 — `any` as escape hatch
+         Replacement: `unknown` + narrowing, or proper User type
+         Rationale: loses type safety in test-critical code
+
+### Stack-compatibility confirmed
+- Node: 22.3 ✓ allows Temporal
+- TS: 5.5 ✓ allows `satisfies` operator
+- React: 19.0.2 ✓ allows Server Components
+
+### Summary
+BLOCK: 1  (must fix)
+WARN:  1  (strongly advised)
+INFO:  1  (opportunistic)
+```
+
+---
+
+## Guardrails
+
+- **Verify stack before recommending** — suggesting `Temporal` on Node 18 wastes a review cycle.
+- **Don't aggregate-rewrite legacy** — flag, don't refactor wholesale. A single migration is a PR, not a silent edit.
+- **Repo-level opt-outs respected** — if `.eslintrc` deliberately allows `var` or a deprecated pattern (grandfather clause for a legacy module), note and skip.
+- **Citation required** — every suggestion links to the official migration doc or the MDN/React/Python guide. No link → drop the suggestion.
+- **BLOCK only for compile-breaking or security-sensitive** — class components don't BLOCK a working PR; a missing parameterized query DOES.
+- **Stop at 10 findings per file** — above 10, return "file needs a dedicated modernization task" rather than a linter dump.
+
+---
+
+## How to verify
+
+- [ ] Anti-pattern catalogue checked for each language in stack?
+- [ ] Each finding has 2026 canonical replacement?
+- [ ] Stack compatibility confirmed?
+- [ ] VERDICT issued (CLEAN / FINDINGS)?
+- [ ] Migration notes provided for each finding?
+
+## When triggered
+
+- CODEBASE step after `explorer` reads the target files
+- `@ciel-explorer` dispatched for PR review
+- Before accepting LLM-generated code in a legacy codebase (high drift risk)
+- After `@ciel-researcher` validates an API — this skill confirms the call site uses modern idioms
+
+---
+
+## References
+
+- ThoughtWorks Technology Radar April 2026 — "curated shared instructions" volume
+- React 19 migration guide — react.dev/blog/2024/04/25/react-19
+- PEP 585 / PEP 604 — Python builtin-generics + union syntax
+- Go 1.18 — `any` alias, generics
+- MDN Async/Await — developer.mozilla.org/en-US/docs/Learn/JavaScript/Asynchronous

package/assets/skills/workflow/pattern-fitness-check/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: pattern-fitness-check
+description: For every existing code pattern being considered for reuse, applies a 3-question fitness check (same problem? same constraints? same volume?) before copying. Flags HUBs (high fan-in files), duplication candidates, and prior AI-generated patterns that contradict official docs. Invoked during the CODEBASE step of every Ciel task.
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# pattern-fitness-check — Don't copy patterns blindly
+
+Part of CRÉER step 5 (CODEBASE). Pattern-matching without fitness checking is the single most common LLM coding failure (per Ciel's Guards table).
+
+---
+
+## 3-question fitness check
+
+For EACH pattern considered for reuse, answer all 3:
+
+1. **Same problem?** — What problem did this pattern solve originally? (git blame the commit)
+   - If the pattern was written for use case A and you're facing use case B → NOT the same problem.
+
+2. **Same constraints?** — Volume, transport, sync/async, batch/single, cardinality
+   - Pagination pattern written for 1k items might fail at 100M items.
+   - Sync validation pattern might not fit async flow.
+   - REST pagination pattern doesn't fit WebSocket message stream.
+
+3. **Same data shape?** — Is the input/output structure identical?
+   - Different field names → adapter needed
+   - Different nullable fields → null-safety differs
+   - Different ordering guarantees → might break downstream
+
+→ **All yes** → APPLY. **Any no** → ADAPT or DO NOT USE.
+
+---
+
+## Additional checks
+
+### Prior AI-generated patterns
+
+Treat existing code written during a prior AI session as a **suggestion, not law**. If it contradicts current official docs → likely an inherited anti-pattern. Flag and do not follow.
+
+Signal: code with unusual structure, comments like `// AI-suggested` or `// TODO: verify this approach`.
+
+### Duplication check
+
+If 2+ copies of the pattern you're about to write ALREADY EXIST → extract a shared helper FIRST, then use it.
+
+```bash
+# Find similar patterns
+grep -rn "fun <functionName>" --include='*.kt' src/
+```
+
+### Mini repo-map (3 greps)
+
+For impacted files, build a minimal map:
+
+1. **Signatures** — `grep -n "^fun \|^class \|^interface \|^object " <file>`
+2. **Dependents** — `grep -rln "import .*<filename>" src/`
+3. **Hub check** — if step 2 returns 5+ files → **HUB WARNING**: changes ripple widely, proceed with caution
+
+---
+
+## Output format
+
+```
+## PATTERN FITNESS
+
+### Patterns considered
+- APPLY: <pattern at file:line> — same problem ✓ same constraints ✓ same shape ✓
+- ADAPT: <pattern at file:line> — <what differs> → <how to adapt>
+- DO NOT USE: <pattern at file:line> — <reason>
+
+### Mini repo-map
+- Impacted files: <list>
+- Key signatures: <func/class at file:line>
+- Dependents (1 hop): <list>
+- Hub check: <NO — safe | YES — N files, changes ripple>
+
+### Duplication check
+- [None / Found N copies at file:line — extract helper first]
+
+### Prior AI patterns
+- [None / Flagged: <file:line> contradicts <doc URL> — do not follow]
+```
+
+---
+
+## Guardrails
+
+- **Git blame mandatory** for "same problem?" — don't rely on current code reading. Read the commit message where the pattern was introduced.
+- **Numeric constraints**: quantify "volume" — "1k items" vs "1M items" matters. Don't say "big" or "small".
+- **HUB threshold**: 5+ importers is the default; adjust per project size. A core util imported by 50+ files is extremely high-ripple — needs cross-team coordination.
+- **Don't over-adapt**: if adaptation grows to > 50 lines different from the original, just write new code. Adapting is not saving effort.
+
+---
+
+## How to verify
+
+- [ ] 3-question fitness check applied (same problem? same constraints? same volume)?
+- [ ] Prior AI-generated patterns flagged?
+- [ ] Duplication check performed (≥ 2 copies)?
+- [ ] Mini repo-map generated (impacted files, key signatures, dependents)?
+- [ ] Hub check performed (high fan-in files)?
+
+## When triggered
+
+- Standard/Critical tasks, during CODEBASE step
+- Trivial tasks, if the fix is "use an existing pattern" (quickly — 1 pattern, 1 fitness check)
+- When user says "we already have code for this" or "reuse X"
+- When `explorer` agent identifies a candidate pattern

package/assets/skills/workflow/playwright-visual-critic/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: playwright-visual-critic
+description: How to review UI visually using Playwright MCP — launch dev server, capture accessibility tree (not screenshots), check layout/contrast/focus/responsive at multiple viewports, and produce structured findings. Prefers accessibility-tree analysis over pixel screenshots (deterministic, 2-5KB vs 100KB+). Requires Playwright MCP configured.
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Playwright Visual Critique — See Before Shipping UI
+
+## What this covers
+
+How to visually review UI using Playwright MCP. UI bugs invisible to code review: clipped text, contrast failures, broken focus order, mobile overflow. The 2026 pattern is NOT "screenshot → vision model"; it's "accessibility tree → structured critique", which is 20-50x cheaper and more accurate.
+
+## Core principle
+
+**Accessibility tree first, screenshots last.** Tree is deterministic, cheap, and doesn't break on font/rendering differences. Screenshots are brittle and expensive to analyze.
+
+## Prerequisites
+
+Playwright MCP must be installed:
+
+```bash
+# One-time setup
+claude mcp add playwright --transport stdio -- npx @playwright/mcp@latest
+```
+
+Verify with: `claude mcp list | grep playwright`.
+
+If not installed → STOP and instruct the user to run the command above. Do not attempt to critique without it.
+
+## Methodology
+
+### Capture via Playwright MCP
+
+1. **`browser_navigate`** — navigate to target URL
+2. **`browser_resize`** — for each viewport (375 mobile, 768 tablet, 1440 desktop)
+3. **`browser_snapshot`** — accessibility tree (structured YAML/JSON)
+4. **`browser_take_screenshot`** — only if visual regression check needed (cost optimization)
+5. **`browser_console_messages`** — check for JS errors / a11y violations
+
+### Visual critique checklist
+
+**Layout**
+- No horizontal overflow (no element with `scrollable: true` on x-axis for main content)
+- No clipped text (elements with `hidden: true` while `expected: visible`)
+- No zero-size interactive elements (touch targets ≥ 24×24px per WCAG 2.5.8)
+
+**Contrast & color**
+- Text contrast ≥ 4.5:1 (normal text) / 3:1 (large text)
+- Color is not the sole signal (error states have icon/text, not just red)
+
+**Keyboard & focus**
+- Every interactive element has `focusable: true`
+- Focus order matches visual order (tree `focus_index` is monotonic)
+- No focus trap unless intentional (modal dialogs)
+- `:focus-visible` ring is present (no `outline: none` without alternative)
+
+**Responsive**
+- At 375px width, primary content fits without zoom
+- Navigation collapses to mobile pattern (drawer / bottom-nav) — not truncated desktop nav
+
+**Semantic structure**
+- One `<h1>` per page
+- `<main>`, `<nav>`, `<header>`, `<footer>` landmarks present
+- Form inputs have associated labels (tree `label_id` populated)
+
+**Console**
+- No JS errors
+- No React / Vue / Svelte warnings
+- No axe-core violations (if integrated)
+
+## Key points
+
+- **Do not attempt if MCP not installed** — halt cleanly with install instructions
+- **Timebox**: 3 viewports × 5 minutes analysis = 15 min hard cap
+- **Don't critique Lighthouse perf metrics here** — stay on visual + a11y
+- **Auth-gated pages**: instruct the user to seed a test session cookie first. Do not attempt to handle login credentials
+- **Local dev SSL**: use `--ignore-https-errors` in Playwright MCP config for self-signed certs
+
+## Common anti-patterns
+
+1. **Screenshot-first analysis**: pixel screenshots are brittle, break on font differences, and cost 20-50x more to process
+2. **No viewport variation**: mobile bugs are the most common and the most missed — always test at 375px
+3. **Ignoring console output**: JS errors and framework warnings often point to the root cause
+4. **Critiquing without MCP installed**: will fail silently or produce empty results — always verify prerequisites
+
+## How to verify
+
+- **All viewports checked**: mobile, tablet, desktop — no skipped
+- **Findings have selectors**: every issue points to a specific element in the accessibility tree
+- **Severity classified**: BLOCK (broken), WARN (bad practice), INFO (minor)
+- **Console clean**: no JS errors or framework warnings
+
+## References
+
+- Playwright MCP — playwright.dev/docs/getting-started-mcp
+- github.com/microsoft/playwright-mcp — official implementation
+- alexop.dev — "Building an AI QA Engineer with Claude Code and Playwright MCP" (real-world pattern)
+- WCAG 2.2 — w3.org/WAI/WCAG22/Understanding/ (AA criteria used in the checklist)