@designerbyron/lifecode-rag 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +191 -2
  3. package/bin/lifecode-rag.mjs +449 -0
  4. package/client.js +2801 -0
  5. package/cordis.patch.yml +3 -0
  6. package/docs/ARCHITECTURE-v0.2.md +269 -0
  7. package/docs/AUTO-DISCOVERY.md +111 -0
  8. package/docs/AUTOMATION-POLICIES.md +232 -0
  9. package/docs/CONTRATO-v0.1.md +195 -0
  10. package/docs/EMBEDDING-PROVIDERS.md +105 -0
  11. package/docs/OBSERVABILITY.md +241 -0
  12. package/docs/PA-UI-0-API-CONTRACT.md +802 -0
  13. package/docs/PERFORMANCE-BUDGETS.md +118 -0
  14. package/docs/PROJECT-AWARE-ARCHITECTURE.md +580 -0
  15. package/docs/PROJECT-AWARE-DATA-CONTRACT.md +411 -0
  16. package/docs/PROJECT-AWARE-ERROR-CONTRACT.md +112 -0
  17. package/docs/PROJECT-AWARE-SESSION-CONTRACT.md +120 -0
  18. package/docs/WORKSPACE-API.md +239 -0
  19. package/icon.svg +7 -0
  20. package/index.js +198 -0
  21. package/lib/audit-export.mjs +70 -0
  22. package/lib/audit.mjs +120 -0
  23. package/lib/auto-context.mjs +322 -0
  24. package/lib/automation.mjs +214 -0
  25. package/lib/chunk.mjs +100 -0
  26. package/lib/config-resolve.mjs +119 -0
  27. package/lib/context.mjs +150 -0
  28. package/lib/conversation-events.mjs +145 -0
  29. package/lib/db.mjs +309 -0
  30. package/lib/diagnose.mjs +197 -0
  31. package/lib/discovery.mjs +402 -0
  32. package/lib/doctor.mjs +82 -0
  33. package/lib/embed.mjs +96 -0
  34. package/lib/embedders.mjs +103 -0
  35. package/lib/errors.mjs +227 -0
  36. package/lib/exec-context.mjs +238 -0
  37. package/lib/extract.mjs +260 -0
  38. package/lib/harness-workspaces.mjs +85 -0
  39. package/lib/hash.mjs +34 -0
  40. package/lib/ingest.mjs +239 -0
  41. package/lib/inputs.mjs +67 -0
  42. package/lib/library-state.mjs +252 -0
  43. package/lib/maintenance.mjs +113 -0
  44. package/lib/metrics.mjs +164 -0
  45. package/lib/migrate.mjs +373 -0
  46. package/lib/operations.mjs +132 -0
  47. package/lib/pa-api.mjs +517 -0
  48. package/lib/paths.mjs +345 -0
  49. package/lib/policy.mjs +125 -0
  50. package/lib/profile.mjs +128 -0
  51. package/lib/readmodel.mjs +159 -0
  52. package/lib/recovery.mjs +557 -0
  53. package/lib/registry-schema.mjs +206 -0
  54. package/lib/registry.mjs +406 -0
  55. package/lib/resolve.mjs +311 -0
  56. package/lib/retention.mjs +143 -0
  57. package/lib/revocation.mjs +124 -0
  58. package/lib/roots-structure.mjs +224 -0
  59. package/lib/schema.mjs +173 -0
  60. package/lib/scope-ops.mjs +379 -0
  61. package/lib/scope-stores.mjs +128 -0
  62. package/lib/search.mjs +345 -0
  63. package/lib/selection.mjs +150 -0
  64. package/lib/server.mjs +335 -0
  65. package/lib/session-identity.mjs +51 -0
  66. package/lib/sessions.mjs +343 -0
  67. package/lib/sync-scheduler.mjs +354 -0
  68. package/lib/sync.mjs +755 -0
  69. package/lib/tags.mjs +45 -0
  70. package/lib/tools.mjs +364 -0
  71. package/lib/trusted-roots.mjs +149 -0
  72. package/lib/worker-context.mjs +22 -0
  73. package/package.json +67 -5
@@ -0,0 +1,3 @@
1
+ - insert:
2
+ - id: lifecode-rag
3
+ name: '@designerbyron/lifecode-rag'
@@ -0,0 +1,269 @@
1
+ # LifeCode RAG — Arquitectura v0.2
2
+
3
+ **Fecha:** 2026-11-17 · **Ámbito:** `lifecode-rag/` · **Estado:** propuesta para autorización (no implementada)
4
+ **Base:** v0.1.0 implementada y verificada (66/66 pruebas, `check` verde, herméticos verdes)
5
+
6
+ ---
7
+
8
+ ## 1. Qué cambia y qué no
9
+
10
+ v0.1.0 es un **motor de herramientas**: siete tools `lifecode_rag_*` sobre un almacén SQLite propio.
11
+ v0.2.0 añade dos capas —**Workspace** (pestaña nativa) y **Observabilidad**— y convierte la recuperación
12
+ en una capacidad configurable, sin reescribir el motor.
13
+
14
+ Lo que **no** cambia:
15
+
16
+ - El contrato de las siete herramientas v0.1.0 queda congelado (ver `CONTRATO-v0.1.md`).
17
+ - El almacén sigue siendo SQLite propiedad exclusiva del plugin (`node:sqlite`, FTS5, vectores BLOB).
18
+ - Cero dependencias `@deepseek-ai/*` y cero dependencias de ejecución nuevas en esta etapa.
19
+ - La separación de etapas: ingesta → normalización → chunking → embeddings → índice → recuperación →
20
+ contexto → citas. Ninguna etapa se salta ni se fusiona para "simplificar".
21
+
22
+ Lo que **sí** cambia:
23
+
24
+ - El Workspace **no lee tablas**: consume un *read model* (`lib/query.mjs`) y una API HTTP versionada.
25
+ - Se añaden métricas **agregadas** y un motor de **políticas** con tres niveles de automatización.
26
+ - Los embeddings dejan de ser un detalle interno y pasan a ser un **puerto** con proveedores evaluables.
27
+
28
+ ## 2. Principios rectores
29
+
30
+ | Principio | Consecuencia arquitectónica |
31
+ |---|---|
32
+ | Independencia de Skill Center | Sin imports, sin rutas, sin estado ni ciclos de instalación compartidos. La única coincidencia permitida es que ambos son bundles de DSH. |
33
+ | Local First | Ninguna ruta de código abre sockets salvo un proveedor de embeddings declarado como remoto y aprobado por llamada. |
34
+ | Eficiencia de tokens | Recuperación selectiva, salida compacta por defecto, presupuesto de contexto explícito y medición del ahorro. |
35
+ | Fail-closed | Permiso ausente, estado ambiguo o validación fallida ⇒ error tipado, nunca una escritura parcial. |
36
+ | Una sola fuente de verdad | SQLite es autoritativo; las proyecciones (snapshot, métricas, JSONL de auditoría) son derivadas y regenerables. |
37
+ | Contratos antes que pantallas | La UI consume contratos versionados; nunca conoce el esquema interno. |
38
+
39
+ ## 3. Vista de capas
40
+
41
+ ```mermaid
42
+ flowchart TB
43
+ subgraph Host[DSH Host]
44
+ T[7 tools lifecode_rag_*]
45
+ A[approval]
46
+ W[webServer]
47
+ S[slots client]
48
+ end
49
+
50
+ subgraph Core[Core — lib/]
51
+ ING[ingest] --> EXT[extract] --> NRM[normalize] --> CHK[chunk] --> EMB[embed port] --> IDX[index]
52
+ QRY[search] --> FUSE[fuse RRF] --> CTX[context MMR] --> CIT[citations]
53
+ POL[policy engine] -.gate.- ING
54
+ POL -.gate.- QRY
55
+ AUD[audit chain] -.append.- ING
56
+ AUD -.append.- MAINT[maintenance]
57
+ end
58
+
59
+ subgraph Store[Store]
60
+ DB[(SQLite: sources, chunks, chunks_fts, vectors, source_tags, audit, meta)]
61
+ end
62
+
63
+ subgraph Read[Read model — lib/query.mjs]
64
+ RM[snapshot · sources · metrics · health]
65
+ end
66
+
67
+ subgraph Workspace[Workspace]
68
+ HTTP[HTTP API /lifecode-rag/api/v1] --> CL[client.js · pestaña nativa]
69
+ end
70
+
71
+ T --> Core
72
+ IDX --> DB
73
+ QRY --> DB
74
+ MAINT --> DB
75
+ AUD --> DB
76
+ DB --> RM --> HTTP
77
+ W --> HTTP
78
+ S --> CL
79
+ A --> T
80
+ ```
81
+
82
+ Regla de dependencia, verificable con `tools/check.mjs`:
83
+
84
+ ```
85
+ index.js → lib/tools.mjs → lib/{ingest,search,context,maintenance}
86
+ lib/query.mjs → lib/db.mjs (solo lectura)
87
+ lib/workspace-api.mjs → lib/query.mjs (+ acciones que llaman al core)
88
+ client.js → HTTP únicamente
89
+ lib/core nunca importa lib/workspace-api, lib/query, client ni nada del Workspace
90
+ ```
91
+
92
+ ## 4. Módulos de v0.1.0 (baseline real)
93
+
94
+ | Módulo | Responsabilidad | Estado |
95
+ |---|---|---|
96
+ | `lib/paths.mjs` | Raíz, configuración, `isWithin`. | implementado |
97
+ | `lib/errors.mjs` | `RagError`, 25 códigos declarados. | implementado, con deuda (3 códigos emitidos sin declarar) |
98
+ | `lib/hash.mjs` | SHA-256, digest normalizado, `chunk_key`. | implementado |
99
+ | `lib/schema.mjs` | DDL v2, `application_id`, `meta`. | implementado |
100
+ | `lib/db.mjs` | Apertura, guardas, transacciones, FTS integrity/rebuild. | implementado |
101
+ | `lib/extract.mjs` | Formatos texto, HTML/JSON/JSONL/CSV, normalización. | implementado |
102
+ | `lib/chunk.mjs` | Chunking con solape, encabezados, offsets. | implementado |
103
+ | `lib/embed.mjs` | `local-hash-v1` (256 dims), coseno, BLOB. | implementado, **léxico** |
104
+ | `lib/ingest.mjs` | Preparación completa y sustitución atómica por fichero. | implementado |
105
+ | `lib/search.mjs` | FTS5/BM25, vectores, RRF k=60, filtros. | implementado |
106
+ | `lib/context.mjs` | MMR, presupuesto, citas. | implementado |
107
+ | `lib/maintenance.mjs` | forget, reindex fts/vectors/all. | implementado |
108
+ | `lib/audit.mjs`, `lib/audit-export.mjs` | Cadena de hashes, export JSONL, verificación. | implementado |
109
+ | `lib/policy.mjs` | Rutas protegidas, symlink/junction, hardlink. | implementado |
110
+ | `lib/tags.mjs` | Etiquetas normalizadas. | implementado |
111
+ | `lib/doctor.mjs` | Diagnóstico. | implementado |
112
+ | `lib/tools.mjs`, `index.js` | Siete tools + adaptador. | implementado |
113
+
114
+ ## 5. Módulos nuevos de v0.2.0
115
+
116
+ | Módulo | Responsabilidad | No puede |
117
+ |---|---|---|
118
+ | `lib/ports/embedding.mjs` | Contrato `EmbeddingProvider` + registro. | abrir red por sí mismo |
119
+ | `lib/ports/extractor.mjs` | Contrato `DocumentExtractor` (futuro PDF/DOCX). | importar el core |
120
+ | `lib/query.mjs` | Read model: snapshot, fuentes, salud, métricas. Solo `SELECT`. | escribir, abrir transacciones de escritura |
121
+ | `lib/metrics.mjs` | Agregación diaria, retención, consultas de series. | guardar prompts, respuestas o texto de consulta |
122
+ | `lib/policies.mjs` | Evaluación de políticas y clasificación de acciones. | conceder aprobaciones |
123
+ | `lib/workspace-api.mjs` | Rutas HTTP v1, validación de entrada, serialización. | acceder a tablas fuera de `query.mjs` |
124
+ | `lib/automation.mjs` | Indexación programada dentro de raíces autorizadas, con presupuesto. | saltarse `policy`/`approval` |
125
+
126
+ ## 6. Puertos y contratos
127
+
128
+ ### 6.1 `EmbeddingProvider`
129
+
130
+ ```js
131
+ /**
132
+ * @typedef {Object} EmbeddingProvider
133
+ * @property {string} id Identidad estable, p. ej. 'local-hash-v1' o 'onnx-minilm-multilingual-v1'
134
+ * @property {number} dim
135
+ * @property {'local'|'remote'} kind
136
+ * @property {(texts: string[], opts?: {signal?: AbortSignal}) => Promise<Float32Array[]>} embedBatch
137
+ */
138
+ ```
139
+
140
+ Reglas: determinista para el mismo `id`+`dim`; L2-normalizado; error tipado (`embedding-failed`);
141
+ un proveedor remoto exige aprobación por llamada y no se activa por configuración sola. El `id` se
142
+ almacena junto a cada vector, de modo que dos modelos pueden convivir durante una migración.
143
+
144
+ ### 6.2 `DocumentExtractor`
145
+
146
+ `{ id, extensions: string[], extract(bytes, {path, mime}) => {text, mime} }`. Los extractores registrados
147
+ se evalúan por extensión; ninguno puede leer fuera del buffer recibido.
148
+
149
+ ### 6.3 `ReadModel`
150
+
151
+ `lib/query.mjs` expone funciones puras sobre una conexión de solo lectura:
152
+
153
+ ```js
154
+ snapshot(db) // { counts, health, lastIndexedAt, embedders: [...] }
155
+ listSources(db, query) // paginado, filtros por colección/etiqueta/estado
156
+ sourceDetail(db, ref) // metadatos + chunks (paginados, sin texto completo por defecto)
157
+ metricsSummary(db, {from, to})
158
+ metricsSeries(db, {metric, from, to, bucket})
159
+ ```
160
+
161
+ Ninguna función de `query.mjs` puede recibir SQL, ni devolver filas crudas con columnas internas
162
+ (`prev_hash`, `vec` binario, `meta` completo).
163
+
164
+ ## 7. Flujos
165
+
166
+ ### 7.1 Ingesta (sin cambios de fondo)
167
+
168
+ ```mermaid
169
+ sequenceDiagram
170
+ participant M as Modelo
171
+ participant T as lifecode_rag_ingest
172
+ participant P as policy
173
+ participant I as ingest
174
+ participant DB as SQLite
175
+ M->>T: paths / collection / tags / force
176
+ T->>T: expandir directorios, clasificar TODAS las rutas
177
+ alt ruta protegida o fuera de raíz
178
+ T-->>M: path-denied / approval-required (sin abrir el almacén)
179
+ end
180
+ T->>P: ¿raíz autorizada?
181
+ T->>I: prepareDocument (extraer, chunk, vectores)
182
+ I->>DB: BEGIN IMMEDIATE
183
+ I->>DB: upsert source + delete chunks antiguos + insert + tags + audit
184
+ I->>DB: COMMIT
185
+ I-->>T: {ingested, skipped, errors}
186
+ ```
187
+
188
+ Invariante I6: toda fila de `sources` tiene ≥1 chunk. Un fallo de preparación no toca la versión anterior.
189
+
190
+ ### 7.2 Recuperación y contexto
191
+
192
+ 1. `queryTokens` → FTS5 (`bm25`) y vector search (coseno) en paralelo lógico.
193
+ 2. `fuseRrf` con k=60; empates por `chunk_key`.
194
+ 3. `assembleContext` con MMR (λ=0.7), presupuesto en tokens estimados (`ceil(chars/4)`), sin cortar chunks.
195
+ 4. Citas `[n]` con `chunkKey`, URI, offsets.
196
+
197
+ ### 7.3 Workspace
198
+
199
+ ```mermaid
200
+ sequenceDiagram
201
+ participant U as Persona
202
+ participant C as client.js
203
+ participant H as /api/v1
204
+ participant Q as query.mjs
205
+ participant DB as SQLite
206
+ U->>C: abre pestaña
207
+ C->>H: GET /snapshot
208
+ H->>Q: snapshot(db)
209
+ Q->>DB: SELECT agregados (solo lectura)
210
+ Q-->>H: conteos, salud, proveedores
211
+ H-->>C: JSON (ETag)
212
+ C-->>U: Overview con estado real
213
+ ```
214
+
215
+ El Workspace no escribe: las acciones (reindexar, olvidar, cambiar política) van por `POST /actions`,
216
+ pasan por el mismo evaluador de políticas y, cuando toca, por `ctx.approval.request`.
217
+
218
+ ## 8. Aislamiento respecto de Skill Center
219
+
220
+ LifeCode Skill Center y LifeCode RAG comparten host, no producto. Concretamente:
221
+
222
+ - No hay imports cruzados ni rutas de estado compartidas.
223
+ - `PROTECTED_SEGMENTS = ['lifecode-skill-center']` sigue rechazando cualquier ruta que contenga ese
224
+ segmento, incluidas las copias instaladas en el perfil.
225
+ - El Workspace de RAG vive en su propio slot (`sidebar.panellist` id `lifecode-rag`, `main` clave
226
+ `lifecode-rag`); no reutiliza el id `lifecode-skill-center`.
227
+ - Los ciclos de instalación son independientes: dos bundles, dos filas de loader, dos versiones.
228
+
229
+ ## 9. Compatibilidad con el host (evidencia)
230
+
231
+ | Capacidad | Contrato verificado | Fuente |
232
+ |---|---|---|
233
+ | Pestaña nativa | slot `sidebar.panellist` (lista, `id` direcciona el panel) + slot `main` (keyed, misma clave) | `Slots.listSubTree` en vivo; ocupantes actuales incluyen `lifecode-skill-center` |
234
+ | Panel activo | prop estándar `usePanelInfo` → `PanelInfo.activePanelId` (`null` = Conversación) | `dsh-client-ui-layout/src/client/service.ts` y `src/client/index.ts` |
235
+ | Icono de rail | props `{size, active}` del owner | catálogo del slot |
236
+ | HTTP | `ctx.webServer.register({kind, path, handler})`, rutas nombradas, `getOrigin()` | servicio `webServer` |
237
+ | Aprobaciones | `ctx.approval.request` → solo `allowed-once` concede | servicio `approval` |
238
+ | Working directory | `ctx.workingDirectory.ensure(agent, signal)` | servicio `workingDirectory` |
239
+ | Tema | tokens `--dsw-alias-*` (14 verificados) | `Theme.listTokens` |
240
+ | Cliente | `window.__ModuleLoader__.load({id, factory})`, React del loader | `ui-plugin.md` + precedente LSC |
241
+ | SQLite/FTS5 | `node:sqlite` 3.53.4 en el proceso host | sonda propia (v0.1.0) |
242
+
243
+ No se asume ninguna API por nombre: lo que no está en esta tabla se marca como no verificado en
244
+ `PLAN-v0.2.0.md` y se comprueba en M0 antes de escribir código.
245
+
246
+ **Ciclo de vida del panel.** El host no emite un evento de «panel seleccionado»; la señal es el hook
247
+ `usePanelInfo` que el runtime inyecta en el slot `main` (contrato de `dsh-client-ui-layout`). La UI lo usa
248
+ para detener el refresco cuando el panel no está activo (`WORKSPACE-UX.md` §5); `document.visibilityState`
249
+ solo cubre minimizado. Si ese hook desapareciera en una versión futura, el panel debe degradar a «sin
250
+ refresco automático», no a polling ciego.
251
+
252
+ ## 10. Riesgos arquitectónicos
253
+
254
+ | Riesgo | Impacto | Mitigación |
255
+ |---|---|---|
256
+ | El read model se convierte en segunda lógica | Divergencia UI/motor | `query.mjs` solo agrega; los cálculos de recuperación siguen en `search`/`context` |
257
+ | Métricas que se vuelven vigilancia | Privacidad | Solo agregados; sin texto de consulta ni prompts; retención y borrado |
258
+ | Pestaña que ralentiza el escritorio | Mala experiencia | Carga diferida por sección, sin polling oculto, presupuestos medidos |
259
+ | Proveedor de embeddings que cambia la calidad | Regresión silenciosa | `model_id` por vector + evaluación obligatoria antes de promover |
260
+ | Automatización que erosiona aprobaciones | Seguridad | Tres niveles explícitos; el motor de políticas no puede conceder |
261
+ | Crecimiento del almacén | Coste y latencia | Retención de métricas, compactación documentada, límites por ingesta |
262
+
263
+ ## 11. Decisiones abiertas
264
+
265
+ - Formato exacto del fichero de políticas (`policies.json` vs tabla `policies`): se decide en M1 con
266
+ criterio de atomicidad y auditoría.
267
+ - ¿El Workspace necesita WebSocket para progreso de ingesta larga, o basta polling bajo demanda?
268
+ Se mide en M3; por defecto, sin WebSocket.
269
+ - ¿Las métricas viven en SQLite o en un JSONL agregado? SQLite por transaccionalidad; se confirma en M1.
@@ -0,0 +1,111 @@
1
+ # Descubrimiento automático de proyectos y resolución por sesión
2
+
3
+ **Fecha:** 2026-11-19 · **Estado:** implementado y probado en local · **Ámbito:** `lifecode-rag`
4
+
5
+ ## Qué problema resuelve
6
+
7
+ Antes, una sesión nueva sin selección explícita fallaba con `scope-unresolved` aunque su `cwd`
8
+ estuviera dentro de un proyecto real ya registrado, y el panel mostraba datos sintéticos como si
9
+ fueran el proyecto activo. Ahora el plugin puede **descubrir** proyectos dentro de una ubicación de
10
+ trabajo en la que el usuario confía, **registrarlos** de forma idempotente y **resolver** el proyecto
11
+ de la sesión por su `cwd`, sin exigir selección manual y sin ampliar por su cuenta el ámbito de lectura.
12
+
13
+ ## Los cuatro conceptos (no son sinónimos)
14
+
15
+ | Concepto | Qué significa | Dónde vive |
16
+ |---|---|---|
17
+ | Workspace confiable | Ubicación de trabajo que una persona confió una vez (`trusted_roots`, máx. 32) | `meta.trusted_roots` del registro |
18
+ | Proyecto descubierto | Proyecto detectado por indicadores dentro de un workspace confiable | resultado de `scanWorkspace` |
19
+ | Proyecto registrado | Proyecto con identidad estable (`prj_…`) y raíz autorizada | tablas `projects`/`roots` |
20
+ | Proyecto indexado | Proyecto con almacén de ámbito y fuentes | `profiles/<perfil>/scopes/<id>/rag.sqlite3` |
21
+
22
+ Descubrir **no** indexa, **no** lee documentos y **no** autoriza lectura. La única autorización que
23
+ abre la puerta es `trust add --path <abs>` (por defecto con autorización de lectura) ejecutada por una
24
+ persona o por un mecanismo del host. Sin `readAuthorization`, la resolución automática no registra nada.
25
+
26
+ ## Indicadores reconocidos
27
+
28
+ `artisan` (Laravel), `composer.json` (PHP), `package.json` (Node, clasificado por dependencias en
29
+ nuxt/next/vue/react/angular/svelte), `*.sln`/`*.csproj` (.NET), `pyproject.toml`/`requirements.txt`
30
+ (Python), `go.mod`, `Cargo.toml`, `pom.xml`, `Gemfile`, `.git` (Git), `index.html` (web). Sólo se lee
31
+ `package.json` (≤ 256 KiB) para clasificar; nunca ficheros de secretos (`.env*`, claves, `.npmrc`,
32
+ `credentials.json`, …).
33
+
34
+ Se excluyen `.git`, `node_modules`, `vendor`, `dist`, `build`, `out`, `target`, `bin`, `obj`,
35
+ `.next`, `.nuxt`, `__pycache__`, `.venv`, `venv`, `cache`, `tmp`, `.idea`, `.vscode`, `secrets`,
36
+ `.ssh`, y los enlaces simbólicos (se registran como `skipped`, no se recorren).
37
+
38
+ ## Registro idempotente
39
+
40
+ `registerDiscoveredProject` se apoya en la raíz registrada (`roots.path_key`): si el proyecto ya
41
+ existe se actualizan sólo los metadatos (`project_discovery:<id>`: tipo, indicadores, primera/última
42
+ detección, raíz registrada) y se **conservan** el `id`, el almacén y las fuentes. Un cambio de ruta
43
+ crea una entrada nueva de descubrimiento, no reescribe el proyecto histórico. Nunca se crea un
44
+ almacén por descubrir.
45
+
46
+ ## Resolución por sesión
47
+
48
+ 1. Identidad del host (`exec.agent.id`) y perfil.
49
+ 2. Selección explícita si existe (prevalece, incluidas raíces anidadas: gana la más específica).
50
+ 3. Si no hay selección: `cwd` → `findProjectBoundary` (sube desde el `cwd` hasta el workspace
51
+ confiable, tolera directorios aún no creados) → auto-registro si hay autorización de lectura →
52
+ `resolveScope` normal.
53
+ 4. Sin workspace confiable, sin autorización o fuera de toda raíz: `scope-unresolved` (nunca una
54
+ búsqueda global, nunca un proyecto por defecto).
55
+
56
+ ## CLI
57
+
58
+ ```sh
59
+ node bin/lifecode-rag.mjs trust add --path C:\ruta\a\mi-proyecto --read true
60
+ node bin/lifecode-rag.mjs trust list
61
+ node bin/lifecode-rag.mjs discover scan --path C:\ruta\a\mi-proyecto
62
+ node bin/lifecode-rag.mjs discover register --path C:\ruta\a\mi-proyecto --read true
63
+ node bin/lifecode-rag.mjs discover show --project prj_…
64
+ node bin/lifecode-rag.mjs trust remove --path C:\ruta\a\mi-proyecto
65
+ ```
66
+
67
+ `trust remove` revoca la confianza sin borrar proyectos ni almacenes.
68
+
69
+ ## Límites conocidos
70
+
71
+ - El panel sigue siendo **informativo** (fixtures de demostración claramente etiquetados): no hay API
72
+ con datos reales porque DSH no ofrece autenticación por sesión (PA-UI-0, BLOCKED). Las herramientas
73
+ del agente sí usan datos reales.
74
+ - La confianza se guarda en `meta` para no migrar el esquema; el día que haya tabla propia se migrará
75
+ con procedimiento reversible.
76
+ - No se descubren proyectos por red ni en unidades no confiadas; el escaneo es local y acotado
77
+ (`maxDepth` 4, `maxProjects` 200).
78
+
79
+ ## Harness Open Projects (2026-11-19)
80
+
81
+ DeepSeek Harness mantiene un registro durable de *workspaces* (`ctx.workspaceRegistry`): ruta
82
+ canónica, título y sesiones que lo tienen abierto. El plugin lo usa como la señal de **qué
83
+ proyectos tiene abiertos la persona**, en vez de deducirlo de `cwd` o de confiar en una carpeta
84
+ contenedora:
85
+
86
+ - `lib/harness-workspaces.mjs` normaliza los workspaces vivos (`listOpenProjects`) y resuelve el
87
+ proyecto de una sesión (`openProjectForSession`) o el que contiene un `cwd`
88
+ (`openProjectForCwd`). Los workspaces cuyo directorio ya no existe (`status() !== 'ok'`) se
89
+ omiten.
90
+ - Si la sesión pertenece a un proyecto abierto, ese proyecto es el candidato aunque su `cwd`
91
+ apunte a la carpeta contenedora. Abrir `plugins-dhs` **no** registra `businesssuite`,
92
+ `carlosdiaz` ni ningún hermano.
93
+ - Abrir un proyecto **no es autorizar**: la lectura sigue exigiendo `trust add` sobre la ruta del
94
+ proyecto. Sin esa autorización la llamada falla en cerrado con `scope-unresolved`,
95
+ `reason: "project-not-authorized"` y el comando exacto en `details.command`.
96
+ - Cuando el proyecto abierto es hijo del `cwd`, la resolución va directa a su id en lugar de
97
+ exigir una coincidencia por prefijo.
98
+
99
+ La prueba de forma real (`eval/auto-discovery-01/scripts-harness-shape.mjs`) copia el registro
100
+ real con `VACUUM INTO`, lee `$DSH_HOME/storages/workspace.json` y demuestra: sin trust →
101
+ `project-not-authorized`; con trust sólo de `<proyecto>` → resuelve ese proyecto con `cwd`
102
+ `<checkout>`; ningún hermano registrado; el registro y el almacén reales no cambian
103
+ (hashes antes/después en `16-harness-shape.txt`).
104
+
105
+ ### Límite de esta entrega
106
+
107
+ El agente que atiende esta sesión ejecuta el código cargado en el arranque del host. Este módulo y
108
+ la resolución por proyectos abiertos se escribieron **después** de ese arranque, así que la
109
+ verificación en vivo del host queda pendiente de la próxima recarga; las pruebas locales y la
110
+ prueba de forma real están en verde. El registro real tampoco tiene todavía un `trusted root` para
111
+ `plugins-dhs`, de modo que una llamada real sigue fallando en cerrado a propósito.
@@ -0,0 +1,232 @@
1
+ # LifeCode RAG — Políticas y automatización
2
+
3
+ **Fecha:** 2026-11-17 · **Estado:** diseño propuesto (no implementado)
4
+ **Regla madre:** la automatización nunca concede lo que una persona no autorizó; el motor de políticas
5
+ puede denegar, nunca aprobar.
6
+
7
+ ---
8
+
9
+ ## 1. Tres niveles
10
+
11
+ | Nivel | Quién decide | Ejemplos | Efecto si falta el permiso |
12
+ |---|---|---|---|
13
+ | **Automático** | Política vigente | recuperar, contar métricas, diagnosticar, exportar auditoría, indexar dentro de raíces ya autorizadas | se ejecuta o se omite; nunca pide |
14
+ | **Confirmación** | Persona, en el host o la UI | cambiar proveedor de embeddings, ampliar raíces, reindexado `all`, bajar retención de métricas | no se ejecuta; queda como propuesta |
15
+ | **Aprobación** | `ctx.approval.request` (solo `allowed-once`) | `forget`, acceso a rutas fuera de raíces, egress, purga masiva, operaciones destructivas | `approval-required` / `approval-unavailable` |
16
+
17
+ La desactivación de RAG no borra nada. La desinstalación no borra el almacén.
18
+
19
+ ## 2. Qué es automático de verdad
20
+
21
+ ### 2.1 Recuperación automática — límite real del host
22
+
23
+ **Corregido en PA6 (reconciliado 2026-11-18):** el host sí expone `agent/pre-step` y el plugin Project-Aware inyecta contexto con él (`lifecode-rag/index.js`, `lib/auto-context.mjs`). La v0.2 sigue sin inyectar porque su recuperación es de otro almacén. Texto original conservado por trazabilidad: no existía un punto de extensión verificado que permitiera **inyectar texto recuperado antes de
24
+ cada llamada al modelo**. `systemPrompt.section` añade instrucciones, no contenido por turno; escuchar
25
+ `system-prompt/assemble` está desaconsejado por la guía del host. Por tanto:
26
+
27
+ - **v0.2 no promete recuperación automática invisible.** Prometerla sin un hook sería mentir.
28
+ - Lo que sí se ofrece: una sección de prompt **opt-in** (`autoRetrieval.enabled=false` por defecto) que
29
+ instruye al agente a usar `lifecode_rag_search`/`lifecode_rag_context` cuando la pregunta toque
30
+ conocimiento del proyecto, con un presupuesto declarado.
31
+ - El agente sigue decidiendo la consulta; el motor no adivina.
32
+
33
+ Esta limitación se revisa en cada actualización del host; si aparece un hook (`agent.beforeModelCall` o
34
+ equivalente), se documenta y se evalúa con benchmark.
35
+
36
+ ### 2.2 Indexación automática
37
+
38
+ Permitida solo dentro de `roots` ya autorizadas y con presupuesto:
39
+
40
+ ```json
41
+ {
42
+ "version": 1,
43
+ "roots": ["C:/proyecto/docs"],
44
+ "autoIndex": { "enabled": false, "intervalMinutes": 15, "maxFilesPerRun": 50, "maxBytesPerRun": 10485760 },
45
+ "autoRetrieval": { "enabled": false, "budgetTokens": 1200, "maxChunks": 6 },
46
+ "retention": { "metricsDays": 90 },
47
+ "workspace": { "refreshSeconds": 30 }
48
+ }
49
+ ```
50
+
51
+ - Se ejecuta **como mucho** cada `intervalMinutes`, y solo si no hay turno abierto (`agents.turnBoundaryOf`)
52
+ y hay sesión activa. Si el host no permite saberlo, **no indexa**: la duda no autoriza.
53
+ - Compara `(size, mtime)` y digest antes de leer: un fichero sin cambios no se re-extrae.
54
+ - Un fallo por fichero se registra y no aborta el lote; el lote termina con `{ingested, skipped, errors}`.
55
+ - Nunca amplía raíces: una ruta nueva fuera de `roots` exige confirmación y, si está fuera del proyecto,
56
+ aprobación por llamada como en la tool.
57
+ - Cancelación: `signal` del host o botón de la UI; se comprueba entre ficheros.
58
+
59
+ ### 2.3 Diagnóstico y mantenimiento
60
+
61
+ - `doctor` y comprobación de integridad FTS: automáticos, solo lectura.
62
+ - `reindex fts`: automático si la integridad falla (reconstrucción derivada, no destruye datos).
63
+ - `reindex vectors`: confirmación; recorre todos los vectores y puede tardar.
64
+ - `forget`: siempre aprobación con alcance exacto (`sourceId`, URI, nº de chunks).
65
+ - Exportación de auditoría: automática (fichero derivado, regenerable).
66
+
67
+ ## 3. Evaluador
68
+
69
+ ```js
70
+ /**
71
+ * @returns {{decision:'allow'|'confirm'|'approve'|'deny', reason:string, code?:string, scope?:object}}
72
+ */
73
+ evaluate(action, context)
74
+ ```
75
+
76
+ `action` — `retrieve | ingest | reindex | forget | config.change | root.add | egress | purge`.
77
+ `context` = `{actor:'model'|'human'|'automation', sessionId, agentId, insideRoots, isProtected, egress, destructive}`.
78
+
79
+ ### 3.1 Clasificación de purgas (única fuente; `OBSERVABILITY.md` §7 la referencia)
80
+
81
+ | Operación | Nivel | Alcance obligatorio | Nota |
82
+ |---|---|---|---|
83
+ | purga rutinaria > `metricsDays` | automático | `{kind:'retention'}` | dentro de la retención ya autorizada; solo métricas |
84
+ | bajar `metricsDays` | confirmación | `{from,to}` | no borra hasta confirmar |
85
+ | purga anticipada de métricas | confirmación | `{before}` | conserva lo que quede dentro de la nueva retención |
86
+ | purgar todo el histórico de métricas | aprobación | `{all:true}` | auditoría con recuento borrado |
87
+ | borrar el almacén | aprobación | `{store:true}` | exige copia previa verificable |
88
+
89
+ Una purga **nunca** toca `sources`, `chunks`, `vectors` ni la auditoría: esas filas no son telemetría.
90
+
91
+ ### 3.2 Orden de evaluación (fail-closed)
92
+
93
+ 1. ¿Ruta protegida (Skill Center, almacén propio)? — `deny` `path-denied`.
94
+ 2. ¿Ruta fuera de raíces? — `approve` (una vez) o `deny` si no hay servicio de aprobación.
95
+ 3. ¿Purga? — nivel de §3.1; `scope` obligatorio; sin `scope` es `deny`, no una aprobación genérica.
96
+ 4. ¿Acción destructiva? — `approve` con `scope` obligatorio.
97
+ 5. ¿Cambio de proveedor/raíz? — `confirm`.
98
+ 6. ¿Dentro de política automática y presupuesto? — `allow`.
99
+ 7. Cualquier duda — `deny`.
100
+
101
+ El evaluador **no** llama a `approval`; devuelve la decisión y el llamador (tool/ruta) pide la aprobación.
102
+ Así una ruta HTTP no puede aprobar por sí misma.
103
+
104
+ ## 4. Integración con el host
105
+
106
+ - `ctx.approval.request({agent, toolName, reason, callId})`; solo `allowed-once` concede.
107
+ - Sin `approval` disponible —! `approval-unavailable` (fail-closed), nunca «seguir sin permiso».
108
+ - La UI muestra el estado «pendiente de aprobación»; no tiene botón de aprobar.
109
+ - Toda decisión (pedida/concedida/rechazada) se audita con `action`, `target`, `outcome`.
110
+
111
+ ## 5. Auditoría de políticas
112
+
113
+ Cambiar `policies.json` es una escritura sensible:
114
+
115
+ - validación completa antes de escribir (desconocido —! `invalid-config`; nunca se ignora en silencio);
116
+ - escritura atómica (tmp + fsync + rename) y `updated_at`;
117
+ - evento `policy.change` en la cadena de auditoría con el diff de claves (no valores secretos);
118
+ - la configuración efectiva se puede leer por `GET /config`, sin secretos.
119
+
120
+ ## 6. Presupuestos y degradación
121
+
122
+ - La indexación automática tiene techo por ejecución; al alcanzarlo para y reporta `truncated`.
123
+ - La recuperación automática tiene presupuesto de tokens; si no cabe, devuelve vacío con `truncated`
124
+ (nunca recorta un chunk a la mitad).
125
+ - Si el almacén está bloqueado (`store-busy`), la automatización reintenta una vez y desiste; no martillea.
126
+ - Si el proveedor de embeddings falla, la recuperación híbrida degrada a FTS y lo declara en `mode`.
127
+
128
+ ## 7. Matriz de pruebas
129
+
130
+ | Caso | Esperado |
131
+ |---|---|
132
+ | Ruta con segmento `lifecode-skill-center` | `path-denied`, sin abrir almacén |
133
+ | Ruta fuera de raíz sin aprobación | `approval-required`, sin escritura |
134
+ | `forget` sin `scope` | error de validación, no aprobación genérica |
135
+ | `reindex all` sin confirmación | `confirm` (no ejecuta) |
136
+ | Automatización con presupuesto agotado | `truncated:true`, sin excepción |
137
+ | `approval` ausente | `approval-unavailable` |
138
+ | Cambio de config con clave desconocida | `invalid-config`, fichero intacto |
139
+ | Política con `roots` que incluye Skill Center | rechazo al guardar, no al usar |
140
+ | Purga rutinaria dentro de retención | `allow`, solo `metrics_daily` |
141
+ | Bajar `metricsDays` | `confirm`, sin borrar hasta confirmación |
142
+ | Purga total de métricas sin `scope` | `deny`, sin borrado |
143
+ | Borrar almacén | `approve` + copia previa; sin copia, `deny` |
144
+ | Purga con `sources` en el alcance | `deny` (no es telemetría) |
145
+
146
+ ## 8. Sincronización periódica (M6.7)
147
+
148
+ El programador de `lib/sync-scheduler.mjs` sustituye a la automatización v0.2 sólo cuando el perfil
149
+ tiene registro Project-Aware. Se apoya **exclusivamente** en `ctx.timer.interval` del host.
150
+
151
+ ### 8.1 Interruptor
152
+
153
+ - `automation.enabled` se lee al arrancar el programador y en cada tick, desde
154
+ `<profileRoot>/config.json`.
155
+ - Cambiar el fichero con el plugin ya cargado **no arranca ni detiene** el temporizador: hay que
156
+ recargar el plugin (`plugin_manager` con `enabled:false` y luego `true`) para que `apply` vuelva a
157
+ ejecutarse. Es el procedimiento de activación y desactivación soportado.
158
+ - Al descargar el plugin, el `ctx.effect` ejecuta `stop()`: cierra el disposer del temporizador y
159
+ aborta la pasada en curso por el `AbortSignal` propio del programador.
160
+
161
+ ### 8.2 Presupuesto y degradación
162
+
163
+ | Situación | Respuesta |
164
+ |---|---|
165
+ | Presupuesto del tick agotado | corte entre ficheros, `stop_reason='budget'`, `outcome='partial'` |
166
+ | Límite de ficheros alcanzado | `stop_reason='file-limit'`, resto para la pasada siguiente |
167
+ | Tick solapado | no se ejecuta; `skippedTicks+1`, `lastSkipReason='already-running'` |
168
+ | Fallo de una pasada | `consecutiveFailures`, backoff `2^(n-1)` hasta 8 intervalos |
169
+ | Sin registro en el perfil | `{skipped:true, reason:'no-registry'}`, sin ruido por tick |
170
+ | Sin temporizador del host | `start()` devuelve `no-timer`; no hay respaldo global |
171
+
172
+ Un fallo no detiene el host ni desactiva el programador: se cuenta, se audita y se reintenta con
173
+ backoff. El reintento nunca repite efectos destructivos inciertos (el ledger y `effect_key` siguen
174
+ mandando).
175
+
176
+ ### 8.3 Aprobaciones
177
+
178
+ La sincronización periódica no pide aprobación por fichero: trabaja dentro de raíces ya autorizadas y
179
+ su compuerta es la autorización por ámbito (`assertScopeSyncable`) y la revocación entre ficheros. La
180
+ egreso sigue cerrado: sin proveedor remoto, o `egress-denied`. Ninguna ejecución automática ejecuta
181
+ `forget`, `reindex` ni `ingest` con rutas fuera de raíz.
182
+
183
+ ## 9. M6.8 — medición del presupuesto y observabilidad del backoff
184
+
185
+ Dos ajustes operativos salidos de M6.8. No cambian el contrato ni la política: cambian cómo se mide el
186
+ tiempo y qué se puede ver del scheduler.
187
+
188
+ ### 9.1 El presupuesto se mide con reloj monotónico
189
+
190
+ `automation.tickBudgetMs` se compara ahora contra `performance.now()` (reloj monotónico de
191
+ `node:perf_hooks`), no contra `Date.now()`. Motivo: un ajuste de hora (NTP, cambio de zona, suspensión
192
+ del equipo) podía alargar un tick sin límite —si el reloj retrocede, la condición de fin no se cumple— o
193
+ cortarlo antes de tiempo.
194
+
195
+ - El corte sigue ocurriendo **entre ficheros**, en dos puntos: antes de abrir el lote de pendientes y
196
+ dentro de `authorize`, que corre antes de preparar y escribir cada fichero. Nunca dentro de una
197
+ transacción.
198
+ - El reloj de pared se usa **solo** para marcas persistidas (`operation_steps`, `sync_state`, auditoría)
199
+ y para el campo informativo `ms`.
200
+ - `syncScope`/`syncScopes` aceptan `monotonic` como dependencia opcional para pruebas; el scheduler lo
201
+ propaga.
202
+
203
+ ### 9.2 El backoff se puede observar
204
+
205
+ `status()` expone ahora, además de lo anterior:
206
+
207
+ | Campo | Significado |
208
+ |---|---|
209
+ | `consecutiveFailures` | Fallos consecutivos del tick (no de un fichero) |
210
+ | `lastError` | Último error (`code`, mensaje), o `null` |
211
+ | `nextAttemptAt` | Instante del próximo intento tras un fallo, o `null` |
212
+ | `backoffFactor` | `min(2**(n-1), 8)`; `0` sin fallos |
213
+ | `backoffRemainingMs` | Milisegundos que faltan hasta `nextAttemptAt` |
214
+ | `skippedTicks` / `lastSkipReason` | Ticks omitidos y por qué (`already-running`, `backoff`, `disabled`) |
215
+ | `effective` | Política aplicada: intervalo, ficheros por pasada y presupuesto |
216
+
217
+ Fórmula: `nextAttemptAt = lastAttemptAt + intervalMs * min(2**(n-1), 8)`. El primer fallo ya espera ×2:
218
+ no hay reintento inmediato. Un fallo **de fichero** no es un fallo **de tick** y no activa backoff.
219
+
220
+ ### 9.3 Desactivar surte efecto inmediato
221
+
222
+ Si `automation.enabled` pasa a `false` durante un backoff, el siguiente tick lo detecta antes de
223
+ comprobar la espera, la cancela y resetea contador y `nextAttemptAt`. `stop()` hace lo mismo. No queda
224
+ una espera preparada para el siguiente arranque.
225
+
226
+ ### 9.4 Límites declarados
227
+
228
+ - El backoff y el corte por presupuesto están probados de forma determinista con reloj y temporizador
229
+ inyectados, pero **no** se han provocado en el host real: exigía romper la configuración del perfil o
230
+ un árbol artificial dentro de la raíz autorizada.
231
+ - El scheduler sigue siendo de una sola instancia por proceso; no hay lease entre host y CLI (ver
232
+ `RISK-REGISTER.md`, R-02).