diff --git a/README.md b/README.md index f0ce3956..5f624b0a 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,7 @@ * [4.1. From Manual to Agentic](#41-from-manual-to-agentic) * [4.2. Evolution Path](#42-evolution-path) * [4.3. Adaptive AI Tiering and Rate Limiting](#43-adaptive-ai-tiering-and-rate-limiting) + * [4.4. Doc-as-Behavior Mandate Bridge](#44-doc-as-behavior-mandate-bridge) 5. [5. Dual-Edition Architecture (V1 vs V2)](#5-dual-edition-architecture-v1-vs-v2) * [5.1. V1: The Exhaustive Archive](#51-v1-the-exhaustive-archive) * [5.2. V2: The Agentic Elite Edition](#52-v2-the-agentic-elite-edition) @@ -50,6 +51,7 @@ * [9.4. Deployment Lifecycle](#94-deployment-lifecycle) * [9.5. Automated Mandate Auditing](#95-automated-mandate-auditing) * [9.6. Multi-Part Reporting Engine](#96-multi-part-reporting-engine) + * [9.7. Workflow UI Auto-Sync](#97-workflow-ui-auto-sync) 10. [10. Branching Strategy and Lifecycle](#10-branching-strategy-and-lifecycle) 11. [11. Contributing to the Archive](#11-contributing-to-the-archive) 12. [12. Developer Experience and VSCode Setup](#12-developer-experience-and-vscode-setup) @@ -231,6 +233,11 @@ To ensure maximum throughput and resilience, Nubenetes uses a proprietary **Mult - **Quality-based Upgrading**: If a high-speed model (Flash) fails to produce valid structured data (JSON), the engine automatically triggers an **Elite Fallback**, re-routing the same request to a Pro model to ensure zero-loss curation quality. - **Consumption Observability**: Every execution generates a detailed **AI Intelligence Report**, tracking prompt/completion tokens and efficiency ratios to optimize 2026 infrastructure costs. +### 4.4. Doc-as-Behavior Mandate Bridge +Nubenetes implements a direct bridge between documentation and AI behavior: +- **Mandate Ingestion**: At the start of every workflow, the `MandateIngestor` parses the natural language instructions in [`GEMINI.md`](GEMINI.md). +- **Dynamic Context**: These mandates are injected directly into the AI's system instructions, ensuring that the bot's reasoning is always aligned with the latest project policies without requiring manual code updates. + --- ## 5. Dual-Edition Architecture (V1 vs V2) @@ -300,6 +307,7 @@ To maximize economic efficiency, all AI agents follow a **Database-First** appro ### 6.3. Database Lifecycle and Hygiene To maintain a high-performance "Single Source of Truth", Nubenetes implements automated hygiene protocols: +- **Semantic Drift Detection**: Using **SHA256 Content Fingerprinting**, the system monitors for silent updates in technical resources. If the content of a link changes significantly (e.g., a version update or blog rewrite), it is automatically flagged for AI re-evaluation to refresh its summary and impact score. - **GitHub Branch Auto-Heal**: If a deep link returns a 404, the engine automatically attempts to rescue it by migrating the path from `master` to `main`. Verified revivals are automatically updated in the V1 archive. - **Parked Domain Detection**: Using AI-driven content inspection, the engine identifies expired domains displaying "Buy this domain" parking pages, marking them as `DEAD` even if they return an HTTP 200 status. - **Auto-Redirect Fix (Canonical Updates)**: During health checks, if a permanent redirection (301/302) is detected, the engine automatically updates the Markdown files with the final **Canonical URL**. This reduces latency and prevents future link rot. @@ -440,6 +448,7 @@ graph TD ### 7.6. Strategic Benefits - **Platinum Lifecycle Management**: The system implements advanced data engineering fields including **SHA256 Content Fingerprinting** (to detect silent content drift), **Health Reliability Scoring** (0-100 EMA), and **Source Provenance Tracking**. This ensures that autonomous agents make context-aware decisions throughout the multi-year lifecycle of every technical resource. +- **Deep Semantic Deduplication**: The V2 engine identifies multiple URLs belonging to the same technical project (e.g., website, repository, documentation) and consolidates them into a single **Authoritative Super-Entry** with `aliases`, ensuring a clean V2 portal while preserving full link history in V1. - **Technical Immutability (V1)**: AI agents are strictly forbidden from overwriting human-curated titles, manual 🌟 stars, or additional descriptive comments in the V1 archive, ensuring the bot respects and preserves manual engineering effort. - **Automated Semantic Interlinking (Mandate 5)**: AI agents identify technical relationships between categories and automatically inject cross-references (*"See also..."*) into the V1 archive, transforming it into an interconnected technical web. - **Executive Comparison Tables (V2 Premium)**: High-density categories in the V2 portal feature AI-generated technical comparison tables (Solution, Maturity, Focus, Language), providing instant decision support for architects. @@ -564,6 +573,9 @@ Every Pull Request generated by the Agentic engine includes a non-blocking **Saf ### 9.6. Multi-Part Reporting Engine To handle the scale of 17,000+ resources, the GitOps manager implements a **Multi-Part Reporting System**. If the audit matrix or execution log exceeds GitHub's character limits, the engine automatically fragments the report into multiple successive PR comments, ensuring 100% observability without data truncation. +### 9.7. Workflow UI Auto-Sync +To maintain **Mandate 11**, the system features a metadata-driven UI synchronization engine. It automatically detects new categories in the curation sources and alerts the maintainer to update the GitHub Actions interface, ensuring the control plane is always a perfect mirror of the underlying technical data. + --- ## 10. Branching Strategy and Lifecycle