create-genia-os 2.4.0 → 3.0.0

package/template/.aiox-core/development/tasks/gotcha.md

@@ -0,0 +1,136 @@
+# Task: Add Gotcha
+
+> **Command:** `*gotcha {title} - {description}`
+> **Agent:** @dev
+> **Story:** 9.4 - Gotchas Memory
+> **AC:** AC5
+
+---
+
+## Purpose
+
+Add a gotcha (known issue/workaround) manually to the project's gotchas memory.
+
+---
+
+## Usage
+
+```bash
+*gotcha {title}
+*gotcha {title} - {description}
+*gotcha {title} --category {category} --severity {severity}
+```
+
+### Arguments
+
+| Argument    | Required | Description                        |
+| ----------- | -------- | ---------------------------------- |
+| title       | Yes      | Short title for the gotcha         |
+| description | No       | Detailed description (after " - ") |
+
+### Options
+
+| Option       | Default | Description                                                 |
+| ------------ | ------- | ----------------------------------------------------------- |
+| --category   | auto    | Category: build, test, lint, runtime, integration, security |
+| --severity   | warning | Severity: info, warning, critical                           |
+| --workaround | -       | Solution or workaround text                                 |
+| --files      | -       | Comma-separated list of related files                       |
+
+---
+
+## Workflow
+
+```yaml
+steps:
+  - name: Parse Input
+    action: |
+      1. Extract title from input
+      2. Extract description if provided (after " - ")
+      3. Parse any flags (--category, --severity, etc.)
+    validates:
+      - Title is not empty
+
+  - name: Auto-detect Category
+    action: |
+      If category not provided, analyze title and description
+      to detect category based on keywords:
+      - build: build, compile, webpack, vite, etc.
+      - test: test, jest, vitest, mock, etc.
+      - lint: lint, eslint, prettier, etc.
+      - runtime: TypeError, null, undefined, crash, etc.
+      - integration: api, http, database, etc.
+      - security: xss, csrf, auth, etc.
+
+  - name: Create Gotcha
+    action: |
+      Use GotchasMemory.addGotcha() to create:
+      {
+        title: parsed title,
+        description: parsed description,
+        category: detected or provided,
+        severity: provided or "warning",
+        workaround: provided or null,
+        relatedFiles: provided or []
+      }
+
+  - name: Confirm Creation
+    action: |
+      Display:
+      - Gotcha ID
+      - Title
+      - Category (detected or provided)
+      - Severity
+```
+
+---
+
+## Output Example
+
+```
+Added gotcha: gotcha-lxyz123-abc456
+
+  Title: Always check fetch response.ok
+  Category: integration (auto-detected)
+  Severity: warning
+
+  This gotcha will be shown when working on related tasks.
+```
+
+---
+
+## Examples
+
+```bash
+# Simple
+*gotcha Always check fetch response.ok
+
+# With description
+*gotcha Zustand persist needs type annotation - Without explicit type, TypeScript cannot infer store type
+
+# With all options
+*gotcha Protected files need full read --category build --severity critical --workaround "Read without limit/offset"
+
+# With related files
+*gotcha API endpoint CORS issue --files "src/api/client.ts,src/lib/fetch.ts"
+```
+
+---
+
+## Integration
+
+- **Uses:** `GotchasMemory.addGotcha()`
+- **Script:** `.aiox-core/core/memory/gotchas-memory.js`
+- **Outputs:** `.aiox/gotchas.json`, `.aiox/gotchas.md`
+
+---
+
+## Related Commands
+
+- `*gotchas` - List all gotchas
+- `*gotcha-context` - Get relevant gotchas for current task
+- `*list-gotchas` - Legacy command (same as \*gotchas)
+
+---
+
+_Task file for Story 9.4 - Gotchas Memory_

package/template/.aiox-core/development/tasks/gotchas.md

@@ -0,0 +1,153 @@
+# 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 .aiox/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:** `.aiox-core/core/memory/gotchas-memory.js`
+- **Source:** `.aiox/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/template/.aiox-core/development/tasks/health-check.yaml

@@ -0,0 +1,265 @@
+---
+# Health Check Task Definition
+# Story: INS-4.8 - Unify Health-Check + Doctor v2
+# Version: 3.0.0 — Delegates to `aiox doctor --json` (unified)
+
+name: health-check
+id: health-check
+version: "3.0"
+description: |
+  Unified health diagnostic for AIOX projects.
+  Invokes `aiox doctor --json` internally via Bash tool and adds governance
+  interpretation with Constitution context and remediation guidance.
+
+  NOTE: This task delegates ALL check logic to `aiox doctor` (15 checks).
+  It does NOT have its own list of health checks — single source of truth.
+
+category: development
+owner: devops
+
+# CLI integration
+command: "*health-check"
+aliases:
+  - "*hc"
+# NOTE: *doctor alias REMOVED (INS-4.8) to avoid confusion with CLI `aiox doctor`
+
+# Task parameters
+parameters:
+  - name: fix
+    type: boolean
+    default: false
+    description: "Pass --fix to aiox doctor for auto-remediation"
+
+  - name: verbose
+    type: boolean
+    default: false
+    description: "Show all checks including passed ones"
+
+# Execution instructions
+instructions: |
+  ## How to Execute This Task
+
+  This task is executed by an agent using Claude Code native tools (Bash, Read).
+  It does NOT run a script — it provides instructions for the agent to follow.
+
+  ### Step 1: Run aiox doctor --json
+
+  Use the Bash tool to run:
+
+  ```bash
+  npx aiox-core doctor --json
+  ```
+
+  If `--fix` was requested, run instead:
+
+  ```bash
+  npx aiox-core doctor --json --fix
+  ```
+
+  NOTE: Always use `npx aiox-core` (not `node bin/aiox.js`) — this works in both
+  framework-dev mode (resolves local bin) and project-dev/brownfield mode
+  (resolves from node_modules/.bin/).
+
+  Capture the JSON output.
+
+  ### Step 2: Parse JSON Output
+
+  The output is a JSON object with structure:
+  ```json
+  {
+    "summary": { "total": 15, "pass": 12, "warn": 2, "fail": 1, "info": 0 },
+    "checks": [
+      { "check": "settings-json", "status": "PASS", "message": "...", "fixCommand": null },
+      { "check": "rules-files", "status": "FAIL", "message": "...", "fixCommand": "aiox doctor --fix" }
+    ]
+  }
+  ```
+
+  ### Step 3: Apply Governance Interpretation
+
+  For each check result, map to the Constitution article and provide remediation context
+  using the governance map below.
+
+  ### Step 4: Format Output as Markdown
+
+  Present results as a readable markdown report:
+
+  ```markdown
+  ## AIOX Health Check
+
+  Summary: {pass} PASS | {warn} WARN | {fail} FAIL | {info} INFO
+
+  ### Issues Requiring Attention
+
+  **[FAIL] {check-name}** — {message}
+  - Constitution Impact: Article {N} ({article-name}) — {governance-note}
+  - Remediation: {fixCommand or manual instruction}
+
+  **[WARN] {check-name}** — {message}
+  - Constitution Impact: Article {N} ({article-name}) — {governance-note}
+  - Remediation: {fixCommand or manual instruction}
+
+  ### All Checks
+  | Check | Status | Note |
+  |-------|--------|------|
+  | {check} | {status} | {message} |
+  ```
+
+  If `--verbose` is false, only show FAIL and WARN items in the issues section.
+  Always show the summary line and the full table.
+
+# Governance Interpretation Map (Constitution → Check)
+governance_map:
+  settings-json:
+    article: "II"
+    article_name: "Agent Authority"
+    governance_note: "Boundary protection — deny rules enforce framework immutability"
+    remediation: "aiox doctor --fix"
+
+  rules-files:
+    article: "II"
+    article_name: "Agent Authority"
+    governance_note: "Agent authority rules provide behavioral constraints"
+    remediation: "aiox doctor --fix"
+
+  agent-memory:
+    article: "II"
+    article_name: "Agent Authority"
+    governance_note: "Agent identity persistence across sessions"
+    remediation: "aiox doctor --fix"
+
+  entity-registry:
+    article: "III"
+    article_name: "Story-Driven Development"
+    governance_note: "Code intelligence registry for entity-aware development"
+    remediation: "aiox doctor --fix"
+
+  git-hooks:
+    article: "V"
+    article_name: "Quality First"
+    governance_note: "Quality gates enforced at git operations"
+    remediation: "aiox doctor --fix"
+
+  core-config:
+    article: "I"
+    article_name: "CLI First"
+    governance_note: "Configuration integrity — core-config.yaml drives CLI behavior"
+    remediation: "aiox doctor --fix"
+
+  claude-md:
+    article: "II"
+    article_name: "Agent Authority"
+    governance_note: "Agent context — CLAUDE.md provides system prompt foundation"
+    remediation: "aiox doctor --fix"
+
+  ide-sync:
+    article: "II"
+    article_name: "Agent Authority"
+    governance_note: "Agent consistency across IDE configurations"
+    remediation: "aiox doctor --fix"
+
+  graph-dashboard:
+    article: "I"
+    article_name: "CLI First"
+    governance_note: "CLI observability dashboard availability"
+    remediation: "Manual — install graph-dashboard package"
+
+  code-intel:
+    article: "III"
+    article_name: "Story-Driven Development"
+    governance_note: "Code intelligence for entity-aware development workflows"
+    remediation: "aiox doctor --fix"
+
+  node-version:
+    article: "V"
+    article_name: "Quality First"
+    governance_note: "Runtime requirements — Node.js 18+ required"
+    remediation: "Manual — upgrade Node.js to 18+"
+
+  npm-packages:
+    article: "V"
+    article_name: "Quality First"
+    governance_note: "Dependencies installed and consistent"
+    remediation: "npm install"
+
+  skills-count:
+    article: "II"
+    article_name: "Agent Authority"
+    governance_note: "Agent capabilities — skills extend agent functionality"
+    remediation: "npx aiox-core install --force"
+
+  commands-count:
+    article: "II"
+    article_name: "Agent Authority"
+    governance_note: "Agent action vocabulary — commands define what agents can do"
+    remediation: "npx aiox-core install --force"
+
+  hooks-claude-count:
+    article: "V"
+    article_name: "Quality First"
+    governance_note: "Quality gates — hooks enforce governance at runtime"
+    remediation: "npx aiox-core install --force"
+
+# Output schema
+output:
+  type: object
+  properties:
+    summary:
+      type: string
+      description: "PASS/WARN/FAIL count summary"
+    issues:
+      type: array
+      description: "List of FAIL and WARN items with governance context"
+    report:
+      type: string
+      description: "Full markdown report"
+
+# Examples
+examples:
+  - name: "Quick health check"
+    command: "*health-check"
+    description: "Run all 15 doctor checks with governance interpretation"
+
+  - name: "Health check with auto-fix"
+    command: "*health-check --fix"
+    description: "Run checks and auto-fix where possible"
+
+  - name: "Verbose output"
+    command: "*health-check --verbose"
+    description: "Show all checks including passed ones"
+
+# Help text
+help: |
+  ## AIOX Health Check (Unified)
+
+  Runs `aiox doctor --json` internally and adds governance context.
+  15 checks across configuration, environment, and agent readiness.
+
+  ### Quick Start
+
+  ```bash
+  *health-check              # Run all checks
+  *health-check --fix        # Auto-fix issues
+  *health-check --verbose    # Show all checks
+  ```
+
+  ### What It Checks
+
+  The task delegates to `aiox doctor` which runs 15 modular checks:
+  settings-json, rules-files, agent-memory, entity-registry, git-hooks,
+  core-config, claude-md, ide-sync, graph-dashboard, code-intel,
+  node-version, npm-packages, skills-count, commands-count, hooks-claude-count.
+
+  ### Governance Interpretation
+
+  Each FAIL/WARN result is mapped to a Constitution article:
+  - **Article I** (CLI First): core-config, graph-dashboard
+  - **Article II** (Agent Authority): settings-json, rules-files, agent-memory, claude-md, ide-sync, skills-count, commands-count
+  - **Article III** (Story-Driven Dev): entity-registry, code-intel
+  - **Article V** (Quality First): git-hooks, node-version, npm-packages, hooks-claude-count
+
+  ### Relationship to Other Tools
+
+  - `aiox doctor` = CLI tool (standalone, technical output)
+  - `*health-check` = This task (contextual, governance-aware, agent-facing)
+  - `core/health-check/` = Legacy HCS-2 system (separate, not used by this task)

package/template/.aiox-core/development/tasks/ids-governor.md

@@ -0,0 +1,94 @@
+# 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:** @aiox-master
+**Story:** IDS-7 (aiox-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/aiox-ids.js ids:check "your intent" --type task
+node bin/aiox-ids.js ids:impact create-doc
+node bin/aiox-ids.js ids:stats --json
+node bin/aiox-ids.js ids:register path/to/file.md
+```
+
+---
+
+## Dependencies
+
+- `.aiox-core/core/ids/framework-governor.js` — FrameworkGovernor class
+- `.aiox-core/core/ids/registry-loader.js` — RegistryLoader
+- `.aiox-core/core/ids/incremental-decision-engine.js` — DecisionEngine
+- `.aiox-core/core/ids/registry-updater.js` — RegistryUpdater
+- `.aiox-core/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)*