@caoscompanybr/merlin 3.5.0

package/.merlin-core/commands/review/check.md

@@ -0,0 +1,91 @@
+---
+description: Unified quality gate — runs lint, typecheck, test, build, and security scan in one command
+model: sonnet
+version: "3.0.0"
+---
+
+# /check — Unified Quality Gate
+
+Runs all quality gates in a single command. Replaces remembering 4-5 separate commands.
+Stops on first failure by default (fail-fast). Reports pass/fail per gate with timing.
+
+## Usage
+
+```
+/check              → Run all gates on changed files (default)
+/check --full       → Run all gates on the entire project
+/check --fix        → Auto-fix lint/format issues, then run all gates
+/check --security   → Security scan only (Semgrep + dependency audit)
+/check --fast       → Skip build and security, run lint + typecheck + test only
+```
+
+## Protocol
+
+### Step 1: Detect Stack
+
+Inspect project root for:
+
+- `package.json` → Node/JavaScript/TypeScript
+- `pyproject.toml` or `setup.py` → Python
+- `go.mod` → Go
+- `Cargo.toml` → Rust
+- Multiple → run all applicable stacks
+
+### Step 2: Build Gate Sequence
+
+Run gates in this order (stop on first failure unless `--full`):
+
+| #   | Gate          | Node/TS                               | Python            | Go                     | Rust           |
+| --- | ------------- | ------------------------------------- | ----------------- | ---------------------- | -------------- |
+| 1   | Lint / Format | `npm run lint`                        | `ruff check .`    | `golangci-lint run`    | `cargo clippy` |
+| 2   | Type Check    | `npm run typecheck` or `tsc --noEmit` | `mypy .`          | _(built into compile)_ | `cargo check`  |
+| 3   | Tests         | `npm test`                            | `pytest`          | `go test ./...`        | `cargo test`   |
+| 4   | Build         | `npm run build`                       | `python -m build` | `go build ./...`       | `cargo build`  |
+| 5   | Security      | `semgrep --config=auto .`             | `bandit -r .`     | `gosec ./...`          | `cargo audit`  |
+
+> If a package.json script doesn't exist (e.g. no `typecheck` script), skip that gate and note it.
+> Check `package.json` scripts before running — use the actual configured script name.
+
+### Step 3: Report Results
+
+Output a summary table after all gates (or after failure):
+
+```
+/check Results — [timestamp]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Gate          Status    Duration   Notes
+──────────────────────────────────────
+Lint          ✓ PASS    1.2s
+Type Check    ✓ PASS    3.4s
+Tests         ✗ FAIL    8.1s       3 failures (see below)
+Build         ─ SKIP              (stopped on test failure)
+Security      ─ SKIP              (stopped on test failure)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Verdict: FAIL — fix Tests to proceed
+
+[Failure details here]
+```
+
+### Step 4: On Failure
+
+1. Show the full failure output (truncated to last 50 lines if very long)
+2. Identify the root cause (missing import, type error, assertion failure, etc.)
+3. Ask: "Shall I fix this?" — do NOT auto-fix unless `--fix` flag was used
+4. After fix: re-run only the failed gate, not the full sequence
+
+### --fix Mode
+
+Only auto-fixes deterministic, safe issues:
+
+- `eslint --fix` / `prettier --write`
+- `ruff check --fix .`
+- `gofmt -w .`
+- `rustfmt`
+
+Never auto-fixes: test failures, type errors, build errors, security findings.
+
+## Integration
+
+- Uses [static-analysis](../../skills/general/static-analysis/SKILL.md) for the security gate
+- Reports feed into [quality-gates](../../skills/general/guardrails/SKILL.md) Layer 1 (pre-commit)
+- On FAIL verdict, suggest [/debug](./debug.md) for deeper investigation

package/.merlin-core/commands/review/debug.md

@@ -0,0 +1,135 @@
+---
+description: Systematic debugging — find root cause before attempting fixes
+model: opus
+---
+
+# Debug
+
+Investigate issues using a 4-phase systematic methodology. Random fixes waste time and create new bugs.
+
+**Iron Law:** NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.
+
+## Phase 1: Root Cause Investigation
+
+Before attempting ANY fix:
+
+1. **Read error messages carefully** — Don't skip past errors. Read stack traces completely. Note line numbers, file paths, error codes. They often contain the exact solution.
+
+2. **Reproduce consistently** — Can you trigger it reliably? What are the exact steps? If not reproducible, gather more data — don't guess.
+
+3. **Check recent changes** — What changed that could cause this?
+
+   ```bash
+   git log --oneline -10
+   git diff HEAD~3
+   ```
+
+4. **Gather evidence in multi-component systems** — When the system has multiple layers (API → service → database, CI → build → deploy):
+
+   ```bash
+   # Log what enters and exits EACH component boundary
+   # Layer 1: entry point
+   echo "=== Input received: ==="
+   echo "PARAM: ${PARAM:+SET}${PARAM:-UNSET}"
+
+   # Layer 2: processing
+   echo "=== State after processing: ==="
+
+   # Layer 3: output
+   echo "=== Result: ==="
+   ```
+
+   Run once to gather evidence showing WHERE it breaks. Then investigate that specific component.
+
+5. **Trace data flow backward** — Where does the bad value originate? What called this with the bad value? Keep tracing up the call stack until you find the source. Fix at source, not at symptom.
+
+## Phase 2: Pattern Analysis
+
+Find the pattern before fixing:
+
+1. **Find working examples** — Locate similar working code in the same codebase
+2. **Compare against references** — If implementing a pattern, read the reference implementation COMPLETELY (don't skim)
+3. **Identify differences** — What's different between working and broken? List every difference, however small
+4. **Understand dependencies** — What settings, config, environment does this need?
+
+## Phase 3: Hypothesis and Testing
+
+Scientific method — one variable at a time:
+
+1. **Form single hypothesis** — State clearly: "I think X is the root cause because Y"
+2. **Test minimally** — Make the SMALLEST possible change to test the hypothesis
+3. **Verify before continuing** — Did it work? Yes → Phase 4. No → form NEW hypothesis. DON'T add more fixes on top.
+
+## Phase 4: Implementation
+
+1. **Spawn agents for evidence gathering:**
+   - Use **scout** to find related test files and error handlers
+   - Use **researcher** to analyze the code path
+
+2. **Create failing test case** — Simplest possible reproduction. Automated test if possible.
+
+3. **Implement single fix** — Address the root cause. ONE change at a time. No "while I'm here" improvements.
+
+4. **Verify fix** — Test passes? No other tests broken? Issue actually resolved?
+
+5. **If fix doesn't work:**
+   - Count: How many fixes have you tried?
+   - If < 3: Return to Phase 1, re-analyze with new information
+   - **If ≥ 3: STOP and question the architecture**
+
+## The 3-Fix Escalation Rule
+
+When 3+ fixes have failed, this is NOT a bug — it's an architectural problem.
+
+**Signals:**
+
+- Each fix reveals new shared state or coupling
+- Fixes require "massive refactoring" to implement
+- Each fix creates new symptoms elsewhere
+
+**Action:** STOP fixing. Present to the user:
+
+```
+Debug Escalation: [Brief description]
+
+Attempted Fixes:
+1. [Fix 1] → Result: [what happened]
+2. [Fix 2] → Result: [what happened]
+3. [Fix 3] → Result: [what happened]
+
+Pattern: [What the failures reveal about the architecture]
+
+Recommendation: [Refactor X / Redesign Y / Discuss approach with team]
+```
+
+## Red Flags — STOP and Return to Phase 1
+
+If you catch yourself thinking any of these, you're guessing instead of investigating:
+
+| Thought                                        | Reality                                                |
+| ---------------------------------------------- | ------------------------------------------------------ |
+| "Quick fix for now, investigate later"         | Quick fixes become permanent. Investigate now.         |
+| "Just try changing X and see"                  | That's guessing, not debugging. Gather evidence first. |
+| "I'll add multiple changes and run tests"      | Can't isolate what worked. One change at a time.       |
+| "It's probably X, let me fix that"             | "Probably" means you don't know. Verify first.         |
+| "I don't fully understand but this might work" | Stop. Understand before changing.                      |
+
+## Output Format
+
+```
+Debug Report: [Brief description]
+
+Root Cause: [What's actually wrong — traced to source]
+Location: [file:line]
+Evidence: [What confirms this is the issue]
+Phase reached: [1-4]
+
+Fix Applied:
+- [Specific change made]
+
+Verification:
+- [Test that proves the fix works]
+- [Other tests still passing]
+
+Risk Assessment: [LOW/MEDIUM/HIGH]
+```

package/.merlin-core/commands/review/doubts.md

@@ -0,0 +1,178 @@
+---
+description: Collaborative code discussion session informed by project learnings
+model: opus
+---
+
+# Doubts
+
+Initiate a collaborative code discussion session between the AI and the user.
+Unlike `/debug` (which diagnoses issues) or `/adversarial-review` (which attacks
+code), `/doubts` is a **two-way conversation** where either party raises questions
+about the codebase, and answers are informed by accumulated project learnings.
+
+This command is **Discussion-First by design** (Article XIII). No code is written
+or modified during a doubts session — only reading, researching, and discussing.
+
+## Usage
+
+```
+/doubts [area]         — Open discussion about a code area or domain
+/doubts [file path]    — Discuss a specific file with learnings context
+/doubts                — AI asks what area the user wants to explore
+```
+
+## When to Use
+
+- When the user says "I have a question about..." or "I'm not sure how..."
+- When the user wants to understand how a part of the codebase works
+- When onboarding to unfamiliar code and wanting to discuss it collaboratively
+- When there's a suspicion that code may contradict known learnings or patterns
+- When the user wants to review code together without committing to changes
+
+## Process
+
+### Step 1: Determine Scope
+
+1. **If file path provided:** Use that file as the target
+2. **If area/domain provided:** Use it as a search scope
+3. **If nothing provided:** Ask the user:
+
+```markdown
+What area of the codebase would you like to discuss?
+
+You can specify:
+
+- A file path (e.g., `src/routes/api.ts`)
+- A domain (e.g., "authentication", "database", "API")
+- A concept (e.g., "how errors are handled", "the build pipeline")
+```
+
+### Step 2: Load Learnings Context
+
+1. Search `thoughts/shared/learnings/` for entries matching the scope:
+   - Match by `applies_to` field (file paths, module names)
+   - Match by `domain` field
+   - Match by `tags` field
+   - Match by keyword in title or content
+2. Exclude any learnings where `supersedes` points to them from a newer entry
+3. Sort by relevance (keyword match score), then by date (newest first)
+4. Cap at 10 learnings to keep context focused
+
+### Step 3: Read the Code
+
+1. Read the target file(s) in the specified scope
+2. If scope is broad (a directory or domain), identify the 3-5 most relevant
+   files using Glob/Grep and read those
+3. Note: read code thoroughly — this is a discussion, not a skim
+
+### Step 4: Cross-Reference
+
+Analyze where learnings apply to the current code:
+
+- **Known gotchas** in this area? Flag them with the code location
+- **Established patterns/conventions** that the code follows (or breaks)?
+- **Previous constraints or workarounds** that explain unusual code?
+- **Superseded learnings** that might indicate outdated knowledge?
+- **Gaps** — areas with no learnings that might benefit from discussion?
+
+### Step 5: Present Initial Findings
+
+```markdown
+## 🤔 Doubts Session: [area/file]
+
+### What I See
+
+[Brief description of the code area — its purpose, structure, key patterns]
+
+### Relevant Learnings
+
+| #   | Learning | Category | Confidence | Applies To |
+| --- | -------- | -------- | ---------- | ---------- |
+| 1   | [title]  | [cat]    | [conf]     | [path]     |
+
+[If a learning directly applies to visible code, quote the relevant code
+and explain the connection]
+
+### Questions I Have
+
+1. [AI's genuine question about the code — informed by learnings gaps]
+2. [Potential inconsistency between code and a known learning]
+3. [Area where behavior is unclear and no learning exists]
+
+### Your Turn
+
+Do you have doubts about any specific part of this code?
+Are there areas where behavior is unclear or surprising to you?
+```
+
+### Step 6: Discussion Loop
+
+Maintain a back-and-forth conversation:
+
+**When the user asks a question:**
+
+1. Research the code to find the answer (read files, trace logic, check tests)
+2. Check if any existing learnings address this question
+3. Present the answer with evidence (code references, learning citations)
+4. If unsure, say so honestly (Article X — Professional Objectivity)
+
+**When the AI identifies something worth discussing:**
+
+1. Present the observation with code evidence
+2. Reference any relevant learning or its absence
+3. Ask the user for their perspective or clarification
+
+**Conversation discipline:**
+
+- Stay focused on the declared scope — don't drift to unrelated areas
+- Reference learnings by their citation ID when applicable
+- If a new insight emerges, note it for potential capture at wrap-up
+- After 3-4 exchanges, offer to wrap up or continue
+
+### Step 7: Wrap Up
+
+When the user is satisfied or the discussion reaches natural conclusion:
+
+```markdown
+## 📋 Doubts Session Summary
+
+### Clarified
+
+- [What was understood or resolved during the discussion]
+
+### New Learnings to Capture
+
+- [Any new insights discovered — for each, offer to run /capture-learning]
+
+### Updated Learnings
+
+- [Any existing learnings that need confidence upgrade or correction]
+
+### Remaining Doubts
+
+- [Anything still unclear — offer to create a reminder or research task]
+
+### Suggested Next Steps
+
+- [Concrete actions based on what was discussed]
+```
+
+For each new learning identified, ask: "Want me to `/capture-learning` for this?"
+For remaining doubts, ask: "Want me to `/create-reminder` to revisit this?"
+
+## Rules
+
+- **No implementation** — never write, edit, or modify code during a doubts session
+- **Two-way conversation** — actively ask questions, don't just answer
+- **Evidence-based** — cite code lines and learning IDs, don't speculate
+- **Honest uncertainty** — if you don't know, say so (Article X)
+- **Learning-aware** — always check learnings before answering from scratch
+- **Scope discipline** — stay within the declared area unless user redirects
+
+## Constitution Compliance
+
+- **Article XIII (Discussion-First):** This IS the discussion command — it embodies the principle
+- **Article VIII (Craftsmanship):** Leverages accumulated knowledge instead of re-discovering
+- **Article X (Professional Objectivity):** AI raises genuine questions, admits uncertainty
+- **Article III (Spec-Driven):** Discussions can feed into research → plan → implement pipeline
+- **Article IV (No Invention):** Findings are grounded in code evidence and existing learnings

package/.merlin-core/commands/review/engineering-audit.md

@@ -0,0 +1,87 @@
+---
+description: Run a 6-axis engineering audit evaluating architecture, security, performance, resiliency, quality, and scale
+model: opus
+---
+
+# Engineering Audit
+
+Run a holistic engineering audit across 6 dimensions. Not style. Not lint. Structure, security, resilience, and quality.
+
+## Usage
+
+```
+/engineering-audit [file-or-directory-path]
+```
+
+If no path provided, audit the most recently changed files via `git diff --name-only`.
+
+## Process Steps
+
+### Step 1: Identify Scope
+
+1. If a path was provided, use it as the audit scope
+2. If no path, run `git diff --name-only` and `git diff --cached --name-only` to identify changed files
+3. Read all files in scope fully — understand the current state
+
+### Step 2: Load Skill Context
+
+Load the engineering-audit skill from `.merlin-core/skills/general/engineering-audit/SKILL.md` for the evaluation rubric.
+
+For deep dives, cross-reference:
+
+- `static-analysis` skill for security tooling
+- `web-quality` skill for frontend performance standards
+- `code-style` skill for structural rules and resiliency patterns
+
+### Step 3: Evaluate All 6 Axes
+
+For each file in scope, evaluate across all dimensions:
+
+1. **Architecture** — Separation of concerns, module boundaries, data flow, circular dependencies
+2. **Security** — Input validation, auth, secrets, injection, trust boundaries, CVEs
+3. **Performance** — Frontend (re-renders, bundle, lazy loading, Core Web Vitals) + Backend (N+1, indexes, blocking, caching, pooling, pagination)
+4. **Resiliency** — Error handling context, retry logic, graceful degradation, race conditions, transactions, timeouts
+5. **Quality** — Tests, naming, abstractions, dead code, duplication, function/file length
+6. **Scale** — Bottlenecks at 10x/100x, horizontal scalability, query efficiency, statelessness, caching strategy
+
+### Step 4: STANDARD Reflection
+
+Before issuing your verdict, reflect:
+
+> **GOAL CHECK:** Did I evaluate ALL 6 axes, or did I skip the harder ones?
+> **EVIDENCE CHECK:** Does every finding include a specific file/area reference and a concrete fix?
+> **SEVERITY CHECK:** Are my severity ratings calibrated? CRITICAL = security/crash/data-loss, not inconvenience.
+> **ANTI-NITPICK:** Am I flagging style preferences? If so, remove them. This is about structure, not tabs vs spaces.
+
+### Step 5: Present Findings
+
+For each finding:
+
+```
+[CRITICAL/HIGH/MEDIUM/LOW] Title
+Where: file or area
+Problem: what's wrong
+Impact: what happens if not fixed
+Fix: specific change needed
+```
+
+### Step 6: Deliver Verdict
+
+Summarize with total findings by severity, then one of:
+
+- **SHIPPA** — World-class. Ship it.
+- **CORRIGE PRIMEIRO** — Fix the findings, then ship.
+- **REPENSA** — Fundamental issues. Rethink the approach before proceeding.
+
+### Step 7: Offer to Fix
+
+If verdict is CORRIGE PRIMEIRO:
+
+- Offer to fix HIGH-severity issues immediately
+- After fixing, re-run the audit on the fixed code
+
+## Constitution Compliance
+
+- **Article V (Quality First):** Engineering audit is a quality gate
+- **Article X (Professional Objectivity):** Flag technically unsound patterns without sugarcoating
+- **Article VII (Human Gates):** Final verdict requires human acknowledgment

package/.merlin-core/commands/review/local-review.md

@@ -0,0 +1,48 @@
+---
+description: Set up and perform local code review before creating PR
+model: opus
+---
+
+# Local Review
+
+Review changes locally before creating a pull request. Ensures quality gate Layer 1 compliance.
+
+## Process
+
+1. **Assess scope:**
+   - Run `git diff main...HEAD --stat` to see all changed files
+   - Count the number of files and lines changed
+
+2. **Run automated checks (Quality Layer 1):**
+   - `npm run lint` (or project-equivalent)
+   - `npm test` (or project-equivalent)
+   - `npm run typecheck` (if TypeScript)
+   - `npm run build` (if applicable)
+
+3. **Review each file:**
+   - For each changed file, read the diff
+   - Check for: security issues, logic errors, missing tests, style violations
+   - Note any Constitution violations (especially Principle IV: No Invention)
+
+4. **Present review summary:**
+
+```
+Local Review: [branch name]
+
+Files changed: [count]
+Lines: +[added] -[removed]
+
+Automated Checks:
+- [ ] Lint: [pass/fail]
+- [ ] Tests: [pass/fail]
+- [ ] Typecheck: [pass/fail]
+- [ ] Build: [pass/fail]
+
+Code Review:
+- [Finding 1 with file:line]
+- [Finding 2 with file:line]
+
+Verdict: [READY / NEEDS FIXES]
+```
+
+5. **If NEEDS FIXES**, offer to fix issues before PR

package/.merlin-core/commands/review/verify-goals.md

@@ -0,0 +1,83 @@
+---
+description: Verify implementation against plan must_haves using goal-backward verification
+model: opus
+---
+
+# Verify Goals
+
+Verify that an implementation satisfies the plan's must_haves using **goal-backward verification** (GSD pattern). Instead of checking "did we do the work?", this checks "are the goals met?"
+
+## Usage
+
+```
+/verify-goals [plan-file-path]
+```
+
+If no path provided, locate the most recent plan in `thoughts/shared/plans/`.
+
+## Process
+
+### Step 1: Extract Must-Haves
+
+1. Read the plan file fully
+2. Locate the `## Must-Haves` section
+3. Parse the three tables: Truths, Artifacts, Key Links
+4. If no must_haves section exists, report: "No must_haves found. Consider adding them with /iterate-plan."
+
+### Step 2: Verify Truths
+
+For each truth in the Truths table:
+
+- **If `automated`:** Run the verification command. Record pass/fail with output.
+- **If `manual`:** Present the manual step to the user. Ask them to confirm.
+- **If `both`:** Run the automated check first, then present the manual step.
+
+### Step 3: Verify Artifacts
+
+For each artifact in the Artifacts table:
+
+- Check that the `path_pattern` resolves to an existing file
+- If `validation` is specified, perform additional checks (e.g., "parseable JSON" → try JSON.parse)
+- Record exists/missing for each artifact
+
+### Step 4: Verify Key Links
+
+For each key_link:
+
+- Check that `implementation_ref` (file:line) exists and is reachable
+- Mark status as `verified` if the file and line exist
+- Flag any `pending` links as unimplemented requirements
+
+### Step 5: Present Report
+
+```markdown
+## Goal-Backward Verification: [plan name]
+
+### Truths
+
+| ID  | Statement   | Verification | Result            |
+| --- | ----------- | ------------ | ----------------- |
+| T1  | [statement] | automated    | PASS/FAIL         |
+| T2  | [statement] | manual       | CONFIRMED/PENDING |
+
+### Artifacts
+
+| ID  | Description | Path   | Result         |
+| --- | ----------- | ------ | -------------- |
+| A1  | [desc]      | [path] | EXISTS/MISSING |
+
+### Key Links
+
+| Requirement | Implementation | Status   |
+| ----------- | -------------- | -------- |
+| FR-1        | src/auth.js:42 | verified |
+
+### Verdict: [ALL_MET / PARTIAL / NONE_MET]
+
+[If PARTIAL: list which truths failed, which artifacts are missing, which links are unverified]
+```
+
+## Constitution Compliance
+
+- **Article IV (No Invention):** Key links ensure every implementation traces to a requirement
+- **Article V (Quality First):** Goal-backward verification is a quality gate

package/.merlin-core/commands/session/capture-feedback.md

@@ -0,0 +1,74 @@
+---
+description: Record approve/reject feedback so the agent stops repeating rejected suggestions
+model: sonnet
+---
+
+# Capture Feedback
+
+Record a granular **approve/reject** signal whenever the user accepts or rejects
+a suggestion. Feedback is the v3.4 immune-system memory: it is **consulted before
+re-suggesting** (so the same rejected idea is not proposed again) and is promoted
+over time into durable `learnings/` and `decisions/`.
+
+Feedback is **FIFO-capped** — only the newest 30 entries per domain are kept
+(`merlin prune-feedback`). It is ephemeral by design; durable signal graduates.
+
+## When to Use
+
+- The user approves or rejects something you proposed (a draft, a plan, an action)
+- The user corrects your judgment ("don't do X", "I prefer Y")
+- The user expresses a tone/style preference worth not re-learning the hard way
+
+## The Pipeline (don't skip the consult step)
+
+```
+Feedback (granular, here) → Lessons (curated prose) → Decisions (permanent)
+```
+
+Before making a NEW suggestion in a domain, scan `thoughts/shared/feedback/` for
+prior rejections in that domain. Don't repeat a rejected approach.
+
+## Process
+
+1. **Capture the signal:** what you suggested, the decision (`approve`/`reject`), and the **reason** (the reason is the load-bearing part).
+2. **Set metadata:**
+   - **domain:** feedback area (`content`, `tasks`, `recommendations`, `tone`, …)
+   - **decision:** `approve` | `reject`
+   - **tags:** domain + type keywords
+3. **Save:** `thoughts/shared/feedback/YYYY-MM-DD-{slug}.md`
+4. **Rebuild the index:** `node .merlin-core/tools/merlin-tools.js index`
+5. **Prune (optional / scheduled):** `node .merlin-core/tools/merlin-tools.js prune-feedback`
+
+## Template
+
+```markdown
+---
+title: "[What was suggested]"
+date: YYYY-MM-DD
+domain: "[content|tasks|recommendations|tone]"
+decision: reject
+reason: "[Why it was approved/rejected — concrete]"
+tags: [domain, type]
+source_agent: dev
+project: "[project name]"
+---
+
+# Feedback: [Title]
+
+## Suggestion
+
+[What you proposed.]
+
+## Decision
+
+**[approve|reject]** — [the reason, in the user's words where possible]
+
+## Apply Next Time
+
+[How this changes future suggestions in this domain.]
+```
+
+## Constitution Compliance
+
+- **Article VIII (Craftsmanship):** closes the loop — the agent learns from approvals/rejections instead of repeating them
+- **Article IV (No Invention):** only record decisions the user actually made