@neikyun/ciel 6.11.2 → 6.13.0

package/assets/skills/iac/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: iac
+description: "IaC — l'infrastructure comme code, pas comme clics. State management, drift detection, modules, immutabilite. A charger quand on definit ou modifie l'infrastructure."
+---
+
+# Infrastructure as Code
+
+**Principe premier :** L'infrastructure n'est pas une liste de ressources a creer — c'est un programme dont le state est la verite. La console est un outil de debugging, pas de gestion. Chaque clic est une dette qui sera oubliee et qui cassera au pire moment. Le vrai benefice de l'IaC n'est pas la vitesse de creation (la console est plus rapide pour 1 instance) — c'est la repetabilite : meme code → meme infra, dans 6 mois, par un autre humain, sans surprise. Le state file est ton inventaire physique — si tu le perds, tu reconstruis ou tu importes, mais tu ne devines pas.
+
+## Checklist
+- [ ] Toute l'infrastructure est dans le code — zero ressource creee a la main (verifie avec drift detection)
+- [ ] Le state est stocke dans un backend securise (S3 + DynamoDB lock, Terraform Cloud, Pulumi SaaS) — jamais en local
+- [ ] Les modules sont versionnes (tag git, pas `source = "../common"`)
+- [ ] Les ressources sont immutables — on remplace, on ne modifie pas en place
+- [ ] Les secrets sont referencees depuis un secret manager, pas en clair dans le code
+- [ ] Le plan est toujours sauvegarde (`terraform plan -out=plan.out`) et applique depuis le meme fichier
+- [ ] Drift detection tourne regulierement (hebdomadaire ou dans la CI) — alerter si ecart
+
+## Anti-patterns
+### Console comme outil principal
+**Ce qu'on voit :** l'equipe cree les ressources a la main "parce que c'est plus rapide". 6 mois plus tard, 200 ressources non trackees, configuration inconnue.
+**Pourquoi c'est dangereux :** la console ne laisse pas de trace. Pas de review possible. Pas de rollback. Impossible de reproduire l'environnement. Le disaster recovery devient un puzzle.
+**Faire plutot :** toute ressource est definie dans le code. Si une ressource existe deja, l'importer (`terraform import`) puis la gerer en code. La console est en read-only.
+
+### State local
+**Ce qu'on voit :** `terraform.tfstate` dans le repo ou sur le laptop du dev. "C'est bon, je l'ai en local."
+**Pourquoi c'est dangereux :** le laptop meurt, le state est perdu. Deux devs appliquent en parallele → corruption. Le state contient des donnees sensibles (passwords, private keys) → fuite.
+**Faire plutot :** backend distant avec locking (S3 + DynamoDB). Chaque `apply` verifie le lock. Le state est chiffre. Les secrets sont marques `sensitive` dans le code, pas extraits du state.
+
+### Module monolithe
+**Ce qu'on voit :** un seul module `main.tf` de 2000 lignes qui gere tout : reseau, compute, DB, DNS, IAM. Chaque changement fait peur.
+**Pourquoi c'est dangereux :** blast radius maximal. Un changement de DNS peut detruire la DB si le state est corrompu. La revue est impossible. Le `terraform plan` prend 10 minutes.
+**Faire plutot :** infrastructure decomposee en modules independants. Reseau dans un state, compute dans un autre, DB dans un autre. Chaque module a son propre cycle de vie. Les dependances sont explicites (data sources, remote state).
+
+## Patterns
+### Immutabilite
+**Quand :** toute ressource modifiable (instances, conteneurs, lambdas).
+**Comment :** `create_before_destroy = true`. On cree la nouvelle ressource, on valide, puis on detruit l'ancienne. Pas de modification en place. Le code est la verite — si le code change, la ressource est remplacee.
+
+### Drift detection
+**Quand :** toute equipe de plus d'une personne.
+**Comment :** `terraform plan -detailed-exitcode` ou `pulumi refresh --diff` dans la CI chaque semaine. Si drift → ticket automatique. Corriger la cause (console ? script maison ?) pas juste l'effet.
+
+### GitOps
+**Quand :** deploiement continu de l'infrastructure.
+**Comment :** le repo git est la source de verite. Un merge sur main declenche le plan, puis l'apply. Pas de `terraform apply` depuis un laptop. Le pipeline a les permissions IAM minimales (OIDC).

package/assets/skills/logging/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: logging
+description: "Logging — structured JSON, correlation ID, PII scrubbing, centralized aggregation, log levels as signal. À charger quand on configure les logs."
+---
+
+# Logging
+
+**Principe premier :** Les logs ne sont pas pour toi — ils sont pour le "toi du futur" qui debug une erreur à 3h du matin sans contexte. Un log qui dit "Error occurred" est pire que pas de log — il donne l'illusion d'information. Chaque log doit répondre à : quoi, quand, où, qui, et pourquoi c'est arrivé. Le format est JSON structuré, pas du texte libre — parce que les logs seront parsés par des machines (Loki, ELK, Datadog) bien avant d'être lus par des humains.
+
+## Checklist
+- [ ] Logs structurés JSON — pas de `console.log("texte libre " + variable)`
+- [ ] Correlation ID (trace ID) injecté et transmis à travers tous les services
+- [ ] Niveaux de log respectés : ERROR (action requise), WARN (attention), INFO (normal), DEBUG (détail)
+- [ ] Stack trace + contexte (userId, orderId, params) dans chaque ERROR
+- [ ] PII/secret scrubbing : jamais de password, token, carte bancaire, email dans les logs
+- [ ] Centralisation : tous les logs vers un endpoint unique (Loki/ELK/CloudWatch)
+- [ ] Rétention configurée : hot 7j, warm 30j, cold 1 an
+
+## Anti-patterns
+### Log texte libre
+**Ce qu'on voit :** `console.log("User " + userId + " logged in at " + Date.now())`. Concaténation de strings.
+**Pourquoi c'est dangereux :** impossible à parser automatiquement. Pas de champ structuré. Recherche et filtrage impossibles sans regex fragiles. Si le format change légèrement, tous les dashboards cassent.
+**Faire plutôt :** `logger.info({ event: "user_login", userId, timestamp }, "User logged in")`. JSON structuré. Champs typés. Requêtable.
+
+### Pas de correlation ID
+**Ce qu'on voit :** chaque service logue avec son propre ID. Impossible de suivre une requête à travers 3 microservices.
+**Pourquoi c'est dangereux :** debug en microservices = ouvrir 3 terminaux, chercher manuellement des timestamps qui coïncident. Une requête lente = mystère complet.
+**Faire plutôt :** correlation ID généré à l'entrée (API Gateway). Transmis dans chaque header HTTP. Logué dans chaque service. Une recherche = une requête = tous les logs.
+
+### Données sensibles dans les logs
+**Ce qu'on voit :** `logger.error("Payment failed", { cardNumber, cvv, userId })`.
+**Pourquoi c'est dangereux :** PCI-DSS violé. Données bancaires dans les logs. En cas de fuite des logs, toutes les cartes compromises. Les logs sont souvent moins protégés que la DB.
+**Faire plutôt :** `logger.error("Payment failed", { paymentId, errorCode, userId })`. Jamais de PII ou secret. Scrub automatisé en cas de doute.
+
+## Patterns
+### Structured JSON logging
+**Quand :** toute application.
+**Comment :** chaque log = `{timestamp, level, message, service, correlationId, ...context}`. Parse, filtre, indexe par Loki/ELK. Requêtable : `{.level = "ERROR"} | json | ...`
+
+### Centralized aggregation
+**Quand :** plus d'un service.
+**Comment :** tous les logs → stdout (K8s/Docker) → Promtail (parse, label) → Loki (stocke) → Grafana (requete LogQL). Un seul endroit pour chercher. LogQL : `{service="api", level="error"} |= "payment" | json`. Depuis Grafana, lien direct : log → trace ID → Tempo → span exact.
+
+### Debug flow Grafana (metrics → logs → traces)
+**Quand :** incident en production.
+**Comment :** (1) Grafana dashboard : métrique RED rouge → clic sur le point → (2) "Explore logs" → LogQL filtré par temps + service → (3) extraire le trace ID du log → (4) Tempo : trace complète avec tous les spans. Sans intégration, ces 3 outils sont séparés. Avec Grafana, ils sont liés.

package/assets/skills/meta/ciel-improve/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: ciel-improve
+description: Analyzes recent session transcripts to detect repeated failure modes, user corrections, and skill output truncation, then produces a patch-set proposing specific rewrites for Ciel skills. Never rewrites autonomously — always returns a patch-set for user approval.
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# ciel-improve — Meta-skill for self-improvement
+
+## What this covers
+This is the heart of Ciel's self-modification subsystem. It reads conversation history, identifies where skills failed to trigger or produced weak output, and proposes concrete rewrites.
+
+## Core principle
+**Never rewrite autonomously.** Every change is a proposal. The user approves each patch individually.
+
+## Inputs
+
+- **Session transcripts**: last N session JSONL files (default N=10)
+- **Current Ciel version**: `.version` SHA
+- **Project learnings**: `.claude/learnings.md` (if exists)
+- **Latest eval scores**: `evals/results/*.json` (if exist)
+
+## Process
+
+### 1. Parse transcripts
+
+For each session JSONL, extract:
+- User messages (what was asked)
+- Tool calls (what was invoked)
+- User corrections ("non", "that's wrong", "use X instead")
+- Skill triggers (log lines `SkillInvoked: <name>`)
+
+### 2. Identify issues
+
+Classify each turn:
+- **UNTRIGGERED**: skill should have fired but didn't
+- **MISTRIGGERED**: skill fired when it shouldn't have
+- **TRUNCATED**: output < 200 tokens on non-trivial task
+- **CORRECTED**: user explicitly corrected behavior
+- **REPEATED**: same failure 2+ times across sessions
+
+### 3. Map issues to skills
+
+For each issue, find the responsible skill:
+- Description didn't match intent → patch description
+- Output truncated → patch output constraints
+- Correction repeated → patch to enforce corrected behavior
+
+### 4. Generate candidate rewrites
+
+For each responsible skill, produce 2-3 candidates:
+- **A**: baseline (current)
+- **B**: tightened gates + more specific description
+- **C**: reduced scope + clearer trigger phrasing
+
+### 5. Run `skill-variant-evaluator` on each candidate
+
+Winner = highest aggregate binary score (tiebreak: lowest token usage).
+
+### 6. Produce patch-set
+
+```
+## Patch 1 — skills/<category>/<name>/SKILL.md
+Issue: <REPEATED: user corrected "use pip not uv" 3 times>
+Baseline score: 0.62 | Candidate B score: 0.89 (winner)
+
+--- BEFORE (lines 15-20)
+<old block>
+--- AFTER
+<new block>
+
+Approve? [y/n/edit]
+```
+
+## Common patterns
+
+### Good improvement proposal
+
+```
+# Ciel improvement proposals — 2026-04-23
+
+Sessions analyzed: 5
+Issues detected: 3
+Patches proposed: 2
+
+## Patch 1 — skills/utility/commit-writer/SKILL.md
+Issue: CORRECTED — user said "add issue reference" 3 times, skill didn't enforce it
+Before: "If branch name matches pattern, add Closes #N"
+After: "feat/fix commits MUST have Closes #N. If no issue detected, prompt user."
+
+## No-fix issues (user must decide)
+- User prefers squash merges but pr-merger defaults to merge commit — preference, not bug
+```
+
+### Bad improvement proposal
+
+```
+Found some issues. Fixed them.
+```
+
+Problems: no patches, no scoring, no user approval, autonomous rewrite.
+
+## Anti-patterns
+
+- **Autonomous rewrite** — NEVER write changes directly. Always propose patches.
+- **> 5 patches per run** — too noisy. Pause and ask user.
+- **Description rewrite > 200 chars** — prevents wholesale rewrites
+- **> 1 new skill per run** — prevents skill explosion
+- **Proposing skill deletion** — user decides manually
+- **Breaking YAML** — every patch must preserve valid frontmatter
+
+## How to verify
+
+- [ ] Sessions parsed (≥ 1 transcript read)?
+- [ ] Issues classified (UNTRIGGERED/MISTRIGGERED/TRUNCATED/CORRECTED/REPEATED)?
+- [ ] Each issue mapped to a responsible skill?
+- [ ] Candidates generated (2-3 per issue)?
+- [ ] Patch-set returned (not applied)?
+- [ ] Patch count ≤ 5?
+- [ ] YAML frontmatter preserved in all patches?
+
+## When triggered
+
+- User runs `/ciel-improve`
+- User asks "can you improve yourself?" or "analyze my recent sessions"
+- `improver` agent invokes this skill
+
+Do NOT trigger on every task — this is an infrequent meta operation.

package/assets/skills/meta/learnings-capture/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: learnings-capture
+description: Mines the recent conversation for user corrections and failure modes, extracts MISTAKE→RULE pairs, and appends them to .claude/learnings.md or ciel-overlay.md. Invoked automatically at session boundaries. Deduplicates against existing entries.
+allowed-tools: Read, Bash
+---
+
+# learnings-capture — Auto-capture session learnings
+
+## What this covers
+Closes the feedback loop: every user correction or failure mode observed in a session becomes a persistent rule that Ciel applies in future sessions.
+
+## Core principle
+**Every correction is a learning opportunity.** If the user said "no, use X" — that becomes a rule. If a test failed because of Y — that becomes a rule. Capture it before the session ends.
+
+## Inputs
+
+- **conversation-scope**: last N turns to analyze (default 20)
+- **target-file**: `local` → `.claude/learnings.md` | `project` → `ciel-overlay.md` | `auto` (default)
+
+## Process
+
+### 1. Scan recent turns
+
+Read the last 20 turns. Skip if < 5 turns.
+
+### 2. Extract signals
+
+- **User corrections**: "no, use X", "stop doing Y", "always X", "never Y"
+- **Failure modes**: test failures, CI red, "the fix broke X"
+- **Positive patterns**: "that worked", "keep doing X"
+
+### 3. Formulate MISTAKE → RULE pairs
+
+```
+[<date>] MISTAKE: <what happened> → RULE: <how to avoid it>
+```
+
+Example:
+```
+[2026-04-23] MISTAKE: used `npm install` despite project using Bun → RULE: check for bun.lockb before picking package manager
+```
+
+### 4. Classify scope
+
+- **local** — project-agnostic → `.claude/learnings.md`
+- **project** — tied to this project's stack → `ciel-overlay.md`
+
+### 5. Deduplicate
+
+Check if RULE portion (normalized) already exists. Skip if duplicate.
+
+### 6. Append
+
+Append new pairs at bottom of target file under `## Leçons projet` or `## Learnings`.
+
+## Common patterns
+
+### Good learning capture
+
+```
+# Session learnings captured
+
+Turns analyzed: 15
+Signals detected: 3
+New pairs: 2
+Duplicates skipped: 1
+
+## Appended to ciel-overlay.md
+- [2026-04-23] MISTAKE: used vi.mock() for internal service → RULE: use vi.spyOn() for internal logic, vi.mock() only for external I/O
+- [2026-04-23] MISTAKE: committed .env file → RULE: check git diff --cached for .env before commit
+```
+
+### Bad learning capture
+
+```
+Captured some learnings.
+```
+
+Problems: no pairs, no dedup, no classification.
+
+## Anti-patterns
+
+- **Overwriting** — always append, never overwrite
+- **Deleting** — even "wrong" learnings stay
+- **Dedup threshold too low** — 80% lexical similarity = duplicate
+- **> 10 pairs per session** — pick top 10, skip rest
+- **PII captured** — filter passwords, tokens, emails before writing
+- **No timestamp** — use `[YYYY-MM-DD]` format
+
+## How to verify
+
+- [ ] ≥ 1 turn analyzed?
+- [ ] Signals detected and classified?
+- [ ] MISTAKE → RULE pairs formatted correctly?
+- [ ] Scope classified (local/project)?
+- [ ] Deduplication performed?
+- [ ] PII filtered out?
+- [ ] Pairs appended (not overwritten)?
+
+## When triggered
+
+- `Stop` hook fires at session end
+- `PreCompact` hook fires before context compaction
+- User says "capture what we just learned"
+- `meta-critiquer` invokes at step 3 (user correction detected)

package/assets/skills/meta/patch-spec/patch-spec.md

@@ -0,0 +1,50 @@
+# Patch-Set Format Specification
+
+Shared output format for `ciel-improve` (transcript-driven skill rewrites) and `skill-freshness-auditor` (external-reference freshness). Both produce the same structure for user approval.
+
+## Format
+
+Each patch-set is a markdown file with sections. One patch per change, never batched.
+
+```
+## Patch <N>/<TOTAL>: <brief description>
+
+### File
+<relative path to the SKILL.md or file>
+
+### Change
+<what to add, remove, or modify — exact text>
+
+### Rationale
+<why this change improves the skill — 1-2 sentences>
+
+### Evidence
+<for freshness: the source URL + what changed>
+<for improve: the transcript excerpt that triggered this>
+```
+
+## Rules
+
+1. **Max 5 patches per run** — a larger change means the skill needs a rewrite, not patches
+2. **One patch per concern** — never batch unrelated changes into one patch
+3. **Relative paths only** — never absolute paths
+4. **No auto-apply** — patches are for user approval only
+5. **Evidence is mandatory** — without evidence, the patch is speculation
+
+## Example
+
+```
+## Patch 1/3: Update Playwright MCP version pin
+
+### File
+skills/domain/mcp-configurator/SKILL.md
+
+### Change
+Replace `@playwright/mcp@latest` with `@playwright/mcp@1.52.0`
+
+### Rationale
+v1.52.0 added `browser_drop` tool, fixing a gap in file upload workflow.
+
+### Evidence
+https://github.com/microsoft/playwright-mcp/releases/tag/v1.52.0
+```

package/assets/skills/meta/skill-creator/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: skill-creator
+description: Creates a new Ciel skill from a conversation pattern or explicit user request. Validates kebab-case naming, YAML frontmatter, file size limits, and progressive-disclosure structure. Returns proposed SKILL.md for user approval — never writes directly.
+allowed-tools: Read, Glob, Bash
+---
+
+# skill-creator — Meta-skill for skill creation
+
+## What this covers
+Generates a valid SKILL.md scaffold following Ciel's conventions. Returns a diff for user approval, then applies it if approved.
+
+## Core principle
+**Skills are discovered, not registered.** The `description` field is the skill's search key. If it's vague, the skill won't trigger.
+
+## Inputs
+
+- **name**: kebab-case, max 64 chars, unique
+- **category**: `workflow`, `research`, `domain`, `utility`, `meta`
+- **purpose**: one-line description (becomes `description` foundation)
+- **context-fork?**: needs isolated fork context? (boolean)
+- **tools-needed**: subset of available tools
+
+## Validation pipeline
+
+### 1. Name validation
+
+- Regex: `^[a-z0-9][a-z0-9-]{0,62}[a-z0-9]$`
+- Reserved: reject `anthropic`, `claude`, `mcp` prefixes
+- Uniqueness: check existing skills — no collision
+- Category prefix: warn if redundant (e.g. `workflow-foo` in `workflow/`)
+
+### 2. Description generation
+
+- Third person: "Analyzes X" ✓ / "I analyze X" ✗
+- Front-load use case + trigger keywords
+- Include "Use when..." clause
+- ≤ 1024 chars, recommended 200-500
+
+### 3. Scaffold SKILL.md
+
+```markdown
+---
+name: <name>
+description: <generated description>
+[allowed-tools: <tools> — only if non-default]
+[context: fork — only if needed]
+[agent: <agent-type> — only if context: fork]
+---
+
+# <human-readable name>
+
+<1-2 sentence overview>
+
+---
+
+## Inputs
+<expected inputs>
+
+## Process
+<steps>
+
+## Output format
+<expected output shape>
+
+## Guardrails
+<rules>
+
+## When triggered
+<triggers>
+```
+
+### 4. Optional reference.md
+
+If user indicates need for extended content, generate `reference.md` alongside SKILL.md. Only ONE level of reference, never nested.
+
+## Common patterns
+
+### Good skill description
+
+```yaml
+description: Generates 3 hostile critiques per changed file (1 functional, 1 import, 1 data-assumption) and resolves each with FIX/ACCEPT/DEFER. Invoked by the critic agent on Write/Edit for Standard/Critical tasks with 3+ changed files.
+```
+
+### Bad skill description
+
+```yaml
+description: Helps with code review.
+```
+
+Problems: no trigger, no output, no specificity.
+
+## Anti-patterns
+
+- **Max 1 new skill per invocation** — prevents skill explosion
+- **SKILL.md ≤ 300 lines** — aim for 100-200
+- **reference.md ≤ 500 lines**
+- **Duplication check** — if ≥ 70% keyword overlap with existing skill, warn
+- **Never create**: `claude-*`, `anthropic-*`, `mcp-*` names
+- **Always preserve**: valid YAML frontmatter
+
+## How to verify
+
+- [ ] Name valid kebab-case, ≤ 64 chars, unique?
+- [ ] Category is one of the 5 valid categories?
+- [ ] Description: third person, ≤ 1024 chars, includes trigger?
+- [ ] SKILL.md ≤ 300 lines?
+- [ ] No overlap with existing skills (grep checked)?
+- [ ] YAML frontmatter valid?
+- [ ] Catalog entry appended to reference.md?
+
+## When triggered
+
+- User runs `/ciel-create-skill <name> <purpose>`
+- `ciel-improve` detects a pattern worth extracting
+- User says "create a skill for X" or "turn this into a skill"

package/assets/skills/meta/skill-freshness-auditor/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: skill-freshness-auditor
+description: Scans every Ciel skill (SKILL.md + reference.md) for stale external references — outdated library version pins, dead URLs, superseded research citations — and produces a freshness patch-set proposing specific rewrites for user approval. Complements `ciel-improve` (transcript-driven) by catching drift from the outside world instead of from observed failures. Never auto-rewrites; always returns a patch-set.
+allowed-tools: Read, Grep, Glob, Bash, WebFetch, WebSearch
+---
+
+# skill-freshness-auditor — Keep skills current against external reality
+
+Skills age through two channels: (a) **inside** — user corrections, observed failures, truncation (handled by `ciel-improve`); and (b) **outside** — the library you pinned shipped a new major, the official docs URL moved, the research paper you cited was superseded. This skill owns channel (b).
+
+Output is always a proposal — user approves each patch before it writes to disk.
+
+---
+
+## Inputs
+
+- **skills-root**: defaults to `$CIEL_DIR/skills/` (or `./skills/` if running against a clone). Optionally filter via `--scope=<category>` (workflow/research/domain/utility/meta/ciel).
+- **freshness-window**: defaults — URLs older than 18 months = warn, library majors older than 12 months = warn, research citations older than 24 months = warn. Overridable.
+- **max-patches**: defaults 5 per run (same cap as `ciel-improve`).
+
+---
+
+## Process
+
+### 1. Enumerate skills
+
+```bash
+find "$SKILLS_ROOT" -name SKILL.md -o -name reference.md
+```
+
+For each file, record path + last-modified time (`git log -1 --format=%ai <path>` if in a repo, else mtime).
+
+### 2. Extract external references
+
+Three categories (grep-based extraction per skill):
+
+| Category | Regex / heuristic | Examples in existing skills |
+|---|---|---|
+| **URL** | `https?://[^\s)]+` | docs.anthropic.com, cli.github.com, raw.githubusercontent.com |
+| **Library + version pin** | `\b([A-Za-z][\w\-./]+)\s+(v?\d+\.\d+(?:\.\d+)?)` OR table rows like `Playwright 1.49` | Vitest, Playwright, React, Ktor, Anthropic SDK |
+| **Research citation** | `\b(STRATUS|CriticBench|IdentityChain|ThoughtWorks.*Tech Radar|OWASP Top \d+|WCAG [\d.]+|SLSA Level \d+) (\d{4})` | STRATUS 2024, ThoughtWorks Tech Radar April 2026 |
+
+Store per-skill: `[(category, text, location), ...]`.
+
+### 3. Freshness check per reference
+
+Dispatch three sub-procedures **in parallel** (one per category) to minimize wall-clock:
+
+#### 3a. URL liveness
+For each URL:
+- `WebFetch url="$URL" prompt="Return just the HTTP status and Last-Modified header if shown."` — ≤ 200 tokens/check.
+- Flag if: 404, 301/302 to unrelated domain, OR Last-Modified > freshness-window.
+
+#### 3b. Library version drift
+For each library + version pair:
+- `WebSearch "<library> latest stable version 2026"` (or current year).
+- Extract the latest major/minor from the first 2 results.
+- Flag if: pinned major ≠ latest major (breaking-change gap) OR pinned minor < latest - 2 minors.
+
+#### 3c. Research citation recency
+For each citation:
+- `WebSearch "<name> <year+1 or later> superseded revised v2"` — look for a newer version.
+- Flag if: a newer paper/version exists AND is >6 months old (not a preprint hot off the press).
+
+### 4. Produce the freshness patch-set
+
+For each flagged finding, emit ONE patch entry. Format identical to `ciel-improve` patches (reuses that skill's approval UX):
+
+```
+## Patch K — skills/<category>/<name>/SKILL.md — FRESHNESS-<subcategory>
+Reference: `<exact text>` at line N
+Finding: <1 sentence why it's stale — with freshness-source URL>
+Severity: HIGH (broken) | MEDIUM (outdated) | LOW (minor)
+
+--- BEFORE (line N)
+<old line>
+--- AFTER (proposed)
+<new line with updated ref>
+
+Approve? [y/n/edit]
+```
+
+Per-severity handling:
+- **HIGH** (broken): 404 URL, removed-from-npm library → proposed AFTER = best replacement found, or `[BROKEN — resolve manually]` marker
+- **MEDIUM** (outdated): version drift 1 major behind, URL still-200-but-redirecting → AFTER = latest pin
+- **LOW** (minor): minor-version drift only, research citation 2-3 years old but still current → AFTER = optional bump, or note in `## Last-audited` footer
+
+### 5. Track history
+
+After each approved patch, append a line to `$CIEL_DIR/.freshness-log.jsonl`:
+
+```json
+{"ts":"2026-04-17T14:30Z","skill":"skills/workflow/pattern-fitness-check/SKILL.md","ref":"Playwright 1.49","action":"bumped-to-1.53","audit_version":"2.4.5"}
+```
+
+Skip re-auditing a ref whose log entry is < freshness-window old (cache hits — saves WebFetch budget across repeated runs).
+
+---
+
+## Output format
+
+```
+# Ciel freshness audit — <ISO-8601 timestamp>
+
+Skills scanned: <N>
+References extracted: <M>  (URLs: <u>, libs: <l>, citations: <c>)
+Cache hits (recent): <h>
+Network checks performed: <nc>
+Findings: HIGH <h>, MEDIUM <m>, LOW <l>
+
+## Patches proposed (max 5)
+
+## Patch 1 — …
+## Patch 2 — …
+
+## Cached (skipped this run — last audit within freshness window)
+- <path>:<line> <ref> (last checked <date>)
+
+## Unable to check (network / paywall / ambiguity)
+- <path>:<line> <ref> — reason: <timeout | cloudflare | semantic ambiguity>
+```
+
+---
+
+## Guardrails
+
+- **Max 5 patches per run** — same cap as `ciel-improve`. Prevents noise; defer rest to next run.
+- **Never autonomous rewrite** — every patch waits for `[y/n/edit]`. No exceptions.
+- **Never downgrade a pin** — if a skill pins v2 and latest is v3, propose bump; never propose going to v1 based on noise.
+- **Version-pin patches must cross-check** — before proposing "bump X from v1.2 to v1.5", fetch v1.5's changelog to ensure the feature the skill relies on still exists. An AI-hallucinated bump that breaks semantics is worse than a slightly-stale pin.
+- **Research citation patches require a named superseding work** — never replace a citation with "(outdated)" alone; the new citation must be specific and fetchable.
+- **Skip auto-patching `CHANGELOG.md`** — changelogs are append-only history; outdated refs there are a feature, not a bug.
+- **Respect `--scope` filter** — if the user asks only for `workflow` skills, don't scan `domain` or `meta`.
+- **Cache window override** — `--force` bypasses the 18-month URL cache (rerun everything).
+
+---
+
+## When triggered
+
+- User runs `/ciel-refresh`
+- User asks "are any skills stale?" or "check Ciel for outdated references"
+- Scheduled monthly (recommended) — drift accumulates silently; a monthly pass keeps it bounded
+- Before a major version bump — so the new version ships without stale pins
+
+Do NOT trigger automatically on every task — this is a batched meta operation, ~1-3K tokens per skill scanned. Burns budget if over-invoked.
+
+---
+
+## How to verify
+
+- [ ] Skills enumerated (find command ran)?
+- [ ] External references extracted (URLs, libs, citations)?
+- [ ] Freshness checks performed per category (URL liveness, version drift, citation recency)?
+- [ ] Patch-set format matches ciel-improve (BEFORE/AFTER)?
+- [ ] Patch count ≤ 5?
+- [ ] Freshness log appended?
+- [ ] Cache hits skipped (no redundant checks)?
+
+## Relation to other meta skills
+
+- **`ciel-improve`** — transcript-driven; catches failures Ciel experienced. This skill catches reality changes Ciel has not yet tripped over.
+- **`skills-first-design-auditor`** — structure-driven; validates frontmatter, length, examples. This skill validates *content currency*, not form.
+- **`skill-variant-evaluator`** — A/B scorer. Not invoked here unless a patch is a semantic rewrite (version bump alone doesn't need evaluation).
+- **`skill-creator`** — scaffolds new skills. This skill updates existing ones in place.