grimoire-framework 1.0.0

package/.grimoire/development/tasks/gotchas.md

@@ -0,0 +1,155 @@
+# Task: List Gotchas
+
+> **Command:** `*gotchas [options]`
+> **Agent:** @dev
+> **Story:** 9.4 - Gotchas Memory
+> **AC:** AC6
+
+---
+
+## Purpose
+
+List and search known gotchas (issues and workarounds) from the project's gotchas memory.
+
+---
+
+## Usage
+
+```bash
+*gotchas
+*gotchas --category {category}
+*gotchas --severity {severity}
+*gotchas --unresolved
+*gotchas search {query}
+```
+
+### Options
+
+| Option         | Default | Description                                  |
+| -------------- | ------- | -------------------------------------------- |
+| --category     | all     | Filter by category                           |
+| --severity     | all     | Filter by severity (info, warning, critical) |
+| --unresolved   | false   | Show only unresolved gotchas                 |
+| --stats        | false   | Show statistics only                         |
+| search {query} | -       | Search gotchas by keyword                    |
+
+---
+
+## Workflow
+
+```yaml
+steps:
+  - name: Load Gotchas
+    action: |
+      Load gotchas from .grimoire/gotchas.json via GotchasMemory
+
+  - name: Apply Filters
+    action: |
+      If --category: filter by category
+      If --severity: filter by severity
+      If --unresolved: filter out resolved gotchas
+      If search: filter by keyword match
+
+  - name: Display Results
+    action: |
+      For each gotcha, show:
+      - [SEVERITY] Title
+      - Category
+      - Description (truncated)
+      - Workaround (if exists)
+      - Related files (if any)
+      - Status (resolved/unresolved)
+
+      If --stats:
+        Show statistics instead of full list
+```
+
+---
+
+## Output Example
+
+### Default List
+
+```
+=== Gotchas (12 total, 10 unresolved) ===
+
+[CRITICAL] Protected files require full read
+  Category: build
+  Hook de read-protection bloqueia partial reads. Sempre usar Read sem limit/offset.
+  Workaround: Ler arquivo completo, depois filtrar no código
+  Files: **/CLAUDE.md, **/agents/*.md
+
+[WARNING] Zustand persist needs type annotation
+  Category: runtime
+  Without explicit type parameter and extra parentheses, TypeScript cannot infer...
+  Files: src/stores/*.ts
+
+[INFO] React useEffect cleanup for async operations
+  Category: runtime
+  Without cleanup, race conditions can occur when component unmounts...
+
+---
+Total: 12 | Critical: 1 | Warning: 8 | Info: 3
+```
+
+### With --stats
+
+```
+=== Gotchas Statistics ===
+
+Total: 12
+  - Unresolved: 10
+  - Resolved: 2
+
+By Category:
+  - build: 3
+  - test: 2
+  - lint: 1
+  - runtime: 4
+  - integration: 1
+  - security: 1
+
+By Severity:
+  - critical: 1
+  - warning: 8
+  - info: 3
+
+By Source:
+  - manual: 5
+  - auto_detected: 7
+```
+
+---
+
+## Categories
+
+| Category    | Description          | Keywords                      |
+| ----------- | -------------------- | ----------------------------- |
+| build       | Build/compile issues | webpack, vite, tsc, bundle    |
+| test        | Testing issues       | jest, vitest, mock, coverage  |
+| lint        | Linting/formatting   | eslint, prettier, stylelint   |
+| runtime     | Runtime errors       | TypeError, null, undefined    |
+| integration | API/DB issues        | fetch, cors, postgres, prisma |
+| security    | Security issues      | xss, csrf, auth, injection    |
+
+---
+
+## Integration
+
+- **Uses:** `GotchasMemory.listGotchas()`, `GotchasMemory.search()`
+- **Script:** `.grimoire/core/memory/gotchas-memory.js`
+- **Source:** `.grimoire/gotchas.json`
+
+---
+
+## Related Commands
+
+- `*gotcha {title}` - Add a new gotcha
+- `*gotcha-context` - Get relevant gotchas for current task
+- `*list-gotchas` - Legacy alias for this command
+
+---
+
+_Task file for Story 9.4 - Gotchas Memory_
+
+

package/.grimoire/development/tasks/health-check.yaml

@@ -0,0 +1,227 @@
+---
+# Health Check Task Definition
+# Story: HCS-2 - Health Check System Implementation
+# Version: 1.0.0
+
+name: health-check
+id: health-check
+version: "2.0"
+description: |
+  Run comprehensive health checks on your grimoire project.
+  Diagnoses configuration issues, environment problems, and provides
+  auto-fixing for common issues.
+
+category: development
+owner: devops
+
+# CLI integration
+command: "*health-check"
+aliases:
+  - "*hc"
+  - "*doctor"
+
+# Task parameters
+parameters:
+  - name: mode
+    type: string
+    default: "quick"
+    description: "Execution mode: 'quick' (<10s, critical/high only) or 'full' (<60s, all checks)"
+    options:
+      - quick
+      - full
+
+  - name: domain
+    type: string
+    default: "all"
+    description: "Domain to check: project, local, repository, deployment, services, or all"
+    options:
+      - all
+      - project
+      - local
+      - repository
+      - deployment
+      - services
+
+  - name: fix
+    type: boolean
+    default: true
+    description: "Enable auto-fixing for Tier 1 issues"
+
+  - name: fix-tier
+    type: number
+    default: 1
+    description: "Maximum tier for auto-fixing (1=silent, 2=prompted, 3=manual guide only)"
+    min: 1
+    max: 3
+
+  - name: output
+    type: string
+    default: "console"
+    description: "Output format"
+    options:
+      - console
+      - markdown
+      - json
+
+  - name: verbose
+    type: boolean
+    default: false
+    description: "Show all checks, not just issues"
+
+  - name: save
+    type: boolean
+    default: false
+    description: "Save report to .grimoire/reports/health-check-latest.json"
+
+# Execution steps
+steps:
+  - id: initialize
+    name: "Initialize Health Check"
+    action: log
+    params:
+      message: "🏥 Starting grimoire Health Check (mode: {{mode}})"
+
+  - id: run-checks
+    name: "Run Health Checks"
+    action: script
+    script: |
+      const { HealthCheck } = require('../../core/health-check');
+
+      const config = {
+        mode: '{{mode}}',
+        autoFix: {{fix}},
+        autoFixTier: {{fix-tier}},
+        output: {
+          format: '{{output}}',
+          verbose: {{verbose}},
+        },
+      };
+
+      const healthCheck = new HealthCheck(config);
+
+      const options = {
+        domain: '{{domain}}',
+      };
+
+      const results = await healthCheck.run(options);
+
+      // Display report
+      console.log(results.report);
+
+      // Save if requested
+      if ({{save}}) {
+        const fs = require('fs').promises;
+        const path = require('path');
+
+        const reportDir = path.join(process.cwd(), '.grimoire', 'reports');
+        await fs.mkdir(reportDir, { recursive: true });
+
+        const reportPath = path.join(reportDir, 'health-check-latest.json');
+        await fs.writeFile(reportPath, JSON.stringify(results, null, 2));
+
+        console.log(`\n📄 Report saved to: ${reportPath}`);
+      }
+
+      // Return summary for task output
+      return {
+        score: results.overall.score,
+        status: results.overall.status,
+        issues: results.overall.issuesCount,
+        autoFixed: results.autoFixed?.length || 0,
+      };
+
+  - id: summary
+    name: "Display Summary"
+    action: log
+    params:
+      message: |
+
+        Health Check Complete:
+        - Score: {{run-checks.score}}/100
+        - Status: {{run-checks.status}}
+        - Issues: {{run-checks.issues}}
+        - Auto-fixed: {{run-checks.autoFixed}}
+
+# Output schema
+output:
+  type: object
+  properties:
+    score:
+      type: number
+      description: "Overall health score (0-100)"
+    status:
+      type: string
+      description: "Health status: healthy, degraded, warning, critical"
+    issues:
+      type: number
+      description: "Number of issues found"
+    autoFixed:
+      type: number
+      description: "Number of issues auto-fixed"
+
+# Examples
+examples:
+  - name: "Quick check"
+    command: "*health-check"
+    description: "Run quick health check (critical and high severity)"
+
+  - name: "Full check"
+    command: "*health-check --mode=full"
+    description: "Run comprehensive health check"
+
+  - name: "Check specific domain"
+    command: "*health-check --domain=repository"
+    description: "Check only repository health"
+
+  - name: "With auto-fix confirmation"
+    command: "*health-check --fix-tier=2"
+    description: "Allow prompted auto-fixes"
+
+  - name: "Save JSON report"
+    command: "*health-check --output=json --save"
+    description: "Generate and save JSON report"
+
+  - name: "Verbose output"
+    command: "*health-check --verbose"
+    description: "Show all checks including passed ones"
+
+# Help text
+help: |
+  ## grimoire Health Check
+
+  Diagnoses issues in your grimoire project across 5 domains:
+
+  - **Project**: package.json, dependencies, framework config
+  - **Local**: Git, npm, IDE, disk space, memory, network
+  - **Repository**: Git status, branches, conflicts, lockfile
+  - **Deployment**: Environment files, CI/CD, Docker
+  - **Services**: MCP, GitHub CLI, Claude Code, APIs
+
+  ### Quick Start
+
+  ```bash
+  *health-check              # Quick check
+  *health-check --mode=full  # Full check
+  ```
+
+  ### Auto-Fixing
+
+  Issues are classified into 3 tiers:
+  - **Tier 1**: Auto-fixed silently (safe, reversible)
+  - **Tier 2**: Prompted for confirmation
+  - **Tier 3**: Manual guide provided
+
+  ### Output Formats
+
+  - `console`: Colorful terminal output
+  - `markdown`: GitHub-compatible markdown
+  - `json`: Machine-readable JSON
+
+  ### Examples
+
+  ```bash
+  *health-check --domain=repository --verbose
+  *health-check --fix-tier=2 --save
+  *hc --mode=full --output=markdown
+  ```
+

package/.grimoire/development/tasks/ids-governor.md

@@ -0,0 +1,96 @@
+# Task: IDS Governor Commands
+
+**Task ID:** ids-governor
+**Version:** 1.0
+**Purpose:** Execute IDS Framework Governor commands (*ids query, *ids health, *ids stats, *ids impact)
+**Agent:** @grimoire-master
+**Story:** IDS-7 (grimoire-master IDS Governor Integration)
+
+---
+
+## Overview
+
+This task handles the execution of IDS (Incremental Development System) commands through the FrameworkGovernor facade. All commands are advisory and non-blocking.
+
+### Available Commands
+
+| Command | Description | Arguments |
+|---------|-------------|-----------|
+| `*ids query {intent}` | Query registry for REUSE/ADAPT/CREATE recommendations | intent (required), --type (optional) |
+| `*ids health` | Registry health check | none |
+| `*ids stats` | Registry statistics (entity counts, health score) | --json (optional) |
+| `*ids impact {entity-id}` | Impact analysis for modifications | entity-id (required) |
+
+---
+
+## Execution Steps
+
+### *ids query {intent}
+
+1. Load FrameworkGovernor (RegistryLoader + DecisionEngine + RegistryUpdater)
+2. Call `governor.preCheck(intent, entityType)`
+3. Display formatted output using `FrameworkGovernor.formatPreCheckOutput(result)`
+4. If matches found, present options: [1] ADAPT existing [2] CREATE new [3] Skip
+5. Log decision
+
+### *ids health
+
+1. Load FrameworkGovernor
+2. Call `governor.healthCheck()`
+3. If RegistryHealer available: display full health report
+4. If RegistryHealer unavailable: display basic stats with degraded mode message
+5. Show entity count and registry loaded status
+
+### *ids stats
+
+1. Load FrameworkGovernor
+2. Call `governor.getStats()`
+3. Display formatted output using `FrameworkGovernor.formatStatsOutput(result)`
+4. Show: totalEntities, byType, byCategory, healthScore, healerAvailable
+
+### *ids impact {entity-id}
+
+1. Load FrameworkGovernor
+2. Call `governor.impactAnalysis(entityId)`
+3. Display formatted output using `FrameworkGovernor.formatImpactOutput(result)`
+4. Show: directConsumers, indirectConsumers, riskLevel, adaptabilityScore
+5. If HIGH/CRITICAL risk: display warning
+
+---
+
+## CLI Equivalents
+
+All commands are also available via CLI:
+
+```bash
+node bin/grimoire-ids.js ids:check "your intent" --type task
+node bin/grimoire-ids.js ids:impact create-doc
+node bin/grimoire-ids.js ids:stats --json
+node bin/grimoire-ids.js ids:register path/to/file.md
+```
+
+---
+
+## Dependencies
+
+- `.grimoire/core/ids/framework-governor.js` — FrameworkGovernor class
+- `.grimoire/core/ids/registry-loader.js` — RegistryLoader
+- `.grimoire/core/ids/incremental-decision-engine.js` — DecisionEngine
+- `.grimoire/core/ids/registry-updater.js` — RegistryUpdater
+- `.grimoire/core/ids/registry-healer.js` — RegistryHealer (optional, IDS-4a)
+
+---
+
+## Error Handling
+
+All commands apply graceful degradation:
+- Timeout: 2 seconds (warn and proceed)
+- Missing healer: Show degraded mode message
+- Registry load failure: Display error with recovery suggestion
+- All operations are advisory and never block the user
+
+---
+
+*IDS-7 | Created 2026-02-10 by @dev (Dex)*
+
+

package/.grimoire/development/tasks/ids-health.md

@@ -0,0 +1,91 @@
+# IDS Registry Health Check Task
+
+## Purpose
+
+Run a self-healing health check on the IDS entity registry to detect and auto-fix data integrity issues.
+
+---
+
+## Pre-Conditions
+
+- Entity registry exists at `.grimoire/data/entity-registry.yaml`
+- IDS modules are installed (IDS-1, IDS-3, IDS-4a)
+
+---
+
+## Execution
+
+### Step 1: Run Health Check
+
+```bash
+node bin/grimoire-ids.js ids:health
+```
+
+Review the output for any detected issues.
+
+### Step 2: Auto-Heal (Optional)
+
+If auto-fixable issues are detected, run with `--fix`:
+
+```bash
+node bin/grimoire-ids.js ids:health --fix
+```
+
+This will:
+- Create a backup of the registry before changes
+- Auto-fix issues: checksum mismatches, orphaned references, missing keywords, stale timestamps
+- Skip non-auto-healable issues (missing files) and emit warnings
+- Log all healing actions to `.grimoire/data/registry-healing-log.jsonl`
+
+### Step 3: JSON Output (Machine-Readable)
+
+```bash
+node bin/grimoire-ids.js ids:health --json
+node bin/grimoire-ids.js ids:health --fix --json
+```
+
+### Step 4: Review Warnings
+
+If critical issues are found (missing files), the command exits with code 1.
+Review the warnings and take manual action as suggested.
+
+---
+
+## Post-Conditions
+
+- Registry integrity issues are detected and reported
+- Auto-healable issues are fixed (with --fix)
+- Non-auto-healable issues generate warnings with suggested actions
+- Healing actions are logged for audit trail
+- Registry backup is created before any modifications
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | No critical issues |
+| 1 | Critical issues found (e.g., missing files) |
+
+---
+
+## Programmatic Usage
+
+```javascript
+const { RegistryHealer } = require('.grimoire/core/ids/registry-healer');
+
+const healer = new RegistryHealer();
+const healthResult = healer.runHealthCheck();
+
+if (healthResult.summary.total > 0) {
+  const healResult = healer.heal(healthResult.issues, { autoOnly: true });
+  console.log(`Healed: ${healResult.healed.length}, Skipped: ${healResult.skipped.length}`);
+}
+```
+
+---
+
+*Story IDS-4a | Self-Healing Data Integrity*
+
+

package/.grimoire/development/tasks/ids-query.md

@@ -0,0 +1,156 @@
+---
+
+## Task Definition (grimoire Task Format V1.0)
+
+```yaml
+task: idsQuery()
+responsável: Any Agent
+responsavel_type: Agente
+atomic_layer: Molecule
+
+**Entrada:**
+- campo: intent
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Non-empty string describing what is needed
+
+- campo: context
+  tipo: object
+  origem: User Input
+  obrigatório: false
+  validação: Optional filters (type, category)
+
+- campo: format
+  tipo: string
+  origem: User Input
+  obrigatório: false
+  validação: "json" or "text" (default: text)
+
+**Saída:**
+- campo: analysis_result
+  tipo: object
+  destino: Return value
+  persistido: false
+
+- campo: decision
+  tipo: string
+  destino: Return value
+  persistido: false
+```
+
+---
+
+## Pre-Conditions
+
+```yaml
+pre-conditions:
+  - [ ] Entity Registry exists at .grimoire/data/entity-registry.yaml
+    tipo: pre-condition
+    blocker: false
+    validação: |
+      If missing, engine returns CREATE with empty registry rationale
+    error_message: "Registry not found — CREATE decisions will be recommended"
+```
+
+---
+
+## Purpose
+
+Query the IDS (Incremental Development System) Entity Registry to find existing artifacts that match a given intent. Returns REUSE, ADAPT, or CREATE recommendations based on semantic matching.
+
+**Constitution Reference:** Article IV-A — REUSE > ADAPT > CREATE
+
+---
+
+## Usage
+
+### CLI Usage
+
+```bash
+# Basic query
+node bin/grimoire-ids.js ids:query "validate story drafts"
+
+# With JSON output
+node bin/grimoire-ids.js ids:query "template rendering engine" --json
+
+# Filter by type
+node bin/grimoire-ids.js ids:query "database migration" --type script
+
+# Filter by category
+node bin/grimoire-ids.js ids:query "agent persona" --category agents
+```
+
+### Programmatic Usage (Agent Context)
+
+```javascript
+const path = require('path');
+const { RegistryLoader } = require(path.resolve('.grimoire/core/ids/registry-loader'));
+const { IncrementalDecisionEngine } = require(path.resolve('.grimoire/core/ids/incremental-decision-engine'));
+
+const loader = new RegistryLoader();
+loader.load();
+
+const engine = new IncrementalDecisionEngine(loader);
+const result = engine.analyze('validate story drafts before implementation');
+
+// result.summary.decision → 'REUSE' | 'ADAPT' | 'CREATE'
+// result.recommendations → ranked list with rationale
+// result.justification → CREATE justification (if applicable)
+```
+
+---
+
+## Decision Interpretation
+
+| Decision | Meaning | Action |
+|----------|---------|--------|
+| **REUSE** | >=90% relevance match | Use the existing artifact directly |
+| **ADAPT** | 60-89% match + adaptable | Modify existing artifact (changes <30%) |
+| **CREATE** | No suitable match | Create new artifact with justification |
+
+---
+
+## Output Structure
+
+```yaml
+intent: "validate story drafts"
+recommendations:
+  - entityId: "validate-story"
+    decision: "REUSE"
+    confidence: "high"
+    relevanceScore: 0.95
+    rationale: "Strong match..."
+summary:
+  totalEntities: 474
+  matchesFound: 3
+  decision: "REUSE"
+  confidence: "high"
+rationale: "Found 3 matches above threshold..."
+```
+
+---
+
+## Related Commands
+
+- `grimoire ids:create-review` — Review CREATE decisions for 30-day assessment
+- `*develop` — Development workflow (uses IDS recommendations at G4 gate)
+
+---
+
+## Metadata
+
+```yaml
+story: IDS-2
+version: 1.0.0
+dependencies:
+  - registry-loader.js (IDS-1)
+  - incremental-decision-engine.js (IDS-2)
+tags:
+  - ids
+  - registry
+  - decision-engine
+updated_at: 2026-02-08
+```
+
+