@caoscompanybr/merlin 3.5.0

package/.merlin-core/commands/session/create-reminder.md

@@ -0,0 +1,86 @@
+---
+description: Create a persistent reminder for cross-session awareness
+model: sonnet
+---
+
+# Create Reminder
+
+Create a reminder document that persists across sessions. Reminders are injected
+into agent context via the Alkimia memory system, ensuring important items
+are never forgotten between context resets.
+
+## When to Use
+
+- An important detail must not be forgotten across sessions
+- A deadline or due date needs tracking
+- A specific condition must be checked before proceeding with future work
+- A blocker needs to remain visible until resolved
+
+## Process
+
+1. **Gather details:**
+   - Title (clear, action-oriented)
+   - Priority: low | medium | high | critical
+   - Due date (if applicable)
+   - Owner agent (who should see this reminder most prominently)
+   - Whether it blocks execution (blocking: true/false)
+   - Related plan or task (if applicable)
+
+2. **Determine linking:**
+   - Check if there's an active plan this reminder relates to
+   - Link via `plan_ref` in frontmatter if so
+
+3. **Save the reminder:**
+   - Path: `thoughts/shared/reminders/YYYY-MM-DD-{slug}.md`
+   - Use today's date and a descriptive kebab-case slug
+
+4. **Rebuild the thoughts index** after saving:
+
+   ```bash
+   node .merlin-core/tools/merlin-tools.js index
+   ```
+
+5. **Confirm creation:**
+   - Show the saved path
+   - Explain when and how it will surface in agent context
+
+## Template
+
+```markdown
+---
+title: "[Clear action-oriented title]"
+date: YYYY-MM-DD
+tags: [relevant, tags]
+priority: medium
+due_date: YYYY-MM-DD
+status: pending
+owner: dev
+blocking: false
+plan_ref: ""
+---
+
+# Reminder: [Title]
+
+## What
+
+[Clear description of what needs to be remembered]
+
+## Why It Matters
+
+[Impact if this is forgotten]
+
+## Action Items
+
+- [ ] [Specific action 1]
+- [ ] [Specific action 2]
+
+## Related
+
+- Plan: [link to plan if applicable]
+- Handoff: [link to handoff if applicable]
+```
+
+## Constitution Compliance
+
+- **Article VIII (Craftsmanship):** Reminders support continuity across sessions
+- **Article III (Spec-Driven):** Reminders can link to plans for traceability

package/.merlin-core/commands/session/fast-start.md

@@ -0,0 +1,261 @@
+---
+description: Interactive session onboarding — triage thoughts, conclude stale items, set direction
+model: opus
+version: 3.0.0
+---
+
+# Fast Start — Interactive Session Onboarding
+
+Scan the thought index, present what's in flight, interactively triage stale
+items with the user, conclude what's done, capture learnings, and establish a
+clean session direction. This is the primary mechanism for thought lifecycle
+management.
+
+Project-scoped — only surfaces thoughts relevant to the current project.
+Cross-project items are summarized separately, never mixed in.
+
+## When to Use
+
+- At the very start of a fresh session (suggested automatically via CLAUDE.md)
+- When returning to a project after a break
+- When the user says "let's clean up" or "what's going on"
+- When onboarding a new team member or agent to a project's current state
+
+## Process
+
+### Phase 0: Project Scope Detection
+
+Before scanning thoughts, determine what project this session belongs to:
+
+1. **Read `project-config.yaml`** and extract `project.name` (e.g., `"Gestao Merlin"`)
+2. **Build project aliases** — a set of strings that identify "this project":
+   - The `project.name` value (e.g., `"Gestao Merlin"`)
+   - The working directory basename (e.g., `"Gestao Merlin"`)
+   - Common abbreviations: lowercase, no spaces (e.g., `"gestao-merlin"`, `"merlin"`)
+3. **Also load `managed_projects`** from `project-config.yaml` — these are
+   OTHER projects managed from this repo. Their names become the "cross-project"
+   identifiers (e.g., `"ProjectA"`, `"ProjectB"`, `"ProjectC"`)
+
+**Project matching rules** for each thought entry:
+
+- Check `frontmatter.project` field against project aliases → **this-project**
+- Check `frontmatter.project` against managed project names → **cross-project** (tag with project name)
+- Check `frontmatter.location` field — if it points to a different directory → **cross-project**
+- If filename contains a managed project slug (e.g., `proja-`, `projb-`, `projc-`) → **cross-project**
+- **No project field AND no cross-project signals** → assume **this-project** (local thought)
+
+### Phase 1: Index-Based Quick Scan
+
+1. **Read `thoughts/shared/INDEX.json`** (single file, not all documents):
+   - If INDEX.json is missing or older than 24 hours, rebuild it first:
+     `node .merlin-core/tools/merlin-tools.js index`
+   - Parse the `entries` array
+
+2. **Apply project scope filter (Phase 0):**
+   - Split entries into **this-project** and **cross-project** buckets
+   - All subsequent phases (2, 3, 4) operate ONLY on **this-project** entries
+   - Cross-project entries are summarized once in Phase 4
+
+3. **Partition this-project entries by the `lifecycle` field:**
+   - **active** — `lifecycle === "active"` → needs interactive review
+   - **stale** — `lifecycle === "stale"` → flagged for triage
+   - **terminal** — `lifecycle === "terminal"` → **SKIP entirely** (cold data)
+   - If an entry lacks a `lifecycle` field (old index format), fall back to
+     reading its frontmatter `status` directly and classify:
+     - Terminal statuses: `concluded`, `achieved`, `abandoned`, `completed`, `complete`, `expired`, `done`, `milestone_complete`
+     - Active statuses: `active`, `pending`, `draft`, `acknowledged`, `in_progress`, or no status
+     - Stale: active but older than 14 days
+
+4. **Present the partition summary:**
+
+   ```
+   📊 Thought Inventory (Gestao Merlin): X active, Y stale, Z terminal (cold)
+   📦 Cross-project items skipped: N (from ProjectA, ProjectB, ProjectC...)
+   ```
+
+5. **Only read FULL files for active + stale items** (never read terminal items).
+   If ≤3 active items total, use **Quick Mode** (Phase 5).
+
+> **CRITICAL:** Terminal items MUST NOT appear in the interactive review,
+> reminders check, or active context sections. They are cold data — indexed
+> and searchable but invisible to session onboarding.
+
+### Phase 2: Interactive Review
+
+Present active and stale handoffs and plans (newest first). For each one,
+read the full file and present:
+
+```markdown
+---
+📋 **[Type]: [Title]** ([date])
+> [First 2-3 lines of content or summary section]
+> Tags: [tags]
+
+Status: **Active** | Age: [X days]
+[If stale]: ⚠️ **Stale** — last updated [X] days ago
+
+❓ What's the status of this?
+  1. Still active — keep it
+  2. Done — conclude it
+  3. Done + capture learnings
+  4. Skip for now
+---
+```
+
+Process the user's response:
+
+- **1 (keep):** Leave as-is, move to next item
+- **2 (conclude):** Run `/conclude` in batch mode — add `status: concluded` and `concluded_date`
+- **3 (conclude + learn):** Run `/conclude` with learning capture — guide through `/capture-learning`
+- **4 (skip):** Move to next item without changes
+
+Continue until all active/stale handoffs and plans are reviewed. Group
+consecutive "conclude" actions and confirm as a batch before writing:
+"I'll conclude these N items: [list]. Proceed?"
+
+### Phase 3: Reminders & Objectives Check
+
+> Only show items where `lifecycle` is NOT `terminal`.
+
+#### Reminders
+
+1. List all pending/acknowledged reminders (lifecycle: active or stale)
+2. Flag OVERDUE (due_date in the past) and BLOCKING items
+3. For each overdue reminder, ask: "Still relevant? Complete / Expire / Extend?"
+4. Apply status changes as confirmed
+
+#### Objectives
+
+1. List all active objectives with progress (lifecycle: active or stale)
+2. Flag OVERDUE (deadline in the past)
+3. For each, briefly ask: "Still pursuing this? Any progress update?"
+4. Update `progress_pct` if user provides new numbers
+5. Conclude achieved/abandoned objectives via `/conclude`
+
+#### Certified Processes (business "process fast-start")
+
+> Permanent operating procedures (Constitution XIV) — surfaced, not triaged.
+
+1. List `certified` processes from `thoughts/shared/processes/` (skip `deprecated`)
+2. For each, show its trigger (manual / cron schedule) and how to run it
+3. This is read-only awareness — do NOT conclude or modify processes here; use
+   `/recall-processes` for full detail or `/run-process <slug>` to execute one
+
+Present as:
+
+```markdown
+### 🎯 Active Objectives
+
+| #   | Objective | Progress | Deadline | Status                       |
+| --- | --------- | -------- | -------- | ---------------------------- |
+| 1   | [title]   | [pct]%   | [date]   | On Track / At Risk / Overdue |
+
+### 📌 Pending Reminders
+
+| #   | Reminder | Priority   | Due    | Owner    | Flags                    |
+| --- | -------- | ---------- | ------ | -------- | ------------------------ |
+| 1   | [title]  | [priority] | [date] | @[agent] | 🔴 OVERDUE / 🚫 BLOCKING |
+
+### ⚙️ Certified Processes
+
+| #   | Process | Trigger       | Run                   |
+| --- | ------- | ------------- | --------------------- |
+| 1   | [title] | [cron/manual] | `/run-process [slug]` |
+
+Any updates on these?
+```
+
+### Phase 4: Session Summary
+
+After triage is complete, present the cleaned-up view:
+
+```markdown
+## ⚡ Session Briefing
+
+### 📊 Triage Results
+
+- **Concluded this session:** [N] items
+- **Learnings captured:** [N]
+- **Still active:** [N] items
+- **Cold data (skipped):** [N] terminal items not shown
+
+### 🔴 Immediate Attention
+
+- [Overdue or blocking items — only shown if they exist]
+
+### 🔄 Active Context
+
+- **Handoffs:** [list of remaining active handoffs with 1-line summaries]
+- **Plans:** [list of remaining active plans with 1-line summaries]
+- **Objectives:** [list with progress]
+
+### 🧠 Recent Learnings (last 7 days)
+
+- **[title]** — [category]: [domain] ([confidence])
+
+### 📦 Cross-Project Items (not shown in review)
+
+> These thoughts belong to other managed projects. They were not included
+> in the interactive triage. To review them, open a session in that project.
+
+| Project  | Active | Stale | Types              |
+| -------- | ------ | ----- | ------------------ |
+| ProjectA | 2      | 1     | handoff, objective |
+| ProjectB | 0      | 1     | plan               |
+
+_Omit this section if there are zero cross-project items._
+
+### 💡 Suggested Actions
+
+1. [Most urgent action based on what remains]
+2. [Second priority]
+
+What would you like to focus on?
+```
+
+### Phase 5: Quick Mode (Fallback)
+
+Used when ≤3 active items total, or user explicitly says "quick" or "brief".
+This is the v1 behavior — read-only, no interactive triage:
+
+1. Present all active items in the summary format (Phase 4)
+2. Skip the interactive review (Phases 2-3)
+3. Still end with suggested actions and the focus question
+
+## Rules
+
+- **Project-scoped** — only review thoughts belonging to the current project; cross-project items get a summary table, never interactive review
+- **Index-first** — always read INDEX.json before individual files
+- **Never surface terminal items** — cold data stays cold
+- **Interactive by default** — the whole point is dialogue with the user
+- **Never auto-conclude** — always ask before changing any status (Article VII)
+- **Batch confirmations** — group multiple conclusions and confirm together
+- **Learning capture is optional** — offer it but don't force it
+- **End with a question** — always ask what to focus on (Article XIII)
+- **Respect user pace** — if user says "skip the rest" or "looks good", stop triage immediately
+
+## Graceful Handling
+
+- If a section has no items, show: `*No [type] found.*`
+- If the entire thoughts directory is empty:
+
+```markdown
+## ⚡ Fast Start Briefing
+
+No active objectives, reminders, handoffs, or learnings found.
+
+This project has a clean slate. You can:
+
+- `/create-objective` to set a goal
+- `/create-reminder` to track an action item
+- Start working and `/capture-learning` as you discover things
+
+What would you like to work on?
+```
+
+## Constitution Compliance
+
+- **Article VII (Human Gates):** Every status change requires explicit user confirmation
+- **Article VIII (Craftsmanship):** Proper lifecycle management, no orphaned thoughts
+- **Article III (Spec-Driven):** Surfaces existing plans and objectives before new work
+- **Article XIII (Discussion-First):** Interactive dialogue, ends with open question

package/.merlin-core/commands/session/recall-learnings.md

@@ -0,0 +1,79 @@
+---
+description: Recall domain-specific learnings relevant to current work context
+model: sonnet
+---
+
+# Recall Learnings
+
+Retrieve and present learnings relevant to the current agent's area of action.
+While the Alkimia memory system automatically surfaces learnings during context
+injection, this command allows explicit, filtered retrieval when an agent needs
+to check what's known about a specific domain before starting work.
+
+## When to Use
+
+- Before starting work in an area to see what's already been learned
+- When encountering unexpected behavior — check if it's a known gotcha
+- When establishing patterns — check if conventions already exist
+- When onboarding to a project — understand its accumulated domain knowledge
+- When an agent asks "what do we know about [topic]?"
+
+## Process
+
+### Step 1: Determine Filters
+
+Accept optional filters from the user or infer from context:
+
+- **domain:** Filter by area of action (e.g., "database", "api", "frontend")
+- **project:** Filter by project name
+- **category:** Filter by type (gotcha, pattern, convention, constraint, insight, workaround)
+- **tags:** Filter by specific keywords
+- **applies_to:** Filter by file paths or module names
+
+If no filters provided, use the current agent's ID and active task context
+to infer the most relevant domain.
+
+### Step 2: Scan Learnings
+
+1. Read all files in `thoughts/shared/learnings/`
+2. Parse frontmatter for metadata
+3. Apply filters (any match on domain, tags, or applies_to counts)
+4. Exclude learnings that have been superseded (check `supersedes` field across all docs)
+5. Sort by relevance: keyword match to current context, then by date (newest first)
+
+### Step 3: Present Results
+
+```markdown
+## Learnings: [domain/filter]
+
+| #   | Title   | Category | Confidence | Date   | Tags   |
+| --- | ------- | -------- | ---------- | ------ | ------ |
+| 1   | [title] | [cat]    | [conf]     | [date] | [tags] |
+
+### Details
+
+#### 1. [Title]
+
+> [Insight text — the core learning]
+
+- **Applies to:** [paths/modules]
+- **Source:** @[agent] on [date]
+- **File:** [path to learning doc]
+```
+
+If no learnings match the filters, inform the agent and suggest broadening
+the search or creating new learnings as they discover domain knowledge.
+
+### Step 4: Offer Actions
+
+After presenting results, offer:
+
+- View full details of a specific learning
+- Update confidence level (observed → verified) if confirmed during current work
+- Mark a learning as superseded if it's outdated
+- Capture a new learning if gaps are identified
+
+## Constitution Compliance
+
+- **Article VIII (Craftsmanship):** Proactive knowledge retrieval prevents re-discovery
+- **Article III (Spec-Driven):** Learnings inform planning with real observations

package/.merlin-core/commands/session/recall-processes.md

@@ -0,0 +1,74 @@
+---
+description: Recall the business's certified processes — a "process fast-start"
+model: sonnet
+---
+
+# Recall Processes
+
+Retrieve and present the certified PROCESSOs relevant to the current work — a
+"fast-start of the business's processes." While the Alkimia memory system already
+surfaces certified processes during context injection (they are permanently active,
+like learnings), this command gives explicit, filtered recall when you want to see
+exactly which repeatable procedures exist and how to run them.
+
+## When to Use
+
+- At the start of work, to see what the business already runs as a defined process
+- Before doing something manually — check if a certified process already covers it
+- When deciding what to automate next (gaps in process coverage)
+- When an agent asks "what processes do we have for [domain]?"
+
+## Process
+
+### Step 1: Determine Filters
+
+Accept optional filters from the user or infer from context:
+
+- **domain / tags:** area (e.g., "release", "maintenance", "content")
+- **trigger_mode:** `manual` | `scheduled` | `event`
+- **status:** default to `certified` (the runnable ones); include `draft`/`tested` only if asked
+
+### Step 2: Scan Processes
+
+1. Read all files in `thoughts/shared/processes/`
+2. Parse the flat frontmatter (title, status, trigger_mode, schedule, tz) and the
+   `json` definition body block (steps + success_criteria)
+3. Apply filters; exclude `deprecated`
+4. Sort: `certified` first, then by trigger (scheduled by next cadence), then date
+
+### Step 3: Present Results
+
+```markdown
+## Certified Processes: [domain/filter]
+
+| #   | Title   | Trigger       | Steps | Status    |
+| --- | ------- | ------------- | ----- | --------- |
+| 1   | [title] | [cron/manual] | [n]   | certified |
+
+### Details
+
+#### 1. [Title]
+
+> [Purpose — one line]
+
+- **Trigger:** [manual | "0 18 * * 5" America/Sao_Paulo]
+- **Steps:** [n] ([k] autonomous, [m] gated)
+- **Run:** `/run-process [slug]` · **File:** [path]
+```
+
+If no processes match, say so and suggest `/create-process` to define one.
+
+### Step 4: Offer Actions
+
+After presenting, offer:
+
+- Run a certified process now (`/run-process <slug>`)
+- Inspect a process's full step list + safety classification
+- Create a new process (`/create-process`) for an uncovered need
+- Re-certify a `tested`/edited process (`certify-process`) if its signature is stale
+
+## Constitution Compliance
+
+- **Article XIV (Certified Process Authority):** Only `certified` processes are runnable
+  without per-step approval; recall makes the certified set visible and invokable.
+- **Article VIII (Craftsmanship):** Surfacing defined processes prevents ad-hoc re-work.

package/.merlin-core/commands/session/resume-handoff.md

@@ -0,0 +1,51 @@
+---
+description: Resume work from a handoff document with fresh context
+model: opus
+---
+
+# Resume Handoff
+
+Resume work from a previously created handoff document. This command loads the essential context from the handoff into a fresh context window.
+
+## Process
+
+0. **Validate fresh context:**
+   - If `.merlin/context-bridge.json` exists and `tool_calls > 10`, warn:
+     "This session is not fresh. For best results, start a new Claude Code session."
+   - For Folloni Funnel phase transitions, fresh context is REQUIRED.
+
+1. **Resolve handoff file:**
+   - If a handoff path or filename was provided in ARGUMENTS:
+     - Full path → use directly
+     - Filename only (e.g., `2026-03-15-skill-ecosystem-v2.21.md`) → look in `thoughts/shared/handoffs/`
+     - Partial match (e.g., `skill-ecosystem`) → fuzzy-match against handoff filenames in the directory
+   - If no path provided → find the most recent file in `thoughts/shared/handoffs/`
+
+2. **Read the handoff document FULLY**
+3. **Restore context:**
+   - Check git branch matches handoff
+   - Read the key files mentioned
+   - Review the "What's Next" section
+   - Note any open questions
+4. **Create todo list** from the remaining work items
+5. **Report readiness:**
+
+```
+Resumed from handoff: [title]
+
+Branch: [branch name]
+Phase: [current phase]
+
+Remaining work:
+1. [Next step]
+2. [Following step]
+
+Ready to continue. What should I focus on first?
+```
+
+## Rules
+
+- Read ALL key files mentioned in the handoff
+- Don't repeat completed work
+- If the handoff mentions open questions, raise them immediately
+- Trust the handoff's "What Was Done" section

package/.merlin-core/commands/session/run-process.md

@@ -0,0 +1,53 @@
+---
+description: Run a certified PROCESSO locally — autonomous start-to-stop (Constitution XIV)
+model: sonnet
+---
+
+# Run Process
+
+Execute a **certified** PROCESSO locally. Under Article XIV, a certified + signed process
+runs **start-to-finish without per-step approval** — its autonomous steps were pre-approved
+at certification time. The executor enforces the irreducible floor: ABSOLUTE-safety steps,
+non-autonomous steps, and any push whose secret scan fails will HALT for explicit approval.
+
+## When to Use
+
+- To run a recurring business process on demand
+- As the **rehearsal vehicle** for certification (run with dry-run before `/certify-process --rehearsed`)
+- To re-run a scheduled process manually
+
+## Usage
+
+```bash
+# Dry-run (default) — simulate every step's decision, execute nothing:
+node .merlin-core/tools/merlin-tools.js run-process <slug-or-path>
+
+# Live — execute autonomous steps start-to-stop:
+node .merlin-core/tools/merlin-tools.js run-process <slug-or-path> --live
+```
+
+## Behavior (the executor contract)
+
+1. **Refuses** any process that is not `status: certified`.
+2. **Refuses** if the step-list signature does not verify (file edited since certification →
+   re-certify required). This is the tamper guard.
+3. Per step, decides via the approval engine under a certification context:
+   - autonomous + non-absolute + valid signature → **runs free** (CERTIFIED stake, no prompt);
+   - `safety: absolute` → **halts** for explicit human approval (Article XI — never autonomous);
+   - `autonomous: false` → **halts** for approval (gated step);
+   - a `git push` step → **secret-scanned first**; a finding **blocks** the push (Article XIV-c).
+4. On a halt/block, the autonomous run **stops** at that step and reports
+   `halted-for-approval` (or `failed` for a secret block). Resume after resolving.
+5. Records `last_run_status` + `last_run_at` into the process (live runs only).
+
+## Safety
+
+- **Default is dry-run.** Always dry-run first to see the decision plan before `--live`.
+- ABSOLUTE actions and `secrets.expose` can never be auto-run — this command cannot
+  override the Article XI floor.
+
+## Constitution Compliance
+
+- **Article XIV (Certified Process Authority):** Permission-free execution is licensed only
+  by a valid certification signature; the gate moved to authoring time.
+- **Article XI (Absolute Safety Boundaries):** ABSOLUTE steps + failed secret scans hard-stop.