# Analisi implementativa: evoluzione mappa mentale e indice codebase per docs-node

**Repository:** `sophiadeveloper/mcp-servers`  
**Branch di riferimento:** `reworks_docs_node_part2`  
**Area:** `docs-node`  
**Tipo documento:** proposta implementativa / roadmap post online-sync  
**Data:** 2026-07-22  
**Autore:** analisi tecnica assistita  

---

## 1. Sintesi esecutiva

Questa proposta definisce una fase evolutiva da sviluppare **in coda** al lavoro attuale su `docs-node` online/sync. L'obiettivo non e' sostituire l'architettura corrente, ma estendere `docs-node` da sistema di indicizzazione documentale a **knowledge graph locale e sincronizzabile**, mantenendo i principi gia' introdotti nel branch `reworks_docs_node_part2`:

- SQLite come storage locale embedded;
- UUID, versioni, hash e soft delete per entita' sincronizzabili;
- manifest V3;
- changelog incrementale;
- replica locale/remota;
- conflitti persistiti e risolvibili;
- compatibilita' legacy dei tool MCP esistenti.

La proposta aggiunge due capacita' opzionali:

1. **Mappa mentale evoluta**: layer semantico con provenance, certezza delle relazioni, lint periodico, pathfinding e possibile export Obsidian-compatible.
2. **Indice codebase opzionale**: inventario e symbol extraction leggera della codebase collegata a uno scaffale documentale, per creare link verificabili tra documentazione e codice.

La raccomandazione principale e':

```text
Mantenere SQLite come database canonico.
Aggiungere un graph layer leggero e incrementale.
Introdurre codebase indexing solo come feature opt-in, read-only e hash-based.
Non migrare a MongoDB o a un database server-like.
Non indicizzare l'intero contenuto del codice di default.
```

---

## 2. Contesto e stato attuale rilevante

### 2.1 Stato corrente di docs-node

`docs-node` nasce come server MCP per indicizzare documentazione Markdown in SQLite locale, con ricerca full-text e relazioni semantiche tra documenti e scaffali. Il branch `reworks_docs_node_part2` ha gia' introdotto una traiettoria piu' ampia:

- modalita' `remote-server`;
- endpoint HTTP `/sync/*` e `/mcp`;
- manifest export V3;
- replica locale di scaffali remoti;
- tool `docs_remote`;
- changelog incrementale;
- push/pull manuale;
- conflitti persistiti;
- token read/write separati;
- soft delete/tombstone;
- sync status piu' leggibile.

Questa base rende possibile aggiungere una mappa mentale piu' strutturata senza cambiare il paradigma operativo.

### 2.2 Principio guida

La nuova fase deve restare coerente con le regole interne del repository:

- modifiche incrementali;
- compatibilita' legacy;
- migrazioni non distruttive;
- test/smoke per ogni modifica di storage o schema MCP;
- nessun refactor monolitico fuori scope;
- separazione chiara tra dati utente non rigenerabili e cache/indici rigenerabili.

---

## 3. Obiettivi

### 3.1 Obiettivi funzionali

1. Migliorare la mappa mentale con relazioni piu' affidabili, spiegabili e verificabili.
2. Distinguere relazioni estratte deterministicamente, inferite, ambigue, manuali e curate.
3. Introdurre provenance ed evidenza puntuale per ogni relazione rilevante.
4. Consentire query agentiche sulla mappa, inclusi pathfinding e neighborhood graph.
5. Aggiungere lint periodico per rilevare link morti, duplicati, relazioni stale e feedback loop.
6. Consentire l'indicizzazione opzionale di codebase collegate agli scaffali documentali.
7. Collegare documenti a file, simboli, test, endpoint e configurazioni implementative.
8. Segnalare documentazione potenzialmente stale quando cambia il codice collegato.
9. Preparare un export opzionale Obsidian-compatible come vista, non come storage primario.

### 3.2 Non obiettivi

Non rientrano in questa fase:

- sostituire SQLite con MongoDB o altro database server;
- rendere Obsidian lo storage canonico;
- indicizzare tutto il contenuto della codebase come default;
- introdurre Tree-sitter come dipendenza obbligatoria core;
- introdurre chiamate LLM automatiche non esplicitamente abilitate;
- sincronizzare remotamente l'intero indice codice senza policy esplicita;
- trasformare `docs-node` in un code search engine generalista.

---

## 4. Decisione architetturale: mantenere SQLite

### 4.1 Motivazione

SQLite resta la scelta piu' corretta per `docs-node` perche':

- e' embedded e non richiede server;
- e' gia' usato dal branch attuale;
- supporta bene indici, transazioni, WAL, FTS e JSON metadata;
- semplifica installazione e supporto Windows;
- riduce l'overhead operativo per utenti MCP locali;
- si integra con il modello gia' esistente di migrazioni, changelog e sync;
- consente adjacency table efficienti per grafi di dimensioni medio-piccole.

### 4.2 Perche' non MongoDB

MongoDB non e' consigliato in questa fase:

- richiede un processo server (`mongod`) anche se locale;
- aumenta setup, diagnosi e supporto;
- non risolve il problema centrale, che e' governance del grafo, non storage documentale annidato;
- complica la portabilita' del server MCP;
- introduce un modello operativo diverso dal file SQLite locale gia' supportato;
- rende piu' difficile mantenere una modalita' locale semplice, offline e senza prerequisiti.

### 4.3 Modello consigliato

```text
SQLite canonico
  - shelves
  - documents
  - tags
  - document_links
  - shelf_links
  - remote_sources
  - shelf_sync_state
  - change_log
  - sync_conflicts
  - graph/concept/code tables nuove

Markdown/Obsidian export opzionale
  - vista derivata
  - rigenerabile
  - non fonte primaria
```

---

## 5. Architettura target a livelli

L'evoluzione proposta usa un modello a tre livelli.

### 5.1 Source Layer

Contiene sorgenti grezze e verificabili:

- Markdown documentali;
- codice sorgente;
- test;
- file di configurazione;
- transcript;
- asset importati;
- eventuali PDF o media convertiti.

Policy:

```text
Source Layer = read-only per l'agente, salvo azioni esplicite fuori da docs-node.
```

Nel caso della codebase, `docs-node` deve indicizzare metadati e simboli, non diventare editor del codice.

### 5.2 Knowledge/Wiki Layer

Contiene rappresentazioni navigabili e arricchite:

- documenti indicizzati;
- concept node;
- link doc-doc;
- link doc-code;
- link doc-concept;
- link concept-concept;
- evidenze e provenance.

Policy:

```text
Knowledge Layer = modificabile tramite tool MCP controllati.
```

Le relazioni automatiche devono restare `heuristic` o `inferred` fino a promozione manuale/curata.

### 5.3 Schema Layer

Contiene regole e vincoli:

- tassonomia relazioni;
- regole di certezza;
- lint rules;
- schema export Obsidian;
- policy di code indexing;
- allowlist/exclude default.

Policy:

```text
Schema Layer = read-only durante l'uso ordinario.
```

File candidati:

```text
docs-node/schema/mindmap-relations.json
docs-node/schema/mindmap-lint-rules.json
docs-node/schema/code-indexing-policy.json
docs-node/schema/obsidian-export-template.md
```

---

## 6. Evoluzione della mappa mentale

### 6.1 Problema attuale

Il modello attuale di mappa mentale e' utile ma prevalentemente documentale:

```text
shelf -> document
document -> document
document -> tag
shelf -> shelf
```

Questa struttura non distingue abbastanza bene:

- link certi da link ipotizzati;
- link manuali da link euristici;
- link basati su evidenza puntuale da link basati su similarita' debole;
- link aggiornati da link stale;
- concetti astratti da documenti fisici.

### 6.2 Nuovo principio: edge spiegabili

Ogni relazione significativa deve poter rispondere a quattro domande:

1. **Chi ha creato il link?** parser, euristica, agente, utente, import.
2. **Quanto e' affidabile?** extracted, inferred, ambiguous, manual, curated.
3. **Su quale evidenza si basa?** excerpt, path, line range, timestamp, hash sorgente.
4. **E' ancora valida?** confronto hash/versione/stato tombstone.

### 6.3 Certezza delle relazioni

Valori raccomandati:

```text
extracted  = relazione deterministica estratta da sorgente verificabile
inferred   = relazione dedotta da euristica o LLM
ambiguous  = relazione candidata ma incerta
manual     = relazione inserita manualmente dall'utente/agente
curated    = relazione revisionata e promossa come affidabile
```

Nota: `manual` e `curated` non sono sinonimi. Un link manuale puo' essere operativo ma non ancora revisionato formalmente.

### 6.4 Provenance minima per edge

Ogni edge generato automaticamente dovrebbe includere metadata simili:

```json
{
  "certainty": "extracted",
  "origin": "markdown_wikilink_parser",
  "extractor_version": "mindmap-v1",
  "source": {
    "type": "document",
    "uuid": "...",
    "path": "docs/example.md",
    "content_sha256": "..."
  },
  "evidence": [
    {
      "kind": "line_range",
      "path": "docs/example.md",
      "start_line": 12,
      "end_line": 18,
      "excerpt": "..."
    }
  ]
}
```

Per transcript/video:

```json
{
  "kind": "timestamp_range",
  "start": "00:02:10",
  "end": "00:03:04",
  "excerpt": "..."
}
```

---

## 7. Concept graph

### 7.1 Razionale

Il grafo documento-documento non basta per rappresentare conoscenza trasversale. Servono nodi concettuali che normalizzino termini e temi ricorrenti:

```text
document -> concept -> document
code_symbol -> concept -> document
transcript_segment -> concept -> document
```

Esempio:

```text
Documento: replica locale docs-node
  -> Concept: optimistic concurrency
  -> Concept: sync conflict
  -> Concept: manifest v3

Codice: pushShelfChanges()
  -> Concept: optimistic concurrency
  -> Concept: sync conflict
```

### 7.2 Tabelle proposte

```sql
CREATE TABLE concept_nodes (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  uuid TEXT NOT NULL UNIQUE,
  label TEXT NOT NULL,
  normalized_label TEXT NOT NULL,
  description TEXT,
  origin TEXT NOT NULL DEFAULT 'heuristic',
  certainty TEXT NOT NULL DEFAULT 'inferred',
  confidence REAL,
  metadata_json TEXT,
  version INTEGER NOT NULL DEFAULT 1,
  metadata_sha256 TEXT,
  created_at TEXT NOT NULL DEFAULT (datetime('now')),
  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
  deleted_at TEXT,
  UNIQUE(normalized_label)
);
```

```sql
CREATE TABLE concept_links (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  uuid TEXT NOT NULL UNIQUE,
  source_type TEXT NOT NULL,
  source_uuid TEXT NOT NULL,
  target_type TEXT NOT NULL,
  target_uuid TEXT NOT NULL,
  relation TEXT NOT NULL,
  certainty TEXT NOT NULL DEFAULT 'inferred',
  confidence REAL,
  evidence_json TEXT,
  origin TEXT NOT NULL DEFAULT 'heuristic',
  version INTEGER NOT NULL DEFAULT 1,
  metadata_sha256 TEXT,
  created_at TEXT NOT NULL DEFAULT (datetime('now')),
  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
  deleted_at TEXT,
  UNIQUE(source_type, source_uuid, target_type, target_uuid, relation, origin)
);
```

### 7.3 Relazioni raccomandate

```text
mentions
explains
implements
depends_on
contradicts
supersedes
example_of
source_of_truth_for
derived_from
has_risk
has_decision
has_open_question
related_to
```

### 7.4 Strategia di introduzione

Non introdurre subito il concept graph come dipendenza di tutti i flussi. Procedere cosi':

1. estrarre concetti in dry-run;
2. scrivere concetti solo con `apply=true`;
3. usare i concetti per arricchire `correlate`, non per sostituirlo;
4. aggiungere lint per duplicati concettuali;
5. introdurre pathfinding solo dopo stabilizzazione dei dati.

---

## 8. Lint della mappa mentale

### 8.1 Razionale

Un grafo knowledge tende a degradare se non viene manutentato. I rischi principali sono:

- link verso entita' cancellate;
- relazioni stale dopo modifica sorgenti;
- duplicati concettuali;
- link ambigui mai revisionati;
- note generate da agente usate come fonte primaria;
- contraddizioni non rilevate;
- crescita eccessiva di nodi a basso valore.

### 8.2 Tool MCP proposto

```json
{
  "name": "docs_mindmap",
  "arguments": {
    "action": "lint_mindmap",
    "shelf": "MCP Servers Docs",
    "checks": [
      "dead_links",
      "stale_source_hash",
      "duplicate_concepts",
      "ambiguous_edges",
      "orphan_nodes",
      "self_generated_feedback",
      "conflicting_claims"
    ],
    "apply": false
  }
}
```

### 8.3 Check minimi

| Check | Descrizione | Auto-fix sicuro |
| --- | --- | --- |
| `dead_links` | Target inesistente o tombstoned | si, solo link heuristic/inferred |
| `stale_source_hash` | Evidenza basata su hash vecchio | no, report |
| `duplicate_concepts` | Concetti normalizzati simili | no, proposta merge |
| `ambiguous_edges` | Link ambigui non revisionati | si, prune sopra soglia eta' opzionale |
| `orphan_nodes` | Concetti senza link utili | si, se heuristic e vecchi |
| `self_generated_feedback` | Note generate citate come fonte primaria | no, report |
| `conflicting_claims` | Relazioni incompatibili | no, report |

### 8.4 Output atteso

```json
{
  "ok": true,
  "shelf": "MCP Servers Docs",
  "summary": {
    "issues": 18,
    "auto_fixable": 7,
    "requires_review": 11
  },
  "issues": [
    {
      "type": "stale_source_hash",
      "severity": "warning",
      "entity_type": "concept_link",
      "entity_uuid": "...",
      "message": "La sorgente collegata e' cambiata dopo la creazione del link.",
      "recommended_action": "recompute_or_review"
    }
  ]
}
```

---

## 9. Pathfinding e neighborhood graph

### 9.1 Obiettivo

Consentire all'agente di navigare il grafo senza caricare scaffali interi. Il caso d'uso e':

```text
Trova il percorso piu' breve e affidabile tra un documento di requisito e il codice che lo implementa.
```

### 9.2 Tool MCP proposto

```json
{
  "name": "docs_mindmap",
  "arguments": {
    "action": "map_path",
    "from": "docs://document/<uuid>",
    "to": "code://symbol/<uuid>",
    "max_depth": 4,
    "prefer_certainty": ["curated", "manual", "extracted"],
    "include_evidence": true
  }
}
```

Output:

```json
{
  "path": [
    {
      "type": "document",
      "uuid": "...",
      "label": "Replica locale docs-node"
    },
    {
      "type": "concept",
      "uuid": "...",
      "label": "optimistic concurrency"
    },
    {
      "type": "code_symbol",
      "uuid": "...",
      "label": "pushShelfChanges"
    }
  ],
  "score": 0.91,
  "evidence": []
}
```

### 9.3 Neighborhood graph

Tool complementare:

```json
{
  "action": "map_neighborhood",
  "uri": "docs://document/<uuid>",
  "depth": 2,
  "include_code": true,
  "include_concepts": true,
  "min_confidence": 0.65,
  "format": "json"
}
```

Formati possibili:

- `json` per agenti;
- `mermaid` per report Markdown;
- `obsidian` per export wiki.

---

## 10. Export Obsidian-compatible

### 10.1 Decisione

Obsidian non deve diventare lo storage primario. Puo' pero' essere un eccellente layer di visualizzazione.

```text
SQLite docs-node = fonte canonica
Obsidian vault = export derivato e rigenerabile
```

### 10.2 Tool proposto

```json
{
  "name": "docs_mindmap",
  "arguments": {
    "action": "export_mindmap_wiki",
    "shelf": "MCP Servers Docs",
    "save_path": "E:/exports/docs-node-vault",
    "format": "obsidian",
    "include_concepts": true,
    "include_code_links": true,
    "include_evidence": true
  }
}
```

### 10.3 File generati

```text
vault/
  documents/
    replica-locale-docs-node.md
  concepts/
    optimistic-concurrency.md
    sync-conflict.md
  code/
    docs-node-src-remote-client-js.md
  index.md
```

Esempio nota concept:

```md
---
uuid: "..."
type: concept
normalized_label: optimistic_concurrency
origin: curated
---

# Optimistic concurrency

## Documenti collegati

- [[Replica locale docs-node]]
- [[Conflitti sync]]

## Simboli codice collegati

- [[pushShelfChanges]]

## Evidenze

- `docs-node/src/http/read-only-server.js`
- `docs-node/src/remote/client.js`
```

---

## 11. Indice codebase opzionale

### 11.1 Razionale

L'indice codebase non deve competere con IDE o GitHub search. Deve servire a collegare documentazione e implementazione reale.

Casi d'uso primari:

- documento -> file/simbolo che implementa la feature;
- codice cambiato -> documenti potenzialmente stale;
- requisito -> test associati;
- endpoint/tool MCP -> documentazione corrispondente;
- pathfinding agente tra concetto, documento e codice;
- lint: documentazione senza codice o codice senza documentazione.

### 11.2 Principio di sicurezza operativa

```text
La codebase indicizzata da docs-node e' read-only.
```

`docs-node` non deve modificare file sorgenti. Deve limitarsi a leggere metadata, hash e simboli.

### 11.3 Modalita' progressive

#### Modalita' 1: `metadata_only`

Default raccomandato.

Indicizza:

- path relativo;
- estensione;
- language guess;
- size;
- SHA-256;
- data ultimo scan;
- stato deleted/tombstoned.

Non salva contenuto codice.

#### Modalita' 2: `symbols_light`

Estrae simboli leggeri con parser regex/tokenizer per linguaggi supportati inizialmente:

- JavaScript/TypeScript/MJS/CJS;
- Markdown frontmatter/code fence references;
- JSON package/config rilevanti;
- eventuali PowerShell script in modo basilare.

Estrae:

- import/export;
- function/class;
- costanti uppercase;
- action MCP string literal;
- endpoint HTTP string literal;
- nomi test/smoke;
- package script.

#### Modalita' 3: `ast_optional`

Futura e opzionale. Integra Tree-sitter o adapter equivalente.

Non deve essere dependency core nella prima implementazione.

### 11.4 Tool MCP proposto: attach codebase

```json
{
  "name": "docs_codebase",
  "arguments": {
    "action": "attach_codebase",
    "shelf": "MCP Servers Docs",
    "project_path": "E:/mcp-servers",
    "include": [
      "docs-node/**/*.js",
      "docs-node/**/*.mjs",
      "tests/smoke/docs-node*.mjs",
      "docs-node/package.json"
    ],
    "exclude": [
      "**/node_modules/**",
      "**/.git/**",
      "**/dist/**",
      "**/build/**",
      "**/*.db",
      "**/*.zip"
    ],
    "scan_mode": "metadata_only"
  }
}
```

### 11.5 Tool MCP proposto: scan codebase

```json
{
  "name": "docs_codebase",
  "arguments": {
    "action": "scan_codebase",
    "shelf": "MCP Servers Docs",
    "code_source": "mcp-servers-docs-node",
    "incremental": true,
    "dry_run": false
  }
}
```

### 11.6 Tool MCP proposto: link document to code

Manuale o semi-automatico:

```json
{
  "name": "docs_codebase",
  "arguments": {
    "action": "link_document_code",
    "document_uri": "docs://document/<uuid>",
    "code_uri": "code://file/<uuid>",
    "relation": "implemented_by",
    "certainty": "manual",
    "rationale": "Il documento descrive la replica remota implementata in questo file."
  }
}
```

### 11.7 Tool MCP proposto: propose doc-code links

```json
{
  "name": "docs_codebase",
  "arguments": {
    "action": "propose_doc_code_links",
    "shelf": "MCP Servers Docs",
    "min_confidence": 0.7,
    "apply": false
  }
}
```

Segnali iniziali:

- path citato nel documento;
- nome funzione citato nel documento;
- endpoint citato sia nel codice sia nella documentazione;
- action MCP citata sia nel codice sia nella documentazione;
- test file con nome correlato;
- package/script citato.

### 11.8 Tool MCP proposto: stale docs

```json
{
  "name": "docs_codebase",
  "arguments": {
    "action": "detect_stale_docs",
    "shelf": "MCP Servers Docs",
    "include_code_changes": true,
    "include_unlinked_docs": true
  }
}
```

Regola chiave:

```text
Se document D e' collegato a code file F o symbol S,
e hash(F/S) cambia dopo la creazione/validazione del link,
allora D e' candidato stale.
```

---

## 12. Schema dati codebase

### 12.1 `code_sources`

```sql
CREATE TABLE code_sources (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  uuid TEXT NOT NULL UNIQUE,
  shelf_id INTEGER NOT NULL REFERENCES shelves(id) ON DELETE CASCADE,
  name TEXT NOT NULL,
  project_path TEXT NOT NULL,
  include_globs_json TEXT NOT NULL,
  exclude_globs_json TEXT NOT NULL,
  scan_mode TEXT NOT NULL DEFAULT 'metadata_only',
  visibility TEXT NOT NULL DEFAULT 'local_only',
  created_at TEXT NOT NULL DEFAULT (datetime('now')),
  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
  deleted_at TEXT,
  UNIQUE(shelf_id, name)
);
```

### 12.2 `code_files`

```sql
CREATE TABLE code_files (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  uuid TEXT NOT NULL UNIQUE,
  code_source_id INTEGER NOT NULL REFERENCES code_sources(id) ON DELETE CASCADE,
  relative_path TEXT NOT NULL,
  language TEXT,
  size_bytes INTEGER,
  content_sha256 TEXT,
  metadata_sha256 TEXT,
  indexed_at TEXT,
  deleted_at TEXT,
  UNIQUE(code_source_id, relative_path)
);
```

### 12.3 `code_symbols`

```sql
CREATE TABLE code_symbols (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  uuid TEXT NOT NULL UNIQUE,
  code_file_id INTEGER NOT NULL REFERENCES code_files(id) ON DELETE CASCADE,
  symbol_type TEXT NOT NULL,
  name TEXT NOT NULL,
  qualified_name TEXT,
  start_line INTEGER,
  end_line INTEGER,
  signature TEXT,
  metadata_json TEXT,
  content_sha256 TEXT,
  metadata_sha256 TEXT,
  indexed_at TEXT,
  deleted_at TEXT,
  UNIQUE(code_file_id, symbol_type, qualified_name, start_line)
);
```

### 12.4 `graph_links`

Valutare se mantenere `document_links` e aggiungere solo code-specific links, oppure introdurre una tabella generalizzata.

Opzione consigliata per evoluzione pulita:

```sql
CREATE TABLE graph_links (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  uuid TEXT NOT NULL UNIQUE,
  shelf_id INTEGER REFERENCES shelves(id) ON DELETE CASCADE,
  source_type TEXT NOT NULL,
  source_uuid TEXT NOT NULL,
  target_type TEXT NOT NULL,
  target_uuid TEXT NOT NULL,
  relation TEXT NOT NULL,
  certainty TEXT NOT NULL DEFAULT 'inferred',
  confidence REAL,
  origin TEXT NOT NULL DEFAULT 'heuristic',
  evidence_json TEXT,
  metadata_json TEXT,
  version INTEGER NOT NULL DEFAULT 1,
  metadata_sha256 TEXT,
  created_at TEXT NOT NULL DEFAULT (datetime('now')),
  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
  deleted_at TEXT,
  UNIQUE(source_type, source_uuid, target_type, target_uuid, relation, origin)
);
```

Tipi ammessi iniziali:

```text
document
shelf
tag
concept
code_file
code_symbol
transcript_segment
```

Relazioni codebase:

```text
implemented_by
implements
tested_by
configures
defines
imports
exports
calls
mentions
stale_against
```

---

## 13. Sync e replica per il code index

### 13.1 Decisione iniziale

L'indice codebase deve essere **local-only** per default.

Motivi:

- path locali possono differire tra macchine;
- branch e commit possono differire;
- codice puo' essere piu' sensibile della documentazione;
- volume e churn sono maggiori;
- conflitti su metadata codice hanno poco valore operativo;
- sync remota del codice puo' generare rumore.

### 13.2 Cosa sincronizzare

Sincronizzare solo se esplicitamente richiesto:

| Entita' | Default | Sync opzionale |
| --- | --- | --- |
| `code_sources` | local-only | metadata redatti |
| `code_files` | local-only | path relativo + hash + repo/commit |
| `code_symbols` | local-only | simboli pubblici, senza body |
| `graph_links doc-code` | local-only | curated/manual only |
| `concept_links` | sync | si, se non contengono segreti |

### 13.3 Provenance codebase per link sincronizzabili

```json
{
  "repo": "sophiadeveloper/mcp-servers",
  "branch": "reworks_docs_node_part2",
  "commit": "<sha>",
  "relative_path": "docs-node/src/remote/client.js",
  "symbol": "fetchRemoteJson",
  "content_sha256": "...",
  "indexed_at": "..."
}
```

### 13.4 Regola anti-leak

I contenuti codice non devono essere inclusi in manifest remoti o export senza opt-in esplicito.

```text
Default export/sync codebase = metadata only.
```

---

## 14. Integrazione con changelog e conflitti

### 14.1 Entity types aggiuntivi

Aggiungere gradualmente al changelog:

```text
concept_node
concept_link
graph_link
code_source
code_file
code_symbol
```

Ma solo dopo avere chiarito la policy di sync per ciascuna entita'.

### 14.2 Operazioni

Rimanere compatibili con l'approccio esistente `upsert/delete`:

```text
upsert concept_node
upsert concept_link
upsert graph_link
upsert code_source
upsert code_file
upsert code_symbol
delete/tombstone ...
```

### 14.3 Conflitti

Per entita' rigenerabili, evitare conflitti manuali quando possibile.

| Entita' | Tipo dato | Strategia conflitto |
| --- | --- | --- |
| `concept_node` curated | dati utente | conflitto esplicito |
| `concept_node` heuristic | rigenerabile | remote/local prefer policy |
| `graph_link` curated/manual | dati utente | conflitto esplicito |
| `graph_link` heuristic | rigenerabile | prune/recompute |
| `code_file` | rigenerabile | recompute locale |
| `code_symbol` | rigenerabile | recompute locale |

---

## 15. Guardrail anti-overhead

### 15.1 Feature flag

Le nuove capacita' devono essere disabilitate di default:

```text
DOCS_NODE_MINDMAP_ADVANCED=0
DOCS_NODE_CODE_INDEX=0
DOCS_NODE_CODE_INDEX_AST=0
DOCS_NODE_OBSIDIAN_EXPORT=0
```

In alternativa, nessun env globale e attivazione solo tramite tool/config DB.

### 15.2 Limiti di scansione codebase

Default raccomandati:

```json
{
  "max_file_size_bytes": 524288,
  "max_files_per_scan": 5000,
  "max_symbols_per_file": 500,
  "exclude": [
    "**/node_modules/**",
    "**/.git/**",
    "**/dist/**",
    "**/build/**",
    "**/coverage/**",
    "**/*.db",
    "**/*.sqlite",
    "**/*.zip",
    "**/*.png",
    "**/*.jpg",
    "**/*.pdf"
  ]
}
```

### 15.3 No LLM by default

Tutte le pipeline iniziali devono essere deterministiche:

- parsing Markdown;
- path/link extraction;
- regex/token extraction;
- hash comparison;
- graph traversal;
- lint.

Qualsiasi LLM-based inference deve essere:

- opt-in;
- marcata `inferred` o `ambiguous`;
- accompagnata da evidence;
- non promossa automaticamente a `curated`.

---

## 16. Tool MCP proposti

### 16.1 Nuovo tool: `docs_mindmap`

Azioni:

```text
extract_concepts
list_concepts
merge_concepts
manage_concept_links
propose_mindmap_links
lint_mindmap
map_path
map_neighborhood
export_mindmap_wiki
promote_link
prune_heuristic_links
```

Motivazione: non sovraccaricare ulteriormente `docs_management`.

### 16.2 Nuovo tool: `docs_codebase`

Azioni:

```text
attach_codebase
list_codebases
scan_codebase
list_code_files
read_code_file_metadata
list_code_symbols
link_document_code
propose_doc_code_links
detect_stale_docs
unlink_codebase
```

### 16.3 Compatibilita' con tool esistenti

- `docs_navigation search` resta invariato.
- `docs_navigation read_document` puo' aggiungere metadata/warning opzionali su code links/stale docs.
- `docs_management correlate` puo' restare com'e' e delegare la parte avanzata a `docs_mindmap`.
- `docs_remote` non deve gestire codebase indexing nella prima fase, salvo report local-only in `sync_status`.

---

## 17. Roadmap implementativa

Questa roadmap va considerata **successiva** alla stabilizzazione del lavoro online/sync corrente.

### Milestone 6 - Provenance e certainty sugli edge

**Obiettivo:** rendere i link esistenti spiegabili e classificabili.

Scope:

- estendere `document_links.metadata_json` con `certainty`, `evidence`, `extractor`, `source_hash`;
- aggiornare `correlate` per distinguere `heuristic/inferred/ambiguous`;
- aggiungere utility per evidence compact;
- aggiungere output backward-compatible.

DB:

- nessuna nuova tabella obbligatoria;
- eventuale migrazione non distruttiva per normalizzare metadata.

Tool:

- `docs_mindmap promote_link`;
- `docs_mindmap prune_heuristic_links` o riuso controllato di action esistente.

Test:

- smoke `docs-node-mindmap-certainty.smoke.mjs`;
- test metadata legacy senza `certainty`;
- test output con `apply=false`.

Done:

- link legacy ancora leggibili;
- nessun cambio breaking nei payload esistenti;
- evidence presente per nuovi link automatici.

---

### Milestone 7 - Lint mappa mentale

**Obiettivo:** introdurre manutenzione automatica del grafo.

Scope:

- nuovo tool `docs_mindmap`;
- action `lint_mindmap`;
- check iniziali: `dead_links`, `stale_source_hash`, `ambiguous_edges`, `orphan_nodes`;
- dry-run default;
- auto-fix solo per casi sicuri.

DB:

- possibile tabella opzionale `mindmap_lint_runs` per audit;
- altrimenti output stateless.

Test:

- fixture con link morto;
- fixture con hash stale;
- fixture con link ambiguous;
- test `apply=false` non modifica DB;
- test `apply=true` agisce solo su link sicuri.

Done:

- report leggibile da agente;
- nessun pruning distruttivo di link manual/curated;
- documentazione README aggiornata.

---

### Milestone 8 - Concept graph minimale

**Obiettivo:** aggiungere nodi concettuali senza sostituire il grafo documentale.

Scope:

- tabelle `concept_nodes`, `concept_links`;
- action `extract_concepts` in dry-run;
- action `list_concepts`;
- action `manage_concept_links`;
- deduplica base via `normalized_label`.

DB:

- migrazione non distruttiva;
- UUID/version/hash/deleted_at coerenti con il branch corrente;
- entity type predisposti per changelog, ma sync opzionale.

Test:

- migrazione DB vuoto;
- migrazione DB legacy;
- estrazione concetti da heading/tag;
- merge duplicati non distruttivo.

Done:

- concetti navigabili;
- nessuna dipendenza LLM;
- apply esplicito per scritture.

---

### Milestone 9 - Pathfinding e neighborhood graph

**Obiettivo:** usare il grafo per ridurre context pressure.

Scope:

- action `map_path`;
- action `map_neighborhood`;
- ranking per `certainty`, `confidence`, distanza;
- output JSON;
- output Mermaid opzionale.

DB:

- nessuna migrazione se si usa `concept_links` e `document_links`;
- valutare vista virtuale/adattatore in codice per trattare edge eterogenei.

Test:

- percorso diretto;
- percorso tramite concept;
- filtro su certainty;
- max_depth rispettato;
- nessun loop infinito.

Done:

- agente puo' chiedere percorso tra documento e concetto/documento;
- output compatto;
- evidenze opzionali.

---

### Milestone 10 - Codebase inventory metadata-only

**Obiettivo:** collegare scaffali documentali a codebase locali senza overhead alto.

Scope:

- nuovo tool `docs_codebase`;
- tabelle `code_sources`, `code_files`;
- action `attach_codebase`;
- action `scan_codebase` metadata-only;
- action `list_code_files`;
- hash incrementale;
- exclude default robusti.

DB:

- nuove tabelle con UUID/version/hash/deleted_at;
- `visibility = local_only` default.

Test:

- scan piccola fixture;
- exclude `node_modules`;
- incremental scan invariato;
- file modificato aggiorna hash;
- file rimosso diventa tombstone.

Done:

- nessun contenuto codice salvato;
- scan veloce;
- no dipendenze native;
- codebase disabilitata se non attaccata a shelf.

---

### Milestone 11 - Link doc-code manuali e proposti

**Obiettivo:** creare traceability doc -> code.

Scope:

- tabella `graph_links` oppure tabella dedicata `document_code_links`;
- action `link_document_code`;
- action `propose_doc_code_links`;
- segnali deterministici: path, symbol name, endpoint, action MCP, test name;
- `apply=false` default per proposte.

Decisione schema:

- se si vuole convergere verso grafo generico: `graph_links`;
- se si vuole minimizzare impatto: `document_code_links` iniziale, migrabile in futuro.

Raccomandazione: `graph_links`, per evitare proliferazione di tabelle link specifiche.

Test:

- link manuale doc-file;
- proposta link da path citato;
- proposta link da endpoint citato;
- link non creato sotto soglia confidenza;
- lint non cancella manual/curated.

Done:

- un documento puo' mostrare file/simboli correlati;
- link hanno provenance;
- nessuna sync remota automatica.

---

### Milestone 12 - Symbol extraction leggera

**Obiettivo:** rendere i link piu' precisi senza Tree-sitter obbligatorio.

Scope:

- tabella `code_symbols`;
- parser leggero JS/TS/MJS/CJS;
- estrazione import/export/function/class/constants;
- estrazione string literal per endpoint/action MCP in modo prudente;
- action `list_code_symbols`.

Test:

- function/class export;
- import path;
- endpoint string;
- action MCP string;
- file grande skippato;
- nessun crash su syntax non gestita.

Done:

- symbol extraction deterministica;
- no LLM;
- no dipendenze native;
- hash-based incremental.

---

### Milestone 13 - Stale documentation detection

**Obiettivo:** segnalare documenti che potrebbero non riflettere piu' il codice.

Scope:

- action `detect_stale_docs`;
- confronto hash link evidence vs hash corrente;
- severity score;
- integrazione warning opzionale in `docs_navigation read_document`;
- report Markdown/JSON.

Heuristics:

```text
high    = codice collegato curated/manual cambiato e doc invariato
medium  = codice collegato inferred cambiato
low     = file code senza doc link in area documentata
```

Test:

- file code cambia -> doc stale;
- doc aggiornata dopo codice -> non stale;
- link heuristic basso -> warning low;
- stale non blocca lettura documento.

Done:

- report utile in review;
- nessun falso blocco operativo;
- supporto dry-run.

---

### Milestone 14 - Export Obsidian-compatible

**Obiettivo:** fornire visualizzazione esterna senza cambiare storage.

Scope:

- action `export_mindmap_wiki`;
- export documenti/concept/code metadata;
- wikilinks;
- frontmatter UUID/hash;
- `save_path` assoluto obbligatorio;
- output rigenerabile.

Test:

- export crea vault;
- wikilinks validi;
- frontmatter include UUID;
- export non include contenuto codice salvo opt-in;
- path traversal prevented.

Done:

- vault navigabile in Obsidian;
- export dichiarato derivato;
- nessuna dipendenza runtime da Obsidian.

---

### Milestone 15 - AST adapter opzionale

**Obiettivo:** valutare Tree-sitter o adapter equivalente solo dopo proof of value.

**Stato decisionale:** `OUT OF SCOPE / DEFERRED`. M15 non e' autorizzata per
implementazione e resta fuori scope fino a una nuova decisione esplicita. La
presenza di grammatiche disponibili non costituisce da sola un go: prima serve
un proof of value ripetibile che dimostri un miglioramento materiale rispetto a
`symbols_light`. Nessuna dipendenza AST, feature flag, migration, asset WASM o
nuova superficie MCP deve essere aggiunta come effetto implicito delle
milestone M6-M14.

Scope:

- design adapter interface;
- feature flag;
- dipendenza opzionale;
- fallback a symbols_light;
- test piattaforme supportate;
- documentazione setup/restart.

Criteri per procedere:

- symbols_light non basta;
- benefici misurabili su link precision;
- overhead installazione accettabile;
- Windows support verificato;
- smoke test stabili.

Decision gate obbligatorio:

1. corpus rappresentativo con expected symbols revisionati per linguaggio;
2. confronto ripetibile `symbols_light` vs adapter candidato su precisione,
   recall, errori di parse, tempo, memoria e dimensione degli asset;
3. verifica Node 24 e Windows senza peggiorare l'installazione base;
4. scelta esplicita tra binding nativo e parser WASM/precompilato;
5. approvazione separata di dipendenze, setup e matrice piattaforme.

Done:

- nessun impatto su installazione base;
- AST disponibile solo opt-in;
- fallimento AST non rompe docs-node.

---

### Milestone 16 - Adapter simboli multi-linguaggio (proposta condizionata)

**Stato decisionale:** `PROPOSED / NOT APPROVED`. La milestone e' tecnicamente
fattibile, ma dipende dal go/no-go di M15 e non autorizza implementazione. Il
supporto resta integralmente `local_only`: non entra in Manifest V3, snapshot,
replica, read-through, delta, push, change-log o `sync_conflicts`.

**Obiettivo:** estendere l'estrazione metadata-only a ColdFusion/CFML, PHP e
C# per .NET 10, senza trasformare `docs-node` in un motore di code search e
senza persistere body o snippet.

#### Architettura proposta

- Introdurre un contratto interno `SymbolExtractorAdapter` con selezione per
  estensione/linguaggio, versione dell'adapter, capability dichiarate e report
  di parse strutturato.
- Conservare `symbols_light` come adapter built-in e fallback obbligatorio per
  JS/TS/MJS/CJS.
- Riutilizzare `docs_codebase.extract_code_symbols`; nessun nuovo tool MCP e
  nessuna estrazione implicita durante `scan_codebase`.
- Aggiungere solo parametri opzionali compatibili con client severi, ad esempio
  `parser_mode: light | auto | ast`, con default legacy `light` finche' non
  viene approvata una diversa decisione.
- Normalizzare i risultati nei tipi trasversali gia' esposti (`import`,
  `export`, `function`, `class`, `constant`, `mcp_action`, `http_endpoint`) e
  conservare in metadata `language`, `native_kind`, `adapter`,
  `adapter_version`, `parser_mode` ed errori non bloccanti. Nuovi tipi pubblici
  richiederebbero una migration separata e non sono impliciti in M16.
- Preferire parser WASM/precompilati caricati dinamicamente per evitare
  toolchain native nell'installazione base. Gli asset opzionali devono essere
  installati dal setup esplicito, mai scaricati all'avvio ordinario.
- Se adapter o asset non sono disponibili, restituire warning/skipped per file
  e usare il fallback consentito; il fallimento non deve interrompere
  `docs-node` ne' modificare simboli validi prodotti in precedenza.

#### ColdFusion / CFML

Estensioni iniziali: `.cfm`, `.cfc`, `.cfs`. La grammatica candidata espone
tre dialect: `cfml` per componenti/template misti tag + CFScript, `cfscript`
per file script puri e `cfquery` per SQL embedded. Questo rende fattibile la
copertura richiesta di cfscript, cftag, CFC e CFM.

Estrarre almeno:

- componenti/interfacce e loro nome/extends/implements;
- funzioni script e `<cffunction>`, parametri e access level come metadata;
- property script e `<cfproperty>`;
- import/include (`import`, `<cfinclude>`) e riferimenti a componenti;
- action MCP e endpoint HTTP tramite overlay euristico prudente;
- `<cfquery>`/`queryExecute` soltanto come metadata di presenza o riferimento,
  senza SQL/body persistito.

Rischio specifico: il pacchetto Node candidato documenta runtime Node
`>=18 <24` e build native con GCC/MinGW su Windows, mentre la CI del repository
usa Node 24. Il binding nativo non e' quindi approvabile senza verifica o
aggiornamento upstream; per il PoV va valutato prima il caricamento WASM. La
grammatica dichiara test principalmente su Lucee: fixture Adobe ColdFusion e
Lucee devono restare separate per evitare equivalenze non dimostrate.

#### PHP

Estensioni iniziali: `.php` e, solo con fixture dedicate, `.phtml`. La
grammatica ufficiale Tree-sitter distingue PHP embedded e `php_only`.

Estrarre almeno:

- namespace e `use`;
- classi, interfacce, trait ed enum;
- funzioni, metodi, costruttori, proprieta' e costanti;
- include/require;
- route/endpoint soltanto tramite query/overlay framework-specifici
  allowlisted, senza assumere Laravel, Symfony o altro framework dal solo PHP.

#### C# / .NET 10

Estensione iniziale: `.cs`. Per progetti `net10.0`, la versione di linguaggio
predefinita e' C# 14; la grammatica candidata dichiara copertura C# 1-14, con
limiti espliciti su alcune direttive delle file-based app. `.csproj` puo'
essere letto temporaneamente solo per rilevare TFM/LangVersion, senza
persistirne contenuto.

Estrarre almeno:

- namespace e `using`;
- classi, record, struct, interfacce ed enum;
- metodi, costruttori, proprieta', eventi e costanti;
- attributi rilevanti come metadata;
- ASP.NET Core controller/action, attributi `Route`/`Http*` e Minimal API
  `MapGet`/`MapPost`/equivalenti tramite overlay deterministico;
- nomi qualificati e range di linea quando disponibili.

#### Storage e compatibilita'

- Nessun contenuto sorgente, snippet, SQL o body viene persistito o restituito.
- L'incrementalita' resta ancorata a `code_files.content_sha256`; chiave cache
  effettiva: hash file + adapter + versione adapter + parser mode.
- Un cambio adapter/versione forza il riallineamento dei soli simboli del file,
  preservando UUID quando la chiave stabile coincide.
- Code source e simboli restano locali anche su installazioni con remote-server;
  `docs_codebase` continua a non essere pubblicato dal remote-server.
- M16 non introduce link documento-simbolo, semantic compilation, type
  resolution, package restore, build del progetto o esecuzione di codice.

#### Proof of value e criteri di accettazione

- Fixture reali ma redatte per CFML tag/script/CFC/CFM, PHP mixed/pure e C# 14
  su `net10.0`, con expected symbols revisionati.
- Baseline disabilitata identica a M12: stessi tool, output e setup base.
- Parser opzionale mancante/incompatibile: warning strutturato e nessun crash.
- Test Windows, Linux e macOS sulla modalita' scelta; Node 24 obbligatorio per
  la CI repository.
- Nessuna toolchain C/C++ richiesta quando la capability e' disabilitata.
- Nessun byte sorgente in DB/output; hash, versioni e tombstone restano
  deterministici.
- Evidenza di miglioramento sui casi che `symbols_light` non riconosce; senza
  beneficio misurabile la milestone torna `DEFERRED`.

#### Fonti esterne verificate

- Tree-sitter parser registry: PHP, C#, CFML/CFScript/CFQuery con parser
  generati e ABI correnti: <https://github.com/tree-sitter/tree-sitter/wiki/List-of-parsers>
- PHP grammar ufficiale: <https://github.com/tree-sitter/tree-sitter-php>
- C# grammar ufficiale, copertura dichiarata C# 1-14:
  <https://github.com/tree-sitter/tree-sitter-c-sharp>
- CFML grammar candidata, dialect `.cfm`/`.cfc`, CFScript e CFQuery:
  <https://github.com/cfmleditor/tree-sitter-cfml>
- Microsoft C# language versioning: .NET 10 usa C# 14 come default:
  <https://learn.microsoft.com/dotnet/csharp/language-reference/language-versioning>

---

### Milestone 17 - Feature-status adoption advisories e gate di classificazione

**Stato:** `IMPLEMENTED`.

`docs_management feature_status` mantiene invariati i blocchi legacy
`tags`, `scan_sources`, `shelf_links` e `document_links`, e aggiunge in modo
additivo `adoption_advisories`. Gli advisory non misurano invocazioni MCP né
identificano agenti: derivano esclusivamente da conteggi aggregati SQLite e
forniscono i passi preliminari quando una capability non puo produrre valore
senza setup.

- Copertura obbligatoria: provenance edge, concept graph, inventory codebase,
  link documento-file, symbol extraction, stale documentation e consultazione
  remota.
- Non richiedono advisory di inizializzazione: lint, pathfinding/neighborhood
  ed export Obsidian. Sono read-only/on-demand e rimangono scopribili da
  `tools/list`, README e skill.
- Ogni action delle superfici `docs_mindmap`, `docs_codebase` e `docs_remote`
  deve dichiarare una capability nel registry interno. Il boot fallisce se
  manca la classificazione o se una capability con
  `requires_initialization:true` non e collegata ad alcuna action.
- Remote-server: gli advisory non scrivono `feature_state`, non effettuano
  rete e dichiarano `docs_codebase`/client `docs_remote` non disponibili.
- Nessuna migration e nessuna tabella di telemetria: non sono memorizzati
  prompt, token, path, hash, contenuto, identity dell'agente o timestamp di
  invocazione.

**Test:** la smoke `docs-node.smoke.mjs` verifica il payload additivo e la
forma degli advisory; l'avvio del server esercita il gate di classificazione.
Ogni nuova capability con setup deve aggiornare registry, advisory, smoke e
documentazione nella stessa modifica.

---

### Milestone 18 - Visualizzazione interattiva del graph

**Stato decisionale:** `IMPLEMENTED`. La visualizzazione e'
indipendente dal decision gate M15/M16: non richiede AST, parser aggiuntivi,
migrazioni, entity type, change-log o sync incrementale.

La proposta adotta un canvas unico con layer filtrabili `document` e `concept`;
non separa quindi la mappa mentale dal concept graph. I link doc-code restano
metadata locali nell'inspector e fuori dal grafo della prima release. Per
sottografi bounded Mermaid e' gia' disponibile tramite `map_path` e
`map_neighborhood`; il possibile export HTML e' un artefatto locale, derivato,
single-file e rigenerabile, non una nuova fonte canonica.

La futura action proposta e' `docs_mindmap.export_mindmap_html`, limitata a
shelf locali scrivibili, con path/neighborhood come viste primarie e overview
clusterizzata soltanto con troncamento esplicito. Deve riusare l'adattatore
read-only esistente, non includere sorgenti/snippet, applicare marker + staging
per `force:true` e non scrivere DB, cursor, replica o change-log. Nessuna
azione `docs_remote` entra in M18 iniziale; un export da snapshot remoto e'
una decisione successiva e deve dichiarare `snapshot_only`.

Dettaglio tecnico, sicurezza, schema, test e documentazione da aggiornare:
[analisi dedicata visualizzazione graph](analisi-tecnica-visualizzazione-grafo-docs-node.md).

---

### Milestone 19 - Vista globale zoomabile e progressive disclosure (proposta)

**Stato decisionale:** `PROPOSED / NOT APPROVED`. M19 e' un miglioramento UX
locale dell'artefatto HTML M18, indipendente da M15/M16 e senza migrazioni,
tool MCP, change-log o sync remoto.

Obiettivo: offrire una **Vista completa** del grafo come orientamento a basso
dettaglio, con tooltip mouse/focus anche al minimo zoom. Il tooltip espone
label, tipo e UUID breve; click, Enter o Space fissano il dettaglio
nell'inspector. Zoom/pan, ricerca con recenter ed espansione/collasso dei
cluster avvengono nello stesso canvas, senza navigazione a pagine.

La vista clusterizzata resta il default; una "esplosione" non implica label
complete per tutti i nodi. M19 richiede hit-area minima, progressive disclosure,
limiti dichiarati e browser validation delle prestazioni. Canvas/WebGL resta
fuori scope salvo evidenza che SVG non sia sufficiente. Dettaglio completo:
[Milestone 19 nella analisi visualizzazione graph](analisi-tecnica-visualizzazione-grafo-docs-node.md#10-milestone-19-proposta--vista-globale-zoomabile-e-progressive-disclosure).

---

## 18. Test strategy complessiva

### 18.1 Smoke nuovi consigliati

```text
tests/smoke/docs-node-mindmap-certainty.smoke.mjs
tests/smoke/docs-node-mindmap-lint.smoke.mjs
tests/smoke/docs-node-concepts.smoke.mjs
tests/smoke/docs-node-map-path.smoke.mjs
tests/smoke/docs-node-codebase-inventory.smoke.mjs
tests/smoke/docs-node-codebase-links.smoke.mjs
tests/smoke/docs-node-stale-docs.smoke.mjs
tests/smoke/docs-node-obsidian-export.smoke.mjs
# solo dopo go M15/M16:
tests/smoke/docs-node-code-symbol-adapters.smoke.mjs
```

### 18.2 Test migration

Per ogni milestone con storage:

- DB vuoto;
- DB legacy privo di nuove tabelle;
- DB con dati reali minimali;
- rollback non distruttivo tramite backup manuale documentato;
- idempotenza migrazione.

### 18.3 Test schema MCP

Per ogni nuovo tool/action:

- `tools/list` valido;
- ogni array in schema dichiara `items`;
- errori leggibili;
- `apply=false` default dove appropriato;
- output duale `content` breve + `structuredContent` stabile se adottato dal pattern repo.

### 18.4 Performance guardrails

Metriche minime da registrare nei test o nei report:

- file scansionati;
- file saltati;
- tempo scansione;
- simboli estratti;
- link proposti;
- link applicati;
- issue lint;
- dimensione DB prima/dopo.

---

## 19. Rischi e mitigazioni

| Rischio | Impatto | Mitigazione |
| --- | --- | --- |
| Overhead scansione codebase | medio | opt-in, metadata-only, incremental hash |
| Dipendenze native Tree-sitter | alto | fase opzionale tardiva, fallback leggero |
| Grafo rumoroso | alto | certainty, provenance, lint, apply=false |
| Feedback loop agente | alto | source_role, provenance, lint self-generated |
| Esposizione codice via sync/export | alto | metadata-only default, local-only, opt-in esplicito |
| Migrazioni complesse | medio | milestone piccole, migration test legacy/vuoto |
| ABI/runtime parser incompatibile con Node 24 | alto | PoV su Node 24, preferenza WASM/precompilato, fallback light |
| Divergenze Adobe ColdFusion/Lucee | alto | fixture separate, native kind/provenance, nessuna equivalenza implicita |
| False positive endpoint framework-specifici | medio | overlay allowlisted, evidence del pattern, nessuna semantic inference automatica |
| Context pressure su vault grandi | medio | pathfinding, filtri certainty, max depth |
| Link stale | medio | hash evidence, stale docs detection |
| Breaking compatibility MCP | alto | nuovi tool separati, output backward-compatible |

---

## 20. Criteri di successo

La fase e' utile se produce questi risultati misurabili:

1. Un documento puo' mostrare concetti, file e simboli correlati con evidence.
2. Un cambio codice puo' indicare documenti probabilmente da aggiornare.
3. Un agente puo' trovare il percorso tra requisito documentato e implementazione senza caricare tutto lo scaffale.
4. Il lint individua link morti/stale/ambigui senza cancellare dati curati.
5. La scansione codebase resta disabilitata finche' non viene configurata.
6. Lo storage resta SQLite e il setup base non peggiora.
7. Nessun contenuto codice viene sincronizzato o esportato senza opt-in.
8. Tutte le modifiche passano smoke e migration test.
9. M15 e M16 restano fuori scope finche' un decision gate esplicito non ne
   approva PoV, dipendenze, piattaforme e criteri di valore.
10. M18 e' un export HTML locale implementato; non implica supporto remoto.
11. M19 resta proposta separata: vista globale zoomabile, tooltip al minimo
    zoom ed espansione progressiva richiedono decisione e browser validation.

---

## 21. Raccomandazione finale

Procedere con questa evoluzione, ma solo dopo avere stabilizzato la roadmap online/sync in corso.

Ordine consigliato:

```text
1. Provenance + certainty sui link esistenti
2. Lint mappa mentale
3. Concept graph minimale
4. Pathfinding/neighborhood graph
5. Codebase inventory metadata-only
6. Link doc-code
7. Symbol extraction leggera
8. Stale docs detection
9. Export Obsidian-compatible
10. Feature-status adoption advisories e gate di classificazione
11. Decision gate M15 - AST/Tree-sitter opzionale (deferred)
12. M16 - adapter simboli CFML/PHP/C# .NET 10 (proposed, condizionato a M15)
13. M18 - visualizzazione graph HTML locale (implemented, indipendente da M15/M16)
14. M19 - vista globale zoomabile e progressive disclosure (proposed, local-only)
```

La scelta piu' importante e' mantenere il focus:

```text
Non costruire un secondo motore di code search.
Costruire un layer di traceability tra documentazione, concetti e implementazione.
```

In questo modo `docs-node` resta leggero, locale e compatibile con l'architettura attuale, ma diventa molto piu' utile per agenti AI che devono ragionare su documentazione, codice e stato implementativo reale.

---

## 22. Fonti e riferimenti interni usati per l'analisi

Fonti repository considerate:

- `skills/mcp-technical-analyst/SKILL.md`: routing e regole di analisi multi-sorgente.
- `skills/mcp-technical-analyst/references/deliverable-templates.md`: struttura del deliverable tecnico.
- `AGENTS.md`: governance minima, compatibilita' legacy, migrazioni e smoke.
- `docs/mcp-skills-agents-development-guide.md`: policy MCP, docs-first, compatibilita' host/client e test strategy.
- `docs/mcp-runtime-upgrade-governance.md`: regole per storage persistente e migrazioni.
- `docs-node/README.md` su branch `reworks_docs_node_part2`: stato modalita' remote-server, sync, replica, conflitti e tool `docs_remote`.
- `docs-node/index.js` su branch `reworks_docs_node_part2`: manifest V3, HTTP transport, costanti sync e remote client.
- `docs-node/src/db/migrations.js` su branch `reworks_docs_node_part2`: UUID, versioni, hash, remote sources, sync state, changelog e conflitti.
- `docs-node/src/http/read-only-server.js` su branch `reworks_docs_node_part2`: endpoint HTTP sync/read-write protetti.
- `docs-node/src/remote/client.js` su branch `reworks_docs_node_part2`: fetch remoto, auth profile, retry/backoff e timeout.
- Discussione sul video Graphify/Obsidian: ingestion deterministica, livelli di certezza, wiki layer, hash incrementale, lint e rischi di feedback loop.