PythonWoods · PythonWoods-Dev · Jul 26, 2026 · Jul 26, 2026 · Jul 26, 2026 · Jul 26, 2026
diff --git a/.draft/OrchestrationPrompts/Roadmaps/0. Priority Table.md b/.draft/OrchestrationPrompts/Roadmaps/0. Priority Table.md
@@ -0,0 +1,73 @@
+# Zenzic Roadmap & Prompt Priority Table
+
+| Stato | Priorità | Prompt | Feature | Motivazione architetturale |
+| :--- | :--- | ---: | :--- | :--- |
+| `[x]` | **P0** | Prompt 1 | **Zenzic Language Server (ZLS) & VS Code Integration** | Fondamento della strategia "Shift-Left". Senza ZLS stabile, le funzionalità IDE successive non hanno una base affidabile. (Rilasciato in v0.23.x). |
+| `[x]` | **P0** | Prompt 10 | **Incremental Analysis Engine** | Necessario per rendere ZLS réellement utilizzabile. Riduce il costo delle analisi incrementali e preserva il requisito di latenza sub-50ms. (Rilasciato in v0.23.x). |
+| `[x]` | **P1** | Prompt 7 | **VS Code Code Actions (Quick Fixes)** | Completa il ciclo diagnostica → remediation. Abilita Quick Fixes deterministici via `textDocument/codeAction` e `WorkspaceEdit` in-memory. (Rilasciato in v0.24.0). |
+| `[x]` | **P1** | Prompt 8 | **DQS Workspace UI** | Porta la qualità globale nell'ambiente autore tramite un bridge asincrono deterministico CLI (`zenzic score --json`) e visualizzazione nella Status Bar di VS Code. (Completata in v0.26.0). |
+| `[x]` | **P0** | — | **LSP Stabilization & Hot-Reloading** | Parità di governance CLI-IDE e hot-reloading guidato da `watched_config_files` dell'Adapter. (Rilasciato in v0.25.0). |
+| `[ ]` | **P0** | Prompt 6 | **Smart Link Graph** | Completa il modello VSM trasformandolo da sistema di risoluzione a motore di analisi topologica completa. Abilita rilevamento di isole, cicli e struttura documentale. |
+| `[ ]` | **P0** | Prompt 15 | **Baseline & Regression Tracking** | Introduce il controllo evolutivo della qualità. Indispensabile per CI enterprise e per impedire regressioni DQS. |
+| `[ ]` | **P1** | Prompt 2 | **Semantic Linting & Readability Metrics** | Estende Zenzic oltre la validazione strutturale verso la qualità del contenuto mantenendo il paradigma deterministic static analysis. |
+| `[ ]` | **P1** | Prompt 16 | **Configuration Validation Engine** | Riduce errori operativi e diventa la sorgente unica per CLI, VS Code e documentazione tramite Mirror Law. |
+| `[ ]` | **P1** | Prompt 14 | **Policy-as-Code Engine** | Formalizza la governance. Trasforma configurazioni sparse e ADR in un modello dichiarativo verificabile. |
+| `[ ]` | **P2** | Prompt 3 | **Docusaurus Bridge Architecture** | Prima implementazione concreta dell'ecosistema adapter. Valida il modello VSM artifact-based fuori dal Core. |
+| `[ ]` | **P2** | Prompt 4 | **Sphinx Adapter** | Estende la compatibilità open-source. Deve seguire la stabilizzazione del contratto BaseAdapter. |
+| `[ ]` | **P2** | Prompt 5 | **Hugo Adapter** | Analogo allo Sphinx Adapter. Priorità inferiore perché dipende dall'efficacia del modello adapter. |
+| `[ ]` | **P2** | Prompt 12 | **Custom Rule SDK v3** | Importante per ecosistema e community, ma richiede prima stabilità dell'engine di analisi e sandbox. |
+| `[ ]` | **P2** | Prompt 13 | **SARIF Enterprise Integration** | Migliora integrazione security e compliance, ma non modifica il cuore architetturale. |
+| `[ ]` | **P3** | Prompt 17 | **Performance Telemetry Engine** | Utile per ottimizzazione e governance operativa, ma deve seguire la stabilizzazione del runtime. |
+| `[ ]` | **P3** | Prompt 19 | **Zenzic Audit Mode** | Feature enterprise ad alto valore, ma richiede stabilità di DQS, Policy Engine e SARIF. |
+| `[ ]` | **P3** | Prompt 18 | **Multi Repository Documentation Graph** | Feature avanzata che amplia il dominio, ma richiede prima maturità completa di VSM, Smart Graph e artifact composition. |
+| `[ ]` | **P3** | Prompt 9 | **VS Code Configuration Autocomplete** | Importante per UX, ma subordinata alla stabilizzazione dello schema configurativo e del Configuration Validation Engine. |
+
+---
+
+## Sequenza milestone aggiornata
+
+| Milestone | Obiettivo | Prompt coinvolti | Stato |
+| :--- | :--- | :--- | :--- |
+| **v0.23 — Authoring Intelligence Foundation** | Portare Zenzic dentro l'IDE con feedback immediato | 1 → 10 | `[x] Completata` |
+| **v0.24 — Interactive Intelligence** | Completa il ciclo diagnostica → remediation nell'IDE | 7 | `[x] Completata` |
+| **v0.25 — LSP Stabilization & Hot-Reloading** | Parità CLI-IDE, hot-reload adapter, path normalization | — | `[x] Rilasciata` |
+| **v0.26 — DQS Workspace UI** | Visualizzazione deterministica DQS nell'editor via CLI bridge asincrono | 8 | `[x] Completata (v0.26.0)` |
+| **v0.27 — Deterministic Quality Platform** | Evolvere da validator a quality governance engine | 6 → 15 → 2 → 16 | `[ ] In programma` |
+| **v0.28 — Governance & Extensibility** | Aprire SDK, policy e integrazioni enterprise | 14 → 12 → 13 → 19 | `[ ] In programma` |
+| **v0.29 — Ecosystem Expansion** | Espandere il perimetro verso framework esterni | 3 → 4 → 5 → 18 | `[ ] In programma` |
+| **v0.30 — Operational Excellence** | Ottimizzazione e osservabilità avanzata | 17 → 9 | `[ ] In programma` |
+
+---
+
+## Dipendenze critiche
+
+```text
+ZLS (v0.23.x - Complete)
+ │
+ ├── Incremental Analysis Engine (v0.23.x - Complete)
+ │       │
+ │       ├── Code Actions (v0.24.0 - Complete)
+ │       ├── DQS Workspace UI (v0.26.0 - Complete)
+ │       └── Hot-Reloading & Governance Parity (v0.25.0 - Complete)
+ │
+ ├── Smart Link Graph (v0.27)
+ │       │
+ │       └── Multi Repository Graph (v0.29)
+ │
+ ├── DQS Model
+ │       │
+ │       ├── Baseline Tracking (v0.27)
+ │       ├── Policy Engine (v0.28)
+ │       └── Audit Mode (v0.28)
+ │
+ └── Adapter Contract
+         │
+         ├── Docusaurus (v0.29)
+         ├── Sphinx (v0.29)
+         └── Hugo (v0.29)
+```
+
+Questa sequenza mantiene una progressione coerente:
+
+**Core deterministico → IDE intelligence → LSP Stabilization → Quality Governance → Ecosystem Expansion → Enterprise Platform**.
+
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -30,7 +30,6 @@ Before advancing the core feature set, the following infrastructural and validat
 *Completing the diagnostic-to-remediation loop within the IDE.*
 
 - **VS Code Code Actions (Quick Fixes):** Implement `textDocument/codeAction` via LSP to allow users to instantly apply deterministic fixes (e.g., `Z121`, `Z603`) directly from the editor.
-- **DQS Workspace UI:** Bring the Document Quality Score (DQS) into the authoring environment via a dedicated VS Code sidebar panel, providing global repository state without leaving the editor.
 
 ### [v0.25] — LSP Stabilization & Hot-Reloading
 
@@ -40,7 +39,13 @@ Before advancing the core feature set, the following infrastructural and validat
 - **Adapter-Driven Config Hot-Reloading:** Enable real-time VSM topology rebuilds in VS Code when engine configuration files (e.g., `mkdocs.yml`, `zensical.toml`) change, without requiring an LSP server restart.
 - **BaseAdapter Contract Hardening:** Expose `watched_config_files` on the `BaseAdapter` interface to preserve Adapter Neutrality across third-party engines.
 
-### [v0.26] — Deterministic Quality Platform
+### [v0.26] — DQS Workspace UI
+
+*Bringing the global Documentation Quality Score into the authoring environment via an asynchronous, deterministic CLI execution bridge.*
+
+- **Asynchronous CLI Execution Bridge:** Restore DQS visualization in the VS Code Status Bar via `child_process.execFile` calling `zenzic score --json`, guaranteeing 100% mathematical parity with CI/CD without blocking LSP performance.
+
+### [v0.27] — Deterministic Quality Platform
 
 *Evolving from a strict validator to a comprehensive quality governance engine.*
 
@@ -49,7 +54,7 @@ Before advancing the core feature set, the following infrastructural and validat
 - **Semantic Readability Metrics:** Extend Zenzic beyond structural validation into content quality (e.g., deterministic Flesch-Kincaid scoring) while maintaining the static analysis paradigm.
 - **Configuration Validation Engine:** Reduce operational errors by establishing a single source of truth for configuration schemas across the CLI, VS Code, and documentation.
 
-### [v0.27] — Governance & Extensibility
+### [v0.28] — Governance & Extensibility
 
 *Opening the engine to enterprise policies and custom integrations.*
 
@@ -58,15 +63,15 @@ Before advancing the core feature set, the following infrastructural and validat
 - **SARIF Enterprise Integration:** Enhance security and compliance integrations for enterprise dashboards.
 - **Zenzic Audit Mode:** High-value enterprise reporting mode requiring stable DQS, Policy Engine, and SARIF outputs.
 
-### [v0.28] — Ecosystem Expansion
+### [v0.29] — Ecosystem Expansion
 
 *Expanding the perimeter to external frameworks.*
 
 - **Docusaurus Bridge Architecture:** The first concrete implementation of the adapter ecosystem, validating the artifact-based VSM model outside the Core.
 - **Sphinx & Hugo Adapters:** Extend open-source compatibility following the stabilization of the `BaseAdapter` contract.
 - **Multi-Repository Documentation Graph:** Advanced feature to analyze documentation spanning multiple repositories, requiring full maturity of the VSM and artifact composition.
 
-### [v0.29] — Operational Excellence
+### [v0.30] — Operational Excellence
 
 *Advanced observability and developer experience.*
 

diff --git a/docs/reference/cli.md b/docs/reference/cli.md
@@ -54,7 +54,13 @@ Select a command tab to view its execution flags, default behaviors, and usage e
     | `--fail-under` | — | `0` | Minimum required score. Fails quality gate (Exit 1) if score falls below threshold. |
     | `--stamp` | — | `false` | Updates README.md status badge with the newly computed DQS score. |
     | `--format` | `-f` | `text` | Output format: `text` or `json`. |
+    | `--json` | — | `false` | Shorthand for `--format json`. Suppresses all rich/text output and emits a single JSON object on `stdout`. Preferred for programmatic consumers (e.g., editor integrations, shell scripts). |
     | `--strict` | `-s` | `false` | Includes external HTTP link validation in score calculation. |
+    | `--breakdown` | — | `false` | Expands category breakdown showing individual Z-Codes and transparent penalty math. |
+    | `--save` | — | `false` | Saves score snapshot to `.zenzic-score.json` for use with `zenzic diff`. |
+    | `--check-stamp` | — | `false` | Verifies badge stamp files contain the current score URL. Exits 1 if any badge is stale. |
+    | `--no-header` | — | `false` | Suppresses the Zenzic banner (set automatically by `--ci`). |
+    | `--ci` | — | `false` | CI shorthand: sets `--no-header`. |
 
     **Usage Examples:**
     ```bash title="Terminal"
@@ -66,8 +72,46 @@ Select a command tab to view its execution flags, default behaviors, and usage e
 
     # Stamp status badge into README.md
     zenzic score --stamp
+
+    # Emit machine-readable JSON for programmatic consumers (editor integrations, scripts)
+    zenzic score --json
+
+    # Equivalent long form
+    zenzic score --format json
     ```
 
+    ??? info "JSON Output Schema (`--json`)"
+        When `--json` (or `--format json`) is passed, the command emits a single JSON
+        object on `stdout` with no rich/text output. Suitable for piping to `jq` or
+        parsing in editor extensions.
+
+        ```json
+        {
+          "project": "<project-name>",
+          "score": 98,
+          "threshold": 0,
+          "status": "success",
+          "timestamp": "2026-07-26T16:49:29+00:00",
+          "categories": [
+            { "name": "structural", "weight": 0.30, "issues": 0, "category_score": 1.0,
+              "contribution": 0.30, "raw_penalty": 0, "is_capped": false },
+            { "name": "navigation", "weight": 0.25, "issues": 0, "category_score": 1.0,
+              "contribution": 0.25, "raw_penalty": 0, "is_capped": false },
+            { "name": "content",    "weight": 0.20, "issues": 0, "category_score": 1.0,
+              "contribution": 0.20, "raw_penalty": 0, "is_capped": false },
+            { "name": "brand",      "weight": 0.25, "issues": 0, "category_score": 1.0,
+              "contribution": 0.25, "raw_penalty": 0, "is_capped": false }
+          ],
+          "suppression_count": 2,
+          "suppression_cap": 30,
+          "suppression_debt_pts": 2,
+          "debt_status": "MANAGED DEBT"
+        }
+        ```
+
+        Possible values of `status`: `success`, `failing` (score < `fail_under`),
+        `security_breach` (Z2xx finding detected).
+
 === "zenzic diff"
 
     Evaluate score delta and finding changes against a stored baseline file:

diff --git a/src/zenzic/cli/_standalone.py b/src/zenzic/cli/_standalone.py
@@ -233,8 +233,21 @@ def score(
         "--breakdown",
         help="Explode scoring categories showing individual occurred Z-Codes and transparent math.",
     ),
+    json_flag: bool = typer.Option(
+        False,
+        "--json",
+        help=(
+            "Shorthand for --format json. Suppresses all rich/text output and emits a single "
+            "JSON object on stdout. Intended for programmatic consumers (e.g., editor integrations)."
+        ),
+    ),
 ) -> None:
     """Compute a 0–100 documentation quality score across all checks."""
+    # ECOSYSTEM-FEAT-002: --json is a shorthand alias for --format json.
+    # Programmatic consumers (e.g., editor integrations) should prefer this flag
+    # over --format json for ergonomic clarity.
+    if json_flag:
+        output_format = "json"
     if ci:
         no_header = True