aios-core 4.1.0 → 4.2.0

package/.claude/rules/ids-principles.md

@@ -0,0 +1,112 @@
+# IDS Principles — Detailed Rules
+
+> Status: Planned (IDS epic is Draft — principles apply as aspirational guidance)
+
+## Decision Hierarchy: REUSE > ADAPT > CREATE
+
+### REUSE (Relevance >= 90%)
+- Use existing artifact directly without modification
+- Import/reference existing entity
+- No justification needed beyond confirming match
+
+### ADAPT (Relevance 60-89%)
+- Adaptability score >= 0.6
+- Changes MUST NOT exceed 30% of original artifact
+- Changes MUST NOT break existing consumers (check usedBy list)
+- Document changes in artifact's change log
+- Update registry relationships
+- Impact analysis required
+
+### CREATE (No suitable match)
+Required justification:
+- `evaluated_patterns`: Existing entities you considered
+- `rejection_reasons`: Why each was rejected (technical reasons)
+- `new_capability`: What unique capability this provides
+- Register in Entity Registry within 24 hours
+- Establish relationships with existing entities
+- Define adaptability constraints for future reuse
+
+## Verification Gates G1-G6
+
+### G1: Epic Creation (@pm)
+- **Type:** Human-in-loop, Advisory
+- **Trigger:** `*create-epic` workflow
+- **Action:** Query registry for related entities, display potentially reusable artifacts
+- **Latency:** < 24h (async)
+- **Blocking:** No
+
+### G2: Story Creation (@sm)
+- **Type:** Human-in-loop, Advisory
+- **Trigger:** `*draft` workflow
+- **Action:** Check existing tasks/templates matching story work
+- **Latency:** < 24h (async)
+- **Blocking:** No
+
+### G3: Story Validation (@po)
+- **Type:** Human-in-loop, Soft Block
+- **Trigger:** `*validate-story-draft` workflow
+- **Action:** Verify referenced artifacts exist, detect potential duplication
+- **Latency:** < 4h (async)
+- **Blocking:** Soft (can override with reason)
+
+### G4: Dev Context (@dev)
+- **Type:** Automated, Informational
+- **Trigger:** Story assignment / `*develop` start
+- **Action:** Display matching patterns as reminder
+- **Latency:** < 2s
+- **Blocking:** NO (logged only for metrics)
+
+### G5: QA Review (@qa)
+- **Type:** Automated, Blocks Merge
+- **Trigger:** PR/merge request
+- **Action:** Check if new artifacts could have reused existing
+- **Latency:** < 30s
+- **Blocking:** YES if new entity without registry entry or justification
+
+### G6: CI/CD (@devops)
+- **Type:** Automated, Blocks Merge
+- **Trigger:** CI pipeline
+- **Action:** Registry integrity check + sync
+- **Latency:** < 60s
+- **Blocking:** YES on CRITICAL, WARN on MEDIUM/LOW
+
+## Override Policy
+
+**Command:** `--override-ids --override-reason "explanation"`
+
+**Permitted when:**
+- Time-critical fix requires immediate creation
+- Adaptation would introduce unacceptable risk
+- Existing artifact is deprecated/frozen
+
+**Requirements:**
+- Logged for audit trail
+- Reviewed within 7 days
+- Include override reason in gate verification log
+
+## Graceful Degradation
+
+All gates implement circuit breaker:
+- **Timeout:** 2s default
+- **On timeout:** warn-and-proceed
+- **On error:** log-and-proceed
+- **Key principle:** Development NEVER blocked by IDS failures
+
+```yaml
+circuit_breaker:
+  failure_threshold: 5
+  success_threshold: 3
+  reset_timeout_ms: 60000
+```
+
+## Article IV-A: Incremental Development (Constitution Amendment)
+
+**Severity:** MUST
+
+**Four Core Rules:**
+1. **Registry Consultation Required** — Query before creating
+2. **Decision Hierarchy** — REUSE > ADAPT > CREATE strictly
+3. **Adaptation Limits** — Changes < 30%, don't break consumers
+4. **Creation Requirements** — Full justification, register within 24h
+
+**Reference:** `docs/stories/epics/epic-ids-incremental-development/`

package/.claude/rules/story-lifecycle.md

@@ -0,0 +1,139 @@
+# Story Lifecycle — Detailed Rules
+
+## Status Progression
+
+```
+Draft → Ready → InProgress → InReview → Done
+```
+
+| Status | Trigger | Agent | Action |
+|--------|---------|-------|--------|
+| Draft | @sm creates story | @sm | Story file created |
+| Ready | @po validates (GO) | @po | **MUST update status field in story file from Draft → Ready** |
+| InProgress | @dev starts implementation | @dev | Update status field |
+| InReview | @dev completes, @qa reviews | @qa | Update status field |
+| Done | @qa PASS, @devops pushes | @devops | Update status field |
+
+**CRITICAL:** The `Draft → Ready` transition is the responsibility of @po during `*validate-story-draft`. When verdict is GO (including conditional GO after fixes are applied), @po MUST update the story's Status field to `Ready` and log the transition in the Change Log. A story left in `Draft` after a GO verdict is a process violation.
+
+## Phase 1: Create (@sm)
+
+**Task:** `create-next-story.md`
+**Inputs:** PRD sharded, epic context
+**Output:** `{epicNum}.{storyNum}.story.md`
+
+## Phase 2: Validate (@po)
+
+**Task:** `validate-next-story.md`
+
+### 10-Point Validation Checklist
+
+1. Clear and objective title
+2. Complete description (problem/need explained)
+3. Testable acceptance criteria (Given/When/Then preferred)
+4. Well-defined scope (IN and OUT clearly listed)
+5. Dependencies mapped (prerequisite stories/resources)
+6. Complexity estimate (points or T-shirt sizing)
+7. Business value (benefit to user/business clear)
+8. Risks documented (potential problems identified)
+9. Criteria of Done (clear definition of complete)
+10. Alignment with PRD/Epic (consistency with source docs)
+
+**Decision:** GO (≥7/10) or NO-GO (<7/10 with required fixes)
+
+## Phase 3: Implement (@dev)
+
+**Task:** `dev-develop-story.md`
+
+### Execution Modes
+
+**YOLO (autonomous):**
+- 0-1 prompts
+- Decisions logged in `decision-log-{story-id}.md`
+- Best for: simple, deterministic tasks
+
+**Interactive (default):**
+- 5-10 prompts with educational checkpoints
+- Confirmations at key decision points
+- Best for: learning, complex decisions
+
+**Pre-Flight (plan-first):**
+- All questions upfront (10-15 prompts)
+- Generates execution plan
+- Then zero-ambiguity execution
+- Best for: ambiguous requirements, critical work
+
+### CodeRabbit Self-Healing in Dev Phase
+
+```
+iteration = 0
+while CRITICAL issues found AND iteration < 2:
+  auto-fix CRITICAL/HIGH
+  iteration++
+if CRITICAL persist after 2 iterations:
+  HALT — manual intervention required
+```
+
+## Phase 4: QA Gate (@qa)
+
+**Task:** `qa-gate.md`
+
+### 7 Quality Checks
+
+1. **Code review** — patterns, readability, maintainability
+2. **Unit tests** — adequate coverage, all passing
+3. **Acceptance criteria** — all met per story AC
+4. **No regressions** — existing functionality preserved
+5. **Performance** — within acceptable limits
+6. **Security** — OWASP basics verified
+7. **Documentation** — updated if necessary
+
+### Gate Decisions
+
+| Decision | Score | Action |
+|----------|-------|--------|
+| PASS | All checks OK | Approve, proceed to @devops push |
+| CONCERNS | Minor issues | Approve with observations documented |
+| FAIL | HIGH/CRITICAL issues | Return to @dev with feedback |
+| WAIVED | Issues accepted | Approve with waiver documented (rare) |
+
+### Gate File Structure
+
+```yaml
+storyId: STORY-42
+verdict: PASS | CONCERNS | FAIL | WAIVED
+issues:
+  - severity: low | medium | high
+    category: code | tests | requirements | performance | security | docs
+    description: "..."
+    recommendation: "..."
+```
+
+## QA Loop (Iterative Review-Fix)
+
+```
+@qa review → verdict → @dev fixes → re-review (max 5 iterations)
+```
+
+**Commands:**
+- `*qa-loop {storyId}` — Start full loop
+- `*stop-qa-loop` — Pause and save state
+- `*resume-qa-loop` — Resume from saved state
+- `*escalate-qa-loop` — Force manual escalation
+
+**Escalation triggers:**
+- max_iterations_reached (default: 5)
+- verdict_blocked
+- fix_failure (after retries)
+- manual_escalate (user command)
+
+**Status:** Tracked in `qa/loop-status.json`
+
+## Story File Update Rules
+
+| Section | Who Can Edit |
+|---------|-------------|
+| Title, Description, AC, Scope | @po only |
+| File List, Dev Notes, checkboxes | @dev |
+| QA Results | @qa only |
+| Change Log | Any agent (append only) |

package/.claude/rules/workflow-execution.md

@@ -0,0 +1,150 @@
+# Workflow Execution — Detailed Rules
+
+## Task-First Principle
+
+**Workflows são compostos por tasks conectadas, não por agentes conectados.** Cada task define seus inputs, outputs, pre/post-conditions e execution modes. Os agentes listados abaixo são os **executores padrão** de cada task — mas a sequência, as regras e as dependências vêm das definições de tasks em `.aios-core/development/tasks/`.
+
+Uma task validada é lei: deve ser executada conforme configurada, com todas as suas dependências respeitadas, independente de quem a executa (agent, worker, clone ou humano).
+
+---
+
+## 4 Primary Workflows
+
+### 1. Story Development Cycle (SDC) — PRIMARY
+
+**Full 4-phase workflow for all development work.**
+
+#### Phase 1: Create (@sm)
+- **Task:** `create-next-story.md`
+- **Inputs:** PRD sharded, epic context
+- **Output:** `{epicNum}.{storyNum}.story.md`
+- **Status:** Draft
+
+#### Phase 2: Validate (@po)
+- **Task:** `validate-next-story.md`
+- **10-point checklist** (see `story-lifecycle.md`)
+- **Decision:** GO (>=7) or NO-GO (required fixes listed)
+
+#### Phase 3: Implement (@dev)
+- **Task:** `dev-develop-story.md`
+- **Modes:** Interactive / YOLO / Pre-Flight
+- **CodeRabbit:** Self-healing max 2 iterations
+- **Status:** Ready → InProgress
+
+#### Phase 4: QA Gate (@qa)
+- **Task:** `qa-gate.md`
+- **7 quality checks** (see `story-lifecycle.md`)
+- **Decision:** PASS / CONCERNS / FAIL / WAIVED
+- **Status:** InProgress → InReview → Done
+
+---
+
+### 2. QA Loop — ITERATIVE REVIEW
+
+**Automated review-fix cycle after initial QA gate.**
+
+```
+@qa review → verdict → @dev fixes → re-review (max 5)
+```
+
+**Commands:**
+- `*qa-loop {storyId}` — Start loop
+- `*qa-loop-review` — Resume from review
+- `*qa-loop-fix` — Resume from fix
+- `*stop-qa-loop` — Pause, save state
+- `*resume-qa-loop` — Resume from state
+- `*escalate-qa-loop` — Force escalation
+
+**Config:**
+- Max iterations: 5 (`autoClaude.qaLoop.maxIterations`)
+- Status file: `qa/loop-status.json`
+
+**Verdicts:**
+- APPROVE → Complete, mark Done
+- REJECT → @dev fixes, re-review
+- BLOCKED → Escalate immediately
+
+**Escalation triggers:**
+- `max_iterations_reached`
+- `verdict_blocked`
+- `fix_failure`
+- `manual_escalate`
+
+---
+
+### 3. Spec Pipeline — PRE-IMPLEMENTATION
+
+**Transform informal requirements into executable spec.**
+
+| Phase | Agent | Output | Skip If |
+|-------|-------|--------|---------|
+| 1. Gather | @pm | `requirements.json` | Never |
+| 2. Assess | @architect | `complexity.json` | source=simple |
+| 3. Research | @analyst | `research.json` | SIMPLE class |
+| 4. Write Spec | @pm | `spec.md` | Never |
+| 5. Critique | @qa | `critique.json` | Never |
+| 6. Plan | @architect | `implementation.yaml` | If APPROVED |
+
+**Complexity Classes:**
+
+| Score | Class | Phases |
+|-------|-------|--------|
+| <= 8 | SIMPLE | gather → spec → critique (3) |
+| 9-15 | STANDARD | All 6 phases |
+| >= 16 | COMPLEX | 6 phases + revision cycle |
+
+**5 Complexity Dimensions (scored 1-5):**
+- **Scope:** Files affected
+- **Integration:** External APIs
+- **Infrastructure:** Changes needed
+- **Knowledge:** Team familiarity
+- **Risk:** Criticality level
+
+**Critique Verdicts:**
+
+| Verdict | Average Score | Next Step |
+|---------|--------------|-----------|
+| APPROVED | >= 4.0 | Plan (Phase 6) |
+| NEEDS_REVISION | 3.0-3.9 | Revise (Phase 5b) |
+| BLOCKED | < 3.0 | Escalate to @architect |
+
+**Constitutional Gate (Article IV — No Invention):**
+Every statement in spec.md MUST trace to FR-*, NFR-*, CON-*, or research finding. NO invented features.
+
+---
+
+### 4. Brownfield Discovery — LEGACY ASSESSMENT
+
+**10-phase technical debt assessment for existing codebases.**
+
+**Data Collection (Phases 1-3):**
+- Phase 1: @architect → `system-architecture.md`
+- Phase 2: @data-engineer → `SCHEMA.md` + `DB-AUDIT.md` (if DB exists)
+- Phase 3: @ux-design-expert → `frontend-spec.md`
+
+**Draft & Validation (Phases 4-7):**
+- Phase 4: @architect → `technical-debt-DRAFT.md`
+- Phase 5: @data-engineer → `db-specialist-review.md`
+- Phase 6: @ux-design-expert → `ux-specialist-review.md`
+- Phase 7: @qa → `qa-review.md` (QA Gate: APPROVED | NEEDS WORK)
+
+**Finalization (Phases 8-10):**
+- Phase 8: @architect → `technical-debt-assessment.md` (final)
+- Phase 9: @analyst → `TECHNICAL-DEBT-REPORT.md` (executive)
+- Phase 10: @pm → Epic + stories ready for development
+
+**QA Gate (Phase 7):**
+- **APPROVED:** All debits validated, no critical gaps, dependencies mapped
+- **NEEDS WORK:** Gaps not addressed, return to Phase 4
+
+---
+
+## Workflow Selection Guide
+
+| Situation | Workflow |
+|-----------|---------|
+| New story from epic | Story Development Cycle |
+| QA found issues, need iteration | QA Loop |
+| Complex feature needs spec | Spec Pipeline → then SDC |
+| Joining existing project | Brownfield Discovery |
+| Simple bug fix | SDC only (YOLO mode) |

package/LICENSE

@@ -1,48 +1,48 @@
-Commons Clause License Condition v1.0
-
-The Software is provided to you by the Licensor under the License,
-as defined below, subject to the following condition.
-
-Without limiting other conditions in the License, the grant of rights
-under the License will not include, and the License does not grant to
-you, the right to Sell the Software.
-
-For purposes of the foregoing, "Sell" means practicing any or all of
-the rights granted to you under the License to provide to third parties,
-for a fee or other consideration (including without limitation fees for
-hosting or consulting/support services related to the Software), a
-product or service whose value derives, entirely or substantially, from
-the functionality of the Software.
-
-Any license notice or attribution required by the License must also
-include this Commons Clause License Condition notice.
-
----
-
-MIT License
-
-Copyright (c) 2025 SynkraAI Inc. - AIOS Framework
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-
----
-
-Software: Synkra AIOS (AI-Orchestrated System for Full Stack Development)
-License: MIT
-Licensor: SynkraAI Inc.
+Commons Clause License Condition v1.0
+
+The Software is provided to you by the Licensor under the License,
+as defined below, subject to the following condition.
+
+Without limiting other conditions in the License, the grant of rights
+under the License will not include, and the License does not grant to
+you, the right to Sell the Software.
+
+For purposes of the foregoing, "Sell" means practicing any or all of
+the rights granted to you under the License to provide to third parties,
+for a fee or other consideration (including without limitation fees for
+hosting or consulting/support services related to the Software), a
+product or service whose value derives, entirely or substantially, from
+the functionality of the Software.
+
+Any license notice or attribution required by the License must also
+include this Commons Clause License Condition notice.
+
+---
+
+MIT License
+
+Copyright (c) 2025 SynkraAI Inc. - AIOS Framework
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Software: Synkra AIOS (AI-Orchestrated System for Full Stack Development)
+License: MIT
+Licensor: SynkraAI Inc.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aios-core",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "Synkra AIOS: AI-Orchestrated System for Full Stack Development - Core Framework",
   "bin": {
     "aios": "bin/aios.js",