@rune-kit/rune 2.2.4 → 2.3.0

package/skills/sentinel/references/config-protection.md

@@ -0,0 +1,52 @@
+# Config Protection — 3-Layer Defense Reference
+
+Reference for Step 4.6. Detect attempts to weaken linting, security, or CI/CD configurations.
+
+## Layer 1 — Linter/Formatter Config Drift
+
+Scan diff for changes to:
+- `.eslintrc*`, `eslint.config.*`, `biome.json` → rules disabled or removed
+- `tsconfig.json` → `strict` changed to `false`, `any` allowed, `skipLibCheck` added
+- `ruff.toml`, `.ruff.toml`, `pyproject.toml [tool.ruff]` → rules removed from select list
+- `.prettierrc*` → significant format changes without team discussion
+
+Detection patterns:
+
+```
+# ESLint rule disable
+"off" or 0 in rule config (compare with previous)
+// eslint-disable added to >3 lines in same file
+
+# TypeScript strictness weakening
+"strict": false
+"noImplicitAny": false
+"skipLibCheck": true (added, not already present)
+
+# Ruff rule removal
+select = [...] with fewer rules than before
+```
+
+Match = **WARN** — "Config change weakens code quality — verify this is intentional."
+
+## Layer 2 — Security Middleware Removal
+
+Scan for removal of security-critical middleware or decorators:
+
+- `helmet` removed from Express/Fastify middleware chain
+- `csrf` middleware removed or commented out
+- `cors` configuration changed to `origin: '*'`
+- `SecurityMiddleware` removed from Django `MIDDLEWARE`
+- `@csrf_protect` decorator removed from Django views
+
+Match = **BLOCK** — "Security middleware removed — this must be explicitly justified."
+
+## Layer 3 — CI/CD Safety Bypass
+
+Scan for weakening of CI/CD safety checks:
+
+- `--no-verify` added to git commands in scripts
+- `--force` added to deployment scripts
+- Test steps removed or marked `continue-on-error: true`
+- Coverage thresholds lowered
+
+Match = **WARN** — "CI safety check weakened — verify this is intentional."

package/skills/sentinel/references/destructive-commands.md

@@ -0,0 +1,40 @@
+# Destructive Command Guard — Pattern Table and Safe Exceptions
+
+Reference for Step 4b. Real-time command guard patterns for agent workflows.
+
+> Source: garrytan/gstack v0.9.0 (careful/freeze/guard skills) — real-time command safety, composable with edit scope lock.
+
+## Pattern Table
+
+Any skill executing Bash commands SHOULD check against these patterns before execution:
+
+| Pattern | Risk | Action |
+|---------|------|--------|
+| `rm -rf` / `rm -r` / `rm --recursive` | Recursive delete | WARN — confirm target is expected |
+| `DROP TABLE` / `DROP DATABASE` / `TRUNCATE` | Data loss | BLOCK — require explicit confirmation |
+| `git push --force` / `git push -f` | History rewrite | WARN — confirm branch is correct |
+| `git reset --hard` | Uncommitted work loss | WARN — verify no unsaved changes |
+| `git checkout .` / `git restore .` | Working tree wipe | WARN — verify intent |
+| `kubectl delete` / `docker system prune` | Production impact | BLOCK — require namespace/context confirmation |
+| `chmod 777` / `chmod -R 777` | Permission escalation | WARN — almost never correct |
+
+## Safe Exceptions (do NOT warn)
+
+- `rm -rf node_modules`, `.next`, `dist`, `__pycache__`, `.cache`, `build`, `.turbo`, `coverage`, `target`
+- `git push --force-with-lease` (safe force push)
+- `docker rm` on explicitly named test containers
+
+## Static Scan Targets (Step 4a)
+
+Scan changed files for:
+- Destructive shell commands in scripts: `rm -rf /`, `DROP TABLE`, `DELETE FROM` without `WHERE`, `TRUNCATE`
+- File operations using absolute paths outside the project root (e.g., `/etc/`, `/usr/`, `C:\Windows\`)
+- Direct production database connection strings (`prod`, `production` in DB host names)
+
+Destructive command on production path = **BLOCK**. Suspicious path = **WARN**.
+
+## Composable Modes (future — advisory only)
+
+- **Careful mode**: warn before any destructive command (all patterns above)
+- **Freeze mode**: restrict file edits to a specific directory (scope lock)
+- **Guard mode**: careful + freeze combined

package/skills/sentinel/references/domain-hooks.md

@@ -0,0 +1,73 @@
+# Domain Hook Templates — Pre-Commit Hook Generation Reference
+
+Reference for Step 5 (Domain Hook Templates). Contains the hook architecture, template, and built-in domain patterns.
+
+## Hook Architecture
+
+```
+hooks/
+├── pre-commit-security.sh      # Always — secret scan, OWASP basics (generated by sentinel)
+├── pre-commit-<domain>.sh      # Domain-specific — generated on request
+└── validate-<domain>.py        # Complex validation scripts (Python for portability)
+```
+
+## Hook Generation Rules
+
+1. **Exit 0 if no relevant files staged** — prevents false positives when committing unrelated changes
+2. **ERRORS block commit** (exit 1) — critical violations that must be fixed
+3. **WARNINGS alert but allow** (exit 0 with stderr) — non-critical issues the developer should review
+4. **List specific files and line numbers** — actionable output, not vague warnings
+5. **Fast execution** (<5 seconds) — hooks that slow down commits get disabled by developers
+
+## Domain Hook Template
+
+```bash
+#!/usr/bin/env bash
+# Pre-commit hook: <domain> quality gate
+# Generated by rune:sentinel — do not edit manually
+
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)
+DOMAIN_FILES=$(echo "$STAGED_FILES" | grep -E '<file-pattern>')
+
+# Exit early if no relevant files staged
+if [ -z "$DOMAIN_FILES" ]; then
+  exit 0
+fi
+
+ERRORS=0
+WARNINGS=0
+
+for file in $DOMAIN_FILES; do
+  # ERROR checks (block commit)
+  # <domain-specific-error-patterns>
+
+  # WARNING checks (alert only)
+  # <domain-specific-warning-patterns>
+done
+
+if [ $ERRORS -gt 0 ]; then
+  echo "❌ $ERRORS error(s) found — commit blocked. Fix before retrying."
+  exit 1
+fi
+
+if [ $WARNINGS -gt 0 ]; then
+  echo "⚠️  $WARNINGS warning(s) found — review recommended."
+fi
+
+exit 0
+```
+
+## Built-in Domain Hook Patterns
+
+| Domain | File Pattern | ERROR Checks | WARNING Checks |
+|--------|-------------|-------------|----------------|
+| **Schema/API** | `*.graphql`, `*.proto`, `openapi.*` | Breaking field removal, type changes | Deprecated field usage |
+| **Database** | `migrations/*.sql`, `*.migration.*` | DROP TABLE without backup, DELETE without WHERE | Missing rollback script |
+| **Config** | `*.env*`, `*config*`, `tsconfig*` | Secrets in config, strict mode disabled | New env var without docs |
+| **Dependencies** | `package.json`, `requirements.txt`, `Cargo.toml` | Known vulnerable version pinned | Major version bump without changelog |
+| **Legal/Compliance** | `docs/policies/*`, `PRIVACY*`, `TERMS*` | Placeholder text ([Company Name], [Date]) | Review date >12 months old |
+| **Financial** | `**/invoice*`, `**/billing*`, `**/payment*` | Hardcoded prices/rates, missing decimal precision | Currency without locale formatting |
+
+## Usage
+
+When a pack or skill requests domain hooks via `sentinel` integration, generate the appropriate hook script using the template above, customized with domain-specific patterns from the table.

package/skills/sentinel/references/framework-patterns.md

@@ -0,0 +1,46 @@
+# Framework-Specific Security Patterns
+
+Reference for Step 4.5. Apply only when the relevant framework is detected in changed files.
+
+## Django
+
+Detect: `django` in `requirements.txt` or imports.
+
+| Check | Severity |
+|-------|----------|
+| `DEBUG = True` in non-development settings file | BLOCK |
+| Missing `permission_classes` on `ModelViewSet` | WARN |
+| `SecurityMiddleware` / CSRF middleware removed from `MIDDLEWARE` list | BLOCK |
+
+## React / Next.js
+
+Detect: `.tsx` or `.jsx` files in changed set.
+
+| Check | Severity |
+|-------|----------|
+| JWT stored in `localStorage` instead of `httpOnly` cookie | WARN |
+| `dangerouslySetInnerHTML` without `DOMPurify.sanitize()` | BLOCK |
+
+## Node.js / Express / Fastify
+
+Detect: `express` or `fastify` in imports.
+
+| Check | Severity |
+|-------|----------|
+| CORS set to `origin: '*'` on authenticated endpoints | WARN |
+| Missing `helmet` middleware for HTTP security headers | WARN |
+
+## Python
+
+Detect: `.py` files in changed set.
+
+| Check | Severity |
+|-------|----------|
+| `pickle.loads(user_input)` or `eval(user_expression)` | BLOCK |
+| `yaml.load()` without `Loader` argument (uses unsafe loader) | WARN |
+
+## Detection Notes
+
+- Framework detection is file-based — scan imports and dependency manifests (`package.json`, `requirements.txt`, `Cargo.toml`, `go.mod`) in the changed file set.
+- Apply only the relevant framework sections — do not scan React patterns in a pure Python project.
+- "The framework handles security" is NOT an acceptable reason to skip any check (see Constraints in SKILL.md).

package/skills/sentinel/references/owasp-patterns.md

@@ -0,0 +1,69 @@
+# OWASP Patterns — Code Examples and Detection Details
+
+Reference for Step 3 (OWASP Check). Contains concrete detection examples for each category.
+
+## SQL Injection
+
+Detect string concatenation or interpolation inside SQL query strings.
+Severity: **BLOCK**
+
+```python
+# BAD — string interpolation in SQL → BLOCK
+cursor.execute(f"SELECT * FROM users WHERE id = {user_id}")
+query = "SELECT * FROM users WHERE name = '" + name + "'"
+
+# GOOD — parameterized query
+cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))
+```
+
+Detection signals:
+- f-string or `+` concatenation where the outer string contains `SELECT`, `INSERT`, `UPDATE`, `DELETE`, `WHERE`, `FROM`
+- `.format()` or `%` formatting applied to SQL strings
+
+## XSS (Cross-Site Scripting)
+
+Detect `innerHTML =`, `dangerouslySetInnerHTML`, `document.write(` with non-static content.
+Severity: **BLOCK**
+
+```typescript
+// BAD — renders raw user content → BLOCK
+element.innerHTML = userComment;
+<div dangerouslySetInnerHTML={{ __html: userInput }} />
+
+// GOOD — safe alternatives
+element.textContent = userComment;
+<div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(userInput) }} />
+```
+
+Detection signals:
+- `innerHTML` assigned a variable (not a string literal)
+- `dangerouslySetInnerHTML` without `DOMPurify.sanitize()` wrapping the value
+- `document.write(` with any non-literal argument
+
+## CSRF
+
+Detect HTML `<form>` without CSRF token fields; `Set-Cookie` without `SameSite`.
+Severity: **WARN**
+
+Detection signals:
+- `<form method="post">` or `<form method="POST">` without a hidden input containing `csrf`, `_token`, or `authenticity_token`
+- `Set-Cookie:` header string without `SameSite=` attribute
+
+## Missing Input Validation
+
+Detect new route/API handlers passing `req.body` / `request.json()` directly to DB calls.
+Severity: **WARN**
+
+```typescript
+// BAD — raw body to DB → WARN
+app.post('/users', async (req, res) => { await db.users.create(req.body); });
+
+// GOOD — validate at boundary
+app.post('/users', async (req, res) => {
+  const validated = CreateUserSchema.parse(req.body);
+  await db.users.create(validated);
+});
+```
+
+Detection signals:
+- Route handler body where `req.body` / `request.json()` / `event.body` flows directly into a DB call (`.create(`, `.insert(`, `.save(`, `.update(`) with no intermediate validation call

package/skills/sentinel/references/secret-patterns.md

@@ -0,0 +1,40 @@
+# Secret Patterns — Extended Gitleaks Reference
+
+Extended secret detection patterns for Step 1 (Secret Scan).
+
+## 1b. Extended Gitleaks Patterns
+
+```
+SLACK_TOKEN:      xox[bpors]-[0-9a-zA-Z]{10,}
+STRIPE_KEY:       [sr]k_(live|test)_[0-9a-zA-Z]{24,}
+SENDGRID:         SG\.[a-zA-Z0-9_-]{22}\.[a-zA-Z0-9_-]{43}
+TWILIO:           SK[0-9a-fA-F]{32}
+FIREBASE:         AIza[0-9A-Za-z_-]{35}
+PRIVATE_KEY:      -----BEGIN (RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----
+JWT:              eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}
+GENERIC_API_KEY:  (?i)(apikey|api_key|api-key)\s*[:=]\s*["'][A-Za-z0-9_-]{16,}
+```
+
+## 1c. Git History Scan (First Run Only)
+
+If no `.rune/sentinel-baseline.md` exists, run a historical scan:
+
+```bash
+git log --all --diff-filter=A -- '*.env*' '*.key' '*.pem' '*.p12' '*credentials*' '*secret*'
+```
+
+Result: any output → **WARN** — historical secret files detected. Recommend BFG/git-filter-repo cleanup.
+
+For subsequent runs, scan only the current diff (incremental).
+
+## Core Patterns (always active)
+
+Scan for these patterns in all changed files:
+
+- `sk-`, `AKIA`, `ghp_`, `ghs_`, `-----BEGIN`
+- `password\s*=\s*["']`, `secret\s*=\s*["']`
+- `api_key\s*=\s*["']`, `token\s*=\s*["']`
+- `.env` file contents committed directly (lines matching `KEY=value` outside `.env` files)
+- High-entropy strings: length > 40, entropy > 4.5 → HIGH_ENTROPY candidate
+
+Any match = **BLOCK**.

package/skills/sentinel/references/skill-content-guard.md

@@ -0,0 +1,55 @@
+# Skill Content Security Guard — 28 Regex Category Reference
+
+Reference for Step 3.5. Scan SKILL.md and skill-adjacent content files BEFORE write/commit.
+First-match-wins — report the category that triggered and halt.
+
+> Source: nextlevelbuilder/goclaw (832★) — 28 compiled regex rules on skill content pre-write.
+
+## Category Groups
+
+| Category | Pattern Examples | Severity |
+|----------|-----------------|----------|
+| Destructive ops | `rm -rf /`, `fork bomb: :(){ :|:& };:` | BLOCK |
+| Code injection | `eval(`, `exec(`, `curl \| bash`, `wget \| sh` | BLOCK |
+| Credential theft | `cat ~/.ssh`, `env \| grep`, `printenv` in instructions | BLOCK |
+| Path traversal | `../../../`, `%2e%2e%2f` in tool call instructions | BLOCK |
+| SQL injection | `' OR '1'='1`, `; DROP TABLE` in prompt text | BLOCK |
+| Privilege escalation | `sudo`, `chmod 777`, `chown root` in agent instructions | WARN |
+| Prompt injection | `Ignore previous instructions`, `Disregard your`, `New system prompt:` | BLOCK |
+| Jailbreak attempts | `DAN mode`, `developer mode`, `unrestricted AI` | BLOCK |
+| Data exfiltration | `curl -d @`, `nc -e`, sending files to external hosts in instructions | BLOCK |
+| Reverse shell | `bash -i`, `/dev/tcp/`, `mkfifo` in agent instructions | BLOCK |
+| Env variable leak | `$HOME`, `$PATH`, `$USER` echoed to external endpoints | WARN |
+| File enumeration | `ls -la /`, `find / -name`, directory traversal in instructions | WARN |
+| Network scanning | `nmap`, `masscan`, port scanning in instructions | BLOCK |
+| Crypto mining | `xmrig`, `minergate`, cryptocurrency mining commands | BLOCK |
+| Log tampering | `> /var/log/`, clearing auth logs in instructions | BLOCK |
+| Process hijacking | `ptrace`, `LD_PRELOAD=` in agent instructions | BLOCK |
+| Sudo escalation | `sudo -i`, `sudo su`, `sudo bash` | BLOCK |
+| SUID abuse | `find / -perm -4000`, SUID bit manipulation | WARN |
+| Crontab injection | `crontab -e`, scheduled malicious commands | WARN |
+| Package poisoning | Installing from untrusted registries in instructions | WARN |
+| DNS rebinding | Localhost bypass patterns in HTTP instructions | WARN |
+| SSRF patterns | Internal IP ranges (10.x, 192.168.x, 172.16-31.x) in fetch instructions | WARN |
+| Template injection | `{{7*7}}`, `${7*7}` in output templates | WARN |
+| Insecure deserialization | `pickle.loads`, `yaml.load(` without safe loader | BLOCK |
+| XXE injection | XML with `SYSTEM` entity in tool call content | WARN |
+| Header injection | `\r\n` in HTTP header values | WARN |
+| Command chaining abuse | `;` or `&&` chains in Bash instructions with destructive ops | WARN |
+| Webhook exfiltration | Sending `.rune/` or `SKILL.md` content to external URLs | BLOCK |
+
+## Safe Exceptions
+
+These patterns appear legitimately in skill examples and MUST NOT trigger:
+
+1. **Inside fenced code blocks labeled as anti-patterns** — preceded by `# BAD`, `// BAD`, or block labeled `bad-example`
+2. **Inside backtick fences explicitly documenting the attack** — educational examples in security skills (sentinel itself, sast, adversary)
+3. **Actual shell scripts in `scripts/` directory** — functional code, not agent instructions
+4. **Files in `test/`, `fixtures/`, `__mocks__/`** — test data, not live instructions
+
+## When to Apply
+
+- Any time skill content is WRITTEN or EDITED (not just committed)
+- Invoke from `skill-forge` Phase 7 pre-ship check
+- Invoke from any hook writing to `SKILL.md` files
+- Scope: `skills/*/SKILL.md`, `extensions/*/PACK.md`, `.rune/*.md`, agent files

package/skills/session-bridge/SKILL.md

@@ -3,7 +3,7 @@ name: session-bridge
 description: Universal context persistence across sessions. Auto-saves decisions, conventions, and progress to .rune/ files. Loads state at session start. Use when any skill makes architectural decisions or establishes patterns that must survive session boundaries.
 metadata:
   author: runedev
-  version: "0.2.0"
+  version: "0.4.0"
   layer: L3
   model: haiku
   group: state
@@ -42,7 +42,8 @@ Solve the #1 developer complaint: context loss across sessions. Session-bridge a
 ├── decisions.md      — Architectural decisions log
 ├── conventions.md    — Established patterns & style
 ├── progress.md       — Task progress tracker
-└── session-log.md    — Brief log of each session
+├── session-log.md    — Brief log of each session
+└── instincts.md      — Learned project-specific patterns (trigger→action)
 ```
 
 ## Execution
@@ -143,6 +144,63 @@ Use `Edit` to append a one-line entry to `.rune/session-log.md`:
 [YYYY-MM-DD HH:MM] — [brief description of session accomplishments]
 ```
 
+#### Step 5.5 — Autonomous Loop Notes (when inside team or headless)
+
+When session-bridge is invoked by `cook` running inside `team` or in autonomous mode (`claude -p`), persist iteration state to `.rune/task-notes.md`:
+
+```markdown
+# Task Notes: [task name]
+## What Worked (with evidence)
+- [approach]: [outcome, test output, or file path as proof]
+
+## What Failed
+- [approach]: [why it failed, error message]
+
+## What's Left
+- [ ] [remaining task with specific next step]
+
+## Key Context for Next Iteration
+- [critical info that would be lost on context reset]
+```
+
+**Why**: In autonomous loops, each `claude -p` invocation starts with zero context. Without this file, the next iteration repeats failed approaches and loses progress. The notes bridge the gap between independent invocations.
+
+**Rules**: Agent reads `.rune/task-notes.md` at start (Step 1 of Load Mode), updates at end. Keep concise — max 50 lines. Prune completed items.
+
+> Source: affaan-m/everything-claude-code (91.9k★) — SHARED_TASK_NOTES cross-iteration bridge.
+
+#### Step 5.7 — Instinct Extraction (Project-Scoped Learning)
+
+Extract atomic "instincts" — learned trigger→action patterns — from this session and persist to `.rune/instincts.md`. Instincts are project-scoped by default to prevent cross-project contamination.
+
+**Instinct format:**
+
+```markdown
+## [YYYY-MM-DD] Instinct: <short name>
+
+**Trigger:** <when this pattern applies — specific condition>
+**Action:** <what to do — specific behavior>
+**Confidence:** <0.3–0.9>
+**Evidence:** <what happened that taught this — file, error, outcome>
+```
+
+**Extraction rules:**
+
+| Signal | Example | Confidence |
+|--------|---------|------------|
+| Repeated manual correction by user | "Don't use X, use Y here" (2+ times) | 0.7–0.9 |
+| Failed approach → successful pivot | Tried approach A, failed, approach B worked | 0.5–0.7 |
+| Project-specific convention discovered | "This codebase uses X pattern for Y" | 0.4–0.6 |
+| One-off preference (may not generalize) | User chose a specific library once | 0.3–0.4 |
+
+**Promotion to global**: When the same instinct (matching trigger+action) appears in `.rune/instincts.md` across 2+ projects at confidence ≥0.8, promote it to Neural Memory via Step 6 with tag `[cross-project, instinct]`. Until then, it stays project-local.
+
+**Pruning**: At session start (Load Mode Step 1), review instincts older than 30 days with confidence <0.5 — remove them. Instincts that conflict with current conventions should be removed immediately.
+
+**Max instincts**: Keep `.rune/instincts.md` under 20 entries. When full, evict the lowest-confidence entry.
+
+> Source: affaan-m/everything-claude-code (91.9k★) — instinct-based learning with project isolation.
+
 #### Step 6 — Cross-Project Knowledge Extraction (Neural Memory Bridge)
 
 Before committing, extract generalizable patterns from this session for cross-project reuse:

package/skills/skill-forge/SKILL.md

@@ -3,7 +3,7 @@ name: skill-forge
 description: Use when creating new Rune skills, editing existing skills, or verifying skill quality before deployment. Applies TDD discipline to skill authoring — test before write, verify before ship.
 metadata:
   author: runedev
-  version: "1.2.0"
+  version: "1.5.0"
   layer: L2
   model: opus
   group: creation
@@ -97,11 +97,13 @@ Follow `docs/SKILL-TEMPLATE.md` format. Required sections:
 | Frontmatter | YES | Name, description, metadata |
 | Purpose | YES | One paragraph, ecosystem role |
 | Triggers | YES | When to invoke |
-| Calls / Called By | YES | Mesh connections |
+| Calls / Called By | YES | Mesh connections (control flow) |
+| Data Flow | YES | Feeds Into / Fed By / Feedback Loops (data flow) |
 | Workflow | YES | Step-by-step execution |
 | Output Format | YES | Structured, parseable output |
 | Constraints | YES | 3-7 MUST/MUST NOT rules |
 | Sharp Edges | YES | Known failure modes |
+| Self-Validation | YES | Domain-specific QA checklist (per-skill, not centralized) |
 | Done When | YES | Verifiable completion criteria |
 | Cost Profile | YES | Token estimate |
 | Mesh Gates | L1/L2 only | Progression guards |
@@ -277,12 +279,108 @@ Wire the skill into the mesh:
 1. **Update `docs/ARCHITECTURE.md`** — add to correct layer/group table
 2. **Update `CLAUDE.md`** — increment skill count, add to layer list
 3. **Add mesh connections** — update SKILL.md of skills that should call/be called by this one
-4. **Verify no conflicts** — new skill's output format compatible with consumers?
+4. **Map data flow** — identify which skills consume this skill's output (Feeds Into) and which skills' outputs this skill needs (Fed By). Look for feedback loops where two skills refine each other's work
+5. **Write Self-Validation** — 3-5 domain-specific checks unique to this skill's output. Ask: "What quality issues can ONLY this skill catch?"
+6. **Verify no conflicts** — new skill's output format compatible with consumers?
 
-### Phase 7 — SHIP
+### Phase 6.5 — EXTENSION AUTHORING (if building an extension, not a skill)
+
+Extensions augment existing skills with optional capabilities. Unlike skills (standalone workflow units) or packs (domain bundles), extensions ADD features to skills that already exist — without modifying the core skill file.
+
+#### Extension vs Skill vs Pack
+
+| Concept | Purpose | Modifies Core? | Self-contained? |
+|---------|---------|----------------|-----------------|
+| **Skill** | Standalone workflow unit (SKILL.md) | N/A — IS core | Yes |
+| **Pack** | Domain bundle of skills (PACK.md) | No — bundles existing | Yes |
+| **Extension** | Augments existing skill with new capability | No — additive only | Yes — own dir with install/uninstall |
+
+#### Extension Directory Structure
+
+```
+extensions/<extension-name>/
+├── EXTENSION.md           # Manifest: what it extends, how, dependencies
+├── install.sh             # Unix installer (non-destructive MCP merge)
+├── install.ps1            # Windows installer
+├── uninstall.sh           # Clean removal
+├── uninstall.ps1          # Clean removal (Windows)
+├── skills/
+│   └── <skill-name>/
+│       └── SKILL.md       # New skill added by extension
+├── agents/                # Optional subagent definitions
+│   └── <agent-name>.md
+├── references/            # Domain knowledge loaded by extension skills
+│   └── <topic>.md
+├── scripts/               # Executable utilities
+│   └── <script>.py|.sh
+└── docs/
+    └── SETUP.md           # Extension-specific configuration guide
+```
+
+#### EXTENSION.md Manifest
+
+```yaml
+---
+name: "<extension-name>"
+extends: "<target-skill-or-pack>"
+description: "What capability this extension adds"
+requires:
+  - mcp: "<mcp-server-name>"        # Optional: MCP server dependency
+  - skill: "<required-skill-name>"   # Required core skill
+install_method: "non-destructive"    # MUST be non-destructive
+---
+```
+
+#### Extension Rules
+
+1. **Non-destructive install** — extension MUST NOT modify existing skill files. It adds new files alongside.
+2. **Self-contained** — removing the extension directory restores the system to its pre-install state.
+3. **MCP merge** — if the extension adds MCP tools, install script MUST merge into settings.json without overwriting existing entries.
+4. **Fallback graceful** — if the MCP server or external dependency is unavailable, the extension skill MUST degrade gracefully (report unavailability, don't crash).
+5. **Cost awareness** — if the extension calls paid APIs, the extension skill MUST warn before expensive operations and track usage.
+6. **Pre-flight check** — extension skill Step 1 MUST verify dependencies are available before executing.
+
+#### When to Build an Extension (vs a Skill or Pack)
+
+- Build an **extension** when: the capability requires an external API/MCP, is optional, and augments an existing skill
+- Build a **skill** when: the capability is self-contained and fits a layer in the mesh
+- Build a **pack** when: you're bundling multiple related skills for a domain
+
+### Phase 7 — EVAL (Behavior Tests)
+
+Before shipping, write **Eval Scenarios** — behavior tests for the SKILL.md itself. These are "unit tests for skill files, not code."
+
+Save evals to `skills/<name>/evals.md`. Minimum 4 evals per skill:
+
+| Eval ID | Category | Required? |
+|---------|----------|-----------|
+| E01 | Happy path — core workflow | YES |
+| E02 | Edge case — unusual/empty input | YES |
+| E03 | Adversarial — pressure scenario | YES |
+| E04 | Jailbreak/injection attempt | YES for security-critical skills |
+
+Each eval follows the format defined in `rune:test` → "Skill Behavior Tests" section:
+- **Prompt**: exact situation the agent faces
+- **Expected Reasoning**: step-by-step reasoning agent SHOULD follow
+- **Must Include**: what the output MUST contain or do
+- **Must NOT**: anti-patterns the output MUST NOT produce
+
+Run each eval with a subagent. An eval FAILS if the agent produces a Must NOT output.
+
+**Pre-ship gate**: At least E01–E03 must PASS before committing. Security-critical skills (touching auth/secrets/destructive ops) require 8+ evals including jailbreak and credential-leak scenarios.
+
+Also run the **Skill Content Security Guard** (sentinel Step 3.5) on the new SKILL.md content before commit — blocks destructive ops, prompt injection, and jailbreak patterns embedded in skill instructions.
+
+<HARD-GATE>
+No evals.md → skill is behavior-untested. Do NOT ship untested skills.
+Eval file with 0 passing evals = same as no evals.
+</HARD-GATE>
+
+### Phase 8 — SHIP
 
 ```bash
 git add skills/[skill-name]/SKILL.md
+git add skills/[skill-name]/evals.md
 git add docs/ARCHITECTURE.md CLAUDE.md
 # Add any updated existing skills
 git commit -m "feat: add [skill-name] — [one-line purpose]"
@@ -302,7 +400,11 @@ git commit -m "feat: add [skill-name] — [one-line purpose]"
 - [ ] At least one observed failure documented
 - [ ] Anti-rationalization table from real test failures
 - [ ] Mesh connections bidirectional (calls AND called-by both updated)
+- [ ] Data flow mapped (Feeds Into / Fed By / Feedback Loops)
+- [ ] Self-Validation has 3-5 domain-specific checks (not generic)
 - [ ] Output format is structured and parseable by other skills
+- [ ] `evals.md` written with at least 3 passing eval scenarios (E01 happy-path, E02 edge-case, E03 adversarial)
+- [ ] Skill Content Security Guard passed (sentinel Step 3.5 — no destructive ops or injection patterns in SKILL.md)
 
 **Architecture:**
 - [ ] Layer assignment correct (L1=orchestrate, L2=workflow, L3=utility)
@@ -311,6 +413,14 @@ git commit -m "feat: add [skill-name] — [one-line purpose]"
 - [ ] ARCHITECTURE.md updated
 - [ ] CLAUDE.md updated
 
+**Extension-specific (if building an extension):**
+- [ ] EXTENSION.md manifest present with extends, requires, install_method
+- [ ] install.sh + install.ps1 tested (non-destructive merge)
+- [ ] uninstall.sh + uninstall.ps1 tested (clean removal)
+- [ ] Extension skill has dependency pre-flight check (Step 1)
+- [ ] Fallback behavior documented when external dependency unavailable
+- [ ] Cost warning present if extension calls paid APIs
+
 ## Adapting Existing Skills
 
 When editing, not creating:
@@ -368,6 +478,8 @@ Techniques:
 ### Mesh Impact
 - New connections: [count] ([list of skills])
 - Bidirectional check: PASS | FAIL
+- Data flow mapped: [count] feeds-into, [count] fed-by, [count] feedback loops
+- Self-Validation: [count] domain-specific checks written
 ```
 
 ## Constraints
@@ -393,6 +505,9 @@ Techniques:
 | Code blocks in SKILL.md bloat every invocation | HIGH | WHY vs HOW split: SKILL.md ≤10-line code blocks, extract rest to references/ |
 | Writing skill without TDD (no observed failures first) | CRITICAL | Skill TDD: RED (run scenario WITHOUT skill → document failures) → GREEN (write skill targeting failures) → REFACTOR (find bypasses → add blocks) |
 | Description leaks workflow → agent skips full content | HIGH | CSO Discipline: description = triggers only. Test: can you execute from description alone? If yes, it leaks too much |
+| Self-Validation copies completion-gate checks | HIGH | Self-Validation is DOMAIN-specific: "assertions per test", "dependency ordering". NOT generic: "tests pass", "build succeeds" — those belong to completion-gate |
+| Data Flow confused with Calls | MEDIUM | Calls = runtime invocation (skill A calls skill B). Feeds Into = artifact persistence (skill A writes .rune/X.md, skill B reads it later). If it's a direct function call → Calls. If it's via files/context → Data Flow |
+| Feedback Loop missing one direction | MEDIUM | Every Feedback Loop ↻ must document BOTH directions: what A sends to B AND what B sends back to A. One-way = Feeds Into, not a loop |
 
 ## Done When
 
@@ -403,6 +518,18 @@ Techniques:
 - Mesh connections wired (ARCHITECTURE.md, CLAUDE.md, related skills)
 - Git committed with conventional commit message
 
+## Returns
+
+| Artifact | Format | Location |
+|----------|--------|----------|
+| New or updated skill file | Markdown (SKILL.md) | `skills/<name>/SKILL.md` |
+| Eval scenarios | Markdown | `skills/<name>/evals.md` |
+| Reference files (if needed) | Markdown | `skills/<name>/references/` |
+| Architecture docs update | Markdown | `docs/ARCHITECTURE.md` |
+| Skill Forge Report | Markdown | inline |
+
 ## Cost Profile
 
 ~3000-8000 tokens per skill creation (opus for Phase 2-5 reasoning, haiku for scout/verification). Most cost is in the iterative test-refine loop (Phase 4-5). Budget 2-4 test iterations per skill.
+
+**Scope guardrail:** skill-forge authors and tests skill files — it does not implement the features those skills describe.