arkaos 2.17.1 → 2.17.4

package/core/workflow/session_summary.py

@@ -0,0 +1,204 @@
+"""Session summary generator.
+
+Generates end-of-session recap saved to ~/.arkaos/sessions/{session_id}.json
+and optionally printed to stdout.
+
+Includes:
+- Phases completed
+- Total duration
+- Violations
+- Artifacts produced
+- Agent outputs
+"""
+
+import json
+import uuid
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class PhaseSummary:
+    """Summary of a single phase."""
+
+    phase_id: str
+    phase_name: str
+    status: str
+    duration_ms: int = 0
+    artifacts: list[str] = field(default_factory=list)
+    violations: list[str] = field(default_factory=list)
+
+
+@dataclass
+class SessionSummary:
+    """Complete session summary."""
+
+    session_id: str
+    workflow: str
+    project: str
+    started_at: str
+    completed_at: str = ""
+    total_duration_ms: int = 0
+    phases: list[PhaseSummary] = field(default_factory=list)
+    violations: list[dict] = field(default_factory=list)
+    agent_outputs: dict[str, str] = field(default_factory=dict)
+    metadata: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), indent=2)
+
+
+def _sessions_dir() -> Path:
+    """Get sessions directory path."""
+    sessions = Path.home() / ".arkaos" / "sessions"
+    sessions.mkdir(parents=True, exist_ok=True)
+    return sessions
+
+
+def save_session(summary: SessionSummary) -> Path:
+    """Save session summary to JSON file.
+
+    Args:
+        summary: The session summary to save
+
+    Returns:
+        Path to saved file
+    """
+    path = _sessions_dir() / f"{summary.session_id}.json"
+    path.write_text(summary.to_json(), encoding="utf-8")
+    return path
+
+
+def load_session(session_id: str) -> SessionSummary | None:
+    """Load a session summary by ID.
+
+    Args:
+        session_id: The session UUID
+
+    Returns:
+        SessionSummary or None if not found
+    """
+    path = _sessions_dir() / f"{session_id}.json"
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return SessionSummary(**data)
+    except (json.JSONDecodeError, KeyError, OSError):
+        return None
+
+
+def list_sessions(limit: int = 10) -> list[SessionSummary]:
+    """List recent sessions.
+
+    Args:
+        limit: Maximum number of sessions to return
+
+    Returns:
+        List of SessionSummary objects, newest first
+    """
+    sessions_dir = _sessions_dir()
+    if not sessions_dir.exists():
+        return []
+
+    sessions = []
+    for path in sorted(sessions_dir.glob("*.json"), key=lambda p: p.stat().st_mtime, reverse=True)[
+        :limit
+    ]:
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            sessions.append(SessionSummary(**data))
+        except (json.JSONDecodeError, KeyError):
+            pass
+
+    return sessions
+
+
+class SessionSummaryBuilder:
+    """Builder for session summaries."""
+
+    def __init__(self, workflow: str, project: str):
+        self.summary = SessionSummary(
+            session_id=str(uuid.uuid4()),
+            workflow=workflow,
+            project=project,
+            started_at=datetime.now(timezone.utc).isoformat(),
+        )
+
+    def add_phase(self, phase: PhaseSummary) -> None:
+        """Add a phase to the summary."""
+        self.summary.phases.append(phase)
+
+    def add_violation(self, rule: str, detail: str, severity: str = "") -> None:
+        """Add a violation to the summary."""
+        self.summary.violations.append(
+            {
+                "rule": rule,
+                "detail": detail,
+                "severity": severity,
+            }
+        )
+
+    def add_agent_output(self, agent_id: str, output: str) -> None:
+        """Add an agent output."""
+        self.summary.agent_outputs[agent_id] = output
+
+    def set_metadata(self, key: str, value: Any) -> None:
+        """Set a metadata field."""
+        self.summary.metadata[key] = value
+
+    def complete(self) -> SessionSummary:
+        """Finalize and return the summary."""
+        self.summary.completed_at = datetime.now(timezone.utc).isoformat()
+        self.summary.total_duration_ms = sum(p.duration_ms for p in self.summary.phases)
+        return self.summary
+
+    def save(self) -> Path:
+        """Complete and save the session."""
+        self.complete()
+        return save_session(self.summary)
+
+    def render_text(self) -> str:
+        """Render summary as human-readable text."""
+        self.complete()
+        lines = [
+            "═" * 60,
+            "  SESSION SUMMARY",
+            "═" * 60,
+            f"  Session: {self.summary.session_id[:8]}...",
+            f"  Workflow: {self.summary.workflow}",
+            f"  Project: {self.summary.project}",
+            f"  Started: {self.summary.started_at}",
+            f"  Completed: {self.summary.completed_at}",
+            f"  Duration: {self.summary.total_duration_ms}ms",
+            "",
+            "  PHASES",
+        ]
+
+        for phase in self.summary.phases:
+            icon = "✓" if phase.status == "completed" else "✗" if phase.status == "failed" else "○"
+            lines.append(f"  {icon} {phase.phase_name} ({phase.duration_ms}ms)")
+            for artifact in phase.artifacts:
+                lines.append(f"    → {artifact}")
+            for violation in phase.violations:
+                lines.append(f"    ⚠ {violation}")
+
+        if self.summary.violations:
+            lines.append("")
+            lines.append(f"  VIOLATIONS ({len(self.summary.violations)})")
+            for v in self.summary.violations:
+                sev = v.get("severity", "")
+                marker = "🔴" if sev == "BLOCK" else "🟠" if sev == "ESCALATE" else "🟡"
+                lines.append(f"  {marker} [{v.get('rule', '?')}] {v.get('detail', '')}")
+
+        lines.append("═" * 60)
+        return "\n".join(lines)
+
+    def print(self) -> None:
+        """Print summary to stdout."""
+        print(self.render_text())

package/core/workflow/state.py

@@ -34,7 +34,11 @@ def _write(state: dict) -> dict:
     path = _state_path()
     path.parent.mkdir(parents=True, exist_ok=True)
     fd = NamedTemporaryFile(
-        mode="w", dir=str(path.parent), suffix=".tmp", delete=False, encoding="utf-8",
+        mode="w",
+        dir=str(path.parent),
+        suffix=".tmp",
+        delete=False,
+        encoding="utf-8",
     )
     try:
         json.dump(state, fd, indent=2)
@@ -104,7 +108,11 @@ def set_branch(branch: str) -> dict:
 
 
 def add_violation(
-    rule: str, detail: str, tool: str | None = None, file: str | None = None,
+    rule: str,
+    detail: str,
+    tool: str | None = None,
+    file: str | None = None,
+    severity: str | None = None,
 ) -> dict:
     """Append a violation to the violations list."""
     state = _require_state()
@@ -113,6 +121,8 @@ def add_violation(
         violation["tool"] = tool
     if file:
         violation["file"] = file
+    if severity:
+        violation["severity"] = severity
     state["violations"].append(violation)
     return _write(state)
 

package/departments/dev/SKILL.md

@@ -53,60 +53,28 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 For `/dev feature` and `/dev api`:
 
 ```
-Phase 0: SPECIFICATION → Paulo + Gabriel create/validate spec
-  Gate: User approval
-
-Phase 1: RESEARCH → Analyst researches patterns + Gabriel checks architecture
-  Gate: Auto
-
-Phase 2: ARCHITECTURE → Gabriel designs + Marco approves ADR
-  Gate: User approval
-
+Phase 0: SPECIFICATION → Paulo + Gabriel create/validate spec (User approval gate)
+Phase 1: RESEARCH → Analyst + Gabriel check patterns + architecture
+Phase 2: ARCHITECTURE → Gabriel designs + Marco approves ADR (User approval gate)
 Phase 3: IMPLEMENTATION → Andre (backend) + Diana (frontend) in parallel
-  Gate: Auto
-
-Phase 4: SELF-CRITIQUE → Paulo reviews against Clean Code + SOLID
-  Gate: Auto
-
+Phase 4: SELF-CRITIQUE → Paulo reviews Clean Code + SOLID
 Phase 5: SECURITY AUDIT → Bruno runs OWASP Top 10 + dependency scan
-  Gate: Auto
-
-Phase 6: QA → Rita runs ALL tests, checks coverage >= 80%, mutation score
-  Gate: Auto
-
-Phase 7: QUALITY GATE → Marta dispatches Eduardo (copy) + Francisca (tech)
-  Gate: APPROVED required from all three
-
-Phase 8: DOCUMENTATION → Save ADR + docs to Obsidian
-  Gate: Auto
+Phase 6: QA → Rita runs ALL tests, coverage >= 80%, mutation score
+Phase 7: QUALITY GATE → Marta + Eduardo (copy) + Francisca (tech) → APPROVED
+Phase 8: DOCUMENTATION → ADR + docs to Obsidian
 ```
 
 ## Focused Workflow (4 Phases)
 
-For `/dev debug`, `/dev refactor`, `/dev db`, `/dev performance`, `/dev pipeline`:
-
-```
-Phase 0: DIAGNOSE → Relevant specialist investigates
-Phase 1: IMPLEMENT → Fix/change with tests
-Phase 2: VERIFY → Rita validates, Paulo reviews
-Phase 3: QUALITY GATE → Marta reviews
-```
+For `/dev debug`, `/dev refactor`, `/dev db`, `/dev performance`, `/dev pipeline`: Diagnose → Implement with tests → Rita validates → Quality Gate (Marta).
 
 ## Specialist Workflow (2 Phases)
 
-For `/dev review`, `/dev test`, `/dev security-audit`, `/dev clean-review`:
-
-```
-Phase 0: EXECUTE → Specialist agent performs the task
-Phase 1: REPORT → Results saved to Obsidian
-```
+For `/dev review`, `/dev test`, `/dev security-audit`, `/dev clean-review`: Execute → Report (Obsidian).
 
 ## Branch Workflow (Mandatory)
 
-All code-modifying commands create a feature branch:
-- Features: `feature/<slug>`
-- Fixes: `fix/<slug>`
-- Refactors: `refactor/<slug>`
+Feature branches: `feature/<slug>` · `fix/<slug>` · `refactor/<slug>`
 
 ## Frameworks Applied
 

package/departments/dev/skills/agent-design/SKILL.md

@@ -101,31 +101,11 @@ Surface these issues WITHOUT being asked:
 
 ```markdown
 ## Agent System Design: <System Name>
-
-### Architecture
-- **Pattern:** <selected pattern>
-- **Rationale:** <why this pattern fits>
-
-### Agents
-| Agent | Role | Tools | Interfaces |
-|-------|------|-------|-----------|
-| ... | ... | ... | ... |
-
-### Communication
-- **Pattern:** <message passing / shared state / event-driven>
-- **Handoff contract:** <fields passed between agents>
-
-### Guardrails
-- **Input:** <validation rules>
-- **Output:** <filtering rules>
-- **Human gates:** <approval checkpoints>
-
-### Evaluation Metrics
-- Task success rate target: >X%
-- Latency budget: <Xms per stage>
-- Cost ceiling: <$ per task>
+### Architecture: <pattern> | Rationale: <why>
+### Agents: | Agent | Role | Tools | Interfaces |
+### Communication: <pattern> | Handoff: <fields passed>
+### Guardrails: Input <rules> | Output <rules> | Human gates <checkpoints>
+### Evaluation: Success >X% | Latency <Xms/stage | Cost <$$/task
 ```
 
-## References
-
-- [architecture-patterns.md](references/architecture-patterns.md) — 5 multi-agent patterns with decision matrix, anti-patterns, and scaling characteristics
+See `references/architecture-patterns.md` for multi-agent pattern details.

package/departments/dev/skills/ci-cd-pipeline/SKILL.md

@@ -87,48 +87,25 @@ Surface these issues WITHOUT being asked:
 ```yaml
 # .github/workflows/ci.yml
 name: CI
-on:
-  push:
-    branches: [main, develop]
-  pull_request:
-    branches: [main]
-
+on: { push: { branches: [main, develop] }, pull_request: { branches: [main] } }
 jobs:
   lint:
     runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: <setup-action>
-      - run: <install-command>
-      - run: <lint-command>
-
+    steps: [uses: actions/checkout@v4, uses: <setup-action>, run: <install-command>, run: <lint-command>]
   test:
     needs: lint
     runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: <setup-action>
-      - run: <install-command>
-      - run: <test-command>
-
+    steps: [uses: actions/checkout@v4, uses: <setup-action>, run: <install-command>, run: <test-command>]
   build:
     needs: test
     runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: <setup-action>
-      - run: <install-command>
-      - run: <build-command>
-
+    steps: [uses: actions/checkout@v4, uses: <setup-action>, run: <install-command>, run: <build-command>]
   deploy:
     needs: build
     if: github.ref == 'refs/heads/main'
     environment: <staging|production>
     runs-on: ubuntu-latest
-    steps:
-      - run: <deploy-command>
+    steps: [run: <deploy-command>]
 ```
 
-## References
-
-- [github-actions-patterns.md](references/github-actions-patterns.md) — Caching strategies, matrix builds, reusable workflows, secret management, deployment environments, and common pitfalls
+See `references/github-actions-patterns.md` for caching strategies and deployment patterns.

package/departments/dev/skills/db-schema/SKILL.md

@@ -106,29 +106,11 @@ Surface these issues WITHOUT being asked:
 
 ```markdown
 ## Schema Design: <Feature Name>
-
-### Entities
-| Table | Purpose | Key Columns |
-|-------|---------|------------|
-| ... | ... | ... |
-
-### Relationships
-| From | To | Type | FK |
-|------|-----|------|-----|
-| ... | ... | 1:N | ... |
-
-### Indexes
-| Table | Columns | Type | Reason |
-|-------|---------|------|--------|
-| ... | ... | composite | ... |
-
-### Migration
-<Laravel migration code>
-
-### ERD
-<Mermaid diagram>
+### Entities: | Table | Purpose | Key Columns |
+### Relationships: | From | To | Type | FK |
+### Indexes: | Table | Columns | Type | Reason |
+### Migration: <Laravel migration code>
+### ERD: <Mermaid diagram>
 ```
 
-## References
-
-- [indexing-strategy.md](references/indexing-strategy.md) — B-tree vs hash vs GIN vs GiST, composite index ordering, partial indexes, covering indexes, EXPLAIN ANALYZE interpretation
+See `references/indexing-strategy.md` for B-tree vs hash vs GIN vs GiST and EXPLAIN ANALYZE.

package/departments/dev/skills/dependency-audit/SKILL.md

@@ -117,6 +117,4 @@ Surface these issues WITHOUT being asked:
 - Recommendation: {SAFE TO DEPLOY | FIX BEFORE DEPLOY | BLOCK DEPLOY}
 ```
 
-## References
-
-- [license-matrix.md](references/license-matrix.md) — Open source license compatibility matrix, copyleft obligations, commercial use implications, and dual-licensing strategies
+See `references/license-matrix.md` for full license compatibility matrix.

package/departments/dev/skills/incident/SKILL.md

@@ -101,29 +101,11 @@ Surface these issues WITHOUT being asked:
 
 ```markdown
 ## Incident Report: <title>
-
-### Summary
-- Severity: SEV{level}
-- Duration: {start} to {end} ({total time})
-- Impact: {users/services affected}
-- Root Cause: {1-2 sentence summary}
-
-### Timeline
-| Time | Event |
-|------|-------|
-
-### Root Cause Analysis
-[5 Whys / Fishbone / Timeline analysis]
-
-### Action Items
-| # | Action | Owner | Due | Status |
-|---|--------|-------|-----|--------|
-
-### Lessons Learned
-1. [Key takeaway]
-2. [Key takeaway]
+### Summary: SEV{level} | Duration: {start}-{end} | Impact: {users/services} | Root Cause: {1-2 sentences}
+### Timeline: | Time | Event |
+### Root Cause: [5 Whys / Fishbone analysis]
+### Action Items: | # | Action | Owner | Due | Status |
+### Lessons Learned: 1. [takeaway] 2. [takeaway]
 ```
 
-## References
-
-- [severity-playbook.md](references/severity-playbook.md) — SEV1-4 definitions, escalation paths, communication templates, and PIR checklist
+See `references/severity-playbook.md` for SEV1-4 definitions and escalation paths.

package/departments/dev/skills/mcp-builder/SKILL.md

@@ -101,21 +101,8 @@ Surface these issues WITHOUT being asked:
 
 ```markdown
 ## MCP Server: <Server Name>
-
-### Tools
-| Tool | Description | Params | Returns |
-|------|------------|--------|---------|
-| ... | ... | ... | ... |
-
-### Auth
-- **Strategy:** <env vars / OAuth / API key>
-- **Outbound hosts:** <allowlist>
-
-### Versioning
-- **Current:** v<X>
-- **Compatibility:** <backward-compatible since vX>
-
-### Deployment
-- **Runtime:** <Python / TypeScript>
-- **Transport:** <stdio / HTTP>
+### Tools: | Tool | Description | Params | Returns |
+### Auth: <strategy> | Outbound hosts: <allowlist>
+### Versioning: v<X> | Compatibility: <backward-compatible since vX>
+### Deployment: <Python / TypeScript> | Transport: <stdio / HTTP>
 ```

package/departments/dev/skills/observability/SKILL.md

@@ -90,34 +90,11 @@ Surface these issues WITHOUT being asked:
 
 ```markdown
 ## Observability Design: <project>
-
-### Service Inventory
-| Service | SLI | SLO Target | Current |
-|---------|-----|------------|---------|
-
-### Logging
-- Format: [structured JSON / plaintext -- recommendation]
-- Missing correlation IDs: [list]
-- Level misuse: [list]
-
-### Metrics & Alerts
-- Golden signals coverage: [X/4 per service]
-- Alert rules: [count] ([actionable %])
-- Missing alerts: [list]
-
-### Tracing
-- Instrumented services: [X/Y]
-- Sampling strategy: [head/tail/adaptive]
-
-### Dashboard Plan
-- [Executive | Service | Component] dashboards needed
-
-### Recommendations (priority order)
-1. [Most impactful improvement]
-2. [Next priority]
-3. [Next priority]
+### Service Inventory: | Service | SLI | SLO Target | Current |
+### Logging: Format, missing IDs, level issues
+### Metrics & Alerts: Golden signals X/4, alert rules, missing alerts
+### Tracing: Instrumented X/Y, sampling strategy
+### Dashboard Plan: [Executive | Service | Component] dashboards needed
 ```
 
-## References
-
-- [slo-design.md](references/slo-design.md) — SLI/SLO/SLA framework, error budget calculations, and burn rate alert configuration
+See `references/slo-design.md` for SLI/SLO/SLA framework details.

package/departments/dev/skills/performance-profiler/SKILL.md

@@ -99,30 +99,9 @@ Surface these issues WITHOUT being asked:
 
 ```markdown
 ## Performance Profile: <Target>
-
-### Baseline
-| Metric | Value | Budget | Status |
-|--------|-------|--------|--------|
-| P50 latency | 480ms | < 100ms | OVER |
-| P95 latency | 1240ms | < 200ms | OVER |
-| P99 latency | 3100ms | < 1000ms | OVER |
-| DB queries/req | 23 | < 10 | OVER |
-
-### Root Cause
-[What the profiler revealed]
-
-### Fix Applied
-[What changed]
-
-### After
-| Metric | Before | After | Delta |
-|--------|--------|-------|-------|
-| P50 | 480ms | 48ms | -90% |
-| P95 | 1240ms | 120ms | -90% |
-| P99 | 3100ms | 280ms | -91% |
-| Queries | 23 | 1 | -96% |
-
-### Recommendations
-| Priority | Action | Expected Impact |
-|----------|--------|----------------|
+### Baseline: | Metric | Value | Budget | Status |
+### Root Cause: [what profiler revealed]
+### Fix Applied: [what changed]
+### After: | Metric | Before | After | Delta |
+### Recommendations: | Priority | Action | Expected Impact |
 ```

package/departments/dev/skills/rag-architect/SKILL.md

@@ -103,28 +103,10 @@ Surface these issues WITHOUT being asked:
 
 ```markdown
 ## RAG System Design: <System Name>
-
-### Pipeline
-- **Chunking:** <strategy>, <size>, <overlap>
-- **Embedding:** <model>, <dimensions>
-- **Vector DB:** <database>, <index type>
-- **Retrieval:** <strategy>, top-K=<N>
-- **Reranking:** <model or none>
-
-### Evaluation Targets
-| Metric | Target |
-|--------|--------|
-| Faithfulness | >X% |
-| Context Relevance | >X |
-| Answer Relevance | >X |
-
-### Cost Estimate
-- Embedding cost: ~$X per 1K docs
-- Storage: ~$X/month for <N> vectors
-- Query cost: ~$X per 1K queries
+### Pipeline: Chunking <strategy+size+overlap> | Embedding <model+dims> | Vector DB <db+index>
+### Retrieval: <strategy>, top-K=<N> | Reranking: <model or none>
+### Evaluation: Faithfulness >X% | Context Relevance >X | Answer Relevance >X
+### Cost: Embedding ~$X/1K docs | Storage ~$X/mo | Query ~$X/1K queries
 ```
 
-## References
-
-- [chunking-strategies.md](references/chunking-strategies.md) — Decision tree and benchmarks for chunking approaches
-- [evaluation-guide.md](references/evaluation-guide.md) — RAGAS metrics and ground truth dataset creation
+See `references/chunking-strategies.md` and `references/evaluation-guide.md` for details.

package/departments/dev/skills/release/SKILL.md

@@ -110,21 +110,8 @@ Surface these issues WITHOUT being asked:
 
 ```markdown
 ## Release Plan: v{X.Y.Z}
-
-### Version Bump: {MAJOR|MINOR|PATCH}
-### Reason: {summary of changes}
-
-### Readiness
-- [ ] Code quality gates: {PASS/FAIL}
-- [ ] Documentation: {PASS/FAIL}
-- [ ] Approvals: {PASS/FAIL}
-
-### Changes Included
-- Features: {count}
-- Fixes: {count}
-- Breaking changes: {count}
-
-### Deployment Strategy: {blue-green / canary / rolling}
-### Rollback Plan: {container revert / feature flag / DB-safe}
-### Risk Assessment: {LOW / MEDIUM / HIGH}
+### Version Bump: {MAJOR|MINOR|PATCH} | Reason: {summary}
+### Readiness: Code quality [PASS/FAIL] | Docs [PASS/FAIL] | Approvals [PASS/FAIL]
+### Changes: Features {count} | Fixes {count} | Breaking {count}
+### Deployment: {blue-green/canary/rolling} | Rollback: {plan} | Risk: {LOW/MEDIUM/HIGH}
 ```