@caoscompanybr/merlin 3.5.0

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

@@ -0,0 +1,155 @@
+---
+description: Capture a domain-specific learning for cross-agent knowledge sharing
+model: sonnet
+---
+
+# Capture Learning
+
+Save a domain-specific insight as a persistent learning document. Learnings are
+small, actionable knowledge points that agents discover while working — gotchas,
+patterns, conventions, constraints, and workarounds. They are indexed and surfaced
+to other agents working in the same area of action via the Alkimia memory system.
+
+## When to Use
+
+- An agent discovers a non-obvious behavior in an API, library, or system
+- A pattern or convention is established that future agents should follow
+- A constraint or hard limit is found that affects implementation decisions
+- A workaround is applied that other agents need to know about
+- A gotcha or pitfall is hit that would waste time if re-discovered
+- The user explicitly says "save this as a learning" or "remember this"
+
+## What Qualifies as a Learning (vs Other Types)
+
+| If it's...                                  | Use          |
+| ------------------------------------------- | ------------ |
+| A small, reusable domain fact               | **Learning** |
+| A session state snapshot                    | Handoff      |
+| A multi-session goal                        | Objective    |
+| A time-bound action item                    | Reminder     |
+| A major architectural choice with rationale | Decision     |
+| A deep exploratory analysis                 | Research     |
+
+## Process
+
+1. **Extract the insight:**
+   - Identify the specific knowledge point from the conversation
+   - Distill it to a clear, concise statement (1-3 sentences)
+   - Avoid vague or generic observations — be precise and actionable
+
+2. **Determine metadata (critical for retrieval):**
+   - **domain:** The broad area of action (database, auth, api, build, frontend, deployment, infra, testing, etc.)
+   - **category:** What kind of learning?
+     - `gotcha` — trap, pitfall, unexpected behavior
+     - `pattern` — reusable approach that works well
+     - `convention` — team/project norm to follow
+     - `constraint` — hard limit or system boundary
+     - `insight` — deeper understanding of how something works
+     - `workaround` — temporary fix or bypass
+   - **confidence:** How certain?
+     - `observed` — seen once (default)
+     - `verified` — confirmed across multiple instances
+     - `assumed` — inferred but not yet tested
+   - **ttl:** Retention (v3.4)
+     - `permanent` — 🔒 strategic: philosophy, architecture, durable conventions (default; never expires)
+     - `30d` — ⏳ tactical: a bug/workaround/state fact that goes stale; auto-expires after 30 days
+   - **tags:** Granular keywords (technologies, APIs, file names, concepts)
+   - **applies_to:** Specific files, modules, or areas this is most relevant to
+   - **project:** Which project (if multi-project Merlin install)
+
+3. **Check for superseded learnings:**
+   - Scan `thoughts/shared/learnings/` for existing learnings in the same domain
+   - If this learning updates or contradicts an older one, set `supersedes` to the older file path
+
+4. **Save the learning:**
+   - Path: `thoughts/shared/learnings/YYYY-MM-DD-{slug}.md`
+   - Use today's date and a descriptive kebab-case slug
+   - Slug should include the domain for easy scanning (e.g., `api-pagination-limit`, `build-env-local-required`)
+
+5. **Rebuild the thoughts index** after saving:
+
+   ```bash
+   node .merlin-core/tools/merlin-tools.js index
+   ```
+
+6. **Confirm creation:**
+   - Show the saved path
+   - Show the domain and tags assigned
+   - Explain that agents working in the same area will automatically see this learning
+
+## Template
+
+```markdown
+---
+title: "[Concise, specific title]"
+date: YYYY-MM-DD
+tags: [specific, granular, keywords]
+domain: "[area of action]"
+category: gotcha
+confidence: observed
+ttl: permanent
+source_agent: dev
+project: "[project name]"
+applies_to: [src/specific/path, module-name]
+supersedes: ""
+---
+
+# Learning: [Title]
+
+## Insight
+
+[The specific knowledge point — clear, concise, actionable. 1-3 sentences max.]
+
+## Context
+
+[When and how this was discovered. What was happening that led to this insight.]
+
+## Applies To
+
+- **Files/Modules:** [specific paths or module names]
+- **When:** [under what conditions this is relevant]
+- **Impact:** [what goes wrong if this is ignored]
+
+## Related
+
+- Plan: [link to plan if applicable]
+- Handoff: [link to handoff if applicable]
+```
+
+## Examples
+
+### Gotcha
+
+```
+title: "Electron getUserMedia requires secure context — data URIs fail silently"
+domain: electron
+category: gotcha
+tags: [electron, getUserMedia, mediaDevices, secure-context, data-uri]
+applies_to: [src/main/capture/]
+```
+
+### Convention
+
+```
+title: "React components use composition over inheritance — no class components"
+domain: frontend
+category: convention
+tags: [react, components, composition, hooks]
+applies_to: [src/renderer/components/]
+```
+
+### Constraint
+
+```
+title: "GitHub API rate limit: 5000 requests/hour with token, 60 without"
+domain: api
+category: constraint
+tags: [github, api, rate-limit, authentication]
+applies_to: [src/services/github/]
+```
+
+## Constitution Compliance
+
+- **Article VIII (Craftsmanship):** Learnings preserve domain knowledge across sessions and agents
+- **Article III (Spec-Driven):** Learnings trace to real observations, not invention
+- **Article IV (No Invention):** Only capture what was actually discovered, never speculate

package/.merlin-core/commands/session/check-objectives.md

@@ -0,0 +1,85 @@
+---
+description: Review active objectives and reminders, update progress
+model: sonnet
+---
+
+# Check Objectives
+
+Review all active reminders and objectives, update progress, and flag items
+that need attention. This command provides a snapshot of ongoing goals and
+their current status.
+
+## When to Use
+
+- At the start of a new session to understand what's in flight
+- Periodically during long sessions to stay aligned
+- Before creating a handoff to capture current objective state
+- When resuming from a handoff to re-establish context
+
+## Process
+
+### Step 1: Scan Reminders
+
+1. Read all files in `thoughts/shared/reminders/`
+2. Filter to status = pending or acknowledged (skip completed/expired)
+3. Check if any `due_date` has passed — flag as OVERDUE
+4. Sort by priority (critical > high > medium > low), then by due_date
+
+### Step 2: Scan Objectives
+
+1. Read all files in `thoughts/shared/objectives/`
+2. Filter to status = active (skip draft/paused/achieved/abandoned)
+3. For each objective, evaluate progress against success criteria
+4. Check if any `deadline` has passed — flag as OVERDUE
+5. Sort by deadline proximity
+
+### Step 3: Evaluate Progress
+
+For each active objective:
+
+- Count how many success criteria checkboxes are checked (- [x])
+- Calculate progress_pct from checked/total ratio
+- Update progress_pct in the objective frontmatter if it changed
+
+### Step 4: Present Summary
+
+```markdown
+## Objectives & Reminders Status
+
+### Active Objectives
+
+| Objective | Scope   | Progress | Deadline | Status                       |
+| --------- | ------- | -------- | -------- | ---------------------------- |
+| [title]   | [scope] | [pct]%   | [date]   | On Track / At Risk / Overdue |
+
+### Active Reminders
+
+| Reminder | Priority   | Due    | Owner    | Status            |
+| -------- | ---------- | ------ | -------- | ----------------- |
+| [title]  | [priority] | [date] | @[agent] | Pending / Overdue |
+
+### Recommendations
+
+- [Action items based on current state]
+```
+
+### Step 5: Rebuild Index (if anything changed)
+
+If any objective's `progress_pct` was updated or any reminder status was changed:
+
+```bash
+node .merlin-core/tools/merlin-tools.js index
+```
+
+### Step 6: Offer Actions
+
+After presenting the summary, offer:
+
+- Update an objective's progress or status
+- Mark a reminder as completed or expired
+- Create a new reminder or objective if gaps are identified
+
+## Constitution Compliance
+
+- **Article VIII (Craftsmanship):** Regular check-ins maintain goal awareness
+- **Article III (Spec-Driven):** Objectives connect to the plan-driven workflow

package/.merlin-core/commands/session/conclude.md

@@ -0,0 +1,125 @@
+---
+description: Conclude a thought (handoff, plan, reminder, objective) and optionally capture learnings
+model: sonnet
+---
+
+# Conclude Thought
+
+Mark a thought document as concluded/completed, removing it from active context
+injection while preserving it in the repository. This is a lifecycle primitive
+used by `/fast-start` and available standalone.
+
+## When to Use
+
+- A plan has been fully implemented or is no longer relevant
+- A handoff has been consumed and the session context is no longer needed
+- A reminder has been addressed or is no longer applicable
+- An objective has been achieved or abandoned
+- During `/fast-start` interactive review when the user confirms an item is done
+- Proactively when you notice a thought is stale during normal work
+
+## What This Command Does
+
+1. Adds `status: concluded` (or appropriate terminal status) to the YAML frontmatter
+2. Adds `concluded_date: YYYY-MM-DD` to track when it was closed
+3. Optionally triggers `/capture-learning` to extract insights before closing
+4. The ThoughtsProvider automatically filters out concluded items from context injection
+
+## Process
+
+1. **Identify the thought to conclude:**
+   - Accept a file path, citation ID, or description
+   - If ambiguous, list matching thoughts and ask the user to confirm
+   - Read the file and display its title, date, and summary
+
+2. **Verify it's not already concluded:**
+   - Check `status` field in frontmatter
+   - If already concluded/achieved/abandoned/completed/expired, inform the user and stop
+   - If no frontmatter exists, add the required fields
+
+3. **Determine the appropriate terminal status:**
+
+   | Thought Type | Terminal Statuses            | Default    |
+   | ------------ | ---------------------------- | ---------- |
+   | handoff      | concluded                    | concluded  |
+   | plan         | concluded                    | concluded  |
+   | reminder     | completed, expired           | completed  |
+   | objective    | achieved, abandoned          | achieved   |
+   | research     | concluded                    | concluded  |
+   | decision     | concluded                    | concluded  |
+   | learning     | _(learnings don't conclude)_ | —          |
+   | process      | deprecated                   | deprecated |
+   - Learnings are permanent knowledge — they don't get concluded. If the user
+     wants to retire a learning, suggest using `supersedes` in a new learning instead.
+   - Processes are permanent operating procedures (like learnings). They leave the
+     active set only by being `deprecated` — retire a process when it no longer
+     reflects how the business actually works.
+
+4. **Ask about learning capture:**
+   - Before concluding, ask: "Any insights or learnings to capture from this before closing?"
+   - If yes, guide through the `/capture-learning` flow
+   - If no, proceed to conclusion
+
+5. **Update the frontmatter:**
+   - Add or update `status` to the determined terminal status
+   - Add `concluded_date: YYYY-MM-DD` with today's date
+   - Preserve all existing frontmatter fields
+
+6. **Rebuild the thoughts index** after updating:
+
+   ```bash
+   node .merlin-core/tools/merlin-tools.js index
+   ```
+
+   This keeps INDEX.json fresh so the concluded item is immediately filtered out of active context.
+
+7. **Confirm the conclusion:**
+   - Show the updated file path
+   - Confirm the status change
+   - Note that this thought will no longer appear in context injection
+
+## Examples
+
+### Concluding a handoff
+
+```
+User: /conclude the design intelligence handoff
+Agent: Found: thoughts/shared/handoffs/2026-03-06-design-intelligence-upgrade.md
+       Title: "Design Intelligence Upgrade"
+       Date: 2026-03-06
+
+       Any insights or learnings to capture before closing?
+User: No, it's all captured already
+Agent: Updated status to "concluded" with concluded_date: 2026-03-09.
+       This handoff will no longer appear in session context.
+```
+
+### Concluding a plan
+
+```
+User: /conclude
+Agent: Which thought would you like to conclude? Active items:
+       1. plans/2026-03-08-fast-start-system.md — "Fast-Start System"
+       2. handoffs/2026-03-07-design-intelligence.md — "Design Intelligence"
+User: 1
+Agent: Any insights or learnings to capture before closing?
+User: Yes — the fast-start pattern of scanning thoughts is reusable
+Agent: [Runs /capture-learning flow]
+       ...
+       Plan concluded with status: concluded, concluded_date: 2026-03-09.
+```
+
+## Batch Mode
+
+When called from `/fast-start` interactive review, this command operates in
+streamlined mode:
+
+- Skip the identification step (thought is already selected)
+- Keep the learning capture prompt (important for knowledge preservation)
+- Use shorter confirmations
+
+## Constitution Compliance
+
+- **Article VIII (Craftsmanship):** Proper lifecycle management preserves institutional knowledge
+- **Article III (Spec-Driven):** Concluding plans marks the completion of the SDD cycle
+- **Article VII (Human Gates):** Always asks user before concluding — never auto-concludes

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

@@ -0,0 +1,88 @@
+---
+description: Create a handoff document for context transfer between sessions
+model: opus
+---
+
+# Create Handoff
+
+Create a handoff document that captures the current session state for seamless continuation in a new context window.
+
+## When to Use
+
+- Context window is getting large (DEPLETED/CRITICAL bracket)
+- Switching between development phases
+- Handing work to a different agent or developer
+- End of work session
+
+## Process
+
+1. **Analyze current state:**
+   - Review TodoWrite for in-progress items
+   - Check git status for uncommitted changes
+   - Identify the current phase and next steps
+
+2. **Create handoff document:**
+
+Save to `thoughts/shared/handoffs/` with this format:
+
+```markdown
+---
+date: [ISO 8601]
+from: [current agent/session]
+status: in_progress
+branch: [current git branch]
+---
+
+# Handoff: [Brief Description]
+
+## Current State
+
+- Working on: [task/story]
+- Phase: [which phase of the plan]
+- Branch: [git branch]
+
+## What Was Done
+
+- [Completed item 1]
+- [Completed item 2]
+
+## Key Decisions
+
+| Decision     | Rationale         | Alternatives Rejected              |
+| ------------ | ----------------- | ---------------------------------- |
+| [Decision 1] | [Why this choice] | [What was considered but rejected] |
+
+## What's Next
+
+1. [Next immediate step]
+2. [Following step]
+
+## Important Context
+
+- [Key decision made and why]
+- [Gotcha or pitfall to watch for]
+- [Dependency or blocker]
+
+## Key Files
+
+| File         | Status   | Notes          |
+| ------------ | -------- | -------------- |
+| path/to/file | modified | [what changed] |
+
+## Open Questions
+
+- [Question that needs resolution]
+```
+
+3. **Present the handoff path** to the user:
+
+```
+Handoff saved to: thoughts/shared/handoffs/[filename].md
+To resume: /resume-handoff thoughts/shared/handoffs/[filename].md
+```
+
+4. **Rebuild the thoughts index** after saving:
+   ```bash
+   node .merlin-core/tools/merlin-tools.js index
+   ```
+   This keeps INDEX.json fresh so `/fast-start` and context injection see the new handoff immediately.

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

@@ -0,0 +1,111 @@
+---
+description: Create a cross-session objective with trackable success criteria
+model: sonnet
+---
+
+# Create Objective
+
+Create an objective that tracks a goal across multiple sessions. Objectives
+have explicit success criteria, progress tracking, and deadlines. They persist
+in `thoughts/shared/objectives/` and are surfaced via the Alkimia context engine.
+
+## When to Use
+
+- Starting a multi-session project or feature
+- Defining sprint or team goals
+- Tracking progress on a long-running initiative
+- Establishing measurable targets for a body of work
+
+## Process
+
+1. **Define the objective:**
+   - Title (what we're trying to achieve)
+   - Scope: session | sprint | project | team
+   - Deadline (when this should be achieved by)
+   - Owner (agent or 'team')
+
+2. **Define success criteria (2-5 items):**
+   - Each criterion should be measurable and verifiable
+   - Include both automated checks and manual verification where applicable
+   - Phrase as "X is true" statements, not tasks
+
+3. **Link to plans:**
+   - If implementation plans exist, link them via `linked_plans`
+   - This connects objectives to the spec-driven workflow
+
+4. **Save the objective:**
+   - Path: `thoughts/shared/objectives/YYYY-MM-DD-{slug}.md`
+   - Initial progress_pct: 0
+
+5. **Rebuild the thoughts index** after saving:
+
+   ```bash
+   node .merlin-core/tools/merlin-tools.js index
+   ```
+
+6. **Confirm creation:**
+   - Show the saved path
+   - List the success criteria for user verification
+
+## Template
+
+```markdown
+---
+title: "[What we're trying to achieve]"
+date: YYYY-MM-DD
+tags: [relevant, tags]
+scope: project
+status: active
+owner: team
+deadline: YYYY-MM-DD
+success_criteria:
+  - "Criterion 1 is met"
+  - "Criterion 2 is verified"
+  - "Criterion 3 passes"
+linked_plans: []
+progress_pct: 0
+---
+
+# Objective: [Title]
+
+## Overview
+
+[2-3 sentences describing the goal and why it matters]
+
+## Success Criteria
+
+- [ ] [Criterion 1] — [how to verify]
+- [ ] [Criterion 2] — [how to verify]
+- [ ] [Criterion 3] — [how to verify]
+
+## Current Progress
+
+Progress: 0%
+
+### Completed
+
+(none yet)
+
+### In Progress
+
+(none yet)
+
+### Blocked
+
+(none)
+
+## Related Plans
+
+- [Link to plan if applicable]
+
+## Next Steps
+
+1. [First action toward this objective]
+2. [Second action]
+```
+
+## Constitution Compliance
+
+- **Article VIII (Craftsmanship):** Objectives provide the "why" that keeps agents focused across sessions
+- **Article V (Quality):** Success criteria enforce measurable quality standards
+- **Article III (Spec-Driven):** Objectives link to plans for full traceability

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

@@ -0,0 +1,105 @@
+---
+description: Create a PROCESSO — a certifiable business process (runbook + trigger + checklist)
+model: sonnet
+---
+
+# Create Process
+
+Create a **PROCESSO**: a recurring business process captured as a unified artifact —
+an executable runbook, a trigger/schedule, and a checklist, all in one file. Processes
+persist in `thoughts/shared/processes/` and are surfaced via the Alkimia context engine
+and `/recall-processes`.
+
+A process is **deliberately bureaucratic to create**: every step must be classified by
+safety, and the process only becomes trustworthy after the `/certify-process` pipeline
+(`/tdd` rehearsal + `/check` + human sign-off). This command produces a **`status: draft`**
+process — creation only. Certification and execution are separate, gated steps
+(Constitution XIV).
+
+## When to Use
+
+- A task the business runs repeatedly the same way (release, onboarding, weekly review,
+  content pipeline, backup, audit)
+- Something you want an agent to eventually run autonomously, start-to-finish
+- Codifying tribal knowledge into a repeatable, verifiable procedure
+
+## Process
+
+1. **Define the process header:**
+   - Title (what the process accomplishes)
+   - Owner (agent or 'team'), project, tags
+
+2. **Define the trigger (FACET 2):**
+   - `mode`: `manual` (run on demand), `scheduled` (cron expr + tz), or `event`
+   - For `scheduled`, capture a 5-field cron expression and timezone
+
+3. **Define the steps (FACET 1 — the runbook):** for EACH step, capture:
+   - `id` + `description` (and a concrete `command` where applicable)
+   - **`safety`** — `low` | `medium` | `high` | `absolute`. This is mandatory and is the
+     heart of the bureaucracy. Be honest: anything that writes outside the repo, pushes,
+     deploys, or spends money is at least `high`; anything matching an Article XI ABSOLUTE
+     action (recursive delete, force-push main, exposing secrets, dropping prod DB) is
+     `absolute`.
+   - `autonomous` — may an agent run this without asking? **MUST be `false` when
+     `safety: absolute`** (the certification gate will reject otherwise).
+   - `expected_outcome` — what the rehearsal will assert
+   - `on_failure` — `halt` | `retry` | `skip` | `alert` (default `halt`)
+
+4. **Define success criteria (FACET 3):** measurable "X is true" statements describing the
+   process's end-state. These become the rehearsal assertion at certification.
+
+5. **Save the process:**
+   - Path: `thoughts/shared/processes/YYYY-MM-DD-{slug}.md`
+   - Initial `status: draft` (NEVER hand-write `certified` — only `/certify-process` may)
+
+6. **Validate the draft:**
+
+   ```bash
+   node .merlin-core/tools/merlin-tools.js validate process thoughts/shared/processes/YYYY-MM-DD-{slug}.md
+   ```
+
+7. **Rebuild the thoughts index:**
+
+   ```bash
+   node .merlin-core/tools/merlin-tools.js index
+   ```
+
+8. **Confirm + point at next step:**
+   - Show the saved path and the step/safety summary
+   - Tell the user the next step is `/certify-process` before it can run autonomously
+
+## Template
+
+> **Format (important):** Merlin's frontmatter parser is naive — keep frontmatter FLAT
+> (scalars + inline `tags` array only). The structured runbook (`steps` + `success_criteria`)
+> lives in a fenced `json` block in the body, which `/certify-process` and the executor parse.
+> Do NOT put `steps:` or YAML block-lists in the frontmatter.
+
+**1 — Flat frontmatter** (between the `---` delimiters):
+
+- `title` (string ≥5 chars), `date` (YYYY-MM-DD), `project`, `owner`, `tags: [a, b]`
+- `status: draft` (never hand-write `certified`)
+- `trigger_mode: manual | scheduled | event`; if scheduled add `schedule: "0 9 * * 1"` + `tz: America/Sao_Paulo`
+
+**2 — Body** (after the frontmatter): a `## Purpose` section, then a `## Definition` section
+containing one fenced `json` block — the canonical machine-readable runbook:
+
+- `success_criteria`: array of "X is true" end-state strings (≥1)
+- `steps`: array of objects, each with `id`, `description`, optional `command`,
+  `safety` (`low|medium|high|absolute`), `autonomous` (boolean; MUST be `false` when
+  `safety` is `absolute`), `expected_outcome`, `on_failure` (`halt|retry|skip|alert`)
+
+Then a human `## Runbook / Checklist` (one `- [ ]` per step) and a `## Notes` section
+(edge cases, idempotency, rollback).
+
+See the worked reference file `thoughts/shared/processes/2026-05-01-weekly-thoughts-hygiene.md`
+for the exact layout.
+
+## Constitution Compliance
+
+- **Article XIV (Certified Process Authority):** This command only DRAFTS. Permission-free
+  execution requires `/certify-process` (signature + `/tdd` + human sign-off) first.
+- **Article XI (Absolute Safety Boundaries):** `absolute`-safety steps can never be
+  `autonomous`; they always halt for explicit human approval at run time.
+- **Article III (Spec-Driven):** A process is a spec for repeatable work — research/plan first.
+- **Article V (Quality):** Success criteria are the measurable end-state the rehearsal proves.