IDS - Incremental Development System

📖 Visão Geral

O IDS (Incremental Development System) é o sistema central de rastreamento de artefatos do AIOS. Ele mantém um registro de todas as entidades do framework — tasks, templates, scripts, modules, agents, checklists e data files — com metadata, relacionamentos, adaptability scores e checksums.

Componentes Principais

Módulo	LOC	Função
`registry-loader.js`	312	Load e query do registry YAML
`incremental-decision-engine.js`	653	Recomendações REUSE/ADAPT/CREATE
`registry-healer.js`	868	Self-healing de integridade
`registry-updater.js`	622	Updates incrementais
`framework-governor.js`	567	Facade para aios-master
`verification-gate.js`	283	Gates de verificação
`circuit-breaker.js`	135	Circuit breaker pattern

Estatísticas do Registry

474 entidades totais em 7 categorias
198 tasks, 134 modules, 67 scripts, 52 templates, 12 agents
Query time médio: <1ms
Suporta até ~1000 entidades (v2 sharded planejado)

📁 Entity Registry Schema

Estrutura YAML

metadata:
  version: "1.0.0"
  lastUpdated: "ISO-8601"
  entityCount: 474
  checksumAlgorithm: "sha256"

entities:
  <category>:  # tasks, templates, scripts, modules, agents, checklists, data
    <entity-id>:
      path: "relative/path"
      type: "task"
      purpose: "Brief desc (max 200 chars)"
      keywords: ["k1", "k2"]
      usedBy: ["entity-ids"]       # Reverse dependencies
      dependencies: ["ids"]        # Forward dependencies
      adaptability:
        score: 0.0-1.0
        constraints: []
        extensionPoints: []
      checksum: "sha256:hex"
      lastVerified: "ISO-8601"

Adaptability Scores

Score	Meaning	Example
0.0-0.3	Low — changes likely break consumers	Agent definitions, core templates
0.4-0.6	Medium — needs careful impact analysis	Shared utilities, modules
0.7-1.0	High — safe to adapt with docs	Specific tasks, scripts

RegistryLoader API

const { RegistryLoader } = require('./.aios-core/core/ids/registry-loader');
const loader = new RegistryLoader();
loader.load();

// Query methods
loader.queryByKeywords(['validate', 'story'])  // Find by keywords
loader.queryByType('task')                      // Find by type
loader.queryByPath('core/')                     // Find by path substring
loader.queryByPurpose('validation')             // Find by purpose text
loader.getRelationships(id)                     // Get usedBy + dependencies
loader.getUsedBy(id)                            // Get consumers
loader.getDependencies(id)                      // Get dependencies
loader.verifyChecksum(id, repoRoot)             // Verify file integrity

🧠 Incremental Decision Engine

Analisa intent do desenvolvedor e recomenda REUSE, ADAPT ou CREATE baseado em artefatos existentes no registry.

Algoritmo

Score = TF-IDF Keyword Overlap (60%) + Purpose Similarity (40%)

Decision Matrix:
├── Score >= 90%  →  REUSE
├── Score 60-89%  →  ADAPT (with constraints)
└── Score < 60%   →  CREATE

API

const engine = new IncrementalDecisionEngine(loader);

const result = engine.analyze(
  "validate yaml schema for agent configuration",
  { type: "task" }  // optional filter
);

// Returns:
{
  intent: "validate yaml schema...",
  recommendations: [
    {
      entityId: "validate-agent-yaml",
      decision: "REUSE",
      confidence: "high",
      relevanceScore: 0.92,
      entityPath: ".aios-core/tasks/validate-agent-yaml.md"
    },
    // ...
  ],
  summary: {
    totalEntities: 474,
    matchesFound: 12,
    decision: "REUSE",
    confidence: "high"
  },
  rationale: "High similarity found..."
}

Thresholds

KEYWORD_OVERLAP_WEIGHT: 0.6 (60%)
PURPOSE_SIMILARITY_WEIGHT: 0.4 (40%)
THRESHOLD_MINIMUM: 0.4 (40% mínimo para considerar)
MAX_RESULTS: 20
CACHE_TTL_MS: 300000 (5 min)
ADAPT_IMPACT_THRESHOLD: 0.30

🏥 Registry Healer

Sistema de self-healing que detecta e auto-corrige problemas de integridade no registry.

Healing Rules

Rule ID	Severity	Auto-Healable	Descrição
missing-file	CRITICAL	❌	Arquivo referenciado não existe
checksum-mismatch	HIGH	✅	Conteúdo mudou desde verificação
orphaned-usedBy	MEDIUM	✅	usedBy aponta para entidade inexistente
orphaned-dependency	MEDIUM	✅	dependency aponta para entidade inexistente
missing-keywords	LOW	✅	Entidade sem keywords
stale-verification	LOW	✅	Não verificado em 7+ dias

Health Check

const healer = new RegistryHealer();
const result = healer.runHealthCheck();

// Returns:
{
  issues: [...],
  summary: {
    total: 5,
    bySeverity: { critical: 0, high: 2, medium: 2, low: 1 },
    autoHealable: 5,
    needsManual: 0
  },
  timestamp: "2026-02-19T15:00:00Z"
}

🏛️ Framework Governor

Facade que integra aios-master com o IDS para governança do framework. Todos os métodos são advisory (non-blocking) com graceful degradation e timeout de 2s.

API

Method	Função
`preCheck(intent, type)`	Pre-operation registry query
`impactAnalysis(entityId)`	BFS traversal de usedBy graph
`postRegister(entityId)`	Registra nova entidade
`health()`	Health check do registry
`stats()`	Estatísticas do registry

Impact Analysis (BFS)

const result = await governor.impactAnalysis('shared-validator');

// Returns:
{
  entityId: "shared-validator",
  found: true,
  directConsumers: ["task-a", "task-b"],
  indirectConsumers: ["task-c", "task-d"],
  totalAffected: 4,
  riskLevel: "MEDIUM",  // LOW < 10%, MEDIUM 10-30%, HIGH > 30%
  adaptabilityScore: 0.6
}

Risk Thresholds

LOW: < 10% das entidades afetadas
MEDIUM: 10-30% das entidades afetadas
HIGH: > 30% das entidades afetadas

🪝 Git Hooks Integration

ids-post-commit.js

Roda assincronamente após cada commit para atualizar o registry. NÃO bloqueia o commit.

Obtém arquivos alterados via git diff-tree
Ignora commits docs-only (README, CHANGELOG, etc.)
Atualiza registry via RegistryUpdater

ids-pre-push.js

Roda sincronamente antes do push para garantir registry atualizado. Exit 0 mesmo em erros (non-blocking).

Compara HEAD local com remote tracking branch
Processa todos arquivos diferentes
Ignora push docs-only