@rune-kit/rune 2.7.0 → 2.8.0

package/README.md

@@ -83,16 +83,21 @@ _Methodology: Claude Code CLI headless mode (`claude -p --output-format json`),
 
 ---
 
-## What's New (v2.7.0)
+## What's New (v2.8.0)
+
+- **Anti-Loop Intelligence** — 7 core skills enriched with execution loop detection, saturation analysis, error pattern matching, artifact folding, budget-aware progression, and recovery policy routing
+- **cook v2.1.0** — observation/effect ratio tracking (detects stuck agents reading without writing) + budget-aware phase progression with hard caps on replans, quality retries, and session tool calls
+- **completion-gate v1.8.0** — execution loop audit: classifies tool calls as observation vs effect, flags imbalanced ratios and repeating sequences in gate reports
+- **scout v0.3.0** — info saturation detection: tracks entity discovery rate and content similarity to stop scanning when diminishing returns detected
+- **research v0.4.0** — diminishing returns detection: monitors new-entity ratio and result overlap across searches to skip redundant queries
+- **context-engine v0.9.0** — artifact folding: large tool outputs (>4000 chars or >120 lines) saved to `.rune/artifacts/` with compact preview in context
+- **debug v1.0.0** — known error pattern catalog: 8 error archetypes (STATELESS_LOSS, MODULE_NOT_FOUND, TYPE_MISMATCH, ASYNC_DEADLOCK, etc.) with recovery hints + error fingerprinting for dedup
+- **fix v0.8.0** — recovery policy matrix: classifies errors into 8 types (INPUT_REQUIRED→PROMPT_USER, TIMEOUT→RETRY, POLICY_BLOCKED→ABORT, etc.) before attempting fixes
+- **Source attribution cleanup** — removed all enrichment credit lines from skill files to reduce context noise
+
+### Previous (v2.7.0)
 
 - **Deep Knowledge** — 8 core skills enriched with battle-tested patterns: context compaction, structured cumulative memory, milestone analysis, multi-provider adapters, AI-driven interview, prompt-as-API-contract, token budget tracking, incremental stream processing
-- **context-engine v0.8.0** — structured compaction summaries with continuation point anchoring + sentence-level stream processing pattern
-- **session-bridge v0.5.0** — cumulative project notes (`.rune/cumulative-notes.md`) for living institutional memory across sessions
-- **retro v0.3.0** — milestone progressive analysis at project thresholds (4/12/24/50 retros) with focal-point depth scaling
-- **mcp-builder v0.4.0** — multi-provider adapter pattern reference with discriminated StreamChunk union + dual-model cost config
-- **onboard v0.4.0** — AI-driven conversational interview mode (`--interview`) for ambiguous or complex projects
-- **perf v0.3.0** — token budget tracking for AI-powered apps (loop detection, model mismatch, unbounded tokens, duplicate calls)
-- **cook v2.0.0** — prompt-as-API-contract pattern for structured sub-skill output
 - **946 Tests** — compiler + signals + hooks + scripts + status + visualizer validation
 
 ### Previous (v2.6.0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rune-kit/rune",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "61-skill mesh for AI coding assistants — 5-layer architecture, 200+ connections, 8 platforms (Claude Code, Cursor, Windsurf, Antigravity, Codex, OpenCode, OpenClaw, Generic)",
   "type": "module",
   "bin": {

package/skills/completion-gate/SKILL.md

@@ -4,7 +4,7 @@ description: "Validates agent claims against evidence trail. Catches 'done' with
 user-invocable: false
 metadata:
   author: runedev
-  version: "1.7.0"
+  version: "1.8.0"
   layer: L3
   model: haiku
   group: validation
@@ -91,6 +91,30 @@ Why: Self-Validation catches domain-specific quality issues that generic claim m
 If a skill has Self-Validation and ANY check is UNCONFIRMED or CONTRADICTED → overall verdict cannot be CONFIRMED, even if all explicit claims pass.
 </HARD-GATE>
 
+### Step 1d — Execution Loop Audit
+
+Before validating claims, audit the agent's tool call pattern for execution loops that indicate the agent was stuck but didn't report it:
+
+**Classify the agent's tool calls** from this workflow into two categories:
+
+| Category | Tools | Expected in Phase 4 |
+|----------|-------|---------------------|
+| **Observation** | Read, Grep, Glob, Bash(grep/ls/cat) | <40% of calls |
+| **Effect** | Write, Edit, Bash(build/test/npm) | >60% of calls |
+
+**Loop patterns to detect**:
+
+| Pattern | Detection | Verdict Impact |
+|---------|-----------|----------------|
+| **Observation chain**: 6+ consecutive observation tools in Phase 4 | Count longest observation-only streak | Add WARN: "Agent had {N}-call observation streak during implementation — possible analysis paralysis" |
+| **Low effect ratio**: <20% effect calls during Phase 4 | `effect_calls / total_calls` | Add WARN: "Only {X}% of Phase 4 calls were writes — agent may have been stuck" |
+| **Repeating tool pattern**: Same tool+args called 3+ times | Hash tool+args, count duplicates | Add WARN: "Agent called {tool}({args}) {N} times — possible loop" |
+| **Budget overrun**: Phase 4 exceeded 50 tool calls for a single-file task | Count Phase 4 calls vs files changed | Add WARN: "50+ tool calls for {N} files changed — disproportionate effort" |
+
+**Scoring impact**: Loop warnings don't change individual claim verdicts but ARE included in the Completion Gate Report under a new `### Execution Efficiency` section. This gives the calling orchestrator signal about whether the agent's process was healthy, not just whether the output was correct.
+
+**Skip if**: Nano/Fast rigor — not enough tool calls to meaningfully analyze.
+
 ### Step 2 — Match Evidence
 
 For each claim, look for corresponding evidence in the conversation context:
@@ -167,8 +191,6 @@ UNCONFIRMED — 1 claim lacks evidence, 1 contradicted. Cannot proceed to commit
 
 ### Step 4.5 — Cross-Phase Integration Check
 
-> From GSD (gsd-build/get-shit-done, 30.8k★): "Phase boundaries are where integration bugs hide."
-
 When validating a completed phase in a multi-phase plan, check for integration gaps between phases:
 
 1. **Orphaned exports** — files/functions created in this phase that claim to be used by future phases (see `## Cross-Phase Context → Exports`) but are not yet importable:
@@ -269,6 +291,7 @@ Completion Gate Report with status (CONFIRMED/UNCONFIRMED/CONTRADICTED), claim v
 | Partial completion claimed as full — 80% done but "implemented" | HIGH | Adversarial checklist: check for partial completion, scope mismatch, evidence-claim alignment |
 | Self-Validation skipped — skill has checks but gate ignores them | HIGH | Step 1c: extract Self-Validation from skill's SKILL.md, treat each as implicit claim. Missing = UNCONFIRMED |
 | Plan says done but phase file has unchecked tasks | HIGH | Step 5.5: diff changed files vs phase plan's Files Touched + Tasks sections |
+| Agent stuck in observation loop but claims "implemented" | HIGH | Step 1d: Execution Loop Audit detects low effect ratio and observation chains — flags in report even if claims pass |
 
 ## Done When
 

package/skills/context-engine/SKILL.md

@@ -4,7 +4,7 @@ description: "Context window management. Auto-triggered when context is filling
 user-invocable: false
 metadata:
   author: runedev
-  version: "0.8.0"
+  version: "0.9.0"
   layer: L3
   model: haiku
   group: state
@@ -218,6 +218,54 @@ When processing streaming LLM output (e.g., in skills that invoke AI calls or pr
 - **JSON output**: accumulate until the closing brace — partial JSON can't be parsed
 - **Short responses** (<100 chars expected): overhead of boundary detection exceeds benefit
 
+## Artifact Folding (Large Output Management)
+
+When tool results are excessively large, they consume disproportionate context without proportionate value. **Artifact folding** saves the full output to a file and replaces it in context with a compact preview.
+
+### When to Fold
+
+| Condition | Action |
+|-----------|--------|
+| Tool output > 4000 characters | Fold to artifact |
+| Tool output > 120 lines | Fold to artifact |
+| Multiple tool outputs from the same command class (e.g., 5+ Grep results) | Fold all into single artifact |
+| Code block output > 200 lines | Fold to artifact |
+
+### Folding Procedure
+
+1. **Save full output** to `.rune/artifacts/artifact-{timestamp}-{tool}.md`:
+   ```markdown
+   # Artifact: {tool_name} output
+   Generated: {timestamp}
+   Command: {tool_call_summary}
+   
+   {full_output}
+   ```
+
+2. **Replace in context** with a compact preview:
+   ```
+   [FOLDED: {tool_name} output — {line_count} lines, {char_count} chars]
+   Preview (first 10 lines):
+   {first_10_lines}
+   ...
+   Full output: .rune/artifacts/artifact-{timestamp}-{tool}.md
+   Use Read to access the full artifact if needed.
+   ```
+
+3. **On compaction**: Artifact files survive compaction — the continuation summary references them by path. This means large outputs are preserved across compaction boundaries without consuming context.
+
+### Rules
+
+- **Never fold user messages** — only tool outputs
+- **Never fold error outputs** — errors need full visibility for debugging
+- **Never fold outputs < 1000 chars** — folding overhead exceeds savings
+- **Fold preemptively in YELLOW/ORANGE** — don't wait for RED to start managing output size
+- **Clean up artifacts** at session end: artifacts older than the current session can be deleted (they're already in git history or irrelevant)
+
+### Why
+
+A single `Grep` across a large codebase can return 3000+ lines. Without folding, this consumes ~4000 tokens of context — often more than the rest of the conversation combined. Folding preserves the information (accessible via Read) while keeping context lean. Combined with the Structured Summary compaction technique, artifact folding enables much longer productive sessions.
+
 ## Context Health Levels
 
 ```

package/skills/cook/SKILL.md

@@ -5,7 +5,7 @@ context: fork
 agent: general-purpose
 metadata:
   author: runedev
-  version: "2.0.0"
+  version: "2.1.0"
   layer: L1
   model: sonnet
   group: orchestrator
@@ -634,6 +634,46 @@ Stuck patterns (all banned):
 A wrong first attempt that produces feedback beats perfect understanding that never ships.
 </HARD-GATE>
 
+### Observation/Effect Ratio Tracking
+
+Track every tool call during Phase 4 (IMPLEMENT) as either **observation** (read-only) or **effect** (modifies state):
+
+| Category | Tool Examples |
+|----------|--------------|
+| **Observation** | Read, Grep, Glob, Bash(grep/ls/cat/git log) |
+| **Effect** | Write, Edit, Bash(npm/build/test/mkdir) |
+
+**Detection rules** (check every 8 tool calls during Phase 4):
+
+| Pattern | Threshold | Signal | Action |
+|---------|-----------|--------|--------|
+| **Observation chain** | 6+ consecutive observation tools with zero effects | Agent is stuck reading, not building | Inject: "OBSERVATION LOOP — 6 reads without writing. Act on what you know or report BLOCKED." |
+| **Low effect ratio** | In last 10 calls, effects < 15% | Agent is in analysis mode, not implementation | Inject: "Effect ratio below 15%. Phase 4 is IMPLEMENT — write code, don't just read it." |
+| **Diminishing returns** | Last 3 observations found <2 new relevant facts combined | Searching is no longer productive | Inject: "Diminishing returns — last 3 reads added nothing new. Synthesize and act." |
+| **Repeating sequences** | A-B-A-B or A-B-C-A-B-C pattern across 6+ calls | Circular behavior | Inject: "REPEATING SEQUENCE detected. Break the cycle — try a different approach or report BLOCKED." |
+
+**Important**: These are injected as advisor messages, not hard blocks. The agent can continue if it has good reason, but the message forces conscious acknowledgment of the pattern.
+
+**Skip if**: Phase 1 (UNDERSTAND) — observation-heavy is expected during research. Only track during Phase 4+ where effects should dominate.
+
+### Budget-Aware Phase Progression
+
+Beyond the existing Exit Conditions (MAX_DEBUG_LOOPS, MAX_QUALITY_LOOPS, etc.), track **cumulative budget** across the entire cook session:
+
+| Budget | Limit | What Happens at Limit |
+|--------|-------|----------------------|
+| **Phase 4 react budget** | 15 tool calls per task within Phase 4 | Force: move to next task or report partial completion |
+| **Global replan budget** | 2 replans per session (Phase 4 Step 6) | Force: proceed with current plan or escalate to user |
+| **Quality retry budget** | 3 total quality re-runs across 5a-5d | Force: ship with known issues documented, don't loop |
+| **Total session tool calls** | 150 calls | Force: save state via session-bridge, compact or pause |
+
+**Hard override rules**:
+- If react budget exhausted for a task but task is IN_PROGRESS → force CONTINUE to next task (don't re-attempt)
+- If replan budget exhausted but plan still failing → force escalation (don't attempt 3rd replan)
+- If quality retry budget exhausted → emit concerns in Cook Report, proceed to commit with documented caveats
+
+**Why**: Without hard budgets, agents get trapped in local optimization loops — retrying the same failing approach indefinitely. Budget constraints force escalation or acceptance of partial results, which is always better than an infinite loop.
+
 ### Hash-Based Tool Loop Detection
 
 <MUST-READ path="references/loop-detection.md" trigger="when same tool+args+result appears to be repeating"/>

package/skills/debug/SKILL.md

@@ -3,7 +3,7 @@ name: debug
 description: Root cause analysis for bugs and unexpected behavior. Traces errors through code, uses structured reasoning, and hands off to fix when cause is found. Core of the debug↔fix mesh.
 metadata:
   author: runedev
-  version: "0.9.0"
+  version: "1.0.0"
   layer: L2
   model: sonnet
   group: development
@@ -178,6 +178,38 @@ After successful root cause identification (Step 5), append entry:
 
 This prevents re-debugging the same issue across sessions.
 
+### Step 2d: Known Error Pattern Matching
+
+Before forming hypotheses, match the error against common **error archetypes**. If a match is found, skip directly to the known fix approach — no hypothesis cycling needed.
+
+**Error Pattern Catalog**:
+
+| Pattern ID | Detection (Error Type + Keywords) | Root Cause | Recovery Hint |
+|------------|----------------------------------|------------|---------------|
+| `STATELESS_LOSS` | `NameError` / `ReferenceError` + variable defined in previous step | Execution context doesn't persist between tool calls | "Combine all variable definitions and usage in a single code block" |
+| `MODULE_NOT_FOUND` | `ModuleNotFoundError` / `Cannot find module` | Dependency not installed or wrong import path | "Check package.json/requirements.txt. Install missing dep, then retry" |
+| `TYPE_MISMATCH` | `TypeError` + "undefined is not a function" / "has no attribute" | Wrong type passed through chain — object where primitive expected or vice versa | "Trace the value backward: where was it created? What type was intended?" |
+| `ASYNC_DEADLOCK` | `TimeoutError` / `Promise` + hang / `await` missing | Async/await misuse — missing await, blocking in async, unresolved promise | "Check: missing await? Blocking call in async context? Unresolved promise chain?" |
+| `PATH_MISMATCH` | `ENOENT` / `FileNotFoundError` + path string in error | Relative vs absolute path, or CWD differs from expected | "Print resolved path. Check CWD. Use path.resolve() or Path.resolve()" |
+| `ENCODING_ISSUE` | `UnicodeDecodeError` / `SyntaxError` + quotes/special chars | Non-ASCII characters in code or data (curly quotes, BOM, etc.) | "Check for smart quotes, BOM markers, or non-ASCII in the file. Use `file` command to check encoding" |
+| `ENV_MISSING` | `KeyError` / "undefined" + env var name | Environment variable not set or .env not loaded | "Check .env file exists and is loaded. Verify var name matches exactly (case-sensitive)" |
+| `CIRCULAR_IMPORT` | `ImportError` + "partially initialized" / "circular" | Module A imports B imports A | "Restructure: move shared types to a third module, or use lazy imports" |
+
+**Matching rules**:
+- Match on error type + 2+ keywords from the Detection column
+- If matched: report the pattern ID and recovery hint in the Debug Report, then proceed to test the known fix approach as H1 (highest priority hypothesis)
+- If NOT matched: proceed to Step 3 (form hypotheses from scratch)
+
+**Error fingerprinting**: When comparing errors across hypothesis cycles, normalize these elements before comparison:
+- Line numbers → `<LINE>`
+- File paths → `<PATH>`
+- Variable/function names → `<IDENT>`
+- Timestamps → `<TIME>`
+
+Two errors with the same fingerprint after normalization are the SAME error — don't re-investigate, the previous hypothesis result still applies.
+
+**Catalog growth**: After each successful debug (Step 5), check: does this error pattern match any existing catalog entry? If not, and the root cause is generalizable (not project-specific), suggest adding it to the catalog via a note in the Debug Report: "New pattern candidate: [pattern] — consider adding to error catalog."
+
 ### Step 3: Form Hypotheses
 
 List exactly 2-3 possible root causes — no more, no fewer.
@@ -390,6 +422,8 @@ Debug returns one of four statuses to its caller (cook, fix, test, surgeon). The
 | Running same test 3x with same failure without code change | MEDIUM | True stuck loop — no progress possible. Hand off to fix with current incomplete diagnosis |
 | Scope creep via debug — "while investigating, also fix X" | HIGH | Step 1.5 Scope Lock: lock edits to narrowest affected directory. Fix recommendations MUST stay within boundary. Expand only with user confirmation |
 | Debug report recommends touching 5+ unrelated files | HIGH | Symptom of fixing at crash sites instead of source. Backward trace (Step 2) to find origin. If truly 5+ files → likely architectural issue → escalate via 3-Fix Rule |
+| Re-investigating known error patterns from scratch | MEDIUM | Step 2d: match error against Known Error Pattern Catalog first — skip hypothesis cycling for recognized patterns |
+| Same error fingerprint across cycles treated as different errors | MEDIUM | Step 2d: normalize line numbers, paths, variable names before comparison — same fingerprint = same error |
 
 ## Done When
 

package/skills/fix/SKILL.md

@@ -3,7 +3,7 @@ name: fix
 description: Apply code changes and fixes. Writes implementation code, applies bug fixes, and verifies changes with tests. Core action hub in the development mesh.
 metadata:
   author: runedev
-  version: "0.7.0"
+  version: "0.8.0"
   layer: L2
   model: sonnet
   group: development
@@ -68,6 +68,29 @@ Read and fully understand the fix request before touching any file.
 - If the request is ambiguous or root cause is unclear → call `rune:debug` before proceeding
 - Note the scope: single function, single file, or multi-file change
 
+### Step 1b: Recovery Policy Matrix
+
+Before locating code, classify the incoming error/task into a recovery category to determine the right fix strategy. This prevents wasting effort on the wrong approach.
+
+| Error Type | Recovery Action | Strategy |
+|------------|----------------|----------|
+| `INPUT_REQUIRED` — missing user input, ambiguous spec | **PROMPT_USER** | Return NEEDS_CONTEXT with specific questions. Do NOT guess. |
+| `INPUT_INVALID` — wrong format, type mismatch, encoding | **AUTO_FIX** | Fix at validation layer. Add schema validation (Zod/Pydantic) if missing. |
+| `TIMEOUT` — operation exceeded time limit | **RETRY** with adjustment | Increase timeout, add retry with exponential backoff, or chunk the operation. |
+| `POLICY_BLOCKED` — security gate, lint rule, contract violation | **ABORT** | Do NOT work around the policy. Report to caller with the specific rule that blocked. |
+| `PERMISSION_DENIED` — auth failure, file access, API scope | **PROMPT_USER** | Cannot fix permissions programmatically. Report exact permission needed. |
+| `DEPENDENCY_ERROR` — missing package, version conflict, broken dep | **AUTO_FIX** | Install missing dep, resolve version conflict, or suggest alternative package. |
+| `LOGIC_ERROR` — wrong output, incorrect calculation, bad algorithm | **INVESTIGATE** | Do NOT auto-fix. Call `rune:debug` — logic errors need root cause analysis. |
+| `ENVIRONMENT_ERROR` — wrong Node/Python version, missing system dep | **PROMPT_USER** | Report exact version/tool needed. Agent cannot change system environment. |
+
+**Decision flow**:
+1. Read the incoming diagnosis/error
+2. Classify into one of the 8 error types above
+3. Apply the recovery action — this determines whether to proceed (AUTO_FIX, RETRY), ask (PROMPT_USER), stop (ABORT), or re-diagnose (INVESTIGATE)
+4. Announce: "Recovery policy: {error_type} → {action}"
+
+**Why**: Without a recovery matrix, fix attempts the same strategy (read → change → test) for every error type. A POLICY_BLOCKED error doesn't need code reading — it needs the policy reported. An INPUT_REQUIRED error doesn't need debugging — it needs a question asked. Matching strategy to error type eliminates wasted cycles.
+
 ### Step 2: Locate
 
 Find the exact files and lines to change.
@@ -264,6 +287,7 @@ Known failure modes for this skill. Check these before declaring done.
 | Removing debug instrumentation before fix is verified | MEDIUM | Step 5b: preserve `#region agent-debug` markers until all tests pass — premature cleanup erases failure history |
 | Runaway fix loop — 20+ fixes without checking quality decay | HIGH | Step 4.5: WTF-likelihood self-regulation. >20% risk = STOP. Hard cap 30 fixes/session. Each fix adds risk — diminishing returns after ~15 |
 | Each fix creates a new bug elsewhere — whack-a-mole | CRITICAL | Tight coupling signal. STOP fixing → escalate to debug with note "each fix creates new failure — suspect structural issue". Debug will route to plan for redesign |
+| Applying same fix strategy to every error type | MEDIUM | Step 1b Recovery Policy Matrix: classify error type FIRST — POLICY_BLOCKED needs reporting not fixing, INPUT_REQUIRED needs questions not code |
 
 ## Done When
 

package/skills/plan/SKILL.md

@@ -262,8 +262,6 @@ Every plan output — master plan, phase file, or inline plan — MUST end with
 
 ## Change Stacking (Overlap Detection)
 
-> From OpenSpec (Fission-AI/OpenSpec, 32.8k★): "Dependencies without metadata create phantom coupling."
-
 When producing phase files with wave-based task grouping, every task MUST declare dependency metadata:
 
 ```markdown

package/skills/research/SKILL.md

@@ -3,7 +3,7 @@ name: research
 description: Web search and external knowledge lookup. Gathers data on technologies, libraries, best practices, and competitor solutions.
 metadata:
   author: runedev
-  version: "0.3.0"
+  version: "0.4.0"
   layer: L3
   model: haiku
   group: knowledge
@@ -67,6 +67,29 @@ Call `WebSearch` for each query. Collect result titles, URLs, and snippets. Iden
 - **Diversity: never select 3+ URLs from the same domain** — spread across source types
 
 
+### Step 2b — Diminishing Returns Detection
+
+After each WebSearch call, evaluate whether additional searches are productive:
+
+**Track across search results**:
+- **Entity set**: Extract key entities from each result set (library names, API names, version numbers, technique names, company names)
+- **New entity ratio**: `new_entities_in_this_search / total_entities_found_so_far`
+- **Result overlap**: How many URLs from this search were already seen in previous searches
+
+| Signal | Threshold | Action |
+|--------|-----------|--------|
+| New entity ratio < 10% | Last search added almost nothing new | Skip remaining queries, proceed to Step 3 with existing results |
+| Result overlap > 60% | Most URLs already fetched or seen | Skip this query's results entirely |
+| All 3 queries return same top 3 URLs | Search space is exhausted | Proceed directly to Step 3 — more queries won't help |
+
+**Report when triggered**:
+```
+Note: Research saturation reached after [N] searches — [M] unique entities found.
+Additional queries showed <10% new information. Proceeding with synthesis.
+```
+
+**Why**: Research skills commonly waste 2-3 WebFetch calls on pages that repeat information already gathered. Saturation detection saves tool calls and context tokens while preserving research quality — the first 3 sources typically contain 90%+ of available information.
+
 ### Step 3 — Deep Dive
 
 Call `WebFetch` on the top 3-5 URLs identified in Step 2. Hard limit: **max 5 WebFetch calls** per research invocation. For each fetched page:

package/skills/scout/SKILL.md

@@ -3,7 +3,7 @@ name: scout
 description: "Fast codebase scanner. Use when any skill needs codebase context. Finds files, patterns, dependencies, project structure. Pure read-only — never modifies files."
 metadata:
   author: runedev
-  version: "0.2.0"
+  version: "0.3.0"
   layer: L2
   model: haiku
   group: creation
@@ -79,6 +79,27 @@ Based on the scan request, run focused searches:
 
 **Verification gate**: At least 1 relevant file found, OR confirm the target does not exist.
 
+#### Info Saturation Detection (Know When to Stop)
+
+Scout's default is "max 10 file reads" — but the real question is whether additional reads are productive. Track saturation across Phase 2 searches:
+
+**Entity tracking**: As you scan files, extract key entities (function names, class names, imports, API endpoints, config keys). Maintain a running set of discovered entities.
+
+| Signal | Threshold | Meaning | Action |
+|--------|-----------|---------|--------|
+| **New entity ratio** | Last 2 file reads added <2 new entities | Search is exhausted for this domain | STOP scanning, move to Phase 3 |
+| **Content similarity** | Last 2 files share >70% of the same imports/patterns | Files are in the same module, redundant reads | Skip remaining files in this directory |
+| **Query variation** | 3+ Glob/Grep queries with different patterns all return the same files | All search angles converge | Domain is fully mapped, proceed |
+
+**When saturation detected**: Emit in Scout Report:
+```
+### Saturation
+- Reached after [N] file reads — last 2 reads added [M] new entities
+- Recommendation: synthesize_and_report (further scanning unlikely to yield new insights)
+```
+
+**Why**: Without saturation detection, scout reads its full budget of 10 files even when 3 files already contain everything needed. This wastes context tokens and delays the calling skill. Early saturation detection returns control faster.
+
 ### Phase 3: Dependency Mapping
 
 1. Use `Grep` to find import/require/use statements in identified files

package/skills/sentinel-env/SKILL.md

@@ -112,8 +112,6 @@ Detect and verify tools the project depends on:
 5. **Build tools**: Check for `turbo.json` (turborepo), `nx.json` (Nx), `Makefile`, etc.
 
 6. **Hard dependencies** — tools the project WRAPS (not just uses as dev dependency):
-   > From CLI-Anything (HKUDS/CLI-Anything, 17.4k★): "The software is a required dependency, not optional."
-
    Scan for evidence that the project wraps an external tool:
    - `Grep` for `shutil.which(`, `which `, `command -v ` → project looks up an executable at runtime
    - `Grep` for `subprocess.run(`, `child_process.exec(`, `Deno.Command(` → project invokes external CLI

package/skills/verification/SKILL.md

@@ -101,8 +101,6 @@ Compile all results into the structured report. Update all TodoWrite items to co
 
 ### 3-Level Artifact Verification
 
-> From GSD (gsd-build/get-shit-done, 30.8k★): "Task done ≠ Goal achieved."
-
 Every file created or modified during implementation must pass ALL 3 levels:
 
 **Level 1 — EXISTS**: File is on disk, non-empty.