aios-core 4.2.15 → 4.4.0

package/.aios-core/development/tasks/health-check.yaml

@@ -1,15 +1,18 @@
 ---
 # Health Check Task Definition
-# Story: HCS-2 - Health Check System Implementation
-# Version: 1.0.0
+# Story: INS-4.8 - Unify Health-Check + Doctor v2
+# Version: 3.0.0 — Delegates to `aios doctor --json` (unified)
 
 name: health-check
 id: health-check
-version: "2.0"
+version: "3.0"
 description: |
-  Run comprehensive health checks on your AIOS project.
-  Diagnoses configuration issues, environment problems, and provides
-  auto-fixing for common issues.
+  Unified health diagnostic for AIOS projects.
+  Invokes `aios doctor --json` internally via Bash tool and adds governance
+  interpretation with Constitution context and remediation guidance.
+
+  NOTE: This task delegates ALL check logic to `aios doctor` (15 checks).
+  It does NOT have its own list of health checks — single source of truth.
 
 category: development
 owner: devops
@@ -18,168 +21,204 @@ owner: devops
 command: "*health-check"
 aliases:
   - "*hc"
-  - "*doctor"
+# NOTE: *doctor alias REMOVED (INS-4.8) to avoid confusion with CLI `aios 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
+    default: false
+    description: "Pass --fix to aios doctor for auto-remediation"
 
   - name: verbose
     type: boolean
     default: false
-    description: "Show all checks, not just issues"
+    description: "Show all checks including passed ones"
 
-  - name: save
-    type: boolean
-    default: false
-    description: "Save report to .aios/reports/health-check-latest.json"
-
-# Execution steps
-steps:
-  - id: initialize
-    name: "Initialize Health Check"
-    action: log
-    params:
-      message: "🏥 Starting AIOS 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(), '.aios', '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}}
+# 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 aios doctor --json
+
+  Use the Bash tool to run:
+
+  ```bash
+  node bin/aios.js doctor --json
+  ```
+
+  If `--fix` was requested, run instead:
+
+  ```bash
+  node bin/aios.js doctor --json --fix
+  ```
+
+  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": "aios 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
+  ## AIOS 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: "aios doctor --fix"
+
+  rules-files:
+    article: "II"
+    article_name: "Agent Authority"
+    governance_note: "Agent authority rules provide behavioral constraints"
+    remediation: "aios doctor --fix"
+
+  agent-memory:
+    article: "II"
+    article_name: "Agent Authority"
+    governance_note: "Agent identity persistence across sessions"
+    remediation: "aios doctor --fix"
+
+  entity-registry:
+    article: "III"
+    article_name: "Story-Driven Development"
+    governance_note: "Code intelligence registry for entity-aware development"
+    remediation: "aios doctor --fix"
+
+  git-hooks:
+    article: "V"
+    article_name: "Quality First"
+    governance_note: "Quality gates enforced at git operations"
+    remediation: "aios doctor --fix"
+
+  core-config:
+    article: "I"
+    article_name: "CLI First"
+    governance_note: "Configuration integrity — core-config.yaml drives CLI behavior"
+    remediation: "aios doctor --fix"
+
+  claude-md:
+    article: "II"
+    article_name: "Agent Authority"
+    governance_note: "Agent context — CLAUDE.md provides system prompt foundation"
+    remediation: "aios doctor --fix"
+
+  ide-sync:
+    article: "II"
+    article_name: "Agent Authority"
+    governance_note: "Agent consistency across IDE configurations"
+    remediation: "aios 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: "aios 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 aios-core install --force"
+
+  commands-count:
+    article: "II"
+    article_name: "Agent Authority"
+    governance_note: "Agent action vocabulary — commands define what agents can do"
+    remediation: "npx aios-core install --force"
+
+  hooks-claude-count:
+    article: "V"
+    article_name: "Quality First"
+    governance_note: "Quality gates — hooks enforce governance at runtime"
+    remediation: "npx aios-core install --force"
 
 # Output schema
 output:
   type: object
   properties:
-    score:
-      type: number
-      description: "Overall health score (0-100)"
-    status:
+    summary:
       type: string
-      description: "Health status: healthy, degraded, warning, critical"
+      description: "PASS/WARN/FAIL count summary"
     issues:
-      type: number
-      description: "Number of issues found"
-    autoFixed:
-      type: number
-      description: "Number of issues auto-fixed"
+      type: array
+      description: "List of FAIL and WARN items with governance context"
+    report:
+      type: string
+      description: "Full markdown report"
 
 # Examples
 examples:
-  - name: "Quick check"
+  - name: "Quick health 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"
+    description: "Run all 15 doctor checks with governance interpretation"
 
-  - 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: "Health check with auto-fix"
+    command: "*health-check --fix"
+    description: "Run checks and auto-fix where possible"
 
   - name: "Verbose output"
     command: "*health-check --verbose"
@@ -187,40 +226,36 @@ examples:
 
 # Help text
 help: |
-  ## AIOS Health Check
-
-  Diagnoses issues in your AIOS project across 5 domains:
+  ## AIOS Health Check (Unified)
 
-  - **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
+  Runs `aios doctor --json` internally and adds governance context.
+  15 checks across configuration, environment, and agent readiness.
 
   ### Quick Start
 
   ```bash
-  *health-check              # Quick check
-  *health-check --mode=full  # Full check
+  *health-check              # Run all checks
+  *health-check --fix        # Auto-fix issues
+  *health-check --verbose    # Show all checks
   ```
 
-  ### Auto-Fixing
+  ### What It Checks
 
-  Issues are classified into 3 tiers:
-  - **Tier 1**: Auto-fixed silently (safe, reversible)
-  - **Tier 2**: Prompted for confirmation
-  - **Tier 3**: Manual guide provided
+  The task delegates to `aios 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.
 
-  ### Output Formats
+  ### Governance Interpretation
 
-  - `console`: Colorful terminal output
-  - `markdown`: GitHub-compatible markdown
-  - `json`: Machine-readable JSON
+  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
 
-  ### Examples
+  ### Relationship to Other Tools
 
-  ```bash
-  *health-check --domain=repository --verbose
-  *health-check --fix-tier=2 --save
-  *hc --mode=full --output=markdown
-  ```
+  - `aios 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/.aios-core/development/tasks/kb-mode-interaction.md

@@ -235,7 +235,7 @@ Offer a concise list of main topic areas the user might want to explore:
 7. **Configuration** - Customizing AIOS for your needs
 8. **Best Practices** - Tips for effective AIOS usage
 
-Or ask me about anything else related to @synkra/aios-core!
+Or ask me about anything else related to aios-core!
 
 ### 3. Respond Contextually
 
@@ -263,7 +263,7 @@ When user is done or wants to exit KB mode:
 
 **User**: *kb-mode
 
-**Assistant**: I've entered KB mode and have access to the full AIOS knowledge base. I can help you with detailed information about any aspect of @synkra/aios-core.
+**Assistant**: I've entered KB mode and have access to the full AIOS knowledge base. I can help you with detailed information about any aspect of aios-core.
 
 **What would you like to know more about?**
 
@@ -276,7 +276,7 @@ When user is done or wants to exit KB mode:
 7. **Configuration** - Customizing AIOS for your needs
 8. **Best Practices** - Tips for effective AIOS usage
 
-Or ask me about anything else related to @synkra/aios-core!
+Or ask me about anything else related to aios-core!
 
 **User**: Tell me about workflows
 

package/.aios-core/development/tasks/plan-create-context.md

@@ -272,6 +272,52 @@ scope_analysis:
         4. Note exemplar implementations
 ```
 
+### Step 3.5: Code Intelligence: Implementation Context (Optional — Auto-skip if unavailable)
+
+> **Condition:** Only execute if `isCodeIntelAvailable()` returns true.
+> If no code intelligence provider is available, skip this step silently and proceed to Step 4.
+
+When code intelligence is available, enrich the context with real symbol definitions, dependencies, and test references:
+
+```javascript
+const { isCodeIntelAvailable } = require('.aios-core/core/code-intel');
+const { getImplementationContext } = require('.aios-core/core/code-intel/helpers/planning-helper');
+
+if (isCodeIntelAvailable()) {
+  // Extract key symbols from story analysis (step 3)
+  const symbols = extractedComponents; // From step 3 scope analysis
+
+  const context = await getImplementationContext(symbols);
+
+  // Enrich files-context.yaml with:
+  // - context.definitions: exact file + line for each symbol definition
+  // - context.dependencies: dependency graph per symbol
+  // - context.relatedTests: test files referencing each symbol
+}
+```
+
+**If data is available, add to files-context.yaml:**
+
+```yaml
+codeIntelligence:
+  definitions:
+    - symbol: '{symbol}'
+      file: '{definition.file}'
+      line: {definition.line}
+  dependencies:
+    - symbol: '{symbol}'
+      deps: {dependency graph}
+  relatedTests:
+    - symbol: '{symbol}'
+      tests:
+        - file: '{test.file}'
+          line: {test.line}
+```
+
+> **Note:** Partial results are accepted — if findDefinition succeeds but analyzeDependencies fails for a symbol, the definition is still included.
+
+---
+
 ### Step 4: Generate Outputs
 
 ```yaml
@@ -666,7 +712,7 @@ errors:
 
 ```yaml
 project:
-  name: '@synkra/aios-core'
+  name: 'aios-core'
   version: '2.3.0'
   type: EXISTING_AIOS
 

package/.aios-core/development/tasks/plan-create-implementation.md

@@ -438,6 +438,61 @@ build_plan:
             notes: "{optional context for coder}"
 ```
 
+### Step 6.5: Code Intelligence: Impact Analysis (Optional — Auto-skip if unavailable)
+
+> **Condition:** Only execute if `isCodeIntelAvailable()` returns true.
+> If no code intelligence provider is available, skip this step silently and proceed to Step 7.
+
+When code intelligence is available, enrich each subtask with blast radius and risk assessment:
+
+```javascript
+const { isCodeIntelAvailable } = require('.aios-core/core/code-intel');
+const { getImplementationImpact } = require('.aios-core/core/code-intel/helpers/planning-helper');
+
+if (isCodeIntelAvailable()) {
+  // For each subtask, analyze the files it modifies
+  for (const subtask of allSubtasks) {
+    const impact = await getImplementationImpact(subtask.files);
+    if (impact) {
+      subtask.codeIntelligence = {
+        blastRadius: impact.blastRadius,
+        riskLevel: impact.riskLevel, // 'LOW' | 'MEDIUM' | 'HIGH'
+        references: impact.references,
+      };
+
+      // If HIGH risk, add warning note to subtask
+      if (impact.riskLevel === 'HIGH') {
+        subtask.notes = (subtask.notes || '') +
+          ` ⚠️ HIGH blast radius (${impact.blastRadius} refs) — consider additional review.`;
+      }
+    }
+  }
+}
+```
+
+**If data is available, add to each subtask in implementation.yaml:**
+
+```yaml
+subtasks:
+  - id: '1.1'
+    description: '...'
+    codeIntelligence:
+      blastRadius: 12
+      riskLevel: 'MEDIUM'
+      references:
+        - file: 'src/module-a.js'
+        - file: 'tests/module-a.test.js'
+```
+
+**Risk Level Thresholds:**
+- **LOW:** 0-4 references affected
+- **MEDIUM:** 5-15 references affected
+- **HIGH:** >15 references affected — add risk note to subtask
+
+> **Note:** Risk data is advisory. It enriches the plan but does not block execution.
+
+---
+
 ### Step 7: Validate Plan
 
 ```yaml

package/.aios-core/development/tasks/po-close-story.md

@@ -425,3 +425,10 @@ updated_at: 2026-02-05
 - `validate-next-story.md` - Validates story before implementation (START)
 - `po-close-story.md` - Closes story after merge (END)
 - `po-backlog-review.md` - Review backlog for sprint planning
+
+## Handoff
+next_agent: @sm
+next_command: *draft
+condition: Story closed, next story in epic available
+alternatives:
+  - agent: @po, command: *backlog-review, condition: Sprint review needed before next story

package/.aios-core/development/tasks/pr-automation.md

@@ -16,9 +16,9 @@ checklists:
 
 ## Purpose
 
-To help users contribute to the AIOS open-source project (`@synkra/aios-core`) by automating the PR creation process, ensuring contributions follow project standards, pass quality checks, and have proper formatting before submission.
+To help users contribute to the AIOS open-source project (`aios-core`) by automating the PR creation process, ensuring contributions follow project standards, pass quality checks, and have proper formatting before submission.
 
-**Target Repository**: `@synkra/aios-core` (open-source framework)
+**Target Repository**: `aios-core` (open-source framework)
 
 **Contribution Types Supported**:
 - Squads (new agents, tasks, workflows)
@@ -102,7 +102,7 @@ To help users contribute to the AIOS open-source project (`@synkra/aios-core`) b
    - Ensure naming conventions followed
 
 2. **Validate Repository State**
-   - Check if `@synkra/aios-core` repository is set as upstream
+   - Check if `aios-core` repository is set as upstream
    - Verify fork exists (or create one)
    - Ensure main branch is up-to-date
 
@@ -303,8 +303,8 @@ To help users contribute to the AIOS open-source project (`@synkra/aios-core`) b
   - **Validation**: Files at `contribution_path` exist
   - **Error**: "Files not found at {contribution_path}"
 
-- [ ] Fork of @synkra/aios-core exists
-  - **Validation**: `gh repo view {user}/@synkra/aios-core` succeeds
+- [ ] Fork of aios-core exists
+  - **Validation**: `gh repo view {user}/aios-core` succeeds
   - **Action**: If not found, create fork automatically
 
 - [ ] Main branch is up-to-date

package/.aios-core/development/tasks/qa-create-fix-request.md

@@ -621,3 +621,10 @@ This task is complete when:
 - Constraints section present
 - File follows template structure
 ```
+
+## Handoff
+next_agent: @dev
+next_command: *fix-qa-issues
+condition: QA_FIX_REQUEST.md generated
+alternatives:
+  - agent: @dev, command: *apply-qa-fixes, condition: Simple fixes, no structured request needed

package/.aios-core/development/tasks/qa-fix-issues.md

@@ -683,3 +683,10 @@ metadata:
     - quality-assurance
     - development
 ```
+
+## Handoff
+next_agent: @qa
+next_command: *review {story-id}
+condition: All QA_FIX_REQUEST issues resolved
+alternatives:
+  - agent: @dev, command: *run-tests, condition: Verify fixes pass before re-review