@olives/devos 2.1.1 → 4.0.0

package/docs/2026-09-03-devos-ecc-gap-analysis.md

@@ -0,0 +1,187 @@
+# Dev-OS Gap Analysis vs ECC (+ DeepSeek Harness & Other Agentic Workflow Patterns)
+
+## Scope
+This document compares current Dev-OS capabilities to patterns found in:
+- ECC (`affaan-m/ecc`)
+- DeepSeek Harness (`deepseek-ai/deepseek-harness`)
+- Broader agentic orchestration references (LangGraph, AutoGen, CrewAI, repository-harness)
+
+Goal: identify concrete upgrade opportunities for Dev-OS in agents, skills, hooks, memory, and graph-style orchestration.
+
+## Executive Summary
+Dev-OS has strong foundational workflow discipline (clear role separation, staged quality gates, human approval). Its biggest opportunity is to evolve from a mostly **linear workflow policy** into a **stateful graph-orchestrated runtime** with:
+1. richer agent specialization,
+2. evented hooks beyond commit time,
+3. shared durable memory for collaborative agents,
+4. installable capability packs and profile-driven setup,
+5. measurable reliability/eval loops.
+
+## Current Dev-OS Baseline (Observed)
+- Agent personas: **11** (`.agents/agents/*.md`)
+- Skills: **60** (`.agents/skills/*`)
+- Slash commands: **10** (`.agents/commands/*.md`)
+- Hook/enforcement model today: pre-commit gate via `.agents/scripts/install-hooks.sh` + `.agents/scripts/commit.sh`
+- Generated integration model: `.agents/commands` + `.agents/agents` compiled to `.claude/commands` and `.claude/agents` via `devos init`.
+
+## ECC / DeepSeek Signals Relevant to Dev-OS
+
+### ECC patterns worth extracting
+- Large specialization surface (declared: **68 agents, 286 skills, 94 commands**) with harness-specific adapters and shared core behaviors.
+- Runtime hook graph with lifecycle events (`PreToolUse`, `PostToolUse`, `SessionStart`, `PreCompact`, `Stop`, `SessionEnd`) and profile-based control (`minimal/standard/strict`).
+- Explicit memory persistence lifecycle and a dedicated **unified-memory** skill for cross-harness handoffs.
+- Install/runtime manifests (`.claude/ecc-tools.json`) including dependency graph + managed file ownership for safer upgrades and uninstall behavior.
+- Multi-agent coordination patterns (`dmux-workflows`, codex multi-agent role configs).
+
+### DeepSeek Harness patterns worth extracting
+- “Everything is a plugin” capability seams and composition by profile/bundle rather than hardcoded monolith behavior.
+- Event-centric architecture and durable session event logs as a system of record.
+- Clear extension-point taxonomy for tools, agents, sessions, workflows, and providers.
+- Experimental team coordination seam (task board + mailbox concept) as a graph-like collaboration primitive.
+
+### Broader agentic workflow ecosystem signals
+- LangGraph emphasis: durable execution, stateful agents, long/short memory, human-in-the-loop checkpoints.
+- AutoGen/CrewAI emphasis: orchestrated multi-agent teams, event-driven flows, observability/tracing.
+- repository-harness emphasis: repository-as-source-of-truth, explicit authority boundaries, proof-driven completion.
+
+## Gap Matrix: Dev-OS vs Upgrade Opportunities
+
+| Area | Dev-OS today | Gap | Upgrade direction |
+|---|---|---|---|
+| Agent specialization | 11 general team roles | Missing domain micro-agents and execution modes | Add tiered role catalog (core + optional domain packs) |
+| Skills architecture | Rich but mostly static skills | No package/dependency model for skills | Introduce installable skill packs with dependency graph |
+| Hooks | Commit gate + secret scan at commit-time | Missing session/tool lifecycle hooks | Add runtime hook pipeline (pre/post tool, session lifecycle, compaction) |
+| Orchestration model | Workflow docs define linear steps | No runtime DAG/state machine of tasks | Introduce graph execution engine with explicit node states and transitions |
+| Memory | `CURRENT_STATE.md` + `LESSONS.md` | No structured shared memory ledger across agents/sessions | Add durable memory vault (project/team/user scopes, typed entries, handoff protocol) |
+| Multi-agent collaboration | Conceptual routing via Orchestrator | No shared task board/mailbox state | Add agent collaboration primitives (task queue, mailbox, ownership locks) |
+| Eval/reliability | QA/Tester/Security flow exists | No formal pass@k/eval harness | Add eval-driven workflow + regression suites + run scorecards |
+| Observability | Minimal workflow visibility | No execution trace graph/metrics | Add event logs, step traces, failure taxonomy, token/cost telemetry |
+| Install/update lifecycle | `devos init` copies templates | No ownership manifest/conflict-safe updater | Add managed-files manifest + guided update/migrate flow |
+| Cross-harness parity | Claude generation exists | Limited first-class Codex/other harness ergonomics | Add harness adapters + parity matrix + capability flags |
+
+## Recommended Feature Upgrades for Dev-OS
+
+## 1) Graph Engineering Core (highest impact)
+Build a graph-based orchestration layer where every task is a DAG:
+- nodes: planner, researcher, implementer, reviewer, tester, security, deploy-check,
+- edges: dependency, approval, retry,
+- node states: queued/running/blocked/failed/passed,
+- policies: retry budgets, circuit breaker, escalation.
+
+Expected outcome: less manual orchestration overhead, clearer parallelism, deterministic resumability.
+
+## 2) Shared Memory Vault + Handoff Protocol
+Add a structured memory subsystem that supports:
+- scoped memory (`project`, `team`, optional `user`),
+- typed documents (`context`, `decision`, `handoff`, `lesson`, `risk`),
+- provenance metadata (author agent, source files, confidence, timestamp),
+- search/read/write/doctor commands.
+
+Expected outcome: collaborating agents can inherit context safely without overloading prompt windows.
+
+## 3) Runtime Hook Framework (beyond pre-commit)
+Introduce event hooks inspired by ECC lifecycle:
+- `SessionStart`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`, `SessionEnd`.
+- profile controls: `minimal`, `standard`, `strict`.
+- hook registry for local scripts with safe defaults and explicit opt-ins.
+
+Expected outcome: proactive enforcement and automation throughout the session, not only at commit time.
+
+## 4) Capability Pack System for Skills/Agents
+Move from static template copy toward composable packs:
+- pack manifest (`id`, `version`, `dependsOn`, `files`, `conflictsWith`),
+- optional packs (security-hardening, eval, data-science, mobile, enterprise-governance),
+- install/update/remove with ownership tracking.
+
+Expected outcome: lean default install, scalable specialization, safer updates.
+
+## 5) Reliability and Eval Layer
+Create a first-class eval workflow:
+- define capability evals + regression evals per major feature change,
+- pass@k tracking for agent workflows,
+- gating rules (“cannot mark complete if required eval suite regresses”),
+- longitudinal scorecards per agent role/workflow.
+
+Expected outcome: quantifiable confidence in autonomous execution quality.
+
+## 6) Multi-Agent Collaboration Primitives
+Add shared operational state:
+- task board (who owns what, status, blockers),
+- mailbox/events for cross-agent requests,
+- artifact contracts (what output format each handoff requires),
+- conflict prevention (file locks/intents or explicit ownership claims).
+
+Expected outcome: better parallel execution with fewer duplicate/conflicting edits.
+
+## 7) Harness Parity Strategy
+Define first-class harness adapters (Claude, Codex, Cursor, others) with:
+- support matrix by capability (agents, skills, hooks, memory, MCP),
+- adapter-specific constraints and generated outputs,
+- compatibility tests for generated surfaces.
+
+Expected outcome: Dev-OS behaves predictably across environments, not only Claude-first.
+
+## Suggested New/Expanded Dev-OS Agent Set
+Keep current core, add optional packs:
+- **Planning/Control**: graph-orchestrator, dependency-manager, loop-operator
+- **Quality**: eval-engineer, regression-guardian, benchmark-analyst
+- **Memory/Knowledge**: memory-curator, handoff-auditor, decision-librarian
+- **Security/Governance**: policy-enforcer, secret-hygiene-auditor, compliance-reviewer
+- **Domain packs**: language/framework reviewers (Go, Python, Java, Rust, Laravel, mobile)
+
+## Suggested New Skill Families
+- graph-workflow-design
+- workflow-runtime-observability
+- shared-memory-operations
+- handoff-contracts
+- eval-driven-development
+- postmortem-pattern-extraction
+- harness-parity-testing
+- pack-authoring-and-versioning
+
+## Suggested Hook Profiles
+- **minimal**: commit gate + secret scan + session summary
+- **standard**: minimal + post-edit quality checks + compact reminders + activity tracking
+- **strict**: standard + stronger tool-use blocking rules + expanded policy checks
+
+## Implementation Phasing (for future work)
+
+### Phase 1 — Foundation
+- Define graph execution schema and state model
+- Define memory document schema + storage locations
+- Add runtime hook loader with profile support
+
+### Phase 2 — Core Runtime
+- Wire orchestrator to graph runtime
+- Add task board/mailbox primitives
+- Add lifecycle hooks and memory ingestion at session boundaries
+
+### Phase 3 — Reliability + Ecosystem
+- Add eval framework and scorecards
+- Add capability-pack installer/updater with ownership manifests
+- Add harness parity matrix + compatibility tests
+
+## Risks / Trade-offs
+- More runtime machinery increases complexity; must keep zero-dependency CLI constraints where required.
+- Over-automation can weaken human governance if escalation policies are not explicit.
+- Shared memory can become noisy without strict schemas and pruning/doctor tooling.
+- Harness fragmentation risk if parity tests are not automated.
+
+## Success Metrics for “Dev-OS better than today”
+- Reduced manual intervention per feature delivery cycle.
+- Higher first-pass completion rate of delegated tasks.
+- Lower rework loops across Developer↔QA↔Tester.
+- Faster cross-session recovery time (from interruption to productive resume).
+- Measurable eval pass@k improvement and reduced escaped defects.
+
+## Suggested Immediate Next Decisions
+1. Choose memory scope model (`project/team/user`) and governance policy.
+2. Decide graph engine location (CLI-native module vs skill runtime extension).
+3. Decide initial hook event set and default profile.
+4. Decide minimum viable capability-pack manifest schema.
+5. Pick 3 pilot workflows to graphify first (feature delivery, bugfix, dependency update).
+
+## References Analyzed
+- Dev-OS local repository (`.agents/AGENTS.md`, `docs/ARCHITECTURE.md`, `docs/SLASH_COMMANDS.md`, `.agents/scripts/*`, `bin/devos.js`)
+- ECC (`AGENTS.md`, `README.md`, `hooks/README.md`, `hooks/hooks.json`, `hooks/memory-persistence/*`, `.claude/ecc-tools.json`, `.codex/config.toml`, selected skills)
+- DeepSeek Harness (`README.md`, `AGENTS.md`, `docs/architecture.md`, selected `.agents/skills/*`)
+- Additional references: `langchain-ai/langgraph`, `microsoft/autogen`, `crewAIInc/crewAI`, `hoangnb24/repository-harness`

package/docs/2026-09-12-devos-v4-roadmap-research.md

@@ -0,0 +1,314 @@
+# Dev-OS v4.0 Research & Architectural Roadmap
+
+**Document ID:** DEVOS-RES-2026-09-12  
+**Author:** Antigravity & Olives Technologies Engineering OS  
+**Status:** PROPOSED & UNDER RESEARCH  
+**Scope:** Building upon the ECC/DeepSeek Gap Analysis (`docs/2026-09-03-devos-ecc-gap-analysis.md`) and addressing real-world field experience from production usage.
+
+---
+
+## 1. Executive Summary
+
+Dev-OS v3.0.0 successfully laid the foundation for enterprise multi-agent workflows:
+- **F1:** Runtime Lifecycle Hooks (`.agents/hooks/`, `.claude/hooks.json`).
+- **F2:** Composable Capability Packs (`.agents/packs.json`, lean installs).
+- **F3:** Structured Shared Memory Vault (`.agents/memory/`, ADRs, handoffs).
+- **F4:** Deterministic Task Board DAG State (`docs/TASK_BOARD.md`, `/task`).
+- **F5:** Multi-Platform Harness Expansion (Claude, Google Antigravity/Gemini, OpenCode, Cursor, Codex) with user-selectable targeting.
+
+However, real-world development experience and analysis of the remaining items in the ECC/DeepSeek gap analysis reveal **five critical systemic problems** that currently hinder full autonomous leverage:
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                       CURRENT REAL-WORLD PAIN POINTS                        │
+├─────────────────────────────────────────────────────────────────────────────┤
+│ 1. ORCHESTRATOR AMNESIA: Agents and skills are not mechanically enforced.   │
+│    The model forgets to route tasks to specialists (Dev, QA, Tester, DBA)   │
+│    and bypasses installed skills, collapsing into a single monolithic chat. │
+│                                                                             │
+│ 2. UNGOVERNED UI CODE: Developers jump straight into frontend code without   │
+│    an established design system, resulting in generic "AI aesthetic" styling│
+│    despite `ui-ux-pro-max` being installed. DESIGN.md is created manually.  │
+│                                                                             │
+│ 3. LACK OF FULL HANDS-OFF SDLC: No autonomous mode where an idea can be     │
+│    given to the team, and an executive proxy oversees the full SDLC         │
+│    (Inception → Design → Architecture/DB → Code → Test → QA → Security).   │
+│                                                                             │
+│ 4. SYNTHETIC AI CONTENT: Generated docs, marketing copy, and PRDs suffer    │
+│    from robotic AI tells (forced triads, not-X-but-Y, hyperbolic fluff).    │
+│                                                                             │
+│ 5. STATIC ECOSYSTEM & LOST FEEDBACK: Skills/agents are frozen on disk with   │
+│    no auto-update checks; failures and rule regressions are lost locally    │
+│    instead of feeding improvements back to the Dev-OS core repository.      │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+This research document defines the architecture, mechanical enforcement mechanisms, and implementation roadmap for **Dev-OS v4.0**.
+
+---
+
+## 2. Gap Analysis vs Field Experience Matrix
+
+| Gap Analysis Recommendation | Field Problem Observed | Proposed v4.0 Solution |
+|---|---|---|
+| **Graph Engineering Core** | Orchestrator forgets to delegate; acts as a solo agent | **Mechanical Routing Enforcement Engine (MREE)** via `PreToolUse` hook + Task Board State Machine |
+| **Handoff Contracts** | UI code created without design spec; missing seed data | **Mandatory Design Gate (`docs/DESIGN.md`)** & **Database Seed Protocol** |
+| **Autonomous Workflows** | Human must micromanage every intermediate agent handoff | **Dev-OS Autonomous Executive Mode (`devos run` / `/auto`)** with dynamic subagent spawning |
+| **Quality & Voice Standards** | Documentation and copy read like generic LLM prose | **Mechanical Humanizer Gate (`blader/humanizer`)** on all markdown prose |
+| **Dynamic Capability Packs** | Skills are static; no sync with upstream repos | **Dynamic Skill & Upstream Registry Updater (`devos update --skills`)** |
+| **Observability & Telemetry** | When Dev-OS breaks or loops, insights are trapped locally | **Autonomous Telemetry, RCA Engine & Auto-PR Feedback Loop** |
+
+---
+
+## 3. Pillar 1: Mechanical Agent & Skill Enforcement Engine
+
+### 3.1 The Root Cause of "Orchestrator Amnesia"
+Large Language Models naturally gravitate toward the path of least resistance: answering everything in a single generation. While the commit gate succeeded because `.git/hooks/pre-commit` and `.agents/scripts/commit.sh` are **hard binary shell scripts**, agent delegation and skill invocations have historically relied on **prompt instructions**. Prompt instructions can be bypassed or forgotten during high-context reasoning.
+
+### 3.2 The Mechanical Enforcement Architecture
+To guarantee agents and skills are used without human micromanagement, enforcement must move from *advisory text* to *runtime hook validation*:
+
+```
+User Prompt / Goal
+       │
+       ▼
+[Task Board DAG Check] ──► Is active task queued in docs/TASK_BOARD.md?
+       │                   If NO: Block tool calls until task is declared.
+       ▼
+[Role Authority Check] ──► Is tool caller acting as the assigned specialist?
+       │                   - Developer cannot edit docs/DESIGN.md
+       │                   - QA cannot author production code
+       │                   - Architect cannot author migration SQL
+       ▼
+[Skill Invocation Check]─► Did the task declare a mandatory skill?
+       │                   - UI Task: requires `ui-ux-pro-max`
+       │                   - Documentation Task: requires `humanizer`
+       │                   - Database Task: requires `supabase-postgres-best-practices`
+       ▼
+[PreToolUse Hook] ───────► PASS: Execute tool | FAIL: Reject with exact remediation instruction
+```
+
+### 3.3 Hook Implementation Specification
+In `.agents/hooks/pre-tool-use.sh`:
+1. **Target Inspection:** Inspect files touched by `edit_file`, `write_to_file`, or bash commands.
+2. **Task State Verification:**
+   - Verify `docs/TASK_BOARD.md` contains an active task in `[IN_PROGRESS]`.
+   - If a UI file (`*.tsx`, `*.jsx`, `*.vue`, `*.svelte`, `*.html`, `*.css`) is modified:
+     - Check whether `docs/DESIGN.md` exists and is marked `[APPROVED]`.
+     - If missing, halt execution: `"FAIL: Cannot modify frontend components without an approved docs/DESIGN.md. Delegate to UI Designer using skill ui-ux-pro-max first."`
+3. **Audit Token Enforcement:** Tools pass through only when the executing subagent or persona matches the required role in the task contract.
+
+---
+
+## 4. Pillar 2: Mandatory Design Gate (`docs/DESIGN.md`) & `ui-ux-pro-max`
+
+### 4.1 The Problem
+Even with `ui-ux-pro-max` installed in `.agents/skills/ui-ux-pro-max/`, AI developers often generate standard grey/blue dashboard components with generic typography and arbitrary spacing. The human is forced to intervene repeatedly to define aesthetics.
+
+### 4.2 The Solution: The Design Gate Contract
+Before **any** frontend code or component may be implemented:
+1. The **UI Designer** agent is invoked.
+2. The UI Designer executes the `ui-ux-pro-max` query engine against the project type (e.g. B2B SaaS, developer tool, fin-tech, landing page):
+   ```bash
+   python3 .agents/skills/ui-ux-pro-max/scripts/search.py "SaaS dashboard minimalist typography" --domain style,typography,color
+   ```
+3. The UI Designer generates a formal specification: `docs/DESIGN.md`.
+4. The QA Agent must audit `docs/DESIGN.md` before implementation begins.
+
+### 4.3 Specification: `docs/DESIGN.md` Schema
+Every project requiring visual presentation must have a locked `docs/DESIGN.md` specifying:
+- **Design Archetype:** (e.g., *Technical Minimalist*, *Cyberpunk/Terminal*, *Warm Editorial*, *Bento Modern*).
+- **Color Palette:** Primary, Secondary, Background, Surface, Border, and Semantic tokens (Success, Warning, Error) with exact WCAG 4.5:1 contrast verified.
+- **Typography System:** Primary Display font, Body font, and Monospace font with modular type scale (e.g., 12px, 14px, 16px, 20px, 24px, 32px).
+- **Layout & Grid:** Container max-widths, column grid, responsive breakpoints (`sm`, `md`, `lg`, `xl`), and spacing scale (4px/8px increments).
+- **Component Signatures:** Border radius scale (e.g., sharp 2px vs rounded 12px), button interaction states, shadow elevation levels.
+- **Iconography & Asset Rules:** SVG icon set (e.g., Lucide, Heroicons; strictly NO emojis as functional icons).
+
+---
+
+## 5. Pillar 3: Professional Autonomous SDLC Mode ("DevOS Mode")
+
+### 5.1 Hands-Off Concept
+The user submits a high-level product idea (e.g., *"Build an offline-first markdown notes app with full-text search and tag filtering"*).
+In **Autonomous Mode** (`devos run` or `/devos-mode`):
+- A virtual **Executive Director / Tech Lead Proxy** assumes the human lead's oversight responsibilities.
+- The user can step away; the system executes the professional SDLC sequentially with strict gates:
+
+```mermaid
+flowchart TD
+    Idea["User Idea / Prompt"] --> Stage1["Stage 1: Architect (grill-me) -> docs/PROJECT_REQUIREMENTS.md"]
+    Stage1 --> Stage2["Stage 2: UI Designer (ui-ux-pro-max) -> docs/DESIGN.md"]
+    Stage2 --> Stage3["Stage 3: DBA Agent -> Schema Migrations + Seed Fixtures"]
+    Stage3 --> Stage4["Stage 4: Orchestrator -> docs/TASK_BOARD.md DAG"]
+    Stage4 --> Stage5["Stage 5: Developer -> Implementation (Dynamic Subagents)"]
+    Stage5 --> Stage6["Stage 6: Tester -> Unit, Integration & Seed Data E2E"]
+    Stage6 --> Stage7["Stage 7: QA Agent -> Code Standards & Design Compliance"]
+    Stage7 --> Stage8["Stage 8: Security Agent -> OWASP, Auth & Secret Scan"]
+    Stage8 --> Stage9["Stage 9: Humanizer -> Scrub AI Clichés from Docs & PRD"]
+    Stage9 --> Complete["Stage 10: Human Checkpoint -> Review Final Staged PR"]
+```
+
+### 5.2 Dynamic Subagent Spawning
+During Stage 4 & 5, agents have explicit authority to spawn subagents dynamically:
+- Developer spawns `research` subagent to check documentation or inspect package versions.
+- Tester spawns subagents to run isolated mock environments.
+- DBA spawns seed-generation tasks to populate realistic databases (e.g. faker scripts, edge-case test users, stress datasets).
+
+### 5.3 Database & Seed Data Protocol
+In modern professional engineering, untestable software stems from empty databases.
+The **DBA Agent** is assigned a mandatory sub-deliverable in Stage 3:
+1. `migrations/`: Schema definition with foreign keys, constraints, and indexes.
+2. `seeds/`: Realistic, domain-specific seed fixtures (`dev-seed.sql` or `seed.ts`) covering:
+   - 10+ standard records.
+   - 3+ boundary/edge cases (special characters, unicode, max-length inputs).
+   - Test user credentials for development authentication.
+
+---
+
+## 6. Pillar 4: Humanizer Skill Integration & Documentation Gate
+
+### 6.1 The AI-Writing Dilemma
+Modern AI assistants write in a predictable cadence:
+- Forced triads (`"fast, reliable, and scalable"`).
+- Not-X-but-Y formulas (`"It is not just a tool, but a revolution"`).
+- Dramatic one-line closers (`"Let that sink in."` / `"That is the real win."`).
+- Superlative padding (`"pivotal"`, `"crucial"`, `"testament"`, `"seamless"`).
+
+When Dev-OS generates documentation, customer-facing content, copywriting, or PR summaries, these tells immediately signal unverified robotic output.
+
+### 6.2 Architectural Solution: First-Party Humanizer
+1. **Skill Integration:** Integrate `https://github.com/blader/humanizer` directly into `.agents/skills/humanizer/SKILL.md`.
+2. **Release & QA Gate:**
+   - The QA Agent and Release Manager run the `humanizer` pattern scanner over any newly generated `.md` files in `docs/`, `README.md`, marketing materials, or PR descriptions.
+   - Any unedited structural tells (§1–§5) trigger a `CHANGES REQUESTED` verdict with automated de-fluffing.
+3. **Upstream Sync:** Track `blader/humanizer` upstream releases to incorporate emerging pattern detections as foundation models evolve.
+
+---
+
+## 7. Pillar 5: Dynamic Upstream Skill & Agent Registry
+
+### 7.1 Beyond Static File Copies
+In Dev-OS v3.0.0, `devos init` copies skills and agents into `.agents/skills/` and `.agents/agents/`. Once copied, they become static snapshot files that miss bug fixes, new security rules, or updated style databases.
+
+### 7.2 Dynamic Registry Architecture
+```
+                         DEV-OS CENTRAL REGISTRY
+                    (or GitHub Repositories: blader/humanizer,
+                     nextlevelbuilder/ui-ux-pro-max-skill)
+                                   │
+                                   ▼
+                       `devos update --check`
+                                   │
+                 ┌─────────────────┴─────────────────┐
+                 ▼                                   ▼
+      [CLI Foreground Update]             [SessionStart Hook Check]
+      $ devos update --skills             "Update available for ui-ux-pro-max
+      Safely pulls latest commits         (v2.4 -> v3.0). Run devos update."
+      into .agents/skills/
+```
+
+### 7.3 CLI Operations
+- `devos update --skills`: Pulls upstream updates for installed capability packs and specialist skills while preserving local overrides.
+- `devos skill add <repo|name>`: Dynamically installs external agent skills (e.g. `devos skill add blader/humanizer`).
+- `devos skill list`: Displays installed skills, versions, and update statuses.
+- **Session-Start Background Ping:** In `.agents/hooks/session-start.sh`, run a 500ms non-blocking check against the npm registry or GitHub release tag, printing a non-intrusive alert when updates are available.
+
+---
+
+## 8. Pillar 6: Autonomous Telemetry, Failure RCA & Auto-PR Feedback Loop
+
+### 8.1 The Feedback Problem
+When Dev-OS users encounter:
+- An agent hallucinating a broken command,
+- A pre-commit hook regex failing on edge-case paths,
+- A circuit breaker triggering after 3 failed QA loops,
+- The Orchestrator forgetting a protocol,
+...these incidents are currently trapped on the user's machine. The core Dev-OS project never learns from these field failures.
+
+### 8.2 Autonomous Self-Improvement Architecture
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                       LOCAL DEV-OS RUNTIME RUNNER                           │
+│                                                                             │
+│  [Hook / Runtime Event] ──► Error, Crash, or Circuit Breaker Trip           │
+│                                      │                                      │
+│                                      ▼                                      │
+│  [.agents/telemetry/events.jsonl] ──► Anonymized Local Event Buffer         │
+│                                      │                                      │
+│                                      ▼                                      │
+│  [Meta / Telemetry Agent] ──────────► Performs Root Cause Analysis (RCA)   │
+│                                      │                                      │
+│                                      ▼                                      │
+│  [Sanitization & Privacy Gate] ─────► Strips code, secrets, IP, file paths │
+│                                      │                                      │
+│                                      ▼                                      │
+│  [Automated Feedback PR Engine] ────► Generates GitHub Issue or Pull Request│
+│                                       to `olitech1010/dev-os` with the fix! │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### 8.3 Security & Privacy First Principles
+Telemetry and automated feedback MUST adhere to strict privacy rules:
+1. **Opt-In / Opt-Out Transparency:** Configured in `.agents/manifest.json` (`telemetry: "anonymized"` or `telemetry: "off"`).
+2. **Strict Anonymization:**
+   - Never send proprietary business logic, project code, or git commit history.
+   - Never send API keys, passwords, or tokens (verified via Gitleaks scanner before transmission).
+   - Only transmit: Dev-OS version, Node runtime, target AI harness, failure error signature, tool name, and RCA diagnosis.
+3. **Automated PR Dispatch:**
+   - When a clear fix is synthesized (e.g., a regex fix in `pre-tool-use.sh` or a clarifying line in `developer.md`), the agent drafts a pull request formatted as `fix(engine): resolve edge case in hook verification`.
+   - Uses `gh pr create` targeting `olitech1010/dev-os` from an anonymous/forked branch, allowing the core team to review and merge improvements from the community continuously.
+
+---
+
+## 9. Phased Implementation Roadmap
+
+### Phase 4A: Mechanical Enforcement & Gate Hardening (Immediate Next Step)
+- **4A.1: PreToolUse Mechanical Enforcement:** Implement active task and role verification in `.agents/hooks/pre-tool-use.sh`.
+- **4A.2: Mandatory Design Gate:** Add `docs/DESIGN.md` schema, block frontend modifications if missing, and integrate `ui-ux-pro-max` query automation.
+- **4A.3: Humanizer Skill Integration:** Add `blader/humanizer` to `.agents/skills/humanizer/` and wire into documentation/PR review workflows.
+
+### Phase 4B: Autonomous Executive Mode & Upstream Registry
+- **4B.1: Autonomous Executive SDLC Runner:** Implement `devos run` / `/auto` mode with full stage sequencing (Inception → Design → Architecture/DB → Code → Test → QA → Security → Docs).
+- **4B.2: Database & Seed Protocol:** Standardize DBA deliverable with automated test seed generation.
+- **4B.3: Dynamic Skill Updater:** Implement `devos update --skills` and non-blocking session-start update alerts.
+
+### Phase 4C: Observability, RCA & Auto-PR Feedback Loop
+- **4C.1: Local Telemetry Buffer:** Implement `.agents/telemetry/events.jsonl` tracking circuit breaker trips and rule violations.
+- **4C.2: Meta / RCA Telemetry Agent:** Create dedicated analysis agent persona (`.agents/agents/telemetry.md`).
+- **4C.3: Anonymized Feedback PR Engine:** Automated issue/PR synthesis to `olitech1010/dev-os`.
+
+---
+
+## 10. User-Approved Architectural Decisions & Ratification
+
+Following review by the Engineering Lead, the following core architecture decisions are ratified for implementation in Dev-OS v4.0:
+
+1. **Mechanical Design Gate (Hard Block):**
+   - `.agents/hooks/pre-tool-use.sh` hard-blocks frontend file creation and editing (`*.tsx`, `*.jsx`, `*.vue`, `*.svelte`, `*.html`, `*.css` in source directories) if `docs/DESIGN.md` does not exist.
+   - The UI Designer agent must first extract design tokens and patterns from `ui-ux-pro-max`, generate `docs/DESIGN.md`, and obtain QA approval before developers write frontend components.
+
+2. **Standardized Execution Modes:**
+   - `interactive` (Default): Standard pair-programming with orchestrator, staged reviews, and human approval before commits.
+   - `guided`: Step-by-step confirmation checkpoints for each SDLC stage with explicit confirmation prompts.
+   - `auto` (`devos run` / `/auto`): Hands-off autonomous mode tailored for non-technical startup founders, CEOs, and MVP builders. An Executive Proxy / Product Lead orchestrates the complete SDLC from idea to functional MVP.
+   - `audit`: Read-only evaluation and diagnostic mode for analyzing code quality, security posture, and standards compliance.
+
+3. **Interactive Human Tester Guide (`/docs/TESTING_GUIDE.md`):**
+   - In `auto` mode, the testing stage produces a dedicated deliverable: `/docs/TESTING_GUIDE.md`.
+   - This document provides a step-by-step interactive walkthrough for non-technical founders and QA testers.
+   - Includes seed data records, test accounts (`user@example.com`, `admin@example.com`), and simple test passwords: **`devos123` universally throughout for all users**.
+
+4. **Default Telemetry (`telemetry: on (recommended)`):**
+   - During installation and manifest initialization, telemetry is enabled by default to capture anonymized failure events, error codes, and RCA reports locally in `.agents/telemetry/events.jsonl`.
+   - Generates automated feedback pull requests or reports back to `olitech1010/dev-os` to continually harden Dev-OS.
+   - Users can explicitly opt out via `--no-telemetry` or `devos telemetry disable`.
+
+5. **Mechanical Humanizer Integration:**
+   - `blader/humanizer` is integrated into `.agents/skills/humanizer/SKILL.md` and added to the `core` capability pack.
+   - QA and Release Manager agents enforce the humanizer checklist across all generated documentation in `/docs/`, PR summaries, and PRDs.
+   - Pre-commit and pre-tool hooks provide automated scanning via `.agents/scripts/humanize-check.sh`.
+
+6. **Expanded Agent & Skill Catalog:**
+   - Incorporates agent roles and skills from ECC (`affaan-m/ecc`), Claude Code, and DeepSeek Harness into composable capability packs.
+   - Includes UI Designer (`ui-designer.md`), Telemetry Agent (`telemetry.md`), Executive Proxy (`executive-proxy.md`), and Eval Engineer (`eval-engineer.md`).
+

package/docs/ARCHITECTURE.md

@@ -103,12 +103,94 @@ flowchart LR
     Target --> Workflow[Execute Workflow / Prompt]
 ```
 
+### Runtime Lifecycle Hooks Flow (F1)
+
+```mermaid
+flowchart TD
+    SessionStart[SessionStart Hook] --> Fetch[git fetch --all --prune]
+    Fetch --> Digest[Display Hard Rules Digest]
+    
+    ToolInvocation[Tool Execution / Bash] --> PreToolUse{PreToolUse Hook}
+    PreToolUse -- Destructive Command Blocked --> Abort[Abort & Require Dry-Run Plan]
+    PreToolUse -- Raw git commit Blocked --> GateMsg[Redirect to commit.sh]
+    PreToolUse -- Valid Command --> Execute[Execute Tool]
+    
+    SessionClose[SessionEnd Hook] --> StateCheck{CURRENT_STATE.md Updated?}
+    StateCheck -- No & Code Modified --> Warn[Display Rule #13 Reminder]
+    StateCheck -- Yes --> End[Clean Exit]
+```
+
+### Deterministic Task Board & DAG State (F4)
+
+```mermaid
+flowchart LR
+    Backlog[BACKLOG] --> Queued[QUEUED]
+    Queued --> InProgress[IN_PROGRESS]
+    InProgress --> ParallelGate[PARALLEL_GATE]
+    ParallelGate --> HumanCheck[HUMAN_CHECKPOINT]
+    HumanCheck --> Done[DONE]
+```
+
+### Multi-Harness Engine (F5)
+
+```mermaid
+flowchart TD
+    Core[Dev-OS Core: .agents/] --> Compiler[devos init / update]
+    Compiler --> Claude[Claude Code: .claude/ + CLAUDE.md + hooks.json]
+    Compiler --> Cursor[Cursor: .cursor/rules/devos.mdc + .cursorrules]
+    Compiler --> OpenCode[OpenCode: OPENCODE.md + .opencode/rules/]
+    Compiler --> Gemini[Gemini / Antigravity: GEMINI.md]
+    Compiler --> Codex[Codex / Windsurf: .codex/ + .windsurfrules]
+```
+
+### Autonomous SDLC & Mandatory Design Gate (v4.0)
+
+```mermaid
+flowchart TD
+    Idea["Product Idea / MVP Goal"] --> Stage1["1. Inception: Architect (grill-me) -> docs/PROJECT_REQUIREMENTS.md"]
+    Stage1 --> Stage2["2. Design Gate: UI Designer (ui-ux-pro-max) -> docs/DESIGN.md"]
+    Stage2 --> Stage3["3. Schema & Seeds: DBA -> Migrations + Fixtures (devos123)"]
+    Stage3 --> Stage4["4. Task DAG: Orchestrator -> docs/TASK_BOARD.md"]
+    Stage4 --> Stage5["5. Implementation: Developer -> Code authoring"]
+    Stage5 --> Stage6["6. Test Suite: Tester -> Unit/E2E Tests"]
+    Stage6 --> Stage7["7. Testing Guide: Tester -> docs/TESTING_GUIDE.md"]
+    Stage7 --> Stage8["8. QA Gate: QA -> Lint, Types & Design Gate Audit"]
+    Stage8 --> Stage9["9. Security Gate: Security -> OWASP & Secrets Scan"]
+    Stage9 --> Stage10["10. Humanizer: Release Manager -> humanize-check.sh"]
+    Stage10 --> FinalReview["Founder Delivery Briefing"]
+```
+
+### Telemetry & Root Cause Analysis (RCA) Feedback Loop
+
+```mermaid
+flowchart LR
+    HookErr[Hook Failure / Circuit Breaker Trip] --> LocalLog[Local Buffer: .agents/telemetry/events.jsonl]
+    LocalLog --> TelemetryAgent[Telemetry Agent: RCA Diagnosis]
+    TelemetryAgent --> Sanitize[Sanitization & Privacy Gate: Strip Code & Secrets]
+    Sanitize --> UpstreamPR[Automated Bug Report / PR to olitech1010/dev-os]
+```
+
 ## Directory Structure
 
 - `.agents/`: The core logic of the OS.
-  - `agents/`: System prompts for each agent.
-  - `commands/`: Slash commands.
-  - `skills/`: Agent capabilities.
-  - `scripts/`: Tooling (e.g., `commit.sh`).
-- `docs/`: User documentation.
-- `src/` (or similar): The actual project source code being managed.
+  - `agents/`: System prompts for each agent persona (Orchestrator, Developer, QA, Tester, DBA, DevOps, Architect, Researcher, Memory Manager, Release Manager, UI Designer, Executive Proxy, Telemetry, Eval Engineer).
+  - `commands/`: Slash commands (YAML frontmatter + instructions: `task.md`, `auto.md`, `design.md`, `humanize.md`, `telemetry.md`, etc.).
+  - `skills/`: Specialist engineering skills (`humanizer/`, `testing-guide/`, `autonomous-sdlc/`, `telemetry/`, etc.).
+  - `hooks/`: Runtime lifecycle hooks (`session-start.sh`, `pre-tool-use.sh`, `session-end.sh`).
+  - `memory/`: Shared memory vault (`decisions/ADRs`, `handoffs/`, `context.json`).
+  - `telemetry/`: Local failure event buffer (`events.jsonl`).
+  - `scripts/`: Tooling (`commit.sh`, `install-hooks.sh`, `humanize-check.sh`).
+  - `packs.json`: Composable capability pack definitions.
+  - `manifest.json`: Installed pack tracking, execution mode, telemetry configuration, and version metadata.
+- `docs/`: Project documentation.
+  - `DESIGN.md`: Mandatory design system specification extracted from `ui-ux-pro-max`.
+  - `TESTING_GUIDE.md`: Interactive human walkthrough guide with seed accounts and universal password `devos123`.
+  - `TASK_BOARD.md`: Deterministic DAG task board state machine.
+  - `CURRENT_STATE.md`: Single source of truth for active tasks and blockers.
+  - `LESSONS.md`: Episodic memory and incident learnings.
+- Multi-Harness Outputs:
+  - `.claude/`: Claude Code commands, agents, and lifecycle hooks.
+  - `.cursor/rules/`: Cursor MDC rule definition.
+  - `.opencode/`: OpenCode configuration and rules.
+  - `CLAUDE.md`, `OPENCODE.md`, `GEMINI.md`: Root harness guidance.
+

package/docs/CHANGELOG.md

@@ -3,6 +3,19 @@
 All notable changes to Dev-OS are documented in this file.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [3.0.0] — 2026-09-11
+
+### Major Features & Upgrades
+- **Runtime Lifecycle Hook Framework (F1)**: Introduced `.agents/hooks/` (`session-start.sh`, `pre-tool-use.sh`, `session-end.sh`) and `.claude/hooks.json` mapping `SessionStart`, `PreToolUse`, and `SessionEnd`. Mechanically enforces Hard Rule #1 (blocks destructive actions), Hard Rule #8 (blocks raw git commit), Hard Rule #13 (session-end state obligation), and Hard Rule #14 (freshness check).
+- **Composable Capability Packs (F2)**: Added pack registry (`.agents/packs.json`) and project manifest (`.agents/manifest.json`). `devos init` now installs lean stack-tailored packs (`core` + target stack), reducing initial token context by 60–75%. Added `devos pack list` and `devos pack add <name>` CLI commands.
+- **Structured Shared Memory Vault (F3)**: Added `.agents/memory/` containing Architecture Decision Records (`decisions/ADR-000-template.md`), session handoffs (`handoffs/handoff-template.md`), and `context.json`. Added `devos memory list`, `devos memory handoff`, and `devos memory doctor` CLI commands, along with `.agents/skills/shared-memory/SKILL.md`.
+- **Deterministic Task Board & DAG Workflow State (F4)**: Added `docs/TASK_BOARD.md` state machine (`[BACKLOG]`, `[QUEUED]`, `[IN_PROGRESS]`, `[PARALLEL_GATE]`, `[HUMAN_CHECKPOINT]`, `[DONE]`), `/task` slash command (`.agents/commands/task.md`), and `.agents/skills/task-board/SKILL.md`.
+- **Multi-Harness Expansion + OpenCode (F5)**: Expanded compilation engine to natively generate rules and configuration across major AI IDEs: **Claude Code** (`.claude/`), **Cursor** (`.cursor/rules/devos.mdc`, `.cursorrules`), **OpenCode** (`OPENCODE.md`, `.opencode/rules/devos-rules.md`, `.opencode/opencode.json`), **Google Antigravity & Gemini** (`ANTIGRAVITY.md`, `GEMINI.md`), and **Codex & Windsurf** (`.codex/instructions.md`, `.windsurfrules`). Added interactive platform selector (Step 3 in `devos init`) and CLI flags (`-p, --platform <name>`, `--harness <list>`) so developers can tailor their workspace for specific tools or generate universal configurations.
+
+## [2.1.1] — 2026-09-10
+
+- **Official npm Scope Release**: Successfully published to npm under `@olives/devos` as public package.
+
 ## [2.1.0] — 2026-09-03
 
 - **Official npm Package Scope (`@olives/devos`)**: Formally registered under the official Olives organization on npm as `@olives/devos` (executable CLI binaries remain `devos`, `olives-devos`, and `devos-init`).