aios-core 4.2.6 → 4.2.7

package/.aios-core/development/agents/ux-design-expert.md

@@ -196,7 +196,7 @@ commands:
 
   # === UNIVERSAL COMMANDS ===
   scan {path|url}: 'Analyze HTML/React artifact for patterns'
-  integrate {pack}: 'Connect with squad'
+  integrate {squad}: 'Connect with squad'
   help: 'Show all commands organized by phase'
   status: 'Show current workflow phase'
   guide: 'Show comprehensive usage guide for this agent'

package/.aios-core/development/checklists/brownfield-compatibility-checklist.md

@@ -0,0 +1,114 @@
+# Brownfield Compatibility Checklist
+
+> Story AIOS-DIFF-4.3.2: Checklist formal de compatibilidade retroativa
+
+## Pre-Migration Compatibility Check
+
+### 1. Source Control Status
+- [ ] All changes committed to version control
+- [ ] Working branch created from main/master
+- [ ] Remote backup verified (push before migration)
+
+### 2. Existing Configuration Preservation
+- [ ] `.env` files backed up (never overwritten by AIOS)
+- [ ] `package.json` scripts preserved
+- [ ] Existing linting config (.eslintrc, .prettierrc) detected
+- [ ] CI/CD workflows (.github/workflows) inventoried
+
+### 3. Dependency Compatibility
+- [ ] Node.js version compatible (>=18)
+- [ ] No conflicting global dependencies
+- [ ] Lock file (package-lock.json/yarn.lock) preserved
+
+### 4. Directory Structure Analysis
+- [ ] `docs/` directory status checked (empty/existing)
+- [ ] `.aios-core/` not present (fresh install)
+- [ ] No naming conflicts with AIOS directories
+
+## During Migration Checks
+
+### 5. Non-Destructive Operations
+- [ ] AIOS creates new files, never overwrites existing
+- [ ] Merge conflicts surfaced for user decision
+- [ ] Original files preserved with `.backup` if conflict
+
+### 6. Configuration Merge Strategy
+- [ ] Existing `.gitignore` entries preserved + AIOS entries added
+- [ ] TypeScript config extended (not replaced) if existing
+- [ ] ESLint rules merged (not overwritten)
+
+### 7. Rollback Points
+- [ ] Pre-migration commit hash recorded
+- [ ] AIOS files clearly identified (can be removed cleanly)
+- [ ] No modifications to existing source code during install
+
+## Post-Migration Validation
+
+### 8. Existing Functionality
+- [ ] `npm test` passes (if tests existed before)
+- [ ] `npm run build` succeeds (if build existed)
+- [ ] Application starts normally
+
+### 9. AIOS Integration
+- [ ] `npx aios-core doctor` reports healthy
+- [ ] Agent activation works (@dev, @architect, etc.)
+- [ ] Existing docs not duplicated
+
+### 10. Rollback Verification
+- [ ] `git diff HEAD~1` shows only AIOS additions
+- [ ] `git checkout HEAD~1 -- .` would restore pre-AIOS state
+- [ ] No orphaned AIOS processes or files
+
+---
+
+## Compatibility Matrix
+
+| Existing Config | AIOS Behavior | User Action Required |
+|-----------------|---------------|---------------------|
+| `.eslintrc.*` | Detect + preserve | None |
+| `.prettierrc.*` | Detect + preserve | None |
+| `tsconfig.json` | Extend (not replace) | Review extends |
+| `jest.config.*` | Detect + preserve | None |
+| `docs/*.md` | Skip (don't overwrite) | Manual merge if needed |
+| `.github/workflows/*` | Inventory only | User decides integration |
+| `package.json` scripts | Preserve all | None |
+
+## Rollback Procedure
+
+If migration fails or is unwanted:
+
+```bash
+# Option 1: Full rollback to pre-migration state
+git checkout HEAD~1 -- .
+
+# Option 2: Remove only AIOS files
+rm -rf .aios-core/
+rm -rf docs/architecture/ docs/prd/ docs/stories/
+# Review and revert .gitignore AIOS entries
+
+# Option 3: Soft rollback (keep docs, remove runtime)
+rm -rf .aios-core/
+```
+
+---
+
+## Checklist Usage
+
+**Pre-Migration:**
+```bash
+# Run compatibility check
+npx aios-core doctor --pre-migration
+```
+
+**Post-Migration:**
+```bash
+# Validate migration
+npx aios-core doctor
+npm test  # if tests exist
+npm run build  # if build exists
+```
+
+---
+
+*AIOS Brownfield Compatibility Checklist v1.0*
+*Story AIOS-DIFF-4.3.2*

package/.aios-core/development/scripts/workflow-state-manager.js

@@ -17,13 +17,15 @@
  * - Each session picks up where the last left off via state file
  *
  * @module workflow-state-manager
- * @version 1.0.0
+ * @version 2.0.0
  */
 
 const fs = require('fs').promises;
 const path = require('path');
 const yaml = require('js-yaml');
 
+const WORKFLOW_STATE_VERSION = '2.0';
+
 class WorkflowStateManager {
   /**
    * @param {Object} [options={}]
@@ -64,6 +66,7 @@ class WorkflowStateManager {
     const instanceId = this._generateInstanceId(wf.id);
 
     const state = {
+      state_version: WORKFLOW_STATE_VERSION,
       workflow_id: wf.id,
       workflow_name: wf.name || wf.id,
       instance_id: instanceId,
@@ -137,6 +140,130 @@ class WorkflowStateManager {
     return state;
   }
 
+  // ============ Runtime-First Next Action ============
+
+  /**
+   * Build normalized execution state from runtime signals.
+   * Deterministic priority:
+   * blocked > qa_rejected > ci_red > completed > in_development > ready_for_validation > unknown
+   *
+   * @param {Object} [signals={}]
+   * @param {string} [signals.story_status]
+   * @param {string} [signals.qa_status]
+   * @param {string} [signals.ci_status]
+   * @param {boolean} [signals.has_uncommitted_changes]
+   * @returns {{ state: string, reasons: string[], normalized: Object }}
+   */
+  evaluateExecutionState(signals = {}) {
+    const storyStatus = String(signals.story_status || 'unknown').toLowerCase();
+    const qaStatus = String(signals.qa_status || 'unknown').toLowerCase();
+    const ciStatus = String(signals.ci_status || 'unknown').toLowerCase();
+    const hasUncommitted = Boolean(signals.has_uncommitted_changes);
+
+    const reasons = [];
+    let state = 'unknown';
+
+    if (storyStatus === 'blocked') {
+      state = 'blocked';
+      reasons.push('story status is blocked');
+    } else if (qaStatus === 'rejected' || qaStatus === 'fail' || qaStatus === 'failed') {
+      state = 'qa_rejected';
+      reasons.push(`qa status is ${qaStatus}`);
+    } else if (ciStatus === 'red' || ciStatus === 'failed' || ciStatus === 'error') {
+      state = 'ci_red';
+      reasons.push(`ci status is ${ciStatus}`);
+    } else if (storyStatus === 'done' || storyStatus === 'completed') {
+      state = 'completed';
+      reasons.push(`story status is ${storyStatus}`);
+    } else if (storyStatus === 'in_progress' || storyStatus === 'review') {
+      if (hasUncommitted) {
+        state = 'in_development';
+        reasons.push('story in progress with uncommitted changes');
+      } else {
+        state = 'ready_for_validation';
+        reasons.push('story in progress with clean working tree');
+      }
+    }
+
+    return {
+      state,
+      reasons,
+      normalized: {
+        story_status: storyStatus,
+        qa_status: qaStatus,
+        ci_status: ciStatus,
+        has_uncommitted_changes: hasUncommitted,
+      },
+    };
+  }
+
+  /**
+   * Deterministic next-action recommendation for runtime-first flows.
+   *
+   * @param {Object} [signals={}]
+   * @param {Object} [options={}]
+   * @param {string} [options.story]
+   * @returns {{ state: string, command: string, agent: string, rationale: string, confidence: number }}
+   */
+  getNextActionRecommendation(signals = {}, options = {}) {
+    const result = this.evaluateExecutionState(signals);
+    const storyArg = options.story ? ` ${options.story}` : '';
+
+    const map = {
+      blocked: {
+        command: `*orchestrate-status${storyArg}`,
+        agent: '@po',
+        rationale: 'Story is blocked. Surface blockers and unblock path first.',
+        confidence: 0.95,
+      },
+      qa_rejected: {
+        command: `*apply-qa-fixes${storyArg}`,
+        agent: '@dev',
+        rationale: 'QA rejected the story. Apply fixes before progressing.',
+        confidence: 0.95,
+      },
+      ci_red: {
+        command: '*run-tests',
+        agent: '@dev',
+        rationale: 'CI is red. Reproduce and fix failing tests/checks first.',
+        confidence: 0.92,
+      },
+      completed: {
+        command: `*close-story${storyArg}`,
+        agent: '@po',
+        rationale: 'Story is complete. Close lifecycle and move to next item.',
+        confidence: 0.9,
+      },
+      in_development: {
+        command: '*run-tests',
+        agent: '@dev',
+        rationale: 'Code is in progress with local changes. Validate before QA handoff.',
+        confidence: 0.85,
+      },
+      ready_for_validation: {
+        command: `*review-build${storyArg}`,
+        agent: '@qa',
+        rationale: 'Development appears stable. Proceed to QA structured review.',
+        confidence: 0.82,
+      },
+      unknown: {
+        command: `*next${storyArg}`,
+        agent: '@dev',
+        rationale: 'Context is incomplete. Request explicit workflow guidance.',
+        confidence: 0.4,
+      },
+    };
+
+    const recommendation = map[result.state] || map.unknown;
+    return {
+      state: result.state,
+      command: recommendation.command,
+      agent: recommendation.agent,
+      rationale: recommendation.rationale,
+      confidence: recommendation.confidence,
+    };
+  }
+
   /**
    * Load state from file
    * @param {string} instanceId

package/.aios-core/development/tasks/next.md

@@ -4,6 +4,9 @@
 
 Suggest next commands based on current workflow context using the Workflow Intelligence System (WIS). Helps users navigate workflows efficiently without memorizing command sequences.
 
+AIOS 4.0.4 runtime-first mode adds deterministic next-step recommendation from
+execution signals (story/qa/ci/diff) via `workflow-state-manager`.
+
 ## Task Definition (AIOS Task Format V1.0)
 
 ```yaml
@@ -88,7 +91,23 @@ const context = await engine.buildContext({
 });
 ```
 
-### Step 3: Get Suggestions
+### Step 3: Runtime-First Deterministic Recommendation (Preferred)
+```javascript
+const { WorkflowStateManager } = require('.aios-core/development/scripts/workflow-state-manager');
+const manager = new WorkflowStateManager();
+
+const runtimeNext = manager.getNextActionRecommendation(
+  {
+    story_status: context.projectState?.storyStatus || 'unknown',
+    qa_status: context.projectState?.qaStatus || 'unknown',
+    ci_status: context.projectState?.ciStatus || 'unknown',
+    has_uncommitted_changes: context.projectState?.hasUncommittedChanges || false,
+  },
+  { story: args.story || context.storyPath || '' },
+);
+```
+
+### Step 4: Get WIS Suggestions (Fallback / enrichment)
 ```javascript
 const result = await engine.suggestNext(context);
 
@@ -103,15 +122,27 @@ const result = await engine.suggestNext(context);
 // }
 ```
 
-### Step 4: Format Output
+### Step 5: Format Output
 ```javascript
 const formatter = require('.aios-core/workflow-intelligence/engine/output-formatter');
 
-// Limit to top 3 unless --all flag
-const displaySuggestions = args.all ? result.suggestions : result.suggestions.slice(0, 3);
+const runtimeSuggestion = {
+  command: runtimeNext.command,
+  args: '',
+  description: runtimeNext.rationale,
+  confidence: runtimeNext.confidence,
+  priority: 1,
+};
+const mergedSuggestions = [runtimeSuggestion, ...(result.suggestions || [])];
+const displaySuggestions = args.all ? mergedSuggestions : mergedSuggestions.slice(0, 3);
 
 // Display formatted output
-formatter.displaySuggestions(result.workflow, result.currentState, result.confidence, displaySuggestions);
+formatter.displaySuggestions({
+  workflow: result.workflow || 'runtime_first',
+  currentState: runtimeNext.state,
+  confidence: runtimeNext.confidence,
+  suggestions: displaySuggestions,
+});
 ```
 
 ---

package/.aios-core/hooks/ids-post-commit.js

@@ -15,6 +15,25 @@ const path = require('path');
 
 const REPO_ROOT = path.resolve(__dirname, '../..');
 
+function isDocsOnlyPath(relativePath) {
+  const p = String(relativePath || '').replace(/\\/g, '/');
+  if (!p) return false;
+
+  if (p.startsWith('docs/')) return true;
+  if (p === 'README.md') return true;
+  if (p === 'CHANGELOG.md') return true;
+  if (p === 'CONTRIBUTING.md') return true;
+  if (p === 'CODE_OF_CONDUCT.md') return true;
+  if (p === 'AGENTS.md') return true;
+
+  return false;
+}
+
+function isDocsOnlyCommit(changes) {
+  if (!Array.isArray(changes) || changes.length === 0) return false;
+  return changes.every((c) => isDocsOnlyPath(c.relativePath));
+}
+
 function getChangedFilesFromLastCommit() {
   try {
     const output = execSync('git diff-tree --no-commit-id --name-status -r HEAD', {
@@ -52,7 +71,11 @@ function getChangedFilesFromLastCommit() {
       }
 
       if (!filePath) continue;
-      changes.push({ action, filePath: path.resolve(REPO_ROOT, filePath) });
+      changes.push({
+        action,
+        relativePath: filePath,
+        filePath: path.resolve(REPO_ROOT, filePath),
+      });
     }
 
     return changes;
@@ -67,6 +90,11 @@ async function main() {
 
   if (changes.length === 0) return;
 
+  if (process.env.AIOS_IDS_FORCE !== '1' && isDocsOnlyCommit(changes)) {
+    console.log('[IDS-Hook] Docs-only commit detected, skipping registry update.');
+    return;
+  }
+
   try {
     const { RegistryUpdater } = require(path.resolve(REPO_ROOT, '.aios-core/core/ids/registry-updater.js'));
     const updater = new RegistryUpdater();

package/.aios-core/hooks/ids-pre-push.js

@@ -16,6 +16,25 @@ const path = require('path');
 
 const REPO_ROOT = path.resolve(__dirname, '../..');
 
+function isDocsOnlyPath(relativePath) {
+  const p = String(relativePath || '').replace(/\\/g, '/');
+  if (!p) return false;
+
+  if (p.startsWith('docs/')) return true;
+  if (p === 'README.md') return true;
+  if (p === 'CHANGELOG.md') return true;
+  if (p === 'CONTRIBUTING.md') return true;
+  if (p === 'CODE_OF_CONDUCT.md') return true;
+  if (p === 'AGENTS.md') return true;
+
+  return false;
+}
+
+function isDocsOnlyPush(changes) {
+  if (!Array.isArray(changes) || changes.length === 0) return false;
+  return changes.every((c) => isDocsOnlyPath(c.relativePath));
+}
+
 function getChangedFilesSinceRemote() {
   try {
     const trackingBranch = execSync('git rev-parse --abbrev-ref --symbolic-full-name @{u}', {
@@ -58,7 +77,11 @@ function getChangedFilesSinceRemote() {
       }
 
       if (!filePath) continue;
-      changes.push({ action, filePath: path.resolve(REPO_ROOT, filePath) });
+      changes.push({
+        action,
+        relativePath: filePath,
+        filePath: path.resolve(REPO_ROOT, filePath),
+      });
     }
 
     return changes;
@@ -76,6 +99,11 @@ async function main() {
     process.exit(0);
   }
 
+  if (process.env.AIOS_IDS_FORCE !== '1' && isDocsOnlyPush(changes)) {
+    console.log('[IDS-Hook] Docs-only push detected, skipping registry update.');
+    process.exit(0);
+  }
+
   try {
     const { RegistryUpdater } = require(path.resolve(REPO_ROOT, '.aios-core/core/ids/registry-updater.js'));
     const updater = new RegistryUpdater();

package/.aios-core/infrastructure/contracts/compatibility/aios-4.0.4.yaml

@@ -0,0 +1,44 @@
+release: "AIOS 4.0.4"
+updated_at: "2026-02-16"
+source_of_truth:
+  docs_matrix: "docs/ide-integration.md"
+  validator: ".aios-core/infrastructure/scripts/validate-parity.js"
+
+global_required_checks:
+  - paths
+
+ide_matrix:
+  - ide: "claude-code"
+    display_name: "Claude Code"
+    expected_status: "Works"
+    required_checks:
+      - claude-sync
+      - claude-integration
+  - ide: "gemini"
+    display_name: "Gemini CLI"
+    expected_status: "Works"
+    required_checks:
+      - gemini-sync
+      - gemini-integration
+  - ide: "codex"
+    display_name: "Codex CLI"
+    expected_status: "Limited"
+    required_checks:
+      - codex-sync
+      - codex-integration
+      - codex-skills
+  - ide: "cursor"
+    display_name: "Cursor"
+    expected_status: "Limited"
+    required_checks:
+      - cursor-sync
+  - ide: "github-copilot"
+    display_name: "GitHub Copilot"
+    expected_status: "Limited"
+    required_checks:
+      - github-copilot-sync
+  - ide: "antigravity"
+    display_name: "AntiGravity"
+    expected_status: "Limited"
+    required_checks:
+      - antigravity-sync