fix: #92 clean 삭제 안전성 및 오탐 방지 강화

README.en.md

@@ -10,7 +10,7 @@ Destroy dead code ruthlessly.
 
 Kratos is a CLI tool for JavaScript and TypeScript projects. It finds unused files, broken imports, unused exports, and orphaned modules, then writes the results to a report. The current implementation combines a Rust core/CLI with an npm launcher, and the npm package `@jeremyfellaz/kratos` loads an optional platform-specific native add-on.
 
-Kratos is an analysis tool for a safe cleanup workflow, not an automatic deletion bot. `clean` is dry-run by default, and files are only removed after you review the report and explicitly pass `--apply`.
+Kratos is an analysis tool for a safe cleanup workflow, not an automatic deletion bot. `clean` is dry-run by default. After review, `--apply` moves verified files out of their code paths into retained storage under `<root>/.kratos/clean-quarantine/`; it does not physically unlink them automatically.
 
 ## Core Capabilities
 
@@ -39,7 +39,7 @@ npx @jeremyfellaz/kratos report ./my-app --format md
 npx @jeremyfellaz/kratos clean ./my-app --min-confidence 0.9
 ```
 
-Only add `--apply` after reviewing the report and deciding to delete the listed targets.
+Only add `--apply` after reviewing the report and deciding to quarantine the listed targets out of their code paths.
 
 ```bash
 npx @jeremyfellaz/kratos clean ./my-app --apply --min-confidence 0.9
@@ -87,10 +87,10 @@ Compares finding changes between two reports.
 
 ### `kratos clean [report-path-or-root] [--apply] [--min-confidence value]`
 
-Previews deletion candidates or deletes them.
+Previews deletion candidates or moves them out of their code paths into retained quarantine.
 
 - Dry-run is the default behavior.
-- Files are deleted only when `--apply` is present.
+- With `--apply`, files are retained under `<root>/.kratos/clean-quarantine/` instead of being physically unlinked.
 - `--min-confidence value` is a confidence threshold from `0.0` to `1.0`.
 - If `--min-confidence` is omitted, Kratos reads `thresholds.cleanMinConfidence` from `kratos.config.json`; when no setting exists, it uses `0.0`.
 
@@ -148,7 +148,7 @@ Deletion targets: 1
 Threshold-skipped targets: 1
 - <root>/src/lib/broken.ts (confidence 0.88, Module has no inbound references and is not treated as an entrypoint.)
 
-Re-run with --apply to delete these files.
+Re-run with --apply to move these files into retained quarantine.
 ```
 
 Comparing identical reports shows no introduced or resolved findings, only persisted counts.
@@ -171,11 +171,11 @@ Totals: introduced 0, resolved 0, persisted 9
 
 ## Report Schema
 
-`scan` currently writes `schemaVersion: 2` reports.
+`scan` currently writes `schemaVersion: 3` reports.
 
 ```json
 {
-  "schemaVersion": 2,
+  "schemaVersion": 3,
   "summary": {
     "filesScanned": 5,
     "entrypoints": 1,
@@ -185,11 +185,23 @@ Totals: introduced 0, resolved 0, persisted 9
     "unusedImports": 0,
     "routeEntrypoints": 1,
     "deletionCandidates": 2
+  },
+  "cleanSafety": {
+    "fingerprintAlgorithm": "sha256",
+    "candidates": [
+      {
+        "file": "<absolute-path>",
+        "fingerprint": "<sha256-or-null>",
+        "identity": "<stable-file-identity-or-null>",
+        "parentIdentity": "<stable-parent-identity-or-null>"
+      }
+    ]
   }
 }
 ```
 
 `findings` contains `brokenImports`, `orphanFiles`, `deadExports`, `unusedImports`, `routeEntrypoints`, and `deletionCandidates`. `graph.modules` records analyzed module paths, entrypoint status, and import/export counts.
+v2/legacy reports remain readable, but `clean --apply` fails closed because they do not contain `cleanSafety` evidence.
 
 ## Configuration
 

README.es.md

@@ -10,7 +10,7 @@ Elimina código muerto sin piedad.
 
 Kratos es una herramienta CLI para proyectos JavaScript y TypeScript. Encuentra archivos no usados, imports rotos, exports no usados y módulos huérfanos, y escribe los resultados en un reporte. La implementación actual combina un core/CLI en Rust con un launcher de npm, y el paquete npm `@jeremyfellaz/kratos` carga un addon nativo opcional específico de la plataforma.
 
-Kratos es una herramienta de análisis para un flujo de limpieza seguro, no un bot de eliminación automática. `clean` usa dry-run por defecto, y los archivos solo se eliminan después de revisar el reporte y pasar `--apply` explícitamente.
+Kratos es una herramienta de análisis para un flujo de limpieza seguro, no un bot de eliminación automática. `clean` usa dry-run por defecto. Tras revisar el reporte, `--apply` mueve los archivos verificados fuera de sus rutas de código y los conserva en `<root>/.kratos/clean-quarantine/`; no los elimina físicamente de forma automática.
 
 ## Capacidades Principales
 
@@ -35,7 +35,7 @@ npx @jeremyfellaz/kratos report ./my-app --format md
 npx @jeremyfellaz/kratos clean ./my-app --min-confidence 0.9
 ```
 
-Añade `--apply` solo después de revisar el reporte y decidir eliminar los objetivos listados.
+Añade `--apply` solo después de revisar el reporte y decidir poner en cuarentena los objetivos listados fuera de sus rutas de código.
 
 ```bash
 npx @jeremyfellaz/kratos clean ./my-app --apply --min-confidence 0.9
@@ -83,10 +83,10 @@ Compara los cambios de hallazgos entre dos reportes.
 
 ### `kratos clean [report-path-or-root] [--apply] [--min-confidence value]`
 
-Previsualiza candidatos de eliminación o los elimina.
+Previsualiza candidatos de eliminación o los mueve fuera de sus rutas de código a una cuarentena conservada.
 
 - El comportamiento por defecto es dry-run.
-- Los archivos solo se eliminan cuando `--apply` está presente.
+- Con `--apply`, los archivos se conservan en `<root>/.kratos/clean-quarantine/` en lugar de desvincularse físicamente.
 - `--min-confidence value` es un umbral de confianza de `0.0` a `1.0`.
 - Si omites `--min-confidence`, Kratos lee `thresholds.cleanMinConfidence` de `kratos.config.json`; si no existe esa configuración, usa `0.0`.
 
@@ -144,7 +144,7 @@ Deletion targets: 1
 Threshold-skipped targets: 1
 - <root>/src/lib/broken.ts (confidence 0.88, Module has no inbound references and is not treated as an entrypoint.)
 
-Re-run with --apply to delete these files.
+Re-run with --apply to move these files into retained quarantine.
 ```
 
 Comparar reportes idénticos no muestra hallazgos introducidos ni resueltos, solo conteos persistentes.
@@ -167,11 +167,11 @@ Totals: introduced 0, resolved 0, persisted 9
 
 ## Esquema Del Reporte
 
-Actualmente `scan` escribe reportes con `schemaVersion: 2`.
+Actualmente `scan` escribe reportes con `schemaVersion: 3`.
 
 ```json
 {
-  "schemaVersion": 2,
+  "schemaVersion": 3,
   "summary": {
     "filesScanned": 5,
     "entrypoints": 1,
@@ -181,11 +181,23 @@ Actualmente `scan` escribe reportes con `schemaVersion: 2`.
     "unusedImports": 0,
     "routeEntrypoints": 1,
     "deletionCandidates": 2
+  },
+  "cleanSafety": {
+    "fingerprintAlgorithm": "sha256",
+    "candidates": [
+      {
+        "file": "<absolute-path>",
+        "fingerprint": "<sha256-or-null>",
+        "identity": "<stable-file-identity-or-null>",
+        "parentIdentity": "<stable-parent-identity-or-null>"
+      }
+    ]
   }
 }
 ```
 
 `findings` contiene `brokenImports`, `orphanFiles`, `deadExports`, `unusedImports`, `routeEntrypoints` y `deletionCandidates`. `graph.modules` registra rutas de módulos analizados, estado de entrypoint y conteos de imports/exports.
+Los reportes v2/legacy siguen siendo legibles, pero `clean --apply` falla de forma cerrada porque no contienen evidencia `cleanSafety`.
 
 ## Configuración
 

README.ja.md

@@ -10,7 +10,7 @@
 
 Kratos は JavaScript/TypeScript プロジェクト向けの CLI ツールです。未使用ファイル、壊れた import、未使用 export、孤立したモジュールを検出し、結果を report に保存します。現在の実装は Rust core/CLI と npm launcher を組み合わせており、npm package `@jeremyfellaz/kratos` が platform ごとの optional native addon を読み込みます。
 
-Kratos は自動削除 bot ではなく、安全なクリーンアップ手順のための分析ツールです。`clean` はデフォルトで dry-run であり、report を確認したうえで `--apply` を明示した場合だけファイルを削除します。
+Kratos は自動削除 bot ではなく、安全なクリーンアップ手順のための分析ツールです。`clean` はデフォルトで dry-run です。report 確認後の `--apply` は、検証済みファイルを元のコードパスから `<root>/.kratos/clean-quarantine/` へ移動して保持し、自動で物理削除しません。
 
 ## 主な機能
 
@@ -35,7 +35,7 @@ npx @jeremyfellaz/kratos report ./my-app --format md
 npx @jeremyfellaz/kratos clean ./my-app --min-confidence 0.9
 ```
 
-リストされた対象を削除すると判断した後だけ `--apply` を追加してください。
+リストされた対象を元のコードパスから隔離すると判断した後だけ `--apply` を追加してください。
 
 ```bash
 npx @jeremyfellaz/kratos clean ./my-app --apply --min-confidence 0.9
@@ -83,10 +83,10 @@ npx @jeremyfellaz/kratos diff ./my-app/.kratos/before.json ./my-app/.kratos/afte
 
 ### `kratos clean [report-path-or-root] [--apply] [--min-confidence value]`
 
-削除候補を preview するか、実際に削除します。
+削除候補を preview するか、元のコードパスから保持型 quarantine へ移動します。
 
 - デフォルト動作は dry-run です。
-- `--apply` がある場合だけファイルを削除します。
+- `--apply` ではファイルを `<root>/.kratos/clean-quarantine/` に保持し、物理的な unlink は自動実行しません。
 - `--min-confidence value` は `0.0` から `1.0` までの信頼度しきい値です。
 - `--min-confidence` を省略すると、Kratos は `kratos.config.json` の `thresholds.cleanMinConfidence` を読みます。設定がなければ `0.0` を使います。
 
@@ -144,7 +144,7 @@ Deletion targets: 1
 Threshold-skipped targets: 1
 - <root>/src/lib/broken.ts (confidence 0.88, Module has no inbound references and is not treated as an entrypoint.)
 
-Re-run with --apply to delete these files.
+Re-run with --apply to move these files into retained quarantine.
 ```
 
 同一の report を比較すると、新規または解決済みの検出結果はなく、継続している件数だけが表示されます。
@@ -167,11 +167,11 @@ Totals: introduced 0, resolved 0, persisted 9
 
 ## レポートスキーマ
 
-現在の `scan` は `schemaVersion: 2` の report を書き込みます。
+現在の `scan` は `schemaVersion: 3` の report を書き込みます。
 
 ```json
 {
-  "schemaVersion": 2,
+  "schemaVersion": 3,
   "summary": {
     "filesScanned": 5,
     "entrypoints": 1,
@@ -181,11 +181,23 @@ Totals: introduced 0, resolved 0, persisted 9
     "unusedImports": 0,
     "routeEntrypoints": 1,
     "deletionCandidates": 2
+  },
+  "cleanSafety": {
+    "fingerprintAlgorithm": "sha256",
+    "candidates": [
+      {
+        "file": "<absolute-path>",
+        "fingerprint": "<sha256-or-null>",
+        "identity": "<stable-file-identity-or-null>",
+        "parentIdentity": "<stable-parent-identity-or-null>"
+      }
+    ]
   }
 }
 ```
 
 `findings` には `brokenImports`、`orphanFiles`、`deadExports`、`unusedImports`、`routeEntrypoints`、`deletionCandidates` が入ります。`graph.modules` には解析済みのモジュールパス、entrypoint 状態、import/export 件数が記録されます。
+v2/legacy report は引き続き読み込めますが、`cleanSafety` evidence がないため `clean --apply` は fail-closed になります。
 
 ## 設定