Merge pull request #6 from udx/development

feat: high-fidelity workflow mesh and Context7 synchronization

Author: fqjony

.github/workflows/context7-ops.yml

@@ -0,0 +1,12 @@
+name: Context7 Sync
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  sync:
+    uses: udx/reusable-workflows/.github/workflows/context7-ops.yml@feature/context7-sync
+    secrets:
+      context7_api_key: ${{ secrets.CONTEXT7_API_KEY }}

.gitignore

@@ -1,8 +1,10 @@
-# Workspace
+# dev.kit State & Hub
 .udx/
 .dev.kit/
 .codex/
 .tmp/
+.drift.tmp
+.processed.tmp
 tasks/
 
 # OS

README.md

@@ -1,63 +1,70 @@
-<img src="assets/logo.svg" alt="dev.kit logo" width="200">
+# dev.kit: The Thin Empowerment Layer
 
-# dev.kit — Resolve the Development Drift
+**Experienced engineering flow with high-fidelity, deterministic results.**
 
-**Experienced engineering flow with no-bullshit results.**
+`dev.kit` resolves the **Drift** (intent divergence) by **Normalizing** it into a deterministic path and **Iterating** to resolution. It acts as a **Thin Empowerment Layer** that bridges human intent with repository truth via **Context-Driven Engineering (CDE)**.
 
-`dev.kit` resolves the **Drift** (intent divergence) by **Normalizing** it into a deterministic path and **Iterating** to the result. It acts as a **Thin Empowerment Layer** (Grounding) that bridges chaotic intent with repository-based skills.
+### 1. Grounding (The Bridge)
+Intent is mapped to repo-specific logic and normalized into a deterministic execution plan.
+![Grounding Bridge](assets/diagrams/grounding-bridge.svg)
 
-## How it Works: The Grounding Bridge
+### 2. Normalization (The Gate)
+Capabilities are resolved at runtime through a **Dynamic Discovery Engine** that scans script headers and skills.
+![Normalization Gate](assets/diagrams/normalization-boundary.svg)
 
-`dev.kit` empowers AI agents (Gemini, Antigravity) with repository-centric grounding:
+### 3. Execution (The Engine)
+AI iterates through instruction steps with deterministic validation and real-time status updates.
+![Execution Engine](assets/diagrams/execution-engine.svg)
 
-1.  **Grounding & Normalization**: Intent is mapped to repo-specific logic and normalized into a deterministic execution plan.
-2.  **Skill Discovery**: `dev.kit` exposes "Experienced Skills" directly to your AI agent's toolbelt (native skill discovery).
-3.  **Waterfall Progression**: AI iterates through instruction steps with deterministic validation and real-time feedback.
+## Standard Engineering Flow
 
-![Intent-to-Action Flow](assets/diagrams/intent-to-action.svg)
+`dev.kit` provides a **Thin Empowerment Layer** that bridges chaotic intent with deterministic repository functions.
 
-## Core Interface
+| Phase | Description | Implementation |
+| :--- | :--- | :--- |
+| **1. Grounding** | **UDX Worker** provides the isolated, pre-hydrated base environment. | [`udx/worker`](docs/reference/operations/worker-ecosystem-refs.md) |
+| **2. Discovery** | **Skill Mesh** resolves internal commands and `@udx` NPM packages. | [`@udx/mcurl`](docs/ai/mesh/npm.md) |
+| **3. Normalize** | AI Reasoning Skills transform intent into a bounded `workflow.md`. | [`SKILL.md`](docs/skills/README.md) |
+| **4. Execute** | Deterministic Primitives execute the logic within the CLI boundary. | `lib/commands/` |
 
-`dev.kit` focuses on repository health and agent empowerment, leaving high-level reasoning to your preferred agent.
+---
 
-- **`dev.kit status`**: (Default) Engineering brief and system diagnostic.
-- **`dev.kit ai`**: Unified agent integration management (Sync, Skills, Status).
-- **`dev.kit task`**: Manage the lifecycle of active workflows and sessions.
-- **`dev.kit config`**: Environment and repository orchestration settings.
+## Core Interface
 
-## Managed AI Skills
+- **`dev.kit status`**: (Default) High-fidelity engineering brief and system health.
+- **`dev.kit doctor`**: Verify environment health, software detection, and compliance.
+- **`dev.kit ai`**: Unified agent integration management and grounding.
+- **`dev.kit sync`**: Logical, atomic repository synchronization and drift resolution.
+- **`dev.kit task`**: Manage the lifecycle of active workflows and engineering sessions.
 
-`dev.kit` provides a suite of deterministic engineering skills that are grounded in your repository's truth:
+> **Execution**: Run any repository-bound skill with `dev.kit skills run <name>`.
 
-- **`visualizer`**: Generate and export high-fidelity Mermaid diagrams (SVG).
-- **`git-sync`**: Resolve repository drift with logical, atomic commits.
-- **`core`**: Maintain environment health and synchronize agent context.
+---
 
-> **Execution**: Run any skill with `dev.kit skills run <name>`.
+## Documentation
 
-## AI Integration
+The `dev.kit` knowledge base is structured to reflect **CDE Principles**.
 
-`dev.kit` integrates natively with your AI agent to enforce standardization and repository truth.
+- **[Foundations](docs/README.md#%EF%B8%8F-foundations)**: Core philosophy (CDE), dev.kit primitives, and methodology.
+- **[Runtime](docs/README.md#%EF%B8%8F-runtime)**: CLI overview, lifecycle, and execution loops.
+- **[AI Integration](docs/README.md#-ai-integration)**: Grounded orchestration and agent mission.
+- **[Best Practices](docs/foundations/best-practices.md)**: High-fidelity engineering rules and command mappings.
 
-```bash
-# Sync skills and engineering context to your agent (Gemini/Codex)
-dev.kit ai sync
-```
-
-> **Grounding Layer**: `dev.kit` does not replace your agent; it hydrates it with the repository's source of truth.
+---
 
 ## Install
 
 ```bash
 curl -fsSL https://udx.dev/dev.kit/install.sh | bash
 ```
 
-## Documentation
+## 📚 Authoritative References
+
+The `dev.kit` mission is grounded in foundational research on high-fidelity automation and AI orchestration:
 
-- **Managed AI Skills**: `docs/ai/skills.md`
-- **Scenarios & Workflows**: `docs/scenarios/README.md`
-- **CLI Overview**: `docs/cli/overview.md`
-- **AI Orchestration**: `docs/ai/README.md`
+- **[The Power of Automation](https://andypotanin.com/the-power-of-automation-how-it-has-transformed-the-software-development-process/)**: Systematic transformation of the engineering flow.
+- **[Observation-Driven Management](https://andypotanin.com/observation-driven-management-revolutionizing-task-assignment-efficiency-workplace/)**: Revolutionary task normalization through pattern recognition.
+- **[Autonomous Technical Operations](https://andypotanin.com/claude-operator-prompt/)**: Principles for high-fidelity agent grounding and execution.
 
 ---
 _UDX DevSecOps Team_

assets/dev-kit-diagram-generator-ux.mmd

@@ -1,5 +1,10 @@
 flowchart LR
-    Source[Canonical Source] --> Project[Adaptation / Projection]
-    Project --> ToolA[Tool A Format]
-    Project --> ToolB[Tool B Format]
-    Project --> Fallback[Fail-Open Fallback]
+    Source[(Repo Source)] --> Discovery{Discovery}
+    Discovery --> Mapping[Fidelity Mapping]
+    Mapping --> Projection([Tool Projection])
+    Projection -- Fail-Open --> Source
+    
+    style Source fill:#bbf,stroke:#333,stroke-width:2px
+    style Discovery fill:#dfd,stroke:#333,stroke-width:2px
+    style Mapping fill:#dfd,stroke:#333,stroke-width:2px
+    style Projection fill:#f9f,stroke:#333,stroke-width:2px