oxe-cc 0.7.1 → 0.9.0

package/lib/sdk/index.d.ts

@@ -66,6 +66,40 @@ export interface AzureHealthContext {
   warnings: string[];
 }
 
+export type CopilotPromptSource = 'workspace' | 'legacy_global' | 'missing';
+
+export interface CopilotWorkspaceIntegration {
+  root: string;
+  promptsDir: string;
+  instructions: string;
+  manifest: string;
+  promptFiles: string[];
+  hasInstructions: boolean;
+  hasOxeBlock: boolean;
+}
+
+export interface CopilotLegacyIntegration {
+  root: string;
+  promptsDir: string;
+  instructions: string;
+  promptFiles: string[];
+  hasInstructions: boolean;
+  hasOxeBlock: boolean;
+  hasOtherManagedBlocks: boolean;
+  detected: boolean;
+}
+
+export interface CopilotIntegrationReport {
+  status: 'healthy' | 'warning' | 'broken' | 'not_installed';
+  detected: boolean;
+  target: 'workspace';
+  promptSource: CopilotPromptSource;
+  workspace: CopilotWorkspaceIntegration;
+  legacy: CopilotLegacyIntegration;
+  manifest: Record<string, unknown> | null;
+  warnings: string[];
+}
+
 /** Relatório retornado por `health.buildHealthReport` e incluído em `runDoctorChecks`.healthReport. */
 export interface OxeHealthReport {
   configPath: string | null;
@@ -80,12 +114,32 @@ export interface OxeHealthReport {
   retroDate: Date | null;
   staleLessons: HealthStaleInfo;
   phaseWarn: string[];
+  runtimeWarn?: string[];
+  reviewWarn?: string[];
+  capabilityWarn?: string[];
+  investigationWarn?: string[];
+  sessionWarn?: string[];
+  installWarn?: string[];
+  copilotWarn?: string[];
+  copilot?: CopilotIntegrationReport | null;
   summaryGapWarn: string | null;
   specWarn: string[];
   planWarn: string[];
+  planSelfEvaluation?: Record<string, unknown> | null;
+  planReviewStatus?: string | null;
+  activeRun?: Record<string, unknown> | null;
+  eventsSummary?: Record<string, unknown> | null;
+  memoryLayers?: Record<string, unknown> | null;
   next: OxeNextSuggestion;
   azureActive?: boolean;
   azure?: AzureHealthContext | null;
+  contextWarn?: string[];
+  semanticsWarn?: string[];
+  contextPacks?: Record<string, ContextPackSummary>;
+  contextQuality?: ContextQualitySummary;
+  semanticsDrift?: SemanticsDriftSummary;
+  packFreshness?: Record<string, PackFreshness>;
+  activeSummaryRefs?: { project: string | null; session: string | null; phase: string | null };
   scanFocusGlobs?: unknown;
   scanIgnoreGlobs?: unknown;
 }
@@ -128,6 +182,49 @@ export interface ParsedTask {
   meta: Record<string, unknown> | null;
 }
 
+export type ContextPackMode = 'standard' | 'auditor';
+
+export interface LessonOutcome {
+  cycle: string;
+  verify_status: string;
+  saved_hours?: number;
+  failure_condition?: string;
+}
+
+export interface LessonMetric {
+  id: string;
+  rule: string;
+  type: string;
+  applied_cycles: string[];
+  outcomes: LessonOutcome[];
+  success_rate: number;
+  status: 'active' | 'deprecated' | 'conditional';
+  deprecation_threshold: number;
+}
+
+export interface ConfidenceDimension {
+  name: string;
+  score: number;
+  weight: number;
+  note: string;
+}
+
+export interface ConfidenceVector {
+  cycle: string | null;
+  generated_at: string | null;
+  dimensions: ConfidenceDimension[];
+  global: { score: number; gate: string };
+}
+
+export interface CriticalHypothesis {
+  id: string;
+  condition: string;
+  validation: string;
+  on_failure: string;
+  checkpoint: string | null;
+  status: 'pending' | 'validated' | 'refuted' | 'skipped';
+}
+
 export interface ParsedPlan {
   tasks: ParsedTask[];
   waves: Record<number, string[]>;
@@ -189,6 +286,110 @@ export interface PlanPathsResult {
   issues: Array<{ path: string; reason: string }>;
 }
 
+export interface OxePermissionRule {
+  pattern: string;
+  action: 'allow' | 'deny' | 'ask';
+  scope?: 'execute' | 'apply' | 'all';
+}
+
+export interface PermissionCheckResult {
+  denied: string[];
+  needsApproval: string[];
+  allowed: string[];
+}
+
+export interface ReplayReport {
+  events: Array<Record<string, unknown>>;
+  totalEvents: number;
+  duration_ms: number | null;
+  runId: string | null;
+  waveIds: number[];
+  taskSequence: string[];
+  checkpointSequence: string[];
+  failureEvents: Array<Record<string, unknown>>;
+  _reportPath?: string;
+}
+
+export interface ContextArtifactSelection {
+  alias: string;
+  path: string | null;
+  exists: boolean;
+  required: boolean;
+  using_fallback: boolean;
+  scope: string;
+  summary: string;
+}
+
+export interface ContextGap {
+  alias: string;
+  severity: 'critical' | 'warning';
+  reason: string;
+}
+
+export interface ContextConflict {
+  alias: string;
+  reason: string;
+  primary_path: string | null;
+  fallback_path: string | null;
+}
+
+export interface PackFreshness {
+  generated_at: string | null;
+  latest_source_at: string | null;
+  pack_age_hours: number | null;
+  max_pack_age_hours: number;
+  stale: boolean;
+  reason: 'fresh' | 'pack_age_exceeded' | 'source_newer_than_pack' | 'fallback_required';
+}
+
+export interface ContextQualityScore {
+  score: number;
+  status: 'excellent' | 'good' | 'fragile' | 'critical';
+  requiredMissing: number;
+  optionalMissing: number;
+  conflicts: number;
+  fallbackCount: number;
+}
+
+export interface ContextPackSummary {
+  path?: string;
+  context_tier: string;
+  semantics_hash: string | null;
+  read_order: string[];
+  selected_artifacts: ContextArtifactSelection[];
+  gaps: ContextGap[];
+  conflicts: ContextConflict[];
+  fallback_required: boolean;
+  freshness: PackFreshness;
+  context_quality: ContextQualityScore;
+}
+
+export interface ContextQualitySummary {
+  primaryWorkflow: string | null;
+  primaryScore: number | null;
+  primaryStatus: string | null;
+  byWorkflow: Record<string, Record<string, unknown>>;
+}
+
+export interface SemanticsDriftSummary {
+  ok: boolean;
+  contractVersion: string;
+  manifestPath: string;
+  manifest: Record<string, unknown> | null;
+  audit: {
+    ok: boolean;
+    warnings: string[];
+    mismatchCount: number;
+    mismatches: Array<Record<string, unknown>>;
+    targets: Record<string, { path: string; checked: number; missing: boolean }>;
+  };
+}
+
+export interface PluginSource {
+  source: string;
+  version?: string;
+}
+
 export interface OxePlugin {
   name: string;
   version?: string;
@@ -219,6 +420,47 @@ export interface AgentsAPI {
   parseCursorCommandFrontmatter: (mdContent: string) => Record<string, unknown>;
 }
 
+export interface ContextAPI {
+  contextPaths: (projectRoot: string, activeSession?: string | null) => Record<string, unknown>;
+  resolveArtifactCandidates: (projectRoot: string, activeSession?: string | null) => Record<string, unknown>;
+  buildProjectSummary: (projectRoot: string, activeSession?: string | null, options?: Record<string, unknown>) => Record<string, unknown>;
+  buildSessionSummary: (projectRoot: string, activeSession?: string | null, options?: Record<string, unknown>) => Record<string, unknown> | null;
+  buildPhaseSummary: (projectRoot: string, activeSession?: string | null, options?: Record<string, unknown>) => Record<string, unknown>;
+  buildContextIndex: (projectRoot: string, activeSession?: string | null, options?: Record<string, unknown>) => Record<string, unknown>;
+  buildContextPack: (projectRoot: string, input?: Record<string, unknown>) => Record<string, unknown>;
+  inspectContextPack: (projectRoot: string, input?: Record<string, unknown>) => Record<string, unknown>;
+  buildAllContextPacks: (projectRoot: string, input?: Record<string, unknown>) => Array<Record<string, unknown>>;
+  computeContextQuality: (pack: Record<string, unknown>) => Record<string, unknown>;
+  computePackFreshness: (pack: Record<string, unknown>, contract?: Record<string, unknown>) => Record<string, unknown>;
+  resolvePackFile: (projectRoot: string, workflow: string, activeSession?: string | null) => string;
+  summarizeText: (text: string, maxChars?: number, maxLines?: number) => string;
+  extractSemanticFragment: (text: string, options?: { intent?: string; maxChars?: number; preserveMarkers?: string[] }) => string;
+  parseHypotheses: (planText: string) => CriticalHypothesis[];
+  parseConfidenceVector: (planText: string) => ConfidenceVector | null;
+}
+
+export interface RuntimeSemanticsAPI {
+  CONTRACT_VERSION: string;
+  CONTRACTS_PATH: string;
+  CONTRACTS_REGISTRY: Record<string, unknown>;
+  REQUIRED_CONTRACT_FIELDS: string[];
+  RUNTIME_METADATA_KEYS: string[];
+  validateWorkflowContractsRegistry: (registry?: Record<string, unknown>) => string[];
+  getWorkflowContract: (slug: string) => Record<string, unknown> | null;
+  getAllWorkflowContracts: () => Array<Record<string, unknown>>;
+  computeSemanticsHash: (slug: string) => string | null;
+  getRuntimeMetadataForSlug: (slug: string, options?: Record<string, unknown>) => Record<string, string>;
+  renderRuntimeMetadataLines: (meta: Record<string, string>) => string[];
+  buildReasoningContractBlock: (meta: Record<string, string>, options?: Record<string, unknown>) => string;
+  pickRuntimeMetadata: (frontmatter: Record<string, string>) => Record<string, string>;
+  splitFrontmatter: (raw: string) => { frontmatter: string; body: string };
+  parseFrontmatterMap: (raw: string) => Record<string, string>;
+  slugFromPromptFilename: (name: string) => string;
+  slugFromCommandFilename: (name: string) => string;
+  auditWrapperText: (slug: string, raw: string) => Record<string, unknown>;
+  auditRuntimeTargets: (projectRoot: string) => Record<string, unknown>;
+}
+
 export interface OxeSdk {
   version: string;
   name: string;
@@ -228,12 +470,17 @@ export interface OxeSdk {
 
   /** Parsing de artefatos OXE. */
   parsePlan: (planMd: string) => ParsedPlan;
+  parseHypotheses: (planText: string) => CriticalHypothesis[];
+  parseConfidenceVector: (planText: string) => ConfidenceVector | null;
   parseSpec: (specMd: string) => ParsedSpec;
   parseState: (stateMd: string) => ParsedState;
   validateDecisionFidelity: (discussMd: string, planMd: string) => DecisionFidelityResult;
+  parseLessonsMetrics: (metricsJson: string) => LessonMetric[];
+  updateLessonMetric: (metrics: LessonMetric[], lessonId: string, outcome: LessonOutcome) => LessonMetric[];
+  deprecateLowEffectiveness: (metrics: LessonMetric[], threshold?: number, minObservations?: number) => LessonMetric[];
 
   health: {
-    loadOxeConfigMerged: (targetProject: string) => { config: Record<string, unknown>; path: string | null; parseError: string | null };
+    loadOxeConfigMerged: (targetProject: string) => { config: Record<string, unknown>; path: string | null; parseError: string | null; sources: { system: string | null; user: string | null; project: string | null } };
     validateConfigShape: (cfg: Record<string, unknown>) => { unknownKeys: string[]; typeErrors: string[] };
     buildHealthReport: (target: string) => OxeHealthReport;
     suggestNextStep: (target: string, cfg?: { discuss_before_plan?: boolean }) => OxeNextSuggestion;
@@ -244,6 +491,9 @@ export interface OxeSdk {
     parseLastRetroDate: (stateText: string) => Date | null;
     isStaleScan: (scanDate: Date | null, maxAgeDays: number) => HealthStaleInfo;
     isStaleLessons: (retroDate: Date | null, maxAgeDays: number) => HealthStaleInfo;
+    copilotWorkspacePaths: (target: string) => { root: string; promptsDir: string; instructions: string; manifest: string };
+    copilotLegacyPaths: () => { root: string; promptsDir: string; instructions: string };
+    copilotIntegrationReport: (target: string) => CopilotIntegrationReport;
     planAgentsWarnings: (target: string) => string[];
     phaseCoherenceWarnings: (phase: string, paths: Record<string, string>) => string[];
     specSectionWarnings: (specPath: string, requiredHeadings: string[]) => string[];
@@ -291,6 +541,9 @@ export interface OxeSdk {
     scanFileForSecrets: (filePath: string, options?: { contentPatterns?: RegExp[] }) => SecretScanResult;
     scanDirForSecretFiles: (dir: string, options?: { secretPatterns?: RegExp[]; maxDepth?: number }) => string[];
     validatePlanPaths: (filePaths: string[], projectRoot: string) => PlanPathsResult;
+    checkFilePermission: (filePath: string, permissions: OxePermissionRule[], currentScope?: string) => { action: string; rule: OxePermissionRule | null };
+    checkPermissions: (fileList: string[], permissions: OxePermissionRule[], scope?: string) => PermissionCheckResult;
+    globToRegex: (glob: string) => RegExp;
     DEFAULT_SECRET_PATTERNS: RegExp[];
     DEFAULT_SECRET_CONTENT_PATTERNS: RegExp[];
     DEFAULT_DENIED_PATH_PATTERNS: RegExp[];
@@ -302,6 +555,8 @@ export interface OxeSdk {
     runHook: (plugins: OxePlugin[], hookName: string, ctx: Record<string, unknown>) => Promise<Array<{ plugin: string; error: string }>>;
     validatePlugins: (projectRoot: string) => PluginValidationResult;
     initPluginsDir: (projectRoot: string) => void;
+    resolvePluginSources: (projectRoot: string, pluginsSources: Array<string | PluginSource>) => { resolved: string[]; errors: Array<{ source: string; error: string }> };
+    installNpmPlugin: (projectRoot: string, pkgName: string, version?: string) => { ok: boolean; path: string; error: string };
   };
 
   dashboard: {
@@ -311,6 +566,9 @@ export interface OxeSdk {
     updatePlanReviewCommentStatus: (projectRoot: string, input?: Record<string, unknown>) => Record<string, unknown> | null;
   };
 
+  context: ContextAPI;
+  runtimeSemantics: RuntimeSemanticsAPI;
+
   operational: {
     operationalPaths: (projectRoot: string, activeSession: string | null) => Record<string, string | null>;
     appendEvent: (projectRoot: string, activeSession: string | null, event?: Record<string, unknown>) => Record<string, unknown>;
@@ -323,6 +581,13 @@ export interface OxeSdk {
     parseCapabilityManifest: (text: string) => Record<string, unknown>;
     readCapabilityCatalog: (projectRoot: string) => Array<Record<string, unknown>>;
     buildMemoryLayers: (projectRoot: string, activeSession: string | null) => Record<string, unknown>;
+    replayEvents: (projectRoot: string, activeSession: string | null, options?: {
+      fromEventId?: string;
+      runId?: string;
+      waveId?: number;
+      limit?: number;
+      writeReport?: boolean;
+    }) => ReplayReport;
   };
 
   azure: {

package/oxe/templates/HYPOTHESES.template.md

@@ -0,0 +1,33 @@
+---
+oxe_doc: hypotheses
+status: draft
+updated: YYYY-MM-DD
+---
+
+<!--
+  Hipóteses Críticas OXE — seção opcional do PLAN.md para tarefas L/XL ou
+  com dependências externas. Cada hipótese deve ser validada antes do
+  checkpoint declarado; se refutada, registrar bloqueio explícito antes de
+  qualquer mutação.
+
+  Formato recomendado: tags XML dentro do MD (para extração pelo context engine)
+  com tabela resumida abaixo para leitura humana.
+
+  Status possíveis: pending | validated | refuted | skipped
+-->
+
+## Hipóteses Críticas
+
+<hypothesis id="H1" checkpoint="T2" status="pending">
+  <condition>Descrever a premissa que precisa ser verdadeira para avançar</condition>
+  <validation>Comando ou inspeção que prova/refuta a hipótese (ex: npm install && node test/auth.cjs)</validation>
+  <on_failure>O que fazer se refutada (ex: bloquear T2, abrir pesquisa de alternativa, replanejar)</on_failure>
+</hypothesis>
+
+<!-- Adicionar mais blocos <hypothesis> conforme necessário -->
+
+### Tabela resumida
+
+| ID  | Hipótese               | Checkpoint | Status  |
+|-----|------------------------|------------|---------|
+| H1  | (descrição da premissa)| antes de T?| pending |

package/oxe/templates/PLAN.template.md

@@ -14,28 +14,59 @@ inputs: []
 
 > Gerado a partir de `.oxe/SPEC.md`. Cada tarefa deve ter bloco **Verificar**.
 
-## Resumo
-
-- **Spec vinculada:** (data ou versão informal)
-- **Ondas:** (número)
-- **Tarefas:** (número)
-
-## Autoavaliação do Plano
-
-- **Melhor plano atual:** sim
-- **Confiança:** 80%
-- **Base da confiança:**
-  - Completude dos requisitos: 20/25
-  - Dependências conhecidas: 12/15
-  - Risco técnico: 15/20
-  - Impacto no código existente: 12/15
-  - Clareza da validação / testes: 13/15
-  - Lacunas externas / decisões pendentes: 8/10
-- **Principais incertezas:** (0–3 bullets)
-- **Alternativas descartadas:** (1–2 linhas)
-- **Condição para replanejar:** (critério objetivo)
-
-## Dependências globais
+## Resumo
+
+- **Spec vinculada:** (data ou versão informal)
+- **Ondas:** (número)
+- **Tarefas:** (número)
+
+## Autoavaliação do Plano
+
+- **Melhor plano atual:** sim
+- **Confiança:** 80%
+- **Base da confiança:**
+  - Completude dos requisitos: 20/25
+  - Dependências conhecidas: 12/15
+  - Risco técnico: 15/20
+  - Impacto no código existente: 12/15
+  - Clareza da validação / testes: 13/15
+  - Lacunas externas / decisões pendentes: 8/10
+- **Principais incertezas:** (0–3 bullets)
+- **Alternativas descartadas:** (1–2 linhas)
+- **Condição para replanejar:** (critério objetivo)
+
+<confidence_vector cycle="C-NN" generated_at="YYYY-MM-DDTHH:MM:SSZ">
+  <dim name="requirements"   score="0.80" weight="25" note="completude dos requisitos" />
+  <dim name="dependencies"   score="0.80" weight="15" note="dependências conhecidas" />
+  <dim name="technical_risk" score="0.75" weight="20" note="risco técnico — ajustar se H* pendentes" />
+  <dim name="code_impact"    score="0.80" weight="15" note="impacto no código existente" />
+  <dim name="validation"     score="0.87" weight="15" note="clareza da validação / testes" />
+  <dim name="open_gaps"      score="0.80" weight="10" note="lacunas externas / decisões pendentes" />
+  <global score="0.80" gate="proceed_with_risk" />
+</confidence_vector>
+
+<!--
+  gate possíveis: proceed | proceed_with_risk | refine_first | blocked
+  Atualizar este bloco a cada replanejamento; o campo cycle deve coincidir com o ciclo atual.
+-->
+
+## Hipóteses Críticas
+
+<!--
+  Obrigatório quando houver tarefas L/XL ou dependências de libs externas/APIs.
+  Omitir se todas as tarefas forem S/M e sem dependências não verificadas.
+  Usar tags XML para extração pelo context engine (ver oxe/templates/HYPOTHESES.template.md).
+-->
+
+<!-- Exemplo (remover se não houver hipóteses):
+<hypothesis id="H1" checkpoint="T2" status="pending">
+  <condition>lib X disponível no npm sem conflito de versão</condition>
+  <validation>npm install X && node -e "require('X')"</validation>
+  <on_failure>bloquear T2, avaliar alternativa Y</on_failure>
+</hypothesis>
+-->
+
+## Dependências globais
 
 - (ex.: branch base, feature flags, migrations)
 

package/oxe/templates/SESSION.template.md

@@ -8,6 +8,8 @@
 - **Criada:** YYYY-MM-DD
 - **Última atividade:** YYYY-MM-DD
 - **Resumo:** <uma linha>
+- **Forked from:** —
+- **Forked at:** —
 
 ## Índice de artefatos
 

package/oxe/templates/SKILL.template.md

@@ -0,0 +1,26 @@
+---
+oxe_skill: true
+id: <skill-id>
+name: <Human Readable Name>
+version: 1.0.0
+type: persona | capability | composite
+scope: global | project
+description: <one-line description>
+invoke: "@<skill-id>"
+references: []
+tags: []
+---
+
+# Skill: <name>
+
+## Descrição
+
+(Quando e como usar este skill. Uma ou duas frases.)
+
+## Ativação
+
+Mencionar `@<skill-id>` no chat ou incluir na atribuição de agente em plan-agents.json (`"persona": "<skill-id>"`).
+
+## Saída esperada
+
+(O que o agente faz ao adotar este skill.)

package/oxe/templates/WORKFLOW_AUTHORING.md

@@ -36,7 +36,7 @@ Mantenha tags **abertas e fechadas** explicitamente (evita ambiguidade para leit
 - Template opcional de pasta `docs/` brownfield: [`DOCS_BROWNFIELD_LAYOUT.md`](DOCS_BROWNFIELD_LAYOUT.md) (copiado para `.oxe/templates/` na instalação).
 - O `SKILL.md` principal do passo deve permanecer o **mapa**: objetivo, contexto essencial, sequência, critérios de sucesso.
 
-## 4. Comandos Cursor e prompts Copilot (frontmatter)
+## 4. Comandos Cursor e prompts Copilot (frontmatter)
 
 Ficheiros em `.cursor/commands/` e `.github/prompts/` costumam ter YAML inicial:
 
@@ -49,7 +49,23 @@ description: Resumo de 5–8 palavras. Use quando o utilizador pedir X, Y ou Z.
 - **Resumo:** o que o passo faz.
 - **Gatilhos:** frases ou intenções que devem ativar o comando (evita disparar em tudo).
 
-O corpo do ficheiro deve **apontar** para o workflow em `oxe/workflows/<passo>.md` (ou `.oxe/workflows/`) sem duplicar a lógica por completo.
+O corpo do ficheiro deve **apontar** para o workflow em `oxe/workflows/<passo>.md` (ou `.oxe/workflows/`) sem duplicar a lógica por completo.
+
+### Metadata cognitiva multi-runtime
+
+Prompts e wrappers OXE podem carregar metadata adicional para sincronizar a postura de raciocínio entre runtimes:
+
+```yaml
+oxe_reasoning_mode: discovery | planning | execution | review | status
+oxe_question_policy: explore_first | ask_high_impact_only | none
+oxe_output_contract: situational | plan | execution | findings | routing
+oxe_tool_profile: read_heavy | write_bounded | review_heavy | mixed
+oxe_confidence_policy: explicit | rubric | optional
+```
+
+- Use a mesma metadata em `.github/prompts/` e `commands/oxe/`.
+- O corpo do wrapper deve incluir um bloco curto de **Contrato de raciocínio OXE deste comando** consistente com essa metadata.
+- Cursor, Codex e CLIs derivados devem preservar essa semântica; não manter regras cognitivas importantes só numa integração.
 
 ## 5. Script vs agente
 

package/oxe/templates/config.template.json

@@ -2,9 +2,10 @@
   "_comment": "OXE config — copie para .oxe/config.json no seu projeto. Remova esta linha.",
   "profile": "balanced",
   "discuss_before_plan": false,
-  "verification_depth": "standard",
-  "plan_confidence_threshold": 70,
-  "security_in_verify": false,
+  "verification_depth": "standard",
+  "plan_confidence_threshold": 70,
+  "security_in_verify": false,
+  "adversarial_verify": false,
   "after_verify_suggest_pr": true,
   "after_verify_draft_commit": true,
   "after_verify_suggest_uat": false,
@@ -16,17 +17,18 @@
   "scan_focus_globs": [],
   "scan_ignore_globs": [],
   "spec_required_sections": [],
-  "plan_max_tasks_per_wave": 0,
-  "azure": {
-    "enabled": false,
-    "default_resource_group": "",
-    "preferred_locations": [],
-    "inventory_max_age_hours": 24,
-    "resource_graph_auto_install": true,
-    "vpn_required": false
-  },
-  "install": {
-    "profile": "recommended",
+  "plan_max_tasks_per_wave": 0,
+  "permissions": [],
+  "azure": {
+    "enabled": false,
+    "default_resource_group": "",
+    "preferred_locations": [],
+    "inventory_max_age_hours": 24,
+    "resource_graph_auto_install": true,
+    "vpn_required": false
+  },
+  "install": {
+    "profile": "recommended",
     "repo_layout": "nested",
     "vscode": false,
     "include_commands_dir": true,

package/oxe/workflows/ask.md

@@ -5,8 +5,12 @@ Responder perguntas sobre a situação atual do trabalho OXE com máxima robuste
 </objective>
 
 <context>
+- Aplicar `oxe/workflows/references/reasoning-discovery.md` como postura cognitiva deste passo.
 - Resolver `active_session` via `oxe/workflows/references/session-path-resolution.md`.
 - Ler sempre `.oxe/STATE.md` global primeiro.
+- Antes de abrir o conjunto amplo de artefatos, tentar o contexto resolvido em `.oxe/context/packs/ask.md` e `.oxe/context/packs/ask.json` como entrada prioritária.
+- Se o pack existir e estiver fresco/coerente, ler primeiro o resumo do pack e depois inspecionar apenas os artefatos listados em `read_order` / `selected_artifacts` antes de expandir a leitura.
+- Se o pack estiver ausente, stale ou com lacunas críticas, fazer fallback explícito para leitura direta e declarar esse fallback na resposta.
 - Com sessão ativa, priorizar artefatos em `.oxe/<active_session>/...` antes do modo legado.
 - Usar `.oxe/codebase/` como mapa do repositório, não como substituto dos artefatos da trilha.
 - Se a pergunta estiver ambígua, responder em modo “situação atual + próximos riscos + melhor próxima ação”.
@@ -15,15 +19,23 @@ Responder perguntas sobre a situação atual do trabalho OXE com máxima robuste
 
 <process>
 1. Ler `.oxe/STATE.md` global e determinar se há `active_session`.
-2. Se houver sessão ativa, ler nesta ordem:
+2. Resolver o contexto estruturado primeiro:
+   - tentar `.oxe/context/packs/ask.md` / `.oxe/context/packs/ask.json` (ou `oxe-cc context inspect --workflow ask --json`) para obter `read_order`, `selected_artifacts`, `gaps`, `conflicts` e `freshness`;
+   - se o pack estiver fresco e sem lacunas críticas, usá-lo como mapa primário de leitura;
+   - se o pack estiver stale, incompleto ou ausente, declarar `fallback para leitura direta` antes de abrir os artefatos brutos.
+3. Se houver pack válido, ler primeiro:
+   - o resumo humano do pack (`.md`);
+   - os artefatos de `read_order`;
+   - quaisquer artefatos adicionais de `selected_artifacts` necessários para responder com evidência.
+4. Se houver sessão ativa e o pack não bastar, ler nesta ordem:
    - `SESSION.md`
    - `spec/SPEC.md`, `spec/ROADMAP.md`, `spec/DISCUSS.md`, `spec/UI-SPEC.md` se existirem
    - `plan/PLAN.md`, `plan/QUICK.md`, `plan/plan-agents.json`, `plan/quick-agents.json` se existirem
    - `execution/STATE.md`, `execution/EXECUTION-RUNTIME.md`, `execution/CHECKPOINTS.md`, `execution/OBSERVATIONS.md`, `execution/DEBUG.md`, `execution/FORENSICS.md`, `execution/SUMMARY.md` se existirem
    - `research/INVESTIGATIONS.md`, `research/RESEARCH.md`, `research/investigations/` se existirem
    - `verification/VERIFY.md`, `verification/VALIDATION-GAPS.md`, `verification/SECURITY.md`, `verification/UI-REVIEW.md` se existirem
-3. Sem sessão ativa, ler o equivalente legado na raiz `.oxe/`.
-4. Em ambos os casos, ler também:
+5. Sem sessão ativa e se o pack não bastar, ler o equivalente legado na raiz `.oxe/`.
+6. Em ambos os casos, ler também:
    - `.oxe/codebase/OVERVIEW.md`
    - `.oxe/codebase/STACK.md`
    - `.oxe/codebase/CONCERNS.md`
@@ -33,8 +45,14 @@ Responder perguntas sobre a situação atual do trabalho OXE com máxima robuste
    - `.oxe/global/LESSONS.md` se existir, com fallback para `.oxe/LESSONS.md`
    - `.oxe/SESSIONS.md` se a pergunta mencionar sessões, histórico ou retomada
    - `.oxe/cloud/azure/INVENTORY.md`, `SERVICEBUS.md`, `EVENTGRID.md`, `SQL.md` e `auth-status.json` se a pergunta tocar Azure, cloud, infraestrutura, mensageria, integração ou banco gerido
-5. Responder à pergunta do utilizador com base em evidência explícita dos artefatos lidos.
-6. Se faltar artefato crítico para responder com segurança, dizer exatamente o que falta e qual comando OXE fecha essa lacuna.
+7. Se a pergunta exigir evidência fora do pack, expandir a leitura apenas para os artefatos adicionais estritamente necessários e mencionar a expansão na resposta.
+8. Responder à pergunta do utilizador com base em evidência explícita dos artefatos lidos.
+9. Se faltar artefato crítico para responder com segurança, dizer exatamente o que falta e qual comando OXE fecha essa lacuna.
+10. Estruturar a resposta conforme o contrato de saída:
+   - **Fatos** — o que os artefatos confirmam sem ambiguidade
+   - **Inferências** — conclusões derivadas dos artefatos
+   - **Lacunas** — o que não pode ser afirmado com segurança
+   - **Próximo passo** — apenas quando fizer sentido operacional
 
 ## Modo diagnóstico padrão
 
@@ -49,6 +67,7 @@ Se o utilizador só disser algo genérico como “o que está acontecendo?”,
 ## Regras de robustez
 
 - Não assumir que `doctor` ou `status` sejam session-aware; eles não substituem a leitura direta dos artefatos da sessão.
+- O context pack acelera e comprime a leitura, mas não substitui a evidência. Se ele estiver stale ou insuficiente, o fallback deve ser explícito.
 - Se houver conflito entre `.oxe/STATE.md` global e `execution/STATE.md` da sessão, explicitar o conflito.
 - Se houver `CHECKPOINTS.md` com itens `pending_approval`, isso tem precedência operacional sobre o “próximo passo” implícito.
 - Se `EXECUTION-RUNTIME.md` ou `INVESTIGATIONS.md` existirem, tratá-los como evidência tática complementar para explicar bloqueios, handoffs, riscos e lacunas.
@@ -58,9 +77,11 @@ Se o utilizador só disser algo genérico como “o que está acontecendo?”,
 </process>
 
 <output>
-- Resposta direta à pergunta do utilizador
+- **Fatos**
+- **Inferências**
+- **Lacunas**
+- **Próximo passo** (quando necessário)
 - Referência curta aos artefatos usados
-- Quando necessário, um único próximo passo OXE
 </output>
 
 <success_criteria>

package/oxe/workflows/capabilities.md

@@ -15,9 +15,11 @@ Gerir capabilities nativas do OXE: listar, explicar, instalar, remover e diagnos
 2. Se o pedido for `list` ou genérico, responder com capabilities instaladas, escopo e riscos.
 3. Se o pedido for instalar ou remover, orientar o utilizador a usar `oxe-cc capabilities ...` ou o workflow equivalente aprovado pelo projeto.
 4. Se o pedido for diagnóstico, apontar drift entre índice, manifestos e artefatos esperados.
+5. Após qualquer operação de install ou remove bem-sucedida, atualizar **`.oxe/STATE.md`**: linha `capabilities_updated: YYYY-MM-DD` ou nota na secção Decisões registando a capability adicionada/removida.
 </process>
 
 <success_criteria>
 - [ ] O estado do catálogo foi lido a partir dos artefatos reais.
 - [ ] A resposta deixa claro o que é capability nativa e o que é núcleo do OXE.
+- [ ] `.oxe/STATE.md` foi atualizado quando houve install ou remove (passo 5).
 </success_criteria>