@neikyun/ciel 6.11.0 → 6.11.2

package/assets/.claude/hooks/memory-engine.py

@@ -851,6 +851,17 @@ def cmd_analyze(args):
     insights_json = base / 'insights.json'
     atomic_write_json(insights_json, insights)
 
+    # Cap human-readable INSIGHTS.md sections when the corpus is large.
+    # insights.json (machine consumer) keeps everything; INSIGHTS.md is read
+    # by humans + by ciel-audit narration so token cost matters at scale.
+    LARGE_CORPUS_THRESHOLD = 150
+    TOP_N = 10
+
+    def maybe_cap(items):
+        if total > LARGE_CORPUS_THRESHOLD and len(items) > TOP_N:
+            return items[:TOP_N], len(items) - TOP_N
+        return items, 0
+
     lines = [
         "# Memory insights",
         "",
@@ -866,50 +877,64 @@ def cmd_analyze(args):
     lines.append("")
 
     if promotion_candidates:
+        shown, omitted = maybe_cap(promotion_candidates)
         lines += [
             "## Promotion candidates",
             "",
             f"Episodes triggered >= {MIN_PROMOTION} times. Promote via skill `memoire-consolidator`.",
             "",
         ]
-        for mid in promotion_candidates:
+        for mid in shown:
             m = episodes[mid]
             lines.append(f"- `{mid}` (trigger_count={m.get('trigger_count', 0)}) - {m.get('title', '?')}")
+        if omitted:
+            lines.append(f"- _+{omitted} more, see insights.json_")
         lines.append("")
 
     if dead_anchors:
+        shown, omitted = maybe_cap(dead_anchors)
         lines += [
             "## Dead anchors",
             "",
             "Memories whose every `path_patterns` entry resolves to no file. Triage in `.ciel/memory/review-queue.md`.",
             "",
         ]
-        for mid in dead_anchors:
+        for mid in shown:
             m = memories[mid]
             patterns = ", ".join(m.get('path_patterns') or [])
             lines.append(f"- `{mid}` - {m.get('title', '?')} (patterns: {patterns})")
+        if omitted:
+            lines.append(f"- _+{omitted} more, see insights.json_")
         lines.append("")
 
     if intent_clusters:
+        ranked = sorted(intent_clusters.items(), key=lambda x: -len(x[1]))
+        shown, omitted = maybe_cap(ranked)
         lines += [
             "## Intent clusters",
             "",
             f"Intents shared by >= {MIN_SUPPORT} memories - recurring topics.",
             "",
         ]
-        for intent, ids in sorted(intent_clusters.items(), key=lambda x: -len(x[1])):
+        for intent, ids in shown:
             lines.append(f"- `{intent}` ({len(ids)}): {', '.join(ids)}")
+        if omitted:
+            lines.append(f"- _+{omitted} more, see insights.json_")
         lines.append("")
 
     if path_clusters:
+        ranked = sorted(path_clusters.items(), key=lambda x: -len(x[1]))
+        shown, omitted = maybe_cap(ranked)
         lines += [
             "## Path clusters",
             "",
             f"Paths referenced by >= {MIN_SUPPORT} memories - high-traffic surface.",
             "",
         ]
-        for path, ids in sorted(path_clusters.items(), key=lambda x: -len(x[1])):
+        for path, ids in shown:
             lines.append(f"- `{path}` ({len(ids)}): {', '.join(ids)}")
+        if omitted:
+            lines.append(f"- _+{omitted} more, see insights.json_")
         lines.append("")
 
     insights_md = base / 'INSIGHTS.md'

package/assets/.claude/settings.json

@@ -20,7 +20,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "echo \"[CIEL v6] Session started — Pipeline: DOCS → QUOI → ASK → AVEC QUOI → DIVERGE → RECHERCHE → CODEBASE → EVALUER → ASK2 → FAIRE → RELIRE → PROUVER → MEMOIRE → META\" && \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/session-version-check.sh"
+            "command": "echo \"[CIEL v6] Session started — Pipeline: DOCS → QUOI → ASK → AVEC QUOI → DIVERGE → RECHERCHE → CODEBASE → EVALUER → ASK2 → FAIRE → RELIRE → PROUVER → MEMOIRE → META\" && { ! [ -x \"$CLAUDE_PROJECT_DIR/.claude/hooks/session-version-check.sh\" ] || \"$CLAUDE_PROJECT_DIR/.claude/hooks/session-version-check.sh\"; }"
           }
         ]
       }
@@ -31,11 +31,11 @@
         "hooks": [
           {
             "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-test-first.sh"
+            "command": "! [ -x \"$CLAUDE_PROJECT_DIR/.claude/hooks/check-test-first.sh\" ] || \"$CLAUDE_PROJECT_DIR/.claude/hooks/check-test-first.sh\""
           },
           {
             "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/pre-tool-write.sh"
+            "command": "! [ -x \"$CLAUDE_PROJECT_DIR/.claude/hooks/pre-tool-write.sh\" ] || \"$CLAUDE_PROJECT_DIR/.claude/hooks/pre-tool-write.sh\""
           }
         ]
       },
@@ -45,7 +45,7 @@
           {
             "type": "command",
             "if": "Bash(rm *)",
-            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-destructive.sh"
+            "command": "! [ -x \"$CLAUDE_PROJECT_DIR/.claude/hooks/block-destructive.sh\" ] || \"$CLAUDE_PROJECT_DIR/.claude/hooks/block-destructive.sh\""
           }
         ]
       },
@@ -54,7 +54,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/pre-agent-gate.sh"
+            "command": "! [ -x \"$CLAUDE_PROJECT_DIR/.claude/hooks/pre-agent-gate.sh\" ] || \"$CLAUDE_PROJECT_DIR/.claude/hooks/pre-agent-gate.sh\""
           }
         ]
       }
@@ -65,7 +65,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/track-file.sh"
+            "command": "! [ -x \"$CLAUDE_PROJECT_DIR/.claude/hooks/track-file.sh\" ] || \"$CLAUDE_PROJECT_DIR/.claude/hooks/track-file.sh\""
           },
           {
             "type": "command",
@@ -108,7 +108,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/meta-critiquer.sh"
+            "command": "! [ -x \"$CLAUDE_PROJECT_DIR/.claude/hooks/meta-critiquer.sh\" ] || \"$CLAUDE_PROJECT_DIR/.claude/hooks/meta-critiquer.sh\""
           }
         ]
       }
@@ -118,7 +118,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/meta-critiquer.sh"
+            "command": "! [ -x \"$CLAUDE_PROJECT_DIR/.claude/hooks/meta-critiquer.sh\" ] || \"$CLAUDE_PROJECT_DIR/.claude/hooks/meta-critiquer.sh\""
           }
         ]
       }

package/assets/commands/ciel-create-skill.md

@@ -1,10 +1,10 @@
 ---
-description: Generates a valid Ciel SKILL.md scaffold following Anthropic Skills-first rules (kebab-case ≤64, YAML description ≤1024, body ≤500 lines).
+description: Generates a valid Ciel SKILL.md scaffold following Anthropic Skills-first rules (kebab-case ≤64, YAML description ≤1536, body ≤500 lines).
 ---
 
 # /ciel-create-skill — Create a new Ciel skill
 
-*Generates a valid SKILL.md scaffold following Anthropic Skills-first rules (kebab-case name ≤64 chars, YAML frontmatter ≤1024-char description, ≤500-line body, progressive disclosure to one reference.md).*
+*Generates a valid SKILL.md scaffold following Anthropic Skills-first rules (kebab-case name ≤64 chars, YAML frontmatter ≤1536-char description, ≤500-line body, progressive disclosure to one reference.md).*
 
 Usage: `/ciel-create-skill <name> <purpose>`
 

package/assets/commands/ciel-status.md

@@ -15,7 +15,7 @@ Usage: `/ciel-status [--check]`
 ```
 ## CIEL STATUS
 
-Version: v6.11.0
+Version: v6.11.2
 Platform: Claude Code
 Config: .claude/settings.json — OK (4 hooks registered)
 Skills directory: skills/ — 43 skills loaded

package/assets/platforms/opencode/.opencode/agents/ciel-improver.md

@@ -265,7 +265,7 @@ Generates a valid SKILL.md scaffold following Ciel's conventions. Returns a diff
 - Third person: "Analyzes X" ✓ / "I analyze X" ✗
 - Front-load use case + trigger keywords
 - Include "Use when..." clause
-- ≤ 1024 chars, recommended 200-500
+- ≤ 1536 chars, recommended 200-500
 
 ### 3. Scaffold SKILL.md
 
@@ -333,7 +333,7 @@ Problems: no trigger, no output, no specificity.
 
 - [ ] Name valid kebab-case, ≤ 64 chars, unique?
 - [ ] Category is one of the 5 valid categories?
-- [ ] Description: third person, ≤ 1024 chars, includes trigger?
+- [ ] Description: third person, ≤ 1536 chars, includes trigger?
 - [ ] SKILL.md ≤ 300 lines?
 - [ ] No overlap with existing skills (grep checked)?
 - [ ] YAML frontmatter valid?

package/assets/platforms/opencode/.opencode/commands/ciel-create-skill.md

@@ -7,12 +7,12 @@ subtask: true
 > **OpenCode note**: This command requires `claude --print` headless mode for full functionality (binary evals, skill scaffold generation). On OpenCode it runs in degraded mode — the improver agent returns proposals only. For the full harness, use Claude Code.
 
 ---
-description: Generates a valid Ciel SKILL.md scaffold following Anthropic Skills-first rules (kebab-case ≤64, YAML description ≤1024, body ≤500 lines).
+description: Generates a valid Ciel SKILL.md scaffold following Anthropic Skills-first rules (kebab-case ≤64, YAML description ≤1536, body ≤500 lines).
 ---
 
 # /ciel-create-skill — Create a new Ciel skill
 
-*Generates a valid SKILL.md scaffold following Anthropic Skills-first rules (kebab-case name ≤64 chars, YAML frontmatter ≤1024-char description, ≤500-line body, progressive disclosure to one reference.md).*
+*Generates a valid SKILL.md scaffold following Anthropic Skills-first rules (kebab-case name ≤64 chars, YAML frontmatter ≤1536-char description, ≤500-line body, progressive disclosure to one reference.md).*
 
 Usage: `/ciel-create-skill <name> <purpose>`
 

package/assets/platforms/opencode/.opencode/commands/ciel-memory-bootstrap.md

@@ -0,0 +1,195 @@
+---
+description: Scan project for ingestable tribal docs (lessons.md, ciel-overlay.md, .claude/rules/, Claude Code auto-memory at ~/.claude/projects/<slug>/memory/, etc.) and propose ingestion into the cued-recall memory under .ciel/memory/. Reports findings if no sources found. Always confirms each candidate with the user before writing.
+---
+
+# /ciel-memory-bootstrap — Initialize Cued-Recall Memory
+
+**Purpose:** First-run scan of an existing project to convert tribal knowledge already documented in `lessons.md`, `ciel-overlay.md`, `.claude/rules/`, Claude Code's per-project auto-memory (`~/.claude/projects/<slug>/memory/`), and similar files into the structured cued-recall memory at `.ciel/memory/`.
+
+**Usage:** `/ciel-memory-bootstrap` (no args)
+
+This is **deterministic**: no agent dispatch, no pipeline, no DIVERGE/EVALUER. Just scan, propose, write on user confirmation.
+
+---
+
+## Instructions
+
+You are bootstrapping the cued-recall memory for this project. Follow these steps in order.
+
+### Step 1 — Scan
+
+Run the bootstrap script in `scan` mode:
+
+```bash
+# Try installed location first, fallback to dev location
+script="$CLAUDE_PROJECT_DIR/.claude/hooks/memory-bootstrap.sh"
+[ -f "$script" ] || script="$CLAUDE_PROJECT_DIR/hooks/memory-bootstrap.sh"
+bash "$script" scan
+```
+
+Or, if running on an installed Ciel: `bash "$HOME/.ciel/hooks/memory-bootstrap.sh" scan`.
+
+Report the output verbatim to the user.
+
+### Step 2 — Decide path
+
+Based on the scan output:
+
+- **If 0 sources found** → tell the user clearly: "No tribal docs to bootstrap from. The cued-recall memory will populate organically as you intervene with me. Nothing more to do." End here.
+- **If sources found** → proceed to Step 3.
+
+### Step 3 — Initialize structure
+
+Run:
+
+```bash
+script="$CLAUDE_PROJECT_DIR/.claude/hooks/memory-bootstrap.sh"
+[ -f "$script" ] || script="$CLAUDE_PROJECT_DIR/hooks/memory-bootstrap.sh"
+bash "$script" ingest
+```
+
+This creates `.ciel/memory/{episodes,concepts,guards}/` and an empty `index.json`. It does NOT auto-write memories — auto-ingestion would create cargo-cult entries from possibly-stale docs (see ADR-0001).
+
+### Step 4 — Read each source
+
+For each source found in Step 1, `Read` the file fully. Identify candidate memories:
+
+| Source format | What becomes a memory |
+|---|---|
+| `[YYYY-MM-DD] MISTAKE: X → RULE: Y` lines (lessons.md style) | One memory per line. Title = the rule. |
+| `## Heading\n\n- rule\n- rule` (rules.md style) | One memory per rule. |
+| Numbered lessons in `ciel-overlay.md` "Key Lessons" | One memory per lesson. |
+| `## section` in CLAUDE.md/AGENTS.md describing a non-obvious convention | One memory per section. |
+| **Claude Code auto-memory** entries (`~/.claude/projects/<slug>/memory/*.md`, excluding `MEMORY.md`) | One memory per file. Title = frontmatter `description`. Cues derived per "Auto-memory mapping" below. |
+
+#### Auto-memory mapping (special parser)
+
+Claude Code auto-memory uses a different frontmatter than Ciel's cued-recall. Each source file looks like:
+
+```yaml
+---
+name: feedback-okhttp-cookiejar-override
+description: Neiyomi shared PersistentCookieJar overrides manual Cookie headers via OkHttp BridgeInterceptor
+metadata:
+  type: feedback
+---
+
+(body markdown — Context / Why / How to apply sections)
+```
+
+When you encounter a file under `$AUTO_MEMORY_DIR`, map it to a Ciel episode as follows:
+
+| Auto-memory field | Ciel frontmatter field | Notes |
+|---|---|---|
+| `description:` | `title:` | one-line summary |
+| `name:` | base of slug for filename | already kebab-case |
+| `metadata.type:` (`user`/`feedback`/`project`/`reference`) | `intents:` `[<type>]` plus topic-specific intents inferred from body | e.g. `feedback` + `okhttp` + `cookie` |
+| body markdown | Ciel episode body, verbatim | preserve Context/Why/How to apply structure |
+| paths cited in body (e.g. `src/`, `*.kt`, `Caddyfile`) | `path_patterns:` | infer from grep — narrow patterns preferred |
+| symbols cited in body (class/function/table names) | `symbols:` | infer from grep |
+| language hint (file extensions in body) | `languages:` | `kotlin`/`typescript`/`python`/`sql`/etc. |
+| `captured_from:` (NEW) | `auto-memory-migration` | distinguishes from user-intervention captures |
+
+**Skip `MEMORY.md`** — it's a table-of-contents index, not memory content. The scan already excludes it.
+
+**Backup before delete.** After successfully writing an episode file for an auto-memory entry, MOVE (not delete) the source to `$AUTO_MEMORY_DIR/.migrated-to-ciel/<filename>` so the user can audit migration. The MEMORY.md index file itself stays in place — Claude Code may regenerate it on next session.
+
+Skip:
+- The pipeline / workflow descriptions (those belong in CLAUDE.md, not memory)
+- General principles already in CLAUDE.md
+- Anything that's just project description (READMEish)
+- Code examples (those go in skills/, not memory)
+
+### Step 5 — Propose batch capture
+
+Once you have N candidate memories from the sources, present them to the user **as a batch**, not one by one (avoid 50 confirmation prompts). Use a single `AskUserQuestion` with the structure:
+
+> "Found N candidates from your tribal docs. I'll list them; you tell me which to capture, which to skip, or 'all'."
+
+For each candidate, show:
+- **Title** (one line)
+- **Source** (file:line)
+- **Suggested tags** (paths, symbols, intents, language inferred from the lesson content)
+
+The user replies with: "all", "1,3,5,8" (specific indices), or "skip".
+
+### Step 6 — Write captured memories
+
+For each captured candidate, create `.ciel/memory/episodes/<YYYY-MM-DD>-<slug>.md` with frontmatter:
+
+```yaml
+---
+id: mem_<NNN>
+title: <title>
+languages: [<inferred>]
+path_patterns:
+  - <pattern>
+symbols: [<inferred>]
+intents: [<inferred>]
+captured_at: <ISO8601 now>
+captured_from: bootstrap
+source: <original-file:line>
+trigger_count: 0
+last_triggered: null
+stale_after_days: 90
+stale: false
+---
+
+# <title>
+
+<content from source, lightly cleaned>
+```
+
+ID strategy: read existing `index.json` for max id, increment. Slug = first 5 words of title, kebab-cased.
+
+### Step 7 — Rebuild index
+
+After all writes, regenerate `.ciel/memory/index.json` by parsing every frontmatter under `.ciel/memory/{episodes,concepts,guards}/`:
+
+```python
+# pseudo — use python3 -c '...' inline
+for each *.md file:
+    parse frontmatter
+    add to memories dict by id
+    for each path_pattern, symbol, intent, language:
+        append id to corresponding by_* index
+write back to index.json
+```
+
+### Step 8 — Confirm
+
+Report:
+
+- N memories captured
+- Sources processed
+- Index rebuilt with M total entries
+- Suggest: "Cued-recall memory now active. Memories will auto-inject when their cues match in future tasks. Run `/ciel-memory-bootstrap` again anytime to re-scan for new tribal docs."
+
+---
+
+## Constraints
+
+- **Never write a memory without user confirmation.** Even on bulk confirmation ("all"), display the list first.
+- **Do not delete the source files.** Bootstrap converts; the user keeps the originals as long as they want.
+- **Tag conservatively.** A memory tagged with `**/*` will fire on every task and pollute. If unsure, narrow the path pattern.
+- **No agent dispatch.** This command is deterministic and runs inline.
+- **Idempotent.** Re-running on an already-bootstrapped project should detect existing memories (by source field) and offer to skip duplicates.
+
+---
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Script not found | `$CLAUDE_PROJECT_DIR` not set | Try `$HOME/.ciel/hooks/memory-bootstrap.sh` instead |
+| Nothing scanned | No tribal docs in this project | Working as intended; report and end |
+| Memories all tagged with broad paths | Source content didn't include path hints | Ask user to refine tags after listing |
+| index.json malformed after rebuild | python3 parse error | Recreate empty index, re-run rebuild step |
+| Auto-memory not detected | Slug derivation mismatch (cwd has unexpected characters) | Override via `CIEL_AUTO_MEMORY_DIR=<absolute-path> bash hooks/memory-bootstrap.sh scan` |
+| Auto-memory file has `name:` but no `description:` | Older auto-memory format | Use first heading or filename as title; ask user to confirm before writing |
+
+## See also
+
+- `docs/adrs/0001-cued-recall-memory.md` — full design rationale
+- `skills/workflow/memoire/SKILL.md` — capture/recall flow
+- `skills/workflow/memoire-consolidator/SKILL.md` — periodic maintenance

package/assets/skills/workflow/adr-auto/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: adr-auto
+description: How to document architectural decisions automatically in Ciel v5 (etape 12). After FAIRE but before RELIRE, if the task involved a significant architectural decision, write an ADR (Architecture Decision Record) to docs/adrs/. Prevents knowledge loss.
+---
+
+# Automatic ADR — Document Decisions in Real Time (Ciel v5)
+
+## What this covers
+
+How to document architectural decisions during the Ciel v5 pipeline (etape 12: ADR). After FAIRE but before RELIRE, if the task involved a significant architectural decision, write an ADR. The decision is documented while fresh, not months later.
+
+## Core principle
+
+**If the decision was non-trivial, document WHY.** Code shows WHAT. ADRs show WHY. Without ADRs, future developers (or future you) will wonder why the code is the way it is.
+
+## When to write an ADR
+
+Write an ADR when the task involves:
+- Adding a new dependency/library
+- Choosing between two technologies
+- Changing a database schema
+- Adopting a design pattern
+- Making a performance trade-off
+- Changing the build/deploy pipeline
+- Any decision with long-term consequences
+
+Do NOT write an ADR for:
+- Bug fixes (tests document the fix)
+- Refactoring without semantic change
+- Renames/reorganizations
+- Dependency upgrades (changelog suffices)
+
+## ADR format (based on Michael Nygard's template)
+
+```
+# ADR-<NNN>: <Title>
+
+## Status
+
+<proposed | accepted | deprecated | superseded by ADR-NNN>
+
+## Context
+
+<What is the issue that we're seeing that is motivating this decision or change? 2-3 sentences.>
+
+## Decision
+
+<What is the change that we're proposing and/or doing? 1-2 sentences.>
+
+## Consequences
+
+<What becomes easier or harder to do because of this change? 2-3 items.>
+
+## References
+
+<Link to relevant docs, tickets, or PRs>
+```
+
+## File naming
+
+`docs/adrs/<NNN>-<kebab-case-title>.md`
+
+Start at 001 and increment.
+
+## How to trigger (Ciel v5)
+
+In the Ciel pipeline (etape 12), during ADR:
+1. Check if the task involved a significant decision (see list above)
+2. If yes -> write `docs/adrs/<NNN>-<title>.md`
+3. Update `.ciel/map.json` to reference the new ADR
+4. Reference the ADR in the RELIRE submission so the critic can check it
+
+## Common rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "The code is self-documenting" | Code shows WHAT. ADRs show WHY. Six months from now, "why did we choose this" is not visible in the code. |
+| "I'll add it later" | Later is when the decision is forgotten and the context is lost. Write it now or it never gets written. |
+| "This decision is too small for an ADR" | If you had to think about it for more than 30 seconds, it's big enough for an ADR. |
+| "Nobody reads ADRs anyway" | Nobody reads them until they need to undo a decision and can't figure out why it was made. Then they're invaluable. |
+
+## How to verify
+
+- [ ] ADR written for every significant decision?
+- [ ] No ADR written for trivial changes?
+- [ ] ADR includes context, decision, consequences?
+- [ ] Map updated with ADR reference?
+- [ ] ADR committed with the code?

package/assets/skills/workflow/ai-failure-modes-detector/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: ai-failure-modes-detector
+description: Detects the six canonical failure modes of LLM-generated code — invented APIs, hallucinated dependencies, version drift, async/sync mismatch, confident-wrong logic, and extrinsic hallucination (plausible but unverifiable output). Runs self-consistency triple-generation checks, AST-based dependency audits, and uncertainty scoring. Triggers BEFORE merging agent-authored code, especially when the author is an LLM. Partners with doc-validator-official (API-level) and self-consistency-verifier (semantic-level).
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# ai-failure-modes-detector — Catch confident-wrong before it lands
+
+LLM-generated code compiles more often than it's correct. Six failure modes account for >90% of post-merge incidents in agentic PRs (ISSTA 2025). This skill runs each check systematically.
+
+---
+
+## Inputs (infer before asking — see orchestrator's Autonomy protocol)
+
+```
+CODE_UNDER_REVIEW: [file paths OR diff hunk]
+AUTHOR: [human | LLM | mixed]
+PROPOSED_DEPS: [new dependencies being added, if any]
+TEST_COVERAGE: [files that have tests | files without]
+```
+
+### Auto-inference sources (exhaust BEFORE asking the user)
+
+- **CODE_UNDER_REVIEW** → `git diff HEAD~1` (last commit) or `git diff main...HEAD` (branch diff) — usually the intent. If user said "this file", extract from prompt.
+- **AUTHOR** → check the last commit's message / co-author trailer. `Co-Authored-By: Claude` or `Generated with Claude Code` → LLM. Otherwise human. If unsure, assume `mixed` (safer default).
+- **PROPOSED_DEPS** → `git diff HEAD~1 -- package.json go.mod requirements.txt` → list added entries. Zero added → skip dep-hallucination check.
+- **TEST_COVERAGE** → for each changed file in CODE_UNDER_REVIEW, check if a corresponding `*.test.*` / `*_test.go` / `test_*.py` exists next to it.
+
+Never ask the user for AUTHOR — always inferable from git. Never ask for TEST_COVERAGE — always checkable via filesystem.
+
+---
+
+## The six failure modes
+
+### 1. Invented APIs
+
+Function/class/method that doesn't exist in the library at the pinned version.
+
+**Detection**:
+- Grep every import and every method call on imported symbols
+- Cross-reference with `node_modules/<pkg>/package.json` + type definitions
+- For dynamic imports (`await import()`), inspect at runtime if possible
+
+**Signal**: import resolves but `<symbol>` not in the `.d.ts` or `__init__.py`.
+
+### 2. Hallucinated dependencies
+
+`npm package` or `pip package` that doesn't exist on the registry (or typo-squat).
+
+**Detection**:
+- For each new dep in PROPOSED_DEPS: `npm view <pkg> --json` or `pip index versions <pkg>`
+- Check publisher reputation (weekly downloads, last publish date, repo link present)
+- Typo-squat check: Levenshtein distance ≤ 2 from a popular package name is SUSPICIOUS
+
+**Signal**: registry returns 404, or package has < 100 downloads/week with no repo.
+
+### 3. Version drift
+
+Code uses an API that exists but at a different version than pinned.
+
+**Detection**:
+- For each external API call, check "Added in vX.Y" / "Deprecated in vX.Y" metadata
+- Compare against pinned version in lockfile
+
+**Signal**: API exists in v2, code pins v1 — silently broken.
+
+### 4. Async/sync mismatch
+
+Sync call in an async codebase or a Promise-returning function not awaited.
+
+**Detection** (TS):
+- `@typescript-eslint/no-floating-promises`
+- Grep for `fetch(`, `fs.readFileSync` (sync in async) or unawaited `async` functions
+- Any `Promise<T>` returned from a function whose callers don't `await`
+
+**Detection** (Python):
+- Sync `requests.get()` inside an `async def`
+- `asyncio.run()` called inside an event loop
+
+**Signal**: type checker emits "Promise returned but not awaited" OR sync call blocks in async context.
+
+### 5. Confident-wrong logic
+
+Code is syntactically and typing-wise valid, passes linting, but is semantically wrong:
+- Off-by-one on pagination
+- Wrong operator (`>=` where `>` needed)
+- Negated boolean
+- Swapped arguments of same type
+
+**Detection**:
+- Run existing tests (if present) — failing tests is the first signal
+- Invariant check: can you state in 1 sentence what the code guarantees? Does it actually guarantee it?
+- For any numerical boundary, ask: "off-by-one in either direction — which breaks?"
+
+**Signal**: behavior divergence between stated goal and actual execution.
+
+### 6. Extrinsic hallucination
+
+Output is plausible but references facts outside the code that cannot be verified:
+- Cites a spec section that doesn't exist
+- Comments claim "per RFC 7231 §5.3" when section 5.3 doesn't cover that
+- Error codes invented (`ERR_USER_QUOTA_EXCEEDED` — is that really thrown?)
+
+**Detection**:
+- Every code comment with a source claim → spot-check
+- Every user-facing string (error codes, log messages) → grep for prior use in the codebase
+
+**Signal**: claim cannot be corroborated.
+
+---
+
+## Report format
+
+```
+## AI-FAILURE-MODES VERDICT
+
+### Author
+LLM  (auto-detected via commit message pattern | user-declared)
+
+### Findings by mode
+1. Invented APIs:
+   [BLOCK] src/auth.ts:42 — `jwt.verifyStrict()` not in jsonwebtoken@9.0.2 (use `verify()` with `algorithms` option)
+
+2. Hallucinated deps:
+   (none — all 3 new deps exist on npm, >10k weekly downloads)
+
+3. Version drift:
+   [WARN] src/db.ts:18 — `drizzle.innerJoin()` added in v0.30, pinned 0.29 — upgrade drizzle-orm
+
+4. Async/sync mismatch:
+   [BLOCK] src/upload.ts:55 — `fs.writeFileSync()` inside async handler — blocks event loop
+
+5. Confident-wrong:
+   [WARN] src/pagination.ts:22 — `offset = page * pageSize` — off-by-one on page=0
+
+6. Extrinsic:
+   [INFO] src/rate-limit.ts:10 — comment cites "per RFC 6585 §4" — RFC 6585 does not have §4; 429 is §4 of RFC 6585 (comment is right, citation format wrong)
+
+### Summary
+BLOCK: 2
+WARN:  2
+INFO:  1
+```
+
+---
+
+## Guardrails
+
+- **BLOCK means don't merge** — invented APIs, hallucinated deps, and async/sync mismatches are production-breaking.
+- **WARN means discuss in review** — not auto-blocking but requires human acknowledgment.
+- **Run against diff, not whole repo** — old code isn't the subject; the new change is.
+- **When tests are absent**, confidence in "confident-wrong" findings drops — request tests be added before clearing the review.
+- **Don't false-positive on stubs** — intentional mocks in `__mocks__/` or `test-helpers/` may reference not-yet-implemented APIs; verify context.
+- **Typo-squat false positives**: popular packages sometimes have close cousins (`request` vs `request-promise`) — check download count AND repo history before flagging.
+
+---
+
+## How to verify
+
+- [ ] All 6 failure modes checked (invented APIs, hallucinated deps, version drift, async/sync, confident-wrong, extrinsic)?
+- [ ] Each finding has evidence (file:line or URL)?
+- [ ] VERDICT issued (CLEAN / FINDINGS)?
+- [ ] Author identified (LLM vs human)?
+- [ ] External API calls validated against official docs?
+
+## When triggered
+
+- Post-write hook when AUTHOR=LLM and task is Standard/Critical
+- Before any PR merge authored wholly or partially by an agent
+- After `@ciel-explorer` completes CODEBASE review
+- User command: "audit this code for AI mistakes"
+
+---
+
+## References
+
+- ISSTA 2025 — "LLM Hallucinations in Practical Code Generation: Phenomena, Mechanism, and Mitigation"
+- arxiv 2601.19106 — "Detecting and Correcting Hallucinations in LLM-Generated Code"
+- arxiv 2404.00971 — "Beyond Functional Correctness"
+- Anthropic 2604.08906 — agentic framework failure taxonomy