aios-core 4.2.15 → 4.4.0

package/.aios-core/development/tasks/review-contributor-pr.md

@@ -0,0 +1,152 @@
+# Task: Review External Contributor PR
+
+## Metadata
+
+```yaml
+id: review-contributor-pr
+agent: devops
+elicit: true
+category: security
+priority: high
+story: NOG-17
+```
+
+## Description
+
+Formal security review process for external contributor PRs before merging. This task ensures PRs from fork contributors are reviewed for security risks not present in internal team PRs.
+
+## Pre-Conditions
+
+- PR is from an external contributor (fork-based)
+- PR has passed automated CI checks (or CI was skipped due to fork restrictions)
+- CodeRabbit review completed (check for hidden content in PR description)
+
+## Inputs
+
+- `{pr_number}` - GitHub PR number to review
+
+## Execution
+
+### Step 1: Identify PR Scope
+
+```bash
+# Get PR details
+gh pr view {pr_number} --json files,additions,deletions,author,body
+
+# Classify PR type
+# CI/Workflow = .github/
+# Test = tests/
+# Code = packages/, .aios-core/, bin/
+# Config = .gitmodules, *.config.*
+# Docs = docs/, *.md
+```
+
+**Elicit:** "PR #{pr_number} classified as: {type}. Proceeding with {type} security checklist."
+
+### Step 2: Security Checklist (by PR type)
+
+#### For CI/Workflow PRs (.github/)
+
+- [ ] No `pull_request_target` with explicit checkout added
+- [ ] No new secrets references (`${{ secrets.* }}`)
+- [ ] No permission escalation (`permissions: write-all`, `contents: write` where unnecessary)
+- [ ] Action versions use known, trusted publishers
+- [ ] Action versions are SHA-pinned (not tag-based)
+- [ ] No `workflow_dispatch` with dangerous inputs
+- [ ] No new `env:` blocks exposing sensitive data
+
+#### For Test PRs (tests/)
+
+- [ ] No `require('https')`, `require('http')`, `require('net')`, `require('dns')` imports
+- [ ] No `fetch()`, `XMLHttpRequest`, or network calls
+- [ ] No `fs.readFileSync` outside test fixtures
+- [ ] No `process.env` access to sensitive variables
+- [ ] No `child_process` usage (`execSync`, `spawn`, etc.)
+- [ ] `require()` paths point to legitimate project modules only
+- [ ] No exfiltration patterns (base64 encoding + network call)
+
+#### For Code PRs (packages/, .aios-core/, bin/)
+
+- [ ] No new dependencies added without justification
+- [ ] No changes to `package.json` scripts (`preinstall`, `postinstall`)
+- [ ] No `.env` file reads or credential handling changes
+- [ ] No `shell: true` in any exec/spawn calls
+- [ ] No string-based command construction (use array args)
+- [ ] CodeRabbit review completed (check for hidden content in PR description)
+
+#### For Config PRs (.gitmodules, *.config.*)
+
+- [ ] No URL changes to external/unknown repositories
+- [ ] No new submodule additions
+- [ ] Config values are expected and documented
+- [ ] No hooks modifications that could alter behavior
+
+### Step 3: Automated Scan
+
+Run the appropriate grep command based on PR type:
+
+```bash
+# For test PRs - check for suspicious patterns
+gh pr diff {pr_number} -- 'tests/' | grep -E "(require\('https|require\('http|require\('net|require\('dns|fetch\(|\.readFileSync|process\.env|child_process|execSync|spawn)"
+
+# For code PRs - check for shell execution patterns
+gh pr diff {pr_number} -- 'packages/' '.aios-core/' 'bin/' | grep -E "(shell:\s*true|execSync\(|\.exec\(|eval\(|Function\()"
+
+# For CI PRs - check for permission/secret changes
+gh pr diff {pr_number} -- '.github/' | grep -E "(permissions:|secrets\.|pull_request_target|workflow_dispatch)"
+
+# For any PR - check for hidden content in PR body
+gh pr view {pr_number} --json body --jq '.body' | grep -iE "(<picture|<source|<img.*onerror|<!--.*ignore.*instruct)"
+```
+
+**Elicit:** "Scan results: {summary}. {findings_count} suspicious patterns found."
+
+### Step 4: Decision Matrix
+
+| PR Changes | Risk Level | Required Actions |
+|-----------|-----------|-----------------|
+| Documentation only | LOW | Standard review |
+| Test files only | MEDIUM | Security scan + grep |
+| Source code | MEDIUM-HIGH | Security scan + careful review |
+| CI/Workflows | HIGH | Security scan + SHA audit + 2 approvals |
+| package.json | HIGH | Block until verified |
+| .gitmodules | MEDIUM | URL verification required |
+| Config files | MEDIUM | Value verification required |
+
+### Step 5: Merge Decision
+
+**Elicit:** Present checklist results and ask for confirmation:
+
+```
+## Contributor PR Security Review Summary
+
+**PR:** #{pr_number}
+**Author:** {author} (external contributor)
+**Type:** {pr_type}
+**Files Changed:** {file_count}
+
+### Checklist Results
+- Security scan: {PASS|WARN|FAIL}
+- Automated grep: {PASS|WARN|FAIL}
+- CodeRabbit: {APPROVED|CHANGES_REQUESTED|PENDING}
+- Hidden content check: {CLEAN|SUSPICIOUS}
+
+### Recommendation
+{APPROVE|APPROVE_WITH_NOTES|REQUEST_CHANGES|BLOCK}
+
+Proceed with merge? (y/n)
+```
+
+## Post-Conditions
+
+- PR reviewed with security checklist appropriate to its type
+- Automated scan completed with no unresolved findings
+- Decision logged (approve, request changes, or block)
+- If merged: enforce_admins temporarily disabled if needed, then re-enabled
+
+## Notes
+
+- For PRs that modify `.github/workflows/`, require 2 maintainer approvals
+- For PRs from **trusted contributors** (e.g., @riaworks with prior merged security PRs), standard review may suffice for docs/test PRs
+- Always re-enable enforce_admins immediately after merge
+- Reference research: `docs/research/2026-02-21-ci-security-external-prs/`

package/.aios-core/development/tasks/setup-llm-routing.md

@@ -210,7 +210,7 @@ claude-free
 ```yaml
 story: "6.7"
 version: 1.1.0
-migrated_from: @synkra/aios-core
+migrated_from: aios-core
 dependencies:
   - install-llm-routing.js
   - llm-routing.yaml

package/.aios-core/development/tasks/spec-critique.md

@@ -593,3 +593,11 @@ metadata:
     - quality-gate
     - qa
 ```
+
+## Handoff
+next_agent: @architect
+next_command: *plan
+condition: Critique verdict is APPROVED
+alternatives:
+  - agent: @pm, command: *write-spec, condition: Critique verdict is NEEDS_REVISION
+  - agent: @architect, command: *analyze-impact, condition: Critique verdict is BLOCKED

package/.aios-core/development/tasks/spec-gather-requirements.md

@@ -543,3 +543,10 @@ metadata:
     - sdd-adoption
   inspiration: GitHub Spec-Kit 9-category taxonomy
 ```
+
+## Handoff
+next_agent: @architect
+next_command: *analyze-impact
+condition: Requirements gathered (requirements.json created)
+alternatives:
+  - agent: @pm, command: *write-spec, condition: SIMPLE complexity, skip assessment

package/.aios-core/development/tasks/spec-research-dependencies.md

@@ -1,5 +1,9 @@
 # Spec Pipeline: Research Dependencies
 
+---
+execution_mode: programmatic  # TOK-3: PTC-eligible (Bash batch) — multi-search + filter in single block
+---
+
 > **Phase:** 3 - Research
 > **Owner Agent:** @analyst
 > **Pipeline:** spec-pipeline

package/.aios-core/development/tasks/spec-write-spec.md

@@ -529,3 +529,8 @@ metadata:
     - documentation
     - prompt-engineering
 ```
+
+## Handoff
+next_agent: @qa
+next_command: *critique-spec {story-id}
+condition: Spec written (spec.md created)

package/.aios-core/development/tasks/triage-github-issues.md

@@ -0,0 +1,356 @@
+# triage-github-issues.md
+
+**Task**: GitHub Issues Triage & Prioritization
+
+**Purpose**: Analyze open GitHub issues, classify by type/severity/effort, prioritize based on impact, and recommend resolution order to the user.
+
+**When to use**: Periodically or when user asks to review the issue backlog, via `@devops *triage-issues` or user request like "what issues should we resolve next?".
+
+## Execution Modes
+
+**Choose your execution mode:**
+
+### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
+- Fetch, classify, and present prioritized list
+- Minimal user interaction
+- **Best for:** Quick overview of issue backlog
+
+### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
+- Present classification, ask user for priority adjustments
+- Discuss trade-offs between quick wins vs high-impact
+- **Best for:** Sprint planning, deciding next work
+
+### 3. Pre-Flight Planning - Comprehensive Upfront Planning
+- Deep analysis of each issue with cross-references
+- Dependency mapping between issues
+- **Best for:** Major backlog grooming sessions
+
+**Parameter:** `mode` (optional, default: `interactive`)
+
+---
+
+## Task Definition (AIOS Task Format V1.0)
+
+```yaml
+task: triageGithubIssues()
+responsavel: Gage (Operator)
+responsavel_type: Agente
+atomic_layer: Organism
+
+**Entrada:**
+- campo: filters
+  tipo: object
+  origem: User Input
+  obrigatorio: false
+  validacao: |
+    Optional filters: { state: 'open', labels: [], assignee: '', limit: 30 }
+  default: { state: 'open', limit: 30 }
+
+- campo: mode
+  tipo: string
+  origem: User Input
+  obrigatorio: false
+  validacao: yolo|interactive|pre-flight
+
+**Saida:**
+- campo: triage_report
+  tipo: object
+  destino: User Display
+  persistido: false
+  formato: |
+    Tabela priorizada com: issue#, titulo, tipo, severidade, esforco, recomendacao
+
+- campo: recommended_next
+  tipo: array
+  destino: User Display
+  persistido: false
+  formato: |
+    Top 3-5 issues recomendados para resolver em ordem
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] GitHub CLI authenticated (gh auth status)
+    tipo: pre-condition
+    blocker: true
+    validacao: |
+      Run: gh auth status
+      Must show authenticated user
+    error_message: "GitHub CLI not authenticated. Run: gh auth login"
+
+  - [ ] Repository has GitHub remote configured
+    tipo: pre-condition
+    blocker: true
+    validacao: |
+      Run: git remote -v
+      Must show github.com remote
+    error_message: "No GitHub remote found. Add with: git remote add origin <url>"
+```
+
+---
+
+## Workflow Steps
+
+### Phase 1: Fetch Issues
+
+```bash
+# Fetch all open issues with labels and metadata
+gh issue list --state open --limit 50 --json number,title,labels,createdAt,updatedAt,comments,assignees,milestone
+
+# Also check for stale issues (>90 days without activity)
+gh issue list --state open --limit 50 --json number,title,updatedAt --jq '.[] | select(.updatedAt < (now - 7776000 | todate))'
+```
+
+### Phase 2: Classify Each Issue
+
+For each issue, determine:
+
+| Dimension | Values | How to Determine |
+|-----------|--------|-----------------|
+| **Type** | BUG, FEATURE, ENHANCEMENT, DOCS, CHORE, SECURITY | From labels + title keywords + issue body |
+| **Severity** | P0-Critical, P1-High, P2-Medium, P3-Low, P4-Cosmetic | Impact on users, workaround availability |
+| **Effort** | XS (<1h), S (1-4h), M (4-8h), L (1-2d), XL (>2d) | Files affected, complexity, research needed |
+| **Impact** | HIGH, MEDIUM, LOW | Users affected x frequency x severity |
+| **Quick Win** | YES/NO | Effort <= S AND Severity >= P2 |
+
+**Classification Heuristics:**
+
+```yaml
+type_detection:
+  BUG: title contains "bug", "broken", "error", "fix", "crash", "fail"
+  SECURITY: title contains "security", "vulnerability", "CVE", labels include "security"
+  DOCS: title contains "docs", "documentation", "readme", labels include "documentation"
+  CHORE: title contains "chore", "cleanup", "refactor", "rename", "update"
+  FEATURE: title contains "feat", "add", "implement", "new"
+  ENHANCEMENT: title contains "improve", "enhance", "optimize", "better"
+
+severity_detection:
+  P0: labels include "critical", body mentions "production down" or "data loss"
+  P1: labels include "high", "important", type is SECURITY
+  P2: labels include "medium", type is BUG without workaround
+  P3: labels include "low", type is ENHANCEMENT
+  P4: type is DOCS or CHORE with no user impact
+
+effort_estimation:
+  - Read issue body for scope indicators
+  - Check if issue references specific files/modules
+  - Check if similar issues were resolved (time taken)
+  - Consider: research needed? multiple files? tests required? installer changes?
+```
+
+### Phase 3: Prioritize
+
+**Priority Score Formula:**
+
+```
+priority_score = (severity_weight * 3) + (impact_weight * 2) + (quick_win_bonus) - (effort_penalty)
+
+severity_weight: P0=10, P1=8, P2=5, P3=3, P4=1
+impact_weight: HIGH=10, MEDIUM=5, LOW=2
+quick_win_bonus: YES=5, NO=0
+effort_penalty: XS=0, S=1, M=3, L=5, XL=8
+```
+
+**Priority Tiers:**
+
+| Tier | Score Range | Action |
+|------|------------|--------|
+| **NOW** | >= 30 | Resolve immediately (P0/P1, security) |
+| **NEXT** | 20-29 | Resolve in current sprint |
+| **SOON** | 10-19 | Schedule for next sprint |
+| **BACKLOG** | < 10 | Keep in backlog, review monthly |
+
+### Phase 4: Present to User
+
+**Output Format:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+GitHub Issues Triage Report
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Repository: {owner}/{repo}
+Open Issues: {count}
+Date: {date}
+
+NOW (resolve immediately):
+  #123 [BUG/P1] Agent files not recognized by Copilot    S  ← Quick Win
+  #456 [SECURITY/P0] Exposed credentials in config       M
+
+NEXT (current sprint):
+  #789 [BUG/P2] Submodule blocks push after merge        M
+  #101 [ENHANCEMENT/P2] Add batch rename support          S  ← Quick Win
+
+SOON (next sprint):
+  #202 [FEATURE/P3] English README                        L
+  #303 [DOCS/P3] Update API documentation                 S
+
+BACKLOG:
+  #404 [CHORE/P4] Remove deprecated methods               XS
+  ...
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Recommendation: Start with #{top_issue} ({reason}).
+Pick an issue number to investigate, or say "resolve #N".
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### Phase 5: User Decision
+
+**elicit: true**
+
+Present the triage report and wait for user to:
+1. Select an issue to investigate → hand off to `*resolve-issue {number}`
+2. Adjust priorities → re-sort and present again
+3. Close stale issues → `gh issue close {number} --comment "Closing as stale"`
+4. Request more detail on specific issue → `gh issue view {number}`
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] All open issues classified with type, severity, and effort
+    tipo: post-condition
+    blocker: false
+    validacao: |
+      Every issue in report has Type, Severity, and Effort columns filled
+
+  - [ ] Priority ranking presented to user
+    tipo: post-condition
+    blocker: true
+    validacao: |
+      User has seen the prioritized triage report
+
+  - [ ] User has selected next action (resolve, close, or defer)
+    tipo: post-condition
+    blocker: false
+    validacao: |
+      User has made a decision on at least one issue
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Triage report covers all open issues (or up to limit)
+    tipo: acceptance-criterion
+    blocker: true
+
+  - [ ] Each issue has type, severity, effort, and priority tier
+    tipo: acceptance-criterion
+    blocker: true
+
+  - [ ] Quick wins are clearly identified
+    tipo: acceptance-criterion
+    blocker: true
+
+  - [ ] User-facing output is a clean, scannable table
+    tipo: acceptance-criterion
+    blocker: true
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** gh (GitHub CLI)
+  - **Purpose:** Fetch issues, labels, comments, close stale issues
+  - **Source:** System CLI
+  - **Required:** true
+
+- **Tool:** git
+  - **Purpose:** Detect repository remote URL
+  - **Source:** System CLI
+  - **Required:** true
+
+---
+
+## Error Handling
+
+**Strategy:** graceful-fallback
+
+**Common Errors:**
+
+1. **Error:** GitHub CLI not authenticated
+   - **Cause:** `gh` not logged in
+   - **Resolution:** Run `gh auth login`
+   - **Recovery:** Prompt user to authenticate
+
+2. **Error:** Rate limit exceeded
+   - **Cause:** Too many API calls
+   - **Resolution:** Wait and retry, or use `--limit` to reduce scope
+   - **Recovery:** Present partial results
+
+3. **Error:** No open issues
+   - **Cause:** Repository has no open issues
+   - **Resolution:** Report clean backlog
+   - **Recovery:** Suggest checking closed issues or creating new ones
+
+---
+
+## Performance
+
+**Expected Metrics:**
+
+```yaml
+duration_expected: 1-3 min
+cost_estimated: $0.001-0.005
+token_usage: ~2,000-5,000 tokens
+```
+
+---
+
+## Metadata
+
+```yaml
+story: N/A (operational task)
+version: 1.0.0
+dependencies:
+  tasks: []
+  checklists: []
+  templates: []
+  tools:
+    - gh (GitHub CLI)
+    - git
+tags:
+  - devops
+  - issue-management
+  - triage
+  - backlog
+created_at: 2026-02-21
+updated_at: 2026-02-21
+related_tasks:
+  - resolve-github-issue.md
+```
+
+---
+
+## Integration with @devops Agent
+
+Called via `@devops *triage-issues` command or user request to analyze the issue backlog.
+
+**Handoff:** When user selects an issue to resolve, hand off to `*resolve-issue {number}`.

package/.aios-core/development/tasks/validate-agents.md

@@ -1,5 +1,9 @@
 # Validate Agents Task
 
+---
+execution_mode: programmatic  # TOK-3: PTC-eligible — batch-scan all agent files in single Bash block
+---
+
 ## Purpose
 
 Validate all agent definition files for structural integrity, required fields,

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

@@ -374,6 +374,16 @@ To comprehensively validate a story draft before implementation begins, ensuring
 - [ ] FAIL: Section missing or critically incomplete
 - [ ] N/A: CodeRabbit disabled in core-config.yaml
 
+### 8.1 Code Intelligence: No Duplicate Functionality (Auto-skip if unavailable)
+
+- **Check code intelligence availability:** Call `isCodeIntelAvailable()` from `.aios-core/core/code-intel`
+- **If available:**
+  - Call `validateNoDuplicates(storyDescription)` from `.aios-core/core/code-intel/helpers/story-helper`
+    - If `hasDuplicates: true`: Add to validation report as **Should-Fix** issue — "Potential duplicate functionality detected: {suggestion}". This is **advisory only** and does NOT block validation.
+    - If `hasDuplicates: false`: Add to report as PASS — "No duplicate functionality detected"
+  - Include result in the **Validation Result** section under "Code Intelligence Check"
+- **If NOT available:** Skip this step silently — validation proceeds exactly as before with no code intelligence items in report
+
 ### 9. Anti-Hallucination Verification
 
 - **Epic Context Enrichment**: Import `EpicContextAccumulator` from `core/orchestration` and call `buildAccumulatedContext(epicId, storyN)` to enrich validation with accumulated epic context (progressive summarization within token limits)
@@ -452,4 +462,11 @@ Provide a structured validation report including:
 - **NO-GO**: Story requires fixes before implementation
 - **Implementation Readiness Score**: 1-10 scale
 - **Confidence Level**: High/Medium/Low for successful implementation
+
+## Handoff
+next_agent: @dev
+next_command: *develop {story-id}
+condition: Story status is Approved (GO decision)
+alternatives:
+  - agent: @sm, command: *draft, condition: Story rejected (NO-GO), needs rework
  

package/.aios-core/development/templates/agent-handoff-tmpl.yaml

@@ -0,0 +1,48 @@
+# Agent Handoff Artifact Template
+# Story: TOK-4A — Agent Handoff Context Strategy
+# Purpose: Compact summary of previous agent's work for context-efficient agent switches.
+# Constraint: Filled artifact MUST be < 500 tokens.
+#
+# Usage: On agent switch (@agent command), the outgoing agent populates this template.
+#        The incoming agent receives: own full profile + this artifact (not previous agent's full persona).
+#
+# Reference: OpenAI Swarm handoff pattern, TOK-4A ACs 1-3
+
+handoff:
+  version: "1.0"
+  timestamp: ""           # ISO 8601 (e.g., 2026-02-23T17:00:00Z)
+  from_agent: ""          # Agent ID of outgoing agent (e.g., dev, qa, sm)
+  to_agent: ""            # Agent ID of incoming agent (e.g., qa, devops)
+
+  # What story/task is being worked on
+  story_context:
+    story_id: ""          # e.g., TOK-4A
+    story_path: ""        # e.g., docs/stories/epics/epic-token-optimization/story-TOK-4A-...md
+    story_status: ""      # e.g., In Progress, Ready for Review
+    current_task: ""      # e.g., Task 3: Integration point & limits
+    branch: ""            # e.g., feat/epic-token-optimization
+
+  # Key decisions made by outgoing agent (max 5)
+  decisions:
+    - ""                  # e.g., "Used CLAUDE.md instructions for compaction (not code module)"
+    # - ""
+
+  # Files created or modified by outgoing agent (max 10)
+  files_modified:
+    - ""                  # e.g., ".aios-core/development/templates/agent-handoff-tmpl.yaml"
+    # - ""
+
+  # Active blockers or issues (max 3)
+  blockers:
+    - ""                  # e.g., "NOG-18 not Done — Phase 2 SYNAPSE integration deferred"
+    # - ""
+
+  # What the incoming agent should do next (max 2 sentences)
+  next_action: ""         # e.g., "Run QA gate on TOK-4A. Verify handoff preserves story context."
+
+# --- Compaction Limits (AC 9) ---
+# Max artifact size: 500 tokens (~375 words)
+# Max retained summaries: 3 (oldest discarded on 4th switch)
+# Max decisions: 5
+# Max files_modified: 10
+# Max blockers: 3