aios-core 2.1.6 → 2.2.0

package/.aios-core/development/tasks/init-project-status.md

@@ -1,506 +1,506 @@
-# init-project-status
-
-**Task ID:** init-project-status
-**Version:** 1.0
-**Created:** 2025-01-14 (Story 6.1.2.4)
-**Agent:** @devops (Gage)
-
----
-
-## Execution Modes
-
-**Choose your execution mode:**
-
-### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
-- Autonomous decision making with logging
-- Minimal user interaction
-- **Best for:** Simple, deterministic tasks
-
-### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
-- Explicit decision checkpoints
-- Educational explanations
-- **Best for:** Learning, complex decisions
-
-### 3. Pre-Flight Planning - Comprehensive Upfront Planning
-- Task analysis phase (identify all ambiguities)
-- Zero ambiguity execution
-- **Best for:** Ambiguous requirements, critical work
-
-**Parameter:** `mode` (optional, default: `interactive`)
-
----
-
-## Task Definition (AIOS Task Format V1.0)
-
-```yaml
-task: initProjectStatus()
-responsável: River (Facilitator)
-responsavel_type: Agente
-atomic_layer: Atom
-
-**Entrada:**
-- campo: project_path
-  tipo: string
-  origem: User Input
-  obrigatório: true
-  validação: Valid directory path
-
-- campo: options
-  tipo: object
-  origem: User Input
-  obrigatório: false
-  validação: Initialization options
-
-**Saída:**
-- campo: initialized_project
-  tipo: string
-  destino: File system
-  persistido: true
-
-- campo: config_created
-  tipo: boolean
-  destino: Return value
-  persistido: false
-```
-
----
-
-## Pre-Conditions
-
-**Purpose:** Validate prerequisites BEFORE task execution (blocking)
-
-**Checklist:**
-
-```yaml
-pre-conditions:
-  - [ ] Directory is empty or force flag set; config valid
-    tipo: pre-condition
-    blocker: true
-    validação: |
-      Check directory is empty or force flag set; config valid
-    error_message: "Pre-condition failed: Directory is empty or force flag set; config valid"
-```
-
----
-
-## Post-Conditions
-
-**Purpose:** Validate execution success AFTER task completes
-
-**Checklist:**
-
-```yaml
-post-conditions:
-  - [ ] Project initialized; config files created; structure valid
-    tipo: post-condition
-    blocker: true
-    validação: |
-      Verify project initialized; config files created; structure valid
-    error_message: "Post-condition failed: Project initialized; config files created; structure valid"
-```
-
----
-
-## Acceptance Criteria
-
-**Purpose:** Definitive pass/fail criteria for task completion
-
-**Checklist:**
-
-```yaml
-acceptance-criteria:
-  - [ ] Project structure correct; all config files valid
-    tipo: acceptance-criterion
-    blocker: true
-    validação: |
-      Assert project structure correct; all config files valid
-    error_message: "Acceptance criterion not met: Project structure correct; all config files valid"
-```
-
----
-
-## Tools
-
-**External/shared resources used by this task:**
-
-- **Tool:** project-scaffolder
-  - **Purpose:** Generate project structure and config
-  - **Source:** .aios-core/scripts/project-scaffolder.js
-
-- **Tool:** config-manager
-  - **Purpose:** Initialize configuration files
-  - **Source:** .aios-core/utils/config-manager.js
-
----
-
-## Error Handling
-
-**Strategy:** retry
-
-**Common Errors:**
-
-1. **Error:** Directory Not Empty
-   - **Cause:** Target directory already contains files
-   - **Resolution:** Use force flag or choose empty directory
-   - **Recovery:** Prompt for confirmation, merge or abort
-
-2. **Error:** Initialization Failed
-   - **Cause:** Error creating project structure
-   - **Resolution:** Check permissions and disk space
-   - **Recovery:** Cleanup partial initialization, log error
-
----
-
-## Performance
-
-**Expected Metrics:**
-
-```yaml
-duration_expected: 0.5-2 min (estimated)
-cost_estimated: $0.0001-0.0005
-token_usage: ~500-1,000 tokens
-```
-
-**Optimization Notes:**
-- Minimize external dependencies; cache results if reusable; validate inputs early
-
----
-
-## Metadata
-
-```yaml
-story: N/A
-version: 1.0.0
-dependencies:
-  - N/A
-tags:
-  - automation
-  - workflow
-updated_at: 2025-11-17
-```
-
----
-
-
-## Description
-
-Initialize dynamic project status tracking for agent activation context. This task sets up the project status feature that displays git state, recent work, and current story/epic information in agent greetings.
-
----
-
-## Inputs
-
-None (runs in current project directory)
-
----
-
-## Elicitation
-
-```yaml
-elicit: false
-```
-
-This task runs autonomously without user interaction.
-
----
-
-## Steps
-
-### Step 1: Detect Git Repository
-
-**Action:** Check if current directory is a git repository
-
-```bash
-git rev-parse --is-inside-work-tree 2>/dev/null
-```
-
-**Exit Condition:** If not a git repo, display message and exit gracefully:
-```
-⚠️  Project status feature requires a git repository.
-    Initialize git first: git init
-```
-
----
-
-### Step 2: Check Current Configuration
-
-**Action:** Read `.aios-core/core-config.yaml` and check `projectStatus.enabled`
-
-**Logic:**
-```javascript
-const config = yaml.load(fs.readFileSync('.aios-core/core-config.yaml'));
-const isEnabled = config?.projectStatus?.enabled === true;
-```
-
-**If already enabled:**
-```
-✅ Project status is already enabled in core-config.yaml
-```
-
-Skip to Step 4.
-
----
-
-### Step 3: Enable Project Status in Config
-
-**Action:** Update `core-config.yaml` to enable project status
-
-**Changes:**
-```yaml
-projectStatus:
-  enabled: true
-  autoLoadOnAgentActivation: true
-  showInGreeting: true
-  cacheTimeSeconds: 60
-  components:
-    gitBranch: true
-    gitStatus: true
-    recentWork: true
-    currentEpic: true
-    currentStory: true
-  statusFile: .aios/project-status.yaml
-  maxModifiedFiles: 5
-  maxRecentCommits: 2
-```
-
-**Confirmation:**
-```
-✅ Enabled projectStatus in core-config.yaml
-```
-
----
-
-### Step 4: Create .aios Directory
-
-**Action:** Ensure `.aios/` directory exists
-
-```bash
-mkdir -p .aios
-```
-
-**Note:** Directory is created if missing, no error if exists.
-
----
-
-### Step 5: Initialize Status Cache
-
-**Action:** Load project status for the first time
-
-```javascript
-const { loadProjectStatus } = require('./.aios-core/scripts/project-status-loader.js');
-const status = await loadProjectStatus();
-```
-
-**Verification:** Check that `.aios/project-status.yaml` was created with valid content.
-
-**Sample Cache Content:**
-```yaml
-status:
-  branch: main
-  modifiedFiles:
-    - story-6.1.2.4.md
-  recentCommits:
-    - "chore: cleanup Utils Registry"
-  currentEpic: null
-  currentStory: null
-  lastUpdate: '2025-01-14T10:30:00.000Z'
-  isGitRepo: true
-timestamp: 1705238400000
-ttl: 60
-```
-
-**Confirmation:**
-```
-✅ Initialized project status cache (.aios/project-status.yaml)
-```
-
----
-
-### Step 6: Test Status Display
-
-**Action:** Simulate agent activation to verify status displays correctly
-
-**Method:** Load status and format for display
-
-```javascript
-const { loadProjectStatus, formatStatusDisplay } = require('./.aios-core/scripts/project-status-loader.js');
-const status = await loadProjectStatus();
-const display = formatStatusDisplay(status);
-console.log('\nExample Agent Greeting:\n');
-console.log('💻 Dex (Builder) ready. Let's build something great!\n');
-console.log('Current Project Status:');
-console.log(display);
-console.log('\nType *help to see available commands!');
-```
-
----
-
-### Step 7: Update .gitignore
-
-**Action:** Ensure `.aios/project-status.yaml` is gitignored
-
-**Check:** Look for `.aios/project-status.yaml` entry in `.gitignore`
-
-**If missing:** Add entry to `.gitignore`
-
-```gitignore
-# AIOS Project Status Cache (auto-generated)
-.aios/project-status.yaml
-```
-
-**Confirmation:**
-```
-✅ Added .aios/project-status.yaml to .gitignore
-```
-
----
-
-### Step 8: Display Success Summary
-
-**Action:** Show complete setup summary
-
-```
-╔═══════════════════════════════════════════════════════════╗
-║  ✅ Project Status Tracking Initialized                  ║
-╚═══════════════════════════════════════════════════════════╝
-
-Configuration:
-  • projectStatus.enabled = true
-  • Cache file: .aios/project-status.yaml
-  • Cache TTL: 60 seconds
-  • Gitignored: Yes
-
-Next Steps:
-  1. Activate any agent to see project status in greeting
-  2. Example: /dev or /po
-  3. Status automatically refreshes every 60 seconds
-
-Documentation: docs/guides/project-status-feature.md
-```
-
----
-
-## Outputs
-
-### Files Created
-
-- `.aios/project-status.yaml` - Status cache file (gitignored)
-
-### Files Modified
-
-- `.aios-core/core-config.yaml` - projectStatus section enabled (if was disabled)
-- `.gitignore` - Added cache file entry (if missing)
-
-### System State
-
-- Project status feature: **ENABLED**
-- All 11 agents will now display project context on activation
-
----
-
-## Validation
-
-- [ ] `.aios/project-status.yaml` exists and contains valid YAML
-- [ ] `core-config.yaml` has `projectStatus.enabled: true`
-- [ ] `.gitignore` includes `.aios/project-status.yaml`
-- [ ] Test agent activation shows status display
-- [ ] Git repository detected correctly
-- [ ] Cache TTL is 60 seconds
-
----
-
-## Error Handling
-
-### Not a Git Repository
-
-**Error:**
-```
-⚠️  Project status feature requires a git repository.
-```
-
-**Resolution:**
-```bash
-git init
-```
-
-### core-config.yaml Not Found
-
-**Error:**
-```
-❌ Could not find .aios-core/core-config.yaml
-   Are you in the project root directory?
-```
-
-**Resolution:** Navigate to project root before running task.
-
-### Permission Denied on .aios Directory
-
-**Error:**
-```
-❌ Cannot create .aios directory: Permission denied
-```
-
-**Resolution:** Check file system permissions for project directory.
-
----
-
-## Rollback
-
-To disable project status tracking:
-
-1. **Edit core-config.yaml:**
-   ```yaml
-   projectStatus:
-     enabled: false
-   ```
-
-2. **Remove cache file:**
-   ```bash
-   rm .aios/project-status.yaml
-   ```
-
-3. **Restart agent sessions** - new activations won't load status
-
----
-
-## Performance Notes
-
-- **First load:** ~80-100ms (git commands + file I/O)
-- **Cached load:** ~5-10ms (YAML read only)
-- **Cache invalidation:** Automatic after 60 seconds
-- **Agent overhead:** Minimal (<100ms added to activation)
-
----
-
-## Dependencies
-
-### Scripts
-
-- `.aios-core/scripts/project-status-loader.js` - Core status loader
-
-### NPM Packages
-
-- `js-yaml` - YAML parsing (already in project dependencies)
-- `execa` - Git command execution (already in project dependencies)
-
-### Git Commands Used
-
-- `git rev-parse --is-inside-work-tree` - Detect git repo
-- `git branch --show-current` - Get current branch (git >= 2.22)
-- `git rev-parse --abbrev-ref HEAD` - Fallback for older git
-- `git status --porcelain` - Get modified files
-- `git log -2 --oneline --no-decorate` - Get recent commits
-
----
-
-## Related
-
-- **Story:** 6.1.2.4 - Dynamic Project Status Context
-- **Documentation:** `docs/guides/project-status-feature.md`
-- **Config:** `.aios-core/core-config.yaml` (projectStatus section)
-
----
-
-**Status:** ✅ Production Ready
-**Tested On:** Windows, Linux, macOS
-**Git Requirement:** git >= 2.0 (2.22+ recommended)
+# init-project-status
+
+**Task ID:** init-project-status
+**Version:** 1.0
+**Created:** 2025-01-14 (Story 6.1.2.4)
+**Agent:** @devops (Gage)
+
+---
+
+## Execution Modes
+
+**Choose your execution mode:**
+
+### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
+- Autonomous decision making with logging
+- Minimal user interaction
+- **Best for:** Simple, deterministic tasks
+
+### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
+- Explicit decision checkpoints
+- Educational explanations
+- **Best for:** Learning, complex decisions
+
+### 3. Pre-Flight Planning - Comprehensive Upfront Planning
+- Task analysis phase (identify all ambiguities)
+- Zero ambiguity execution
+- **Best for:** Ambiguous requirements, critical work
+
+**Parameter:** `mode` (optional, default: `interactive`)
+
+---
+
+## Task Definition (AIOS Task Format V1.0)
+
+```yaml
+task: initProjectStatus()
+responsável: River (Facilitator)
+responsavel_type: Agente
+atomic_layer: Atom
+
+**Entrada:**
+- campo: project_path
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Valid directory path
+
+- campo: options
+  tipo: object
+  origem: User Input
+  obrigatório: false
+  validação: Initialization options
+
+**Saída:**
+- campo: initialized_project
+  tipo: string
+  destino: File system
+  persistido: true
+
+- campo: config_created
+  tipo: boolean
+  destino: Return value
+  persistido: false
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Directory is empty or force flag set; config valid
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check directory is empty or force flag set; config valid
+    error_message: "Pre-condition failed: Directory is empty or force flag set; config valid"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Project initialized; config files created; structure valid
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify project initialized; config files created; structure valid
+    error_message: "Post-condition failed: Project initialized; config files created; structure valid"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Project structure correct; all config files valid
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert project structure correct; all config files valid
+    error_message: "Acceptance criterion not met: Project structure correct; all config files valid"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** project-scaffolder
+  - **Purpose:** Generate project structure and config
+  - **Source:** .aios-core/scripts/project-scaffolder.js
+
+- **Tool:** config-manager
+  - **Purpose:** Initialize configuration files
+  - **Source:** .aios-core/utils/config-manager.js
+
+---
+
+## Error Handling
+
+**Strategy:** retry
+
+**Common Errors:**
+
+1. **Error:** Directory Not Empty
+   - **Cause:** Target directory already contains files
+   - **Resolution:** Use force flag or choose empty directory
+   - **Recovery:** Prompt for confirmation, merge or abort
+
+2. **Error:** Initialization Failed
+   - **Cause:** Error creating project structure
+   - **Resolution:** Check permissions and disk space
+   - **Recovery:** Cleanup partial initialization, log error
+
+---
+
+## Performance
+
+**Expected Metrics:**
+
+```yaml
+duration_expected: 0.5-2 min (estimated)
+cost_estimated: $0.0001-0.0005
+token_usage: ~500-1,000 tokens
+```
+
+**Optimization Notes:**
+- Minimize external dependencies; cache results if reusable; validate inputs early
+
+---
+
+## Metadata
+
+```yaml
+story: N/A
+version: 1.0.0
+dependencies:
+  - N/A
+tags:
+  - automation
+  - workflow
+updated_at: 2025-11-17
+```
+
+---
+
+
+## Description
+
+Initialize dynamic project status tracking for agent activation context. This task sets up the project status feature that displays git state, recent work, and current story/epic information in agent greetings.
+
+---
+
+## Inputs
+
+None (runs in current project directory)
+
+---
+
+## Elicitation
+
+```yaml
+elicit: false
+```
+
+This task runs autonomously without user interaction.
+
+---
+
+## Steps
+
+### Step 1: Detect Git Repository
+
+**Action:** Check if current directory is a git repository
+
+```bash
+git rev-parse --is-inside-work-tree 2>/dev/null
+```
+
+**Exit Condition:** If not a git repo, display message and exit gracefully:
+```
+⚠️  Project status feature requires a git repository.
+    Initialize git first: git init
+```
+
+---
+
+### Step 2: Check Current Configuration
+
+**Action:** Read `.aios-core/core-config.yaml` and check `projectStatus.enabled`
+
+**Logic:**
+```javascript
+const config = yaml.load(fs.readFileSync('.aios-core/core-config.yaml'));
+const isEnabled = config?.projectStatus?.enabled === true;
+```
+
+**If already enabled:**
+```
+✅ Project status is already enabled in core-config.yaml
+```
+
+Skip to Step 4.
+
+---
+
+### Step 3: Enable Project Status in Config
+
+**Action:** Update `core-config.yaml` to enable project status
+
+**Changes:**
+```yaml
+projectStatus:
+  enabled: true
+  autoLoadOnAgentActivation: true
+  showInGreeting: true
+  cacheTimeSeconds: 60
+  components:
+    gitBranch: true
+    gitStatus: true
+    recentWork: true
+    currentEpic: true
+    currentStory: true
+  statusFile: .aios/project-status.yaml
+  maxModifiedFiles: 5
+  maxRecentCommits: 2
+```
+
+**Confirmation:**
+```
+✅ Enabled projectStatus in core-config.yaml
+```
+
+---
+
+### Step 4: Create .aios Directory
+
+**Action:** Ensure `.aios/` directory exists
+
+```bash
+mkdir -p .aios
+```
+
+**Note:** Directory is created if missing, no error if exists.
+
+---
+
+### Step 5: Initialize Status Cache
+
+**Action:** Load project status for the first time
+
+```javascript
+const { loadProjectStatus } = require('./.aios-core/scripts/project-status-loader.js');
+const status = await loadProjectStatus();
+```
+
+**Verification:** Check that `.aios/project-status.yaml` was created with valid content.
+
+**Sample Cache Content:**
+```yaml
+status:
+  branch: main
+  modifiedFiles:
+    - story-6.1.2.4.md
+  recentCommits:
+    - "chore: cleanup Utils Registry"
+  currentEpic: null
+  currentStory: null
+  lastUpdate: '2025-01-14T10:30:00.000Z'
+  isGitRepo: true
+timestamp: 1705238400000
+ttl: 60
+```
+
+**Confirmation:**
+```
+✅ Initialized project status cache (.aios/project-status.yaml)
+```
+
+---
+
+### Step 6: Test Status Display
+
+**Action:** Simulate agent activation to verify status displays correctly
+
+**Method:** Load status and format for display
+
+```javascript
+const { loadProjectStatus, formatStatusDisplay } = require('./.aios-core/scripts/project-status-loader.js');
+const status = await loadProjectStatus();
+const display = formatStatusDisplay(status);
+console.log('\nExample Agent Greeting:\n');
+console.log('💻 Dex (Builder) ready. Let's build something great!\n');
+console.log('Current Project Status:');
+console.log(display);
+console.log('\nType *help to see available commands!');
+```
+
+---
+
+### Step 7: Update .gitignore
+
+**Action:** Ensure `.aios/project-status.yaml` is gitignored
+
+**Check:** Look for `.aios/project-status.yaml` entry in `.gitignore`
+
+**If missing:** Add entry to `.gitignore`
+
+```gitignore
+# AIOS Project Status Cache (auto-generated)
+.aios/project-status.yaml
+```
+
+**Confirmation:**
+```
+✅ Added .aios/project-status.yaml to .gitignore
+```
+
+---
+
+### Step 8: Display Success Summary
+
+**Action:** Show complete setup summary
+
+```
+╔═══════════════════════════════════════════════════════════╗
+║  ✅ Project Status Tracking Initialized                  ║
+╚═══════════════════════════════════════════════════════════╝
+
+Configuration:
+  • projectStatus.enabled = true
+  • Cache file: .aios/project-status.yaml
+  • Cache TTL: 60 seconds
+  • Gitignored: Yes
+
+Next Steps:
+  1. Activate any agent to see project status in greeting
+  2. Example: /dev or /po
+  3. Status automatically refreshes every 60 seconds
+
+Documentation: docs/guides/project-status-feature.md
+```
+
+---
+
+## Outputs
+
+### Files Created
+
+- `.aios/project-status.yaml` - Status cache file (gitignored)
+
+### Files Modified
+
+- `.aios-core/core-config.yaml` - projectStatus section enabled (if was disabled)
+- `.gitignore` - Added cache file entry (if missing)
+
+### System State
+
+- Project status feature: **ENABLED**
+- All 11 agents will now display project context on activation
+
+---
+
+## Validation
+
+- [ ] `.aios/project-status.yaml` exists and contains valid YAML
+- [ ] `core-config.yaml` has `projectStatus.enabled: true`
+- [ ] `.gitignore` includes `.aios/project-status.yaml`
+- [ ] Test agent activation shows status display
+- [ ] Git repository detected correctly
+- [ ] Cache TTL is 60 seconds
+
+---
+
+## Error Handling
+
+### Not a Git Repository
+
+**Error:**
+```
+⚠️  Project status feature requires a git repository.
+```
+
+**Resolution:**
+```bash
+git init
+```
+
+### core-config.yaml Not Found
+
+**Error:**
+```
+❌ Could not find .aios-core/core-config.yaml
+   Are you in the project root directory?
+```
+
+**Resolution:** Navigate to project root before running task.
+
+### Permission Denied on .aios Directory
+
+**Error:**
+```
+❌ Cannot create .aios directory: Permission denied
+```
+
+**Resolution:** Check file system permissions for project directory.
+
+---
+
+## Rollback
+
+To disable project status tracking:
+
+1. **Edit core-config.yaml:**
+   ```yaml
+   projectStatus:
+     enabled: false
+   ```
+
+2. **Remove cache file:**
+   ```bash
+   rm .aios/project-status.yaml
+   ```
+
+3. **Restart agent sessions** - new activations won't load status
+
+---
+
+## Performance Notes
+
+- **First load:** ~80-100ms (git commands + file I/O)
+- **Cached load:** ~5-10ms (YAML read only)
+- **Cache invalidation:** Automatic after 60 seconds
+- **Agent overhead:** Minimal (<100ms added to activation)
+
+---
+
+## Dependencies
+
+### Scripts
+
+- `.aios-core/scripts/project-status-loader.js` - Core status loader
+
+### NPM Packages
+
+- `js-yaml` - YAML parsing (already in project dependencies)
+- `execa` - Git command execution (already in project dependencies)
+
+### Git Commands Used
+
+- `git rev-parse --is-inside-work-tree` - Detect git repo
+- `git branch --show-current` - Get current branch (git >= 2.22)
+- `git rev-parse --abbrev-ref HEAD` - Fallback for older git
+- `git status --porcelain` - Get modified files
+- `git log -2 --oneline --no-decorate` - Get recent commits
+
+---
+
+## Related
+
+- **Story:** 6.1.2.4 - Dynamic Project Status Context
+- **Documentation:** `docs/guides/project-status-feature.md`
+- **Config:** `.aios-core/core-config.yaml` (projectStatus section)
+
+---
+
+**Status:** ✅ Production Ready
+**Tested On:** Windows, Linux, macOS
+**Git Requirement:** git >= 2.0 (2.22+ recommended)