@caoscompanybr/merlin 3.5.0

package/.merlin-core/skills/general/purge-leaked-secret/SKILL.md

@@ -0,0 +1,383 @@
+---
+name: purge-leaked-secret
+description: Reactive runbook for when a credential is exposed (committed to git, pushed to GitHub, or visible in working tree). Rotate first, clean second, audit third. Companion to secret-safe-commit (which prevents the leak in the first place).
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  auto_activate:
+    [
+      purge-secret,
+      leaked-secret,
+      credential-rotation,
+      gitleaks-finding,
+      secret-incident,
+      git-history-clean,
+    ]
+  tool_reminders:
+    [
+      Rotate the credential FIRST before doing any cleanup — every minute the old key works is a window of exposure,
+      Assume the secret is compromised even if exposure was brief — never skip rotation,
+      Git history rewrites (filter-repo) are usually overkill once the secret is rotated — focus effort on rotation + future prevention,
+      Document the incident in thoughts/shared/incidents/ even for self-caught leaks (pattern data informs prevention),
+      Never paste the leaked secret into agent logs / chat / commit messages — even after rotation it's a habit that breeds future leaks,
+    ]
+---
+
+# Purge Leaked Secret Skill
+
+**Mission:** When a secret leaks — whether caught by gitleaks before commit,
+discovered post-commit by audit, or reported by an external party — execute a
+deterministic 5-phase response that minimizes exposure window and prevents
+recurrence.
+
+This skill is the reactive twin of `secret-safe-commit` (preventive). The
+preventive skill stops 99% of leaks from happening; this one handles the 1%
+that get through (or were there before the preventive skill was installed —
+e.g., the 3 credential files we found in a real project).
+
+---
+
+## When this skill activates
+
+- Gitleaks detects a finding (during `/safe-commit` or CI)
+- User mentions "leaked", "exposed credential", "rotate", "key compromised"
+- Engineering audit flags hardcoded credentials in code review
+- External party (security researcher, GitHub secret scanning) reports an exposed secret
+- After running baseline `gitleaks detect --log-opts="--all"` on a project for the first time
+
+---
+
+## Core principle: Rotation > Cleanup
+
+**Every minute the old credential is valid is a window of exposure.** A
+rotated credential that exists in git history is harmless (the value no
+longer authorizes anything). An unrotated credential that's been "scrubbed"
+from git history with `filter-repo` is still active in attacker tooling that
+cloned before the scrub.
+
+Order of operations is non-negotiable:
+
+1. **Rotate** (revokes the leaked value upstream)
+2. **Remove from disk** (working tree + .gitignore)
+3. **Optionally clean git history** (only if compliance requires it)
+4. **Audit + document** (what leaked, when, blast radius)
+5. **Prevent recurrence** (install secret-safe-commit if not already)
+
+---
+
+## The 5-phase protocol
+
+### Phase 1 — IDENTIFY (60 seconds)
+
+For each leaked credential, answer:
+
+| Question                      | Where to look                                                                                                                                                                                                                          |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| What type of credential?      | The secret prefix usually identifies it: `AKIA*`=AWS, `ghp_*`=GitHub PAT, `AIza*`=Google API key, `sk_*`=Stripe, `re_*`=Resend, `eyJ*`=JWT, `-----BEGIN*`=private key, `GOCSPX-*`=Google OAuth client secret, `APP_USR-*`=Mercado Pago |
+| Which file?                   | gitleaks output reports `File:` and `Line:`                                                                                                                                                                                            |
+| Is it in git history?         | `git log --all --full-history -p -S "<partial_secret>" -- '*'`                                                                                                                                                                         |
+| When was it first committed?  | `git log --all --full-history --diff-filter=A -- <filepath>`                                                                                                                                                                           |
+| Has it been pushed to remote? | `git log @{upstream}.. --oneline` shows unpushed; if missing, it's pushed                                                                                                                                                              |
+| Public or private repo?       | `gh repo view --json visibility -q .visibility`                                                                                                                                                                                        |
+
+**Severity matrix:**
+
+| Pushed to public repo                                                           | Pushed to private repo                                               | Local commit only                             | Working tree only                     |
+| ------------------------------------------------------------------------------- | -------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------- |
+| 🔴 CRITICAL — assume compromised within minutes (bots scrape GH within seconds) | 🟠 HIGH — assume compromised if anyone with repo access is untrusted | 🟡 MEDIUM — exposure to local OS/backup tools | 🟢 LOW — exposure to dev machine only |
+
+### Phase 2 — ROTATE (5–30 minutes, depending on credential type)
+
+This is the ONLY step that actually closes the exposure. Do it FIRST, before
+any cleanup. Do NOT skip "because I'll clean it up quick" — assume the secret
+is compromised.
+
+**Rotation procedures by credential type:**
+
+| Credential                                     | Where to rotate                                                                                                                                     | Approximate time |
+| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
+| **Firebase Admin SDK key**                     | console.firebase.google.com → Project Settings → Service Accounts → "Generate new private key" → after testing new key works, click "Delete" on old | 5 min            |
+| **Google OAuth client secret**                 | console.cloud.google.com → APIs & Services → Credentials → click client → "Reset Secret"                                                            | 3 min            |
+| **Google API key**                             | console.cloud.google.com → APIs & Services → Credentials → "Regenerate key"                                                                         | 2 min            |
+| **GitHub PAT (`ghp_*`)**                       | github.com/settings/tokens → revoke old, generate new with same scopes                                                                              | 5 min            |
+| **GitHub fine-grained token (`github_pat_*`)** | github.com/settings/personal-access-tokens → revoke + regenerate                                                                                    | 5 min            |
+| **AWS access key (`AKIA*`)**                   | IAM console → Users → Security Credentials → Make active key Inactive → Create new → Test → Delete inactive                                         | 10 min           |
+| **Stripe (`sk_live_*` / `sk_test_*`)**         | dashboard.stripe.com → Developers → API keys → Roll                                                                                                 | 3 min            |
+| **Mercado Pago access token (`APP_USR-*`)**    | mercadopago.com.br → Aplicações → Credentials → Reset                                                                                               | 5 min            |
+| **OpenAI API key (`sk-*`)**                    | platform.openai.com → API keys → Revoke + Create new                                                                                                | 3 min            |
+| **Anthropic API key (`sk-ant-*`)**             | console.anthropic.com → API Keys → Delete + Create                                                                                                  | 3 min            |
+| **Resend API key (`re_*`)**                    | resend.com/api-keys → Delete + Create                                                                                                               | 3 min            |
+| **Mailgun / Sendgrid**                         | Provider dashboard → API keys section                                                                                                               | 5 min            |
+| **Database password**                          | Connect via root, `ALTER USER ... PASSWORD ...`, update env vars across all consumers atomically                                                    | 15 min           |
+| **SSH private key**                            | Generate new keypair (`ssh-keygen -t ed25519`), install on server, REMOVE OLD pubkey from authorized_keys                                           | 10 min           |
+| **JWT signing secret**                         | Rotate the signing key in your auth service config — invalidates ALL outstanding tokens (users will need to re-login)                               | 15 min           |
+| **Webhook signing secret**                     | Provider dashboard → Webhooks → Roll secret → update consumer env var                                                                               | 10 min           |
+
+**Universal rotation checklist (after generating new value):**
+
+- [ ] Update env var / secret manager (Firebase Secrets, Infisical, GitHub Secrets, etc.)
+- [ ] Test the new value works (smoke test the integration)
+- [ ] Revoke / delete the old value upstream
+- [ ] Update local `.env` (NOT committed) if used in development
+- [ ] Notify any teammate who might have the old value cached
+- [ ] If the secret is in CI: confirm CI now uses the new value before next deploy
+
+### Phase 3 — REMOVE (5 minutes)
+
+Now that the upstream is rotated, clean up the leaked file:
+
+```bash
+# 1. Remove from working tree
+rm <leaked-file>
+
+# 2. Add to .gitignore by literal name (don't rely on patterns)
+echo "<leaked-file>" >> .gitignore
+
+# 3. Stage the .gitignore change + the deletion
+git add .gitignore
+git rm --cached <leaked-file>  # if it was tracked
+
+# 4. Commit (use /safe-commit which now has gitleaks pre-flight)
+/safe-commit "security: remove rotated credential file <name>"
+```
+
+If the leaked credential was hardcoded INSIDE source code (not a separate
+file), edit the code to use an env var / secret manager reference, then
+commit normally.
+
+### Phase 4 — DECIDE: clean git history or accept?
+
+This is the hardest phase. Most teams over-rotate to git-filter-repo when
+it's not necessary.
+
+**When to leave history alone (common case):**
+
+- Credential is rotated → old value is dead → presence in history is a
+  historical curiosity, not a vulnerability
+- Repo is private → blast radius is limited to people who already have access
+- Rewrite would require force-push + everyone re-cloning + breaks any open PRs
+- Cost > benefit for already-invalid secrets
+
+**When to actually clean history:**
+
+- Compliance requires it (SOC 2 Type II, HIPAA, PCI-DSS audit explicit clause)
+- The credential is a long-lived shared resource that can't be fully rotated
+  (e.g., a hardcoded customer's actual phone number that violates LGPD)
+- Repo is public AND the secret is for an account that contains regulated data
+
+**If you decide to clean (use git-filter-repo, NOT the deprecated git filter-branch):**
+
+```bash
+# Install
+pip install git-filter-repo
+
+# Backup the repo first (filter-repo is destructive)
+git clone --mirror <repo> <repo>-backup
+
+# Remove a specific file from all history
+git filter-repo --path <leaked-file> --invert-paths
+
+# OR remove a specific string from all history (more surgical, slower)
+git filter-repo --replace-text <(echo "<leaked-string>==>REDACTED")
+
+# Force-push to remote (this is destructive — coordinate with team)
+git push --force-with-lease --all
+git push --force-with-lease --tags
+
+# Notify all collaborators to re-clone (their local refs will be diverged)
+```
+
+**After force-push:** GitHub may still cache the old commits via the API for
+~24h. The data is no longer reachable but old SHAs may resolve briefly. Do
+NOT count history rewrite as "the secret is now gone" — count rotation as
+that.
+
+### Phase 5 — DOCUMENT + PREVENT (15 minutes)
+
+#### Incident document
+
+Create `.merlin-core/thoughts/shared/incidents/YYYY-MM-DD-<short-name>.md`:
+
+```markdown
+---
+date: 2026-04-27
+incident_type: secret_leak
+severity: HIGH # CRITICAL/HIGH/MEDIUM/LOW per matrix in Phase 1
+status: resolved
+---
+
+# Incident: <Short name>
+
+## What leaked
+
+- Credential type: <e.g., Firebase Admin SDK private key>
+- File: <path>
+- First committed: <date or "working tree only">
+- Pushed to remote: yes/no, when
+- Repo visibility at time of leak: public/private
+
+## How discovered
+
+- Detection method: <gitleaks pre-commit / CI scan / external report / manual audit>
+- Detected by: <person or system>
+- Detection date: <ISO 8601>
+
+## Blast radius
+
+- Estimated exposure window: <minutes/hours/days>
+- Systems accessible with leaked credential: <list>
+- Evidence of unauthorized access in logs: <yes/no, summary>
+
+## Response timeline
+
+- HH:MM - leak detected
+- HH:MM - rotation started for credential X
+- HH:MM - rotation complete + tested
+- HH:MM - file removed from working tree + .gitignore updated
+- HH:MM - decision: <history rewrite yes/no, reasoning>
+- HH:MM - incident closed
+
+## Root cause
+
+- <e.g., file was generated by `firebase init` and not auto-added to .gitignore>
+- <e.g., developer pasted secret into code instead of env var because deadline pressure>
+
+## Prevention actions
+
+- [ ] Installed `secret-safe-commit` skill / verified gitleaks pre-commit active
+- [ ] Added file pattern to project `.gitleaks.toml` if applicable
+- [ ] Added file by literal name to `.gitignore`
+- [ ] Documented in team runbook
+```
+
+#### Install secret-safe-commit if not already
+
+If this leak happened because the project didn't have gitleaks pre-commit:
+
+```bash
+# In the affected project root:
+pip install pre-commit
+cp <merlin-skills>/secret-safe-commit/templates/.pre-commit-config.yaml .
+cp <merlin-skills>/secret-safe-commit/templates/.gitleaks.toml .
+mkdir -p .github/workflows
+cp <merlin-skills>/secret-safe-commit/templates/secret-scan.yml .github/workflows/
+pre-commit install
+```
+
+#### Pattern feedback
+
+If the leaked credential type wasn't caught by default gitleaks rules
+(unusual prefix, custom internal token), add a custom rule to the project's
+`.gitleaks.toml` AND consider contributing the rule upstream to gitleaks.
+
+---
+
+## Common gotchas
+
+### Gotcha #1 — "I'll just delete the file, no one will notice"
+
+If the file was ever committed (even briefly), it's in git history. `rm` only
+removes from working tree. The credential is still discoverable via
+`git log -p`. Always rotate first; never assume "no one saw it".
+
+### Gotcha #2 — Rotating in the wrong order leaves a downtime window
+
+If you rotate a database password by:
+
+1. Update DB to require new password
+2. Update app env var to use new password
+
+Step 1 will break the running app until step 2 completes. Reverse the order:
+
+1. Add the new password as a SECONDARY accepted password (if your DB supports)
+2. Update app env var
+3. Verify app works with new password
+4. Revoke old password
+
+For databases without dual-password support, accept brief downtime and
+schedule rotation during low-traffic window.
+
+### Gotcha #3 — Rotating Firebase Admin key invalidates active sessions
+
+Firebase Admin SDK service account keys, when rotated, invalidate any cached
+auth state in running Cloud Functions instances. Functions will throw auth
+errors briefly until they re-fetch the new key. Plan rotation during low
+traffic.
+
+### Gotcha #4 — `git filter-repo` requires fresh clone
+
+`git filter-repo` refuses to operate on a regular working clone (it expects
+a fresh clone or `--force` flag). The intent: prevent accidental rewriting
+of work-in-progress branches. Always clone fresh into a temp dir for
+filter-repo operations.
+
+### Gotcha #5 — Force-push doesn't clear GitHub forks
+
+If anyone forked the repo before the leak, the secret is in their fork. You
+cannot force-push someone else's fork. Reach out to known forkers; otherwise
+accept the residual exposure (rotation makes it irrelevant anyway).
+
+### Gotcha #6 — Cached secrets in dev machines
+
+Even after rotation, the OLD credential may still be cached in:
+
+- Local `.env` files (update them)
+- Shell history (`history -d <line>`)
+- Editor session restore data
+- Browser autofill (developer tools / API testers)
+- Postman / Insomnia / Bruno collections (rotate stored secrets)
+
+Notify all team members to update their local copies.
+
+---
+
+## Specific runbook: a real 3-credential-file incident
+
+This skill was created in response to discovering 3 credential files in the
+working tree:
+
+| File                                                               | Credential type                      | Severity                                      | Action                                                          |
+| ------------------------------------------------------------------ | ------------------------------------ | --------------------------------------------- | --------------------------------------------------------------- |
+| `client_secret_<PROJECT_NUMBER>-*.apps.googleusercontent.com.json` | Google OAuth client secret           | HIGH (if pushed) / LOW (if working-tree only) | Rotate via console.cloud.google.com                             |
+| `<project>-firebase-adminsdk-fbsvc-<hash>.json`                    | Firebase Admin SDK private key (RSA) | CRITICAL                                      | Rotate via console.firebase.google.com                          |
+| `youtube_token.json`                                               | Google OAuth refresh + access tokens | MEDIUM                                        | Revoke via myaccount.google.com → Security → Third-party access |
+
+**Pre-flight investigation (CRITICAL — do before deciding severity):**
+
+```bash
+cd /path/to/project
+
+# Check if any of these files are in git history (any branch, any commit)
+git log --all --oneline -- \
+  'client_secret_*.json' \
+  '*-firebase-adminsdk-*.json' \
+  'youtube_token.json' 2>&1
+
+# If output is EMPTY: working-tree only, severity = LOW for all 3
+# If output has commits: pushed status determines CRITICAL vs HIGH
+git log --remotes --oneline -- \
+  'client_secret_*.json' \
+  '*-firebase-adminsdk-*.json' \
+  'youtube_token.json' 2>&1
+
+# If second command shows commits: pushed = CRITICAL severity
+```
+
+Then proceed through Phases 2-5 above.
+
+---
+
+## Related skills
+
+- **`secret-safe-commit`** — preventive twin (stops the leak from happening)
+- **`engineering-audit`** — security axis includes "leaked credentials in code"
+- **`vps-security-hardening`** — recovery kit pattern (USB) referenced in Phase 2
+- **`incident-response-runbook`** (Tier 3 roadmap) — broader template for any incident type
+
+---
+
+## References
+
+- [GitHub: removing sensitive data from a repository](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository)
+- [git-filter-repo official docs](https://github.com/newren/git-filter-repo)

package/.merlin-core/skills/general/reflection/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: reflection
+description: Structured metacognition checkpoints for deep reasoning. Forces agents to pause and examine their own thought process before making decisions.
+license: Apache-2.0
+metadata:
+  author: merlin-framework
+  version: "3.0.0"
+  auto_activate: [reflect, rethink, reconsider, reasoning, assumption-check]
+  tool_reminders:
+    [
+      Run the 4-Question Pause before finalizing any plan or architecture decision,
+      Use DEEP reflection (with Devil's Advocate) after test failures,
+    ]
+---
+
+# Reflection — Think Tool
+
+Structured metacognition protocol for agents to examine their reasoning before committing to decisions.
+
+## When to Reflect
+
+Trigger a reflection checkpoint at these moments:
+
+- After completing research synthesis (before writing the document)
+- Before finalizing an implementation plan
+- When encountering unexpected or contradictory findings
+- Before making architectural trade-offs
+- When uncertain about a decision's implications
+- When switching approaches mid-task
+
+## Reflection Protocol
+
+### The 4-Question Pause
+
+1. **GOAL CHECK:** What am I trying to achieve? Has the original goal drifted? Am I solving the right problem?
+
+2. **EVIDENCE CHECK:** What have I found so far? What is the strongest evidence supporting my current direction? What contradicts it? Are there findings I'm ignoring?
+
+3. **UNCERTAINTY CHECK:** What am I uncertain about? What assumptions am I making that I haven't validated? What information would change my conclusion?
+
+4. **NEXT STEP CHECK:** Given the above, what should I do next? Should I continue on this path, pivot to a different approach, or escalate to the user?
+
+## Depth Levels
+
+### QUICK Reflection
+
+- **Use during:** implementation, debugging, simple decisions
+- **Questions:** GOAL CHECK + NEXT STEP CHECK only
+- **Format:** 2-3 sentences inline
+
+### STANDARD Reflection
+
+- **Use during:** research synthesis, plan drafting, code review
+- **Questions:** All 4 questions
+- **Format:** Structured block with `> [REFLECTION]` prefix
+
+### DEEP Reflection
+
+- **Use during:** major architectural decisions, strategy pivots, risk assessment, test failures
+- **Questions:** All 4 questions + Devil's Advocate (argue against your own conclusion)
+- **5th Question — DEVIL'S ADVOCATE:** What could go wrong? What am I missing? Argue against your own conclusion with the strongest counter-arguments you can find.
+- **Format:** Full structured block with counter-argument section
+
+## Output Format
+
+```markdown
+> [REFLECTION — STANDARD]
+> **Goal:** Building the authentication middleware for the API gateway.
+> **Evidence:** Found 3 existing auth patterns in the codebase. JWT is used everywhere.
+> **Uncertainty:** Unclear if refresh token rotation is required — spec doesn't mention it.
+> **Next:** Proceed with JWT but ask user about refresh token requirement before finalizing.
+```
+
+## Anti-Patterns
+
+- **Not analysis paralysis.** Reflection is a brief, structured pause — not an excuse to delay.
+- **Not second-guessing.** Don't re-question decisions already validated by evidence.
+- **Not recursive.** One reflection per checkpoint. Don't reflect on your reflection.
+- **Not a substitute for asking.** If you're truly blocked, escalate to the user instead of reflecting indefinitely.
+
+## Mandatory Transitions (v2.6.0)
+
+The following phase transitions trigger **automatic** reflection checkpoints enforced by `ReflectCheckpointEngine`. These are NOT optional — the gate evaluator will block advancement if reflection fails.
+
+| Transition                       | Depth    | Questions                                               |
+| -------------------------------- | -------- | ------------------------------------------------------- |
+| `research_to_architecture`       | STANDARD | GOAL, EVIDENCE, UNCERTAINTY, NEXT_STEP                  |
+| `architecture_to_implementation` | STANDARD | GOAL, EVIDENCE, UNCERTAINTY, NEXT_STEP                  |
+| `before_commit`                  | QUICK    | GOAL, NEXT_STEP                                         |
+| `after_test_failure`             | DEEP     | GOAL, EVIDENCE, UNCERTAINTY, NEXT_STEP, DEVILS_ADVOCATE |
+
+The reflection output is scored (0.0–1.0) and concerns are classified as NONE/LOW/MEDIUM/HIGH/CRITICAL. A CRITICAL or HIGH concern level causes the `reflection_passed` gate check to fail.
+
+## Integration Points
+
+- `/research` — STANDARD reflection after Step 4 (Synthesize Findings)
+- `/plan` — STANDARD reflection after Step 2 (Draft the Plan)
+- `/implement` — QUICK reflection at each phase boundary
+- `/adversarial-review` — DEEP reflection before issuing final verdict
+- **WorkflowExecutor** — automatic checkpoint at every phase transition (v2.6.0)